AWS Builder Center

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

Five Phases Pipeline

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

Stage Atom: 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

Orchestrator and Domain Agents


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;  next  emits 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

Two-tier knowledge directory

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.md

06 · Adaptive Scope — Same Engine, Different Depth

Adaptive scope bar chart

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.json  via  uvx , 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:
  1. Fan out — N units run concurrently, each in fresh context
  1. Verdict + re-verify — referee re-checks before merge (the lying-conductor guard)
  1. Serialised merge — anti-tamper, one at a time, full audit trail
  1. 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.
AI-DLC WORKFLOWS · v2.3.0 · GA PREVIEW —  awslabs/aidlc-workflows 
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article