Install AIM once. Stop re-explaining your project.

The problem is not context size

Large context windows help an agent read more. They do not decide what matters.

A repository may contain source code, old plans, half-finished branches, product notes and instructions written for another tool. A chat may contain ten good ideas and one approved direction. Loading more of it can make the model sound better informed while leaving the delivery question unanswered:

What are we trying to deliver, where does the work stand, and what should happen next?

Teams often patch that gap with a heroic prompt. They paste the product vision, architecture, conventions, current task and definition of done into every new session. The prompt grows. Details conflict. The human becomes the state manager.

AIM moves that responsibility into an inspectable repository workflow. Its public documentation describes the method as a loop with four roles and three hard human gates. The current release is v2.3.1; the stable runtime contract is still 2.0. Product version and state schema are tracked separately, which is a small detail with a useful consequence: a release can improve the operator experience without pretending that every repository checkpoint has changed.

The core loop is short:

PO -> TDO -> Dev -> Reviewer -> TDO -> PO

The Product Owner protects the outcome. The Technical Delivery Owner chooses one end-to-end Done Increment. Dev builds the approved behavior. Reviewer looks for mistakes and risk. TDO turns the evidence into a testable checkpoint. PO accepts the result or changes direction.

The AI does most of the motion. The human keeps the decisions that carry value, risk and public consequence.

Install the skill

You need Node.js and a repository. Run the installation from the repository root:

npx skills add joneri/agile-iteration-method \
  --skill agile-iteration-method

The skills CLI asks which installed agent hosts should receive AIM. If you know that this project will move between Codex, Claude Code and GitHub Copilot, make the targets explicit:

npx skills add joneri/agile-iteration-method \
  --skill agile-iteration-method \
  --agent codex \
  --agent claude-code \
  --agent github-copilot \
  --yes

That command installs the same portable workflow for three hosts. It does not make the hosts identical. Codex, Claude Code and Copilot keep their own tool permissions, interface features and specialist formats.

If the skill is already installed, update it:

npx skills update agile-iteration-method --yes

Restart the active agent if the skill does not appear. Skill discovery varies by host. The common part is SKILL.md, an open format built around a required name, description and Markdown instructions, with optional scripts, references and assets. The Agent Skills specification defines that portable base. OpenAI, Anthropic and GitHub each document support for filesystem-based skills.

This shared format is the first half of portability. Repository state is the other half.

Build the boring, excellent repository

Beginners are often shown an intimidating “perfect AI repo” containing a wall of instruction files. AIM needs far less.

After setup and calibration, the useful shape is:

your-project/
├── aim.profile.yaml       # verified repository knowledge
├── aim.roles.yaml         # project-specific role expertise
├── .aim/
│   ├── epic.md            # the approved outcome and boundaries
│   ├── state.json         # the current checkpoint
│   ├── increments/        # one end-to-end slice at a time
│   ├── decisions/         # gate decisions and reasons
│   └── reviews/           # independent findings and evidence
└── ...your actual project

You do not maintain these runtime files as a second backlog. AIM writes and reads them while it works. They remain visible so a human, another session or another compatible agent can inspect the same delivery position.

Three boundaries keep this tidy:

• aim.profile.yaml stores reusable facts about the repository: stack, commands, locality, short authoritative docs and risk zones.
• aim.roles.yaml describes what PO, TDO, Dev and Reviewer need to know in this project.
• .aim/ records the active run and its evidence. It is runtime history, not a dumping ground for permanent product documentation.

That separation matters. A test command can remain true for months. An active increment may change tomorrow. Mixing both into one enormous instruction file forces every new agent to sort durable facts from expired plans.

Calibrate before you ask for work

Run:

/aim calibrate-repo

Calibration inspects cheap evidence first: package metadata, known commands, the repository tree and short maintained documents. It creates or refreshes a reviewable profile. It is not permission to edit code.

A useful profile might learn:

commands:
  install: npm install
  cheapValidation: npm run lint
  tests: npm test
  build: npm run build

localities:
  checkout: src/checkout
  payments: src/payments

riskZones:
  - payment state transitions
  - retry idempotency

The next session can begin near src/checkout, run lint before the expensive build and avoid opening a 300-page architecture export that has nothing to do with the change. Repo awareness saves context by selecting evidence, not by memorising every file.

Inspect the proposed profile. Correct bad commands now. An incorrect reusable fact is worse than a missing one because it fails with confidence.

