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. Examples here use Claude Code unless noted.

Lifecycle Overview

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 <name> or /aidlc --phase <name>. 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.
• To run one stage without moving your workflow, use /aidlc --stage <name> --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, still get those stage gates as real stops. See 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.
• 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.

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.
• 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, and plan approval. See 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 setting, or Guard Policy lowers that; only the machine-wide AIDLC_SKIP_HUMAN_PRESENCE_GUARD=1 does. 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 — scaffold the docs directory, 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.

Execution notes: - All three stages run inline inside aidlc-utility intent-create - no LLM subagent delegation, no per-stage prompt. - Workspace detection is a rule-based scanner (file extensions, known config filenames, package manifests). - No user interaction is needed during this phase.

Phase 1: Ideation

Purpose: Validate the initiative — capture intent, assess feasibility, define scope, form the team, and secure approval to proceed.

flowchart TD
    S11["1.1 Intent Capture & Framing\n(aidlc-product-agent)"]
    S12["1.2 Market Research\n(aidlc-product-agent)"]
    S13["1.3 Feasibility & Constraints\n(aidlc-architect-agent)"]
    S14["1.4 Scope Definition\n(aidlc-product-agent)"]
    S15["1.5 Team Formation\n(aidlc-delivery-agent)"]
    S16["1.6 Rough Mockups\n(aidlc-design-agent)"]
    S17["1.7 Approval & Handoff\n(aidlc-delivery-agent)"]
    VG1{{"Verification Gate:\nIdeation → Inception"}}

    S11 ==>|ALWAYS| S12
    S11 -.->|"skip: bugfix, refactor,\ninfra, security-patch"| S14
    S12 -.->|CONDITIONAL| S13
    S12 -.->|"skip if no\nfeasibility needed"| S14
    S13 -.->|CONDITIONAL| S14
    S14 ==>|ALWAYS| S15
    S14 -.->|"skip: poc,\nbugfix, refactor"| S17
    S15 -.->|CONDITIONAL| S16
    S15 -.->|"skip if no UI"| S17
    S16 -.->|CONDITIONAL| S17
    S17 ==>|ALWAYS| VG1

    style S11 fill:#c8e6c9,stroke:#388e3c,color:#000
    style S14 fill:#c8e6c9,stroke:#388e3c,color:#000
    style S17 fill:#c8e6c9,stroke:#388e3c,color:#000
    style S12 fill:#fff9c4,stroke:#f9a825,color:#000
    style S13 fill:#fff9c4,stroke:#f9a825,color:#000
    style S15 fill:#fff9c4,stroke:#f9a825,color:#000
    style S16 fill:#fff9c4,stroke:#f9a825,color:#000
    style VG1 fill:#ef9a9a,stroke:#c62828,color:#000

Stage colors: Green = ALWAYS (runs whenever the selected scope includes it). Yellow = CONDITIONAL (may skip based on scope, project type, or plan). For the exact per-scope stage membership, see the Stage-by-Scope Matrix.

Intent Capture records the initial description, workflow-selected scope, and used memory rules in its questions file. Claims in the intent statement and stakeholder map carry inline source tags; both artifacts surface assumptions and open questions. Retained assumptions require explicit confirmation before the Product Lead reviewer and approval gate run.

Phase 2: Inception

Purpose: Elaborate the requirements — analyze the codebase, elicit requirements, design architecture, decompose into units of work, and plan delivery.

