AI-DLC: How It Works

Prologue: Meet the Cast

Before the story begins, let’s meet the players. Every character has a role. Nobody works alone.

The hatted agents are all Claude -- fresh instances with clean context, each focused on one job for one unit.

Act 1: The Big Picture

Every feature follows the same rhythm. Four steps. Then repeat.

For cross-functional teams, passes let design, product, and dev each run this loop independently -- the output of one becomes the input to the next.

Most features follow this full cycle. But there are shortcuts:

Why Specs Matter

The difference between hoping for the best and knowing what done looks like.

See the difference

Good criteria are the ones an AI can check without asking you.

Act 2: Planning Together

This is the most important part. Good planning means the AI can build autonomously. Bad planning means it keeps asking you questions.

Act 3: Building

Now the AI works. You typed /ai-dlc:execute. Three loops nest inside each other, from big to small.

Outer Loop: The Assembly Line

Units flow through a pipeline. Independent units can build in parallel. Each one unlocks the next.

The dependency graph (DAG) determines the order. Unit 1 has no dependencies, so it starts first. Once Unit 1 completes, Units 2 and 3 can build in parallel. Unit 4 waits for both 2 and 3.

Middle Loop: The Hat Rotation

Inside each unit, the AI cycles through hats. Each hat has one job. Quality gates stand between them — every time the Builder finishes a session, it must pass the gates before stopping.

When a design pass is active, the same rotation applies -- but the Builder becomes a Designer. Instead of production code, it produces wireframes, design tokens, and component specs. The design blueprint from elaboration feeds into every artifact.

Inner Loop: The Bolt (Context Recovery)

This is the clever part. AI agents have limited memory -- called a “context window.” When the memory fills up, a normal AI would forget everything. AI-DLC solves this by saving progress to files on disk. When a new session starts, the AI reads those files and picks up exactly where it left off. This is called a bolt -- one focused work session.

Act 4: Quality and Safety

Two systems keep everything on track: quality gates that enforce standards, and hooks that run silently in the background.

Quality Gates -- The Tollbooths

Every time the AI tries to stop, it must pass through a gate. Quality gates are harness-enforced — defined in frontmatter, run by hooks, no exceptions.

How Quality Gates Work: Detection → Definition → Enforcement

Quality gates aren't hardcoded. They're discovered from your repo, written into version-controlled frontmatter, and enforced mechanically by the harness — all without any manual configuration.

---
title: Add auth middleware
quality_gates:
  - name: tests
    command: npm test
  - name: typecheck
    command: npm run typecheck
  - name: lint
    command: npm run lint
---

---
title: Implement JWT validation
quality_gates:
  - name: auth-integration
    command: npm test -- --grep auth
---

Three hard gates stand between hats. The harness enforces them mechanically — the agent cannot bypass them:

The Safety Net -- Hooks

Hooks are automated scripts that fire at specific moments during a session. They run silently. You never see them. But they keep everything honest.

Act 5: Finishing and Learning

All units are done. The code is written. The tests pass. But the story isn’t over yet. Four stages remain.

Your Toolkit

Every command you need, organized by when you’ll reach for it

The Cycle Continues

Every completed intent makes the next one better. Reflections feed into seeds. Seeds surface during elaboration. Compound learnings inform future builders. The methodology improves itself -- and your codebase -- with every cycle.

From the Blog