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.

• How it works
• Prerequisites
• Installation
• Quick Start
• Two Modes
• Supported AI Providers
• Project Structure
• The SDLC Pipeline
• CLI Reference
• Chat Mode — Slash Commands
• Configuration Reference
• Quality Gates
• Supported Stacks
• Troubleshooting
• Contributing
• License

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.

Live session context — every aaid CLI command that changes state automatically updates a block inside your CLAUDE.md. Claude Code loads this at session start, so after restarting VS Code you instantly have your active sprint, story statuses, epic progress, and gate bypasses — no re-analysis, no warm-up.

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.

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

The simplest way. No PATH issues, always uses the latest version:

cd your-project
npx aaidlc init

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.

# 1. Navigate to your project
cd my-project

# 2. Initialise — follow the wizard
npx aaidlc init

# 3. Open the project in VS Code with Claude Code extension
# 4. Type in Claude Code chat:
/aaid-requirements

# 1. Navigate to your project
cd my-existing-project

# 2. Initialise
npx aaidlc init

# 3. Open in VS Code with Claude Code, then run:
/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.

aaidlc works in two distinct modes. You can use either or mix them on the same project.

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.

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.

aaidlc works with any of the following providers. Select your provider during aaid init.

# Install Ollama from https://ollama.com
ollama pull llama3.2

# During aaid init, select:
# > AI provider: OpenAI-compatible (Ollama, Groq, Mistral, Together...)
# > Model name: llama3.2
# > API base URL: http://localhost:11434/v1   (default)
# > API key env: (leave blank)

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

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.

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.

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.

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.

# Implement a specific story
aaid run dev --story E-01-01

# Or use chat mode for interactive implementation
# → /aaid-dev-story in Claude Code

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.

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.

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 mode requires an API key. Install globally: npm install -g aaidlc

Each agent loads all prior phase outputs before running, so context carries forward automatically.

Gates run real tools (ESLint, coverage, npm audit, secret scanners) and block on failure.

Gate names: design-review · code-standards · test-coverage · security-scan

Story statuses: backlog → in-progress → in-review → done (or blocked / deferred at any point)

Skills are reusable AI prompts that work without a config file — paste the output into any AI chat.

aaid skill list                                   # List all available skills
aaid skill write-story "user login with OAuth"    # Generate a story card
aaid skill design-architecture "payment service"  # Architecture prompt
aaid skill generate-tests src/payments.ts         # Test generation prompt
aaid skill review-code src/                       # Code review prompt
aaid skill threat-model                           # Security threat model
aaid skill generate-docs "UserService"            # Documentation prompt
aaid skill competitor-analysis "product name"     # Market research
aaid skill gtm "product name"                     # GTM strategy

After npx aaidlc init, 29 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.

Type /aaid- in Claude Code chat to see all 29 commands as autocomplete suggestions. Run /aaid-help at any time for the in-chat reference.

Run these early in a project. The documents they produce feed every downstream agent and command.

Use these daily to manage your sprint board, epics, and story lifecycle.

New project (greenfield):

/aaid-requirements → /aaid-architecture → /aaid-scaffold → /aaid-backlog → /aaid-dev-story (per story)
Daily: /aaid-standup → /aaid-story-update → /aaid-sprint-board

Existing / legacy project:

/aaid-migrate → /aaid-pattern-audit → /aaid-scaffold → /aaid-dev-story (new features)

Launch preparation:

/aaid-gtm → /aaid-marketing → /aaid-devops → /aaid-generate-docs

Architecture health check:

/aaid-pattern-audit → /aaid-review-code → /aaid-threat-model

Not sure where to start? Run /aaid-chat and pick a specialist — they'll read your project context and guide you to the right next step.

Every command interviews you before generating output — targeted questions one at a time, not a form dump. For example /aaid-dev-story asks:

1. Is this production work or a prototype/spike? (relaxes requirements for spikes)
2. Paste the story — user narrative and acceptance criteria
3. What file path should be created or modified?
4. Any existing interfaces or base classes to implement?
5. 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.

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    # typescript | python | java | php | go | csharp | ruby | rust
  framework: nextjs       # react | nextjs | vue | nuxt | angular | svelte | nestjs | express
                          # fastify | django | fastapi | flask | spring-boot | quarkus
                          # laravel | symfony | gin | echo | fiber | aspnet-core | rails
                          # axum | actix | none
  patterns:
    - clean-architecture  # applied by all agents as the design standard
    - repository          # additional pattern for code generation

agents:
  enabled:
    - pm
    - architect
    - dev
    - qa
    - security
    - reviewer
    - docs
    - devops

  # AI provider — choose one
  ai_provider: claude     # claude | openai | gemini | openai-compatible

  # Model for selected provider
  model: claude-sonnet-4-6

  # Environment variable that holds your API key
  api_key_env: ANTHROPIC_API_KEY

  # Required only for openai-compatible providers (Ollama, Groq, Mistral, etc.)
  # base_url: "http://localhost:11434/v1"

standards:
  enforce: strict         # strict | warn | off
  rules:
    - typescript.standards  # built-in ruleset for your stack

gates:
  maxRetries: 3           # how many times an agent retries after gate failure

  design_review:
    enabled: true
    blocking: true
    require_adr: true     # ADR must exist before development can start

  code_standards:
    enabled: true
    blocking: true
    max_lint_errors: 0    # zero tolerance
    max_complexity: 10    # cyclomatic complexity limit

  test_coverage:
    enabled: true
    blocking: true
    minimum_coverage: 80  # percentage
    require_unit_tests: true
    require_integration_tests: true

  security_scan:
    enabled: true
    blocking: true
    fail_on:
      - critical
      - high               # medium and low are warnings only

# Optional: enable discovery phases
discovery:
  competitor_analysis: false
  gtm_strategy: false

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

Runs after the architecture phase. Checks the architecture document, not code.

Runs after the development phase. Checks your actual source files.

Banned patterns by language:

Runs after the testing phase. Checks your test files and coverage report.

To generate the coverage report: npx jest --coverage

Runs after the security phase. Three independent tiers.

Gate tooling is keyed on language. Framework (React, NestJS, Django, etc.) adds context to agent prompts but does not change which tools run.

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.

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")

You are running an aaid command outside a project that has been initialised. Run aaid init first, or cd into your project directory.

Export your API key before running CLI mode:

export ANTHROPIC_API_KEY=sk-ant-...   # Claude
export OPENAI_API_KEY=sk-...          # OpenAI
export GOOGLE_API_KEY=AIza...         # Gemini

For permanent setup, add the export to your shell profile (.bashrc, .zshrc, or Windows environment variables).

aaidlc runs your project's own linter. Install ESLint in your project:

npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

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'].

If using Ollama, make sure the Ollama server is running:

ollama serve

Then verify the model is pulled: ollama list

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.

1. Fork and clone the repository
2. npm install
3. npm run build — must produce zero TypeScript errors
4. npm test — all tests must pass
5. npm run lint — zero ESLint errors
6. 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

MIT — see LICENSE for details.

Built for engineering teams that want AI assistance with guardrails, not AI assistance that ships broken code.