AI-DLC v2 Core Concepts
AI-DLC is an agent-driven dev lifecycle framework. This walks through v2: how stages are markdown files, scopes tune depth, and one engine routes it all.
v1 asked one LLM to both decide what to do next and do it. v2 splits the two: code decides which stage runs next; the LLM does the skilled work inside it — reproducible every run. 32 stages, 11 domain agents, one state file per intent.
agent = model + harness · the framework ships the harness One core (harness-neutral source) → Four harnesses (Claude Code, Kiro CLI, Kiro IDE, Codex CLI) — generated, byte-parity guarded.
01 · The Five Phases

Every project walks through five phases, from workspace scaffolding to production operations:
Phase 0 — Initialization: Scaffold workspace, detect greenfield vs brownfield.
Phase 1 — Ideation: Intent capture, clarifying questions, scope-definition.
Phase 2 — Inception: Requirements, stories, design — the WHAT and WHY.
Phase 3 — Construction: Units loop — code, tests, sensors active.
Phase 4 — Operation: Deploy, monitor, close the loop.
An approval gate at nearly every stage — you stay in control.
02 · The Atom — One File, Three Compartments

Every stage is a single markdown file with typed frontmatter (the compiler's contract) and a body the agent reads. The body splits into three compartments — feedforward that guides before generation, feedback that checks after.
Feedforward · guides before
-
Steps— The methodology. Numbered prose the LLM follows — authored by methodology owners, plus the knowledge, rules, and persona loaded for the stage.
Feedback · checks after
-
Sensors— The checks. Imported linters & type checkers fire on every write and verify the output. Findings land in the audit trail — advisory, never blocking.
Feedback · learns across runs
-
Learn— The feedback seam. A correction this run becomes a standing rule the next run reads — the human decides what was worth keeping.
03 · What Drives It

The Orchestrator (Deterministic)
Reads
aidlc-state.md plus a compiled stage graph and emits one routing directive. Same state in → same next stage out, every time.Key features:
-
next/report— two engine subcommands;nextemits one of 9 directive kinds (run-stage, present-gate, ask, invoke-swarm, done…)
-
audit/ shards— 70-event structured trail, timestamped, sharded per clone
-
--resume— reload state + audit, pick up mid-stage
11 Domain Agents (Probabilistic)
Product · Design · Delivery · Architect · AWS-Platform · Compliance · DevSecOps · Developer · Quality · Pipeline-Deploy · Operations
Each agent is pinned to a model and inherits the session toolset. A 14-agent roster overall (adding reviewer, composer, and product-lead).
04 · One Engine, Many Doors
Count | Command | Role | Description |
|---|---|---|---|
1 | /aidlc | Orchestrator | The full workflow. Detects scope, walks every gate, resumes from disk. |
4 | /aidlc-bugfix | Scope-runner | Same loop, one scope baked in — bugfix, mvp, feature, security-patch. |
29 | /aidlc-code-generation | Stage-runner | One stage in isolation, tool-enforced never to advance your workflow. |
3 | /aidlc-replay | Session view | Read-only — replay, session-cost, outcomes-pack. No state ever changes. |
05 · Two-Tier Knowledge

Methodology — Ships with framework in
.claude/knowledge/ . You don't touch this.Team Knowledge — User-managed in
aidlc/spaces/<space>/knowledge/ . Framework never overwrites.aidlc/knowledge/├── developer-agent/│ ├── typescript-conventions.md│ └── api-design-patterns.md├── quality-agent/│ └── acceptance-criteria.md├── architect-agent/└── aidlc-shared/ └── security-baselines.md06 · Adaptive Scope — Same Engine, Different Depth

9 scopes, auto-detected from your intent (
feature is the no-keyword catch-all; enterprise is opt-in), or hand-tailored with /aidlc compose .Scope | Stages |
|---|---|
bugfix | 7 |
poc | 8 |
refactor | 8 |
security-patch | 10 |
infra | 13 |
mvp | 22 |
workshop | 25 |
feature | 32 |
enterprise | 32 |
A scope lights a sub-graph — skipped stages stay in the DAG.
07 · How Standards Actually Stick
Three enforcement mechanisms work together:
Mechanism | How it works |
|---|---|
Hooks | SessionStart, PostToolUse, PreCompact, SubagentStop, Stop. The Stop hook is the one blocking gate. |
Sensors | Wrap your own linters & type checkers. Fire on file writes, feed results into the audit trail — advisory, not blocking. |
Learning Loop | A human correction becomes a persistent rule in project.md (promotable to team) — applied automatically next run. |
08 · Optional Tooling — Sharper Code Quality
None of this is a prerequisite — AI-DLC runs on Claude Code + bun alone. But quality has two levers:
Ground the input (fewer errors written):
- Your editor's LSP — real symbols, types, definitions from the codebase. In Kiro,
/code. The agent writes against APIs that exist, not ones it guessed.
- AWS MCP servers — real AWS API shapes, pricing, IaC. Ships in
.mcp.jsonviauvx, non-blocking.
Check the output (the rest caught before the gate):
- Lint + type-check ships as sensors — the two AI-DLC includes. But the sensor only wraps a tool you install & configure (eslint, tsc).
- Playwright e2e you author — wrap it as your own sensor. Verifies the thing actually works, not just that it compiles.
Grounding cuts errors up front; sensors catch what slips through — the feedforward / feedback split from §02, applied to code quality.
09 · Construction at Scale — The Autonomous Swarm
When you grant autonomy, the engine emits
invoke-swarm and a conductor fans out N units in parallel.The swarm follows a strict protocol:
- Fan out — N units run concurrently, each in fresh context
- Verdict + re-verify — referee re-checks before merge (the lying-conductor guard)
- Serialised merge — anti-tamper, one at a time, full audit trail
- Any failure → baton back to a human
aidlc-swarm.ts is a deterministic, stateless referee — it never writes code, it judges. Parallel throughput is a happy-path optimisation, never a bypass.10 · Extend It — Data Over Code
Want to add a stage? Drop one markdown file with typed frontmatter, tag the scopes it belongs to, then:
compile # rebuilds the graph + grid/aidlc --doctor # validates every scope's sub-DAG
No TypeScript, no orchestrator edit. Bundle a set of stages as an optional plugin — a host-native install that composes onto core and leaves the base trees byte-identical when inactive.
One engine. Many doors. The code routes; the model works.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article