Orchestrator

Orchestration is split across two pieces. A deterministic engine (aidlc-orchestrate.ts, with exactly six subcommands: next, continue, report, park, team-board, and wait; continue is internal steering transport and team-board is the read-only Team Construction query, and wait is the bounded read-only wait for dispatched work) owns every between-stage decision - scope determination, stage routing, jump resolution, resume and init guards, gate status, and workflow completion - and emits a typed directive on each next. The conductor (.claude/skills/aidlc/SKILL.md, invoked via /aidlc) is a thin forwarding loop that acts on each directive - running the named stage, asking the human a question, fanning out a swarm - and reports stage-work outcomes with report. Engine ask answers instead follow their typed next, command, claim, or execute-remedy route; only the prompt-rendered resume menu uses a non-stage report. SKILL.md is not the control plane: the routing decisions live in the engine and the compiled data it reads (tools/data/stage-graph.json, tools/data/scope-grid.json), while SKILL.md owns execution quality inside the move the engine names.

This chapter documents the workflow behaviour from the conductor's side — entry points, session management, scope-to-stage mapping, the stage execution and advancement protocol, and the deliberate deviations. For the engine internals — the next/report contract, the typed directive union, the conductor persona, plural skills, scope shape, and the swarm referee — see Engine and Skill System. For user-facing command usage, see the User Guide -- CLI Commands.

Ownership note. Throughout this chapter, the behaviours described — argument resolution, scope detection, jump validation, resume branching — are computed by the engine on each next and delivered to the conductor as a directive. Where older prose said "the orchestrator does X," read it as "the engine decides X and emits a directive; the conductor carries it out." The decision logic is deterministic tool code, never SKILL.md prose.

Path convention. Each intent's state, audit trail, and intent-scoped artifacts live under its record dir — aidlc/spaces/<space>/intents/<YYMMDD>-<label>/, written <record>/ below. Reverse Engineering is the exception: its durable, per-repository outputs live at aidlc/spaces/<active-space>/codekb/<repo>/. The audit trail is a directory of per-clone shards under <record>/audit/, not a single file.

Table of Contents

• Entry Points
• Session Management
• Scope-to-Stage Mapping
• Stage Execution Engine
• Stage Advancement Protocol
• Task Tracking
• Deliberate Deviations
• Error Handling
• Appendix A: Stage Graph Reference
• Appendix B: Hook Reference
• Appendix C: Approval Gate Patterns

Entry Points

The conductor passes $ARGUMENTS to the engine's first next verbatim — it never pre-parses them. The engine parses the flags and freeform text and resolves which of the invocation patterns below applies, emitting the matching directive. The patterns are engine-resolved inputs, not conductor-side branches.

/aidlc [scope] -- Explicit Scope

When the argument matches one of the 11 known scopes (enterprise, feature, mvp, poc, bugfix, refactor, infra, security-patch, classic, workshop, express):

An explicitly named scope on a fresh workspace (no intent yet — no aidlc-state.md under aidlc/spaces/*/intents/*/) creates the first intent: the engine's next emits a run-then-continue print directive naming aidlc-utility.ts intent-create --scope <scope> (threading any --depth / --test-strategy / --review flags onto the named command); the conductor runs it and re-runs next to land on the first stage. Both naming shapes — the bare positional (/aidlc bugfix) and the explicit flag (/aidlc --scope bugfix) — emit the identical creation print. Describing what to build (/aidlc "build the auth service") also creates. A bare /aidlc with no explicitly named scope and no description does NOT creation (an env- or default-resolved scope is not a creation signal); it emits the no-state error directing the user to describe what to build or name a scope.

1. Reads guardrails from aidlc/spaces/<active-space>/memory/.
2. Asks the user "What would you like to build?"
3. Determines stages to execute per the Scope-to-Stage Mapping.
4. Executes the Initialization phase (workspace-scaffold, workspace-detection, state-init) as a single deterministic aidlc-utility intent-create call. The welcome message is rendered at session start via companyAnnouncements in settings.json.
5. Creates stage-level tasks for all in-scope stages. The first stage is set to in_progress; the rest are pending. Stages not in scope get no task at all.
6. Begins the first post-initialization stage.

/aidlc [freeform] -- AI Scope Detection

When the argument is freeform text (not a known scope keyword):

1. Reads guardrails from aidlc/spaces/<active-space>/memory/.
2. Analyzes the intent against keyword patterns:
3. "fix" / "bug" / "broken" maps to bugfix
4. "refactor" / "clean up" / "simplify" maps to refactor
5. "infrastructure" / "deploy" / "infra" maps to infra
6. "security" / "CVE" / "vulnerability" / "patch" maps to security-patch
7. "proof of concept" / "prototype" / "poc" / "spike" maps to poc
8. "mvp" / "minimum viable" maps to mvp
9. "workshop" / "lab" / "training" maps to workshop
10. "express" / "lightweight" maps to express
11. The underlying no-keyword resolver defaults to classic in a stock install; the user-facing cold-start path offers composition first for no-match or rich prose
12. Disambiguation rule: descriptions longer than five words receive the compose offer unless an affirmative high-specificity keyword (refactor, mvp, minimum viable, poc, proof of concept, or CVE) matches. The exemption checks every keyword, including those after an earlier generic match in the same scope, and rejects occurrences with nearby preceding negation. Eligible scopes retain the alphabetical tie-break. See scope auto-detection for examples and limitations.
13. On a clear keyword match, emits a typed scope-confirm ask naming the effective ceremony from the compiled grid and workspace scan: the scope, a request preview, stage count, approval gates, and the choice to confirm, change scope, or compose a tailored plan. The directive carries response_route: "next" and proposed_scope, names the request only by id (a terminal pasted <document> block stays in the question store as data and never enters an ask), and carries confirm_command, compose_command, and scope_commands (one complete, shell-quoted command per valid scope). Its question echoes at most 240 characters of the request, ending in ... when truncated. Greenfield previews apply the same reverse-engineering skip as intent creation. A per-unit clause is appended only when the scope executes units-generation and its Construction stages fan out over the resulting Unit DAG. The cost clause also names disabled effective policy, including creation flags and environment kill switches: classic defaults add ; no summary confirmation, while opting summary confirmation in removes the clause (an advisory review cap is not a disabled ceremony). Scopes with none disabled omit this clause.
14. On no match / rich prose, emits a typed compose-offer ask with response_route: "next", compose_command, and scope_commands. The composer estimates the task's implementation entropy and proposes the minimum viable EXECUTE/SKIP grid, human-gated (see below). The offer's example scope list carries counts too (express = 10 of 33 stages, classic = 18, feature = all 33) so the magnitude difference is visible before choosing.
15. On confirmation, the conductor runs the ask's complete shell-safe next command instead of calling report. Scope and compose commands carry --request <8hex id>, never the request text. For a different scope, it runs the scope_commands entry whose scope matches the chosen plan; a name with no entry is not a valid scope. The engine resolves the id to the stored full description, which intent creation records as Project in aidlc-state.md.
16. If the user overrides the detected scope, uses the user's chosen scope instead.

The engine keeps a copy of each question's request as {id, text, proposedScope, origin, askedAbout?, createdAt} in its own gitignored file under aidlc/.aidlc-sessions/questions/, written once and never rewritten, so concurrent sessions in one clone never share or invalidate each other's asks; asking again is a new question with a new id, and the earlier one stays answerable. The copies follow the same operating-system permissions as the rest of the workspace, where the request lands anyway once work starts, and are reached through no symlinked path. The copy is removed once its answer starts work; an unanswered question is kept unless question-retention-days (or AIDLC_QUESTION_RETENTION_DAYS) sets a retention period, and a question whose copy is gone errors with a describe-the-work-again message. Intent creation builds the whole record before listing it: the folder, audit, and project description first, then the workflow state, which names the question as Question Id, and last the intents.json row, which records it as request. A retry that finds a finished record its start never listed (a start stopped between the two) lists that record instead of building another. A folder without aidlc-state.md is invisible to every record scan, so a start cut off before its state lands lists nothing and trying again creates the work (under the next free folder name). A repeated answer never creates work twice: intent create and next find the row carrying that question id, continue work still in flight (Already started <record>, continuing it.), and for archived or completed work ask first (You already started this as <record>, which is archived. Start it again as new work?), starting it again from that record's stored description. Late answers: a new-work question's start or new-plan answer acts as answered even after other work became active, starting the new work alongside it; a new-work-routing question is bound to the space and records (by folder and uuid) it named, and its continue_command and compose_command act only on one of those, asking the routing question again, with the scope the human confirmed, when another is selected. On a legacy flat-layout (pre-workspace) project, a question-backed creation refuses before anything moves and keeps the question answerable; the refusal names the one-time intent create --scope <scope> that moves the flat workflow into its own intent, after which the same command creates the request. Conductors do not read or rewrite these runtime files and must not substitute the preview for the full request.