Configure the four specialists

The portable skill can run sequentially in one conversation. A repository can also define native project specialists for each supported host:

/aim configure-agents

AIM reads aim.roles.yaml, presents a collision-safe plan and refreshes the selected host's specialist files. The roles keep the same authority everywhere:

• PO owns the Epic and acceptance.
• TDO owns the Done Increment and delivery evidence.
• Dev owns implementation inside approved scope.
• Reviewer owns independent findings, never acceptance.

This is more than assigning four personalities. Each role has a different write boundary. A reviewer should not quietly repair its own finding and mark the work accepted. A developer should not widen the Epic because a nearby refactor looks attractive. One main AIM thread owns .aim/state.json and gate transitions.

If a host cannot run native specialists, AIM falls back to the same role order in one thread. The interface gets simpler; ownership does not change.

Start with an outcome

Avoid this:

Create RetryButton.tsx, add a hook, update the API and write three tests.

Those may become implementation tasks, but they smuggle in a design before the problem is agreed.

Start with the result a user should experience:

/aim start "EPIC: When a profile form fails to save, preserve the user's work,
explain what happened and provide a safe retry path"

For a first project, choose Strict mode and Cost Control unless the work touches security, money, migration, public APIs or other trust-sensitive behavior:

/aim mode strict
/aim cost control

Strict pauses at Gate A, Gate B and Gate E. Cost Control reduces context and narration, not review or human ownership. AIM can escalate the cost profile when the risk requires deeper evidence.

Gate A: approve the destination

PO turns your sentence into an Epic with a goal, non-goals, acceptance criteria and rollback notes. A good Gate A proposal for the form example might say:

Goal: A failed save never destroys typed profile data. The user sees a clear
reason and can retry once the failure is resolved.

Non-goals: Redesigning the entire profile page, changing authentication or
adding offline synchronization.

Acceptance: Typed values remain visible after a simulated server failure; the
error is accessible; retry sends one new request; success clears the error.

Read this as a product contract. Ask whether a user would notice the outcome and whether the boundaries exclude tempting side quests.

Then answer:

approve

or:

change: keep automatic retries out of scope; require the user to choose retry

No implementation should begin before this decision. Speed gained before direction is approved usually returns as rework.

Gate B: approve one complete slice

TDO now proposes one Done Increment. AIM uses the skateboard test: can a user ride it, or did the team merely polish a pedal for a vehicle that does not exist?

A weak increment would be “create the retry button component.” The button has no value without preserved form state, a failure response and a working second attempt.

A real first increment is:

Simulate one save failure end to end, keep every typed field intact, show an accessible error, let the user retry manually and verify that the next successful response completes the save.

That slice crosses presentation, state, API behavior, failure handling and tests. It is small because it covers one behavior. It may touch several focused files.

At Gate B, check five things:

1. A user can experience the whole behavior. 2. The increment makes sense without promised future work. 3. Failure and safety behavior are included. 4. Exact planned files and responsibilities are listed. 5. The demo can prove success or failure.

Approve it:

approve

Dev may now build. Gate C reports implementation readiness. Reviewer checks the exact approved diff at Gate D. Neither soft gate asks you to perform a ceremonial approval.

Change tools in the middle of the loop

Here is the part that changes the feel of AI-assisted work.

Imagine that Codex framed the Epic and TDO prepared the increment. You approved Gate B, but you want to continue implementation in Claude Code. Close Codex. Open Claude Code in the same repository and run:

/aim continue

Claude Code reads .aim/state.json first. It can see the active Epic, approved increment, current role, mode and last gate. It reads aim.profile.yaml to find the relevant code and validation commands. It loads the AIM skill for the role contract. You do not need to reconstruct the project in prose.

After Dev completes the work, you can open the repository in GitHub Copilot and run the same intent:

/aim continue

Copilot resumes from the durable checkpoint and enters review or TDO validation according to the recorded state.

Literal command routing can differ. If one host does not expose /aim as a native slash command, write the same intent in ordinary language:

Continue the active AIM Epic from its current checkpoint.

The syntax may fall back. The role order, gate ownership and state effects must stay the same.

This works under clear conditions:

• AIM is installed for the next host.
• The next host opens the same working copy, or a synchronized copy containing the relevant .aim and profile files.
• Repository policy allows those files to travel through the chosen branch or shared filesystem.
• Secrets remain outside .aim.

