Scopes

A scope is the dial that decides which of the framework's 33 stages run for a given kind of work, and which sit out. A bugfix doesn't need market research or environment provisioning, but it still runs the deployment pipeline and execution stages; a regulated enterprise feature needs the full lifecycle. Rather than asking the user to hand-pick stages every time, AI-DLC ships eleven named scopes — each one a curated EXECUTE/SKIP verdict over the full stage set, paired with workflow defaults such as depth, test strategy, and an optional review ceiling. Pick the scope and the rest cascades.

For a harness engineer, a scope is pure data, authored the same way every other primitive is — as a file. It is two halves: one core/scopes/aidlc-<name>.md file (its identity, routing metadata, and workflow defaults) plus a per-stage membership tag (each stage's frontmatter scopes: list naming the scopes it runs under). Adding or tuning a scope requires no TypeScript. This chapter walks the workflow: what a scope is made of, how to add a team scope, how to tune an existing one, and what the tooling checks for you versus what it leaves to you.

For the full eleven-scope catalog with use cases and the routing table users read, see Scopes, Depth, and Test Strategy in the User Guide. This chapter is the authoring side of that same data.

What a scope is made of

A scope is authored in two places, and the split is the whole idea: the scope's identity lives in its own file, and its membership (which stages run under it) lives transposed onto the stages.

1. The scope file — core/scopes/aidlc-<name>.md. One file per scope, mirroring core/sensors/. The feature scope's frontmatter looks like this:

---
name: feature
depth: Standard
keywords: []
description: Full lifecycle for new features, practical depth
skeleton: on
runner: true
guard_policy: off
sensors: on
learnings: on
summary_confirmation: on
plan_approval: on
collaborators: off
---

# feature scope

The full-lifecycle scope for new feature work at practical depth. ...

The scope frontmatter fields are:

The loader rejects duplicate scope name values across files and names both files in the error. Invalid ceremony values are rejected with the file, key, and the two allowed values. Resolution is kill switch (1) → valid intent line → scope default → on. Every shipped scope declares all five ceremony keys explicitly rather than leaning on the default: classic declares sensors, learnings, and plan approval on and summary confirmation off, bugfix declares sensors and plan approval on and learnings and summary confirmation off, express declares all four of those off, poc declares plan approval off and the other three on, and the other seven declare those four on; collaborators is on only on enterprise and off on every other scope. Classic's gated flow also caps reviews to one advisory pass and disables walking-skeleton ceremony, while explicit autonomy keeps the single pre-merge review.

Express turns sensors, learnings, and summary confirmation off; override them per intent with /aidlc --sensors on|off, /aidlc --learnings on|off, or /aidlc --summary-confirmation on|off.

Freeform default

freeform_default: true lets an install nominate the scope used when the internal classic default is unavailable after plugin selection. The nomination is checked before the sole-enabled-plugin fallback, so a plugin with several scopes can choose its lean default instead of accepting the alphabetically first scope.

At most one enabled scope may declare freeform_default: true. Graph compilation fails and names every claimant when the selected core/plugin set contains more than one. Claims on disabled plugins do not conflict until those plugins are enabled together. The field does not repair explicit typos: an unknown AWS_AIDLC_DEFAULT_SCOPE value still fails validation.

Walking-skeleton default

The optional skeleton: field controls the scope-dependent walking-skeleton stance. skeleton: on means that when the team's ## Walking Skeleton practices resolve to scope-dependent, Construction opens with the walking-skeleton ceremony for this scope. skeleton: off means the first Bolt runs as a regular Bolt. Absence defaults to off, so composed/runtime-approved scopes and plugin scopes do not conjure a skeleton Bolt unless they opt in explicitly.

Scopes for existing code

The optional existing_code: true field marks a scope that changes code that already exists (bugfix, refactor, and security-patch ship with it). A plan the composer tailors for a new project does not run on such a scope when a scope meant for new work fits, so new work is not recorded as a fix; and creating work on one in a folder that scans as a new project, which drops its Reverse Engineering, prints a note that the scope usually targets existing code. Absence means the scope suits new work too.

Guard Policy default

The optional guard_policy: field is the value a new intent on this scope starts with, written to its state file at creation as - **Guard Policy**: <value> (from scope <name>). The human can change it for that one intent by typing /aidlc --guard-policy <value> or by asking in their own words; either way the agent runs the setter, and lowering it to relaxed or off takes a message from the person since the last decision. An older intent without this line remains strict until explicitly set, while the next new intent starts from the scope default again. To hold a value for everyone on the repo, do not edit eleven scope files: declare it once in memory (## Guard Policy with Mode: strict in aidlc/spaces/<space>/memory/org.md, team.md, or project.md). A memory strict wins over every scope default and refuses chat or flag flips by naming the file. A memory relaxed or off (the narrowest layer that declares one) replaces a value that came from the scope, while a value the person set for one intent stays; an absent or empty section changes nothing. The validation error for anything other than the three values names the file and the allowed values; the per-intent command repairs an invalid state line.

A scope word is a product statement about how much ceremony this kind of work deserves. It is not the only control: a human can lower one of the four switchable fences for one piece of work with /aidlc config set guard.<fence> off, which writes the Guards Off state line and one GUARD_DISABLED audit row. Setting on can raise a policy-lowered fence, writing Guards On and GUARD_RESTORED. Setting the Guard Policy word clears the line that goes against it: off clears Guards On, strict clears Guards Off, and relaxed clears neither. Human presence is the key holder and has no per-work switch; only AIDLC_SKIP_HUMAN_PRESENCE_GUARD=1 lowers it. Environment kill switches remain the machine-wide override. Declare off in a scope only when every piece of work on it should run with those four fences lowered, as every shipped scope except enterprise does. To spare people a fence they meet only occasionally, use the per-work switch instead; the next piece of work starts from its own scope default.

change_control: is the retired spelling of this key. It is read for one release and never written; a scope file that names both keys with the same value is accepted, and one that names them with different values is rejected naming the file and both values.

2. The membership tag — each stage's scopes: frontmatter. A stage names the scopes it runs under in its own frontmatter, in core/aidlc-common/stages/<phase>/<slug>.md:

scopes:
  - enterprise
  - feature
  - mvp

A stage that names a scope is EXECUTE under it; absence is SKIP. Packaging transposes every stage's scopes: list into the compiled EXECUTE/SKIP grid at <harness-dir>/tools/data/scope-grid.json. The grid is an ignored generated projection that the runtime reads; you never hand-edit or commit it. The 3 initialization stages name every scope (they always run).

That transpose is the mechanism for authored scopes, which is what this chapter is about. A scope saved at runtime from a composed plan (scope save) has no stage declaring it, so it cannot be transposed: its durable definition lives in the user's own tree at aidlc/scopes/<name>.md and compile projects it into the harness grid. You do not author those, and they are not part of this workflow; see Where a saved scope is stored. A composed plan the person does not save writes no scope at all: it runs on a stock scope with its own stage changes recorded in that piece of work's state.

The one judgment call worth understanding is the relationship between depth and testStrategy. Depth controls how much detail each stage's artifacts carry; test strategy controls how many tests get generated. They're independent on purpose. Most shipped scopes leave testStrategy off so it inherits from depth — classic is Standard/Standard and express is Minimal/Minimal. workshop demonstrates the explicit split with Standard depth and Minimal testing. If your scope wants a split, declare both. For what each level means, see The 3 Depth Levels and The 3 Test Strategy Levels in the User Guide.

The exhaustive field-by-field contract lives in Contributing: Adding a Scope in the Developer Reference. keywords are only hints the agent reads when it proposes a plan; no tool matches them against the request. This chapter summarizes the decisions; that section is the normative spec.

How scopes relate to stages

A scope and a stage point at each other from opposite ends, and it helps to hold both directions in view.

A stage declares its own identity — its phase, its lead agent, the artifacts it consumes and produces, and now the scopes it runs under (its scopes: list). A scope declares its identity, routing metadata, and workflow defaults in its own .md file, with no per-stage membership inside it; membership lives on the stages. The binding between them is the scope name. When you add a new stage (see Adding a Stage), you put the scope membership on that stage — its scopes: list names every scope that should run it. A stage that names no scope is SKIP everywhere. The transpose at compile turns those per-stage lists into the grid, so membership is authored once, on the stage, rather than re-declared in eleven separate scope blocks.

The one exception is a plugin scope's include_stages, which names stages of the base plugin it builds on: files that plugin cannot edit.

That separation is the same data-versus-code line the rest of this guide rests on (see Harness Engineer Guide). The scope file is data about identity; the stage's scopes: list is data about membership; the compiled grid is the transpose of the two.

Adding a team scope

Suppose your team wants a hotfix scope — leaner than bugfix, for the urgent production patch where you want a regression test and a deploy, nothing else. The change is a new scope file, a scopes: tag on each stage that should run, and regenerated local projections. Mirror the discipline below; the verification steps and the full command lines are in Contributing § Adding a Scope.

Steps

1. Drop core/scopes/aidlc-hotfix.md. Copy aidlc-bugfix.md (the closest existing scope) and edit the frontmatter: set name: hotfix, pick depth, add keywords as hints the agent reads when proposing a plan for freeform text ([hotfix, urgent]), a description for the help text, skeleton: on|off for the scope-dependent Construction ceremony default, keep existing_code: true from aidlc-bugfix.md, since a hotfix changes code that already exists, freeform_default: true only if this is the selected install's unique fallback nomination, testStrategy only if it should diverge from depth, and review_cap only if the scope should lower stage reviews. Write a short prose body explaining the intent. Set sensors, learnings, and summary_confirmation to off only for ceremonies the scope should omit; absent keys stay on. Intent overrides and global kill switches use the table above.

2. Tag the stages that should run under hotfix. In each stage you want EXECUTE (under core/aidlc-common/stages/<phase>/), add hotfix to its frontmatter scopes: list. A stage you don't tag is SKIP for the scope. The 3 initialization stages must include it (they always run).

3. Regenerate. Run bun scripts/package.ts to rebuild the ignored harness projections, including scope-grid.json and the compiled scope table. Run bun scripts/package.ts --check to confirm two independent source-only builds are byte-identical.

4. Verify the scope resolves and is accepted. Run /aidlc --doctor. Then confirm an init under the new scope produces a state file with the right Scope: line, and that it's accepted as an env default and as a mid-workflow --scope change.

5. Check the plan's hints (only if you populated keywords; the agent reads them in the plan proposal step, no tool matches them). Confirm the plan proposal step for a freeform phrase lists your scope with those hints, so the agent can propose it.

6. Update the scope-aware docs and add a routing test. Several docs enumerate scopes by hand — the User Guide's scope reference and routing table, the customization chapter's valid-values list, and the orchestrator reference's scope-to-stage mapping. Update them in the same change. If your scope skips stages in a pattern no existing scope uses, add a workflow test modeled on the existing per-scope tests.

7. (Optional) Generate a typeable runner. A scope is fully usable via /aidlc --scope <name> the moment its file lands; no runner is needed. If you want a one-word command (/aidlc-hotfix), add runner: true to the scope frontmatter and run aidlc engine gen runner-scopes; aidlc engine gen runner-scopes --all emits skills/aidlc-<scope>/SKILL.md for every scope file regardless of that flag. Each runner is a thin shell that drives aidlc-orchestrate next --scope <name> to done with the scope baked in, plus a "Starting unrelated new work?" section carrying the same recognize, offer (AskUserQuestion, never auto-create), and next --new-intent --scope <name> guidance the /aidlc orchestrator has. The runner packages an already-runnable scope, and the scope file is its definition. It carries no hooks: block: the deterministic spine (audit, sensors, rebuild-stage-graph, state validation) is registered project-wide in settings.json, so every runner inherits it for free. Re-run the generator (or aidlc engine gen runner-scopes --check) whenever you add or rename a scope file.

What validates automatically

This implementation derives the valid-scope list from .claude/scopes/*.md presence at runtime through validScopes(), so a lot falls into place the moment the file lands:

• The scope is valid everywhere at once — init, --scope change, env-default resolution, and doctor all consult the same helper, so none of them needs a code edit.
• Error messages list your scope in alphabetical order with no change.
• If you gave it keywords, they appear as hints in the plan proposal step the agent reads for freeform /aidlc <text> as soon as the frontmatter list is populated — no SKILL.md prose edit, just the table regeneration.
• Packaging always derives the grid from the current stage YAML, so stale local generated bytes are not release inputs.

What does NOT validate automatically

• A scopes: tag with a typo'd scope name still parses. A stage frontmatter that names hotfx instead of hotfix compiles cleanly — it just produces a grid column nobody asks for. The catch is that validScopes() derives from the .md files, so a scope with no file is rejected at invocation; but a mistyped tag on a stage silently drops that stage from the real scope. /aidlc --doctor and a per-scope test are the guardrails.
• A stale local projection can mislead manual inspection. If you edit a stage's scopes: and keep using an old ignored dist/ tree, that local runtime still contains the old grid. Regenerate before local runtime checks; CI and release assembly always rebuild from source.
• Per-scope phase-sequence coverage. The shipped phase-sequence test iterates a hardcoded list of the known scope names; a new scope isn't exercised by it until you extend that list. Add your scope to it in the same change.
• The hand-maintained docs. The User Guide's stage-by-scope matrix and scope routing table are checked against the compiled grid (t244-scope-matrix-doc-sync), so a new scope fails that test until its column and row are there. The rest is prose nothing checks, such as the customization chapter's valid-values list and the scope descriptions; keep it in step with the scope files yourself.

Tuning an existing scope

Tuning is a smaller edit, but it lands on the stage, not the scope. Two changes come up often:

• Flip a stage in or out. Add or remove the scope name from a stage's scopes: list. This is how you'd, say, add mvp to observability-setup's scopes: because your team always wires monitoring even for a first cut. One tag, then regenerate with bun scripts/package.ts and run --doctor.
• Change a default depth, test strategy, or review ceiling. Adjust depth, add/remove testStrategy, or add/remove review_cap in the scope's core/scopes/aidlc-<name>.md frontmatter. The first two recalibrate artifact and test volume; review_cap lowers stage review classes to adversarial, advisory, or none without ever raising them. Because each scope carries its own defaults, the change applies to every workflow that selects the scope. Per-run --depth, --test-strategy, and --review can lower the corresponding behavior further.
• Change a ceremony default. Set sensors, learnings, summary_confirmation, plan_approval, or collaborators to on or off in the scope file. Existing intent lines retain their choice; a scope change refreshes scope-sourced lines but preserves per-intent overrides. Apart from plan_approval: off, which builds each code plan without asking, and collaborators: off, which runs every stage lead-only, no ceremony switch removes stage approval, human-turn authority, audit, team write protection, or the reviewer.

Either way, the regenerate-and-doctor pair from step 3 above applies. The edit is small; the verification is the same.

A note on layering: tuning the shipped scopes edits framework-shipped files directly — a stage's scopes: tag or a shipped core/scopes/aidlc-*.md. That's legitimate for a fork that wants different defaults, but be aware you're changing files that carry the aidlc- lineage and a framework upgrade may want to reconcile them. Adding a net-new scope file alongside the shipped eleven is the cleaner path when you want a team-specific behavior without touching the defaults everyone else relies on.

Next

Rules and the Learning Loop — author the standing decisions that travel into every workflow, and let the loop promote a one-time correction into a durable rule.

For the normative scope-shape and runner contract — how a .claude/scopes/ file drives which stages a workflow visits, and how the generator turns it into a typeable /aidlc-<scope> skill — see Skill System §5 (scope shape) and §4 (runners) in the Developer Reference.