CLI Commands

All AI-DLC commands start with the orchestrator invocation. This chapter is a complete reference for every invocation pattern and flag.

Invocation prefix differs by harness. On Claude Code, Kiro IDE, Kiro CLI, Cursor, opencode, and GitHub Copilot you type /aidlc; on Codex CLI it is $aidlc (or /skills → aidlc). The flags and behaviour below are identical either way — only the prefix changes. The examples use /aidlc; substitute $aidlc on Codex. See the Kiro CLI, Kiro IDE, Codex CLI, Cursor, opencode, and GitHub Copilot harness guides.

Cursor shortcuts. Cursor also exposes /aidlc-status, /aidlc-jump --stage <slug|#> (or --phase <name|#>), and /aidlc-scope <name> as native skills. They package the matching /aidlc forms below and use the same engine; they are aliases, not alternate state paths.

Quick Reference

Command Decision Tree

flowchart TD
    START(["What do you want to do?"])

    Q1{"Start a new\nworkflow?"}
    Q2{"Check or manage\nan existing workflow?"}
    Q3{"Verify the\nproject?"}

    A1["/aidlc feature"]
    A2["/aidlc Build a payments API"]
    A3["/aidlc"]
    A4["/aidlc --status"]
    A5["/aidlc --stage code-generation"]
    A6["/aidlc --phase construction"]
    A8["/aidlc --doctor"]

    START --> Q1
    START --> Q2
    START --> Q3

    Q1 -->|"Know the scope"| A1
    Q1 -->|"Describe what you want"| A2
    Q2 -->|"Resume where I left off"| A3
    Q2 -->|"See progress"| A4
    Q2 -->|"Jump to a stage"| A5
    Q2 -->|"Jump to a phase"| A6
    Q3 -->|"Verify setup"| A8

    style START fill:#e1bee7,stroke:#7b1fa2

Detailed Reference

/aidlc [scope] — Start with explicit scope

Start a new workflow with one of the enabled scopes. Core ships 11 named scopes; plugins can add more, and select-plugins can hide disabled plugin/core scopes from runtime.

Syntax:

/aidlc enterprise
/aidlc feature
/aidlc mvp
/aidlc poc
/aidlc bugfix
/aidlc refactor
/aidlc infra
/aidlc security-patch

Behavior: The framework recognizes the scope keyword, asks what you want to build, then runs the Initialization phase and begins the first domain stage. If a state file already exists, it offers resume options instead.

Example:

/aidlc bugfix
> What would you like to fix?
> The login API returns 500 when email contains a plus sign

/aidlc [description] — Start with auto-detection

Describe what you want to build and the engine auto-detects the appropriate scope.

Syntax:

/aidlc Build a REST API for inventory management
/aidlc Fix the login timeout bug

Behavior: The engine analyzes keywords in your description (e.g., "fix" suggests bugfix). A clear match asks a one-line confirm naming the MATCHED scope and its ceremony (stage count, approval-gate count, and any per-unit fan-out, all from the compiled grid); rich or unmatched prose gets the compose offer (see /aidlc compose below) instead of a silent default. You confirm or override before the workflow begins.

Example:

/aidlc Fix the null pointer in ProfileSerializer
> Starting a "bugfix" workflow for: "Fix the null pointer in ProfileSerializer" - 7 of 33 stages, 4 approval gates, 1 stage repeats per unit of work in Construction. Confirm to proceed, name a different scope, or say "compose" for a tailored plan.

/aidlc compose - The adaptive composer

Force the composer even when a stock scope would match. Works in three moments:

/aidlc compose "harden the deployment pipeline and add observability"
/aidlc compose --report sonar.json
/aidlc compose            (mid-workflow: re-shape the pending stages)

