AD-SDLC: Agent-Driven Software Development Lifecycle

Automate your software development from requirements to deployment, built on the Claude Agent SDK.

Every AI-backed pipeline stage runs through a single Claude Agent SDK entry point (ExecutionAdapter). The three modes currently contain 39 stage slots that reuse 29 unique pipeline agent types; the repository also carries 7 support/delegated definitions, for 36 canonical prompt files shipped with every npm scaffold. These axes are tracked separately and checked from source.

Quick Start

Get started in under 5 minutes:

# 1. Install AD-SDLC
npm install -g ad-sdlc

# 2. Initialize your project
ad-sdlc init my-project
cd my-project

# 3. Start with your requirements
claude "Implement user authentication with OAuth2"

That's it! The agents will generate documents, create issues, implement code, and open PRs.

What is AD-SDLC?

AD-SDLC is an automated software development pipeline that uses specialized Claude agents to transform requirements into production-ready code. It supports three modes:

Greenfield Pipeline (New Projects)

User Input → Mode Detection → Collector → PRD Writer → SRS Writer → SDP Writer
         → Repo Detection → GitHub Repo Setup → SDS Writer
         ─┬─▶ Threat Model Writer ─┐
          ├─▶ Tech Decision Writer ─┤
          └─▶ UI Spec Writer ──────┤
                                    ↓
   Doc Indexing ← PR Reviewer ← Validation ← Worker ← Controller ← SVP Writer ← Issue Generator

Enhancement Pipeline (Existing Projects)

Existing Docs + Code → Document Reader → Codebase Analyzer → Code Reader
                                                                  ↓
                                                      Doc-Code Comparator
                                                                  ↓
                                                        Impact Analyzer
                                                                  ↓
                                      PRD Updater → SRS Updater → SDS Updater
                                                                  ↓
                                         Issue Generator + Regression Tester
                                                                  ↓
                            Controller → Worker → Validation → PR Reviewer
                                                                      ↓
                                                    Doc Indexing + CI Fix (on failure)

Import Pipeline (Existing GitHub Issues)

GitHub Issues → Issue Reader → Controller → Worker → Validation → PR Reviewer
                                                                       ↓
                                                        CI Fixer (delegated on failure)

Agent Definition Inventory (36 Prompt Files)

Phase	Agent	Role
Orchestration	AD-SDLC Orchestrator	Coordinates the full pipeline lifecycle
	Analysis Orchestrator	Coordinates the analysis sub-pipeline
Setup	Mode Detector	Detects Greenfield vs Enhancement vs Import mode
	Project Initializer	Creates `.ad-sdlc` directory structure and config
	Repo Detector	Determines if existing repo or new setup needed
	GitHub Repo Setup	Creates and initializes GitHub repository
Collection	Collector	Gathers requirements from text, files, and URLs
	Issue Reader	Imports existing GitHub Issues for Import pipeline
	Local Issue Reader	Local-mode issue import variant without a GitHub dependency
Documentation	PRD Writer	Generates Product Requirements Document
	SRS Writer	Generates Software Requirements Specification
	SDP Writer	Generates Software Development Plan from PRD and SRS
	SDS Writer	Generates Software Design Specification (SDS) and a separate Database Schema Specification (DBS)
	Threat Model Writer	Generates STRIDE/DREAD Threat Model from SDS
	Tech Decision Writer	Generates Technology Decision documents with alternatives analysis from the SDS technology stack
	UI Spec Writer	Generates UI screen specifications, user flow documents, and design system references from SRS
	Doc Index Generator	Generates structured documentation index (manifest, bundles, graph, router) from pipeline artifacts
Planning	Issue Generator	Creates GitHub Issues from SDS components
	SVP Writer	Generates Software Verification Plan with test cases from SRS and issues
Execution	Controller	Orchestrates work distribution and monitors progress
	Worker	Implements code based on assigned issues
	Local Reviewer	Local-mode PR review variant (no GitHub dependency)
Quality	PR Reviewer	Creates PRs and performs automated code review
	CI Fixer	Automatically diagnoses and fixes CI failures
	Regression Tester	Validates existing functionality after changes
V&V	Stage Verifier	Verifies every completed stage; strict mode can halt the live scheduler on failure
	RTM Builder	Builds Requirements Traceability Matrix from requirements to implementation
	Validation Agent	Validates final implementation against requirements and acceptance criteria
