aaidlc

aaidlc — Agentic AI Development Life Cycle

Learn more on the official website: https://aaidlc.com/

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.

• Specialized agents for each SDLC phase (PM, Architect, Dev, QA, Security, DevOps, Docs)
• Full context carryover — every agent sees all prior phase outputs automatically
• Persistent live context — current sprint, active stories, and gate results are kept in .aaid/context.md and auto-loaded into every Claude Code session via a single @-import; no re-explaining your project after a restart
• Versioned artifacts — every planning deliverable and story keeps a full history under versions/, with no git required
• Enforced quality gates — runs real tools (ESLint, coverage, secret scanners) and blocks on failure
• Multi-LLM — Claude, OpenAI, Gemini, or any local model via Ollama
• Cross-session memory — agents record decisions, gotchas, and patterns to .aaid/memory.md; that knowledge auto-loads into every future session
• 34 chat slash commands for Claude Code · GitHub Copilot prompt files via aaid init --copilot

Table of Contents

• Quick Start
• Installation
• Three Modes
• Supported AI Providers
• CLI Reference
• Chat Commands — Claude Code
• Chat Commands — GitHub Copilot
• Configuration
• Quality Gates
• Supported Stacks
• Project Structure
• Troubleshooting
• Contributing

Quick Start

# New project
cd my-project
npx aaidlc init
# Then in Claude Code chat: /aaid-requirements

# Existing project
cd my-existing-project
npx aaidlc init
npx aaidlc index        # optional: build codebase map so agents understand your project structure
# Then in Claude Code chat: /aaid-migrate

The aaid init wizard asks for your project name, tech stack, design patterns, and AI provider. For chat mode, skip the API key — it is not required.

Installation

Option A — npx (no install needed)

npx aaidlc init
npx aaidlc <command>

Always runs the latest version. No PATH configuration required.

Option B — global install

npm install -g aaidlc
aaid init

Windows — aaid not recognised after global install? Run this in PowerShell, then restart your terminal:

$npmBin = "$env:APPDATA\npm"
$current = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$current;$npmBin", "User")

Or skip the fix and use npx aaidlc everywhere — it works without any PATH configuration.

Three Modes

Mode A — CLI Mode

Runs agents via the terminal. Requires an API key. Agents write output to aaid_artifacts/, update state, and trigger quality gates.

aaid run pm --task requirements
aaid run architect
aaid run dev --story E-01-01

Best for: automated pipelines, CI/CD, batch story processing.

Mode B — Chat Mode (Claude Code)

Uses Claude Code's slash command system. No API key needed — works with a Claude Pro subscription. After aaid init, 34 slash commands appear in your Claude Code chat.

/aaid-requirements → /aaid-architecture → /aaid-dev-story

Claude interviews you, generates the output, and writes files to your project automatically. Best for: interactive work, single-developer projects.

Mode C — Chat Mode (GitHub Copilot)

Generates reusable prompt files for GitHub Copilot Chat. Run once after aaid init:

aaid init --copilot

Produces .github/prompts/aaid-*.prompt.md (34 prompts) and .github/copilot-instructions.md. Invoke with #aaid-requirements, #aaid-dev-story, etc. in Copilot Chat.

Coverage note: Content generation works fully. File auto-save requires a manual copy step — Copilot shows output in chat, you save it to disk.

Supported AI Providers

Select your provider during aaid init. All providers are used in CLI mode only — chat mode uses your Claude Pro subscription.

Provider	Models	API Key Variable
Claude (Anthropic) — default	claude-sonnet-4-6, claude-opus-4-8, claude-haiku-4-5	ANTHROPIC_API_KEY
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, free)	llama3.2, mistral, qwen2.5-coder, phi-4	None
Groq	llama-3.3-70b, mixtral-8x7b	GROQ_API_KEY
Mistral	mistral-large, codestral	MISTRAL_API_KEY
Together AI	various	TOGETHER_API_KEY

Ollama setup:

ollama pull llama3.2
# During aaid init → OpenAI-compatible → llama3.2 → http://localhost:11434/v1

CLI Reference

Requires an API key. Install globally: npm install -g aaidlc

Project Setup

