aaidlc

aaidlc — Agentic AI Development Life Cycle

aaidlc is a developer CLI that brings structured, multi-agent AI assistance to every phase of the software development life cycle — from requirements through deployment — with enforced quality gates that block bad code before it ships.

Unlike general-purpose AI chat, aaidlc uses specialized agents for each SDLC phase, carries full project context forward across every phase, and enforces non-negotiable quality standards automatically. It works with Claude, OpenAI, Google Gemini, or any local model via Ollama.

Table of Contents

• How it works
• 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

How it works

Your project
     │
     ▼
aaid init
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│                        SDLC Pipeline                            │
│                                                                 │
│  PM Agent  →  Architect  →  Dev Agent  →  QA  →  Security     │
│    │              │             │          │         │          │
│    ▼              ▼             ▼          ▼         ▼          │
│  requirements  architecture  source     tests    audit          │
│  brd           adrs          test files coverage threat-model   │
│  prd           patterns      impl notes                         │
│  backlog                                                        │
│                                                                 │
│  ◄──── Every agent sees ALL prior phase outputs ────►           │
│                                                                 │
│  ┌──────────────────────────────────────────────────┐          │
│  │              Quality Gates (blocking)             │          │
│  │  design-review · code-standards · test-coverage  │          │
│  │  security-scan                                    │          │
│  └──────────────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────────────┘
     │
     ▼
aaid_artifacts/ committed to your repo

Context carryover is what makes aaidlc different. When the dev agent implements a story, it already knows your requirements, architecture decisions, design patterns, and every prior phase output. No copy-pasting context between chat windows.

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.

Prerequisites

• Node.js 18.0.0 or higher (download)
• Claude Code VS Code extension or desktop app — for chat mode (recommended)
• An AI provider API key — only if you use CLI mode. Not needed for chat mode.

Installation

Recommended — use npx (no install needed)

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

cd your-project
npx aaidlc init

Alternative — install globally

npm install -g aaidlc

Windows note: If you get aaid is not recognized after global install, your npm global bin folder is not in PATH. Use npx aaidlc instead — it works without any PATH configuration.

Quick Start

New project

# 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

Existing / legacy project

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

Two Modes

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

Mode A — CLI Mode

Runs agents programmatically via the terminal. Requires an API key for your chosen AI provider. Each aaid run command invokes an AI agent, writes the output to aaid_artifacts/, updates state, and triggers the relevant quality gates.

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

Best for: automated pipelines, CI/CD integration, batch processing of multiple stories.

Mode B — Chat Mode (Claude Code)

Uses Claude Code's slash command system. No API key needed — works with a Claude Pro subscription via the Claude Code VS Code extension or desktop app. After npx aaidlc init, 18 slash commands appear in your Claude Code chat.

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

Claude interviews you, generates the output, and saves the files to your project automatically using its built-in file tools. No copy-pasting.

Best for: interactive work, single-developer projects, users who prefer conversational AI.

Supported AI Providers

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

Provider	Models	API Key Variable	Notes
Claude (Anthropic)	claude-sonnet-4-6, claude-opus-4-8, claude-haiku-4-5	ANTHROPIC_API_KEY	Default — recommended
OpenAI	gpt-4o, gpt-4o-mini, o3, o3-mini	OPENAI_API_KEY
Google Gemini	gemini-2.5-pro, gemini-2.5-flash	GOOGLE_API_KEY
Ollama (local)	llama3.2, mistral, qwen2.5-coder, phi-4	None required	Free, runs on your machine
Groq	llama-3.3-70b, mixtral-8x7b	GROQ_API_KEY	OpenAI-compatible
Mistral	mistral-large, codestral	MISTRAL_API_KEY	OpenAI-compatible
Together AI	various	TOGETHER_API_KEY	OpenAI-compatible

Setting up Ollama (local, no API key)

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

Project Structure

Running aaid init creates the following in your project root:

