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
• AI-assistance attribution — every commit records how it was produced (agent-authored / agent-assisted / agent-reviewed / human), so aaid report ai-usage can show how much of the codebase is AI-assisted and whether AI-touched code passes gates as often as hand-written code
• 42 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
• AI-assistance attribution & reporting
• 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, 42 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 (42 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

Where your API key goes

aaid.config.yaml stores only the name of the variable holding your key (api_key_env), never the key itself. aaid reads the key at run time and never writes it anywhere. It checks three sources in order:

1. Environment variable — recommended.

# PowerShell, persists for new terminals (reopen the terminal afterwards)
[Environment]::SetEnvironmentVariable('OPENAI_API_KEY','<your-key>','User')

# macOS / Linux — add to ~/.zshrc or ~/.bashrc
export OPENAI_API_KEY='<your-key>'

2. Secret manager — nothing sensitive on disk. Set api_key_command to any command that prints the key; it runs only when the environment variable is unset.

agents:
  api_key_env: "OPENAI_API_KEY"
  api_key_command: "op read op://Vault/openai/credential"

Works with 1Password (op), HashiCorp Vault, az keyvault secret show, aws secretsmanager get-secret-value, gcloud secrets versions access. Best fit when each client project uses a different key. stdin is inherited, so a CLI that prompts for biometric or SSO auth still works.

3. .env beside aaid.config.yaml — OPENAI_API_KEY=<key>. aaid init adds .env to .gitignore, and aaid warns if it finds a key in a .env that git would commit. aaid reads this file but never creates or writes it, and pulls out only the one variable it needs rather than loading the file into the environment — so subprocesses spawned by gates (eslint, jest, playwright) don't inherit every secret in it.

api_key_env takes a variable name, not a key. A key pasted there would be a live credential in a tracked file, so aaid refuses to run until it's corrected. Avoid keeping keys in cloud-synced project folders (OneDrive, Dropbox, iCloud) — a .env there is replicated into cloud version history.

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 context export | Bundle project context into a shareable pack for a Claude Project / bot — --audience ba\|dev\|all (default ba). BA packs also emit story-assistant-instructions.md. In a workspace, bundles shared product context plus each selected service (interactive app checklist; --all-apps / --app <name> / --yes for CI). No API key | | 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 commit | Review the staged set, scan for credentials, confirm, then commit with AI-assistance attribution. --all, --dry-run, --level, --yes. No API key | | aaid attribute --install-hook | Add both attribution hooks to a project that predates them — the git prepare-commit-msg hook (per clone) and the Claude Code PostToolUse hook in .claude/settings.json (travels with the clone) | | aaid note-write | Records one agent file write to .aaid/agent-writes.jsonl, which is how agent-assisted is detected. Called by the PostToolUse hook — you rarely run it by hand. --path <file> --print verifies the wiring. No API key | | aaid report | Interactive report picker — also prints each report's direct command. No API key | | aaid report ai-usage | AI-assistance levels, volume and gate-pass correlation from commit trailers — --since 90d, --group-by level\|month\|story\|author, --format md\|json\|csv, --stdout. No API key | | aaid report gates | Latest result per gate plus the bypass audit trail. No API key | | aaid report exec | One-page status summary — scope, sprint, quality, AI assistance, risks. Composes the others. No API key | | aaid report sprint | Active sprint: goal, stories by status, points burned, blockers. --sprint <id> for a past one. No API key | | aaid report backlog | Stories grouped by epic, with unestimated work called out. No API key | | aaid report velocity | Delivered points per completed sprint; says so when there are too few to read a trend. No API key | | aaid report flow | Story cycle time — median, 85th percentile, and what is in flight. No API key | | aaid report contributors | Commit activity joined to AI attribution (aggregate unless opted in). No API key | | aaid pr | Open a pull/merge request whose description carries the branch's attribution — survives a squash-merge that discards commit trailers. --push, --update, --base, --draft, --dry-run, --no-labels. Detects GitHub / GitLab / Azure DevOps / Bitbucket | | 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).