Enhancement	Document Reader	Parses existing PRD/SRS/SDS documents
	Code Reader	Extracts source code structure and dependencies
	Codebase Analyzer	Analyzes current architecture and code structure
	Doc-Code Comparator	Detects gaps between documentation and code
	Impact Analyzer	Assesses change implications and risks
	PRD Updater	Incremental PRD updates (delta changes)
	SRS Updater	Incremental SRS updates (delta changes)
	SDS Updater	Incremental SDS updates (delta changes)

Note: Only 29 of these definitions are direct agentType values in the mode arrays. Local aliases, orchestrators, CI repair, Stage Verifier, and RTM Builder are support/delegated definitions. See the runtime inventory for source-derived counts.

How it Works

3-Tier Architecture

AD-SDLC is structured as three cooperating tiers. The orchestrator owns the pipeline DAG, approval flow, and active validation stage; the execution layer is a single Claude Agent SDK entry point; and the knowledge layer (.claude/, MCP servers, claude-config plugin) is consumed by the SDK rather than wired through custom bridges.

flowchart TB
    Orch[T1 Orchestrator] -->|stage 단위| Adapter[T2 ExecutionAdapter]
    Adapter --> SDK[Agent SDK query]
    Adapter --> Hooks[Hook Pipeline]
    SDK -.reads.-> Knowledge[T3 .claude/ + plugin]
    Hooks --> Scratchpad
    Hooks --> Telemetry

Tier	Responsibility	Implementation
T1 Pipeline Control Plane	Stage DAG, checkpoints, V&V gates, domain writers	`src/ad-sdlc-orchestrator/`, `*-writer/`, `vnv/`
T2 Agent Execution Layer	Single SDK entry point, hooks, telemetry bridge	`src/execution/`
T3 Knowledge Layer	Agent definitions, skills, commands, MCP servers	`.claude/`, `.mcp.json`, claude-config plugin

See docs/architecture/v0.1-hybrid-pipeline-rfc.md for the full architecture RFC and docs/architecture/v0.1-migration-guide.md for the v0.0.1 → v0.1.0 migration steps.

Pipeline Flow

AD-SDLC automates the full software development lifecycle through a coordinated agent pipeline:

Mode Detection: The system analyzes your project to determine the appropriate pipeline -- Greenfield (new project), Enhancement (existing project), or Import (existing GitHub issues).
Document Generation: A cascade of writer agents produces structured documents from your requirements. In Greenfield mode: PRD, SRS, SDP, SDS, followed by parallel generation of Threat Model, Technology Decisions, and UI Specifications (when applicable).
Planning: The Issue Generator transforms design specifications into actionable GitHub Issues with dependencies and labels. The SVP Writer creates a Software Verification Plan with derived test cases.
Implementation: The canonical graph runs the controller stage followed by the worker stage. Configured stage concurrency limits independent runnable stages; it does not enforce a worker pool inside SDK agents.
Verification & Validation: The Validation Agent is an active stage in all three modes and checks the implementation against acceptance criteria. Stage Verifier and RTM Builder exist as auxiliary definitions/modules but are not yet orchestrator-enforced gates; their disposition is tracked in #877.
Review & Indexing: The SDK reviewer stage performs code review; supported verification rules run through the existing stage verifier. Workflow coverage and complexity thresholds are not enforced and are rejected when configured. Finally, the Doc Index Generator creates a searchable documentation index from all pipeline artifacts.

Each agent reads and writes to a shared scratchpad, enabling seamless inter-agent communication. The pipeline supports resume (--resume) and start-from (--start-from <stage>) for interrupted sessions.

Features

Automatic Document Generation: PRD, SRS, SDP, SDS, DBS, TM, SVP, TD, and UI specification documents from natural language requirements
UI Specification Generation: Screen specifications, user flow documents, and design system references from SRS use cases; auto-skips for CLI/API/library projects
Separate Database Schema Specification (DBS): SDS Writer emits a dedicated DBS document alongside the SDS, keeping the full database schema decoupled from architectural design
Document Frontmatter Metadata: YAML frontmatter with doc_id, version, status, and change history on all generated documents
Enhancement Pipeline: Incremental updates to existing projects without full rewrites
Import Pipeline: Process existing GitHub Issues directly, skipping document generation
Local Mode: Run the full pipeline without GitHub using --local (or AD_SDLC_LOCAL=1); see Quickstart for details
Mode Detection: Automatically detects Greenfield, Enhancement, or Import pipeline
Pipeline Resume: Resume interrupted pipelines from the last completed stage (--resume)
Session Persistence: Automatic state persistence for pipeline recovery
GitHub Integration: Automatic issue creation with dependencies and labels
Bounded Stage Execution: Configurable concurrency for independent runnable stages
Automated PR Review: SDK reviewer execution with the existing verification policy
Progress Tracking: Real-time visibility into pipeline status
Regression Testing: Identifies affected tests when modifying existing code
Doc-Code Gap Analysis: Detects discrepancies between documentation and implementation
V&V Framework: Final validation is a live pipeline stage, and the scheduler records per-stage verification results; strict haltOnVerificationFailure mode stops the DAG on the first failed gate
Document Audit: Packaged CLI (ad-sdlc audit-docs --project-dir .) that validates pipeline-generated PRD/SRS/SDS/SDP/TM/SVP/TD/DBS documents for frontmatter, required sections, cross-references, and PRD→SRS→SDS traceability; see Document Audit CLI
Resolved Workflow Policy: Canonical presets with validated stage concurrency, retry, timeout, approval, and verification settings. See the runtime configuration contract.