your-project/
│
├── aaid.config.yaml               ← Project configuration (commit this)
│
├── .aaid/
│   └── state.json                 ← Phase & sprint state tracker (gitignored)
│
├── .claude/
│   └── commands/                  ← Claude Code slash commands (24 files)
│       ├── aaid-help.md
│       ├── aaid-chat.md
│       ├── aaid-publish.md
│       ├── aaid-scaffold.md
│       ├── aaid-pattern-audit.md
│       ├── aaid-requirements.md
│       ├── aaid-brd.md
│       ├── aaid-prd.md
│       ├── aaid-backlog.md
│       ├── aaid-competitor-analysis.md
│       ├── aaid-gtm.md
│       ├── aaid-marketing.md
│       ├── aaid-architecture.md
│       ├── aaid-migrate.md
│       ├── aaid-write-story.md
│       ├── aaid-dev-story.md
│       ├── aaid-generate-tests.md
│       ├── aaid-review-code.md
│       ├── aaid-threat-model.md
│       ├── aaid-generate-docs.md
│       ├── aaid-devops.md
│       ├── aaid-k8s.md
│       ├── aaid-debug.md
│       └── aaid-explain-code.md
│
└── aaid_artifacts/                ← All AI-generated outputs (commit these)
    │
    ├── planning/                  ← Strategic & technical documents
    │   ├── requirements.md        ← Product requirements (from PM agent)
    │   ├── brd.md                 ← Business Requirements Document
    │   ├── prd.md                 ← Product Requirements Document
    │   ├── backlog.md             ← Full product backlog with epics & stories
    │   ├── architecture.md        ← System architecture & design decisions
    │   ├── competitor-analysis.md ← Market & competitor research
    │   ├── gtm.md                 ← Go-to-market strategy
    │   └── adrs/                  ← Architecture Decision Records
    │       ├── ADR-001-database-choice.md
    │       └── ADR-002-auth-strategy.md
    │
    ├── tracking/
    │   └── stories/               ← Individual story files
    │       ├── E-01-01.md         ← Story: user login
    │       ├── E-01-02.md         ← Story: password reset
    │       └── E-02-01.md         ← Story: payment checkout
    │
    ├── docs/                      ← AI-generated documentation
    │   └── api-reference.md       ← Detailed API reference
    │
    ├── templates/                 ← HTML templates for /aaid-publish
    │   └── default.html           ← Default template (replace with your branding)
    │
    ├── exports/                   ← Published HTML documents (print to PDF)
    │   └── requirements.html
    │
    └── implementation/
        └── 2026-06-16/            ← Dated folders per implementation session
            ├── E-01-01-impl.md    ← Implementation notes & AC status per story
            ├── code-review.md     ← Code review output
            └── debug-report.md    ← Debug session reports

What each folder is for

aaid.config.yaml — The single source of truth for your project configuration. Commit this to your repository. Controls which agents run, which AI provider is used, and all gate thresholds.

.aaid/state.json — Tracks the current SDLC phase, sprint state, story statuses, and gate results. Automatically gitignored. Rebuilt from artifacts if lost.

.claude/commands/ — Markdown files that become slash commands in Claude Code. Each file is a structured prompt template. Type /aaid-requirements in Claude Code chat to invoke it.

aaid_artifacts/planning/ — Every strategic and technical document generated by the PM and Architect agents. These are plain Markdown files — readable, diffable, committable.

aaid_artifacts/tracking/stories/ — One file per story, in the format E-[epic]-[story].md. Contains the user narrative, acceptance criteria, story points, and current status.

aaid_artifacts/docs/ — AI-generated documentation (API reference, generated guides). Kept separate from your project's hand-written docs so the two never mix.

aaid_artifacts/implementation/ — Daily-dated folders containing implementation notes, code review results, and debug reports. Gives you a full audit trail of what was built and when.

The SDLC Pipeline

Phase 1 — Discovery (optional)

aaid run pm --task competitor-analysis --product "Your product"
aaid run pm --task gtm

Generates market research and go-to-market strategy. Optional phases — skip for internal tools or existing products.

Phase 2 — Planning

aaid run pm --task requirements --product "Your product description"
aaid run pm --task brd
aaid run pm --task prd
aaid run pm --task backlog

Each task reads all prior outputs automatically. The backlog agent produces a full sprint-ready backlog with epics, stories, acceptance criteria, and story point estimates.

Phase 3 — Architecture

aaid run architect

Reads requirements, BRD, and PRD. Produces the architecture document and Architecture Decision Records. Triggers the design-review gate — blocks if ADRs are missing, patterns undocumented, or no API contracts defined.

Phase 4 — Development

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

Phase 5 — Review & Quality

aaid run qa
aaid run security
aaid run reviewer