Context packs for non-repo roles (aaid context export) — Bundles the project's durable context (requirements, PRD, domain glossary, backlog, or — for --audience dev — architecture, ADRs, conventions, codebase map) into a single portable aaid_artifacts/exports/context-pack-<audience>.md. It's a projection of existing artifacts, so it needs no API key and is safe to run in CI. BA use: run aaid context export (default --audience ba), upload the pack as knowledge to a shared Claude Project, and paste the emitted story-assistant-instructions.md as the Project's instructions — now BAs draft app-aware, tracker-ready stories from the browser, no repo or IDE needed. Re-run on design changes (or in CI on merge) to keep it current.

Workspaces (multiple services): the pack always includes shared product context, then layers on each service's own artifacts as clearly labelled sections (## <service> — Requirements), so provenance survives. Run interactively to get a checklist of every app (all pre-selected — unselect any to skip); or scope it non-interactively with --all-apps, --app <name> (repeatable / comma-separated), or --yes. A non-TTY shell (CI) defaults to all apps. Selecting a single service writes a service-suffixed file (context-pack-ba-<service>.md) so per-service Claude Projects don't clobber each other, and a mistyped apps[].path warns loudly instead of silently dropping the service.

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 project-plan | PM | Delivery plan — milestones, phases, resources, dependencies, risks | | aaid run pm --task roadmap | PM | Visual roadmap derived from the plan — roadmap.md (Mermaid gantt) + roadmap.html (standalone timeline) | | 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.

Test plan — aaid test-plan <STORY-ID> generates an AC-traceable test plan (manual test cases + traceability table + automation notes) for a story → implementation/<STORY-ID>/test-plan.md. For QA to verify against, and for /aaid-generate-tests to codify. Chat equivalent: /aaid-test-plan.

QA Automation

A Playwright-based test-automation suite, driven by the story test plans. Convention: folders = features, tags = stories — every spec is tagged (@STORY-014, @TC-3, @P1), so scoped runs and AC-coverage reporting work by scanning.

| Command | Description | |---|---| | aaid qa-automation setup | Readiness check → scaffolds qa-automation/ (Playwright config, smoke spec, page objects, fixtures), registers it as a workspace app, writes the CI workflow, and wires Playwright MCP so chat agents can drive a browser. Flags: --check, --dir, --skip-install, -y | | aaid qa-automation status | Per-story dashboard: test cases ⇄ automated specs ⇄ last run ⇄ AC coverage, with gaps flagged (--story STORY-ID for detail, --json) | | aaid qa-automation run | Run the suite — --story STORY-014 (specs tagged for that story), --smoke, --project e2e\|api |

aaid qa works as an alias for aaid qa-automation (e.g. aaid qa status). Note: aaid run qa is the AI QA agent; aaid qa-automation is the test suite. Authoring happens in chat: /aaid-automate STORY-ID turns a test plan's E2E cases into tagged specs — exploring the live app via Playwright MCP — and /aaid-qa-status is the chat dashboard.

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, 42 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-roadmap | Visual roadmap derived from the project plan — Now/Next/Later horizons, Mermaid gantt in roadmap.md, self-contained swimlane timeline in roadmap.html. Asks a few optional questions you can skip; re-render after date edits with aaid roadmap | | /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-test-plan | AC-traceable test plan for a story — manual test cases + traceability table + automation notes (for QA, before or after implementation) | | /aaid-automate | Turn a story's test plan into tagged Playwright specs in qa-automation/ — explores the live app via Playwright MCP, generates, runs, updates traceability | | /aaid-qa-status | QA automation dashboard — per story: test cases ⇄ automated specs ⇄ last run ⇄ AC coverage | | /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 42 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            # variable NAME, never the key itself
  # api_key_command: "op read op://Vault/anthropic/credential"   # secret manager
  # 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" }

AI-assistance attribution & reporting

Organisations increasingly need to report how much of their merged code was AI-assisted — and, more usefully, whether AI-touched code passes quality gates as often as hand-written code. aaid already records every agent run and gate result in .aaid/state.json, so it can answer both.

Committing

