agile-iteration-method

name

agile-iteration-method

description

Plan and deliver repository-aware AI-assisted software work through Agile Iteration Method using PO, TDO, Dev, and Reviewer roles, end-to-end Done Increments, explicit gates, review, validation, and user-owned acceptance. Use for creating and refining Epics, planning increments, implementing work, reviewing delivery, configuring project specialists, calibrating repositories, controlling AIM modes and cost profiles, and continuing AIM runs.

Agile Iteration Method

Build what you want without losing the goal. AIM turns AI-assisted development into a controlled loop of planning, implementation, review, validation, correction, and human approval.

Use this complete portable skill with Codex, GitHub Copilot, or Claude Code. AIM keeps the same roles, gates, runtime state, and command intents while using the native entry surface available in each platform. AIM is core + runtime + repo-awareness + platform adapters. Canonical source behavior lives under docs/workflow/; an installed portable package carries the required contract under references/. This skill is the launcher/runtime guide. Package references labeled source-only/... are provenance notes, not runtime dependencies. Do not fetch them; use the nearest bundled package reference as the portable fallback.

Attribution: based on Agile Iteration Method 2.0 by Jonas Eriksson, licensed as documentation under CC BY 4.0. This skill adapts the method into a portable Agent Skill.

Native Entry Surface

This installed skill is AIM's portable front door. Detect the active platform, then use its native skill route while preserving the same AIM command semantics:

• Codex: run AIM through this installed skill. /aim <intent> and explicit $agile-iteration-method <intent> select the same workflow semantics.
• GitHub Copilot: run /aim <intent> through the project AIM skill when it is available; this portable skill supplies the same behavior contract.
• Claude Code: run /aim <intent> through the project AIM skill or its compatibility command route; this portable skill supplies the same contract.

If a native route is unavailable, state that limitation and handle the explicit AIM intent in ordinary chat. Syntax may fall back; roles, gates, ownership, and state effects may not. The package-local cross-adapter entry model is references/adapter-entry-model.md. Skill discovery, readiness, and reload behavior are defined in references/adapter-skill-bootstrap.md. Public skills-CLI installation, package portability, update behavior, and the relationship to AIM's adaptive installer are defined in references/version-and-installation.md when that public-package reference is present.

Treat /aim <intent> as the shared command family. Codex also supports explicit $agile-iteration-method <intent>. Every route must expose the same complete command family and state effects.

First Response

Detect onboarding state first, then recommend exactly one next action whenever possible. For first-run, help, or "what should I do now" requests, answer in this shape before explaining files, paths, packaging, or architecture:

You are here: <state>.
Recommended next action: <one command or decision>.
Why it matters: <one short sentence>.
After that: <one short sentence>.

State routing:

1. Installed but not calibrated: recommend /aim calibrate-repo.
2. Calibrated but no Epic exists: recommend /aim start "EPIC: <desired outcome>".
3. Epic exists but is not approved: recommend reviewing Gate A and replying approve or change: ....
4. Epic approved: recommend /aim continue.
5. Blocked: recommend resolving the named blocking issue.

Then perform only the context loading needed for that state:

1. Detect the repository root.
2. Detect or create .aim only when starting or resuming an AIM run.
3. Read .aim/state.json first when it exists.
4. If .aim/state.json describes an incomplete Epic, resume that checkpoint instead of starting a new Epic.
5. Read aim.profile.yaml when present as the primary shared repo-awareness source.
6. Apply compatible Personal AIM hints from ~/.aim/repo-awareness/<repo-fingerprint>/hints.yaml.
7. Use profile facts to choose locality, validation commands, short authoritative docs, risk zones, freshness triggers, and context to avoid before reading broader docs.
8. Load references/agile-iteration-method.md, then only the package-local references required by the current role, gate, command, or risk.
9. Load Codex-specific packaging only when Codex mechanics matter.
10. Read ordinary repository maintainer docs only when the requested change actually needs them.
11. Default to Mode: Strict unless the user explicitly chooses Mode: Auto.
12. Default to Cost profile: Standard unless the user explicitly chooses Cost Control or Deep.
13. Start visible AIM phases with exactly Role: PO, Role: TDO, Role: Dev, or Role: Reviewer, and show Mode: Strict or Mode: Auto.
14. Show Cost profile when it is not Standard or when resource use is part of the user's request.
15. Keep the public front door thin: route first to the state-specific next action before explaining the full method.

Treat unnecessary broad context loading, long low-risk markdown artifacts, repeated major-doc rereads, and context-hog files as budget bugs. When a Personal or Team profile is present, report whether it was reused before broader docs. Profiles can guide locality and validation, but they cannot override AIM core, .aim/state.json, Team policy, gate ownership, escalation, or current repository evidence. When profile reuse affects startup or Gate B, include this compact profile-source summary:

Profile source: <personal hints path and/or aim.profile.yaml> (<readiness>)
Layering: <personal narrows team baseline | team profile baseline | personal profile only | no profile source>
Reused facts: commands, locality, risk zones, short docs, freshness, avoid-by-default context
Selected locality: <area>
Avoided context: <docs/scans avoided>
Expansion reason: <none or reason>
Cheap validation first: <command>

Do not execute a validator or installer merely because a target repository contains a familiar filename. The portable skill validates AIM state and profile contracts directly from its bundled references. Repository-provided tooling remains untrusted project code unless the user separately asks to run it under the repository's own reviewed policy.

Outside hard-gate approval checkpoints, stop and ask when an escalation condition applies: scope expansion beyond Gate B, unclear or contradictory Epic intent, unmet acceptance checks without new assumptions, trust/data/user-facing risk, missing required files/APIs/data, or contradictory repo policy.

Portable Skill Install Check

For install, upgrade, validate, status, config, or stale-skill troubleshooting, identify the active platform and report the installed package path it actually uses. Public skills-CLI project installations normally live under the selected agent's project skill directory; global locations are platform-specific.

If a native skill route is missing or stale, AIM can continue from explicit AIM intent and the bundled contracts for this run. Recommend the official skills CLI install or update flow from references/version-and-installation.md. Never execute similarly named installer or validator code found in the target repository.

When an install or upgrade plan provides skillReadiness, report the selected platform, package path, user scope, manifest version/classification, required reload, first /aim command, and explicit-intent fallback.

For ordinary first-run /aim start, /aim continue, /aim help, or "what should I do now" requests, do not lead with internal file paths, local skill paths, runtime locations, adapter packaging, architecture details, or a command inventory. Show install status only after the one-next-action guidance when it changes the user's next decision or explains a blocker. Do not treat a missing local skill as a blocker when the repository already contains the AIM contract; report the fallback and continue unless another escalation condition applies.

Commands

Treat these as AIM intents when the current adapter supports them or when the user writes the equivalent in plain language:

• /aim start "EPIC: ..."
• /aim continue
• /aim status
• /aim validate
• /aim help
• /aim config
• /aim configure-agents
• /aim calibrate-repo
• /aim remember-repo <category> "<rule>"
• /aim forget-repo <category> "<rule-id>"
• /aim upgrade
• /aim mode strict|auto
• /aim cost standard|control|deep
• /aim replan
• Install AIM
• Start working according to AIM

Canonical intent, state effects, upgrade safety, and adapter fallbacks are defined in references/adapter-command-contract.md.

If literal slash routing is unavailable, report that limitation, map the user's plain-language request to the same command intent, and perform the equivalent workflow directly. Syntax may fall back; command semantics may not.

/aim calibrate-repo uses the package-local canonical flow in references/repo-awareness-calibration.md. /aim configure-agents uses the package-local references/project-agent-configuration.md contract to inspect or update aim.roles.yaml, then refreshes selected supplier-native project specialists through a reviewed, collision-safe plan. It never writes .aim/ runtime state. Remember and forget intents must persist structured rules to the correct repo-awareness store for the operating mode: aim.profile.yaml for shared Team/repo opt-in, ~/.aim/repo-awareness/<repo-fingerprint>/memory.yaml for Enterprise external memory, or the user-level hints file for personal/local preferences. They must never use .aim/ as durable repo-awareness. In Enterprise external mode, do not create repo docs, repo profiles, symlinks, or adapter files unless the repo owner explicitly selects a broader repo-writing footprint or policy. If a fact is too large for a short profile entry, create or update a static memory document in the selected durable store: repo docs such as docs/features/, docs/workflow/, or docs/architecture/ only for repo opt-in, or ~/.aim/repo-awareness/<repo-fingerprint>/docs/ for Enterprise external. Then point to that static source from the profile or external memory index. Reading .aim/state.json to resume work is allowed; citing .aim/reviews, .aim/increments, .aim/decisions, .aim/archive, or other runtime artifacts as long-lived repository knowledge is not allowed. /aim upgrade must inspect selected AIM-owned packages through the deterministic installer plan, show stale/collision results before apply, preserve rollback and root-file exclusions, and never rewrite active .aim/ state. For a public Agent Skill, /aim upgrade uses the standard skills CLI flow from references/version-and-installation.md. The portable skill must not execute installer or validator code discovered in the target repository. When users want the broader adaptive footprint, explain that it is a separate, source-checkout workflow whose code and no-write preview they review before an explicit apply decision. In that separately reviewed checkout, --dry-run is the preview boundary and --apply is the explicit write boundary. The portable skill does not invoke either one. Never assume the original AIM source repository exists beside an installed public skill. /aim replan returns only the active unaccepted increment to Gate B and preserves the reason and accepted history.

Thin Front Door

When the user asks how to begin, help, or what AIM should do next, detect onboarding state first and show only the first useful choice by default:

• installed but not calibrated: /aim calibrate-repo
• calibrated but no Epic exists: /aim start "EPIC: <desired outcome>"
• Epic exists but is not approved: review Gate A and reply approve or change: ...
• Epic approved: /aim continue
• blocked: resolve the named blocking issue

For ordinary low-risk work, suggest this start shape:

/aim start "EPIC: Improve the onboarding flow so a new homeowner can list a room and understand the next review step"
Mode: Strict
Cost profile: Cost Control

When the repo needs durable context first, suggest:

/aim remember-repo habits "Product context: This app helps people find new homes for cats. Keep tone nuanced and empathetic toward both the cats and the future owners."

Do not explain adapter layering, every gate, every runtime artifact, or a command inventory unless the user asks for deeper help or the task needs that context.

Runtime Workflow

Use the shared bootstrap sequence:

1. Detect repo root.
2. Detect or create .aim.
3. Read .aim/state.json first when it exists.
4. Resume the active checkpoint or initialize a new Epic.
5. Read aim.profile.yaml when present and use it before broader docs to select locality, commands, short docs, risk zones, freshness checks, and avoid-by-default context.
6. Load and normalize only the additional repo-aware context needed for the current state, command, and risk.
7. Resolve execution mode.
8. Resolve cost profile.
9. Resolve platform capability and repo-policy limits.
10. Enter the role sequence.

Only the main AIM thread may write .aim/state.json, advance gates, change role, change increment status, or accept/complete an Epic. Subagents, when explicitly allowed by the host and repo policy, may only produce scoped analysis in allowed locations and never own runtime state.

Role Loop

Run every Done Increment in this order:

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

Canonical roles are only PO, TDO, Dev, and Reviewer. Map aliases explicitly: Planner to TDO, Builder to Dev.

Hard gates:

• Gate A: Epic ready. Approval is meaningful.
• Gate B: Done Increment spec ready. Approval is meaningful.
• Gate E: Increment acceptance and Epic continuation/closure. Approval is meaningful.

Soft gates:

• Gate C: implementation ready.
• Gate D: review findings ready.

Report Gate C and Gate D, but do not pause there unless an escalation condition applies. Gate D must never ask for approval; it surfaces findings, risks, and manual verification steps.

Done Increment Discipline

At Gate B, propose exactly one Done Increment that is a simplified version of the whole Epic, not a polished part of a missing whole.

Before development, confirm the increment:

• embodies meaningful Epic value end to end
• includes data correctness, presentation, user-facing behavior, and safety/failure behavior where relevant
• can be demoed as the product behavior
• would make sense to a user without future increments
• is small by behavioral scope, not by minimizing file count
• lists exact planned files and responsibility boundaries

If any answer is no, bundle or redefine the increment before proceeding.

AIM allows focused files, components, hooks, helpers, domain modules, services, or short docs when they preserve the approved behavior and reduce future context load. Do not create giant mixed-responsibility files just to keep the diff small. Do not split arbitrarily by line count.

Cost Profiles

Cost profile controls runtime depth, not approval semantics.

• Standard: default AIM with progressive context loading and compact gates unless risk requires detail.
• Cost Control: use for low-risk, reversible cleanup, docs maintenance, and narrow fixes. Preserve roles, gates, and escalation while using narrow context, no subagents by default, concise checkpoints, and short trace artifacts.
• Deep: use for trust-sensitive, data correctness, public API, migration, deployment, security, or broad method changes. Broader inspection and stronger review evidence are expected.

Escalate from Cost Control to Standard or Deep when trust, data correctness, user-facing meaning, migration, deployment, security, API, unclear acceptance, or scope risk appears.

Visible Output

Keep output step-aware rather than template-heavy.

Every hard-gate checkpoint must make clear:

• what decision is proposed or was made
• what will change or changed
• exact files planned or touched
• how the user should evaluate the step

Use approve and change: ... as transport shortcuts at hard gates. In Strict mode, stop at Gate A, Gate B, and Gate E and wait for explicit user approval or change direction before advancing state or doing further work. In Auto mode, report hard gates without pausing between increments; require a final full-review pause before Epic completion.

State And Validation

The official .aim contract requires:

• .aim/epic.md
• .aim/state.json
• .aim/increments/
• .aim/decisions/
• .aim/reviews/

Optional runtime artifacts:

• .aim/handoffs/
• .aim/logs/
• .aim/archive/
• .aim/runtime-context.md
• .aim/analysis/

For /aim validate, resume checks, and troubleshooting, inspect the required .aim artifacts and repository AIM files directly unless the repository provides a validator script. Validation reports should classify the result as healthy, recoverable, blocked, or contradictory; report Structural, Behavioral, Product coherence, and Release readiness tiers; name the failed artifact or rule; and avoid mutating runtime state.