Each agent produces a structured report. The reviewer agent checks against your project's specific standards and prior architectural decisions.

Phase 6 — Shipping

aaid run docs
aaid run devops

Docs agent generates README updates, API documentation, and changelogs. DevOps agent generates CI/CD workflows, Dockerfiles, and environment configuration.

CLI Reference

CLI mode requires an API key. Install globally: npm install -g aaidlc

🛠 Project Setup

Command	Description
aaid init	Full init wizard — single-app or workspace mode. Writes an initial live context block to CLAUDE.md.
aaid init --hook-only	Install pre-commit hook in an existing repo without full init (useful for legacy repos in a workspace)
aaid init --add-service	Add a new app/service to an existing workspace config
aaid status	Project health dashboard — artifacts, active sprint, gate results, progress
aaid migrate	Brownfield onboarding — scans codebase, interviews you, generates requirements + architecture + backlog

🤖 SDLC Agents

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

Command	Agent	What it does
aaid run pm --task requirements	PM	Gather and document requirements
aaid run pm --task brd	PM	Business Requirements Document
aaid run pm --task prd	PM	Product Requirements Document
aaid run pm --task backlog	PM	Generate full backlog with epics and stories
aaid run pm --task gtm	PM	Go-to-market strategy
aaid run architect	Architect	Architecture document, ADRs, data model
aaid run dev --story STORY-001	Dev	Implement a story end-to-end
aaid run qa	QA	Generate and validate test suite
aaid run security	Security	Threat model and vulnerability audit
aaid run reviewer	Reviewer	Code review across the codebase
aaid run docs	Docs	Generate README, API reference, guides
aaid run devops	DevOps	CI/CD pipeline and Dockerfile

🔒 Quality Gates

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

Command	Description
aaid gate run all	Run all four gates in sequence
aaid gate run design-review	Check 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 (pre-commit use)
aaid gate run code-standards --app frontend	Workspace: scope to one app
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

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

📊 Sprint & Epic Tracking