aaid commit                 # review the staged set, get consent, commit attributed
aaid commit --all           # stage the working tree (after showing you the list)
aaid commit --dry-run       # show everything, including the trailers, and stop

aaid commit prints the staged files with line counts, lists what is being left out, scans for credentials (.env, id_rsa, *.pem, key-shaped content) and asks before committing. --yes skips the prompt for scripts but still refuses when a possible credential is staged.

Plain git commit is attributed too — a prepare-commit-msg hook stamps it silently, so nothing is missed. In chat, /aaid-commit does the same review conversationally.

Chat work is detected, not declared. A Claude Code PostToolUse hook records every agent file write to .aaid/agent-writes.jsonl, and attribution joins those paths to the staged set — so editing files in chat and then running plain git commit reports agent-assisted on its own:

Attribution

  level    agent-assisted  — a human drove an AI in chat; no aaid agent ran
  via      claude-code  — 2 staged files written by the agent
           src/orders.ts
           src/orders.test.ts

Only Edit, Write, MultiEdit and NotebookEdit are recorded. Read, Grep and Glob are deliberately not: asking an agent a question about your code is not authorship of it. The ledger is gitignored local evidence — the trailer stays the durable record.

--level remains the override, for correcting a detection or reporting a tool with no hook:

aaid commit --level human              # I rewrote that file by hand
aaid commit --level agent-assisted     # Cursor / Copilot work, which has no hook

Add attribution to a project that predates it — installs both the git hook and the chat hook:

aaid attribute --install-hook

The chat hook lives in .claude/settings.json, an ordinary repo file, so unlike .git/hooks it travels with the clone: commit it once and a teammate gets chat attribution without installing anything. Existing settings are merged, never rewritten, and a file that can't be parsed is reported and left untouched rather than replaced.

What lands in the commit

feat(auth): add SSO login

AAID-Level: agent-authored
AAID-Agents: dev,qa
AAID-Story: STORY-042
AAID-Gates: code-standards=pass,test-coverage=87
AAID-Version: 2.0.0
Co-Authored-By: AAID dev agent <[email protected]>

Four levels, not a boolean — because "an agent wrote 800 lines" and "a human wrote everything and aaid ran the lint gate" are not the same claim:

| Level | Meaning | |---|---| | agent-authored | An aaid agent produced the code, under gates | | agent-assisted | A human drove an AI in chat; no aaid agent ran | | agent-reviewed | A human wrote it; aaid gates or review ran over it | | human | aaid is installed; nothing ran |

You remain the commit author; the agent is a co-author. Blame and accountability stay with a person. Trailers work on GitHub, GitLab, Azure DevOps and Bitbucket alike, survive rebase and cherry-pick, and are parsed natively by git — so reporting needs no API token.

Reporting

Every report is a projection of state.json and git log: no model call, no API key, deterministic, safe in CI.

aaid report                                  # interactive picker (shows each direct command)
aaid report exec                             # one page for a steering meeting
aaid report ai-usage --since 90d             # levels, volume, gate-pass rate
aaid report ai-usage --group-by month        # or story | author
aaid report ai-usage --format csv --stdout   # export for a dashboard
aaid report gates                            # gate health + bypass audit trail
aaid report sprint                           # active sprint; --sprint <id> for a past one
aaid report backlog                          # stories by epic, unestimated work flagged
aaid report velocity                         # delivered points per completed sprint
aaid report flow                             # cycle time: median, 85th percentile, in flight
aaid report contributors                     # activity joined to AI attribution
aaid report list                             # the menu, non-interactively

Several of these deliberately refuse to overstate what they know. Velocity needs 3 completed sprints before it will read a trend, and says "history, not a forecast" below that. Backlog counts unestimated stories separately, because a scope figure that quietly excludes work is worse than no figure. Flow leads with the 85th percentile rather than the median — the median is what half your stories beat, the 85th is what you can commit to.

In chat, one /aaid-report covers all of them — bare for the picker, or /aaid-report ai-usage --since 30d to jump straight in.

Level             Commits   Insertions   Gate pass
agent-authored        112       18,402         94%
agent-assisted        203       22,110         91%
agent-reviewed         88        9,740         88%
human                  61        6,205         82%