Behavior: the conductor dispatches the composer agent, which reads your task (or the scan report, or the running workflow's state), runs the read-only detect scan, estimates the five implementation-entropy components (intent ambiguity, structural uncertainty, verification entropy, risk, unresolved assumptions - grounded in CodeKB MCP analysis when configured, the workspace scan otherwise), and proposes the minimum viable EXECUTE/SKIP grid with the score breakdown and a reason for every EXECUTE and SKIP. You approve, edit, or reject at a gate. On approve: a stock match births directly; a custom grid is authored as a real scope (two files in the installed tree) and the workflow births on it in the same turn; an in-flight proposal lands as pending-stage suffix flips via the recompose verb (under the audit lock, strict-validated, RECOMPOSED audited). --new-scope forces synthesis; --report <path> seeds the triaged findings into the intent. The /aidlc-compose skill is a typeable shortcut over the same path. Mid-workflow you can also just say it in chat ("can we skip market research?") - the conductor recognizes a reshape request and routes it through the same gate and verb, no literal compose needed (on the non-Claude harnesses the literal verb remains the documented reliable path).

See Scopes and Depth - The Adaptive Composer for the full flow.

/aidlc — Resume existing workflow

Run with no arguments when a state file exists to resume.

Syntax:

/aidlc

Behavior: Reads aidlc-state.md, checks .aidlc-recovery.md for corruption, then presents four resume options: resume from checkpoint, redo current stage, jump to stage, or start fresh. See Session Management for details.

If no state file exists, the framework treats this as a new workflow and asks for scope/description.

Initialization — automatic, no command

There is no scaffold command. The shipped dist/<harness>/ workspace shell arrives pre-built (the .claude/ engine plus aidlc/spaces/default/memory/), and the engine auto-births the first intent on your first /aidlc (or when you describe what to build). Birth runs the three Initialization stages (Workspace Scaffold, Workspace Detection, State Init) as a single deterministic tool call: it creates the intent's record dir at aidlc/spaces/<space>/intents/<YYMMDD>-<label>/ (the audit/ shard dir, an artifact dir for each phase the scope runs, verification/) and the empty space-level aidlc/knowledge/ directory, runs a rule-based workspace scan, and writes that intent's aidlc-state.md with the scope plan. It logs the init-sequence events (WORKFLOW_STARTED, WORKSPACE_SCAFFOLDED, WORKSPACE_SCANNED, WORKSPACE_INITIALISED, plus per-stage STAGE_STARTED/STAGE_COMPLETED). Naming a scope (/aidlc --scope feature) seeds the initial scope; absent one it resolves AWS_AIDLC_DEFAULT_SCOPE, then defaults to classic. To add team knowledge or guardrails before the first run, edit the shipped aidlc/spaces/default/memory/ files; the space-level aidlc/knowledge/ directory is created (empty) once the first intent exists, and you add free-form files to it from there.

The welcome message is rendered at session start via the companyAnnouncements entry in settings.json.

Multi-repo workspaces. When your workspace root holds more than one sibling code repo (each an immediate child directory with a .git), the birth step records the set of repos the intent touches in its intents.json row. By default it auto-discovers every sibling repo; to scope an intent to a specific subset, the birth tool accepts --repos a,b (a comma-separated list of repo directory names). These are flags of the deterministic aidlc-utility intent-create step the engine runs for you — not /aidlc flags you type. During Construction, each git operation (worktree, swarm, Bolt) targets one repo; the conductor passes --repo <name> to anchor it, required only when an intent spans more than one repo. An intent with no recorded repos is the single-repo default (git runs in the workspace/project dir). See Artifacts Reference.

/aidlc intent [name] — List or switch intents

Bare /aidlc intent lists the intents in the active space; add --json for structured output. /aidlc intent <name> switches the per-user active-intent cursor to an existing intent by unambiguous slug or full record-dir name. It never creates an intent or advances a workflow.

/aidlc space [name] — List or switch spaces

Bare /aidlc space lists spaces; add --json for structured output. /aidlc space <name> switches the per-user active-space cursor and re-points the harness-native method include to that space. It never creates a space or advances an intent.

/aidlc space-create <name> — Create a space

Creates a new team space with the full memory/, knowledge/, codekb/, and intents/ shape, seeded from the framework baseline rather than another team's learned practices. It does not switch spaces automatically. See Spaces and Intents for the workspace model, switching examples, and what is committed.

/aidlc knowledge <verb> — Index and read your own documents

Put your documents — PDFs, Word files, Markdown, plain text — under aidlc/spaces/<space>/knowledge/documents/, organised however you like, then index them so agents can cite them instead of guessing.

--space <name> targets a space other than the active one. onboard is idempotent: re-running it on an unchanged file reports already rather than writing a second row, so sweeping is always safe to repeat. A file that changed at a path that is already indexed reports edited and refreshes that row in place, so one path never carries two live rows — the outcomes are fresh, already, and edited, and they are worth reading, because "no output changed" and "nothing happened" are different results.

Batch limits. A pathless onboard and sync apply the 20-document/256 MiB limits to new, changed, or retrying work, not to already-current catalog rows. An already-reconciled catalog can be larger. When a work batch exceeds a cap, onboard the affected files individually before syncing again. Nothing is indexed when a cap is hit, so the refusal is never half-finished. A single document over 32 MiB is refused without being read at all; the message says so, because "refused" and "read, then refused" have very different costs on a large file.

Scoping. Omit --intent and the document is space-wide — every intent can see it. Bare --intent means the active intent, and fails rather than guessing when there is no cursor. --intent <slug> names one explicitly, and fails if the slug matches zero or more than one intent (slugs can repeat across finished intents; the stored association is always the UUID, so renaming a slug never re-points a document). Scoping to an intent that has finished is refused unless you add --allow-inactive, which exists for back-filling evidence onto a closed record.

Text extraction is delegated to whatever extractor the project configures. PDF gets a default extractor (pdftotext) if none is configured; a Word (.docx) file has no built-in default — with none configured it is catalogued and citable as unsupported_type; after configuring an extractor, run sync to retry unchanged rows of that detected type. If a CONFIGURED extractor is not installed the document is catalogued as extractor_unavailable — visible in list, and fixed by installing the tool and running /aidlc knowledge sync. Re-running onboard on the same unchanged path reports already and does NOT retry extraction — only sync re-probes rows in this state. Nothing is silently skipped.

Extraction is capped: 50 pages for PDF (pdftotext -l 50) and 200,000 characters of extractor output. Past a cap the text is cut and the row records truncated — show prints a truncated yes line above the content and the --json payload carries the flag inside extraction. Treat a truncated extraction as a partial view: "the document does not mention X" is not a safe conclusion from one.

A configured extractor's argv must contain exactly one $IN — the placeholder the document's path is substituted into. A configuration without it is refused when the tool starts, rather than accepted: a process that never receives the file would otherwise record whatever it printed as the extracted text of every document routed to it, which looks like successful extraction and is not. More than one $IN is refused for the same reason — the intent is ambiguous, so it fails closed.

There is deliberately no remove. Deleting a document means deleting your own file and then running sync, so the tool never holds a destructive verb over files you own. A deleted original leaves a tombstoned row — the catalog's record that this was removed on purpose, which is distinct from source_unavailable, meaning a linked original is temporarily unreachable.

Document text is data, not instructions. show ships that warning inline with the content. An imperative sentence inside a customer's contract addresses that customer's engineers — it never redirects an AI-DLC workflow, grants permission, or authorises a command.

The /aidlc-knowledge skill is the same surface, typed as a command.

/aidlc --status — Read-only status

Display current workflow progress without modifying anything.

Syntax:

/aidlc --status

Behavior: Reads the active intent's aidlc-state.md and displays: current phase, current stage, completed/total stage count, scope, depth, and the stage progress list. If no workflow is active, reports that no workflow is in progress.

/aidlc --doctor — Health check

Validate that all of this implementation's prerequisites, configuration, and stage-graph integrity are in place. Exits 0 on full pass, 1 on any failure; the full report writes to stdout in both cases so the orchestrator surfaces it either way. --doctor is read-only — on a fresh shell with no intent yet (no audit/ shards) it creates no files, so it is safe to run before the first intent is born; once an intent exists it records a HEALTH_CHECKED audit row.

When a workflow has issues, --doctor also prints a Workflow diagnosis section listing the structured findings (e.g. gate-unresolved, runtime-graph-stale) for unresolved gates, a stale or missing runtime graph, cold hooks, and similar "it will not advance" causes. The live report and --export share one analysis, so the findings are identical either way.

Syntax:

/aidlc --doctor

What it checks:

Example output:

✓ bun installed (required for CLI tools and hooks)
✓ aidlc-write-audit-log.ts present
✓ aidlc-sync-workflow-state.ts present
✓ aidlc-validate-state.ts present
✓ aidlc-log-subagent.ts present
✓ aidlc-session-start.ts present
✓ aidlc-session-end.ts present
✓ aidlc-statusline.ts present
✓ settings.json present
✓ AWS_AIDLC_DEFAULT_SCOPE (unset — no project default)
✓ workspace shell ready (.claude/ + aidlc/spaces/default/memory/)
✓ Submodules: no .gitmodules at workspace root
✓ Hook heartbeats: not yet fired (first workflow stage will populate)
✓ Hook drops: none recorded
✓ State matches last audit event (no drift)
✓ Cycle detection: 0 cycles
✓ Orphan stage files: 33 graph entries all have files
✓ Uncompiled stage files: 0 stage files missing from the compiled graph
✓ Enabled plugins: all enabled (no selection); enabled stage counts: aidlc=33
✓ Scope validation: 11 scopes valid
✓ Schema validation: 33/33 stages valid
✓ Graph references: 122 artifacts + edges resolved
✓ Keyword overlap: no conflicts
✓ Rule drift: no team/project rule overlaps org policy
✓ Paired sensor coverage: no sensor-bound rules (0 feedforward-only)

/aidlc --doctor --export — Write a diagnostic report

Add --export to --doctor to write a small, redacted diagnostic report so a misbehaving workflow can be debugged without sharing your whole project directory. It runs a fresh doctor pass first (the report never reflects a cached diagnosis), then writes the report. The report write never changes doctor's exit code.

Syntax:

/aidlc --doctor --export
/aidlc --doctor --export --output <dir>

--output <dir> overrides the output location; the default is aidlc/diagnostics/ under the project.

What it produces: a timestamped .tar.gz when a system tar is available, otherwise the report directory is retained with instructions to compress it yourself before sharing (no new package dependency, no bespoke archive writer). The report contains:

What it diagnoses: the report reconstructs the workflow timeline from the audit trail (stage durations, gates, revisions, gaps, and abnormal/incomplete flags), then runs deterministic condition→remedy rules (no LLM) for the common "it will not advance" causes: unresolved approval gates, state/audit drift, and a stale or missing runtime graph / cold or frozen hook heartbeats. Findings come from the same shared DoctorFinding model the live --doctor uses, so the command and the report can never diverge. A remedy that names a recovery bypass (for example an AIDLC_DISABLE_* env var or an "archive your workspace" instruction) is always flagged as not safe to automate.

DOCUMENT_INDEXED/DOCUMENT_UPDATED/DOCUMENT_REMOVED live in the space-level audit shard. --doctor --export reads that shard explicitly and combines it with the active intent's shards, so the report includes document history after a workflow starts while workflow-authority readers remain intent-scoped. list and show continue to read the DocumentKB catalog directly.

Safety. The report never includes workspace source, raw state/audit/ runtime-graph files, artifact/contribution/question/memory bodies, environment variables, or command output. Every emitted string is redacted: your home dir becomes ~, the project root becomes <project>, intent ids are hashed, and secret-like values are scrubbed. Inputs whose real path escapes the project root are refused (a symlinked leaf or parent is not followed out of the tree), per-file and total size are capped (truncations are recorded in the manifest), and files are created owner-only where the platform supports it.

Example output:

Diagnostic report created:
  aidlc/diagnostics/aidlc-diagnostic-report-20260714-153000-3f9a1c22.tar.gz

Findings:
  ERROR gate-unresolved
  WARNING runtime-graph-stale

No source files or artifact bodies were included.

/aidlc --stage <slug|#> — Jump to stage

Jump directly to a specific stage by slug or number.

Syntax:

/aidlc --stage code-generation
/aidlc --stage 3.5
/aidlc --stage requirements-analysis
/aidlc --stage 2.3

Behavior: If a workflow is active, jumps to the target stage (skipping intervening stages with warnings). If no workflow exists, you can combine with --scope:

/aidlc --stage code-generation --scope bugfix

/aidlc --stage <slug> --single — Run one stage in isolation

Add --single to run a single stage on its own without touching your main workflow. The stage runs, writes its artifact, and stops; your workflow's Current Stage is never advanced — the isolation is enforced by the engine, not by convention. Use it to apply one piece of methodology (a requirements analysis, a reverse-engineering scan) without committing to a full lifecycle. The isolated run still uses the stage's configured agents and reviewer, but it does not run workflow learnings or ask for a workflow approval. Its synthetic completion is recorded in the audit log, then the command stops.

/aidlc --stage requirements-analysis --single
/aidlc --stage reverse-engineering --single

Every runnable stage also ships a typeable one-word runner — /aidlc-<slug>, which packages /aidlc --stage <slug> --single. The full runner family (scope runners, stage runners, /aidlc-init, and the session views) is documented in Skills and Runner Commands.

/aidlc --phase <name|#> — Jump to phase

Jump to the first stage of a specific phase.

Syntax:

/aidlc --phase construction
/aidlc --phase 3
/aidlc --phase ideation
/aidlc --phase 1

Behavior: Same as --stage but targets the first stage of the named phase. Can be combined with --scope.

/aidlc --scope <name> — Change scope

Change the active scope of a running workflow.

Syntax:

/aidlc --scope bugfix
/aidlc --scope enterprise

Behavior: Updates the scope configuration in aidlc-state.md, recalculates which stages should execute and which should be skipped, and logs a SCOPE_CHANGED audit event. Can be combined with --depth, --test-strategy, and --review; all supplied overrides are applied in the same change.

Refused under autonomous Construction (Construction Autonomy Mode: autonomous), the same rule as recompose: re-shaping the plan needs a human at the gate, and an unattended run has none. Switch to gated Construction first (aidlc-bolt set-autonomy --mode gated) or let the swarm finish.

On a fresh project with no workflow yet, --scope <name> starts one instead: it behaves exactly like /aidlc <name> — the workspace is initialized with the named scope and the workflow begins at its first stage.

/aidlc --depth <level> — Override depth

Override the depth level of the current or new workflow.

Syntax:

/aidlc --depth minimal
/aidlc --depth standard
/aidlc --depth comprehensive

Behavior: When a workflow is active, updates the Depth field in aidlc-state.md and logs a DEPTH_CHANGED audit event. When combined with --scope, overrides the new scope's default depth. When combined with --stage or --phase, sets the depth for the jump target's execution context. Without an active workflow, produces an error.

Valid values: minimal, standard, comprehensive (case-insensitive).

Examples:

/aidlc --depth minimal                            Change depth of active workflow
/aidlc --scope bugfix --depth comprehensive        Bugfix with comprehensive analysis
/aidlc --stage code-generation --depth minimal     Jump with minimal depth

/aidlc --test-strategy <level> — Override test strategy

Override the test volume strategy independently of depth.

Syntax:

/aidlc --test-strategy minimal
/aidlc --test-strategy standard
/aidlc --test-strategy comprehensive

Behavior: Defaults to the current depth level when not specified, unless the scope declares its own override. When set independently, allows combinations like Standard depth (full artifacts) with Minimal testing (Nyquist model). Updates the Test Strategy field in aidlc-state.md and logs a TEST_STRATEGY_CHANGED audit event.

Valid values: minimal, standard, comprehensive (case-insensitive).

Test strategy models: - Minimal (Nyquist): 1 test per requirement, happy-path floor, unit tests only (~5-15 total) - Standard: 5-8 tests per component, unit + integration - Comprehensive: 10-15 tests per component, all test types

See Scopes, Depth, and Test Strategy for full details on each level, defaulting behavior, and common combinations.

Examples:

/aidlc --test-strategy minimal                         Minimal testing for active workflow
/aidlc --depth standard --test-strategy minimal        Full artifacts, minimal tests
/aidlc --scope bugfix --test-strategy comprehensive    Bugfix with thorough testing

/aidlc --review <class> — Cap stage reviews for this run

Set the per-run review override: a ceiling on how heavyweight the §12a stage reviews run for the active workflow.

Syntax:

/aidlc --review adversarial
/aidlc --review advisory
/aidlc --review none

Behavior: Each reviewer-bearing stage declares a review class in its frontmatter — adversarial (the reviewer refutes the artifact and the lead fixes findings across up to reviewer_max_iterations passes) or advisory (one normal-flow review pass; findings are quoted verbatim at the approval gate for you to triage). The effective class per stage is the LOWEST of the stage's declaration, the scope's review_cap (bugfix, poc, classic, and workshop cap to advisory; express caps to none), and this override — so --review advisory turns every remaining adversarial loop into a single normal-flow decision-support pass, --review none skips reviewer dispatch entirely, and --review adversarial clears the override (it cannot raise a class above the stage declaration or the scope cap). Autonomous swarm construction is exempt: inside a Bolt the reviewer is the only pre-merge verification, so the declared class always applies there. Updates the Review Override field in aidlc-state.md and logs a REVIEW_CLASS_CHANGED audit event. It can be supplied when a workflow is born or alongside --scope; a same-as-current scope applies the review override as a config change instead of discarding it. For either class, a later output write that invalidates a terminal receipt permits one bounded recovery request at the next ordinal.

Valid values: adversarial, advisory, none (case-insensitive).

Examples:

/aidlc --review advisory              Single normal-flow pass, findings at the gate
/aidlc --review none                  No stage reviews this run
/aidlc --review adversarial           Clear the override (stage defaults apply)

/aidlc --version — Framework version

Print the framework version (aidlc <X.Y.Z>) and exit. Read-only — works without a workflow and never prompts to resume one.

Syntax:

/aidlc --version

/aidlc --help — Usage information

Display a summary of available commands and flags.

Syntax:

/aidlc --help

Deterministic CLI Tools

Beyond the /aidlc flags above, this implementation ships several Bun/TypeScript tools that the hooks and stage protocol call as a workflow runs. You rarely invoke them by hand, but each is also a useful debug handle.

Use bun <harness-dir>/tools/<tool>.ts <subcommand>, where <harness-dir> is .claude on Claude Code, .kiro on Kiro CLI and Kiro IDE, and .codex on Codex CLI.

aidlc-utility codekb-path - resolve the code knowledge directory

This is a direct utility invocation, not an /aidlc codekb-path command:

bun .claude/tools/aidlc-utility.ts codekb-path --repo <repo>
bun .kiro/tools/aidlc-utility.ts codekb-path --repo <repo>
bun .codex/tools/aidlc-utility.ts codekb-path --repo <repo>

It prints the active space's deterministic aidlc/spaces/<space>/codekb/<repo>/ path. Add --json for {space, repo, dir}. The query writes nothing, creates no directory, and emits no audit event; reverse-engineering stage prose invokes it directly so paths are never derived by hand.

aidlc-utility codekb-scope-diff - check the code knowledge base before a rerun

This is a direct utility invocation, not an /aidlc codekb-scope-diff command:

bun .claude/tools/aidlc-utility.ts codekb-scope-diff --repo <repo>
bun .claude/tools/aidlc-utility.ts codekb-scope-diff --repo <repo> --compare <timestamp.md>
bun .claude/tools/aidlc-utility.ts codekb-scope-diff --repo <repo> --mint --paths src/payments/,src/billing/

The reverse-engineering rerun guard. The codekb store is space-level and shared across intents; a rerun replaces it, so the stage checks first:

• Status mode (default) reads the store's reverse-engineering-timestamp.md Scope of Analysis block and recomputes a content fingerprint over its analyzed paths. Verdicts: NO_STORE (first scan), CURRENT (analyzed paths unchanged - reuse is safe), STALE (analyzed paths changed), UNVERIFIED (no computable fingerprint - e.g. not a git work tree), UNKNOWN_SCOPE (store predates scope tracking).
• Compare mode (--compare <incoming timestamp.md>) answers whether the incoming run's scope covers the store's: COVERS, or NARROWER plus the exact paths and components an overwrite discards. A kind: full scope must include repository root (./), and only another full scope can replace a full store without a NARROWER warning.
• Mint mode (--mint --paths <a,b,...>) prints the fingerprint the architect pastes into the scope block at synthesis time (unknown outside a git work tree or when a pathspec is invalid).

Add --json for the structured shape. Always exits 0 with the verdict in the output (except usage errors); writes nothing, no audit event. The fingerprint is a git write-tree over a temporary index restricted to the analyzed paths, excluding the framework-owned aidlc/ tree when the workspace root is the repository root. It tracks source working-tree content without invalidating itself when codekb/state artifacts are written; rebases or squashes that rewrite history do not fool it, and reverting an edit restores the original fingerprint.

aidlc-utility detect - read-only workspace scan

bun .claude/tools/aidlc-utility.ts detect --json prints the workspace scan (project type, languages, frameworks, build system, and a submodules array of any declared git submodules with their initialized state) plus the resolved scopes dir and scope-grid path. Pure read; the composer runs it to learn where scope data lives on the current harness.

aidlc-workspace-sync - clone and reconcile the declared repo set

This is a direct tool invocation, not an /aidlc workspace-sync command. It reconciles a multi-repo workspace against the optional repos.json manifest at the workspace root (see Declaring the repo set):

bun .claude/tools/aidlc-workspace-sync.ts [--force]
bun .kiro/tools/aidlc-workspace-sync.ts [--force]
bun .codex/tools/aidlc-workspace-sync.ts [--force]
bun .aidlc/tools/aidlc-workspace-sync.ts [--force]

It serializes reconciles with a workspace lock whose live owner is never reaped for age, then runs a read-only preflight before staging clones and generated files. Generated outputs are installed with no-replace links and reversible same-filesystem renames. If .gitignore or aidlc.code-workspace changes during staging, or if repos.json changes after the plan is read, sync aborts rather than applying stale state or overwriting the edit. Prior generated files that are replaced successfully remain under the ignored .aidlc-workspace-sync-recovery-* directory for inspection. The tool clones repos declared in repos.json but missing on disk, rewrites the managed block in the workspace .gitignore to one /{name}/ line per repo, and writes an aidlc.code-workspace VSCode multi-root file listing the root plus each child repo. A declared branch is checked out for a new clone. Repos already on disk are never re-cloned or switched; a mismatch there remains an advisory.

An orphan checkout (on disk but not in repos.json) blocks the run and is removed from the active sibling set only when you pass --force and the tool can prove it has no local-only state. That proof overrides configurable status defaults, includes untracked and ignored files and directories (including empty directories), hidden index state, stashes, refs and reflogs, unreachable Git objects, linked worktrees, submodules, and LFS object stores. It queries each real remote instead of trusting cached remote-tracking refs, then fetches matching object graphs into an isolated probe so an advertised-but-unservable OID cannot authorize removal. A local remote whose storage or object alternates depend on the checkout cannot count as recovery.

After the live-remote proof, the checkout moves into transaction quarantine and receives the full local and live-remote proof again. Its quarantined copy is retained under an ignored .aidlc-workspace-sync-recovery-* directory rather than recursively deleted, so a process that already holds the directory open cannot lose a late write between proof and cleanup. Inspect retained checkout and generated-file backups, then delete the recovery directory manually when it is no longer needed. Any uncertainty blocks for manual review. Exit codes: 0 fully in sync, 1 blocked or error (live paths unchanged), 2 synced but advisory warnings remain (e.g. an existing checkout's branch mismatch).

The manifest is optional and never overrides disk: intent birth still auto-discovers whatever sibling repos are actually present, so this tool only reproduces and tidies the declared set. --doctor carries three advisory rows about it (uncommitted aidlc/ records, repos.json vs on-disk drift, and a stale managed .gitignore block); like all advisory rows they never change the doctor exit code.

aidlc-utility select-plugins - install plugin selection

/aidlc plugin list prints installed plugin names and whether each is enabled. /aidlc plugin select [names] is the public command. select-plugins is its direct utility form; it is not an /aidlc select-plugins command. bun .claude/tools/aidlc-utility.ts select-plugins prints the current selection (all enabled (no selection) when the plugins key is absent) and the known plugin names. Pass a comma-separated list to set it:

bun .claude/tools/aidlc-utility.ts select-plugins test-pro
bun .claude/tools/aidlc-utility.ts select-plugins aidlc,test-pro

The command validates names, writes .claude/tools/data/harness.json, strips a newly disabled plugin's merged contributions from core stage source (structural adds via the compose-written sidecar, spliced prose via its sentinel markers; re-enabling restores them on the next session start), recompiles the full graph with disabled nodes marked enabled:false, prunes/regenerates stage and scope runners, and refreshes the generated SKILL.md scope/stage tables in one transaction. aidlc is core; omitting it disables core surfaces except the always-on Initialization stages. A change that would strand an active workflow (its scope, or a pending EXECUTE stage in its plan, owned by a plugin the new selection disables) is refused with each dependency named - complete or park the workflow first, or keep the plugin enabled.

/aidlc plugin sync runs installed plugin compose hooks. It is safe to run repeatedly; when no plugin roots are present it exits 0 with no installed plugins; nothing to sync.

aidlc-utility recompose - in-flight plan flips

bun .claude/tools/aidlc-utility.ts recompose --skip <slugs> --add <slugs> (comma-separated) flips PENDING, ahead-of-cursor stages' plan suffixes on the live state file. Runs under the audit lock, rejects flips that would starve a remaining stage of a required input (and flips of completed/in-progress stages, behind-cursor stages, any flip that would move the first EXECUTE stage of Construction - the walking-skeleton anchor - in either direction, any recompose against a workflow whose Status is not Running, and any recompose under autonomous Construction - re-shaping the plan needs a human at the gate, so switch to gated first or let the swarm finish), rebuilds the derived state fields, and emits RECOMPOSED. Normally reached through /aidlc compose mid-workflow, not typed directly.

aidlc-graph ars - deterministic ARS scoring

bun .claude/tools/aidlc-graph.ts ars --iae <s> --csu <s> --ve <s> --r <s> --ua <s> [--completed <csv>] [--project-type <t>] computes the adaptive composer's Autonomy Risk Score arithmetic: the weighted composite with its band label, the LOW/MED/HIGH component bands, the per-stage expected-value screen against the shipped cost priors, the nearest stock scopes by grid diff count, and the two gate tables pre-rendered as markdown. Every constant - weights, band boundaries, stage cost priors, EV thresholds - is read from tools/data/ars-priors.json, so the same five scores always render the same numbers; the composer scores the components from evidence and copies this output instead of doing the multiplication. --completed (comma-separated slugs) keeps stages that already ran EXECUTE in the derived grid; --project-type brownfield|greenfield screens out stages whose compiled condition: restricts them to the other kind of project (today Reverse Engineering, brownfield-only). The JSON result lands on stdout; exit 1 on an out-of-range score, an unknown stage slug, or a priors-schema violation - never a silent fallback. The composite is an ADVISORY index for the human at the gate: nothing deterministic routes on it.

bun .claude/tools/aidlc-graph.ts ars --iae 0.55 --csu 0.75 --ve 0.65 --r 0.50 --ua 0.55
bun .claude/tools/aidlc-graph.ts ars --iae 0.30 --csu 0.80 --ve 0.40 --r 0.20 --ua 0.10 \
  --project-type greenfield --completed intent-capture,scope-definition

aidlc-graph validate-grid - arbitrary-grid dependency check

bun .claude/tools/aidlc-graph.ts validate-grid --proposal <path> [--strict] [--project-type <t>] [--keywords <csv>] validates an arbitrary {"<stage>": "EXECUTE"|"SKIP"} JSON grid. The proposal must name every compiled stage exactly once; missing stages, unknown stages, and invalid actions are errors. Lenient mode mirrors validate-scope (an off-path required producer is advisory); --strict hard-rejects it (the recompose posture). --keywords checks each granted keyword against the keywords existing scopes already claim: a collision is a hard error naming the incumbent scope (the composer runs this before writing gate-granted keywords). The result also carries nearest_stock: every graph/plugin-authored stock scope ranked by grid distance from the proposal ({scope, diff, differs}, ascending), with composer-authored scope entries excluded and missing or extra keys counted as differences. For front/report composition, the matched-vs-custom decision routes solely on this final proposal result (diff <= 2 plus compatible depth), not a model recount or the earlier mechanical ARS screen. In-flight recomposition treats the ranking as advisory and preserves the running scope and plan. Exit 1 iff invalid; the JSON result lands on stdout.

aidlc-sensor — inspect and fire Sensors

Sensors are deterministic checks that run after every Write or Edit to a stage output (see Rules and the Learning Loop and reference Sensor System). The PostToolUse hook fires them for you; this tool lets you list, describe, and manually fire one.

A manual fire emits a SENSOR_FIRED audit row, then exactly one terminal row: SENSOR_PASSED, SENSOR_FAILED, or SENSOR_BUDGET_OVERRIDE. A failure writes a detail file under <record>/.aidlc-sensors/<stage>/ (in the intent's record dir). Sensors are advisory — a Sensor failure is never a tool failure, so the command still exits 0. The six Sensors that ship with the framework are claim-sources, required-sections, upstream-coverage, traceability, linter, and type-check.

bun .claude/tools/aidlc-sensor.ts list
bun .claude/tools/aidlc-sensor.ts describe required-sections
bun .claude/tools/aidlc-sensor.ts fire required-sections \
  --stage requirements-analysis \
  --output-path aidlc/spaces/default/intents/<YYMMDD>-<label>/inception/requirements-analysis/requirements.md

aidlc-learnings — the learning-gate tool

This is the deterministic half of the §13 learning gate. After a stage is approved, the orchestrator uses it to turn your stage's memory.md diary into reviewable learning candidates, then to persist the ones you confirm. You normally never call it directly — the orchestrator drives both steps around an AskUserQuestion gate — but it is here so the audit rows it emits make sense.

Confirmed learnings apply on the next workflow, not the current one.

aidlc-runtime — read the runtime graph

The runtime graph (runtime-graph.json in the intent's record dir) is the data-plane record of what actually happened this workflow: which stages ran, how full each memory.md diary got, which Sensors fired, what each returned. It is the runtime mirror of the structural stage-graph.json. The framework recompiles it after every stage transition; this tool lets you trigger a compile or read one stage's row.

bun .claude/tools/aidlc-runtime.ts read requirements-analysis

runtime-graph.json is gitignored. See Artifacts Reference for the artifact's shape and the Runtime Graph reference chapter for the full schema.

Session skills — report on a workflow

Three read-only skills surface what aidlc-runtime summary reports, wrapped in readable output. Type them like commands:

All three are read-only — no stage advance, no audit emit — and source every number from aidlc-runtime summary --json. See Session Management § Session Skills for the full walkthrough.

Environment Variables

AWS_AIDLC_DEFAULT_SCOPE

Pre-set the default scope for a project. Read from .claude/settings.json env block at workflow initialization.

Syntax (in .claude/settings.json):

{
  "env": {
    "AWS_AIDLC_DEFAULT_SCOPE": "classic"
  }
}

Valid values: enterprise, feature, mvp, poc, bugfix, refactor, infra, security-patch, classic, workshop, express.

Precedence: explicit CLI flag > keyword detection > AWS_AIDLC_DEFAULT_SCOPE > hard-coded fallback.

Scope of effect: applies at workflow initialization only. Once the intent's aidlc-state.md exists, the state file is authoritative. See Customization § Per-Project Default Scope for the full walkthrough.

Next Steps

• Skills and Runner Commands — The typeable /aidlc-<scope> and /aidlc-<stage> runners, and what --single does
• Session Management — Resume options and stage jumps in detail
• Scopes, Depth, and Test Strategy — Scope definitions, stage mappings, and test strategy levels
• Troubleshooting — When commands don't behave as expected
• Glossary — Definitions for command, utility command, scope