Installation

Prerequisites

Node.js 22.22.1+ (Download)
Git 2.30+
GitHub CLI 2.0+ (optional, for issue/PR management)
Claude API Key
GITHUB_TOKEN — required for stages that talk to GitHub (pr-reviewer, issue-generator, ci-fixer). Export a Personal Access Token with repo-level scope; the team-shared .mcp.json interpolates it via ${GITHUB_TOKEN} and never stores literals. See docs/configuration/mcp.md for setup, scopes, and troubleshooting.

Install

# Global installation (recommended)
npm install -g ad-sdlc

# Or use directly with npx
npx ad-sdlc init

Configure

# Set your Anthropic API key
export ANTHROPIC_API_KEY="your-api-key"

# For GitHub integration
gh auth login

See Installation Guide for detailed setup instructions.

Dependencies

AD-SDLC v0.1 standardizes on the official Claude Agent SDK as the only AI runtime dependency. The legacy raw @anthropic-ai/sdk client and the in-tree AgentBridge/AgentDispatcher/AgentRegistry stack were removed in v0.1.0 (#798).

Package	Version	Role
`@anthropic-ai/claude-agent-sdk`	`^0.3.260`	Single Agent SDK entry point used by `ExecutionAdapter` for every stage
`commander`	`^15.0.0`	`ad-sdlc` CLI argument parsing
`inquirer`	`^14.2.1`	Interactive prompts for `ad-sdlc init`
`js-yaml`	`^5.4.1`	Pipeline config and document frontmatter parsing
`zod`	`^4.5.4`	Runtime schema validation for configs, external data, and checkpoint schema
`ts-morph`	`^28.0.0`	TypeScript AST analysis for the Code Reader / Codebase Analyzer agents
`chalk`, `dotenv`	latest	CLI output and environment loading

Optional integrations (logging backends, OpenTelemetry exporters, better-sqlite3, ioredis, mammoth, pdf-parse) are declared as optional peer dependencies so the runtime install stays lean; consumers pull them in only when the matching scratchpad backend or document parser is enabled.

Usage

Initialize a New Project

# Interactive mode - guides you through configuration
ad-sdlc init

# Quick setup with defaults
ad-sdlc init my-project --quick

# With specific options
ad-sdlc init my-project \
  --tech-stack typescript \
  --template standard \
  --github-repo https://github.com/user/my-project

Template Options

Template	Workers	Coverage	Features
minimal	2	50%	Basic structure
standard	3	70%	Token tracking, dashboard
enterprise	5	80%	Audit logging, security scanning

Run the Pipeline

# Start with requirements collection
claude "Collect requirements for [your project description]"

# Generate documents step by step
claude "Generate PRD from collected information"
claude "Generate SRS from PRD"
claude "Generate SDS from SRS"

# Create GitHub Issues
claude "Generate GitHub issues from SDS"

# Implement and review
claude "Start implementation with Controller"

CLI Commands

# Initialize new project
ad-sdlc init [project-name]

# Validate configuration files
ad-sdlc validate [--file <path>] [--watch] [--format text|json]

# Check pipeline status
ad-sdlc status [--project <id>] [--format text|json] [--verbose]

# Analyze project for documentation-code gaps
ad-sdlc analyze [--project <path>] [--scope full|documents_only|code_only]

# Generate shell completion script
ad-sdlc completion --shell <bash|zsh|fish>

Document Audit

Once the pipeline has generated documents, validate them with the document audit CLI:

# Audit the current project (writes reports to .ad-sdlc/audit/)
ad-sdlc audit-docs --project-dir .

# Audit a different project and pick the output directory
ad-sdlc audit-docs --project-dir ./my-project --output audit-reports

# Repository contributors may also use the compatible wrapper
npm run audit:docs -- --project-dir ./my-project

The auditor runs frontmatter, required-section, cross-reference, PRD→SRS→SDS traceability, orphan, Mermaid, and relative-link checks across PRD, SRS, SDS, SDP, TM, SVP, TD, and DBS documents. It writes both a machine-readable audit-report.json and a human-readable audit-report.md, and exits with a non-zero status on any error-severity finding — making it suitable as a local pre-merge check or as a CI quality gate. See the Document Audit CLI guide for the full list of checks, report format, exit codes, and CI integration.

Full Pipeline Script

Run the complete AD-SDLC pipeline end-to-end:

# Auto-detect mode and run full pipeline
./ad-sdlc-full-pipeline.sh [project_path] [mode]

# Specify mode explicitly
./ad-sdlc-full-pipeline.sh . greenfield
./ad-sdlc-full-pipeline.sh . enhancement
./ad-sdlc-full-pipeline.sh . import

# Resume an interrupted pipeline
./ad-sdlc-full-pipeline.sh . auto --resume

# Resume a specific session
./ad-sdlc-full-pipeline.sh . auto --resume <session-id>

# Start from a specific stage
./ad-sdlc-full-pipeline.sh . greenfield --start-from sds_generation

# List available sessions for resume
./ad-sdlc-full-pipeline.sh . auto --list-sessions

Shell Autocompletion

Enable tab completion for AD-SDLC commands in your shell:

# Bash
ad-sdlc completion --shell bash >> ~/.bashrc
source ~/.bashrc

# Zsh
ad-sdlc completion --shell zsh > ~/.zsh/completions/_ad-sdlc
source ~/.zshrc

# Fish
ad-sdlc completion --shell fish > ~/.config/fish/completions/ad-sdlc.fish

See Quickstart Guide for a step-by-step tutorial.

Use Cases

New Feature Implementation

claude "Implement user dashboard with usage statistics and charts"

Bug Fix Workflow

claude "Fix #42: Login fails when email contains +"

Refactoring Project

claude "Refactor auth module to use dependency injection"

From Requirements File

claude "Read requirements from docs/requirements.md and implement"

See Use Cases Guide for more examples.

Project Structure

your-project/
├── .claude/
│   └── agents/              # Agent definitions (36 prompt files; see runtime inventory)
│       └── *.md             # Agent prompts (English, used by Claude)
├── .ad-sdlc/
│   ├── config/              # Configuration files
│   │   ├── agents.yaml      # Agent registry
│   │   └── workflow.yaml    # Pipeline configuration
│   ├── logs/                # Audit logs
│   ├── scripts/             # Pipeline shell scripts
│   │   └── ad-sdlc-full-pipeline.sh
│   ├── templates/           # Document templates
│   └── scratchpad/          # Inter-agent state (Scratchpad pattern)
│       └── pipeline/        # Pipeline session state (resume support)
├── docs/                    # Generated documentation
├── src/                     # Generated source code
└── README.md

Documentation

Getting Started

Installation Guide - Detailed setup instructions
Quickstart Guide - 5-minute tutorial
Use Cases - Common scenarios and examples
FAQ - Frequently asked questions

Reference

System Architecture
Runtime Inventory — source-checked agent, stage, and traceability counts
v0.1 Hybrid Pipeline RFC — 3-tier architecture and Claude Agent SDK adoption rationale
v0.1 Migration Guide — v0.0.1 → v0.1.0 contributor and consumer migration steps
Document Status Definitions
Document Audit CLI — validate generated PRD/SRS/SDS/... documents for integrity and traceability
PRD-001: Agent-Driven SDLC
SRS-001: Agent-Driven SDLC
SDS-001: Agent-Driven SDLC

Guides

Agent Deployment
Usage Scenarios — All execution environments and pipeline modes
Reference Documentation

Korean Documentation

Agent Definitions

All templates install the 36 canonical agents and four commands from the npm package. See Canonical assets and upgrades for manifest regeneration, versioning, customization handling, and legacy migration.

ad-sdlc assets update --project-dir . --dry-run
ad-sdlc assets update --project-dir .

Each agent is defined in .claude/agents/ with:

YAML frontmatter (name, description, tools, model)
Markdown body with role, responsibilities, schemas, and workflows

Agent prompt files (.md) are in English and used by Claude during execution.

Slash Commands

The scaffold installs .claude/commands/*.md for use as project slash commands in Claude Code sessions. Each file declares its argument shape via YAML frontmatter (description, optional argument-hint) and a short markdown body that instructs the assistant which CLI subcommand to run.

Command	File	Wraps
`/run-greenfield`	`.claude/commands/run-greenfield.md`	`ad-sdlc init . --quick` + `ad-sdlc run <requirements> --mode greenfield --project-dir .`
`/resume`	`.claude/commands/resume.md`	`ad-sdlc run <requirements> --resume <session-id> --project-dir .`
`/audit-docs`	`.claude/commands/audit-docs.md`	`ad-sdlc audit-docs --project-dir .`
`/status`	`.claude/commands/status.md`	`ad-sdlc status`

To use them, open the project inside a Claude Code session and type the command (for example /run-greenfield "Build a todo app"). Claude follows the matching markdown instructions, parsing requirements and supported options separately and keeping unchecked input out of shell source. New commands can be added by dropping a markdown file with valid frontmatter into .claude/commands/.

Document Frontmatter

All documents generated by the pipeline (PRD, SRS, SDP, SDS, DBS, TM, SVP, TD, UI) include structured YAML frontmatter for machine-readable metadata:

---
doc_id: PRD-my-project
title: Product Requirements Document
version: 1.0.0
status: Draft
generated_by: ad-sdlc v0.1.0
generated_at: '2026-04-12T09:00:00.000Z'
source_documents:
  - collected_info.yaml
change_history:
  - version: 1.0.0
    date: '2026-04-12'
    author: ad-sdlc
    description: Initial generation
---

Frontmatter Fields

Field	Type	Description
`doc_id`	string	Unique document identifier (e.g., `PRD-my-project`)
`title`	string	Human-readable document title
`version`	string	Semantic version (`MAJOR.MINOR.PATCH`)
`status`	enum	`Draft`, `Review`, or `Approved`
`generated_by`	string	Tool and version that generated the document
`generated_at`	string	ISO 8601 generation timestamp
`pipeline_session`	string	Pipeline session ID (optional)
`source_documents`	string[]	Input document references (optional)
`approval`	object[]	Approval entries with role, name, date, status (optional)
`change_history`	object[]	Version history entries (optional)

The frontmatter schema is defined in src/schemas/document-frontmatter.ts and validated with Zod at generation time. Utility functions for generating, parsing, and prepending frontmatter are in src/utilities/frontmatter.ts.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes using conventional commits
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Related Projects

claude-config

A Claude Code configuration management and development guidelines system. Agents in this project can reference claude-config's guidelines during code generation and review to improve code quality.

Repository: kcenon/claude-config
Reference Guide: docs/claude-config-reference.md

License

BSD 3-Clause License - see LICENSE for details.

Need help? Check the FAQ or open an issue.

Name		Name	Last commit message	Last commit date
.claude		.claude
.github		.github
.husky		.husky
.vscode.example		.vscode.example
.vscode		.vscode
docker		docker
docs		docs
examples		examples
schemas		schemas
scripts		scripts
src		src
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json		.mcp.json
.mcp.json.example		.mcp.json.example
.nvmrc		.nvmrc
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
agent-assets.manifest.json		agent-assets.manifest.json
cliff.toml		cliff.toml
doc-sync-points.yaml		doc-sync-points.yaml
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.sdk-contract.json		tsconfig.sdk-contract.json
typedoc.json		typedoc.json
vitest.bench.config.ts		vitest.bench.config.ts
vitest.config.ts		vitest.config.ts
vitest.e2e.config.ts		vitest.e2e.config.ts
vitest.integration.config.ts		vitest.integration.config.ts
vitest.perf.config.ts		vitest.perf.config.ts

Latest commit

History

Folders and files

Repository files navigation

AD-SDLC: Agent-Driven Software Development Lifecycle

Quick Start

What is AD-SDLC?

Greenfield Pipeline (New Projects)

Enhancement Pipeline (Existing Projects)

Import Pipeline (Existing GitHub Issues)

Agent Definition Inventory (36 Prompt Files)

How it Works

3-Tier Architecture

Pipeline Flow

Features

Installation

Prerequisites

Install

Configure

Dependencies

Usage

Initialize a New Project

Template Options

Run the Pipeline

CLI Commands

Document Audit

Full Pipeline Script

Shell Autocompletion

Use Cases

New Feature Implementation

Bug Fix Workflow

Refactoring Project

From Requirements File

Project Structure

Documentation

Getting Started

Reference

Guides

Korean Documentation

Agent Definitions

Slash Commands

Document Frontmatter

Frontmatter Fields

Contributing

Quick Start for Contributors

Related Projects

claude-config

License

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages