aaidlc

v0.5.0

Published

12 hours ago

Agentic AI Development Life Cycle — specialized AI agents, enforced quality gates, and multi-LLM support for every phase of software delivery

0High
0Medium
0Low

beingdct

aaidlc ai sdlc agents claude openai gemini ollama quality-gates agentic developer-tools code-quality software-engineering

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.

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

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