Command	Description
aaid init	Full init wizard — single-app or workspace mode
aaid init --hook-only	Install pre-commit hook only (useful for legacy repos in a workspace)
aaid init --add-service	Add a new app/service to an existing workspace
aaid init --copilot	Generate GitHub Copilot prompt files for the current project
aaid status	Project health dashboard — artifacts, active sprint, gate results
aaid sync	Regenerate sprint-status.yaml, per-story files, and .aaid/context.md from .aaid/state.json (no state change) — run after chat-driven changes
aaid migrate	Brownfield onboarding — scans codebase, generates requirements + architecture + backlog
aaid restructure	Sync aaid_artifacts/ layout with the installed aaidlc version — run after upgrading (--dry-run to preview)
aaid remember "<note>" -t <type>	Record a learning to .aaid/memory.md (type: decision | gotcha | pattern | domain | note)
aaid memory	Show accumulated project memory
aaid index	Build codebase symbol index + dependency graph for efficient agent context
aaid index --full	Force full rebuild of the index
aaid index --status	Show index age, file count, and staleness

Codebase Index (aaid index) — Runs a pure-regex symbol extractor across your project (TypeScript, Python, Java, Go, PHP, Ruby, Rust, C#) and produces .aaid/codeindex.json + .aaid/repomap.md. All CLI agents automatically inject the repomap into their system prompt, giving them an accurate map of your codebase without scanning every file on each run. Re-run after significant code changes; the default mode is incremental (only re-parses modified files).

SDLC Agents

Each agent loads all prior phase outputs automatically — no context copy-pasting.

Command	Agent	Output
aaid run pm --task requirements	PM	Requirements document
aaid run pm --task brd	PM	Business Requirements Document
aaid run pm --task prd	PM	Product Requirements Document
aaid run pm --task backlog	PM	Full backlog with epics, stories, points
aaid run pm --task gtm	PM	Go-to-market strategy
aaid run architect	Architect	Architecture doc, ADRs, diagram views (System Map · Module Map · Data Flow · Dependency Graph), data model
aaid run dev --story STORY-001	Dev	Source file + test file + implementation record
aaid run qa	QA	Test suite validation
aaid run security	Security	Threat model + vulnerability audit
aaid run reviewer	Reviewer	Code review report
aaid run docs	Docs	README, API reference, guides
aaid run devops	DevOps	CI/CD pipeline, Dockerfile, docker-compose

Quality Gates

Gates run real tools against real code and block on failure.

Command	Description
aaid gate run all	Run all four gates in sequence
aaid gate run design-review	ADR existence, patterns, god objects, API contracts
aaid gate run code-standards	Lint, complexity, banned patterns, N+1 detection
aaid gate run test-coverage	Coverage threshold, test file presence, skip detection
aaid gate run security-scan	Secret detection, banned patterns, dependency audit
aaid gate run code-standards --staged	Staged files only — used by pre-commit hook
aaid gate run code-standards --app frontend	Workspace: scope gate to one service
aaid gate skip <name> -r "reason"	Bypass with permanent audit trail
aaid gate skip <name> -r "reason" -e 2026-08-01	Time-limited bypass
aaid gate list-bypasses	Show all active and expired bypasses

Adversarial review — aaid review <target> runs an AI review and writes findings to a review.md. The target dispatches: a planning artifact (prd | architecture | backlog | brd | srs | gtm | requirements) → planning/<target>/review.md; a file, directory, or STORY-ID → code review. Run with no target to be asked what to review. Chat equivalent: /aaid-review.

Sprint & Epic Tracking

Command	Description
aaid sprint plan	Propose a sprint from backlog — interactive review + confirm
aaid sprint status	Kanban board — stories grouped by status
aaid sprint progress	Progress % overall, by sprint, and per epic
aaid sprint velocity	Velocity history — points per sprint, average
aaid sprint complete	Close sprint, record velocity, handle incomplete stories
aaid sprint defer STORY-001 "reason"	Move story to deferred backlog
aaid story add	Add a story (interactive wizard)
aaid story start STORY-001	Transition: backlog → in-progress
aaid story review STORY-001	Transition: in-progress → in-review
aaid story done STORY-001	Transition: any → done
aaid story block STORY-001 "reason"	Transition: any → blocked
aaid epic list	List epics with status, progress, story count
aaid epic add	Create a new epic (interactive wizard)
aaid epic update EPIC-001 in-progress	Update epic status

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

Skills

Portable AI prompts — work without a config file, paste 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 competitor-analysis "product name"

Chat Commands — Claude Code

After aaid init, 34 slash commands appear in .claude/commands/ and are available in Claude Code chat. No API key required.

Commands not showing? Press Ctrl+Shift+P → Developer: Reload Window after init.

Type /aaid- in the chat panel to see all commands as autocomplete suggestions. Run /aaid-help for the in-chat reference.

Utility & Navigation

Command	Description
/aaid-help	Full command reference grouped by category with CLI equivalents
/aaid-tutorial	New here? Start with this. Guided walkthrough — asks new vs existing (brownfield) project, then lists which commands to run, where (chat vs terminal), and why
/aaid-chat	Open a conversation with a specialist — PM, Architect, Dev, QA, Security, DevOps, Reviewer, Marketing, or Docs — loaded with your project context

Planning & Discovery

Command	Output
/aaid-migrate	Start here for existing projects. Reads your codebase → requirements.md + architecture.md + backlog.md
/aaid-requirements	Interview-driven requirements document
/aaid-brd	Business Requirements Document — objectives, scope, stakeholders, risks
/aaid-prd	Product Requirements Document — personas, user journeys, functional specs
/aaid-backlog	Full prioritised backlog with epics, stories, Fibonacci estimates
/aaid-competitor-analysis	Market landscape, competitor matrix, positioning opportunities
/aaid-gtm	Go-to-market strategy — ICP, pricing, channels, launch phases
/aaid-marketing	Full marketing content pack — positioning, landing page, Product Hunt kit, email sequence, social posts, SEO briefs

Architecture & Design

Command	Output
/aaid-architecture	System architecture + four diagram views (arch-views.md: System Map, Module Map, Data Flow, Dependency Graph), ADRs, API contracts, data model, and an optional presentable HTML deck (archdeck.html)
/aaid-scaffold	Apply a design pattern (clean-architecture, hexagonal, CQRS, event-driven, repository…) to your project structure
/aaid-pattern-audit	Audit codebase against target architecture — scores 6 dimensions, lists every violation with file + line, produces migration roadmap

Development

Command	Output
/aaid-write-story	Write a user story card with acceptance criteria
/aaid-dev-story	Implement a story end-to-end — source file + test file + implementation record
/aaid-generate-tests	Complete, runnable test suite for a source file or component

Quality & Security

Command	Output
/aaid-review [target]	Adversarial review — dispatches on the target: a planning artifact (prd, architecture, backlog…) gets a severity-tagged review in its review.md; a file/dir/STORY-ID gets a code review. Asks what to review if no target given
/aaid-review-code	PR-style code review — inline findings, quality scores, final verdict
/aaid-threat-model	OWASP Top 10 + STRIDE threat model, secret detection, auth review, remediation list

DevOps & Infrastructure

Command	Output
/aaid-devops	GitHub Actions CI/CD, Dockerfile, docker-compose, .env.example. Real deploy steps for Fly.io, Railway, AWS ECS, Kubernetes, DigitalOcean, Render, or bare VPS
/aaid-k8s	Full Kubernetes manifest set — Deployment, Service, Ingress, HPA, PDB, NetworkPolicy, ConfigMap, kustomization.yaml

Sprint & Tracking

Command	Description
/aaid-sprint-plan	Interactive sprint planning — shows backlog by epic, asks for goal + duration + story selection, writes sprint to state.json
/aaid-sprint-board	Render the current Kanban board — stories by column, blockers highlighted, sprint health summary
/aaid-standup	Daily standup report — completed, in-progress, blocked. Accepts conversational status updates
/aaid-epic-status	Epic progress dashboard — per-epic bars, story breakdown, risk flags, recommended focus
/aaid-story-update	Conversational story transitions — "I finished STORY-003", "STORY-005 is blocked on X"
/aaid-backlog-groom	AI-assisted grooming — re-scores estimates, splits large stories, identifies gaps, creates/assigns epics

Daily Workflow & Docs

Command	Description
/aaid-debug	Structured root cause analysis for any error or unexpected behaviour
/aaid-remember	Record a decision, gotcha, pattern, or domain fact to .aaid/memory.md — persists across sessions
/aaid-explain-code	Step-by-step walkthrough of any code — WHY it works, hidden invariants, gotchas
/aaid-generate-docs	README, API reference, CHANGELOG, CONTRIBUTING guide, or component deep-dives
/aaid-publish	Convert any artifact markdown to formatted HTML — open in browser and print to PDF

Recommended Flows

New project:

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

Existing project:

/aaid-migrate → /aaid-pattern-audit → /aaid-scaffold → /aaid-dev-story

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.

Chat Commands — GitHub Copilot

aaid init --copilot

Generates:

• .github/prompts/aaid-*.prompt.md — all 34 prompts in Copilot's reusable-prompt format
• .github/copilot-instructions.md — project context + prompt list + file context guidance

Invoke in Copilot Chat with #aaid-requirements, #aaid-dev-story, etc.

Include file context for best results:

#file:.aaid/state.json #aaid-sprint-board
#file:aaid_artifacts/planning/requirements/requirements.md #aaid-dev-story

Re-run aaid init --copilot after aaid init --add-service to regenerate prompts with the new service included.

Configuration

aaid.config.yaml is created by aaid init. Commit this file to your repository.

project:
  name: "my-project"
  language: typescript    # typescript | python | java | php | go | csharp | ruby | rust
  framework: nextjs       # react | nextjs | vue | nestjs | express | django | fastapi
                          # flask | spring-boot | laravel | gin | aspnet-core | rails | none
  patterns:
    - clean-architecture
    - repository

agents:
  enabled: [pm, architect, dev, qa, security, reviewer, docs, devops]
  ai_provider: claude     # claude | openai | gemini | openai-compatible
  model: claude-sonnet-4-6
  api_key_env: ANTHROPIC_API_KEY
  # base_url: "http://localhost:11434/v1"   # Ollama / Groq / Mistral

standards:
  enforce: strict         # strict | warn | off

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 }
  security_scan:    { enabled: true, blocking: true, fail_on: [critical, high] }
  adversarial_review: { enabled: true, blocking: false, block_on: [critical] }

