Introduction

Part of the AI-DLC documentation · User Guide · Harness Engineer Guide · Developer Reference

What is AI-DLC?

AI-DLC (AI-Driven Development Life Cycle) is a methodology for structuring AI-assisted software development into repeatable, traceable phases. It originated from the AWS AI-DLC methodology. This repository implements it natively from one harness-neutral core, so it runs inside the CLI harness you already use — today Claude Code, Kiro CLI, Kiro IDE, Codex CLI, or opencode. This guide is harness-neutral; where a detail differs by harness, it says so and points you to your harness's chapter (see Running on other harnesses). Examples are shown in Claude Code unless noted.

You invoke it with a single command:

/aidlc Build a REST API for inventory management

AI-DLC then guides you through a structured workflow — from capturing your intent, through requirements, design, implementation, testing, and deployment — while keeping you in control at every decision point.

Philosophy: Small Mob, Broad Agents

Rather than dozens of narrow specialists (an approach that recreates waterfall handoff chains), AI-DLC uses 11 broadly capable agents that each participate across multiple stages and phases. Each agent carries context across stages, eliminating handoffs and reducing coordination overhead.

This mirrors how effective human teams work: a mob of 3-5 people covers an entire feature, each bringing broad skills rather than a single narrow specialty.

How the Orchestrator Works

At its core, AI-DLC runs a simple loop. A deterministic engine decides what happens next; the conductor (the /aidlc session, SKILL.md) carries it out, then asks the engine for the next move. Across that loop the framework:

1. Reads stage files — 32 stage definitions across 5 phases, each specifying inputs, steps, outputs, and the lead agent
2. Loads agent personas — Activates domain-expert perspectives (architect, developer, product manager, etc.) with specialized knowledge
3. Manages state and audit — Tracks progress in aidlc-state.md and logs every decision to the intent's audit/ shards for traceability
4. Delegates across stage topologies — For focused autonomous work and multi-agent collaboration, dispatches subagents as a hub-and-spoke, pipeline, or mob
5. Presents approval gates — After each stage, you review and approve before the workflow advances

The engine owns the routing (which stage is next, which scope, when to stop); the conductor owns execution quality (running the stage well, asking good questions, surfacing decisions to you). Most stages run inline: the conductor adopts the agent's perspective and works directly with you in conversation. Four stages use dispatched topologies: Practices Discovery and Code Generation run as subagent hubs, Reverse Engineering as a two-link pipeline, and User Stories as a mob. The complete topology is 28 inline / 2 subagent / 1 pipeline / 1 mob. For the full architecture, see the Developer Reference's Engine and Skill System.

Who This Guide Is For

This guide is for anyone using AI-DLC to build software:

• New users — Start with Getting Started, Your First Workflow, and Spaces and Intents
• Regular users — Reference CLI Commands, Scopes, Depth, and Test Strategy, and Troubleshooting
• Team leads — See Knowledge and Rules and the Learning Loop for customizing AI-DLC to your team's standards

To reshape how AI-DLC behaves — add a stage or an agent, define a scope, author rules and sensors, or add team knowledge (all configuration, no code) — see the Harness Engineer Guide. For changing the AI-DLC codebase itself, see the Developer Reference.

Key Numbers

Guide Map