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
• 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
• 30 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, 30 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 (30 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 migrate	Brownfield onboarding — scans codebase, generates requirements + architecture + backlog
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, 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

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, 30 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-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, Mermaid diagrams, ADRs, API contracts, data model
/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-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-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 30 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.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] }

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/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)
├── .aaid/
│   └── state.json                 ← Sprint & phase state (gitignored)
├── .claude/
│   └── commands/                  ← 30 Claude Code slash commands
├── .github/                       ← Created by aaid init --copilot
│   ├── copilot-instructions.md    ← Copilot workspace context
│   └── prompts/                   ← 30 Copilot prompt files
└── aaid_artifacts/
    ├── planning/                  ← requirements.md, architecture.md, backlog.md, adrs/
    ├── tracking/stories/          ← E-01-01.md, E-01-02.md …
    ├── implementation/            ← Dated folders per session
    ├── docs/                      ← API reference, generated guides
    ├── templates/                 ← HTML templates for /aaid-publish
    └── exports/                   ← Published HTML documents

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.