AIM cannot carry an uncommitted file to another laptop through force of will. It can make the delivery checkpoint portable once the files are available.

Gate E: accept evidence, not confidence

After Reviewer reports findings, TDO presents the increment as a demo:

• what changed;
• what commands passed;
• what the reviewer found;
• what was corrected;
• how you can reproduce the behavior;
• which risk or manual check remains.

Run the form example. Type into every field, force the first request to fail, confirm that the values remain, trigger retry and watch the second request succeed exactly once.

Then accept or change the increment:

approve

change: the error is not announced by the screen reader; correct that before acceptance

Gate E is where human ownership becomes concrete. A green test suite is evidence. It is not the business decision that the behavior is valuable, understandable and ready.

If the Epic still needs more behavior, PO continues and TDO proposes the next Done Increment. If the acceptance criteria are fulfilled, PO asks you to close the Epic. Final acceptance remains yours even in Auto mode.

Reflect after delivery

Completed work contains useful lessons. It also contains temporary hacks, expired assumptions and conclusions that happened to fit one branch.

Run:

/aim reflect

Reflect reads completed AIM evidence, checks material lessons against current repository sources and writes a temporary candidate report under .aim/analysis/. Each candidate keeps its provenance, confidence, contradictions and proposed destination.

Suppose three increments discovered that profile tests need a fake clock before retry assertions are reliable. Reflect may propose a repository rule. It does not silently add the rule. You review the evidence and choose whether to promote it:

/aim remember-repo testing "Retry tests use the shared fake clock before asserting backoff or request count."

If a remembered rule has become false, Reflect can recommend a targeted /aim forget-repo action. If nothing deserves to persist, it should say so.

This follows an old agile discipline. The Agile Manifesto's principles call for teams to reflect regularly and adjust their behavior. AIM connects that retrospective to current repository evidence. History gets a hearing, not automatic authority.

How AIM compares

No single method wins every job. The useful comparison is the job each approach is designed to do.

AIM's advantage comes from composition. An Epic without an increment can stay grand and vague. An increment without review can be persuasively wrong. Review without an acceptance owner can turn green checks into accidental product decisions. Memory without current verification can preserve yesterday's bug as tomorrow's rule.

AIM connects those pieces in one inspectable chain.

That costs more ceremony than a quick prompt. Use the ceremony where failure, drift or handoff costs more than the gates.

When AIM is the wrong tool

Skip a full Epic when you want an explanation of a function, a throwaway code sample or a five-minute experiment. Ask the agent directly.

Use a narrow skill or standing instruction when the job is a repeatable procedure with no product decision, such as formatting release notes.

Use a deterministic script when inputs, outputs and checks are fully defined.

AIM earns its place when several of these are true:

• the work spans sessions;
• more than one person or AI tool may continue it;
• partial success can look convincing;
• review needs independence;
• repository knowledge should be reused carefully;
• a human must own scope or acceptance;
• the cost of retelling the project is already visible.

The method should remove confusion, not become a shrine to process. Choose Cost Control for low-risk work. Keep increments behaviorally small. Let profiles prevent broad rereads. If an AIM artifact grows until nobody can inspect it, that is a method defect worth fixing.

Your first hour with AIM

Use this sequence:

1. Install AIM for the agent hosts you use.
2. Open the repository root.
3. Run /aim calibrate-repo.
4. Review the proposed repository profile.
5. Run /aim configure-agents if you want native project specialists.
6. Run /aim start "EPIC: <one user-visible outcome>".
7. Approve or change Gate A.
8. Approve or change one end-to-end Done Increment at Gate B.
9. Let Dev, Reviewer and TDO produce evidence.
10. Test and accept at Gate E.
11. Run /aim reflect after completed work has lessons worth examining.

Use /aim status when you want the checkpoint:

/aim status

Use /aim help when you do not know the next move:

/aim help

Use /aim continue when you return tomorrow, in another session or in another supported tool:

/aim continue

The final command is the one that makes the whole system feel calm. You no longer begin with a performance of remembering. You begin from a recorded decision.

Fast agents are common. Continuity is rarer. AIM gives speed a destination, review a place in the loop and the human a decision point that cannot be quietly optimized away.

That is the repository you want: one that can tell the next capable agent where the work stands before you have to.

*Disclosure: Jonas Eriksson created Agile Iteration Method. AIM documentation used and adapted in this guide is licensed under CC BY 4.0.*