Scopes, Depth, and Test Strategy

Scopes control which stages execute. Depth controls how much detail each stage produces. Test strategy controls how many tests are generated. Together, they adapt the lifecycle to your task — from a comprehensive enterprise feature to a quick bugfix.

This chapter is the detailed routing reference. If you are choosing what kind of workflow to run, start with Workflow Profiles, where the same scopes are explained in user-facing terms.

The 11 Core Scopes

Core ships 11 named scopes. Each scope defines a stage set, a default depth level, and a default Guard Policy value (strict on enterprise, security-patch, and infra; off on express; relaxed on the rest; see Guard Policy for what the value does and how to set it). Plugin installs can add more scopes, and an install can narrow which plugin scopes are visible with aidlc engine plugin select <names>. When a plugins selection disables core (aidlc omitted), the core scope files remain installed but are not valid runtime scopes until core is re-enabled; the Initialization stages still run for every enabled scope.

enterprise

Use when: Building a regulated enterprise feature that requires full audit trail, compliance review, and production-grade operations.

• Stages: All 33
• Default depth: Comprehensive
• Includes: Full compliance, security, and operations stages

feature

Use when: Building a new feature of any size with the full 33-stage lifecycle. Select it explicitly with --scope feature or /aidlc-feature.

• Stages: All 33
• Default depth: Standard
• Includes: All stages, standard artifact detail

mvp

Use when: Building a greenfield minimum viable product. Skips late-stage operations but retains full design and construction.

• Stages: 23 of 33
• Default depth: Standard
• Skips: All 7 Operation stages (deployment pipeline, environment provisioning, deployment execution, observability, incident response, performance validation, feedback) plus Market Research, Team Formation, and Approval Handoff from Ideation (10 skipped, 23 executed)

poc

Use when: Proving feasibility quickly. Skips most Ideation and Inception stages, focuses on getting to code fast.

• Stages: 8 of 33
• Default depth: Minimal
• Skips: Market Research, Feasibility, Team Formation, Mockups, User Stories, most Operation stages

bugfix

Use when: Fixing a specific bug. Streamlined path from intent capture through code generation and testing.

• Stages: 9 of 33
• Default depth: Minimal
• Includes: Deployment Pipeline and Deployment Execution so the verified fix ships
• Skips: Market Research, Feasibility, Team Formation, Mockups, most design and architecture stages, environment provisioning, and broader operational readiness

refactor

Use when: Cleaning up or restructuring existing code without changing functionality.

• Stages: 10 of 33
• Default depth: Minimal
• Includes: Functional Design plus Deployment Pipeline and Deployment Execution
• Skips: Similar to bugfix — focused on code analysis, design, implementation, and deployment through the existing path

infra

Use when: Making infrastructure changes (new environments, CDK/CloudFormation updates, cost optimization).

• Stages: 13 of 33
• Default depth: Standard
• Skips: User-facing stages (stories, mockups, user flows) — focuses on architecture, infrastructure, and deployment

security-patch

Use when: Responding to a CVE or security vulnerability. Fast path through security-relevant stages.

• Stages: 10 of 33
• Default depth: Minimal
• Skips: Market Research, Team Formation, Mockups, non-security design stages

classic

Use when: You want v1-style ceremony: Inception and Construction, with one human approval per stage. Conditional stages adapt to the project at runtime; Operation remains a placeholder. Stage-declared execution modes and support agents are unchanged.

• Stages: 18 of 33
• Default depth: Standard
• Default test strategy: Standard
• Skips: All Ideation stages (1.1-1.7), CI Pipeline (3.7), and all Operation stages (4.1-4.7)
• Keywords: None; selected explicitly or used as the implicit default
• Ceremony: Walking skeleton and summary confirmation 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.

Override ceremonies for an intent with /aidlc --sensors on|off, /aidlc --learnings on|off, or /aidlc --summary-confirmation on|off. The global kill switches AIDLC_DISABLE_SENSORS=1, AIDLC_DISABLE_LEARNINGS=1, and AIDLC_DISABLE_SUMMARY_CONFIRMATION=1 force them off. Approval gates, Plan Approval, human-turn authority, audit, and team write protection still apply. See ceremony customization.