Command	Description
aaid sprint plan	Propose a sprint from backlog stories — interactive review + confirm
aaid sprint status	Kanban board — stories grouped by status column
aaid sprint progress	Progress % overall, by sprint, and per epic
aaid sprint velocity	Velocity history — points completed per sprint, average
aaid sprint complete	Close active sprint, record velocity, handle incomplete stories
aaid sprint defer STORY-001 "reason"	Move a story to the deferred backlog
aaid story add	Add a single story to the backlog (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 all epics with status, progress bar, and story count
aaid epic add	Create a new epic (interactive wizard)
aaid epic update EPIC-001 in-progress	Update an epic's status

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

🔧 Skills (portable prompts)

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

Chat Mode — Slash Commands

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.

🛠 Utility & Navigation

Command	What it does
/aaid-help	Show the 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 writer — loaded with your project context

📋 Planning & Discovery

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

Command	What it produces
/aaid-migrate	Start here for existing projects. Reads your codebase, interviews you, generates requirements.md + architecture.md + backlog.md
/aaid-requirements	Interview-driven requirements document
/aaid-brd	Formal Business Requirements Document — objectives, scope, stakeholders, risks
/aaid-prd	Product Requirements Document — personas, user journeys, functional specs, open questions
/aaid-backlog	Full prioritised backlog with epics, stories, and Fibonacci story point estimates
/aaid-competitor-analysis	Market landscape, competitor matrix, positioning opportunities
/aaid-gtm	Go-to-market strategy — ICP, pricing, channels, launch phases, risk register
/aaid-marketing	Full marketing content pack — positioning, landing page copy, Product Hunt kit, launch email sequence, social posts, SEO briefs, 4-week content calendar

🏗 Architecture & Design

Command	What it produces
/aaid-architecture	System architecture, Mermaid diagrams, ADRs, API contracts, data model
/aaid-scaffold	Apply a design pattern layer (clean-architecture, hexagonal, CQRS, event-driven, repository…) on top of your project structure
/aaid-pattern-audit	Audit existing codebase against its target architecture — scores 6 dimensions, lists every violation with file + line, produces migration roadmap

💻 Development

Command	What it produces
/aaid-write-story	Write a single user story card with acceptance criteria
/aaid-dev-story	Implement a story end-to-end — source files + test files + implementation record
/aaid-generate-tests	Generate a complete, runnable test suite for a source file or component

🔒 Quality & Security

Command	What it produces
/aaid-review-code	PR-style code review — inline findings, quality scores, final verdict (APPROVED / CHANGES_REQUESTED)
/aaid-threat-model	OWASP Top 10 + STRIDE threat model, secret detection, auth review, remediation priority list

🚀 DevOps & Infrastructure

Command	What it produces
/aaid-devops	CI/CD pipeline (GitHub Actions), Dockerfile, docker-compose, .env.example, branch protection guidance. Real deploy steps for Fly.io, Railway, AWS ECS, Kubernetes, DigitalOcean, Render, or bare VPS
/aaid-k8s	Full Kubernetes manifest set — Namespace, Deployment, Service, Ingress, HPA, PDB, NetworkPolicy, ConfigMap, Secret template, kustomization.yaml

📊 Sprint & Tracking

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

Command	What it does
/aaid-sprint-board	Render the current sprint Kanban board — stories by column, blockers highlighted, sprint health summary. Offers to update story statuses inline
/aaid-standup	Daily standup report — what completed yesterday, what's in progress today, what's blocked. Offers to record status updates conversationally
/aaid-epic-status	Epic progress dashboard — per-epic progress bars, story breakdown by status, risk flags, recommended focus areas
/aaid-story-update	Conversational story lifecycle transitions — "I finished STORY-003", "STORY-005 is blocked on X". Reads current state and applies changes
/aaid-backlog-groom	AI-assisted backlog grooming session — re-scores estimates, splits large stories, identifies gaps, re-prioritises. Updates backlog.md

🔧 Daily Workflow

Command	What it does
/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. Chat response only

📄 Docs & Publishing

Command	What it produces
/aaid-generate-docs	README, API reference, CHANGELOG, CONTRIBUTING guide, or component deep-dives
/aaid-publish	Convert any artifact markdown to a formatted HTML document ready to share or print as PDF

Recommended Flows

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.

How slash commands work

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

• Is this production work or a prototype/spike? (relaxes requirements for spikes)
• Paste the story — user narrative and acceptance criteria
• What file path should be created or modified?
• Any existing interfaces or base classes to implement?
• Related completed stories for context?

Then it generates the source file, test file, and implementation record — and saves all three directly to your project using Claude Code's file tools. No copy-pasting.

Configuration Reference

aaid.config.yaml is created in your project root by aaid init. Every option is shown below with its default value.

project:
  name: "my-project"
  language: typescript    # 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

Provider configuration examples

Claude (default)

agents:
  ai_provider: claude
  model: claude-sonnet-4-6
  api_key_env: ANTHROPIC_API_KEY

OpenAI

agents:
  ai_provider: openai
  model: gpt-4o
  api_key_env: OPENAI_API_KEY

Google Gemini

agents:
  ai_provider: gemini
  model: gemini-2.5-pro
  api_key_env: GOOGLE_API_KEY

Ollama (local — no API key)

agents:
  ai_provider: openai-compatible
  model: llama3.2
  base_url: "http://localhost:11434/v1"

Groq

agents:
  ai_provider: openai-compatible
  model: llama-3.3-70b-versatile
  api_key_env: GROQ_API_KEY
  base_url: "https://api.groq.com/openai/v1"

Quality Gates

Quality gates run automatically when agents complete their work. A failed gate blocks the pipeline and returns specific remediation steps. Agents retry up to maxRetries times before marking a story blocked.

Gate 1 — Design Review

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

Check	What it verifies	Severity
ADR exists	At least one Architecture Decision Record in aaid_artifacts/planning/adrs/	High
Patterns documented	Every pattern in your config is mentioned in the architecture output	High
No god objects	No component has more than 5 listed responsibilities	Medium
API contracts	Architecture output contains endpoint / OpenAPI / contract definitions	Medium
Data model	Architecture output contains schema / entity / database design	Medium
README exists	README.md present in project root with ≥ 10 non-empty lines	High
CHANGELOG exists	CHANGELOG.md present with at least one dated entry	High

Gate 2 — Code Standards

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

Check	What it verifies	Severity
Syntax	Always-available compile/parse check using a tool built into the language runtime — php -l, python -m py_compile, javac, ruby -c, go vet, cargo check, dotnet build. Runs before the linter so syntax errors are caught even when the linter is not installed.	High
Lint	Runs your stack's linter (eslint, ruff, phpcs, golangci-lint, rubocop, cargo clippy, dotnet build) — zero errors required	High
Banned patterns	Language-specific anti-patterns: : any, @ts-ignore, eval(), SELECT * and more per language	High
N+1 queries	Detects database query calls inside loop constructs	High

Banned patterns by language:

Language	Banned
TypeScript	: any, @ts-ignore, eval(), dangerouslySetInnerHTML, v-html=, SELECT *
Python	eval(), exec(), print() in production code, SELECT *
PHP	SQL string concatenation with variables, eval(), SELECT *
Java	System.out.print, Runtime.exec(), SELECT *
Go	fmt.Print in production code, os/exec without validation, SELECT *
Ruby	eval(), send() with user input, SELECT *
Rust	unsafe {} blocks without comment justification, unwrap() in production paths
C#	Console.Write in production code, raw SQL string concat, SELECT *

Gate 3 — Test Coverage

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

Check	What it verifies	Severity
Test files exist	Every source file has a corresponding .test.ts / .spec.ts file	High
Coverage threshold	coverage/coverage-summary.json shows ≥ 80% line coverage	High
No unjustified skips	it.skip() / test.skip() must have a // justification comment	Medium
No empty test files	Every test file contains at least one expect / assert / toBe	Medium

To generate the coverage report: npx jest --coverage

Gate 4 — Security Scan

Runs after the security phase. Three independent tiers.

Check	What it verifies	Severity
Secret detection	AWS keys, GitHub tokens, private keys, DB URLs with credentials, API keys, Stripe keys	Critical
Banned security patterns	eval(), SQL string concat, innerHTML =, document.write(), shell exec concat	Critical / High
Security headers	Checks for helmet (Node), flask-talisman (Python), SecureHeaders (Laravel), Spring Security headers (Java)	High
Dependency audit	Runs npm audit / pip-audit / composer audit — fails on vulnerabilities	High
Security agent coverage	Verifies security report covers OWASP, authentication, input validation, threat model	Medium

Supported Stacks

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

Language	Linter	Test runner	Dependency audit
TypeScript	ESLint + @typescript-eslint	Jest / Vitest	npm audit
Python	Ruff	pytest	pip-audit
PHP	phpcs (PHP_CodeSniffer)	PHPUnit + Pest	composer audit
Java	Checkstyle	JUnit 5 + Mockito	OWASP Dependency Check (mvn)
Go	golangci-lint	go test	govulncheck
Ruby	RuboCop	RSpec	bundler-audit
Rust	cargo clippy	cargo test	cargo audit
C#	dotnet format	dotnet test	dotnet list package --vulnerable

Troubleshooting

Slash commands not showing in Claude Code

After running npx aaidlc init, Claude Code does not detect the new .claude/commands/ files until you reload the window.

Fix: Press Ctrl+Shift+P (or Cmd+Shift+P on Mac) → type Developer: Reload Window → Enter.

After reload, type /aaid- in the Claude Code chat panel and the commands will appear as suggestions.

aaid command not found after global install (Windows)

npm's global bin folder is not in your PATH. Use npx instead — it requires no PATH configuration:

npx aaidlc init
npx aaidlc status
npx aaidlc gate run all

Or fix PATH permanently by running this in PowerShell and restarting the terminal:

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

No aaid.config.yaml found

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

Missing API key. Set the ANTHROPIC_API_KEY environment variable

Export your API key before running CLI mode:

export ANTHROPIC_API_KEY=sk-ant-...   # 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).

Gate fails immediately with eslint is not installed

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

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

Gate fails with No coverage report found

Run your test suite with coverage before running the gate:

npx jest --coverage

The gate reads coverage/coverage-summary.json. Ensure your Jest config has coverageReporters: ['json-summary'].

openai-compatible provider returns connection refused

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

ollama serve

Then verify the model is pulled: ollama list

State gets out of sync

If .aaid/state.json is corrupted or deleted, reset it:

aaid init --reset-state

This reinitialises the state file without touching your artifacts or config.

Contributing

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

Please follow Conventional Commits for commit messages:

feat: add support for new provider
fix: resolve gate false positive on empty src directory
docs: update configuration reference

License

MIT — see LICENSE for details.

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