Free & open source · MIT licensed

Your AI writes code fast.
AIDD ensures it doesn’t break production.

A lightweight methodology and mechanical CLI that stops Claude Code, Codex, and Gemini CLI from hallucinating requirements and grading their own homework.

⭐ Star on GitHub
zsh — aidd
$ aidd check specs/001-auth/
[!] ERROR: Step 6 bypassed.
[!] require_independent_audit.py: Subagent audit missing.
[!] The implementer cannot grade its own homework.
--> Dispatched QA Subagent (UI & Security)...
--> Found 1 missing error handler in CTL-004.
 
$ aidd check-charter .
340 violation(s) across 6 rule(s) — relative imports (Art. 3.3)
 
$ aidd search "auth flow"
-> AMEND F02-Auth-Shell: reopen its spec — do NOT create a new folder.
Never the same agent that wrote it. Never a guessed requirement.
Search first. Ask first. Review independently. Every time.

Sound familiar?

AI coding agents are fast at writing code and bad at knowing what already exists. Left alone, they duplicate specs nobody asked for, ship fixes that fabricate success, and grade their own homework when asked to review it.

“I asked it to fix one button. It rewrote half the screen and I had to figure out what changed.”

Without a plan the AI checks itself against, “fix this” becomes “guess what else might need fixing too.”

“I've reviewed this same screen three times this month for basically the same reason.”

Mistakes found after the code is written cost a redo. AIDD finds them while the plan is still just a plan.

Is this actually for you? If two or more sound like your week, it is:

  • ✕Your AI tool creates something new every time, even for a tiny fix, instead of reusing what's already there.
  • ✕You've reviewed the same screen or feature more than twice for basically the same reason.
  • ✕Nobody on the team is sure which conversation or file has the “real” current requirements anymore.
  • ✕You've caught your AI referencing a screen, button, or database table that turned out not to actually exist.
  • ✕Your team uses more than one AI coding tool, and each one seems to “know” different things about the project.
  • ✕Your architecture rules live in a doc nobody's re-checked against the actual code in months.

How it works

One short routine, every request: check what exists → plan it out loud → build it in small pieces → independent review → compare to the design.

Step −1 / 0

Search first

Every request runs against a compact, auto-built graph of every existing spec before anything new gets created. A match means “amend this,” not “start over.”

Step 1 / 1.5

Audit the mockup, draw the flow

A mechanical pass inventories every screen, component, and control, then one Mermaid diagram per use case replaces paragraphs of prose — correct the diagram, don't describe the fix.

Step 2

Align

Every ambiguity becomes an explicit question for you before code is written, not something discovered after a review.

Step 3

Plan the Screen → Code map

A fresh agent drafts the naming contract and the Screen → Code / Component → Code maps against the real codebase. You approve the draft.

Step 4

Break into small-PR tasks

One screen, one component, or one behavior per task — never batched — each sized with a classify / estimate / decompose / assign rubric.

Step 5

Build, one PR at a time

Every PR ships against a four-part Definition of Done: code, a mapping row, a written-back PR reference, and a screenshot diff against the mockup.

Step 6

Independent review

A separate agent — never the one that built it — audits the result per domain (UI, backend, database, performance). On Claude Code this is a hard technical gate, not just a rule.

Step 7

Hand off the documentation

A comprehensive handoff doc is assembled from what already exists — reassembled, never re-explained.

Why AIDD, not just “write a spec first”

Plenty of workflows tell an agent to plan before it codes. AIDD’s difference is what happens when the agent is tempted to skip that — and what gets checked mechanically instead of trusted to memory.

Enforced, not just documented

A generic spec-driven process is a set of documents an agent is supposed to follow. AIDD's Step 6 independent-audit rule and its graph-coherence check are actual hooks on Claude Code (require_independent_audit.py, require_graph_coherence_audit.py) that hard-block a write until the rule was actually followed — not a convention trusted to memory.

A charter that's actually checked

Project-wide rules split into judgment calls (prose) and checkable ones (pattern + glob) that check_charter.py runs for real. Run against a real production project, it caught two stale “unused” claims in that project's own hand-written notes — both false — and a third rated low-severity that turned out to be 340 real violations.

Reusable components, not per-screen rebuilds

COMP-nnn codes are built once and referenced by every screen that uses them — like a component-based design tool assembling from a library — closing the “rebuilt three times, slightly differently” gap that pure narrative specs don't catch.

Full-stack traceable, not UI-only

A CTL-nnn control that triggers a network call cites the API-nnn it depends on, and contracts.md cites the control back. A backend change's blast radius on the UI becomes a lookup, not a grep across the whole codebase.

One methodology, every tool

skill/AIDD.md is the tool-agnostic core. Claude Code, OpenCode, and Codex read it natively; generate_adapters.py renders the same steps as native command files for Gemini CLI, Cursor, Windsurf, Cline, and GitHub Copilot — one source, no per-agent copy to keep in sync.

Ships to your actual tracker

An approved tasks.md becomes real, trackable issues in GitHub, Azure DevOps, or Bitbucket via tasks_to_issues.py — dry-run by default, never duplicates on re-run. Not another silo of markdown nobody opens again.

Built for teams, not just solo sessions

Approved tasks become real, trackable issues in the tracker your team already uses — never orphaned markdown nobody re-checks.

GitHub Issues

gh CLI, dry-run by default

Azure DevOps

az CLI + azure-devops extension

Bitbucket Cloud

REST API v2.0, app-password auth

aidd tasks-to-issues specs/001-login/tasks.md --provider azure_devops --org ... --apply

Frequently asked

Don’t see yours? Open a GitHub issue or discussion.

Is this a new AI agent I have to learn?+

No. AIDD is not a tool to learn — it's a set of habits your existing AI coding assistant follows for you. You keep using Claude Code, OpenCode, Codex, or Gemini CLI exactly as you do today; AIDD changes what that assistant does before, during, and after it touches code.

Do I need to install anything new?+

For Claude Code: copy skill/ to ~/.claude/skills/aidd and run python scripts/install_hooks.py once. For OpenCode, Codex, or Gemini CLI, a thin adapter points back to the same methodology core — nothing duplicated or relearned per tool.

Does it work in any language?+

The automatic prompt-level nudge covers English, Spanish, Portuguese, and a handful of literal Chinese trigger terms. Outside those, the pipeline still engages — the skill's description is matched semantically regardless of language, and the hard code-edit gate doesn't read the prompt at all.

Is the “independent audit” real, or just a rule in a doc?+

Both, depending on the tool. On Claude Code it's an actual technical gate: writing or updating qa-audit.md is blocked unless a separate subagent was dispatched after the last code edit. On other tools it's the same rule, followed the same way, without that specific lock yet.

Are the token-savings numbers real?+

Yes — measured, not estimated, by comparing a plain read of the relevant spec files against what AIDD's own lookup tools (find_spec.py, check_spec.py) report back, on a real working project. The exact reproduction commands ship in the docs.

Does AIDD replace code review or human judgment?+

No. It replaces the busywork of checking — searching for duplicates, re-reading whole files, grading your own fix — so a person's judgment gets spent on what actually needs it.

Is there a cost?+

AIDD itself is free and open source (MIT license). If your team wants help adopting it — workflow diagnosis, implementation, custom rules, training, ongoing support — every engagement is scoped individually. Open a GitHub issue to talk specifics.

Get in touch

Questions, bug reports, or just want to say hi? Send a message and it’ll open your email client, ready to go.

This opens your email client with the message pre-filled — nothing is sent automatically from this page.