flowchart TD
    S21{{"`**2.1 Reverse Engineering**<br/>    (aidlc-developer-agent + aidlc-architect-agent)<br/>    pipeline: 2-link`"}}
    S2P["2.2 Practices Discovery\n(aidlc-pipeline-deploy-agent)"]
    S22["2.3 Requirements Analysis\n(aidlc-product-agent)"]
    S23["2.4 User Stories\n(aidlc-product-agent)"]
    S24["2.5 Refined Mockups\n(aidlc-design-agent)"]
    S25["2.6 Domain Design\n(aidlc-architect-agent)"]
    S26["2.7 Units Generation\n(aidlc-architect-agent)"]
    S2C["2.8 Contract Design\n(aidlc-architect-agent)"]
    S27["2.9 Delivery Planning\n(aidlc-delivery-agent)"]
    VG2{{"Verification Gate:\nInception → Construction"}}

    BF_CHECK{"Brownfield?\n(from Initialization 0.3)"}
    BF_CHECK -->|Yes| S21
    BF_CHECK -->|No| S2P
    S21 -.->|CONDITIONAL| S2P
    S2P -.->|CONDITIONAL| S22

    subgraph RE_DETAIL["Two-Link RE Pipeline"]
        direction LR
        DEV_SCAN["Step 1: Developer\nCode Scan"]
        ARCH_SYNTH["Step 2: Architect\nSynthesis"]
        DEV_SCAN --> ARCH_SYNTH
    end

    S21 -.-> RE_DETAIL

    S22 ==>|ALWAYS| S23
    S22 -.->|"skip if no user-facing\nfeatures"| S25
    S23 -.->|CONDITIONAL| S24
    S23 -.->|"skip if no UI\nor mockups skipped"| S25
    S24 -.->|CONDITIONAL| S25
    S25 -.->|"if in scope"| S26
    S22 -.->|"if 2.6 skipped"| S26
    S26 -.->|CONDITIONAL| S2C
    S26 -.->|"if 2.8 skipped"| S27
    S2C ==>|ALWAYS| S27
    S27 ==>|ALWAYS| VG2

    style S21 fill:#bbdefb,stroke:#1565c0,color:#000
    style S2P fill:#fff9c4,stroke:#f9a825,color:#000
    style S22 fill:#c8e6c9,stroke:#388e3c,color:#000
    style S26 fill:#c8e6c9,stroke:#388e3c,color:#000
    style S27 fill:#c8e6c9,stroke:#388e3c,color:#000
    style S23 fill:#fff9c4,stroke:#f9a825,color:#000
    style S24 fill:#fff9c4,stroke:#f9a825,color:#000
    style S25 fill:#fff9c4,stroke:#f9a825,color:#000
    style S2C fill:#fff9c4,stroke:#f9a825,color:#000
    style VG2 fill:#ef9a9a,stroke:#c62828,color:#000
    style RE_DETAIL fill:#e8eaf6,stroke:#3f51b5,color:#000

Key behavior: Stage 2.1 runs as a pipeline (2-link chain) — first an aidlc-developer-agent code scan, then an aidlc-architect-agent synthesis that writes the artifacts. Each return creates an ordered durable receipt, and multi-repo work requires one complete chain per repo before approval. It only executes for brownfield projects. Stage 2.2 runs as a subagent hub-and-spoke for greenfield and brownfield work: the lead drafts, quality/developer/devsecops inspect it independently, the human interview resolves gaps, and the lead integrates. Stage 2.4 runs as a mob — the lead drafts, and the design, developer, and quality agents contribute in parallel via contribution files.

Phase 3: Construction

Purpose: Build the solution — design, implement, and test — in reviewable slices.

Why Construction works the way it does

New solo workflows that include Unit decomposition and a source-producing Construction stage default to unit-major, serial execution with verified Unit checkpoints. Each Unit completes its applicable design stages and Code Generation before the next. Runtime order follows unit-of-work-dependency.md; bolt-plan.md records delivery grouping and rationale without replacing that DAG.

With skeleton-on, the first DAG Unit is the smallest working integrated slice. Its code must run through a real end-to-end check, and you approve the verified skeleton before later Units begin. This happens even if you explicitly choose stage-major order. A first design-stage review alone is not a working skeleton.

The check is the intent's recorded, human-authorized Construction Verification Command, reused for every Unit/batch checkpoint. Delivery Planning proposes it from the project scan and records your Approve / Request Changes reply in the invoking SessionStart session. Only Approve authorizes the receipt before the command is set; an unrelated reply, Request Changes, or a reply from another session does not. You may defer if no runnable check exists yet; the first checkpoint then asks before verification. A missing authorization or later command change always requires the recorded-command flow, never a command chosen at verify time. The approval question shows Verified with <verification_command> (exit 0). The verifier records a tool-owned CHECKPOINT_VERIFICATION_RECORDED receipt alongside the proof file, and approval requires that receipt; a hand-written proof file cannot verify a Unit.

Before asking you to Approve or Request Changes at a Unit/skeleton checkpoint, the conductor opens the question with aidlc engine bolt checkpoint --action ask --unit "<unit>" --kind <unit|skeleton> --session "<session ID>". Your exact reply in that session, to this checkpoint question, authorizes only the matching action; an unrelated reply, another session's reply, or a reply to a different question does not. Approval/rejection uses the same --session and only the --user-input you actually chose. A changed checkpoint needs a new question and answer. Automatic approval (human_required: false) needs no ask and no --user-input; a human Request Changes always needs this flow.

