# Phases and Stages The AI-DLC lifecycle is organized into 5 phases containing 33 stages. This chapter explains each phase, lists its stages, and shows how they connect. > **Harness note.** The methodology — the phases, stages, agents, and gates this > guide describes — is identical on every harness. Where a mechanic differs by > harness (how a gate renders, how a subagent is dispatched, where config lives), > the difference is called out and tabled in your harness's chapter: > [Running on other harnesses](harnesses/README.md). Examples here use Claude Code > unless noted. --- ## Lifecycle Overview ```mermaid graph LR subgraph INITIALIZATION["INITIALIZATION (0.1-0.3)"] Z1["Workspace Scaffold"] Z4["State Init"] Z1 -.->|"3 stages"| Z4 end subgraph IDEATION["IDEATION (1.1-1.7)"] I1["Intent Capture"] I7["Approval & Handoff"] I1 -.->|"7 stages"| I7 end subgraph INCEPTION["INCEPTION (2.1-2.9)"] N1["Reverse Engineering"] N7["Delivery Planning"] N1 -.->|"9 stages"| N7 end subgraph CONSTRUCTION["CONSTRUCTION (3.1-3.7)"] C1["Functional Design"] C7["CI Pipeline"] C1 -.->|"3.1–3.5 per Unit in the recorded order; 3.6–3.7 once after all Units"| C7 end subgraph OPERATION["OPERATION (4.1-4.7)"] O1["Deployment Pipeline"] O7["Feedback & Optimization"] O1 -.->|"7 stages"| O7 end Z4 -->|"auto-proceed"| I1 I7 -->|"Verification Gate 1"| N1 N7 -->|"Verification Gate 2"| C1 C7 -->|"Verification Gate 3"| O1 O7 -.->|"Feedback Loop"| I1 style INITIALIZATION fill:#f3e5f5,stroke:#9c27b0,color:#000 style IDEATION fill:#e8f5e9,stroke:#4caf50,color:#000 style INCEPTION fill:#e3f2fd,stroke:#2196f3,color:#000 style CONSTRUCTION fill:#fff3e0,stroke:#ff9800,color:#000 style OPERATION fill:#fce4ec,stroke:#e91e63,color:#000 ``` Phases execute sequentially. At each phase boundary (except Initialization → Ideation), a **verification gate** runs automated traceability checks to catch missing links, orphaned artifacts, or inconsistencies before downstream stages build on them. ### What runs in order, and what runs in parallel **Stages run one at a time, in order.** When a stage completes, the engine moves to the next stage in lifecycle order that your scope runs and that is not already done or skipped (Construction repeats its stages per Unit, as described below). Within one workflow, a later phase does not start while a stage in an earlier phase is still open. - To move ahead anyway, jump: `/aidlc --stage ` or `/aidlc --phase `. The stages you pass over are marked skipped (`[S]`); they are not run later on their own. Jumping back to an earlier stage reopens it and every later stage in your plan. The files stay; a reopened stage that finds its earlier files asks whether to keep them, modify them, or redo the stage from scratch. See [Skipping and Navigating Stages](07-interaction-modes.md#skipping-and-navigating-stages). - To run one stage without moving your workflow, use `/aidlc --stage --single`. It writes that stage's artifact and stops with no workflow gate; your workflow stays where it was. **Construction repeats its stages for each Unit**, in one of two walks: - **Unit-major** (the default for new solo work that has Units and produces source): one Unit goes through its design stages and Code Generation, then the next Unit starts again at the first design stage. You approve each Unit at a verified Unit checkpoint; the stage gates that follow the last Unit are recorded as bookkeeping. Workflows without Unit checkpoints, such as older ones, get one question for those stage approvals instead: one Approve approves them all, and a change request approves none of them. A change for one Unit's stage ("in beta's NFR design, retry failed calls through a queue") redoes that stage and the ones after it for that Unit only, from your words; the other Units are asked nothing, and the one question comes back once. See [Why Construction works the way it does](#why-construction-works-the-way-it-does). - **Stage-major**: every Unit goes through one stage before the next stage starts, and that stage's gate comes once, after the last Unit. With a walking skeleton on, the first Unit still goes through every stage, including Code Generation, before the other Units start. **What can run in parallel**, within a stage or across Units in Construction: - **Units in Construction.** On a stage-major walk with `Construction Execution: swarm`, Units whose dependencies are done build together in one batch, then share one batch checkpoint. Unit-major stays serial. See [Parallel Unit batches](#parallel-unit-batches). - **Per-Unit design passes.** On a stage-major walk, the design stages can hand you a wave of Units that do not depend on each other. - **People, in team mode.** With `Unit Ownership: team`, each person claims a Unit and builds it in their own checkout at the same time as the others. Each checkout keeps its own place, so two people can be at different Construction stages at once. A claim is refused until that Unit's dependencies, and any required walking skeleton, are complete. - **Agents within a stage.** User Stories (2.4) is a mob: the design, developer, and quality agents contribute at the same time. Practices Discovery (2.2) has its inspectors look at the draft independently. Agents and design waves run at the same time where the harness can dispatch in parallel; on a harness that cannot, they run one after another with the same briefs. See [Stage Execution Modes Reference](#stage-execution-modes-reference). **Which stops you always get, and what settings change.** - Every stage your scope runs, outside Initialization, ends with an approval gate. Your scope decides which stages run; a stage it skips has no gate. In Construction, the walk above decides whether you approve per Unit or per stage. In team mode, the gate rhythm you choose when claiming (`per-stage` or `unit-end`) sets the review points instead. See [Multi-Team Construction](workshop-mode.md). - In Construction, choosing **Continue automatically** waives the ordinary completion checkpoints. You still get Plan Approval (unless plan approval is off for the work), an enabled summary confirmation, the verification command choice, skeleton approval, and every failure. - The ceremony switches remove only what they name: sensors, learnings, the summary confirmation, plan approval, and collaborators (the support agents a stage brings in). See [Ceremony Switches](13-customization.md#ceremony-switches). Guard Policy changes how hard the guards hold, not which gates you see. - A gate that is put to you needs a real message from you to approve it. Nothing in a scope, a per-work setting, or Guard Policy lowers that; only `AIDLC_SKIP_HUMAN_PRESENCE_GUARD=1` does, set machine-wide or recorded with `aidlc config flags --bypass`, and AI-DLC tells you while it is off. Checkpoints you chose to let run automatically are recorded without asking you. **How later stages depend on earlier ones.** Each stage declares the artifacts it reads (`consumes`) and writes (`produces`). The engine hands a stage the paths it needs. When a required input is missing, the stage is told whether that is expected (the stage that makes it is not in your scope) or a real gap (for example a stage you skipped with a jump). An expected gap means the stage works from what exists instead of inventing the file. A real gap is raised with you, so you can run the stage that makes the file or put the file in place yourself. The verification gate at each phase boundary checks that the links between phases hold. --- ## Phase 0: Initialization **Purpose:** Bootstrap the workspace: create the intent's record dir, detect the workspace, and initialize state. The welcome message is shown at session start via the `companyAnnouncements` entry in `settings.json` (not a stage). Initialization stages run **automatically** without approval gates. All three execute inside a single deterministic tool call (`aidlc-utility intent-create`) that completes in well under a second. | # | Stage | Lead | Key Artifacts | Condition | |---|-------|------|---------------|-----------| | 0.1 | Workspace Scaffold | orchestrator | first intent's record dir (`aidlc/spaces//intents/-