Adversarial-review gate — adversarial_review governs whether aaid review / /aaid-review findings block progression. Advisory by default (blocking: false): reviews just write review.md. Set blocking: true and aaid sprint plan will halt if a planning artifact's review verdict is NOT_READY or has a finding at a block_on severity — until fixed or overridden with aaid gate skip adversarial-review -r "reason".

Provider examples

# OpenAI
agents: { ai_provider: openai, model: gpt-4o, api_key_env: OPENAI_API_KEY }

# 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

Gates run automatically when agents complete work. A failed gate blocks the pipeline and returns specific remediation steps.

Gate 1 — Design Review

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

Check	Severity
At least one ADR in aaid_artifacts/planning/architecture/adrs/	High
Every configured pattern mentioned in architecture output	High
No component with more than 5 listed responsibilities	Medium
API contracts / endpoint definitions present	Medium
Schema / data model / entity design present	Medium
README.md exists with ≥ 10 non-empty lines	High
CHANGELOG.md exists with at least one dated entry	High

Gate 2 — Code Standards

Runs after the development phase on actual source files.

Check	Severity
Syntax check via built-in runtime tool (php -l, python -m py_compile, javac, ruby -c, go vet, cargo check, dotnet build)	High
Zero linter errors (eslint, ruff, phpcs, golangci-lint, rubocop, cargo clippy)	High
No language-specific banned patterns (:any, eval(), SELECT *, etc.)	High
No database query calls inside loop constructs (N+1 detection)	High

Gate 3 — Test Coverage

Runs after the testing phase.

Check	Severity
Every source file has a corresponding test file	High
coverage/coverage-summary.json shows ≥ 80% line coverage	High
No unjustified it.skip() / test.skip()	Medium
No empty test files (must contain at least one assertion)	Medium

Generate coverage: npx jest --coverage

Gate 4 — Security Scan

Check	Severity
No AWS keys, GitHub tokens, private keys, DB URLs with credentials, Stripe keys	Critical
No eval(), SQL string concat, innerHTML =, document.write(), shell exec concat	Critical / High
Security headers middleware present (helmet, flask-talisman, Spring Security, etc.)	High
npm audit / pip-audit / composer audit / dotnet list package --vulnerable passes	High

Supported Stacks

Gate tooling is keyed on language. Framework adds context to agent prompts but does not change which tools run.

Language	Lint / Build check	Test runner	Audit
TypeScript	ESLint	Jest / Vitest	npm audit
Python	Ruff	pytest	pip-audit
PHP	phpcs	PHPUnit / Pest	composer audit
Java	Checkstyle	JUnit 5	OWASP Dependency Check
Go	golangci-lint	go test	govulncheck
Ruby	RuboCop	RSpec	bundler-audit
Rust	cargo clippy	cargo test	cargo audit
C# (.NET)	dotnet build	dotnet test	dotnet list package --vulnerable

.NET framework choices (selected during aaid init): ASP.NET Core · Minimal API · Blazor Server · Blazor WebAssembly · gRPC · MAUI · WPF · Console / Class Library

.NET coverage: run dotnet test --collect:"XPlat Code Coverage" with the coverlet.collector package — the gate reads TestResults/**/coverage.cobertura.xml automatically.

