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.

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

Project commands

aaid init                          # Scaffold aaidlc in your project
aaid status                        # Full project status dashboard

Agent commands

# PM agent — planning tasks
aaid run pm --task requirements
aaid run pm --task brd
aaid run pm --task prd
aaid run pm --task backlog
aaid run pm --task competitor-analysis --product "product name"
aaid run pm --task gtm

# Other agents
aaid run architect
aaid run dev --story E-01-01
aaid run qa
aaid run security
aaid run reviewer
aaid run docs
aaid run devops

Gate commands

aaid gate run design-review        # Run design review gate only
aaid gate run code-standards       # Run code standards gate only
aaid gate run test-coverage        # Run test coverage gate only
aaid gate run security-scan        # Run security scan gate only
aaid gate run all                  # Run all gates

aaid gate skip design-review --reason "spike, no ADR needed" --expires 2026-08-01
aaid gate list-bypasses            # Show all active and expired bypasses

Sprint commands

aaid sprint plan                   # Propose sprint from backlog
aaid sprint status                 # View sprint board
aaid sprint progress               # Coverage % by epic and sprint
aaid sprint complete               # Close sprint, handle incomplete stories
aaid sprint defer E-01-02 "reason" # Defer a story with a reason

Story commands

aaid story start E-01-01           # Mark story in progress
aaid story done E-01-01            # Mark story complete
aaid story block E-01-01 "reason"  # Mark story blocked

Skill commands

Skills are portable AI prompts that work without a config file. Use them standalone or paste the output into any AI chat.

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

Chat Mode — Slash Commands

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

All commands

Command	When to use	What it produces
/aaid-help	Any time you need a quick command reference	Full command list with descriptions and recommended flow
/aaid-chat	Open a grounded conversation with a specialist — pick from PM, Architect, Developer, QA, Security, DevOps, Reviewer, Marketing, or Docs writer — each loads your project context and responds in character	No file saved (conversational)
/aaid-migrate	Start here for existing/legacy projects — reads your codebase, interviews you, generates all three planning artifacts	requirements.md, architecture.md, backlog.md
/aaid-requirements	New project — interview-driven product requirements	aaid_artifacts/planning/requirements.md
/aaid-brd	Business Requirements Document — stakeholders, objectives, scope, risks	aaid_artifacts/planning/brd.md
/aaid-prd	Product Requirements Document — personas, user journeys, functional requirements	aaid_artifacts/planning/prd.md
/aaid-backlog	Full product backlog with epics, stories, and story points	aaid_artifacts/planning/backlog.md
/aaid-competitor-analysis	Market landscape, competitor comparison, positioning	aaid_artifacts/planning/competitor-analysis.md
/aaid-gtm	Go-to-market strategy — ICP, pricing, channels, launch phases	aaid_artifacts/planning/gtm.md
/aaid-marketing	Full marketing content pack — positioning statement, landing page hero copy, Product Hunt kit, 3-email launch sequence, social posts (LinkedIn/Twitter/X/Reddit), 5 SEO content briefs, 4-week content calendar, messaging cheat sheet	aaid_artifacts/planning/marketing.md
/aaid-architecture	System architecture, Mermaid diagrams, ADRs, API contracts, data model	aaid_artifacts/planning/architecture.md
/aaid-scaffold	Apply a design pattern layer (clean-architecture, hexagonal, CQRS, event-driven, etc.) on top of your project — guides empty projects through official CLI first	aaid_artifacts/planning/scaffold.md
/aaid-pattern-audit	Audit existing codebase against its target architecture — scores 6 dimensions, lists violations with file + line, produces migration roadmap	aaid_artifacts/planning/pattern-audit.md
/aaid-write-story	Write a single user story card with acceptance criteria	aaid_artifacts/tracking/stories/[ID].md
/aaid-dev-story	Implement a story — generates source file + test file + implementation record	Saved to your source paths
/aaid-generate-tests	Generate a complete test suite for an existing source file	Saved to test path
/aaid-review-code	PR-style code review — inline comments, scores, verdict	aaid_artifacts/implementation/[date]/code-review.md
/aaid-threat-model	OWASP Top 10 + STRIDE threat model, secret detection, auth review	aaid_artifacts/planning/threat-model.md
/aaid-generate-docs	README, API reference, CHANGELOG, CONTRIBUTING, high-level project overview, or component deep-dives — pick A–G	Multiple files
/aaid-devops	CI/CD pipeline (GitHub Actions) with real deploy steps per target (Fly.io/Railway/AWS ECS/K8s/DigitalOcean/Render/VPS), Dockerfile, docker-compose, .env.example, branch protection guidance	Infrastructure files
/aaid-k8s	Full Kubernetes manifest set — Deployment, Service, Ingress, HPA, PDB, NetworkPolicy, ConfigMap, Secret template, kustomization.yaml	k8s/ directory
/aaid-debug	Structured root cause analysis for an error or bug	aaid_artifacts/implementation/[date]/debug-report.md
/aaid-explain-code	Step-by-step explanation of any code section — no file saved	Chat response only
/aaid-publish	Convert any artifact markdown to a formatted HTML document ready to print as PDF — default template, custom style, or your own template	aaid_artifacts/exports/[filename].html

Recommended Starting Flows

New project (greenfield):

/aaid-requirements → /aaid-architecture → /aaid-scaffold → /aaid-backlog → /aaid-dev-story (per story)

Existing / legacy project:

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

Launch preparation:

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

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

How slash commands work

Every command interviews you before generating output — it asks targeted questions one at a time rather than dumping a form. 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
Lint	Runs your stack's linter (eslint, ruff, phpcs, checkstyle) — zero errors required	High
Banned patterns	Language-specific anti-patterns: : any, @ts-ignore, eval(), dangerouslySetInnerHTML, v-html, SELECT *	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.