Upgrading an in-flight classic intent

The saved stage plan is preserved: an older classic intent whose Operation stages are recorded as EXECUTE still runs them, and routing, next-stage lookup, and status follow that recorded plan. New classic intents use the smaller grid. Ceremony defaults change immediately when the old intent has no saved ceremony fields: Sensors and Learnings resolve to on, while Summary Confirmation resolves to off from classic. Enable summary confirmation with bun .claude/tools/aidlc-utility.ts config-change --summary-confirmation on (native: aidlc engine config set summary-confirmation on). Saved per-intent ceremony choices remain in effect. Environment kill switches still take precedence.

Classic's reviewer cap also changes immediately: every reviewer-bearing stage runs one advisory pass, and --review adversarial cannot raise that cap (--review none still lowers it). To run the previous classic graph, with CI Pipeline and the Operation stages, change the intent to workshop with aidlc engine scope change --scope workshop; workshop retains the full Inception-through-Operation plan and uses a Minimal test strategy by default. Preserve a production Standard test strategy if needed by adding --test-strategy standard to that scope change.

workshop

Use when: Running a facilitated workshop or training lab with the established full Inception-through-Operation lifecycle and a lighter teaching test floor.

• Stages: 26 of 33
• Default depth: Standard
• Default test strategy: Minimal
• Skips: All Ideation stages (1.1-1.7)
• Keywords: workshop, lab, and training

express

Use when: You want the lightest path from requirements through code and test to a conditional deploy tail, with no design pass or reviewer dispatch.

• Stages: 10 of 33
• Default depth: Minimal
• Review cap: None
• Includes: Initialization, conditional Reverse Engineering, Requirements Analysis, Code Generation, Build and Test, and the conditional Deployment Pipeline, Deployment Execution, and Observability Setup stages
• Skips: Ideation, design, Units Generation, Delivery Planning, CI Pipeline, environment provisioning, and the late operations stages

Scope Routing Table

Authoritative data lives in the .claude/scopes/aidlc-<name>.md files (scope identity), plugin scope files, plus each stage's scopes: frontmatter (membership), compiled into .claude/tools/data/scope-grid.json. The compiled grid contains only scopes enabled by the current plugin selection. Run aidlc engine gen scope-table for the live compiled table (and aidlc engine orchestrate help for the user-facing workflow and scope one-liners).

Scopes differ by an order of magnitude in ceremony: poc runs a narrow single-pass path, while feature runs all 33 stages with 30 gates (32 stages and 29 gates on a new project, where Reverse Engineering is skipped) and five design stages that fan out per Unit of Work in Construction. The scope confirmation line names the effective numbers - stage count, approval-gate count, and any per-unit fan-out - computed from the compiled grid and workspace scan, never estimated. Greenfield work excludes reverse engineering, and scopes that skip units-generation omit the per-unit clause because no Unit DAG exists. You know what you are consenting to before the workflow starts.

The confirmation also lists what the effective policy turns off, including creation flags and environment kill switches. Classic defaults add ; no summary confirmation; opting summary confirmation in removes the clause, because an advisory review cap is not a disabled ceremony. Scopes with every ceremony enabled and no none review cap omit that clause.

Per-project default scope: teams can pre-set the default scope for a project by setting AWS_AIDLC_DEFAULT_SCOPE in .claude/settings.json. See Customization § Per-Project Default Scope.

Stage-by-Scope Matrix

The routing table above gives the counts; this matrix shows exactly which stages execute under each stock scope, so you can see what you will walk through before starting a workflow. A ✓ means the stage is EXECUTE under that scope; an empty cell means SKIP. Stage numbers and names match Phases and Stages.

A ✓ marks static scope membership — it means the stage is included in the scope's plan, not that it will unconditionally execute. CONDITIONAL stages may be skipped at runtime when their condition does not hold (for example, Reverse Engineering only runs for brownfield projects), and pending stages can be reshaped through an approved composer proposal (see the composer). Composed (custom) scopes are not listed here — their grids live in scope-grid.json alongside the stock ones.

