aaidlc — Agentic AI Development Life Cycle

aaidlc is a developer CLI that brings structured, multi-agent AI assistance to every phase of the software development life cycle — from requirements through deployment — with enforced quality gates that block bad code before it ships.
Unlike general-purpose AI chat, aaidlc uses specialized agents for each SDLC phase, carries full project context forward across every phase, and enforces non-negotiable quality standards automatically. It works with Claude, OpenAI, Google Gemini, or any local model via Ollama.
Table of Contents
How it works
Your project
│
▼
aaid init
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ SDLC Pipeline │
│ │
│ PM Agent → Architect → Dev Agent → QA → Security │
│ │ │ │ │ │ │
│ ▼ ▼ ▼ ▼ ▼ │
│ requirements architecture source tests audit │
│ brd adrs test files coverage threat-model │
│ prd patterns impl notes │
│ backlog │
│ │
│ ◄──── Every agent sees ALL prior phase outputs ────► │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Quality Gates (blocking) │ │
│ │ design-review · code-standards · test-coverage │ │
│ │ security-scan │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
aaid_artifacts/ committed to your repo
Context carryover is what makes aaidlc different. When the dev agent implements a story, it already knows your requirements, architecture decisions, design patterns, and every prior phase output. No copy-pasting context between chat windows.
Quality gates are not suggestions. They run real tools against real code — ESLint, coverage reports, npm audit, secret scanners — and block the pipeline on failure with specific remediation steps.
Prerequisites
- Node.js 18.0.0 or higher (download)
- Claude Code VS Code extension or desktop app — for chat mode (recommended)
- An AI provider API key — only if you use CLI mode. Not needed for chat mode.
Installation
Recommended — use npx (no install needed)
The simplest way. No PATH issues, always uses the latest version:
cd your-project
npx aaidlc init
Alternative — install globally
npm install -g aaidlc
Windows note: If you get aaid is not recognized after global install, your npm global bin folder is not in PATH. Use npx aaidlc instead — it works without any PATH configuration.
Quick Start
New project
cd my-project
npx aaidlc init
/aaid-requirements
Existing / legacy project
cd my-existing-project
npx aaidlc init
/aaid-migrate
/aaid-migrate reads your existing codebase, asks you questions about it, and generates requirements.md, architecture.md, and backlog.md — turning your existing code into structured business and technical documentation.
The wizard during npx aaidlc init asks for your project name, tech stack, design patterns, and AI provider. For chat mode, skip the API key step — it is not required.
Two Modes
aaidlc works in two distinct modes. You can use either or mix them on the same project.
Mode A — CLI Mode
Runs agents programmatically via the terminal. Requires an API key for your chosen AI provider. Each aaid run command invokes an AI agent, writes the output to aaid_artifacts/, updates state, and triggers the relevant quality gates.
aaid run pm --task requirements
aaid run architect
aaid run dev --story E-01-01
Best for: automated pipelines, CI/CD integration, batch processing of multiple stories.
Mode B — Chat Mode (Claude Code)
Uses Claude Code's slash command system. No API key needed — works with a Claude Pro subscription via the Claude Code VS Code extension or desktop app. After npx aaidlc init, 18 slash commands appear in your Claude Code chat.
/aaid-requirements
/aaid-architecture
/aaid-dev-story
Claude interviews you, generates the output, and saves the files to your project automatically using its built-in file tools. No copy-pasting.
Best for: interactive work, single-developer projects, users who prefer conversational AI.
Supported AI Providers
aaidlc works with any of the following providers. Select your provider during aaid init.
| Claude (Anthropic) | claude-sonnet-4-6, claude-opus-4-8, claude-haiku-4-5 | ANTHROPIC_API_KEY | Default — recommended |
| OpenAI | gpt-4o, gpt-4o-mini, o3, o3-mini | OPENAI_API_KEY | |
| Google Gemini | gemini-2.5-pro, gemini-2.5-flash | GOOGLE_API_KEY | |
| Ollama (local) | llama3.2, mistral, qwen2.5-coder, phi-4 | None required | Free, runs on your machine |
| Groq | llama-3.3-70b, mixtral-8x7b | GROQ_API_KEY | OpenAI-compatible |
| Mistral | mistral-large, codestral | MISTRAL_API_KEY | OpenAI-compatible |
| Together AI | various | TOGETHER_API_KEY | OpenAI-compatible |
Setting up Ollama (local, no API key)
ollama pull llama3.2
Project Structure
Running aaid init creates the following in your project root:
your-project/
│
├── aaid.config.yaml ← Project configuration (commit this)
│
├── .aaid/
│ └── state.json ← Phase & sprint state tracker (gitignored)
│
├── .claude/
│ └── commands/ ← Claude Code slash commands (24 files)
│ ├── aaid-help.md
│ ├── aaid-chat.md
│ ├── aaid-publish.md
│ ├── aaid-scaffold.md
│ ├── aaid-pattern-audit.md
│ ├── aaid-requirements.md
│ ├── aaid-brd.md
│ ├── aaid-prd.md
│ ├── aaid-backlog.md
│ ├── aaid-competitor-analysis.md
│ ├── aaid-gtm.md
│ ├── aaid-marketing.md
│ ├── aaid-architecture.md
│ ├── aaid-migrate.md
│ ├── aaid-write-story.md
│ ├── aaid-dev-story.md
│ ├── aaid-generate-tests.md
│ ├── aaid-review-code.md
│ ├── aaid-threat-model.md
│ ├── aaid-generate-docs.md
│ ├── aaid-devops.md
│ ├── aaid-k8s.md
│ ├── aaid-debug.md
│ └── aaid-explain-code.md
│
└── aaid_artifacts/ ← All AI-generated outputs (commit these)
│
├── planning/ ← Strategic & technical documents
│ ├── requirements.md ← Product requirements (from PM agent)
│ ├── brd.md ← Business Requirements Document
│ ├── prd.md ← Product Requirements Document
│ ├── backlog.md ← Full product backlog with epics & stories
│ ├── architecture.md ← System architecture & design decisions
│ ├── competitor-analysis.md ← Market & competitor research
│ ├── gtm.md ← Go-to-market strategy
│ └── adrs/ ← Architecture Decision Records
│ ├── ADR-001-database-choice.md
│ └── ADR-002-auth-strategy.md
│
├── tracking/
│ └── stories/ ← Individual story files
│ ├── E-01-01.md ← Story: user login
│ ├── E-01-02.md ← Story: password reset
│ └── E-02-01.md ← Story: payment checkout
│
├── docs/ ← AI-generated documentation
│ └── api-reference.md ← Detailed API reference
│
├── templates/ ← HTML templates for /aaid-publish
│ └── default.html ← Default template (replace with your branding)
│
├── exports/ ← Published HTML documents (print to PDF)
│ └── requirements.html
│
└── implementation/
└── 2026-06-16/ ← Dated folders per implementation session
├── E-01-01-impl.md ← Implementation notes & AC status per story
├── code-review.md ← Code review output
└── debug-report.md ← Debug session reports
What each folder is for
aaid.config.yaml — The single source of truth for your project configuration. Commit this to your repository. Controls which agents run, which AI provider is used, and all gate thresholds.
.aaid/state.json — Tracks the current SDLC phase, sprint state, story statuses, and gate results. Automatically gitignored. Rebuilt from artifacts if lost.
.claude/commands/ — Markdown files that become slash commands in Claude Code. Each file is a structured prompt template. Type /aaid-requirements in Claude Code chat to invoke it.
aaid_artifacts/planning/ — Every strategic and technical document generated by the PM and Architect agents. These are plain Markdown files — readable, diffable, committable.
aaid_artifacts/tracking/stories/ — One file per story, in the format E-[epic]-[story].md. Contains the user narrative, acceptance criteria, story points, and current status.
aaid_artifacts/docs/ — AI-generated documentation (API reference, generated guides). Kept separate from your project's hand-written docs so the two never mix.
aaid_artifacts/implementation/ — Daily-dated folders containing implementation notes, code review results, and debug reports. Gives you a full audit trail of what was built and when.
The SDLC Pipeline
Phase 1 — Discovery (optional)
aaid run pm --task competitor-analysis --product "Your product"
aaid run pm --task gtm
Generates market research and go-to-market strategy. Optional phases — skip for internal tools or existing products.
Phase 2 — Planning
aaid run pm --task requirements --product "Your product description"
aaid run pm --task brd
aaid run pm --task prd
aaid run pm --task backlog
Each task reads all prior outputs automatically. The backlog agent produces a full sprint-ready backlog with epics, stories, acceptance criteria, and story point estimates.
Phase 3 — Architecture
aaid run architect
Reads requirements, BRD, and PRD. Produces the architecture document and Architecture Decision Records. Triggers the design-review gate — blocks if ADRs are missing, patterns undocumented, or no API contracts defined.
Phase 4 — Development
aaid run dev --story E-01-01
The dev agent reads the story, the full architecture, and all prior context. It produces a source file, a test file, and an implementation record. Triggers code-standards, test-coverage, and security-scan gates on each story.
Phase 5 — Review & Quality
aaid run qa
aaid run security
aaid run reviewer
Each agent produces a structured report. The reviewer agent checks against your project's specific standards and prior architectural decisions.
Phase 6 — Shipping
aaid run docs
aaid run devops
Docs agent generates README updates, API documentation, and changelogs. DevOps agent generates CI/CD workflows, Dockerfiles, and environment configuration.
CLI Reference
Project commands
aaid init
aaid status
Agent commands
aaid run pm --task requirements
aaid run pm --task brd
aaid run pm --task prd
aaid run pm --task backlog
aaid run pm --task competitor-analysis --product "product name"
aaid run pm --task gtm
aaid run architect
aaid run dev --story E-01-01
aaid run qa
aaid run security
aaid run reviewer
aaid run docs
aaid run devops
Gate commands
aaid gate run design-review
aaid gate run code-standards
aaid gate run test-coverage
aaid gate run security-scan
aaid gate run all
aaid gate skip design-review --reason "spike, no ADR needed" --expires 2026-08-01
aaid gate list-bypasses
Sprint commands
aaid sprint plan
aaid sprint status
aaid sprint progress
aaid sprint complete
aaid sprint defer E-01-02 "reason"
Story commands
aaid story start E-01-01
aaid story done E-01-01
aaid story block E-01-01 "reason"
Skill commands
Skills are portable AI prompts that work without a config file. Use them standalone or paste the output into any AI chat.
aaid skill list
aaid skill write-story "user login with OAuth"
aaid skill design-architecture "payment service"
aaid skill generate-tests src/payments.ts
aaid skill review-code src/
aaid skill threat-model
aaid skill generate-docs "UserService"
aaid skill competitor-analysis "product name"
aaid skill gtm "product name"
Chat Mode — Slash Commands
After npx aaidlc init, 24 slash commands are generated inside .claude/commands/ and become available in Claude Code chat.
No API key required — chat mode works with a Claude Pro subscription via the Claude Code VS Code extension or desktop app.
Commands not showing up? Claude Code does not pick up new command files automatically. After running npx aaidlc init, press Ctrl+Shift+P → Developer: Reload Window and the commands will appear.
All commands
/aaid-help | Any time you need a quick command reference | Full command list with descriptions and recommended flow |
/aaid-chat | Open a grounded conversation with a specialist — pick from PM, Architect, Developer, QA, Security, DevOps, Reviewer, Marketing, or Docs writer — each loads your project context and responds in character | No file saved (conversational) |
/aaid-migrate | Start here for existing/legacy projects — reads your codebase, interviews you, generates all three planning artifacts | requirements.md, architecture.md, backlog.md |
/aaid-requirements | New project — interview-driven product requirements | aaid_artifacts/planning/requirements.md |
/aaid-brd | Business Requirements Document — stakeholders, objectives, scope, risks | aaid_artifacts/planning/brd.md |
/aaid-prd | Product Requirements Document — personas, user journeys, functional requirements | aaid_artifacts/planning/prd.md |
/aaid-backlog | Full product backlog with epics, stories, and story points | aaid_artifacts/planning/backlog.md |
/aaid-competitor-analysis | Market landscape, competitor comparison, positioning | aaid_artifacts/planning/competitor-analysis.md |
/aaid-gtm | Go-to-market strategy — ICP, pricing, channels, launch phases | aaid_artifacts/planning/gtm.md |
/aaid-marketing | Full marketing content pack — positioning statement, landing page hero copy, Product Hunt kit, 3-email launch sequence, social posts (LinkedIn/Twitter/X/Reddit), 5 SEO content briefs, 4-week content calendar, messaging cheat sheet | aaid_artifacts/planning/marketing.md |
/aaid-architecture | System architecture, Mermaid diagrams, ADRs, API contracts, data model | aaid_artifacts/planning/architecture.md |
/aaid-scaffold | Apply a design pattern layer (clean-architecture, hexagonal, CQRS, event-driven, etc.) on top of your project — guides empty projects through official CLI first | aaid_artifacts/planning/scaffold.md |
/aaid-pattern-audit | Audit existing codebase against its target architecture — scores 6 dimensions, lists violations with file + line, produces migration roadmap | aaid_artifacts/planning/pattern-audit.md |
/aaid-write-story | Write a single user story card with acceptance criteria | aaid_artifacts/tracking/stories/[ID].md |
/aaid-dev-story | Implement a story — generates source file + test file + implementation record | Saved to your source paths |
/aaid-generate-tests | Generate a complete test suite for an existing source file | Saved to test path |
/aaid-review-code | PR-style code review — inline comments, scores, verdict | aaid_artifacts/implementation/[date]/code-review.md |
/aaid-threat-model | OWASP Top 10 + STRIDE threat model, secret detection, auth review | aaid_artifacts/planning/threat-model.md |
/aaid-generate-docs | README, API reference, CHANGELOG, CONTRIBUTING, high-level project overview, or component deep-dives — pick A–G | Multiple files |
/aaid-devops | CI/CD pipeline (GitHub Actions) with real deploy steps per target (Fly.io/Railway/AWS ECS/K8s/DigitalOcean/Render/VPS), Dockerfile, docker-compose, .env.example, branch protection guidance | Infrastructure files |
/aaid-k8s | Full Kubernetes manifest set — Deployment, Service, Ingress, HPA, PDB, NetworkPolicy, ConfigMap, Secret template, kustomization.yaml | k8s/ directory |
/aaid-debug | Structured root cause analysis for an error or bug | aaid_artifacts/implementation/[date]/debug-report.md |
/aaid-explain-code | Step-by-step explanation of any code section — no file saved | Chat response only |
/aaid-publish | Convert any artifact markdown to a formatted HTML document ready to print as PDF — default template, custom style, or your own template | aaid_artifacts/exports/[filename].html |
Recommended Starting Flows
New project (greenfield):
/aaid-requirements → /aaid-architecture → /aaid-scaffold → /aaid-backlog → /aaid-dev-story (per story)
Existing / legacy project:
/aaid-migrate → /aaid-pattern-audit → /aaid-dev-story (new features)
Launch preparation:
/aaid-gtm → /aaid-marketing → /aaid-devops → /aaid-generate-docs
Not sure where to start? Run /aaid-chat and pick a specialist — they'll read your project context and help you figure out the next step.
How slash commands work
Every command interviews you before generating output — it asks targeted questions one at a time rather than dumping a form. For example /aaid-dev-story asks:
- Is this production work or a prototype/spike? (relaxes requirements for spikes)
- Paste the story — user narrative and acceptance criteria
- What file path should be created or modified?
- Any existing interfaces or base classes to implement?
- Related completed stories for context?
Then it generates the source file, test file, and implementation record — and saves all three directly to your project using Claude Code's file tools. No copy-pasting.
Configuration Reference
aaid.config.yaml is created in your project root by aaid init. Every option is shown below with its default value.
project:
name: "my-project"
language: typescript
framework: nextjs
patterns:
- clean-architecture
- repository
agents:
enabled:
- pm
- architect
- dev
- qa
- security
- reviewer
- docs
- devops
ai_provider: claude
model: claude-sonnet-4-6
api_key_env: ANTHROPIC_API_KEY
standards:
enforce: strict
rules:
- typescript.standards
gates:
maxRetries: 3
design_review:
enabled: true
blocking: true
require_adr: true
code_standards:
enabled: true
blocking: true
max_lint_errors: 0
max_complexity: 10
test_coverage:
enabled: true
blocking: true
minimum_coverage: 80
require_unit_tests: true
require_integration_tests: true
security_scan:
enabled: true
blocking: true
fail_on:
- critical
- high
discovery:
competitor_analysis: false
gtm_strategy: false
Provider configuration examples
Claude (default)
agents:
ai_provider: claude
model: claude-sonnet-4-6
api_key_env: ANTHROPIC_API_KEY
OpenAI
agents:
ai_provider: openai
model: gpt-4o
api_key_env: OPENAI_API_KEY
Google Gemini
agents:
ai_provider: gemini
model: gemini-2.5-pro
api_key_env: GOOGLE_API_KEY
Ollama (local — no API key)
agents:
ai_provider: openai-compatible
model: llama3.2
base_url: "http://localhost:11434/v1"
Groq
agents:
ai_provider: openai-compatible
model: llama-3.3-70b-versatile
api_key_env: GROQ_API_KEY
base_url: "https://api.groq.com/openai/v1"
Quality Gates
Quality gates run automatically when agents complete their work. A failed gate blocks the pipeline and returns specific remediation steps. Agents retry up to maxRetries times before marking a story blocked.
Gate 1 — Design Review
Runs after the architecture phase. Checks the architecture document, not code.
| ADR exists | At least one Architecture Decision Record in aaid_artifacts/planning/adrs/ | High |
| Patterns documented | Every pattern in your config is mentioned in the architecture output | High |
| No god objects | No component has more than 5 listed responsibilities | Medium |
| API contracts | Architecture output contains endpoint / OpenAPI / contract definitions | Medium |
| Data model | Architecture output contains schema / entity / database design | Medium |
| README exists | README.md present in project root with ≥ 10 non-empty lines | High |
| CHANGELOG exists | CHANGELOG.md present with at least one dated entry | High |
Gate 2 — Code Standards
Runs after the development phase. Checks your actual source files.
| Lint | Runs your stack's linter (eslint, ruff, phpcs, checkstyle) — zero errors required | High |
| Banned patterns | Language-specific anti-patterns: : any, @ts-ignore, eval(), dangerouslySetInnerHTML, v-html, SELECT * | High |
| N+1 queries | Detects database query calls inside loop constructs | High |
Banned patterns by language:
| TypeScript | : any, @ts-ignore, eval(), dangerouslySetInnerHTML, v-html=, SELECT * |
| Python | eval(), exec(), print() in production code, SELECT * |
| PHP | SQL string concatenation with variables, eval(), SELECT * |
| Java | System.out.print, Runtime.exec(), SELECT * |
| Go | fmt.Print in production code, os/exec without validation, SELECT * |
| Ruby | eval(), send() with user input, SELECT * |
| Rust | unsafe {} blocks without comment justification, unwrap() in production paths |
| C# | Console.Write in production code, raw SQL string concat, SELECT * |
Gate 3 — Test Coverage
Runs after the testing phase. Checks your test files and coverage report.
| Test files exist | Every source file has a corresponding .test.ts / .spec.ts file | High |
| Coverage threshold | coverage/coverage-summary.json shows ≥ 80% line coverage | High |
| No unjustified skips | it.skip() / test.skip() must have a // justification comment | Medium |
| No empty test files | Every test file contains at least one expect / assert / toBe | Medium |
To generate the coverage report: npx jest --coverage
Gate 4 — Security Scan
Runs after the security phase. Three independent tiers.
| Secret detection | AWS keys, GitHub tokens, private keys, DB URLs with credentials, API keys, Stripe keys | Critical |
| Banned security patterns | eval(), SQL string concat, innerHTML =, document.write(), shell exec concat | Critical / High |
| Security headers | Checks for helmet (Node), flask-talisman (Python), SecureHeaders (Laravel), Spring Security headers (Java) | High |
| Dependency audit | Runs npm audit / pip-audit / composer audit — fails on vulnerabilities | High |
| Security agent coverage | Verifies security report covers OWASP, authentication, input validation, threat model | Medium |
Supported Stacks
Gate tooling is keyed on language. Framework (React, NestJS, Django, etc.) adds context to agent prompts but does not change which tools run.
| TypeScript | ESLint + @typescript-eslint | Jest / Vitest | npm audit |
| Python | Ruff | pytest | pip-audit |
| PHP | phpcs (PHP_CodeSniffer) | PHPUnit + Pest | composer audit |
| Java | Checkstyle | JUnit 5 + Mockito | OWASP Dependency Check (mvn) |
| Go | golangci-lint | go test | govulncheck |
| Ruby | RuboCop | RSpec | bundler-audit |
| Rust | cargo clippy | cargo test | cargo audit |
| C# | dotnet format | dotnet test | dotnet list package --vulnerable |
Troubleshooting
Slash commands not showing in Claude Code
After running npx aaidlc init, Claude Code does not detect the new .claude/commands/ files until you reload the window.
Fix: Press Ctrl+Shift+P (or Cmd+Shift+P on Mac) → type Developer: Reload Window → Enter.
After reload, type /aaid- in the Claude Code chat panel and the commands will appear as suggestions.
aaid command not found after global install (Windows)
npm's global bin folder is not in your PATH. Use npx instead — it requires no PATH configuration:
npx aaidlc init
npx aaidlc status
npx aaidlc gate run all
Or fix PATH permanently by running this in PowerShell and restarting the terminal:
[System.Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$(npm config get prefix)", "User")
No aaid.config.yaml found
You are running an aaid command outside a project that has been initialised. Run aaid init first, or cd into your project directory.
Missing API key. Set the ANTHROPIC_API_KEY environment variable
Export your API key before running CLI mode:
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=AIza...
For permanent setup, add the export to your shell profile (.bashrc, .zshrc, or Windows environment variables).
Gate fails immediately with eslint is not installed
aaidlc runs your project's own linter. Install ESLint in your project:
npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
Gate fails with No coverage report found
Run your test suite with coverage before running the gate:
npx jest --coverage
The gate reads coverage/coverage-summary.json. Ensure your Jest config has coverageReporters: ['json-summary'].
openai-compatible provider returns connection refused
If using Ollama, make sure the Ollama server is running:
ollama serve
Then verify the model is pulled: ollama list
State gets out of sync
If .aaid/state.json is corrupted or deleted, reset it:
aaid init --reset-state
This reinitialises the state file without touching your artifacts or config.
Contributing
- Fork and clone the repository
npm install
npm run build — must produce zero TypeScript errors
npm test — all tests must pass
npm run lint — zero ESLint errors
- Open a pull request with a description of what changed and why
Please follow Conventional Commits for commit messages:
feat: add support for new provider
fix: resolve gate false positive on empty src directory
docs: update configuration reference
License
MIT — see LICENSE for details.
Built for engineering teams that want AI assistance with guardrails, not AI assistance that ships broken code.