{"id":47708546,"url":"https://github.com/joneri/agile-iteration-method","last_synced_at":"2026-04-15T19:00:38.700Z","repository":{"id":335750832,"uuid":"1146917568","full_name":"joneri/agile-iteration-method","owner":"joneri","description":"Agile iteration method: a role-based workflow for using Codex as PO, TDO, Dev, Reviewer with gates and documentation rules.","archived":false,"fork":false,"pushed_at":"2026-04-13T19:59:24.000Z","size":504,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T21:33:59.189Z","etag":null,"topics":["agents","agile","ai","codex","llm","product-development","prompting","software-engineering","workflow"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joneri.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-31T22:19:53.000Z","updated_at":"2026-04-13T19:39:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/joneri/agile-iteration-method","commit_stats":null,"previous_names":["joneri/agile-iteration-method"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/joneri/agile-iteration-method","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joneri%2Fagile-iteration-method","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joneri%2Fagile-iteration-method/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joneri%2Fagile-iteration-method/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joneri%2Fagile-iteration-method/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joneri","download_url":"https://codeload.github.com/joneri/agile-iteration-method/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joneri%2Fagile-iteration-method/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31855432,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","agile","ai","codex","llm","product-development","prompting","software-engineering","workflow"],"created_at":"2026-04-02T18:09:02.714Z","updated_at":"2026-04-15T19:00:38.693Z","avatar_url":"https://github.com/joneri.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agile Iteration Method (AIM) v1.6\n\nAIM is a way to run agentic software delivery without losing the thread.\n\nIt gives AI work a clear Agile loop instead of a prompt spiral.\n\nOne loop:\n\n`PO -\u003e TDO -\u003e Dev -\u003e Reviewer -\u003e TDO -\u003e PO`\n\nThat means:\n- the Epic is owned by `PO`\n- the next single Done Increment is owned by `TDO`\n- implementation stays scoped\n- review happens before acceptance\n- the work is always judged as end-to-end user value, not random partial progress\n\nIf you want AI work to stay scoped and reviewable, that is the point.\n\n## Why AIM\n\nWithout a method, agentic development usually breaks in predictable ways:\n- the agent jumps between theories without proving anything\n- scope expands silently\n- \"progress\" becomes a pile of partial edits instead of a shippable slice\n- no one knows what the next approval actually means\n\nAIM fixes that with clear roles, gates and ownership.\n\n## What's new in v1.6\n\nAIM 1.6 keeps the accepted core loop and runtime model and makes AIM budget-aware.\n\n- Cost profiles are now explicit: `Standard`, `Cost Control`, and `Deep`\n- `Cost Control` keeps AIM gates and escalation rules while reducing context, output, and verification depth for low-risk work\n- `Standard` AIM now uses progressive context loading by default instead of rereading every method document\n- `Deep` is available for high-risk work where broader inspection and stronger review are worth the spend\n- `.aim/` is the official repo-local AIM workspace\n- `.aim/state.json` is the durable checkpoint for start, resume and gate tracking\n- small Done Increments are defined by behavioral scope, not by artificially few files\n- focused file boundaries are treated as part of product quality and future context efficiency\n- context hogs are treated as a real delivery problem, not as proof that scope stayed small\n- Codex, Copilot and Claude Code still share one conceptual runtime contract\n- the front door is lighter: start, continue, or validate first; read deeper only when needed\n\n## Why teams use it\n\nThis release is easier to trust, explain and adopt:\n- you can resume real work instead of re-explaining context every session\n- you can inspect runtime state instead of guessing what the agent thinks is happening\n- you can use Codex, Copilot and Claude Code with one shared conceptual model\n- you can use more focused files when that avoids context hogs and keeps boundaries cohesive\n- you can delegate bounded work without losing ownership of gates or acceptance\n- you can install AIM into a real repo without turning the repo into an experiment\n- the public docs make the latest version easier to start, inspect, and explain\n\n## What changed in 1.6\n\n- AIM 1.6 adds a cost-profile axis without changing the role loop or approval semantics.\n- `Strict` and `Auto` still control approvals; `Standard`, `Cost Control`, and `Deep` control runtime depth.\n- Regular AIM gets cheaper through progressive context loading, compact gates, cheap validation first, and risk-scaled review.\n- File-boundary discipline from AIM 1.5 remains part of the visible release story.\n\nIn practice, AIM 1.6 should spend attention where risk justifies it.\nLow-risk cleanup can run in Cost Control, while trust-sensitive product work can stay Standard or move to Deep.\n\n## From prompt pattern to runtime\n\nBefore AIM 1.3, the method was there but the runtime story was too loose.\n\nWith AIM 1.4, the runtime became inspectable and adapter-aware.\n\nWith AIM 1.6:\n- `.aim/` is the official repo-local AIM workspace\n- `.aim/state.json` is the durable checkpoint for start, resume and gate tracking\n- small scope is defined by behavior and user value, not by lowest possible file count\n- runtime depth is explicit through cost profiles\n- normal AIM loads context progressively instead of treating every run as a full reread\n- the public onboarding path makes the latest guidance obvious to new users\n- the front door starts with three simple choices instead of the full method\n- adapter guidance, packaging, and upgrade docs now read as one current release surface\n\nThat is the main upgrade: AIM 1.6 makes the accepted runtime easier to afford without weakening ownership, gates, or escalation.\n\n## Start Here\n\nChoose one:\n\n1. [Start AIM](docs/workflow/quick-start-aim-1.6.md)\n2. [Continue or troubleshoot AIM](docs/workflow/troubleshoot-aim-1.6.md)\n3. [Install or upgrade AIM](docs/workflow/install-aim-1.6.md)\n\nFast start:\n\n```text\n/aim start \"EPIC: \u003cdesired user outcome\u003e\"\nMode: Strict\nCost profile: Cost Control\n```\n\nUse `Cost Control` for ordinary low-risk work. Use `Deep` when the work touches trust, data correctness, deployment, migration, security, or public APIs.\n\nNeed the full map? Use [AIM 1.6 document map](docs/workflow/aim-1.6-doc-map.md).\n\n## Choose Your Adapter\n\n- Codex:\n  the repo is the AIM contract. The Codex skill adds the `/aim` launcher plus bootstrap help.\n- Copilot:\n  use the packaged `aim` agent in `.github/agents/` and add `.github/prompts/` when you want Copilot-style command helpers.\n- Claude Code:\n  use `CLAUDE.md` plus the shipped starter files in `.claude/commands/` and `.claude/agents/`.\n\nThis repo now ships a small Claude starter layer so Claude Code users can start from real files instead of abstract directory guidance.\n\nImportant installation rule:\n- `.github/agents/aim*.agent.md` are part of the AIM instruction layer, not just Copilot decoration.\n- `.github/prompts/` are optional Copilot prompt helpers.\n\n## Codex model\n\n- The repository is the canonical AIM contract.\n- The Codex skill is a bootstrap and convenience layer.\n- `/aim` is the normal Codex start path when the AIM skill is installed and enabled.\n- A fully AIM-aware repo can still be used in Codex without the skill if you start with explicit AIM intent in plain language.\n- 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.\n\n| Adapter | Canonical contract | Convenience layer | Normal start path | Required for best experience |\n| --- | --- | --- | --- | --- |\n| 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 |\n| 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 |\n| 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 |\n\n## Starting A New Repo With AIM v1.6\n\nUse this path when the repository does not exist yet or when you want to bootstrap a new repo around AIM from day one.\n\n### 1. Copy the AIM files into the new repo\n\nRequired for AIM:\n- `AGENTS.md`\n- `docs/workflow/agile-iteration-method.md`\n- `.github/agents/aim.agent.md`\n- `.github/agents/aim-planner.agent.md`\n- `.github/agents/aim-builder.agent.md`\n- `.github/agents/aim-reviewer.agent.md`\n\nRecommended:\n- `docs/workflow/quick-start-aim-1.6.md`\n- `docs/workflow/install-aim-1.6.md`\n- `docs/workflow/migrate-aim-1.5-to-1.6.md`\n- `docs/workflow/troubleshoot-aim-1.6.md`\n- `examples/epics/example-epic.md`\n\nOptional GitHub Copilot prompt files:\n- `.github/prompts/start-aim.prompt.md`\n- `.github/prompts/install-aim.prompt.md`\n- `.github/prompts/help-aim.prompt.md`\n- `.github/prompts/upgrade-aim-1.5-to-1.6.prompt.md`\n\nIf you want Claude Code support too, also copy:\n- `CLAUDE.md`\n- `.claude/agents/aim.md`\n- `.claude/commands/start-aim.md`\n- `.claude/commands/install-aim.md`\n- `.claude/commands/continue-aim.md`\n\nWhat each file is for:\n- `AGENTS.md` defines the canonical repo-aware AIM behavior.\n- `.github/agents/aim*.agent.md` are part of the AIM instruction layer and affect behavior in both Codex and Copilot.\n- in Copilot, those same files also act as native custom-agent files.\n- `.github/prompts/` are optional prompt-entry helpers, mainly useful for Copilot-style command flows.\n- Claude Code uses `CLAUDE.md` and `.claude/` as its adapter layer but does not replace `AGENTS.md`.\n\n### 2. Ignore live AIM runtime state\n\nAdd this to `.gitignore` if it is not already there:\n\n```gitignore\n/.aim\n```\n\n`.aim/` is runtime state, not release material. AIM creates it automatically on first valid start.\n\n### 3. Add your repository-specific rules to `AGENTS.md`\n\nBefore the first run, make sure your repo profile is real, not generic. At minimum, define:\n- stack and runtime assumptions\n- verification and testing strategy\n- deployment and migration constraints\n- role-specific constraints for `PO`, `TDO`, `Dev` and `Reviewer`\n\nThis is what makes AIM behave like your repo instead of a generic chatbot.\n\n### 4. Start your first Epic\n\nIn Codex:\n\n```text\n/aim start \"EPIC: \u003cdesired user outcome\u003e\"\nMode: Strict\nCost profile: Standard\n```\n\n`/aim` is the normal Codex start path when the AIM skill is installed and enabled.\nIf the repo already contains the AIM contract but the skill is not available, start with:\n\n```text\nEPIC: \u003cdesired user outcome\u003e\nMode: Strict\nCost profile: Cost Control\n```\n\nIn Copilot:\n\n```text\n/aim start \"EPIC: \u003cdesired user outcome\u003e\"\nMode: Strict\nCost profile: Standard\n```\n\nIn Claude Code:\n\n```text\nEPIC: \u003cdesired user outcome\u003e\nMode: Strict\nCost profile: Standard\n```\n\nThis repository also ships a small Claude starter layer:\n- `.claude/commands/start-aim.md`\n- `.claude/commands/install-aim.md`\n- `.claude/commands/continue-aim.md`\n- `.claude/agents/aim.md`\n\nIf Claude Code exposes repo command files directly in your environment, use the shipped start command. Otherwise use the explicit start prompt above.\n\nIf you want automatic continuation between increments, use `Mode: Auto` instead of `Mode: Strict`.\n\n## Installing AIM On An Existing Repo\n\nUse 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.\n\n### 1. Keep your product code. Add AIM around it.\n\nYou do not need to restructure the application first.\n\nAdd the core AIM files:\n- `AGENTS.md`\n- `docs/workflow/agile-iteration-method.md`\n- `.github/agents/aim.agent.md`\n- `.github/agents/aim-planner.agent.md`\n- `.github/agents/aim-builder.agent.md`\n- `.github/agents/aim-reviewer.agent.md`\n\nAdd optional Copilot prompt files if you want packaged Copilot entrypoints too:\n- `.github/prompts/`\n\nAdd Claude Code packaging too if needed:\n- `CLAUDE.md`\n- `.claude/agents/aim.md`\n- `.claude/commands/start-aim.md`\n- `.claude/commands/install-aim.md`\n- `.claude/commands/continue-aim.md`\n\nImportant:\n`.github/agents/aim*.agent.md` are not Copilot-only.\nIn AIM, they are part of the repository instruction layer and should be installed for proper AIM behavior in both Codex and Copilot.\n\n### 2. Make `AGENTS.md` repo-aware\n\nFor an existing repo, this is the most important step.\n\nUpdate `AGENTS.md` so it reflects reality:\n- what stack the repo uses\n- how verification should be done\n- what commands are safe\n- what must never be done without escalation\n- whether parallel or delegated work is allowed\n\nIf these rules stay vague, AIM will stay vague.\n\n### 3. Preserve your existing engineering standards\n\nAIM does not replace your tests, CI, review standards or release process.\n\nIt adds:\n- role discipline\n- increment discipline\n- runtime state and resume behavior\n- better approval semantics\n\n### 4. Start with a real Epic, not a task list\n\nBad start:\n\n```text\nFix file X, then maybe refactor Y, then add tests\n```\n\nGood start:\n\n```text\nEPIC: Make the onboarding flow understandable for first-time users without breaking existing signup behavior\nMode: Strict\nCost profile: Standard\n```\n\n`PO` owns the outcome. `TDO` owns the next single Done Increment.\n\n## The Fastest Way To Get Agentic Value\n\nIf someone wants the shortest path, this is it:\n\n1. Copy `AGENTS.md` and `docs/workflow/agile-iteration-method.md` into the target repo.\n2. Copy `.github/agents/aim*.agent.md` into the target repo.\n3. Add `/.aim` to `.gitignore`.\n4. Optionally copy `.github/prompts/` if you want packaged Copilot prompt entrypoints too.\n5. Optionally add `CLAUDE.md` and `.claude/` if you want Claude Code support too.\n6. Open the repo in Codex, Copilot or Claude Code.\n7. Start with `/aim start \"EPIC: \u003cdesired outcome\u003e\"`.\n8. If slash commands are unavailable, start with `EPIC: \u003cdesired outcome\u003e`, `Mode: Strict`, and `Cost profile: Cost Control`.\n\n## Why AIM Feels Different\n\nMost AI coding workflows chase speed of output.\n\nAIM aims for:\n- correctness you can explain\n- scope you can control\n- increments you can actually ship\n- approvals that mean something\n- runtime state you can inspect\n\nThat is why AIM works better on real software delivery than \"just ask the model again.\"\n\n## What AIM Creates At Runtime\n\nOn first valid start, AIM creates `.aim/` if it does not already exist.\n\nImportant runtime artifacts:\n- `.aim/epic.md`\n- `.aim/state.json`\n- `.aim/increments/`\n- `.aim/decisions/`\n- `.aim/reviews/`\n\nThe main AIM thread owns gate progression and `.aim/state.json`.\nSubagents, when allowed, must stay bounded and must not take over shared state or acceptance decisions.\n\n## What The User Experience Looks Like\n\nFor each Done Increment, AIM runs this sequence:\n\n1. `PO` frames the Epic\n2. `TDO` proposes the next single Done Increment\n3. `Dev` implements that increment\n4. `Reviewer` checks correctness, risk and readiness\n5. `TDO` presents the increment as a demo/test checkpoint\n6. `PO` decides whether the Epic continues or closes\n\nThe meaningful approval points are:\n- Gate A: Epic framing\n- Gate B: next Done Increment\n- Gate E: accept the increment or request adjustment\n\n## Strict vs Auto\n\n- `Mode: Strict`\n  Pauses at the meaningful hard gates.\n- `Mode: Auto`\n  Continues through increments automatically unless an escalation condition is hit.\n\nUse `Strict` by default for new teams or high-trust-sensitive work.\nUse `Auto` when the Epic is clear and you want faster throughput with the same gate logic.\n\n## Cost Profiles\n\nCost profile controls runtime depth, not approval flow.\n\n- `Cost profile: Standard`\n  Normal AIM, now cheaper through progressive context loading and compact gates.\n- `Cost profile: Cost Control`\n  Use for low-risk, reversible cleanup or narrow documentation and adapter maintenance. Gates and escalation rules still apply.\n- `Cost profile: Deep`\n  Use for trust-sensitive, data correctness, deployment, migration, security, public API, or broad method changes.\n\nCost Control is not weaker AIM. It is AIM with a smaller runtime budget and a clear rule to escalate when risk appears.\n\n## Platform Adapters\n\nAIM 1.6 explicitly separates:\n- AIM core\n- AIM runtime\n- repo-aware policy\n- platform adapters\n\nThat matters because Codex, Copilot and Claude Code do not always expose the same runtime capabilities.\n\nThe rule is simple:\n- same method where parity is possible\n- explicit fallback where parity is not possible\n- no silent redefinition of gates, ownership or acceptance\n\n### Instruction layering in practice\n\nAIM uses layered repository instructions:\n\n1. AIM base semantics\n2. repository `AGENTS.md`\n3. repository `.github/agents/aim*.agent.md`\n\nThis means `.github/agents/` files are part of AIM behavior in practice, not just optional Copilot decoration.\n\nIn Copilot, they also act as native custom-agent files.\nIn Codex, AIM reads and uses them as part of the repository instruction layer.\n\nClaude Code uses a separate adapter bridge:\n- `CLAUDE.md`\n- `.claude/agents/`\n- `.claude/commands/`\n\nThese files extend the Claude adapter surface but they do not replace `AGENTS.md` as the canonical AIM contract.\n\n## Recommended Reading Order\n\nIf you want to use AIM:\n1. [README.md](README.md)\n2. [Quick start AIM 1.6](docs/workflow/quick-start-aim-1.6.md) for the first run\n3. [Install AIM 1.6](docs/workflow/install-aim-1.6.md) when setup is missing\n4. [AIM 1.6 document map](docs/workflow/aim-1.6-doc-map.md) only when you need the broader path\n\nIf you want to upgrade an existing AIM repo:\n1. [Migrate AIM 1.5 to AIM 1.6](docs/workflow/migrate-aim-1.5-to-1.6.md)\n2. [Quick start AIM 1.6](docs/workflow/quick-start-aim-1.6.md)\n3. [Troubleshoot AIM 1.6](docs/workflow/troubleshoot-aim-1.6.md)\n\nIf you are implementing AIM itself:\n1. [AGENTS.md](AGENTS.md)\n2. [Agile iteration method](docs/workflow/agile-iteration-method.md)\n3. [AIM adapter guidance](docs/workflow/aim-adapter-guidance.md)\n\nDo not start with `AGENTS.md` when the goal is just to install or run AIM in a repository.\n\n## Repository Map\n\n- `AGENTS.md`\n  Canonical repository AIM contract across adapters.\n- `CLAUDE.md`\n  Claude Code bridge layer that maps AIM onto Claude Code without changing the shared runtime contract.\n- `docs/workflow/agile-iteration-method.md`\n  The method and runtime explanation.\n- `docs/workflow/quick-start-aim-1.6.md`\n  The shortest correct start path.\n- `docs/workflow/install-aim-1.6.md`\n  Minimum viable installation guidance.\n- `docs/workflow/aim-1.6-doc-map.md`\n  Route map for the public docs and the correct next read.\n- `docs/workflow/copilot-layer.md`\n  Optional GitHub Copilot packaging and workflow layer.\n- `docs/workflow/release-aim-1.6.md`\n  Release note and publish checklist for the current version.\n- `docs/workflow/migrate-aim-1.5-to-1.6.md`\n  Upgrade guidance for existing AIM repos.\n- `docs/workflow/troubleshoot-aim-1.6.md`\n  Startup, resume, validator and fallback troubleshooting.\n- `docs/workflow/example-aim-1.6-reference-run.md`\n  Concrete example of an AIM 1.6 run.\n- `examples/epics/example-epic.md`\n  Example Epic input.\n\n## Contributing\n\nUse AIM to improve AIM.\n\nSee `CONTRIBUTING.md` for consistency rules, scope rules and documentation expectations.\n\n## License\n\nDocumentation in this repository is licensed under [CC BY 4.0](LICENSE).\n\n## Credits\n\nCreated by Jonas Eriksson.\n\nContributors:\n- [@liamwears](https://github.com/liamwears)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoneri%2Fagile-iteration-method","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoneri%2Fagile-iteration-method","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoneri%2Fagile-iteration-method/lists"}