Auto-Detection from Freeform Intent

You don't have to specify a scope explicitly. Describe what you want, and the orchestrator detects the appropriate scope from keywords:

/aidlc Build a REST API for inventory management

The engine analyzes your intent against keyword patterns:

Disambiguation rule: Descriptions longer than five words normally receive the compose offer below. An affirmative match for refactor, mvp, minimum viable, poc, proof of concept, or CVE instead proposes the matching scope, regardless of length. For example, "refactor the legacy authentication module to improve maintainability" proposes refactor. Generic words such as fix and deploy alone still receive the compose offer.

The exemption checks every keyword, so "security vulnerability CVE-2026-12345" can identify security-patch even when security matches first. Nearby negation before a keyword, such as "do not refactor" or "not a proof of concept", does not activate the exemption; a later affirmative mention can still match. This is a lexical heuristic, so confirm that the proposed plan fits your intent. Among eligible scopes, the first alphabetical scope wins. Inputs of five words or fewer retain the existing alphabetical keyword matching. Plugin-specific keywords retain the length heuristic until plugins can declare their own keyword specificity.

After a clear keyword match, you get a one-line confirmation naming the MATCHED scope and the ceremony it carries, straight from the compiled grid. On a new project it reads like this; on an existing codebase bugfix also runs Reverse Engineering, so the line says 9 of 33 stages and 6 approval gates:

This looks like "bugfix" work, so I'd run the "bugfix" plan for: "fix login bug" - 8 of 33 stages, 5 approval gates.
Say go ahead, name a different plan, or say "compose" and I'll tailor one to this task.

Confirm to proceed, or reply with a different scope (or compose) to course-correct before the workflow starts.

The Adaptive Composer

The underlying resolver's no-keyword default is classic (overridable with AWS_AIDLC_DEFAULT_SCOPE), which is used by explicit fallback paths and low-context utility calls. In the user-facing cold-start flow, rich prose, no keyword hit, or a keyword buried in a long description enters the compose offer before a workflow is created; it does not silently start Feature. You can also force composition:

/aidlc compose "harden the deployment pipeline and add observability"
/aidlc-compose "same thing, as a typeable shortcut"
/aidlc compose --report sonar.json     # compose from a scan report
/aidlc --new-scope "..."               # force a custom plan even on a stock match

The composer agent reads your task, then estimates five implementation-entropy components - intent ambiguity, codebase structural uncertainty, verification entropy, risk, and unresolved assumptions - and composes the minimum viable workflow: the least sufficient EXECUTE/SKIP grid that still produces every artifact the outcome depends on. Structural estimates ground in CodeKB MCP call-graph and component analysis when a CodeKB server is configured and indexed (an optional external tool; nothing ships with AI-DLC); otherwise the composer falls back to the bounded workspace scan (brownfield/greenfield, languages). The proposal you see at the gate carries the score breakdown (each component with a LOW/MED/HIGH band and its evidence), an advisory composite, and a per-stage decision table with a reason for every EXECUTE and SKIP. You approve, edit, or reject; nothing is written and no workflow starts before an explicit approval. A plan applies to the piece of work it was approved for, so composing never adds to your scope list unless you ask. On approve:

• If the proposal MATCHED a stock scope, AI-DLC creates the workflow with that scope directly (a scan report full of code-level findings usually routes to bugfix or security-patch this way).
• For a CUSTOM plan, AI-DLC creates the workflow on the nearest suitable stock scope (one with no walking skeleton and no test strategy other than the plan's depth, so the plan runs as the gate showed it) with the plan's own stage changes and depth, in the same turn, and writes no scope file. The work's state records Plan: custom, based on <scope>, and /aidlc status shows it. The gate for a custom plan has a second approval, Approve and save as scope: it asks for a name (the composer suggests one) and keeps the plan as a reusable scope as well.
• To keep a plan later, ask in plain words ("save this plan as quick-fix"). AI-DLC runs aidlc engine scope save --name quick-fix, which writes the running work's current plan, with its settings and Guard Policy, as a scope, and names the command that reuses it (/aidlc --scope quick-fix "..."). A saved scope resolves like any stock scope, survives a graph recompile and an engine reinstall, and travels between harnesses (see Where a saved scope is stored).
• Every front/report proposal carries a nonblank creationDescription. When the compose request included task text, it is that text verbatim; report-only and task-less proposals derive it from the approved findings/plan. The same-turn creation passes it after the literal -- delimiter as one shell-safe argv value (POSIX single-quoted when rendered in a shell), so the state Project field and intent-record slug preserve descriptions that contain shell metacharacters or begin with a flag. A compose approval cannot continue with only a scope and no description.

Settings at the gate: besides the stage grid, a front/report proposal names the plan's Guard Policy and its four scope settings (sensors, learnings, summary_confirmation, and review_cap), each group on its own row with a one-line reason. That lets a composed plan trim the ceremony inside its stages as well as the stages themselves: a small, well-understood fix might run with sensors and learnings off and reviews capped at advisory. A matched proposal starts from the stock scope's values; either way, values that differ from the stock scope the plan runs on apply to this piece of work only, with no new scope file, and a plan you save stores them in its frontmatter. Ask for any change before approving and it is made; lowering a stock plan's Guard Policy makes it a custom plan, on a stock scope that carries that value. No setting removes an approval gate. Mid-workflow, ask in plain words ("turn sensors off", "give this full reviews") and the change is applied to the running work without a gate (see Ceremony Switches); a review level set for the piece of work replaces its scope's ceiling, so stronger reviews change no stages, and setting the scope's own level returns to its normal reviews. A setting the composer suggests on its own during a mid-workflow compose appears on the gate and applies only if you approve it. Turning summary confirmation off mid-workflow is the one change you make yourself: asked in plain words or approved on the gate, the agent asks you to type /aidlc config set summary-confirmation off.

CodeKB grounding (optional): CodeKB is an external MCP server that serves pre-computed structural analysis of a codebase (call graphs, component inventories, cross-package coupling). AI-DLC does not ship or require it - without it the composer scores structure from the bounded workspace scan, which is the normal path. When you do connect one, the composer uses it as the sole structural evidence source and cites it in the proposal (method: codekb). How to connect it depends on the harness: on Claude Code add the server to your project's .mcp.json (subagents inherit session MCP servers); on Codex add an mcp_servers entry to your config.toml; on opencode add it to your opencode config; on Copilot CLI add it to ~/.copilot/mcp-config.json, and in VS Code to .vscode/mcp.json. On Kiro CLI the shipped composer config sets includeMcpJson: true, so connecting CodeKB means adding it to .kiro/settings/mcp.json without "disabled": true and adding its @<server> grant to the composer agent's tools; Kiro IDE remains fallback-only. Do not confuse CodeKB with the framework's own "codekb" directory (aidlc/spaces/<space>/codekb/) - that is the local artifact store the Reverse Engineering stage writes, unrelated to the MCP server. Note that with CodeKB evidence the composer may propose skipping Reverse Engineering; the proposal must disclose that downstream stages then run without that local store, and you decide at the gate.

Keyword hygiene: saved scopes ship with keywords: [], so a saved plan never participates in keyword auto-detection. Making one inferable for future prompts is an explicit choice when you save it (scope save --keywords <word,...>, single words checked against the keywords other scopes already claim), never a side effect.

In-flight recompose: mid-workflow, /aidlc compose proposes re-shaping the PENDING stages of the running workflow - skip what you no longer need, add back a pending stage you realize you need. The composer re-estimates the entropy components from what completed stages actually resolved, so each proposed flip names the evidence that moved the score ("feasibility settled the integration questions - risk re-scores MED"). Flips apply only to pending, ahead-of-cursor stages (completed and in-progress stages are frozen), are strict-validated so no remaining stage is starved of a required input, and land through the deterministic recompose verb under the audit lock with a RECOMPOSED audit event. When one approval covers stage changes and settings, the same recompose applies both in one write, so the plan is never left half-changed; summary confirmation off stays your own switch to type. The first EXECUTE stage of Construction cannot be flipped by recompose. This protects the stage-routing anchor; it does not make a first design-stage review proof of a working integrated skeleton.

You do not need the literal verb: plain chat like "can we skip market research? we already know this market" is recognized mid-workflow as a reshape request and routed through the same gate and the same recompose verb. When you name the stages yourself ("drop market-research and team-formation"), the conductor may present the gate directly without dispatching the composer agent - the approval gate and the validation are identical either way. On the non-Claude harnesses the literal /aidlc compose "<request>" verb remains the documented reliable path.

Where a saved scope is stored

A stock scope belongs to the engine: it is regenerated into the harness tree on every build. A scope you save from a composed plan is yours: nothing in the engine produces it, so it is stored with the rest of your work:

Two things follow, both of which used to fail:

• An engine reinstall cannot lose the scope. Replacing the harness tree discards the projection; the next graph compile rebuilds it from the record. This matters for the copy channel in particular, where scope-grid.json is a generated file that any copy-over replaces.
• A saved scope travels between harnesses. The record lives in the shared, tool-neutral aidlc/ tree, so a collaborator working in .kiro/ or .codex/ resolves a scope you saved in .claude/ after one graph compile.

If you have a composed scope from an earlier release it lives only in the harness tree; the first graph compile after upgrading writes its record for you, once. From then on the record is the source.

The record's shape

Everything above the sentinel comment is yours to edit — frontmatter and prose alike, including your own Markdown headings and fenced code. Everything between the sentinels is generated. Treat the region as the end of the file: write your prose above it, because that is the part graph compile projects into the harness tree. Anything you append below the END sentinel stays in the record — nothing rewrites a record that already exists — but it is not carried into the harness scope file:

---
name: my-lean-feature
depth: Standard
keywords: []
---

# my-lean-feature

Whatever you want to write, including a "## Stage Grid" heading of your own.

<!-- BEGIN aidlc composed-scope-grid: generated by `aidlc engine graph compile` — reshape the plan through /aidlc compose, not by editing here -->

```json
{ "stages": { "intent-capture": "EXECUTE", "units-generation": "SKIP" } }
```

<!-- END aidlc composed-scope-grid -->

Reshape the plan with /aidlc compose, not by editing the region — a hand-edited grid is not validated against the stage graph, so it can starve a stage of an input it requires.

Editing the part above the sentinel is fine, but note that graph compile writes the harness scope file only when it is missing; it does not overwrite one you have edited. So if you change depth or description in the record, delete <harness>/scopes/aidlc-<name>.md and recompile to re-project it. The plan itself always comes from the record, so this only affects descriptive fields.

When a record is unreadable

A record missing its frontmatter, its name, or its generated grid region stops graph compile and aidlc update with the file path and the required edit named — it is committed work, so it is never silently skipped. Repair the named file, or delete it: if the harness projection is still present, the next compile back-fills a fresh record from it. /aidlc --doctor's Composed scope durability check reports a scope file with no grid column, a record that has not been projected yet, and a runnable workflow whose scope no longer resolves.

The 3 Depth Levels

Depth controls the detail level of artifacts produced at each stage. The scope sets a default depth, but you can override it.

How depth affects stages

At each stage, the agent adjusts its output based on the active depth:

• Minimal: 1-2 page artifact, key decisions only, skip optional sections
• Standard: Complete artifact, all required sections, concise rationale
• Comprehensive: Expanded artifact, optional sections included, detailed justification, compliance cross-references

Overriding depth

You can change the depth at three points:

1. Via the --depth CLI flag — override depth at invocation time:

   /aidlc --depth comprehensive
   /aidlc --scope bugfix --depth standard
   /aidlc --stage code-generation --depth minimal
   

2. At scope confirmation — when the orchestrator confirms the detected scope, reply with --depth <level> instead of just confirming
3. At any approval gate — request a different depth level as part of your feedback

The first completion message in each session reminds you:

**Project depth**: Standard — depth adapts artifact detail.
**Test strategy**: Standard — test strategy controls test volume.
You can request different depth or test strategy at any approval gate.

Specifying Scope Directly

Explicit scope

/aidlc feature
/aidlc bugfix
/aidlc enterprise

Scope with description

/aidlc bugfix Fix the login timeout issue
/aidlc poc Build a quick prototype for the search feature

Override scope with utility command

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

The --scope flag is composable with --stage, --phase, and --depth for jump operations.

Override depth

/aidlc --depth minimal
/aidlc --scope bugfix --depth comprehensive
/aidlc --scope enterprise --depth standard --stage code-generation

The --depth flag overrides the scope's default depth level. Valid values: minimal, standard, comprehensive (case-insensitive).

Override test strategy

/aidlc --test-strategy minimal
/aidlc --depth standard --test-strategy minimal

The --test-strategy flag overrides the test strategy independently of depth. See the full explanation in The 3 Test Strategy Levels below.

The 3 Test Strategy Levels

Test strategy controls how many tests are generated and which test types are included. It is independent of depth — depth controls artifact detail (documents, diagrams, questions), while test strategy controls test volume only. This separation lets you run a full Standard-depth workflow with Minimal testing when speed matters more than test coverage.

Minimal — Nyquist model

Inspired by the Nyquist rate from signal processing: the minimum sampling frequency needed to reconstruct a signal. Minimal test strategy generates the minimum tests needed to verify every requirement — no more, no less.

• 1 test per identified requirement (requirement-driven, not component-driven)
• Happy-path floor: every component gets at least 1 happy-path unit test, even if no requirement maps to it
• Unit tests by default. A bugfix/security-patch targeted regression may use integration or E2E when that is the narrowest level that reproduces the defect; unrelated test volume remains Minimal.
• ~5-15 tests total for a typical project
• Soft guideline — the agent can exceed when safety-critical context demands it

Best for: Workshops, training sessions, proofs of concept, quick bugfixes — any context where you want to verify correctness without investing in a full test suite.

Standard — per-component model

Balanced test coverage that validates boundaries between components.

• 5-8 tests per component
• Unit + integration tests (key boundaries between components)
• E2E, performance, and security tests only if NFR requirements explicitly call for them
• Test pyramid proportions: ~75% unit / ~20% integration / ~5% E2E
• Soft guideline

Best for: Most features and MVPs — good coverage without over-investing in testing.

Comprehensive — full coverage model

Thorough test coverage across all test types.

• 10-15 tests per component
• All test types: unit + integration + E2E + performance (if NFRs exist) + security (if NFRs exist)
• Test pyramid proportions apply across all types
• Soft guideline

Best for: Enterprise features, regulated systems, any context requiring an audit trail of test coverage.

How test strategy defaults work

Most core scopes inherit test strategy from depth. classic therefore uses the production Standard test floor and express uses the requirement-driven Minimal floor. workshop retains its explicit Minimal override at Standard depth for teaching sessions. You can always override with --test-strategy.

Overriding test strategy

You can change the test strategy at three points:

1. Via the --test-strategy CLI flag — override at invocation time:

   /aidlc --test-strategy minimal
   /aidlc --depth standard --test-strategy minimal
   /aidlc --scope bugfix --test-strategy comprehensive
   

2. Mid-workflow — change test strategy on an active workflow:

   /aidlc --test-strategy comprehensive
   

3. At any approval gate — request a different test strategy as part of your feedback

Common depth + test strategy combinations

Choosing the Right Scope

When in doubt, start with feature for full-lifecycle coverage; choose classic for the v1-style Inception and Construction experience without Ideation or Operation.

Next Steps

• Phases and Stages — what each stage does
• Agents — which agents participate in which scopes
• Skills and Runner Commands — the one-word /aidlc-<scope> runners for bugfix, express, feature, mvp, and security-patch
• CLI Commands — full command reference
• Glossary — terminology reference