The autonomy offer is Continue automatically / Review each checkpoint: for eligible checkpoint workflows, skeleton-off offers it at Construction entry, and skeleton-on offers it after the real skeleton checkpoint. An existing choice is not repeated; on-demand grant/revoke requests remain available. Plan Approval, enabled summary confirmation, verification command selection, and failures still need human attention under either choice. Summary confirmation applies only when directive.ceremony.summary_confirmation === "on".

The new default does not convert existing workflows, design-only work, or flows without Units. Their existing stage approvals remain. Team-owned Units keep their own per-stage or unit-end gate rhythm. Preserve explicit iteration choices.

Construction flow

This diagram shows the default path for an eligible solo workflow that produces source. Other workflows keep their recorded execution and approval policy.

flowchart TD
    START(["Begin eligible solo Unit workflow"])
    STANCE{"Skeleton-on?"}
    FIRST["First DAG Unit: applicable design and Code Generation<br/>Human Plan Approval and enabled summary confirmation"]
    INTEGRATED["Real integrated project check passes"]
    SKELETON{{"Human approval of verified skeleton"}}
    OFFER["When offered and no choice is recorded:<br/>Continue automatically / Review each checkpoint"]
    MORE{"Another Unit owed?"}
    UNIT["Next Unit: applicable design and Code Generation<br/>Human Plan Approval and enabled summary confirmation"]
    VERIFY["Verify the completed Unit"]
    CHECKPOINT{{"Ordinary Unit checkpoint<br/>Human if gated; automatic under an explicit grant"}}
    BOOK["Settle completion-only stage bookkeeping"]
    S36["3.6 Build and Test — once across the solution"]
    S37["3.7 CI Pipeline — once, if included"]
    VG3{{"Construction-to-Operation verification"}}
    START --> STANCE
    STANCE -->|Yes| FIRST --> INTEGRATED --> SKELETON --> OFFER
    STANCE -->|No| OFFER
    OFFER --> MORE
    MORE -->|Yes| UNIT --> VERIFY --> CHECKPOINT --> MORE
    MORE -->|No| BOOK --> S36
    S36 --> S37 --> VG3
    S36 -.->|CI skipped| VG3

Parallel Unit batches

Unit-major remains serial. To use swarm execution in an eligible checkpoint workflow, explicitly choose stage-major and Construction Execution: swarm. Execution and approval are separate choices: batch completion may be guided or automatic. Dependency-ready Units may run together; an inline Unit already approved at its checkpoint is not rebuilt in a later batch. Before initial protected prepare, the approved parent application source must be committed and reproducible. In particular, commit the approved inline skeleton source before preparing parallel Units. This is an explicit action; the tool never commits automatically and checks all Units before creating any child. See Swarm prepare.

For a human batch completion decision, the conductor first runs aidlc engine bolt swarm-checkpoint --action ask --batch <N> --units "<Units>" --session "<session ID>", then presents Approve / Request Changes and waits for your exact reply to that batch's question. The same session-bound consent rule applies: never use another question's reply or invent --user-input, and use the same --session for approval/rejection. Automatic batch approval needs no ask or --user-input.

flowchart LR
    READY["Explicit stage-major + swarm<br/>Eligible skeleton checkpoint already approved"]
    COMMIT["Approved application source committed<br/>Only with explicit authorization"]
    PLANS{{"Human Plan Approval for each named Unit<br/>Grouped presentation where supported"}}
    B["Build Unit B"]
    C["Build independent Unit C"]
    EVIDENCE["Current checks and review evidence for the batch"]
    BATCH{{"Batch checkpoint<br/>Human if gated; automatic under an explicit grant"}}
    NEXT["Continue to the next emitted work"]
    READY --> COMMIT --> PLANS
    PLANS --> B --> EVIDENCE
    PLANS --> C --> EVIDENCE
    EVIDENCE --> BATCH --> NEXT

Design stages can use an emitted per-Unit wave on a stage-major path. The conductor follows the emitted Unit set rather than deriving parallelism from a Bolt-plan grouping. BOLT_STARTED / BOLT_COMPLETED apply to the swarm/worktree path; serial inline Unit work uses its lifecycle and checkpoint receipts.

