Glossary
Canonical definitions for AI-DLC terminology. All documentation in the User Guide and Developer Reference uses these terms consistently.
| Term | Definition |
|---|---|
| Agent | One of the 14 shipped personas: 11 domain experts, 2 review-only agents, and the adaptive-workflows composer. The conductor activates each for its specialized stage, review, or composition role. |
| Approval gate | An interactive checkpoint at the end of each stage where you choose to approve the work, request changes, or (after 3 revisions) accept as-is. Initialization stages skip approval gates. |
| Autonomy mode | The setting recorded in aidlc-state.md (Construction Autonomy Mode) after the walking-skeleton ladder prompt. Either autonomous (subsequent Bolts run without gates) or gated (each Bolt asks for approval). Defaults to unset before the prompt. |
| Bolt | The unit of Construction execution: one pass through stages 3.1–3.5 for a Unit (or small group of dependency-linked Units). Stages 3.6 (Build and Test) and 3.7 (CI Pipeline) run once after all Bolts complete, not per-Bolt. The first Bolt in Construction is the walking skeleton. See also: [parallel batch], [walking skeleton], [ladder prompt]. |
| Artifact | A versioned markdown document produced by a stage and stored in the intent's record dir (aidlc/spaces/<space>/intents/<YYMMDD>-<label>/). Examples: requirements.md, code-summary.md, initiative-brief.md. |
| Audit trail | The append-only event log in the intent's record dir at audit/, written as per-clone shards (<host>-<clone>.md) that readers glob and merge by timestamp. Records 74 event types with ISO timestamps for full traceability from intent to production. |
| CLI tool | An external command-line utility required by this implementation (bun is the only runtime prerequisite). Not to be confused with Claude Code tools. |
| Claude Code tool | A built-in Claude Code capability such as Read, Write, Edit, Bash, Glob, Grep, Task, or AskUserQuestion. Agents inherit the full session toolset by default; an optional tools: allowlist can narrow it, and disallowedTools: Task is the one shipped restriction. |
| Codex | The OpenAI Codex CLI harness — one of AI-DLC's harness distributions today, generated from core/ + harness/codex/ into dist/codex/. Invoked with $aidlc. See AI-DLC on Codex CLI. |
| Command | A user-facing invocation of AI-DLC. You type /aidlc followed by a scope, flag, or freeform description. Internally, /aidlc maps to a Claude Code skill. |
| Compaction | Claude Code's automatic process of summarizing earlier conversation context when the context window fills up. This implementation preserves state across compaction via aidlc-state.md and .aidlc-recovery.md. |
| Conductor | The /aidlc session itself (SKILL.md), running a thin forwarding loop: it calls the Engine for the next move, carries it out (running a stage, asking you a question, fanning out a swarm), reports the outcome, and repeats. It owns execution quality, not routing. See Engine and Skill System. |
| Control loop | The feedforward/feedback pairing of Rules (standing decisions applied before work) and Sensors (deterministic checks fired on outputs) that steers and verifies a stage. (Distinct from a Harness, the CLI distribution sense; the two were once both called "harness".) |
| Core | The hand-authored, harness-neutral source of truth at core/ — the engine, stages, agents, rules, scopes, sensors, knowledge, hooks, and session skills. Every harness distribution is generated from it; you edit here, never in dist/. |
| Depth | One of three detail levels (Minimal, Standard, Comprehensive) that controls how much detail each stage produces. Scopes have default depths; you can override at any approval gate. See Scopes, Depth, and Test Strategy. |
| Directive | The typed instruction the Engine emits on each next (e.g. run-stage, ask, print, done, invoke-swarm) telling the Conductor exactly what to do next. See Engine and Skill System. |
| Distribution | A generated, committed, drift-guarded dist/<harness>/ tree for one harness (dist/claude/, dist/kiro/, dist/kiro-ide/, dist/codex/, or dist/opencode/). Users copy it into their project; maintainers never hand-edit it. Produced from the Core by the Packager. |
| Engine | The deterministic orchestration tool (aidlc-orchestrate.ts, with exactly three subcommands: next, report, and park) that owns all between-stage routing — scope resolution, stage sequencing, jumps, resume, gate status — and emits a typed Directive the Conductor acts on. See Engine and Skill System. |
| External tool | A third-party tool or service used by a stage (e.g., AWS CLI, Maven, npm). Distinguished from Claude Code tools. |
| Guardrail | The body sections inside a Rule file (## Forbidden, ## Mandated, and the phase-rule guardrail headings) that express prescriptive behavioural constraints. The container is a Rule; "guardrail" names the prescriptive content within it. See Rule. |
| Harness | A CLI distribution of the AI-DLC core — one capable command-line agent that the harness-neutral Core is rendered onto. The set is open and growable (today: Claude Code, Kiro CLI, Kiro IDE, Codex CLI, opencode). Note — "harness" carries four senses in this repo, by context: (1) this canonical CLI-distribution sense; (2) the rule+sensor control loop (older usage, now renamed — see Control loop); (3) the harness/<name>/ source-surface directory; (4) the tests/harness/ test-helper directory. Only sense 1 is "a harness" in user docs. |
| Hook | A TypeScript script that Claude Code runs automatically in response to events. This implementation uses 13 hooks, all registered project-wide in settings.json: the workflow spine (audit logging, sensor dispatch, runtime-graph compile, statusline sync, state validation on compaction, subagent tracking, loop enforcement on turn-end) plus session lifecycle, human-turn mint, state-transition and reviewer-scope guards, and the statusline command. Each self-gates, no-opping when no workflow is active. |
| Inline execution | The default execution mode where the orchestrator loads an agent persona and executes the stage directly in conversation. Supports real-time user interaction. |
| Intent | A unit of work tracked as a row in the space's intents.json registry ({uuid, slug, dirName, scope, repos, status}), with its own [Record dir] at aidlc/spaces/<space>/intents/<YYMMDD>-<label>/. The <YYMMDD> is a compact UTC date prefix (e.g. 260624 = 2026-06-24) so records sort chronologically, and <label> is a short kebab-case essence of the request; a same-day same-label collision resolves with a numeric counter (-2, -3, …). The canonical, collision-proof id is the time-ordered UUIDv7 stored in the registry row, not the dir suffix. The engine auto-births the first intent on your first /aidlc; the active-intent pointer selects the current one. See Space, Record dir. |
| Kiro | The Kiro harness — one of AI-DLC's harness distributions today, generated from core/ into dist/kiro/ (CLI) and dist/kiro-ide/ (IDE), with the AIDLC method read from aidlc/spaces/<active-space>/memory/ via Kiro's agent resources glob. Invoked with /aidlc. See Running AI-DLC on Kiro IDE and Running AI-DLC on Kiro CLI. |
| Knowledge | Reference material loaded by agents at stage start. Two tiers: methodology knowledge (ships with the framework in .claude/knowledge/) and team knowledge (user-managed, space-level domain knowledge at aidlc/spaces/<space>/knowledge/ — free-form, empty at bootstrap, shared across every intent in the space). |
| Ladder prompt | The single prompt shown at the end of the walking-skeleton Bolt asking you to choose "continue autonomously" or "gate every Bolt". Your choice is recorded as the autonomy mode and governs all remaining Bolts. |
| Learning loop | The v0.5.0 mechanism that turns in-stage corrections into durable practices and Sensors. During a stage the orchestrator records observations in memory.md; at the approval gate it surfaces them, you confirm which to keep, and each confirmed learning is written as a practice in aidlc/spaces/<active-space>/memory/project.md (one-click promote to team.md) — or scaffolds a new Sensor — so it applies on the next workflow. See Rules and the Learning Loop. |
| Lifecycle | The AI-DLC methodology as a whole: the AI-Driven Development Life Cycle. A single execution of the methodology is a workflow. |
| Manifest | A harness's harness/<name>/manifest.ts — the declarative contract telling the Packager how to project the Core into that harness's Distribution (dir map, rules rename, authored files, the optional emit plugin). Adding a harness is mostly writing one manifest. |
| MCP server | An external tool server declared in .mcp.json at the project root (beside .claude/) and provisioned to the Claude Code session. This implementation ships five: context7 plus the four AWS servers (aws-mcp, aws-pricing, aws-iac, aws-serverless). Every agent inherits all session MCP servers — there is no per-agent grant; an agent is prevented from using one by narrowing its tools: allowlist to specific mcp__<server>__<tool> ids. A server you have no credentials for is simply unavailable and never blocks a workflow. See Harness Primitives Mapping — MCP Servers and Getting Started. |
| memory.md | The per-stage observation diary at <record>/<phase>/<stage>/memory.md (under the intent's record dir), auto-created at stage start and maintained by the orchestrator (never hand-edited). Records Interpretations, Deviations, Tradeoffs, and Open questions; it is the input the learning loop reads at the approval gate. |
| Mob execution | A dispatched mesh (mode: mob) in bounded rounds. The lead drafts, mutually blind collaborators write contribution files in parallel, the lead integrates, and unresolved judgment calls may go to the human. User Stories (2.4) is the shipped mob. |
| Multi-repo intent | An intent whose work spans more than one sibling code repo. The repo set is captured at birth — explicitly via --repos a,b or by sibling auto-discovery (every immediate child of the workspace root holding a .git) — and stored in the intent's intents.json row as repos. Construction anchors each git op to a specific repo via --repo <name>; an intent with no recorded repos is the legacy single-repo case (git runs in the project dir). See Artifacts Reference. |
| opencode | The opencode harness (opencode.ai) — one of AI-DLC's harness distributions today, generated from core/ + harness/opencode/ into dist/opencode/. The engine tree ships at .aidlc/ (opencode auto-imports .opencode/tools/*.ts as custom tools, so the engine cannot live there); .opencode/ carries only the native shell (subagents, the /aidlc command, the hook-adapter plugin), and the AIDLC method is read via the instructions glob in the project-root opencode.json. Invoked with /aidlc. See AI-DLC on opencode. |
| Orchestrator | Umbrella term for how a workflow is driven: the deterministic Engine that decides what happens next and the Conductor (SKILL.md) that carries it out. Invoked via /aidlc. See Engine and Skill System. |
| Packager | scripts/package.ts — the build that regenerates every dist/<harness>/ Distribution from the Core + each Manifest. bun scripts/package.ts builds all; --check is the byte-parity drift guard run in CI. |
| Parallel batch | A group of Bolts whose dependencies are satisfied and that don't depend on each other, run concurrently by the orchestrator. A single approval gate at the end of the batch covers every Bolt in it. |
| Pipeline execution | A dispatched chain (mode: pipeline) whose links run in declared order, each seeing all upstream work; the final link leaves the artifacts complete. Reverse Engineering (2.1) is the shipped pipeline. |
| Phase | One of the 5 major divisions of the lifecycle: Initialization (0), Ideation (1), Inception (2), Construction (3), Operation (4). Each phase contains 3-8 stages (Initialization 3, Ideation 7, Inception 8, Construction 7, Operation 7). |
| Phase boundary verification | Automated traceability checks that run at phase transitions to catch missing links, orphaned artifacts, or inconsistencies before downstream stages build on them. |
| Plane | One of the three concerns the framework separates, borrowed from networking architecture: the control plane (stage definitions, Rules, Sensors — the schema of what should run, resolved at compile time), the data plane (the actual stage runs, Bolts, and audit telemetry), and the management plane (/aidlc --doctor, audit queries, CLAUDE.md). See Rules and the Learning Loop for the user-facing orientation and docs/reference/02-plane-architecture.md for the full model. |
| Record dir | The per-intent directory holding one intent's artifacts, per-stage memory.md diaries, aidlc-state.md, and audit/ shards: aidlc/spaces/<space>/intents/<YYMMDD>-<label>/ (written <record>/). Each intent gets its own; the active one is selected by the active-intent pointer. See Space, Intent. |
| Recovery breadcrumb | The hidden file .aidlc-recovery.md written by the PreCompact hook. Contains the last validated stage and timestamp for detecting state corruption after compaction. |
| Reviewer | A quality-gate agent — aidlc-product-lead-agent (requirements/stories/mockups) or aidlc-architecture-reviewer-agent (technical design) — invoked as a separate sub-agent after a stage body produces its artifacts, when the stage declares a reviewer: field. It appends a ## Review verdict (READY / NOT-READY) to the primary artifact; on NOT-READY the builder re-runs, looping up to reviewer_max_iterations (default 2) before presenting unresolved findings at the human approval gate. It never blocks — the human always decides. See Agents. |
| Rule | A persistent behavioural rule authored once in the active-space memory layer (aidlc/spaces/<active-space>/memory/) at the workspace root and pulled into context by each harness's native include (Claude @-import stub, Kiro resources glob, Codex AIDLC_RULES_DIR), applied to every stage it covers. Rules resolve through a strict-additive five-layer chain — org → team → project → phase → stage — where every applicable rule appears in context; broader layers are never overridden, only added to. Rules are the feedforward half of the control loop and may pair with a Sensor for deterministic verification. See Rules and the Learning Loop. |
| Runtime graph | The per-workflow runtime-graph.json artefact in the intent's record dir: a data-plane mirror of the structural stage graph, materialised from the audit log on every approval gate. Records which stages ran, which Bolts forked, which Sensors fired, and the memory.md entry counts — the queryable execution view doctor and the learning loop read. |
| Scope | One of 9 named configurations (enterprise, feature, mvp, poc, bugfix, refactor, infra, security-patch, workshop) that determines which stages execute and at what depth. Can also be auto-detected from freeform intent. |
| Sensor | A deterministic verification check defined by a manifest in .claude/sensors/ (e.g., aidlc-linter.md, aidlc-type-check.md). Sensors fire on Write/Edit to a stage's outputs via the PostToolUse hook and record advisory SENSOR_* audit rows — they never block your workflow. A stage declares which Sensors fire via its sensors: frontmatter list. Sensors are the feedback half of the control loop; Rules are the feedforward half. See Rules and the Learning Loop. |
| Test strategy | One of three test volume levels (Minimal, Standard, Comprehensive) that controls how many tests are generated and which test types are included. Independent of depth — defaults to the depth level unless the scope declares its own default (e.g., workshop defaults to Minimal). See Scopes, Depth, and Test Strategy. |
| Session | A single Claude Code conversation in which you run /aidlc. A workflow may span multiple sessions via the resume mechanism. |
| Skill | A Claude Code primitive: a markdown file with YAML frontmatter that registers a slash command. AI-DLC's orchestrator is implemented as the /aidlc skill. In user-facing documentation, prefer "command" over "skill". |
| Space | A per-team workspace at aidlc/spaces/<space>/ holding its own memory/, knowledge/, and intent records (intents/). The active space is resolved by the gitignored aidlc/active-space pointer and defaults to default; single-team users only ever see spaces/default/. See Intent, Knowledge. |
| Stage | One of the 32 discrete steps in the lifecycle. Each stage has a lead agent, defined inputs/outputs, and follows the stage protocol. Stages are numbered by phase (e.g., 1.1, 2.4, 3.5). |
| State file | The persistent per-intent workflow state at aidlc/spaces/<space>/intents/<YYMMDD>-<label>/aidlc-state.md (under the intent's record dir). Tracks stage progress, scope, workspace context, and session resume information using six-state checkboxes ([ ] / [-] / [?] / [R] / [x] / [S]). |
| Subagent execution | A dispatched hub (mode: subagent) where the conductor invokes a separate agent context through the harness's dispatch tool. Code Generation (3.5) is a focused one-agent run. Practices Discovery (2.2) is hub-and-spoke: lead draft, three mutually blind support contributions, human interview, then lead integration. |
| Unit of work | An independently implementable piece of the solution, decomposed during stage 2.7 (Units Generation). One or more Units are bundled into a Bolt for Construction. |
| Walking skeleton | The first Bolt in Construction — the thinnest end-to-end slice that exercises every integration point. Always gated and interactive so you can confirm the overall shape before the rest of Construction runs. The ladder prompt fires immediately after approval. |
| Utility command | A non-workflow flag passed to /aidlc such as --status, --doctor, --version, --stage, --phase, or --scope. These perform specific operations without running a full workflow. |
| Workflow | A single end-to-end execution of the AI-DLC lifecycle, from /aidlc invocation through stage completion. Scoped to a specific task (feature, bugfix, etc.). |