64% of attributed commits were agent-authored or assisted

That last column is the point. Counting AI commits is easy; saying whether they hold up is the question a CTO actually asks. Reports are written to aaid_artifacts/reports/<name>-<date>.md.

Commits with no AAID-Level trailer are reported as unattributed and excluded from the percentage rather than counted as human, so the headline number stays honest about how much history predates instrumentation.

Per-contributor reporting is opt-in

reports:
  contributor_identity: aggregate    # aggregate | pseudonymous | named

--group-by author refuses to run under the default. Per-developer AI metrics tend to corrupt the dataset they draw from — people who know they are measured strip trailers or route trivial work through an agent — destroying the org-level numbers that are actually useful. Naming individuals can also trigger works-council consultation and GDPR purpose-limitation duties in EU engagements. pseudonymous gives the distribution shape without naming anyone; named is there when a client requires it.

Limits worth knowing

• Squash-merge set to use the PR title only discards trailers at merge. Check your repository settings before relying on the numbers.
• Attribution is self-reported and bypassable (git commit --no-verify, or the ledger being a file on the developer's machine). Sound for engineering metrics and trend lines; not audit-grade — don't present it to a client as assured.
• Chat detection is Claude Code only. Cursor, Windsurf and Copilot expose no equivalent hook, so work done there still needs aaid commit --level agent-assisted — and the plain git commit path has no override at all.
• Figures either side of the 2.0.0 upgrade are not comparable. Commits that earlier versions reported as human are now reported as agent-assisted, so a window spanning the upgrade shows a jump that is instrumentation, not adoption. Note the date, or scope reports to one side of it.
• Attribution is per-commit, not per-line. One agent-written file among your staged set takes the whole commit to that level, with its full churn counted there.
• Trailers carry agent names, story IDs and gate results only, never prompt content: commit messages are permanent and often public.

Opening the pull request

Commit trailers are durable, but a repository that squash-merges using only the PR title discards every commit body — and every trailer with it. aaid pr writes the same information where that setting cannot reach:

aaid pr --push          # open a request for the current branch
aaid pr --dry-run       # show title, description and label, then stop
aaid pr --update        # refresh the block after pushing more commits

The description gets a readable table plus a hidden canonical data block, both generated from one validated object so they cannot drift. The branch takes the strongest level present — one agent-authored commit among nine human ones still means an agent wrote part of it.

| Host | Driven via | Labels | Calls them | |---|---|---|---| | GitHub | gh | yes | pull requests | | GitLab | glab | yes | merge requests | | Azure DevOps | az repos | yes (tags) | pull requests | | Bitbucket | — none exists | none | pull requests |

The host comes from your git remote, and aaid shells out to its CLI — so your host token stays where you already configured it. If the CLI isn't installed (or you're on Bitbucket, which has neither a CLI nor PR labels), aaid pr prints the description and a create-request link instead of pretending.

In chat, /aaid-pr drafts the title and description, shows you the level that will be claimed, and asks before creating anything.

Turn it off entirely with attribution: { enabled: false }.

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/
├── qa-automation/                  ← Playwright E2E/API suite (aaid qa-automation setup)
│   ├── tests/e2e/<feature>/        · folders = features, tags = stories (@STORY-x @TC-n)
│   ├── pages/ · fixtures/ · utils/
│   └── playwright.config.ts
└── 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

The error lists the three places aaid looks. Quickest fix:

# PowerShell — persists for new terminals
[Environment]::SetEnvironmentVariable('OPENAI_API_KEY','<your-key>','User')

# macOS / Linux — add to ~/.zshrc or ~/.bashrc for permanent setup
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=AIza...

See Where your API key goes for the .env and secret-manager options.

api_key_env holds what looks like an API key

api_key_env takes the name of the environment variable, not the key. Fix the config:

agents:
  api_key_env: "OPENAI_API_KEY"    # the NAME

Then supply the key by one of the three routes above — and revoke the pasted key, since it was sitting in plaintext in a config file that may be in your git history or a synced folder.

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

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