The Machine
What wires the work and the mindset together. A single hand-authored core/ of TypeScript tools and hooks is projected into each CLI. Once installed, those scripts (not the model) own the state machine, the routing, the gates, and the audit trail that make the process above deterministic.
3.1A harness on top of a harness
A CLI like Claude Code is already a harness: it hands the model tools, sub-agents, and lifecycle hooks. We don't replace that. We build a second harness on top of it. The AI-DLC engine is a set of TypeScript scripts that plug into those same extension points and turn a raw assistant into a methodology-driven process. The methodology is written once, harness-neutral, then projected into each CLI's shape.
bun scripts/package.ts regenerates each committed dist/<harness>/ from the single core/.What each dist looks like
Every harness gets the same engine; only the wrapper around it changes to match how that CLI loads tools, agents, and hooks.
dist/claude/.claude/
Claude Code. Hooks registered in settings.json; agents are .md files; the engine runs under bun.
dist/kiro/.kiro/
Kiro CLI & IDE. Same engine, reached through an adapter shim. Kiro delivers hook context differently, so a small adapter normalizes it.
dist/codex/.codex/
Codex CLI. Config is TOML; hooks live in hooks.json; agents are emitted into the shape Codex expects.
The harness surface owns
· The orchestrator SKILL.md (per-harness).
· manifest.ts, which says how core maps into this CLI.
· Hook registration in the CLI's config.
Core owns
· The engine (aidlc-orchestrate.ts, aidlc-state.ts).
· Every stage, agent, sensor, knowledge file.
· The methodology. No harness gets special-cased.
core/ (or harness/<name>/), run the packager, and each dist/ tree is regenerated. Users copy dist/<harness>/ into their project. Porting to a new CLI is a projection, not a rewrite.3.2The control loop
The heart of the harness. The orchestrator never decides what to do next. It asks the engine. aidlc-orchestrate.ts next reads state and returns one typed directive; the conductor executes exactly that, then loops back to next. Routing lives in the tool, not the model.
next → one directive → execute → next. State transitions live in tools, so the loop is replayable and auditable.3.3Hooks: staying in the loop between turns
Hooks are how the engine keeps control even between the model's turns. The CLI fires them on lifecycle events, and each is a small bun script. Most are observers (they record and never alter flow). One is flow-altering: it can block or redirect what happens next.
Stop hook is the one that alters flow today.| Hook | Event | Role |
|---|---|---|
session-start | SessionStart | Boot workspace context; run the plugin compose step. |
mint-presence | UserPromptSubmit | Stamp human presence: proof a person was here this turn. |
audit-logger | PostToolUse | Append the canonical audit event for every state-changing write. |
sensor-fire | PostToolUse | Dispatch the deterministic sensors. |
runtime-compile | PostToolUse | Recompile the runtime graph so the next next reads fresh state. |
sync-statusline | PostToolUse | Render live phase / stage / gate status. |
log-subagent | SubagentStop | Track delegated sub-agent runs. |
validate-state | PreCompact | Guard state integrity before context is summarized. |
stop | Stop | Flow-altering. Enforces the forwarding loop so the workflow can't silently halt. |
session-end | SessionEnd | Close the session cleanly. |
PreToolUse reviewer read-scope guard) is in review. It hard-blocks a delegated reviewer from reading sibling units. Same pattern: deterministic enforcement of a rule that used to be prose only.3.4The scripts that run the show
The harness is really a set of core/tools/aidlc-*.ts scripts, each a small CLI the conductor calls. State never changes except through one of these, and that single rule is what makes a run deterministic and auditable. orchestrate is the brain; everything else supports it.
| Script | Role |
|---|---|
orchestrate | The engine. Reads workflow state + the compiled graph and answers "what's next?" as one typed directive. All routing lives here; the model doesn't plan, it dispatches. |
graph | Structural truth. The 32-stage definition graph: dependencies, phases, which agent leads each stage. Compiled, not editable at runtime. |
runtime | Data-plane mirror. Materializes runtime-graph.json from the audit trail + per-stage notes. The live picture of what's actually done, kept fresh so the next next reads current reality. |
state | Transitions. approve / reject / skip / scope-change, each with the human-presence guards. The only writer of the workflow state file. |
audit / log | The logger. Every state change appends a canonical event to an append-only trail (plus a Q&A / decision log). This is what makes a run replayable and explainable after the fact. |
bolt / swarm | Autonomy. Parallel per-unit Construction in isolated worktrees, with the convergence referee that decides what merges back. |
sensor* | Verification. Deterministic checks after a write: required sections, upstream coverage, lint, types. |
SKILL.md) are being kept in lock-step: the engine's job is to emit the exact directive sequence the prose flow already produces, so control can move into deterministic code without changing behavior.The Mind
The judgment behind that work. The reasoning comes from three connected layers: knowledge (what's known), agents (who reasons), and skills (the workflow they follow). This is how a stage turns into expert thinking, before the machine ever enforces anything.
2.1The five layers
Everything in core/ sorts into five layers. The boundary between them is what keeps the model from improvising the parts that must stay deterministic, while letting it reason freely in the parts that should.
| Layer | Lives in | What it holds |
|---|---|---|
| Rules / Memory | memory/ | Org, team, project guardrails + per-phase method. Self-learning: human corrections become persistent rules. |
| Agents | agents/*.md | 14 domain-expert personas. All carry disallowedTools: Task, so only the conductor delegates. |
| Knowledge | knowledge/ | Methodology reference: shared (principles, audit taxonomy) plus per-agent (patterns, testing). |
| Skills | skills/aidlc/ | The orchestrator SKILL.md, the stage protocol, and 32 stage files across 5 phases. |
| Hooks | hooks/*.ts | The control surface (covered under The Machine). |
2.2How they connect
When the engine says "run this stage," four layers snap together in the conductor's context. The stage names its lead agent; the agent's persona sets the voice; the stage protocol pulls the relevant knowledge; rules constrain the whole thing. The output is one artifact, judged at a gate.
Two execution modes
Inline: the conductor adopts the agent's persona and does the work in-context (most stages). Subagent: heavy, isolated work delegated through the Task boundary (reverse-engineering, code-generation).
One delegation seam
Only the conductor holds Task. Every agent carries disallowedTools: Task, so no agent spawns its own sub-agents. Delegation is a single, controlled door.
2.3The agents
14 files: 11 domain-expert personas that lead or support stages, 2 review-only agents that challenge at the gate, and 1 adaptive-workflow composer.
Product
lead
intent, stories, scope
Design
lead
mockups, UX
Architect
lead
feasibility, app + NFR design
AWS Platform
lead
infrastructure, provisioning
Developer
lead
reverse-eng, code-gen
DevSecOps
support
threat model, secure design
Compliance
support
GRC, data classification
Delivery
lead
team, planning, handoff
Pipeline / Deploy
lead
CI/CD, releases
Operations
lead
observability, incidents
Quality
lead
build & test
Architecture Reviewer
review-only
challenges design at the gate
Product Lead
review-only
the customer's voice at the gate
Composer
adaptive
builds a tailored stage plan
2.4Self-learning rules
The memory layer is not static. When a human corrects the workflow, that correction can become a persistent rule at the org, team, or project level, so the same mistake isn't repeated on the next run. Knowledge is reference; rules are learned constraints.
org.md
framework defaults
team.md
affirmed practices
project.md
project overrides
phases/*.md
per-phase method
The Work
Start with the output, since everything else exists to produce it. 32 stages across 5 phases form the full graph; a scope collapses it to the right shape for the task; gates, presence, and bounded autonomy control how much a human stays in the loop.
1.1Phases & stages
The engine walks 32 stages in graph order, gating between them. Two run as delegated sub-agents (heavy, isolated); the rest run inline in the conductor's voice.
1.2Workflow types: one graph, many shapes
The same 32-stage graph collapses to the right shape for the task. A scope marks each stage EXECUTE or SKIP, so a bugfix isn't dragged through market research and a PoC skips operations. Skipped stages stay in the graph (the doctor still validates them), they just don't run. Click a scope to see its shape.
And it's adaptive
The nine named scopes are starting points, not a fixed menu. The composer (an agent) reads your actual task, or a scan of an existing codebase, and authors a custom EXECUTE/SKIP grid when none of the presets fit. So the workflow shape is chosen per task, not forced into a template. A one-file bugfix runs 7 stages; a full greenfield product runs all 32; anything in between is either a named scope or one the composer builds on the spot.
1.3How tightly a human stays in the loop
This is the real control dial. Four mechanisms keep a non-deterministic model producing a deterministic, auditable process, and the human decides how much slack to give it.
GATE Approval between stages
The engine emits a gate at each boundary. The workflow can't advance until a human approves or asks for a revision. The gate names the real next stage, not a guess.
PRESENCE Proof a human was here
The mint-presence hook stamps every human turn. Gate approval checks it, and an approval with no human turn since the gate opened is refused. Closes the rubber-stamp and walk-away traps.
AUDIT Every transition is an event
State changes flow through tools that append to an append-only trail. The taxonomy is canonical and drift-tested. A run replays and explains from the shards alone.
SENSORS Deterministic verification
After a stage writes, sensors fire: required sections present, upstream covered, lint + types clean. Machine checks alongside model judgment.
Autonomy is opt-in and bounded
Construction can run a swarm, parallel per-unit work in isolated git worktrees, but only after a human explicitly sets autonomy to autonomous. Even then, the convergence referee (aidlc-bolt) owns the verdict: a batch merges back only if it's green and untampered. Verbs that re-shape the plan (recompose, scope-change) are refused under autonomy, since there's no human at the gate to approve a new shape. Switch to gated and the human is at every gate again.
The Dials
None of the behavior is hardcoded. Which model each agent runs on, how hard it thinks, where it points at Bedrock, how much a human stays in the loop: all of it is config the client owns. Cost and rigor are settings, not code changes.
4.1settings.json, the control panel
The Claude Code distribution ships a settings.json the client copies and edits. It holds four things that matter: where models resolve, the session model, the reasoning effort, and the hook registrations (covered under The Machine).
[1m] suffix is the 1-million-token context variant, a more expensive flavor of each model. Dropping it (using the standard window) cuts cost without changing tier, as long as the artifacts fit.4.2Model selection: tiers, not model IDs
Agents never name a concrete model. They name a tier (opus, sonnet, haiku, fable) and the env block resolves each tier to an actual Bedrock model ID. Change one line in env and every agent on that tier moves, without touching a single agent file.
The shipped policy is 9 agents on Opus, 5 on Sonnet: heavier design and build work on Opus, review and coordination on Sonnet.
| Tier | Agents |
|---|---|
opus ×9 | architect, aws-platform, product, design, developer, devsecops, compliance, quality, composer |
sonnet ×5 | architecture-reviewer, product-lead, delivery, pipeline-deploy, operations |
model: in the agent frontmatter. An older spelling (modelOverride:) was silently ignored by Claude Code, so tiers didn't actually engage. That's now fixed, so the shipped Opus/Sonnet policy is honored.4.3The cost & rigor levers
Three dials move cost, from surgical to blunt. All are config edits, no code.
Session model
"model": "opus[1m]" → "sonnet[1m]". Drops the orchestrator + every inline stage to a cheaper tier. The single biggest lever.
Effort level
"effortLevel": "xhigh" → high / medium. Cuts reasoning tokens across everything. As strong a cost driver as the model.
Per-agent tier
Edit an agent's model:, or re-point a whole tier in env. Surgical: keep reviewers strong, push support agents cheaper.
[1m] context variant for the standard window, or re-point OPUS at a Sonnet ID to run "opus" agents on Sonnet globally without editing any agent.4.4Behavior & environment flags
Beyond models, environment variables tune where the engine reads its pieces and how strict the guards are. A few worth knowing:
| Flag | Effect |
|---|---|
AWS_AIDLC_DEFAULT_SCOPE | The scope a fresh workflow starts in (ships as workshop). |
CLAUDE_CODE_USE_BEDROCK / AWS_REGION | Route to Bedrock and pick the region. |
AIDLC_USE_SWARM | Enable the autonomous Construction swarm path. |
AIDLC_SKIP_HUMAN_PRESENCE_GUARD | Test-only escape hatch for the presence check. Never for real runs. |
AIDLC_*_DIR (stages, rules, sensors, …) | Point the engine at alternate source trees. This is how the harness stays relocatable and testable. |
The Verbs
There is really one door: /aidlc. Type nothing and it figures out what to do next; type a flag and it jumps, resumes, or re-shapes. The stage skills are convenience shortcuts over the same door. Everything below is what a user actually types.
5.1The one door
Most of the time you just describe what you want, or type /aidlc with no argument, and the engine decides the next move. The flags are for when you want to steer.
| Command | What it does |
|---|---|
/aidlc "build the auth service" | Describe the work in plain words. The engine auto-detects a scope and starts the workflow. |
/aidlc | No argument: run the next move the engine names. This is the everyday "keep going." |
/aidlc --resume | Pick a parked workflow back up. The engine clears the park marker and continues where it stopped. |
/aidlc --status | Read-only. Shows the current phase, stage, gate, and what's blocking the workflow. Changes nothing. |
/aidlc --help | All commands and scopes. |
/aidlc --version | The framework version. |
5.2Steering the plan
These change where the workflow is or what shape it has. Jumps move the cursor; scope and depth reshape the run. Under autonomous Construction the plan-reshaping verbs are refused (no human at the gate).
| Command | What it does |
|---|---|
/aidlc --stage <id> | Jump to a stage by slug or number (code-generation or 3.5). |
/aidlc --phase <name> | Jump to the first in-scope stage of a phase (construction or 3). |
/aidlc --scope <scope> | Set or change scope. Standalone, or combined with --stage/--phase. |
/aidlc --depth <level> | Override depth: minimal, standard, or comprehensive. |
/aidlc compose "<task>" | Ask the composer to author a custom EXECUTE/SKIP grid when no preset fits. Proposes; you approve at a gate. |
recompose --skip <a,b> --add <c> (engine verb) | Flip pending stages EXECUTE/SKIP on a running workflow. Validated strictly, audited as RECOMPOSED. Reached through the compose gate, not hand-run. |
park (engine verb) | Stop cleanly at an inter-stage boundary for a later session. Resume with --resume. |
recompose, park) yourself. The conductor runs them when the engine's directive names them; they're listed so the audit trail and the reshape flow make sense.5.3Spaces & intents
A space is a memory context (org/team/project rules); an intent is one thing you're building inside it. You can run several intents in one space and switch between them.
| Command | What it does |
|---|---|
/aidlc space | List spaces, or switch to one. |
/aidlc space-create <name> | Create a space. Seeds its own memory/ (org, team, project, phases) copied from default. |
/aidlc intent | List intents in the active space, or switch the active intent. |
5.4Inspecting & health
Read-only lenses. None of these mutate workflow state or emit audit events.
| Command | What it does |
|---|---|
/aidlc --doctor | Health check on hooks, settings, directory structure, and recorded hook drops. |
/aidlc --detect | Scan the workspace (greenfield vs brownfield, languages, nested projects, submodules). |
/aidlc replay (skill) | A stakeholder narrative of the session, from the audit trail. Terminal-only, writes nothing. |
/aidlc session-cost (skill) | Deterministic aggregates: duration, stage outcomes, sensor firings, learnings captured. |
/aidlc outcomes-pack (skill) | A handover document at workflow close. Writes OUTCOMES.md, never touches state. |
5.5Skills — shortcuts over the same door
Skills are typed conveniences. A scope skill bakes in a scope so you skip detection; a single-stage skill runs one stage in isolation without advancing the main workflow. Each one is packaging over a /aidlc command that also works on its own.
Scope skills
/aidlc-feature, -mvp, -bugfix, -security-patch. Same as /aidlc --scope <x>, no detection step.
Single-stage skills
/aidlc-code-generation, -functional-design, and one per stage. Runs --stage <x> --single: the stage plus its gate, then stops. The main workflow's cursor is never touched.
Session skills
/aidlc-init, -compose, -replay, -session-cost, -outcomes-pack. Lifecycle helpers around a run.
/aidlc command.