Halt-and-ask on failure

Failures always stop Construction, even in autonomous mode. The Build-and-Test loop-back's rung 4 also stops for the human; required Plan Approvals, summary confirmations, and verification command selection remain separate human decisions.

• If a solo Unit's Code Generation fails, Construction halts immediately and offers retry (re-run just that Unit), skip (mark it [S] and continue — dependents will likely also fail), or abort.
• If one Unit in a parallel batch fails while others succeed, the conductor waits for the whole batch to finish, preserves the successful Units' artifacts on disk, and presents the same retry / skip / abort choice for the failed Unit only.

Stage reference

Key behaviors:

• Eligible new source-producing solo Unit workflows default to unit-major and serial execution. Legacy, design-only, no-Unit, and team-owned workflows retain their existing paths.
• The real skeleton is the first complete integrated Unit, verified and human-approved before later Units; a legacy first-stage gate is only a stage review.
• Ordinary completion follows the recorded autonomy policy. completion_only stage directives settle existing approvals without repeating bodies, reviewers, or human completion questions.
• An autonomy answer does not choose swarm or change iteration order. Explicit stage-major/swarm selection supports guided or automatic batch checkpoints.
• Plan Approval remains mandatory for each Unit; grouping its presentation never removes individual approval receipts. Enabled summary confirmation, verification command selection, and failures still require the human.

Phase 4: Operation

Purpose: Deploy and operate — set up deployment pipelines, provision environments, configure observability, and establish feedback loops.

flowchart TD
    S41["4.1 Deployment Pipeline\n(aidlc-pipeline-deploy-agent)"]
    S42["4.2 Environment Provisioning\n(aidlc-aws-platform-agent)"]
    S43["4.3 Deployment Execution\n(aidlc-pipeline-deploy-agent)"]
    S44["4.4 Observability Setup\n(aidlc-operations-agent)"]
    S45["4.5 Incident Response\n(aidlc-operations-agent)"]
    S46["4.6 Performance Validation\n(aidlc-quality-agent)"]
    S47["4.7 Feedback & Optimization\n(aidlc-operations-agent)"]

    S41 -.->|CONDITIONAL| S42
    S42 -.->|CONDITIONAL| S43
    S43 -.->|CONDITIONAL| S44
    S44 -.->|CONDITIONAL| S45
    S45 -.->|CONDITIONAL| S46
    S46 -.->|CONDITIONAL| S47

    S47 -->|"Approve"| DONE(["Workflow Complete"])
    S47 -->|"Start New Cycle"| IDEATION(["Return to Ideation 1.1"])

    style S41 fill:#fce4ec,stroke:#c62828,color:#000
    style S42 fill:#fce4ec,stroke:#c62828,color:#000
    style S43 fill:#fce4ec,stroke:#c62828,color:#000
    style S44 fill:#fce4ec,stroke:#c62828,color:#000
    style S45 fill:#fce4ec,stroke:#c62828,color:#000
    style S46 fill:#fce4ec,stroke:#c62828,color:#000
    style S47 fill:#fce4ec,stroke:#c62828,color:#000
    style DONE fill:#a5d6a7,stroke:#2e7d32,color:#000
    style IDEATION fill:#e8f5e9,stroke:#4caf50,color:#000

Key behaviors: - All 7 stages are conditional — the entire phase may be skipped for mvp and poc scopes - Stage 4.7 is the terminal stage — on approval, the workflow is complete - The feedback loop from 4.7 back to 1.1 enables iterative development cycles

Phase Transitions and Verification Gates

At each phase boundary (Ideation → Inception, Inception → Construction, Construction → Operation), the framework runs phase boundary verification. This automated check validates:

• All required artifacts from the completing phase exist
• Traceability links between artifacts are intact (e.g., every requirement maps to a story)
• No orphaned artifacts or missing references
• Consistency between related artifacts

If verification fails, the conductor reports the issues and asks whether to proceed or go back to fix them.

Stage Execution Modes Reference

Across all 33 stages, the topology count is 29 inline / 2 subagent / 1 pipeline / 1 mob.

Next Steps

• Scopes, Depth, and Test Strategy — how scopes control which stages execute, including the full Stage-by-Scope Matrix
• Agents — the 14-agent roster and its domain, review, and composition roles
• Your First Workflow — annotated walkthrough
• Glossary — terminology reference