If existing intents have no selected cursor and at least one record is selectable, confirming a scope with pending work emits new-work-routing on every harness rather than dropping the request into a picker. new_work_description contains the request's directions once, proposed_scope preserves the confirmed scope, available_intents lists exact selectors, response_route is next, and numbered_prose_question provides the engine-authored numbered rendering. The routes travel as fields, never inside the human-facing question: new_intent_command (separate new work with the proposed scope), scope_commands (the same for each valid scope, for a human-corrected scope), compose_command (reshape), select_commands (one complete next intent command per selector), and reshape_commands (one per selector, which selects it and then reshapes it), all carrying the same question id; asked about an active workflow instead, the ask carries continue_command in place of available_intents and select_commands. Continuation runs the chosen record's select command and follows its print; reshape runs the chosen record's reshape_commands entry, which selects that record and then reshapes it without stopping in between. Without pending work, the engine emits intent-pick: choose the select_commands entry whose selector matches the selected available_intents value and execute its command verbatim, never interpolate the selector into a command.

/aidlc compose -- The Adaptive Composer

The compose surfaces (a leading compose verb, --new-scope, or --report <path>) make the engine emit a composer-dispatch print instead of a scope confirm. The verb is deliberately NOT a workspace verb (workspace verbs are terminal utility commands the Kiro seam runs off-band; compose is workflow work the conductor dispatches). Two modes split on the state file:

1. Front / report (no workflow yet): the conductor dispatches aidlc-composer-agent, which runs the read-only detect --json scan, estimates the five implementation-entropy components (CodeKB MCP evidence when configured, the workspace scan otherwise), and returns a structured proposal (mode matched|custom, a required nonblank creationDescription, an ars block with the component scores and evidence method, arsRationale, the grid, the four scopeSettings (sensors, learnings, summary_confirmation, review_cap) with a one-line rationale, per-SKIP rationale, a summary copied verbatim from the validator, plus two pre-rendered markdown tables: ARS scores with bands, and per-stage decisions with reasoning) validated by aidlc-graph.ts validate-grid. Validation requires the exact compiled stage set and returns the grid's stage/gate/per-unit summary plus nearest_stock, checks the settings against the words the scope loader accepts (echoed as scope_settings, with summary.off naming what they switch off), and on the composer's final --matched <stock-scope> run rejects a grid that differs from that stock scope or a Guard Policy it cannot apply, echoing the creation_settings that apply the remaining settings to this piece of work; a final --custom run picks the stock scope the plan runs on (the nearest whose Guard Policy default is the proposal's, any for strict, and never one with a walking skeleton or a test strategy other than the plan's depth, which the gate does not show) and echoes it as base_scope with plan_changes and creation_settings against it, plus creation_depth when the proposal's required depth differs from that scope's. Neither route writes a scope file. Composer-authored scopes are excluded from the ranking, and missing or extra keys count as differences. The composer routes matched-vs-custom solely on the final proposal's nearest_stock[0].diff <= 2; the mechanical ARS screen distance is advisory. When it adopts a stock grid it revalidates that final grid, replaces the summary/distance, and rebuilds every affected decision-table row before returning. The conductor never re-derives the verdict. It renders the approve/edit/reject gate as three blocks: the validator's summary line (N stages EXECUTE / M SKIP, G approval gates), then the composer's stage-decision table verbatim, then its ARS score table verbatim under "Scoring detail (advisory)". The first block also carries a Scope settings row the human can flip before approving. An edit to a matched stock grid, or one that lowers its Guard Policy, converts the revised proposal to custom and repeats validation/table rendering, because matched approval creates the stock plan. On approve AI-DLC creates the workflow directly for a stock match; for a custom plan, it creates the workflow on base_scope with intent create --skip <slugs> --add <slugs> (and --depth from creation_depth), which writes the plan as the state file's EXECUTE/SKIP suffixes (the override channel recompose uses) and records Plan: custom, based on <scope>; no scope file is written, so composing never grows the scope library. A custom gate also offers "Approve and save as scope": after creation the conductor runs scope save --name <name> (the utility's scope-save handler), which writes the running work's plan as the durable record aidlc/scopes/<name>.md and compiles its projection, so the scope survives an engine reinstall and resolves at once in this harness, and in another at its next graph compile (see Where a saved scope is stored). The same command saves the plan whenever the person asks later. The skeleton-gate anchor, firstPlannedStageOfPhase("construction", scope, state), reads those suffixes, so a composed plan's first Construction stage is its Bolt-1 gate. Task-backed composition copies the original task into creationDescription verbatim; report-only and task-less composition derives it from the approved report/plan. Task-backed creation follows the dispatch's --request <id> command, preserving the stored request without shell interpolation. For report-only/task-less proposals without a --request id, pass the approved description after the literal -- delimiter as one POSIX-single-quoted argv value; never run scope-only creation.
2. In-flight (workflow running): the composer re-estimates the entropy components from what completed stages actually resolved and returns mode: in-flight with the current scope, the preserved full effective grid, and exact changes.skip / changes.add arrays for PENDING, ahead-of-cursor stages. It never adopts a nearby stock grid, changes scope/depth, or rewrites completed/in-progress/skipped actions; both stock-distance lists are advisory in this branch. Each flip's rationale names the completed-stage evidence that moved the score, and validation runs --strict so a starved flip is caught before the gate. The conductor writes the pending-proposal marker (aidlc/.aidlc-compose-pending) before the gate (the Stop hook honours it as a turn-stop signal) and deletes it on resolve; on approve it passes those exact arrays to aidlc-utility.ts recompose [--skip <slug,...>] [--add <slug,...>] (omitting empty lists; repeated flags accumulate), which flips the plan suffixes under the audit lock, strict-validates against new starvation, rebuilds the derived fields, and emits RECOMPOSED. When the approval also covers settings, the same command carries them as --sensors, --learnings, --summary-confirmation, or --review and applies them in the one state write. No scope registry file is written. The marker is bounded: the Stop hook honours it only while it is fresh (younger than 24h by its mtime), and an older orphan (a session that crashed between the write and the resolve) is ignored and best-effort deleted, so a stranded marker cannot silently disable forwarding-loop enforcement; --doctor also reports a present marker with its age (fresh = advisory pass, stale = fail). recompose refuses under autonomous Construction (it needs a human at the gate) - switch to gated first, or let the swarm finish. Detection is chat-first: the conductor's pre-forward judgment step (the same one that spots new-work) classifies a plain-chat reshape request ("can we skip market research?") and routes it as next compose "<their words>" rather than forwarding it verbatim (a verbatim forward would fall through to Branch 10 and run the current stage). When the request names specific stages imperatively, the conductor may skip the composer dispatch and present the gate itself, running recompose directly on approve - sound because the verb rejects starved/frozen/behind-cursor/skeleton-gate flips (and any autonomous-Construction call) no matter who calls it; the human gate and the marker discipline are identical on both paths.

/aidlc --status -- Progress Check

Read-only command that inspects the current workflow without advancing it:

1. Reads the active intent's aidlc-state.md (under aidlc/spaces/<space>/intents/<YYMMDD>-<label>/).
2. Displays: current phase, current stage, completion percentage, pending decisions, and active agent.
3. If verification is needed, runs the phase boundary check per stage-protocol-governance.md section 13.
4. Does NOT advance the workflow -- strictly read-only.

/aidlc --stage <id> / /aidlc --phase <name> -- Jump to Stage/Phase

Jumps directly to a specific stage or phase. Supports both forward and backward jumps. The engine resolves the target, validates scope membership, and computes the jump direction; it emits a run-then-continue print directive naming the aidlc-jump.ts execute tool. The conductor runs that tool and re-runs next — it does not resolve or validate the jump itself. The numbered steps below describe what the jump computation (engine + tool) performs.

Forward jump (target is ahead of current position): 1. Resolves target: --stage accepts a slug (code-generation) or display number (3.5). --phase accepts a name (construction) or number (3), resolves to the first in-scope stage of that phase. 2. Checks for existing state file. If none, auto-initializes (runs 3 Initialization stages). 3. Validates the target is in scope for the current/specified scope. 4. Marks intermediate in-scope stages as [S] (skipped via jump). Already-completed [x] stages are left unchanged. 5. Warns about missing upstream artifacts and asks for confirmation. 6. Creates stage-level tasks and begins execution from the target stage.

Backward jump (target is behind current position): 1. Same resolution and validation as forward jump. 2. Resets all downstream stages (after the target) to [ ] (not started). Artifacts on disk are preserved, not deleted. 3. When the target stage and subsequent stages re-execute, they detect existing artifacts and offer: Keep / Modify / Redo from scratch. 4. Creates stage-level tasks and begins execution from the target stage.

Composable with --scope (to set/override scope), --depth (to override depth level), and --test-strategy (to override test volume).

/aidlc --scope <scope> -- Set/Override Scope

Sets the workflow scope. When used alone (/aidlc --scope bugfix), behaves like /aidlc bugfix. When combined with --stage or --phase, provides the scope for jump operations. Can be combined with --depth and --test-strategy to override defaults.

/aidlc --depth <level> -- Override Depth

Overrides the depth level (minimal, standard, comprehensive). When used alone, updates the active workflow's depth. When combined with --scope, overrides the new scope's default. Logs a DEPTH_CHANGED audit event for standalone changes.

/aidlc --test-strategy <level> -- Override Test Strategy

Overrides the test volume strategy (minimal, standard, comprehensive) independently of depth. Defaults to the current depth when not specified. Allows combinations like --depth standard --test-strategy minimal for full artifacts with minimal testing. Logs a TEST_STRATEGY_CHANGED audit event for standalone changes.

Intent creation -- the Initialization phase

There is no separate scaffold command (the earlier init flag was retired; the workspace shell ships pre-built in the installed or versioned runtime/<harness>/ projection). The three Initialization stages (workspace-scaffold, workspace-detection, state-init) run deterministically inside aidlc-utility intent-create — auto-invoked on the first /aidlc (or /aidlc <description>), or explicitly via the /aidlc-init packaging. Creation mints the intent's record dir at aidlc/spaces/<space>/intents/<YYMMDD>-<label>/ with state initialised, scope routing applied, and the workflow positioned at the first post-Initialization stage:

1. Creates the record dir tree (idempotent -- skips existing directories/files): the audit/ shard dir, one empty artifact directory per phase the scope runs (a phase with no EXECUTE stage under the active scope gets none, matching the PHASE_SKIPPED events in step 4), and the verification directory. Per-stage directories are not pre-created; a stage's directory appears when it first writes an artifact.
2. Creates the empty space-level aidlc/knowledge/ directory (a sibling of the space's intents/). It is free-form with no fixed file set — creation seeds no per-agent subdirectories and no READMEs; the team adds files itself.
3. Scans the workspace and writes the intent's aidlc-state.md with the actual phase (e.g., IDEATION for --scope feature), the resolved scope, and the stage plan derived from the compiled scope grid (scope-grid.json, the transpose of each stage's scopes: frontmatter). The exact initial description is persisted as one JSON string in committed project-description.json; the state names that source and keeps a safe single-line Project preview.
4. Emits the full event sequence: WORKFLOW_STARTED, WORKSPACE_SCAFFOLDED, WORKSPACE_SCANNED, WORKSPACE_INITIALISED, PHASE_STARTED for the first executing phase, STAGE_STARTED + STAGE_COMPLETED for each Initialization stage, plus PHASE_SKIPPED events for any phases the scope skips.
5. Auto-creates only on a workspace with zero intents; with intents already present and no active cursor, the engine prompts the user to pick one (/aidlc intent <slug>) rather than creating a duplicate. There is no workflow re-birth flag; this is unrelated to project-level aidlc config.
6. When creation was reached via the auto-creation print, the conductor re-runs next and continues into the first post-Initialization stage; the explicit /aidlc-init packaging stops after Initialization so the user invokes /aidlc again to begin interactively.

Resume (State File Exists)

When the active intent's aidlc-state.md exists and a new harness session re-enters with bare /aidlc, the session-start context tells the conductor to present the standard Resume / Redo / Jump / Start Fresh menu. The conductor feeds that choice to report --result resumed --user-input; the engine keeps the per-choice routing deterministic.

1. The session-start hook reads the state file and injects the persisted scope, phase, stage, status, agent, and next action.
2. It flags .aidlc-engine/recovery.md (in the intent's record dir) when present so the conductor can check for compaction-related state corruption.
3. On bare /aidlc re-entry, the conductor presents the four-option menu.
4. The engine routes the reported choice; Resume re-runs normal next, while Redo, Jump, and Start Fresh return the exact follow-up move.

Explicit /aidlc --resume is different: the dispatcher calls next --resume, which skips the menu and falls through to the same continuation route as bare next. A parked workflow still emits the unpark instruction first, no state still errors, and /aidlc --resume --stage <slug> takes the explicit jump route.

Session Management

Session Resume Flow

Bare session re-entry and explicit resume intentionally diverge. The conductor owns the four-option menu on bare /aidlc; explicit --resume expresses the choice up front and enters the engine's normal continuation routing.

flowchart TD
    START(["/aidlc invoked"])
    MODE{"Invocation"}
    STATE_EXISTS{"Active intent\nexists?"}
    RECOVERY_CHECK{".aidlc-engine/recovery.md\nexists?"}
    CORRUPTION{"State matches\nrecovery file?"}
    WARN["Warn user about\npossible corruption"]
    RESUME_MENU["AskUserQuestion:\nResume Options"]
    OPT_RESUME["Resume from\nlast checkpoint"]
    OPT_REDO["Redo\ncurrent stage"]
    OPT_JUMP["Jump to\nspecific stage"]
    OPT_FRESH["Start fresh\n(archive existing)"]
    RESUME_STATE{"State exists?"}
    PARKED{"Workflow parked?"}
    UNPARK["Print unpark command"]
    CONTINUE["Normal next routing:\nload-steering / run-stage"]
    JUMP["Explicit stage jump"]
    NO_STATE["Error: no workflow state"]
    SCOPE_DETECT{"Known scope\nor freeform text?"}
    KNOWN_SCOPE["Use explicit scope"]
    FREEFORM["Auto-detect scope\nfrom keywords"]
    CONFIRM_SCOPE["Confirm scope\nwith user"]
    CREATE["Creation the intent:\nmint record dir,\nstate + audit, begin\nfirst stage"]

    START --> MODE
    MODE -->|"bare /aidlc"| STATE_EXISTS
    MODE -->|"/aidlc --resume"| RESUME_STATE
    MODE -->|"/aidlc --resume --stage"| JUMP

    STATE_EXISTS -->|Yes| RECOVERY_CHECK
    STATE_EXISTS -->|No| SCOPE_DETECT

    RECOVERY_CHECK -->|Yes| CORRUPTION
    RECOVERY_CHECK -->|No| RESUME_MENU
    CORRUPTION -->|Mismatch| WARN --> RESUME_MENU
    CORRUPTION -->|Match| RESUME_MENU

    RESUME_MENU --> OPT_RESUME
    RESUME_MENU --> OPT_REDO
    RESUME_MENU --> OPT_JUMP
    RESUME_MENU --> OPT_FRESH

    RESUME_STATE -->|No| NO_STATE
    RESUME_STATE -->|Yes| PARKED
    PARKED -->|Yes| UNPARK --> CONTINUE
    PARKED -->|No| CONTINUE

    OPT_FRESH -->|"archive + confirm"| CREATE

    SCOPE_DETECT -->|"Known scope"| KNOWN_SCOPE --> CONFIRM_SCOPE
    SCOPE_DETECT -->|"Freeform text"| FREEFORM --> CONFIRM_SCOPE
    CONFIRM_SCOPE --> CREATE

    style START fill:#e1bee7,stroke:#7b1fa2,color:#000
    style RESUME_MENU fill:#bbdefb,stroke:#1565c0,color:#000
    style CONTINUE fill:#c8e6c9,stroke:#388e3c,color:#000
    style CREATE fill:#c8e6c9,stroke:#388e3c,color:#000
    style WARN fill:#ffcdd2,stroke:#c62828,color:#000
    style NO_STATE fill:#ffcdd2,stroke:#c62828,color:#000

State File Schema

The state file at aidlc/spaces/<space>/intents/<YYMMDD>-<label>/aidlc-state.md (the intent's record dir) is generated by the engine according to the contract at .claude/knowledge/aidlc-shared/state-template.md. Stage rows come from the compiled tools/data/stage-graph.json plus scope-grid.json, not from the template. It uses State Version 8 and contains:

Stage Progress uses six-state checkboxes: - [ ] not started - [-] in progress - [?] awaiting your approval (gate open) - [R] revising (you rejected the gate, stage is being revised) - [x] completed (approved by user) - [S] skipped (scope-excluded at init, cut via skip, or bypassed via --stage/--phase jump)

The Construction phase section follows the recorded iteration and checkpoint policy (see Construction Execution below). Each per-Unit stage has a checkbox per Unit from unit-of-work-dependency.md; bolt-plan.md is planning content, not the checkbox source. Under exact Unit Ownership: team, the separate Unit Progress table carries one row per Unit and one cell per applicable per-Unit Construction stage plus its Unit gate; the Stage Progress rows remain one row per stage and become derived from those columns. Construction Autonomy Mode: [unset|autonomous|gated] is recorded under Current Status — written by a ladder answer or an explicit on-demand grant or revocation, and honoured on session resume.

During active team fan-out, unscoped main emits a turn-terminal notice whose message is the deterministic Team Construction board: Unit Progress, locally observed claim movement, merge readiness, claimable Units, and blockers. Stop hooks probe the same branch without cache or state writes. /aidlc --status invokes the same pure board query in snapshot mode.

Recovery Breadcrumb

The recovery breadcrumb (.aidlc-engine/recovery.md in the intent's record dir) is written by the validate-state.ts PreCompact hook. It records a snapshot of the workflow's last known-good state before context compaction occurs.

On session resume, the orchestrator compares the breadcrumb's "Current stage" with the state file's "Current Stage". If they differ, it warns the user that compaction may have caused state corruption. This is important because PreCompact hooks are informational-only and cannot block compaction.

Resume Options

On bare /aidlc session re-entry, the conductor presents four options. The conductor reports the human's answer via report --result resumed --user-input "<answer>"; the engine matches the choice and returns a per-choice directive naming the exact move (an unrecognized answer errors with the accepted choices). Explicit /aidlc --resume skips this menu and performs option 1 directly:

1. Resume from last checkpoint -- Continues from the in-progress stage: re-run next, which reads aidlc-state.md to determine completed/in-progress/not-started stages.

2. Redo current stage -- The directive names aidlc-jump.ts execute --target <current> --direction redo --scope <scope>, which resets the current stage's checkbox; the next next re-runs it from scratch.

3. Jump to stage -- The directive instructs the conductor to ask for the target, then route through next --stage <slug> (the engine resolves the direction and validates the target).

4. Start fresh -- The directive routes through the second-intent flow: confirm scope and description, then next --new-intent --scope <scope> "<description>"; the existing workflow stays in place alongside the new intent.

Session Resume Context Loading

Scope-to-Stage Mapping

The scope determines which of the 33 stages execute and at what depth. Stages not in scope are skipped entirely -- no task is created, no approval gate is presented. All scopes begin with the Initialization phase (0.1-0.3).

Complete Mapping

Authoritative data lives in the .claude/scopes/aidlc-<name>.md files plus each stage's scopes: frontmatter, compiled into .claude/tools/data/scope-grid.json. Run aidlc engine gen scope-table for the live compiled counts.

Detailed Scope Breakdown

• enterprise -- All 33 stages with comprehensive depth. Every stage executes with full artifact detail, deep analysis, and all optional stages included. Suitable for regulated enterprise features requiring complete traceability.
• feature -- The full lifecycle: all 33 stages with standard depth. Same stage set as enterprise but with moderate artifact detail. Available explicitly through --scope feature and /aidlc-feature, or as the project default via AWS_AIDLC_DEFAULT_SCOPE=feature.
• mvp -- Skips most of Ideation (keeps only Intent Capture, light Feasibility, and Scope Definition). Runs all of Inception and Construction. Operation stages optional.
• poc -- Minimal Ideation (only Intent Capture). Core Inception. Only Code Generation and Build and Test from Construction. No Operation.
• bugfix -- No Ideation. Reverse Engineering always included (to find the bug) plus minimal Requirements Analysis. Code Generation, Build and Test, Deployment Pipeline, and Deployment Execution complete the fix path.
• refactor -- No Ideation. Same Inception start as bugfix. Adds Functional Design (as refactoring plan), then uses the same build, test, and deployment tail.
• infra -- No Ideation. Infra-focused Requirements Analysis. NFR stages + Infrastructure Design + CI Pipeline from Construction. Deployment and Observability from Operation.
• security-patch -- No Ideation. Reverse Engineering to find vulnerability context plus minimal Requirements Analysis (the auditable statement of the vulnerability and its remediation criteria). NFR Requirements, Code Generation, Build and Test. Deployment Pipeline and Deployment Execution from Operation.
• classic -- The implicit default (when neither the user nor AWS_AIDLC_DEFAULT_SCOPE names a scope): v1-style ceremony through Inception and Construction, with one human approval per stage. Ideation is skipped and Operation remains a placeholder; stage-declared execution modes and support agents are unchanged. Only the three Initialization stages, Requirements Analysis, Units Generation, Delivery Planning, Code Generation, and Build and Test are ALWAYS; the remaining stages self-select. Standard depth and Standard test strategy preserve the production test floor. Walking-skeleton ceremony and summary confirmation are off. Sensors run and the learnings ritual runs. Reviews are advisory (one pass per stage, findings at the approval gate); explicit autonomy keeps the single pre-merge review. Per-intent /aidlc --sensors on|off, --learnings on|off, and --summary-confirmation on|off override the scope, while AIDLC_DISABLE_SENSORS=1, AIDLC_DISABLE_LEARNINGS=1, and AIDLC_DISABLE_SUMMARY_CONFIRMATION=1 force their ceremony off. Approval gates, Plan Approval, human-turn authority, audit, and team write protection remain.
• workshop -- The compatible facilitated-session lifecycle: Inception, Construction, and Operation, with the established workshop / lab / training keywords, advisory stage reviews, and a Minimal test-strategy override.
• express -- The lightest requirements-to-deploy route: conditional Reverse Engineering, Requirements Analysis, one zero-Unit Code Generation iteration, Build and Test, and a conditional deploy/observability tail. It skips Units Generation, so Bolt, skeleton, ladder, per-Unit, and swarm paths are structurally unreachable. Code Generation artifact paths and validity receipts use the stage-level Construction directory. review_cap: none disables reviewers.

Depth Levels

Stage Execution Engine

Every stage follows one of the four active execution patterns: inline, subagent, pipeline, or mob (29 / 2 / 1 / 1 in the shipped graph). The compiled stage graph (tools/data/stage-graph.json) carries each stage's mode; the engine reads it and delivers it on the run-stage directive as directive.mode. The Stage Graph table in SKILL.md is a human-readable mirror, not the dispatch source.

Full Stage Lifecycle

sequenceDiagram
    participant O as Orchestrator
    participant SF as Stage File
    participant A as Agent (.md)
    participant K as Knowledge (6 steps)
    participant U as User
    participant S as aidlc-state.md
    participant AU as audit/ shard

    O->>A: 1. Apply load-steering parts, then read inline_context_paths
    Note over A: Rules arrive as content - persona and knowledge remain path-loaded

    O->>SF: 2. Read stage file
    Note over SF: directive.stage_file

    O->>K: 3. Read resolved inputs
    Note over K: directive.consumes

    O->>S: 4. Engine activates stage as [-]
    S->>AU: Emit STAGE_STARTED

    alt Inline Stage (29 of 33)
        O->>U: Execute stage work in conversation
        U-->>O: Answer questions, provide feedback
        O->>U: Present 5-part completion message
        O->>U: AskUserQuestion: Approval Gate
        U-->>O: Approve / Request Changes
    else Fully Dispatched Stage (3 of 33: subagent or pipeline)
        O->>O: Bundle context into Task prompt
        O->>O: Call Task tool (subagent_type set to the named agent)
        O-->>O: Receive structured summary
        O->>U: Present completion message from summary
        O->>U: AskUserQuestion: Approval Gate
        U-->>O: Approve / Request Changes
    else Mob Stage (1 of 33)
        O->>U: Execute lead draft inline
        O->>O: Dispatch blind support-agent contributions
        O->>U: Integrate as lead and present Approval Gate
        U-->>O: Approve / Request Changes
    end

    O->>S: 5. Report approved
    S->>AU: Atomically emit STAGE_COMPLETED
    O->>O: 6. Transition tasks, route to next stage

Steering continuation recovery

Every stored steering_payload on a load-steering or run-stage marker has a steering_payload_receipt, the payload's MAC under the local key. Outside a tracked Copilot attempt, a continue receipt that matches no current part falls back to current routing. Stateful workflows route from their state file regardless of the marker's route hint. Stateless runs replay the stored scope, stage, and single-run flag only when the stored receipt verifies. Edited route fields, or a legacy marker without that receipt, supply no trusted route: with no state file, the engine returns an error directive saying the receipt matched no current part and the stored route could not be verified. Issue a fresh next --scope <scope> --stage <stage>, adding --single if it was a single run. A stale or superseded receipt under a tracked Copilot attempt keeps its error path. See Rule delivery and the continuation cursor.

Inline Execution

Inline stages run directly in the orchestrator conversation. The user can interact with the stage in real time. Twenty-nine of 33 stages are inline; the other four are dispatched (practices-discovery and code-generation subagents, reverse-engineering pipeline, user-stories mob).

The 6-step process:

1. Load the stage steering. Follow the ordered load-steering sequence until run-stage; it delivers every substantive active-space rule as content. Then read every inline_context_paths entry. Persona and knowledge remain path-loaded; missing, unreadable, or invalid UTF-8 optional files are omitted from the roster and reported through specific or aggregated context_warnings.
2. Read the stage file. The conductor reads the exact directive.stage_file.
3. Read resolved inputs. The conductor reads the existing artifacts in directive.consumes, applying the stage's documented fallback for expected absent inputs.
4. Load conditional protocol modules. Read every file named by directive.protocol_modules, skipping a module already loaded earlier in the session. The field selects reviewer, ensemble, Construction, and swarm contracts; the SKILL's prose triggers are the compatibility fallback.
5. Execute steps directly in conversation. The orchestrator performs the stage work inline: asking questions, analyzing answers, producing artifacts, and interacting with the user.
6. Follow stage-protocol.md for approval gates. Every inline stage (except the 3 Initialization stages) ends with the 5-part completion message and an AskUserQuestion approval gate.
7. Return control to the engine. After approval, the conductor reports the outcome; the engine atomically updates state, logs completion, and routes to the next stage.

Dispatched and Hybrid Execution

Three stages delegate their lead work to separate agent tasks. The mob keeps its lead inline and dispatches only its support agents:

Workspace detection (0.2) used to be a subagent. It is now a deterministic rule-based scanner inside aidlc-utility intent-create; rules are documented in aidlc-common/stages/initialization/workspace-detection.md.

The 6-step process:

1. Load delivered rules, read stage and inputs. Apply every ordered load-steering part before run-stage. Use the exact directive paths for the stage file and artifacts.
2. Load conductor-owned context. A mob directive carries its lead's complete path roster in inline_context_paths; fully dispatched subagent/pipeline directives carry an empty roster.
3. Prepare briefs: rules as content, artifacts as paths. Paste the accumulated steering bundle verbatim; pass relevant artifact paths and task instructions. The named harness agent config loads persona and knowledge; do not copy either into the prompt.
4. Apply the topology. Use blind spokes for subagent supports, ordered links for pipeline, and blind support contributions plus the bounded objection round for mob. After each pipeline return, mint the current-attempt PIPELINE_LINK_COMPLETED receipt before dispatching the next link; resume from directive.pipeline.completed, and add --single on an isolated run.
5. Collect durable output. The lead owns produces[]; dispatched subagent/mob supports each write an identity-marked contribution file.
6. Complete through the engine. Verify artifacts/evidence and present the approval gate.

Multi-Agent Coordination

Some stages involve multiple agents: a lead agent and one or more support agents. The coordination pattern follows directive.mode — the stage's communication topology — and is always orchestrator-mediated:

1. Execute the lead agent's work first, producing primary artifacts.
2. Bring in each support agent per the topology. On an inline stage the orchestrator reads every lead/support entry in directive.inline_context_paths and adopts those perspectives rather than dispatching them. On mob, it reads the lead-only roster and performs the lead work inline, while each support is a real dispatch. On subagent (hub-and-spoke) and pipeline (chain), the lead and supports are dispatched: mutually-blind spokes on subagent, ordered enrichment hops on pipeline, and parallel blind contributions plus a bounded objection round on mob (stage-protocol-ensemble.md). Every returned pipeline hop is recorded with aidlc-log.ts link; multi-repo chains include --repo, isolated runs include --single, and repo-scoped reuse rows suppress dispatch for reused stores.
3. Synthesize all agent outputs into the final stage artifacts — dispatched support agents write contribution files (Contribution + Positions, stage-protocol-ensemble.md §11) that the lead integrates; the lead alone edits the produces[] artifacts (pipeline links advance them directly); unresolved mob judgment calls surface to the human mid-stage, and maintained dissent is quoted verbatim at the gate.
4. Agents do NOT invoke each other -- only the orchestrator delegates. Authored core and Claude personas enforce this with disallowedTools: Task; harness projections use their native tool policy instead where needed. Kiro omits that unsupported Markdown key and excludes the subagent tool from delegate JSON/frontmatter allowlists.

Practices Discovery is the gate-ordering exception. Its hub-and-spoke work ends at an Approve / Request Changes gate; after Approve, the conductor runs practices-promote. Only that command may commit the affirmed timestamp and PRACTICES_AFFIRMED audit receipt, and the receipt must be fresh for the current stage attempt before the engine accepts approved. Missing, stale, or failed promotion leaves the gate open and the stage incomplete.

Two-Link Reverse Engineering Pipeline

Stage 2.1 is the shipped mode: pipeline example -- a two-link chain in which each link advances the work product directly:

1. Developer (link 1, the lead): Scans the codebase, analyzes code structure, identifies components, maps dependencies, returns raw analysis.
2. Architect (link 2, the final link): Receives the developer's raw analysis and synthesizes it into the 9 codekb artifacts under aidlc/spaces/<active-space>/codekb/<repo>/ -- the final link leaves the produces[] artifacts complete, per the pipeline contract.

Reverse Engineering checks each brownfield repository's shared codekb before scanning. A verified-current store may be reused by human choice; stale, unverified, legacy, or intent-mismatched coverage is rescanned. Multi-repo intents resolve every repository decision before the stage reports or advances. Each scanned repo has its own two-link receipt chain; artifacts without both current-attempt receipts cannot enter or complete approval.

Construction Execution

New source-producing solo Unit workflows record Construction Checkpoints: enabled, Construction Iteration: unit-major, and Construction Execution: serial. Unit decomposition and an included source-producing per-unit stage are required. With a real non-empty Unit DAG, the default walks one Unit through all applicable per-unit stages, including Code Generation, before the next Unit. Runtime order comes from unit-of-work-dependency.md; bolt-plan.md records delivery intent rather than replacing the DAG. Preserve an explicit stage-major choice. Legacy workflows without the checkpoint field retain the first-stage review and late per-stage cascade; team-owned unit_gate uses its own policy. Design-only, zero-Unit, and isolated runs do not gain a checkpoint ceremony.

When skeleton-on applies, the first DAG Unit must be planned as the smallest working integrated slice. It completes its applicable per-unit stages before later Units even under stage-major. The engine then emits a run-stage with construction_checkpoint: {kind, unit, stages, fingerprint, ready, verified, approved, human_required, verification_command, command_authorized, errors, proof_path}. verification_command is the full canonical recorded command, never an abbreviated display label. A skeleton checkpoint requires an actual end-to-end project check, current artifact/source/attempt-bound proof, and a real human approval. An ordinary Unit checkpoint requires verification and follows the recorded completion approval policy. A first design-stage review is not evidence of a shipped skeleton.

The intent's Construction Verification Command is recorded during Delivery Planning or, if the human defers because no runnable check exists, at the first checkpoint. Before presenting the command, write it to <record>/verification-command.txt with the harness's file-write tool (Write/edit), never a shell echo or heredoc. Repo-derived command text must never be interpolated into a shell line, where substitutions could execute before approval. Use the invoking SessionStart session ID: both log decision and log answer require --checkpoint verification-command --command-file verification-command.txt --session "<session ID>". Copy the complete canonical command exactly from the command field in the decision tool's JSON output into the verification-command question's code span; never abbreviate it. Choose a delimiter that preserves any command backticks. The human can also open <record>/verification-command.txt. The canonical command is a nonblank single line of at most 1024 characters. Control characters and display-spoofing characters (Unicode format characters, including zero-width and bidi controls, line/paragraph separators, and no-break space U+00A0) are refused. The human's exact Approve / Request Changes reply in that session binds the answer to the canonical command digest. Only Approve authorizes the receipt; an unrelated reply, Request Changes, or a reply from another session does not. Never write --details "Approve" unless the human chose it; only then run state set-construction-verification-command --command-file verification-command.txt to write the matching Runtime State field. The latest current-workflow VERIFICATION_COMMAND_RECORDED receipt is the authority, not the field alone. When command_authorized: false, route to that question before any verify, even under autonomy, then re-run next. Every Unit/batch checkpoint reuses the authorized command; changing it requires a new receipt and typed setter, never generic state set. The approval question shows "Verified with <full command> (exit 0)", using the complete canonical verification_command from the tool output without abbreviation. Version-3 proofs store the command's SHA-256 and full canonical command as the display label; older proofs require re-verification. 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.

Route metadata before generic gates. The conductor handles unit_gate through the team path, then swarm_checkpoint or construction_checkpoint through their checkpoint commands before body/reviewer/settle handling. It never regenerates a finished Unit because the directive says run-stage. Checkpoint approval/rejection returns to next, not whole-stage report-approval. Missing/stale evidence is repaired through its owning review/receipt procedure, consulting the human as needed; verification must never be invented. The checkpoint commands show the exact action forms.

Only after verify reports verified: true and the current checkpoint has ready: true, open the human Unit/skeleton approval question with aidlc engine bolt checkpoint --action ask --unit "<unit>" --kind <unit|skeleton> --session "<session ID>"; ask refuses an unready or unverified checkpoint. For a human batch question, only after status reports ready: true, run aidlc engine bolt swarm-checkpoint --action ask --batch <N> --units "<Units>" --session "<session ID>". Then present Approve / Request Changes and wait. The human's exact reply in that session, to this checkpoint question, authorizes the matching action; an unrelated reply, another session's reply, or a reply to a different question does not. Pass that same --session on approval/rejection and never pass --user-input the human did not choose. Consent is one-shot and bound to the current checkpoint fingerprint, verification proof ID, and authorized command digest (batch questions bind the fingerprint and per-Unit Command SHA-256 set). Re-running verify or swarm finalize withdraws every open checkpoint question and captured checkpoint response for this intent, in any session. Re-verify, confirm verified: true (batch: ready: true after source landing), and ask again; an older response cannot approve the new evidence. Automatic approval (human_required: false) needs no ask and no --user-input; human rejection always needs this verified question-and-answer flow.

A normal run-stage may also carry construction_policy with iteration, execution, autonomy, offer_autonomy, human_completion_required, and completion_only. When completion_only: true and human_completion_required: false, Unit approvals already cover the work: skip body, questions, reviewer, and learnings prompt; report awaiting-approval then approved without --user-input, then next. Otherwise run the emitted body and required reviews, and use human_completion_required for its routine completion question. An unfinished per-Unit iteration still writes its Unit receipt and calls next. Plan Approval remains human-required under every completion policy; pre-generation summary confirmation applies only when directive.ceremony.summary_confirmation === "on".

Autonomy offer. offer_autonomy: true offers Continue automatically / Review each checkpoint, mapped by bolt set-autonomy to autonomous / gated, then returns to next. Skeleton-off offers at Construction entry; skeleton-on offers after the real skeleton checkpoint. A known choice is never prompted again. Explicit on-demand requests remain valid during Construction; escalation needs a fresh human turn. Autonomy waives ordinary completion questions, not skeleton approval, Plan Approval, verification command selection, enabled summary confirmation, or failure stops.

Execution choice. Eligible new source-producing solo Unit workflows select serial execution independently of autonomy. Explicit Construction Execution: swarm requires stage-major and supports gated or autonomous batch completion. Unit-major stays serial and refuses a contradictory swarm setting. Without the execution field, legacy workflows retain their existing autonomy-based swarm route. An approved inline Unit is not repeated in later swarm batches. Every emitted swarm Unit still needs initial Plan Approval; when several Units' plans are ready together the engine asks one question for all of them and records one approval per Unit. After approval, plan, test instruction, and Testing Contract edits for the same target and attempt follow the effective plan-approval fence: lowered permits continuation, on asks again. Other code moving never asks again. The original human approval evidence remains intact.

Initial prepare requires committed approved source. For protected Code Generation in either legacy autonomy or new checkpoint workflows, the approved parent application source must be committed and reproducible. Initial prepare validates the entire Unit set read-only before creating a worktree. Uncommitted approved source produces an actionable commit-and-retry refusal with no orphan child. This makes committing the approved inline skeleton source an explicit step before a later parallel batch; an autonomy grant does not authorize an automatic commit. Current Plan Approval must still bind the source used.

After a swarm batch settles, swarm_checkpoint carries {batch, units, fingerprint, ready, approved, human_required, errors}. It is handled before swarm_settled and ordinary body logic. Guided completion presents Approve / Request Changes; automatic completion omits --user-input. The checkpoint must be ready, and approval returns to next before another batch. It never completes the whole Code Generation stage on behalf of unbuilt batches.

After a batch Request Changes, the emitted resume_existing: true uses prepare --resume-existing. If the rejection retired the prior approval, obtain fresh Plan Approval for that revision. Once that actual approval exists, retries for the same intent, target, and attempt retain it and may use lowered-fence postapproval continuation. execution_allowed: true (exit 0) permits that continuation even with ok: false; it does not restore approval from an older attempt. A surviving child keeps its source while prior metadata is archived. If native source landing removed the child, verified landing evidence permits a fresh fork from the already-landed parent source, retaining the revision and its actual approval evidence. A missing child without that evidence is refused. Do not assume all post-merge children are preserved, or substitute initial prepare for a rejected-batch resume.

The engine-driven per-unit loop for the design stages (3.1–3.4) and serial code-generation hands the conductor concrete Unit paths with gate: false while work remains. On an explicitly selected stage-major walk, the four inline design stages may also carry directive.wave: complete per-Unit entries for the first unsettled batch, derived from one cache-validated, self-healed DAG snapshot. Each entry identifies its Unit and kind, present/absent consumes, all produces, the kind-applicable required produce subset, Unit-local memory path, build state, completion-receipt state, and paired fingerprint-bound review state. The conductor never reads or reconstructs the DAG.

Wave builders inherit the parent directive's stage metadata, inline persona/knowledge roster, context warnings, accumulated steering content, and effective review class. They use only their entry's paths and do not enter the serial single-active-Unit lifecycle. Instead, after build and paired review settlement, aidlc-state.ts unit complete --wave verifies the live entry, copies its Unit diary into the parent diary with deterministic deduplication, and emits UNIT_COMPLETED. The engine keeps a batch active until every applicable Unit has artifacts, valid summary confirmation, terminal review evidence when required, memory fan-in, and a completion receipt; dependent batches and the single stage gate cannot overtake any of them. Code-generation remains excluded because it writes the shared workspace and carries a mandatory Plan Approval hard stop. Unit-major iteration remains serial. See stage-protocol-construction.md § "Per-unit batch waves" for the full contract.

Diary fan-in leaves an absent parent diary absent when the Unit has no entries. In particular, waves with the learnings ritual off create neither stage nor Unit diaries.

Failure handling is halt-and-ask and runs regardless of autonomy mode:

• Solo Code Generation failure: halt, emit BOLT_FAILED on the swarm/worktree path, present retry / skip / abort.
• Parallel batch partial failure: wait for all parallel Tasks to return, preserve successful Units' artifacts on disk, emit BOLT_FAILED with Succeeded=[names], present the same choices scoped to the failed Unit. Retry re-runs only the failed Unit; the batch siblings stay [x].

This example uses the source-producing solo Unit default (unit-major and serial), skeleton-on, summary confirmation enabled (directive.ceremony.summary_confirmation === "on"), and an explicit automatic-completion choice after the skeleton:

sequenceDiagram
    participant U as User
    participant C as Conductor
    participant E as Engine
    C->>U: First Unit questions, summary and Plan Approval
    U->>C: Confirm summary and approve the plan
    C->>E: Complete applicable design and code work with review receipts
    E->>C: Skeleton checkpoint for the integrated first Unit
    C->>E: Verify real end-to-end project check
    C->>U: Approve the working integrated slice?
    U->>C: Approve
    C->>E: Approve skeleton checkpoint, then next
    E->>C: offer_autonomy true
    C->>U: Continue automatically or review each checkpoint?
    U->>C: Continue automatically
    C->>E: set-autonomy autonomous, then next
    C->>U: Next Unit summary and Plan Approval
    U->>C: Confirm summary and approve the plan
    C->>E: Build, review, verify and auto-approve ordinary Unit
    E->>C: completion_only stage directives after all Units
    C->>E: Report bookkeeping outcomes without user input

State and audit safety under parallel dispatch: aidlc-audit.ts uses mkdir-based locking so concurrent appends are safe. Lifecycle writes happen only after all required Task results return and the conductor reports one outcome; the engine serialises the internal state transition. No state-race risk.

Stage Advancement Protocol

State transitions are engine-owned. The conductor reports outcomes through aidlc-orchestrate.ts; the engine invokes its internal state transition to update the state file, emit lifecycle audit rows, and route atomically. See State Machine for the canonical workflow / phase / stage state diagrams and full audit-event taxonomy.

Stage Lifecycle

stateDiagram-v2
    [*] --> Pending
    state "[ ] Pending" as Pending
    state "[-] Active" as Active
    state "[?] AwaitingApproval" as Awaiting
    state "[R] Revising" as Revising
    state "[x] Completed" as Completed
    state "[S] Skipped" as Skipped

    Pending --> Active : engine route / STAGE_STARTED
    Active --> Awaiting : report awaiting-approval / STAGE_AWAITING_APPROVAL
    Awaiting --> Completed : report approved / GATE_APPROVED + STAGE_COMPLETED
    Awaiting --> Revising : report rejected / GATE_REJECTED + STAGE_REVISING
    Revising --> Awaiting : report revised / STAGE_AWAITING_APPROVAL
    Pending --> Skipped : scope composition / STAGE_SKIPPED
    Active --> Skipped : report skipped / STAGE_SKIPPED
    Revising --> Skipped : report skipped / STAGE_SKIPPED
    Completed --> [*]
    Skipped --> [*]

The orchestration engine owns every transition above. The conductor reports outcomes and never writes checkbox states, calls state lifecycle verbs directly, or emits stage/gate/phase audit events via prose.

When a stage completes (user approves via the gate)

1. Run completion verification - check artifacts exist on disk, guardrails respected. This is a correctness check, not a state transition. This is also enforced deterministically: approve refuses a gated stage whose declared produces artifacts are missing (unless AIDLC_SKIP_ARTIFACT_GUARD=1), so a stage cannot be marked complete without its outputs (#366). Per-unit Construction stages are verified by the swarm referee instead.

2. Enter the gate: aidlc engine orchestrate report --stage <slug> --result awaiting-approval. Before the state transaction opens, the engine fires each gate-bound sensor once per existing declared deliverable. A blocking binding requires a verified pass; findings, unavailable execution, malformed verdicts, and timeouts refuse the transition. To override interactively, first record and present the separate Fix findings / Override blocking sensors decision through aidlc-log.ts, wait for and record the exact human answer, then retry with --override-blocking-sensors --user-input "Override blocking sensors". Autonomous runs cannot override. Otherwise the engine marks [-] → [?], emits STAGE_AWAITING_APPROVAL, and makes /aidlc --status show "Awaiting your approval on \<stage>".

3. Present the approval gate (AskUserQuestion).

4. Record the user's response:

5. Approve -> aidlc engine orchestrate report --stage <slug> --result approved --user-input "<exact choice>". Emits any missing gate row, then GATE_APPROVED + STAGE_COMPLETED, and advances. Refuses with a missing-produced-artifact error if the stage's produces outputs are absent.
6. Request Changes → aidlc engine orchestrate report --stage <slug> --result rejected --user-input "Request Changes" --reason "<feedback>". The engine emits GATE_REJECTED + STAGE_REVISING, marks [?] → [R], and increments Revision Count.

7. After re-running work for a [R] stage, call aidlc engine orchestrate report --stage <slug> --result revised to re-enter the gate (re-runs gate sensors, emits a fresh STAGE_AWAITING_APPROVAL, marks [R] → [?]). The approve-time unrecorded-revision backstop uses the same sensor enforcement before recovered re-entry; a blocking result leaves the durable state at [R].

8. Advance to the next stage: the approval report in step 4 also advances. The engine derives the next in-scope stage from the state file's EXECUTE/SKIP suffix (set by init) plus the compiled scope grid (scope-grid.json). It marks [x] on completed, [-] on next, updates Current Stage / Lifecycle Phase / Active Agent / Next Stage / Last Completed Stage / Last Updated / Completed count, and emits STAGE_STARTED for the next stage. At a phase boundary it additionally emits PHASE_COMPLETED + PHASE_VERIFIED + PHASE_STARTED atomically.

The tool is idempotent — replaying advance <slug> a second time returns {replay: true} without re-emitting events.

1. If this was the last in-scope stage: the same report --stage <slug> --result approved --user-input "<exact choice>" call marks [x], sets Status=Completed, and emits PHASE_COMPLETED + PHASE_VERIFIED + WORKFLOW_COMPLETED. Present a completion summary.

2. Transition tasks: mark the old task completed, set the new task in_progress with activeForm: "Running <Next Stage> [slug]". The [slug] suffix triggers the PostToolUse hook that syncs statusline fields.

Phase Boundary Verification

At phase transitions (init→ideation / inception / …, ideation→inception, inception→construction, construction→operation), advance emits PHASE_COMPLETED + PHASE_VERIFIED + PHASE_STARTED. The orchestrator is responsible for running the traceability check from .claude/knowledge/aidlc-shared/verification.md BEFORE calling advance — if verification fails, surface the issues to the user and do not advance.

Task Tracking

The orchestrator uses Claude Code's TaskCreate/TaskUpdate/TaskList tools to maintain a visible progress sidebar throughout the workflow.

Stage-Level Tasks

Tasks are created at the stage level -- one task per stage in scope. Tasks exist only in the Claude Code task sidebar (NOT stored in the state file). If task IDs are lost after context compaction, they are recovered via TaskList using subject-based lookup.

Task Creation Timing

Tasks are created in phase batches:

• INITIALIZATION: All Initialization stage tasks (workspace-scaffold, workspace-detection, state-init) created before aidlc-utility intent-create runs. The tool completes all three stages in one call; tasks flip to completed after the tool returns.
• IDEATION: All Ideation stage tasks created before stage 1.1 begins.
• INCEPTION: All Inception stage tasks created before stage 2.1 begins.
• CONSTRUCTION: Tasks created from the compiled scope graph and the Unit DAG in unit-of-work-dependency.md. Per-unit stage tasks are created for each unit, plus cross-cutting tasks. bolt-plan.md is planning, not the task source.
• OPERATION: All Operation stage tasks created before stage 4.1 begins.

Per-Unit Task Naming Conventions

Skipped Stage Handling

For stages marked SKIP in the execution plan, the orchestrator creates a task but immediately marks it completed with a skip description. This ensures the sidebar shows the full stage set with clear skip annotations.

MANDATORY Status Line Updates

Before executing ANY stage, the orchestrator MUST:

1. Mark the previous stage task (if any) as completed.
2. Activate the current stage task as in_progress with activeForm set to "Running [Stage Name]".

The task MUST be in_progress for the activeForm spinner to display. This update must happen BEFORE reading the stage file.

Deliberate Deviations

The following intentional differences from the upstream aidlc-workflows/ reference and the v2 framework spec are documented in SKILL.md and stage-protocol.md to prevent future "fix" attempts.

Error Handling

Subagent Failure Retry

When a Claude Code Task tool call fails:

1. Retry once with a reduced context prompt (summarize inception artifacts, pass only current unit's design artifacts).
2. If retry also fails, offer two options: "Run inline" (execute in orchestrator conversation) or "Skip and revisit" (mark incomplete and continue).
3. Log the failure using the Error format in the audit/ shards.

State Corruption Recovery

If aidlc-state.md exists but cannot be parsed:

1. Create a backup (aidlc-state.md.bak).
2. Scan the intent's record dir for artifact evidence to determine which stages actually completed.
3. Rebuild the state file from artifact evidence.
4. Inform the user: "State file was corrupted. Rebuilt from artifacts. Please verify."

If .aidlc-engine/recovery.md disagrees with aidlc-state.md on resume, warn the user of possible compaction-related corruption.

Missing Artifact Recovery

If a stage references prior artifacts that do not exist:

1. Check which expected artifacts are missing.
2. Cross-reference with state (is the producing stage marked complete?).
3. If marked complete but artifacts missing, offer: re-run the stage or provide artifacts manually.
4. If not marked complete, run the stage normally.

Contradictory Inputs Recovery

If user inputs from different stages contradict each other:

1. Flag the specific contradiction with quotes from both sources.
2. Do NOT resolve by choosing one interpretation.
3. Ask the user which input takes priority.
4. Update the overridden artifact and log the resolution.

Error Severity Levels

Appendix A: Stage Graph Reference

Complete reference of all 33 stages with execution metadata. The welcome message is rendered at session start via companyAnnouncements in settings.json — not a stage.

Execution key: - ALWAYS: Executes for all scopes that include this stage. - CONDITIONAL: May be skipped based on scope, project type, or execution plan.

Mode key: - inline: Runs in the orchestrator conversation. User can interact. - subagent (<agent-name>): On Claude Code, delegated via the Task tool with subagent_type set to the named agent (e.g., aidlc-developer-agent). The subagent inherits the full session toolset unless narrowed by an optional tools: allowlist; disallowedTools: Task blocks nested delegation. Other harnesses use their native dispatch and tool-policy surfaces; Kiro delegate allowlists omit subagent.

Appendix B: Hook Reference

The framework hooks are registered project-wide in settings.json (the v0.6.0 hooks-move; they self-gate when no workflow is active). Three of them are detailed below. The rest, including aidlc-run-sensors.ts, aidlc-sync-workflow-state.ts, and aidlc-rebuild-stage-graph.ts, are covered in Hooks and Tools, which carries the authoritative hook list and full source-level documentation for all of them.

PostToolUse: aidlc-write-audit-log.ts

• Matcher: Write|Edit
• Trigger: Every Write or Edit Claude Code tool call during the skill session.
• Behavior: Filters to the intent's record-dir paths only. Skips the audit/ shards themselves (avoids recursion). Emits a canonical ARTIFACT_CREATED (Write to net-new path) or ARTIFACT_UPDATED (Edit, or Write overwriting existing) event via appendAuditEntry. Uses mkdir-based locking via lib.ts.
• Exits silently if the active intent's audit/ shard does not exist.

PreCompact: validate-state.ts

• Matcher: (empty -- matches all compaction events)
• Trigger: Before Claude Code performs context compaction.
• Behavior: Exits silently if no state file exists. Validates aidlc-state.md contains "Stage Progress" and "Current Status" sections. Writes .aidlc-engine/recovery.md breadcrumb.

SubagentStop: log-subagent.ts

• Matcher: (empty -- matches all subagent completions)
• Trigger: When any subagent finishes execution.
• Behavior: Exits silently unless the active workflow state has Status: Running. Otherwise emits a canonical SUBAGENT_COMPLETED audit event via appendAuditEntry (replacing the earlier free-form ## Subagent Completed markdown write). Fields: agent type, agent ID, and truncated message (first 200 characters). Uses mkdir-based locking via lib.ts.

These hooks are TypeScript sources routed through aidlc; they require neither Bun nor jq at runtime.

Human turns and protected question responses

The human-turn hook routes a reply to one recorder. While the engine's Plan Approval question is the active directive, recordPlanApprovalAskReply owns the reply: it reads it in the person's own words from any chat on this piece of work, takes the fingerprint of the plan files as they are, and writes the questions-file answer, the receipt, and the PLAN_APPROVAL_RECORDED row. A typed "review the plan" while an approved plan may keep building records a review request instead. Otherwise the reply goes to the legacy Kiro IDE path's recordPlanApprovalHumanResponse, or to recordProtectedHumanResponse for the session's verification-command, Construction-policy, or checkpoint-approval question. Minting either challenge removes the other challenge and response; if conflicting files nevertheless exist, the hook deletes both and records no response. A protected response binds the session, fresh challenge ID, and offered choice. Its consumer also requires the current canonical target digest.

When a picker supplies the rendered question, the hook requires its exact text digest to match the minting command's --decision text. Without rendered text, the one-open-question rule is the fallback. Every log decision, including an ordinary question, withdraws protected consent for its explicit or ancestry-resolved session before recording the decision; if the session cannot be resolved, it withdraws every session's protected consent. Opening a lifecycle gate through report --result awaiting-approval also withdraws every session's protected consent. Ask protected questions one at a time and wait for the answer before anything else; a withdrawn question must be asked again. These ordinary decision and lifecycle-gate withdrawals do not change Plan Approval's separate challenge/response lifecycle.

Appendix C: Approval Gate Patterns

Standard 2-Option Gate (Construction and Operation)

AskUserQuestion({
  questions: [{
    question: "[Stage Name] complete. How would you like to proceed?",
    header: "Approval",
    multiSelect: false,
    options: [
      { label: "Approve", description: "Continue to [next stage]" },
      { label: "Request Changes", description: "Provide revision feedback" }
    ]
  }]
})

[next stage] is rendered verbatim from the run-stage directive's next_stage field (the display name of the next in-scope stage, computed by the engine at emit time), or Complete workflow when next_stage is null. The conductor never infers the next stage.

Conditional 3-Option Gate (Ideation and Inception only)

AskUserQuestion({
  questions: [{
    question: "[Stage Name] complete. How to proceed?",
    header: "Approval",
    multiSelect: false,
    options: [
      { label: "Approve", description: "Continue to [next stage]" },
      { label: "Request Changes", description: "Provide revision feedback" },
      { label: "Add [Skipped Stage]", description: "Include [stage] which was skipped" }
    ]
  }]
})

Revision Loop Escape Hatch

After 3 "Request Changes" cycles on the same stage, a third option appears:

AskUserQuestion({
  questions: [{
    question: "[Stage Name] -- this is revision cycle [N]. How would you like to proceed?",
    options: [
      { label: "Approve" },
      { label: "Request Changes" },
      { label: "Accept as-is", description: "Archive current version and move on" }
    ]
  }]
})

The "Accept as-is" option logs the decision, marks the stage complete, and overrides the NO EMERGENT BEHAVIOR RULE for that specific stage.

After the 2nd revision cycle (before the escape hatch activates), the approval question includes a note: "After one more revision, an 'Accept as-is' option will become available."

Final Stage Gate (4.7 Feedback & Optimization)

Options:
  - Approve (workflow complete)
  - Request Changes
  - Start New Ideation Cycle

NO EMERGENT BEHAVIOR RULE

Construction and Operation stages MUST use standardized 2-option completion messages. The orchestrator must NOT create 3-option menus or other emergent navigation patterns for these phases. Only Ideation and Inception stages may conditionally include a 3rd option (to add a previously skipped stage). Two sanctioned exceptions exist: the revision loop escape hatch (3+ revision cycles) and the Build-and-Test failure loop-back in the construction protocol module (aidlc-common/protocols/stage-protocol-construction.md) with its impact-estimated halt-and-ask question.

The loop-back replay is settlement-aware. Artifact-only Code Generation workflows may return directly to the all-covered gate; sticky receipt-mode workflows re-emit per-Unit directives and re-mint unit start / unit complete. Both routes apply the planned fix and deterministic Artifact Re-use decisions before the gate, then invoke the declared reviewer for every applicable Unit to record fresh current-attempt REVIEW_COMPLETED receipts: the jump invalidates every prior review and approval refuses without replacements. Unit-major uses this serial per-Unit route and never invokes the autonomous swarm. The replay repairs the already-approved plan, so its Plan Approval answer remains intact; a gated "Retry with fix" is the re-approval of the revised approach.

Cross-References

• Architecture -- 5-layer model, execution model
• Stage Protocol -- behavioral contract for all stages
• Agent System -- agent frontmatter, tool restrictions
• Hooks and Tools -- hook system, audit event taxonomy
• Knowledge System -- 6-step knowledge loading order
• Diagrams -- all Mermaid diagrams consolidated

Completed-stage validity advisory

Immediately before normal happy-path routing, next performs a read-only validity inspection. Runtime artifact instances are resolved through the active Bolt DAG, produces_kinds, and the shared canonical filename resolver, then compared through compact stage-level structure/content fingerprints.

Direct mismatches project stale. Propagation follows artifact dependencies observed in completed consumer receipts, so absent optional inputs do not cause false invalidation. If any completed result is stale or needs revalidation, the engine keeps the normal directive kind and attaches a machine-readable stage_validity advisory. The conductor surfaces its warning, then continues routing. Inspection-unavailable stages remain a per-turn advisory because they need attention. Receipt-less histories are reported as untracked by /aidlc --status only, so migration does not add a warning to every next.

The suggested recovery uses the existing explicit jump path:

/aidlc --stage <earliest-affected-stage>

A successful re-completion writes a fresh receipt. Existing workflows and prior Draft receipt formats remain fail-open until their stages complete again. Full inspection runs on next and explicit --status, never on each statusline render.