https://github.com/joneri/agile-iteration-method
Agile iteration method: a role-based workflow for using Codex as PO, TDO, Dev, Reviewer with gates and documentation rules.
https://github.com/joneri/agile-iteration-method
agents agile ai codex llm product-development prompting software-engineering workflow
Last synced: about 2 months ago
JSON representation
Agile iteration method: a role-based workflow for using Codex as PO, TDO, Dev, Reviewer with gates and documentation rules.
- Host: GitHub
- URL: https://github.com/joneri/agile-iteration-method
- Owner: joneri
- License: other
- Created: 2026-01-31T22:19:53.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-13T19:59:24.000Z (2 months ago)
- Last Synced: 2026-04-13T21:33:59.189Z (2 months ago)
- Topics: agents, agile, ai, codex, llm, product-development, prompting, software-engineering, workflow
- Size: 492 KB
- Stars: 7
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Agile Iteration Method (AIM) v1.6
AIM is a way to run agentic software delivery without losing the thread.
It gives AI work a clear Agile loop instead of a prompt spiral.
One loop:
`PO -> TDO -> Dev -> Reviewer -> TDO -> PO`
That means:
- the Epic is owned by `PO`
- the next single Done Increment is owned by `TDO`
- implementation stays scoped
- review happens before acceptance
- the work is always judged as end-to-end user value, not random partial progress
If you want AI work to stay scoped and reviewable, that is the point.
## Why AIM
Without a method, agentic development usually breaks in predictable ways:
- the agent jumps between theories without proving anything
- scope expands silently
- "progress" becomes a pile of partial edits instead of a shippable slice
- no one knows what the next approval actually means
AIM fixes that with clear roles, gates and ownership.
## What's new in v1.6
AIM 1.6 keeps the accepted core loop and runtime model and makes AIM budget-aware.
- Cost profiles are now explicit: `Standard`, `Cost Control`, and `Deep`
- `Cost Control` keeps AIM gates and escalation rules while reducing context, output, and verification depth for low-risk work
- `Standard` AIM now uses progressive context loading by default instead of rereading every method document
- `Deep` is available for high-risk work where broader inspection and stronger review are worth the spend
- `.aim/` is the official repo-local AIM workspace
- `.aim/state.json` is the durable checkpoint for start, resume and gate tracking
- small Done Increments are defined by behavioral scope, not by artificially few files
- focused file boundaries are treated as part of product quality and future context efficiency
- context hogs are treated as a real delivery problem, not as proof that scope stayed small
- Codex, Copilot and Claude Code still share one conceptual runtime contract
- the front door is lighter: start, continue, or validate first; read deeper only when needed
## Why teams use it
This release is easier to trust, explain and adopt:
- you can resume real work instead of re-explaining context every session
- you can inspect runtime state instead of guessing what the agent thinks is happening
- you can use Codex, Copilot and Claude Code with one shared conceptual model
- you can use more focused files when that avoids context hogs and keeps boundaries cohesive
- you can delegate bounded work without losing ownership of gates or acceptance
- you can install AIM into a real repo without turning the repo into an experiment
- the public docs make the latest version easier to start, inspect, and explain
## What changed in 1.6
- AIM 1.6 adds a cost-profile axis without changing the role loop or approval semantics.
- `Strict` and `Auto` still control approvals; `Standard`, `Cost Control`, and `Deep` control runtime depth.
- Regular AIM gets cheaper through progressive context loading, compact gates, cheap validation first, and risk-scaled review.
- File-boundary discipline from AIM 1.5 remains part of the visible release story.
In practice, AIM 1.6 should spend attention where risk justifies it.
Low-risk cleanup can run in Cost Control, while trust-sensitive product work can stay Standard or move to Deep.
## From prompt pattern to runtime
Before AIM 1.3, the method was there but the runtime story was too loose.
With AIM 1.4, the runtime became inspectable and adapter-aware.
With AIM 1.6:
- `.aim/` is the official repo-local AIM workspace
- `.aim/state.json` is the durable checkpoint for start, resume and gate tracking
- small scope is defined by behavior and user value, not by lowest possible file count
- runtime depth is explicit through cost profiles
- normal AIM loads context progressively instead of treating every run as a full reread
- the public onboarding path makes the latest guidance obvious to new users
- the front door starts with three simple choices instead of the full method
- adapter guidance, packaging, and upgrade docs now read as one current release surface
That is the main upgrade: AIM 1.6 makes the accepted runtime easier to afford without weakening ownership, gates, or escalation.
## Start Here
Choose one:
1. [Start AIM](docs/workflow/quick-start-aim-1.6.md)
2. [Continue or troubleshoot AIM](docs/workflow/troubleshoot-aim-1.6.md)
3. [Install or upgrade AIM](docs/workflow/install-aim-1.6.md)
Fast start:
```text
/aim start "EPIC: "
Mode: Strict
Cost profile: Cost Control
```
Use `Cost Control` for ordinary low-risk work. Use `Deep` when the work touches trust, data correctness, deployment, migration, security, or public APIs.
Need the full map? Use [AIM 1.6 document map](docs/workflow/aim-1.6-doc-map.md).
## Choose Your Adapter
- Codex:
the repo is the AIM contract. The Codex skill adds the `/aim` launcher plus bootstrap help.
- Copilot:
use the packaged `aim` agent in `.github/agents/` and add `.github/prompts/` when you want Copilot-style command helpers.
- Claude Code:
use `CLAUDE.md` plus the shipped starter files in `.claude/commands/` and `.claude/agents/`.
This repo now ships a small Claude starter layer so Claude Code users can start from real files instead of abstract directory guidance.
Important installation rule:
- `.github/agents/aim*.agent.md` are part of the AIM instruction layer, not just Copilot decoration.
- `.github/prompts/` are optional Copilot prompt helpers.
## Codex model
- The repository is the canonical AIM contract.
- The Codex skill is a bootstrap and convenience layer.
- `/aim` is the normal Codex start path when the AIM skill is installed and enabled.
- A fully AIM-aware repo can still be used in Codex without the skill if you start with explicit AIM intent in plain language.
- The skill is still useful in a prepared repo because it gives you the clean `/aim` entrypoint plus status, help, config, validate and upgrade helpers.
| Adapter | Canonical contract | Convenience layer | Normal start path | Required for best experience |
| --- | --- | --- | --- | --- |
| Codex | `AGENTS.md` + `docs/workflow/agile-iteration-method.md` + `.github/agents/aim*.agent.md` | Codex AIM skill | `/aim start "EPIC: ..."` | Skill enabled for `/aim`; repo alone can still work with explicit AIM intent |
| Copilot | `AGENTS.md` + `docs/workflow/agile-iteration-method.md` + `.github/agents/aim*.agent.md` | `.github/prompts/` | select `aim` and run `/aim start "EPIC: ..."` | `.github/agents/aim*.agent.md`; prompts optional |
| Claude Code | `AGENTS.md` + `docs/workflow/agile-iteration-method.md` + `.github/agents/aim*.agent.md` + `CLAUDE.md` | `.claude/commands/` and `.claude/agents/` | repo Claude command or explicit `EPIC: ...` | `CLAUDE.md`; `.claude/` helpers recommended |
## Starting A New Repo With AIM v1.6
Use this path when the repository does not exist yet or when you want to bootstrap a new repo around AIM from day one.
### 1. Copy the AIM files into the new repo
Required for AIM:
- `AGENTS.md`
- `docs/workflow/agile-iteration-method.md`
- `.github/agents/aim.agent.md`
- `.github/agents/aim-planner.agent.md`
- `.github/agents/aim-builder.agent.md`
- `.github/agents/aim-reviewer.agent.md`
Recommended:
- `docs/workflow/quick-start-aim-1.6.md`
- `docs/workflow/install-aim-1.6.md`
- `docs/workflow/migrate-aim-1.5-to-1.6.md`
- `docs/workflow/troubleshoot-aim-1.6.md`
- `examples/epics/example-epic.md`
Optional GitHub Copilot prompt files:
- `.github/prompts/start-aim.prompt.md`
- `.github/prompts/install-aim.prompt.md`
- `.github/prompts/help-aim.prompt.md`
- `.github/prompts/upgrade-aim-1.5-to-1.6.prompt.md`
If you want Claude Code support too, also copy:
- `CLAUDE.md`
- `.claude/agents/aim.md`
- `.claude/commands/start-aim.md`
- `.claude/commands/install-aim.md`
- `.claude/commands/continue-aim.md`
What each file is for:
- `AGENTS.md` defines the canonical repo-aware AIM behavior.
- `.github/agents/aim*.agent.md` are part of the AIM instruction layer and affect behavior in both Codex and Copilot.
- in Copilot, those same files also act as native custom-agent files.
- `.github/prompts/` are optional prompt-entry helpers, mainly useful for Copilot-style command flows.
- Claude Code uses `CLAUDE.md` and `.claude/` as its adapter layer but does not replace `AGENTS.md`.
### 2. Ignore live AIM runtime state
Add this to `.gitignore` if it is not already there:
```gitignore
/.aim
```
`.aim/` is runtime state, not release material. AIM creates it automatically on first valid start.
### 3. Add your repository-specific rules to `AGENTS.md`
Before the first run, make sure your repo profile is real, not generic. At minimum, define:
- stack and runtime assumptions
- verification and testing strategy
- deployment and migration constraints
- role-specific constraints for `PO`, `TDO`, `Dev` and `Reviewer`
This is what makes AIM behave like your repo instead of a generic chatbot.
### 4. Start your first Epic
In Codex:
```text
/aim start "EPIC: "
Mode: Strict
Cost profile: Standard
```
`/aim` is the normal Codex start path when the AIM skill is installed and enabled.
If the repo already contains the AIM contract but the skill is not available, start with:
```text
EPIC:
Mode: Strict
Cost profile: Cost Control
```
In Copilot:
```text
/aim start "EPIC: "
Mode: Strict
Cost profile: Standard
```
In Claude Code:
```text
EPIC:
Mode: Strict
Cost profile: Standard
```
This repository also ships a small Claude starter layer:
- `.claude/commands/start-aim.md`
- `.claude/commands/install-aim.md`
- `.claude/commands/continue-aim.md`
- `.claude/agents/aim.md`
If Claude Code exposes repo command files directly in your environment, use the shipped start command. Otherwise use the explicit start prompt above.
If you want automatic continuation between increments, use `Mode: Auto` instead of `Mode: Strict`.
## Installing AIM On An Existing Repo
Use this path when the product, codebase, tests and CI already exist and you want AIM to become the operating model on top of that repo.
### 1. Keep your product code. Add AIM around it.
You do not need to restructure the application first.
Add the core AIM files:
- `AGENTS.md`
- `docs/workflow/agile-iteration-method.md`
- `.github/agents/aim.agent.md`
- `.github/agents/aim-planner.agent.md`
- `.github/agents/aim-builder.agent.md`
- `.github/agents/aim-reviewer.agent.md`
Add optional Copilot prompt files if you want packaged Copilot entrypoints too:
- `.github/prompts/`
Add Claude Code packaging too if needed:
- `CLAUDE.md`
- `.claude/agents/aim.md`
- `.claude/commands/start-aim.md`
- `.claude/commands/install-aim.md`
- `.claude/commands/continue-aim.md`
Important:
`.github/agents/aim*.agent.md` are not Copilot-only.
In AIM, they are part of the repository instruction layer and should be installed for proper AIM behavior in both Codex and Copilot.
### 2. Make `AGENTS.md` repo-aware
For an existing repo, this is the most important step.
Update `AGENTS.md` so it reflects reality:
- what stack the repo uses
- how verification should be done
- what commands are safe
- what must never be done without escalation
- whether parallel or delegated work is allowed
If these rules stay vague, AIM will stay vague.
### 3. Preserve your existing engineering standards
AIM does not replace your tests, CI, review standards or release process.
It adds:
- role discipline
- increment discipline
- runtime state and resume behavior
- better approval semantics
### 4. Start with a real Epic, not a task list
Bad start:
```text
Fix file X, then maybe refactor Y, then add tests
```
Good start:
```text
EPIC: Make the onboarding flow understandable for first-time users without breaking existing signup behavior
Mode: Strict
Cost profile: Standard
```
`PO` owns the outcome. `TDO` owns the next single Done Increment.
## The Fastest Way To Get Agentic Value
If someone wants the shortest path, this is it:
1. Copy `AGENTS.md` and `docs/workflow/agile-iteration-method.md` into the target repo.
2. Copy `.github/agents/aim*.agent.md` into the target repo.
3. Add `/.aim` to `.gitignore`.
4. Optionally copy `.github/prompts/` if you want packaged Copilot prompt entrypoints too.
5. Optionally add `CLAUDE.md` and `.claude/` if you want Claude Code support too.
6. Open the repo in Codex, Copilot or Claude Code.
7. Start with `/aim start "EPIC: "`.
8. If slash commands are unavailable, start with `EPIC: `, `Mode: Strict`, and `Cost profile: Cost Control`.
## Why AIM Feels Different
Most AI coding workflows chase speed of output.
AIM aims for:
- correctness you can explain
- scope you can control
- increments you can actually ship
- approvals that mean something
- runtime state you can inspect
That is why AIM works better on real software delivery than "just ask the model again."
## What AIM Creates At Runtime
On first valid start, AIM creates `.aim/` if it does not already exist.
Important runtime artifacts:
- `.aim/epic.md`
- `.aim/state.json`
- `.aim/increments/`
- `.aim/decisions/`
- `.aim/reviews/`
The main AIM thread owns gate progression and `.aim/state.json`.
Subagents, when allowed, must stay bounded and must not take over shared state or acceptance decisions.
## What The User Experience Looks Like
For each Done Increment, AIM runs this sequence:
1. `PO` frames the Epic
2. `TDO` proposes the next single Done Increment
3. `Dev` implements that increment
4. `Reviewer` checks correctness, risk and readiness
5. `TDO` presents the increment as a demo/test checkpoint
6. `PO` decides whether the Epic continues or closes
The meaningful approval points are:
- Gate A: Epic framing
- Gate B: next Done Increment
- Gate E: accept the increment or request adjustment
## Strict vs Auto
- `Mode: Strict`
Pauses at the meaningful hard gates.
- `Mode: Auto`
Continues through increments automatically unless an escalation condition is hit.
Use `Strict` by default for new teams or high-trust-sensitive work.
Use `Auto` when the Epic is clear and you want faster throughput with the same gate logic.
## Cost Profiles
Cost profile controls runtime depth, not approval flow.
- `Cost profile: Standard`
Normal AIM, now cheaper through progressive context loading and compact gates.
- `Cost profile: Cost Control`
Use for low-risk, reversible cleanup or narrow documentation and adapter maintenance. Gates and escalation rules still apply.
- `Cost profile: Deep`
Use for trust-sensitive, data correctness, deployment, migration, security, public API, or broad method changes.
Cost Control is not weaker AIM. It is AIM with a smaller runtime budget and a clear rule to escalate when risk appears.
## Platform Adapters
AIM 1.6 explicitly separates:
- AIM core
- AIM runtime
- repo-aware policy
- platform adapters
That matters because Codex, Copilot and Claude Code do not always expose the same runtime capabilities.
The rule is simple:
- same method where parity is possible
- explicit fallback where parity is not possible
- no silent redefinition of gates, ownership or acceptance
### Instruction layering in practice
AIM uses layered repository instructions:
1. AIM base semantics
2. repository `AGENTS.md`
3. repository `.github/agents/aim*.agent.md`
This means `.github/agents/` files are part of AIM behavior in practice, not just optional Copilot decoration.
In Copilot, they also act as native custom-agent files.
In Codex, AIM reads and uses them as part of the repository instruction layer.
Claude Code uses a separate adapter bridge:
- `CLAUDE.md`
- `.claude/agents/`
- `.claude/commands/`
These files extend the Claude adapter surface but they do not replace `AGENTS.md` as the canonical AIM contract.
## Recommended Reading Order
If you want to use AIM:
1. [README.md](README.md)
2. [Quick start AIM 1.6](docs/workflow/quick-start-aim-1.6.md) for the first run
3. [Install AIM 1.6](docs/workflow/install-aim-1.6.md) when setup is missing
4. [AIM 1.6 document map](docs/workflow/aim-1.6-doc-map.md) only when you need the broader path
If you want to upgrade an existing AIM repo:
1. [Migrate AIM 1.5 to AIM 1.6](docs/workflow/migrate-aim-1.5-to-1.6.md)
2. [Quick start AIM 1.6](docs/workflow/quick-start-aim-1.6.md)
3. [Troubleshoot AIM 1.6](docs/workflow/troubleshoot-aim-1.6.md)
If you are implementing AIM itself:
1. [AGENTS.md](AGENTS.md)
2. [Agile iteration method](docs/workflow/agile-iteration-method.md)
3. [AIM adapter guidance](docs/workflow/aim-adapter-guidance.md)
Do not start with `AGENTS.md` when the goal is just to install or run AIM in a repository.
## Repository Map
- `AGENTS.md`
Canonical repository AIM contract across adapters.
- `CLAUDE.md`
Claude Code bridge layer that maps AIM onto Claude Code without changing the shared runtime contract.
- `docs/workflow/agile-iteration-method.md`
The method and runtime explanation.
- `docs/workflow/quick-start-aim-1.6.md`
The shortest correct start path.
- `docs/workflow/install-aim-1.6.md`
Minimum viable installation guidance.
- `docs/workflow/aim-1.6-doc-map.md`
Route map for the public docs and the correct next read.
- `docs/workflow/copilot-layer.md`
Optional GitHub Copilot packaging and workflow layer.
- `docs/workflow/release-aim-1.6.md`
Release note and publish checklist for the current version.
- `docs/workflow/migrate-aim-1.5-to-1.6.md`
Upgrade guidance for existing AIM repos.
- `docs/workflow/troubleshoot-aim-1.6.md`
Startup, resume, validator and fallback troubleshooting.
- `docs/workflow/example-aim-1.6-reference-run.md`
Concrete example of an AIM 1.6 run.
- `examples/epics/example-epic.md`
Example Epic input.
## Contributing
Use AIM to improve AIM.
See `CONTRIBUTING.md` for consistency rules, scope rules and documentation expectations.
## License
Documentation in this repository is licensed under [CC BY 4.0](LICENSE).
## Credits
Created by Jonas Eriksson.
Contributors:
- [@liamwears](https://github.com/liamwears)