Project Structure

your-project/
├── aaid.config.yaml                ← Project config (commit this)
├── CLAUDE.md                       ← Yours — imports live context via @.aaid/context.md
├── .aaid/
│   ├── state.json                  ← Sprint & phase state (gitignored)
│   ├── context.md                  ← Live sprint/story/gate context (aaid-owned, auto-updated)
│   ├── memory.md                   ← Decisions, gotchas, patterns (agent-written, persists)
│   ├── codeindex.json              ← Codebase symbol index (aaid index)
│   └── repomap.md                  ← Human-readable codebase map
├── .claude/
│   └── commands/                   ← Claude Code slash commands
├── .github/                        ← Created by aaid init --copilot
│   ├── copilot-instructions.md
│   └── prompts/
└── aaid_artifacts/
    ├── project-context.md          ← Static rules spine (stack, patterns, conventions)
    ├── sprint-status.yaml          ← Human-readable board, auto-generated
    ├── planning/                   ← One co-located folder per deliverable
    │   ├── prd/                     · prd.md, review.md, versions/
    │   ├── brd/  ·  requirements/  ·  backlog/  ·  gtm/  …
    │   └── architecture/
    │       ├── architecture.md
    │       ├── arch-views.md        ← System Map · Module Map · Data Flow · Dependency Graph
    │       ├── archdeck.html        ← Optional presentable slide deck
    │       └── adrs/                ← ADR-001-*.md
    ├── implementation/
    │   └── STORY-001/               · story.md, impl-notes.md, review.md, versions/
    ├── sprints/                    ← Per-sprint summary + retrospective
    ├── standups/                   ← Dated daily standup reports
    ├── reviews/                    ← Code-review & debug session logs
    ├── logs/                       ← Daily activity, changelog, deferred items
    ├── docs/                       ← API reference, generated guides
    ├── templates/                  ← HTML templates for /aaid-publish
    └── exports/                    ← Published HTML documents

Ownership & live context. .aaid/context.md holds your live project state — active sprint, in-flight stories, gate results — and aaid rewrites it on every state change. Your CLAUDE.md stays yours: aaid adds two @-import lines once (.aaid/context.md and .aaid/memory.md), so Claude Code loads fresh context every session without re-analysis, and your own notes are never touched. GitHub Copilot users can reference these files directly.

Cross-session memory. .aaid/memory.md is an agent-written log of decisions, gotchas, patterns, and domain knowledge that persists across sessions — the experiential complement to state.json. aaid seeds it once and never overwrites it; agents and developers append to it via aaid remember "<note>" -t <type> or the /aaid-remember chat command. Because it's imported into every session, a lesson learned today is available automatically tomorrow.

Co-located, versioned artifacts. Each planning deliverable and each story lives in its own folder alongside its review.md and a versions/ history. Regenerating an artifact snapshots the previous copy into versions/vNNN-YYYY-MM-DD/ before overwriting — a full audit trail with no git required, while the current file always stays at the predictable root path (e.g. planning/prd/prd.md).

Workspace mode. Product-wide planning lives at the workspace root; app-specific architecture, implementation, and docs live inside each app directory. The same folder layout applies at both levels.

Troubleshooting

Slash commands not showing in Claude Code

After aaid init, press Ctrl+Shift+P (or Cmd+Shift+P) → Developer: Reload Window.

aaid not found after global install (Windows)

Use npx aaidlc instead, or fix PATH permanently:

[System.Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$(npm config get prefix)", "User")

Restart your terminal after running this.

No aaid.config.yaml found

Run aaid init first, or cd into your project directory.

Missing API key error

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=AIza...

Add to your shell profile (.bashrc, .zshrc) for permanent setup.

eslint is not installed

aaidlc runs your project's own linter. Install it:

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

No coverage report found

npx jest --coverage

Ensure Jest config has coverageReporters: ['json-summary'].

Ollama connection refused

ollama serve
ollama list   # verify model is pulled

Pre-commit hook not triggering

The hook requires a .git directory at the workspace root (monorepo) or inside each service directory (polyrepo). Re-run aaid init --hook-only after confirming your git setup.

Contributing

• Fork and clone the repo
• npm install && npm run build — must produce zero TypeScript errors
• npm test — all tests must pass
• npm run lint — zero ESLint errors
• Open a PR with a description of what changed and why

Follow Conventional Commits: feat:, fix:, docs:

License

MIT — see LICENSE for details.

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