AIDD — AI-Driven Development

Self-contained: everything needed to run this is in this file. It doesn't require any other skill to be installed, and it doesn't call out to one.

Environment adaptation — one file, every host

This file is host-agnostic on purpose: the same copy adapts to whichever tool loaded it. Read this block once and apply it to every instruction below.

0. If your load came back truncated — you see something like showing lines 1-318 of 732, or the body stops mid-sentence — your host caps tool output (about 50 KB, this file is ~110 KB) and most of this skill never reached you: everything past that cut includes the whole Pipeline (Steps -2 through 7), Engineering standards, Memory and File structure. Read the remainder of <AIDD_HOME>/SKILL.md from the truncation point on, before planning or implementing anything. Do not work from the visible fragment — a half-loaded skill is worse than none, because the missing half is the part that says what to do.

1. Detect your host from the tools you actually have, not from the folder you were installed in:

From here on, AskUserQuestion means "the host's ask-the-user tool" and Agent tool / Task tool mean "dispatch a separate subagent" (the Workflow tool does too, but its subagents are not recorded by AIDD's hooks, so never use it for Step 6 auditors) — substitute your row. Step 6's independence rule is about context isolation, not about a product feature: a different agent audits what you built; if the host has no subagents, do it as an explicitly separate pass over the diff with the implementer's reasoning withheld.

2. Resolve <AIDD_HOME> before running any command below. It is the folder containing this SKILL.md:

• Claude Code → ~/.claude/skills/aidd
• OpenCode → the Base directory for this skill: line, if one was printed — on a skill this size the host truncates the body before it ever reaches the footer, so assume it is missing: check .opencode/skills/aidd, then ~/.config/opencode/skills/aidd, then ~/.claude/skills/aidd (OpenCode's compatibility source), and keep the first that exists and whose SKILL.md contains ## Environment adaptation.
• any other host → wherever you copied this folder

Never paste the literal token <AIDD_HOME> into a shell — substitute the resolved path. If no copy can be found, stop and ask where the skill was installed instead of guessing a path.

3. Enforcement degrades by host; compensate with the CLI, not with memory:

The rules (R1–R12) are identical on every host — only who checks them changes. Rows and sections marked Claude Code only (hooks, evidence log, SessionStart / Stop) describe machinery that host has; they are not a requirement elsewhere, and their absence does not waive the rule behind them.

Installation — by host

Claude Code — full enforcement (recommended, one-time per machine)

AIDD ships with hooks that make it hard to skip. After copying this skill folder to <AIDD_HOME> (~/.claude/skills/aidd) on any device, run once:

python <AIDD_HOME>/scripts/install_hooks.py

This merges eleven hook entries (twelve with the opt-in memory hook) into ~/.claude/settings.json (idempotent — safe to re-run, never duplicates or touches unrelated hooks already configured there):

Evidence durability. An evidence append that cannot take the log lock retries with a short backoff, then spills the row to <log>.spill (merged back by the next reader) and records hook_error, instead of dropping it. An approved spec counts as open even before any plan.md/tasks.md edit was recorded, so it can be closed or abandoned.

Scope: global, every Claude Code session on this machine. Loosen it by editing hooks/require_aidd.py's is_code_file check or hooks/prompt_trigger.py's keyword list.

Uninstall: remove the hook entries from ~/.claude/settings.json by hand.

OpenCode — aidd install --host opencode

OpenCode discovers the skill by itself; the gate needs one command (aidd install --host opencode [project], then aidd doctor --host opencode):

• Compatibility source: OpenCode deliberately reads ~/.claude/skills, so the Claude Code install above is picked up in OpenCode with zero configuration — same folder, same scripts, same paths.
• Native source (optional): copy this folder to ~/.config/opencode/skills/aidd/ (global; higher precedence than the compatibility source) or .opencode/skills/aidd/ (project). Whichever copy ends up loaded becomes <AIDD_HOME>.
• Enforcement layer: aidd install --host opencode copies the plugin to .opencode/plugins/aidd.js and appends it once to the plugin array of .opencode/opencode.json. tool.execute.before sends write/edit/multiedit/patch/bash events through .aidd/hooks/host_adapter.py to rule_gate.py; a block is a thrown error carrying the gate's message. The registration files are protected (R9). Not yet verified against a real OpenCode binary; the once-per-session reminder was dropped.

Gemini CLI — aidd install --host gemini

aidd install --host gemini [project] copies .aidd/, writes GEMINI.md and merges BeforeTool/AfterTool hooks into .gemini/settings.json (exit 2 blocks; the hook command path is relative and not yet confirmed against a real binary). Check with aidd doctor --host gemini. Owner approval: aidd review <spec> --wait, then aidd rules approve <spec>.

Codex Desktop — project or user skill; AIDD gates are manual unless verified

Codex discovers repository skills from .agents/skills/ and user skills from ~/.agents/skills/. Install this folder at .agents/skills/aidd/ for one repository or ~/.agents/skills/aidd/ for the user. Keep the skill's scripts, hooks and templates alongside SKILL.md; do not install only the Markdown pointer when using this full package. Put project-wide always-read instructions in AGENTS.md and point them to the skill.

Windows fallback when aidd is not in PATH: use the user's installed Python and the scripts in the user's installed skill. Do not ask for, guess or search for the AIDD source checkout. In PowerShell:

$AiddPython = (& uv python find 3.14).Trim()
$AiddScripts = Join-Path $HOME '.agents\skills\aidd\scripts'
& $AiddPython (Join-Path $AiddScripts 'aidd_graphs.py') list
$Query = 'keywords or codes'
& $AiddPython (Join-Path $AiddScripts 'find_spec.py') $Query
& $AiddPython (Join-Path $AiddScripts 'aidd_status.py') status

Use aidd_graphs.py show <graph> <query> for graph-first code/method lookups and aidd_status.py rules check <spec> for rule checks. If uv python find is unavailable, select an interpreter already installed for the user (py -0p, then py -3, or python if present) and use the same user-skill script paths. Check the actual error before concluding Python is missing: an Access denied when launching a user-profile interpreter is a sandbox permission boundary, not proof that the file or installation is absent. Use the host's approved way to run that user-installed interpreter; do not substitute the Codex source tree or a stale hard-coded path.

The Codex native hook runtime is separate from Claude hooks. Codex reads project hook configuration from .codex/hooks.json or .codex/config.toml, and the project layer must be trusted. Non-managed hooks also require review/trust in Codex. AIDD's install_host.py currently does not install a Codex host adapter, so do not infer that Claude hooks or .agents/hooks.json enforce AIDD in Codex. Until a Codex registration and adapter are installed and observed working, run aidd rules check <spec> before code edits and aidd status before ending the session; when aidd is absent from PATH, use the user-skill script fallback above. If Codex hooks are configured, verify their trust and live pre-hook denial: documented hook errors, timeouts or malformed results may let the tool run, and a post-hook cannot undo a completed operation. See Codex skills and Codex hooks.

For hosts without an AIDD adapter (including Cursor, Windsurf, Cline and Copilot), pip install aidd-cli && aidd init <project> drops the portable .aidd/ bundle (methodology + find_spec.py / check_spec.py), and aidd adapters generate <target> <project> renders that host's native command files from commands/aidd-*.md. The always-read layer is AGENTS.md (plus GEMINI.md for Gemini). See adapters/README.md.

Hard rules — enforced by hooks on Claude Code, self-checked elsewhere

The pipeline's rules used to live only in prose, and a real run skipped most of them. Each is now a rule a hook enforces (contract: specs/002-aidd-hard-rules/spec.md):

Every block message names the next action (which artifact, which command, which question to ask the user).

Evidence, not trust. Hooks append what they observed (the agent is not supposed to write it). SESSION kinds go to a per-session log under <tempdir>/aidd-hooks/evidence/<session-id>.toon; PROJECT kinds go to <project>/.aidd/evidence/events.toon (git-ignored, append-only). Rules fail closed on missing evidence and open on a hook crash.

Answers are anchored, not guessed. Approval, close and abandon are accepted only from a recorded answer whose chosen label is one of the options the question OFFERED — the agent must offer exactly "Approve" (tasks), "Yes, close" (close) or "Abandon" (abandon). The approval question must contain the tag [tasks:<hash8>] — the first 8 hex chars of the current approval_hash of tasks.md.

Open specs, not "the active spec". A spec is open from the first recorded edit of its plan.md or tasks.md until a spec_closed event. R7 and close apply to EVERY open spec in every project root above the file being written; R6 and the blocking part of R8 apply to the gate target (see R6), the other approved open specs only get a one-time reminder. A spec stops being open only via aidd rules close <id> or aidd rules abandon <id>.

Commands (also usable from a terminal or CI): aidd review <spec_dir> (generate the compact review.html; --full, --wait, --check, --comments, --summary), aidd verify <spec_dir> (execute ## Verification), aidd progress [--detail] (implementation % per spec from the tasks' Target files, measured with no LLM and no third-party graph, plus the approved/verify/audit/closed stages; run it instead of writing your own script to count progress), aidd rules activate <id> (set the gate target), aidd status [spec_dir] [--json] [--refresh] lists ALL open specs with their approval state and WHY blocked lines. aidd rules check <spec_dir> prints PASS\|FAIL Rn message → fix and exits 1 on any violation. aidd rules approve <spec_dir> writes the Approved: line only with the user's recorded answer "Approve". aidd rules close <id> needs an open spec, a valid recorded approval, qa-audit.md, every required domain audited and the recorded answer "Yes, close". aidd rules abandon <id> needs the recorded answer "Abandon". check_spec.py also reports the static rules (R1–R4, R6, R10–R12) as gaps.

Task state in aidd progress and aidd pending (spec 007, amendment 04). A Target written <path> (delete) is done when the file is gone and missing while it still exists (task_state reads the delete key that parse_tasks returns). A migration whose numeric prefix changed resolves to the single project file with the same name after the prefix; two or more candidates stay missing, never guessed. An optional graph .aidd/graphs/path-aliases.toon (section aliases[N]{old,new,scope,reason}:, base names, rows indented two spaces) maps a renamed file to its new name. A target resolved by renumbering or alias gets the state renamed, counts as present in Impl%, and aidd progress --detail lists it. Alias graph registration and explorer (spec 007, amendment 06). When .aidd/graphs/path-aliases.toon exists, aidd_graphs registers graph name aliases of kind aliases pointing to file .aidd/graphs/path-aliases.toon. Query and visualize with aidd graphs show aliases <name>, aidd graphs explorer aliases and aidd graphs explorer (the unified explorer shows it as the layer aliases). The graph model exposes node types alias_old and alias_new connected by directed edge RENAMED_TO.

Executed evidence, not textual (Definition of Done, R10). A ✅ on a screen, API or field means it was RUN: a screenshot on the real device, or the output of the command/query, saved as a file and cited in ## Execution evidence. Reading the code is not evidence. Before claiming there is no device, run adb devices (or the platform equivalent) and record the output in ## Device preflight of qa-audit.md. If it truly cannot be run, write not-verified, write a human test script the user can follow, and keep the Status ⚠️ PARTIAL; never claim done.

Root cause and pattern sweep (R11). From the second report of the same bug, find why it failed again and sweep the codebase for the same pattern before fixing; the third report is a redesign, not another patch.

Acceptance cases and Align. spec.md carries ## Acceptance cases (Case | Real data (id) | Expected | Edge?): written before building, with real record ids and at least one edge. The optional ## Optional Align questions (states, permissions, entry route, target devices) sit outside the 7-row checklist; blank means not asked.

Credential hygiene. The evidence log stores prompts, answers and subagent prompt heads with password|token|secret|api key|bearer-style key=value pairs replaced by key=[redacted], and the hook warns when it redacts. Never copy a secret into a file, spec, memory entry, command or log; reference it by variable name.

Visual fidelity is measured, not inferred (amendment to spec 007; applies to Step 6, R10 and every visual verification task, e.g. T-VISUAL). Closing a UI needs real visual evidence MEASURED against the prototype: same h1, every CTL/COMP of the prototype present, same columns, skeletons at least as many as the prototype. A green unit/component suite is NOT fidelity evidence (measured in b1SycLink F38: vitest 258/258 passed while 32 of 32 states differed from the prototype). Without the measured comparison the screen stays ⚠️ PARTIAL.

R10 freshness is best-effort. Existence, kind and status checks are firm; freshness is not: (a) edits made through PowerShell/Bash are not recorded, so evidence made stale that way passes; (b) only code extensions are recorded, so edits to .json/.xml/.html/.css/.yml/.xaml are invisible; (c) code edits carry no spec attribution, so any recorded code edit in the session makes all file evidence stale; (d) http(s):// evidence has no mtime and is not checked; (e) file mtime resets on git checkout or copy.

check_spec.py gaps G1–G6 (each only when the artifact exists): G1 a control with an Action in mockup-audit.md needs Destination, Data source and States; G2 spec.md needs Acceptance cases with at least one edge; G3 every traceability.md row needs Mockup field, Room/store, DTO, API, SP and Filled-by; G4 contracts.md needs a stamped Contract hash: equal to the table's recomputed hash (run python check_spec.py <spec_dir> --stamp-contract once the contract is settled; re-stamp after changing it); G5 a component used in a screen needs Consumers in components-index.md; G6 two task rows name the same Target file unless one says same owner as T-nn.

Compact hook output. Hook output to the model is intentionally compact: the full pipeline hint is sent once per session and find_spec output is reduced to verdict lines.

Escape hatch (last-resort diagnostic, owner only): AIDD_RULES=off|0|false|no|warn is not a workflow. Set in the env block of ~/.claude/settings.json (Claude Code) or exported in the session environment (any other host), it disables or softens the gates, is recorded as rules_override and is shown by aidd status, so it stays visible. If you reach for it, fix the scoping instead: aidd rules activate <id> for the spec you are working on, aidd review <id> then aidd rules approve <id> for approval. aidd status --refresh recomputes git and disk facts (branch, dirty files, review, verification and gate state) without any LLM. check_spec.py prints STRUCTURAL CHECK ONLY - nothing was executed: zero gaps there never means the spec works; aidd verify is what executes it.

Limitations. (1) Bash and PowerShell can still edit code — the code gate covers Write/Edit/MultiEdit/NotebookEdit; the shell tools are only checked for writes into protected paths. (2) Through Bash/PowerShell an agent can try to forge evidence; the guard is lexical, not a sandbox. (3) The gates verify that a subagent ran and a question was answered, not that they were any good. (4) The user's click cannot be cryptographically proven. (5) Hooks fail open on a crash or timeout. (6) R8 relaxes after 3 blocks per approval hash. (7) Session ids and resume behaviour are not verified. (8) A user quote is checked against what was recorded, not for whether it means what the agent claims. (9) A spec stopped at spec.md is not open. (10) Code can be planted under exempt locations (.git/hooks, node_modules/, specs/). (11) repo — sources only prove that the file exists, not that it is relevant. (12) The shell guard has false positives (cp … specs/…): use the Write tool for those. (13) Session attribution is inferred: before any Bash/PowerShell command that invokes aidd, rule_gate writes a caller marker (<tmp>/aidd-hooks/caller-<sha1(root)>.json, {session, ts}); the CLI prefers a marker younger than ~120 s for the same root, else the newest non-synthetic prompt (not starting with < or [). Refusals name the inferred session. With several concurrent windows the inference can still be wrong; it then fails closed. In short: the rules stop accidental and self-justified skipping; they do not stop a determined agent.

Problem this solves

UI work tends to take several corrective passes instead of landing right the first time. The root cause: the visual truth (mockup / design system) gets pinned down loosely or late, relative to when code gets written. The fix: front-load 100% of the visual truth into stable codes before any implementation task exists, size every task to one small PR pinned to one code + one file, and gate each PR's "done" on three things together (code, mapping row, screenshot diff).

The code system

Assign these the moment you first read the mockup, and never rename them:

COMP-nnn is what's missing if you only track whole screens — the same card appearing on several screens is one component, built once, referenced by every SCREEN-XX that uses it. A SCREEN-XX row lists the COMP-nnn it's composed of; a COMP-nnn row lists which CTL-nnn live inside it and which screens use it.

Full-stack features: a CTL-nnn that triggers a network call cites the API-nnn it depends on in the control inventory (Step 1) — that's the traceability link between "this button" and "this contract."

Every later artifact (spec, task, code comment, checklist) cites the code — never a redescription of the UI. If this project's work is already tracked elsewhere under its own codes, use those instead of minting new ones — never run two numbering systems for the same screen.

Templates

Every artifact below has a real starting skeleton in this skill's own templates/ folder — don't reconstruct a table from memory each time:

<AIDD_HOME>/templates/
├── STATE.md                  # project-root continuity file — copy once per project, read first always
├── mockup-audit.md
├── visual-flow.toon
├── spec.md                   # Step 2 — Minimum Requirements Checklist + functional requirements
├── contracts.md              # API-nnn contracts — only for full-stack features
├── data-model.md             # entities/relationships — only when the feature adds/changes data
├── research.md               # technology decisions worth recording — optional, keep short
├── plan.md
├── tasks.md
├── qa-audit.md
├── comprehensive-documentation.md
├── charter.md            # project-root, not per-feature — see "Project charter" below
└── design-system/
    ├── MASTER.md              # global visual source of truth (Step 0, no-mockup case)
    ├── page-override.md       # per-page/per-screen exception to Master
    └── components-index.md   # project-wide COMP-nnn registry — check before minting a new one

<AIDD_HOME>/scripts/
├── check_spec.py              # mechanical gap-checker — run before the Step 6 Auditor reads by hand
├── check_charter.py      # runs charter.md's checkable rules
├── flowmap.py                 # Step 1.5 — visual-flow.toon → interactive actors×processes HTML + generated pseudocode
├── research_project.py        # [optional, one-time] proposes candidate spec areas on a brownfield project with no specs/ yet
├── aidd_memory.py             # AIDD Memory — code-anchored WHY in .aidd/memory/
├── aidd_memory_import.py      # [optional, one-off] read-only importer from a claude-mem SQLite file
├── tasks_to_issues.py         # turns an approved tasks.md into real tracker issues (dry-run by default)
└── providers/                 # github_provider.py / azure_devops_provider.py / bitbucket_provider.py

Project charter

One file, project-root, not per-feature. Copy templates/charter.md once per project — it's what every spec inherits without restating it: locked stack decisions, and project-specific rules. The template splits rules into prose (judgment calls) and a Checkable rules table (Rule | Type (forbidden/required) | Pattern | Applies to (glob)) that scripts/check_charter.py runs for real — forbidden fails if the pattern appears anywhere under the glob, required fails if it appears nowhere.

python <AIDD_HOME>/scripts/check_charter.py [project-root]

Run this alongside check_spec.py before Step 6 signs off — the charter covers project-wide invariants, check_spec.py covers one spec's own internal consistency.

Research mode — bootstrapping specs when none exist yet

Run this once, at the same time as copying templates/charter.md, on a brownfield project that has real code but no specs/ folder yet. Step -1's find_spec.py can only search specs that already exist; a project with none has nothing for the spec graph to index.

python <AIDD_HOME>/scripts/research_project.py [project-root]

It's a mechanical, stdlib-only directory scan — no LLM, no file content read — that looks for route/page/screen/controller-like directories and prints a numbered list of candidate specs/[###-slug]/ areas, largest first. It never writes a spec or invents content. Once the list is in hand: drop the noise, then run Step 0 through Step 2 per area kept.

Spec graph — and why it stays cheap

find_spec.py's index (specs/index.toon) is AIDD's knowledge graph. It's derived from specs the project already maintains, not from re-reading source code: find_spec.py parses mockup-audit.md's own tables into a US-nnn → SCREEN-XX → COMP-nnn → CTL-nnn → API-nnn DAG, using plain regex/markdown-table parsing — stdlib only, zero LLM calls, zero tokens. Rebuilding it costs a stat() per spec file and, only for files that actually changed, a re-parse of that one file.

This is a trade, not a strict improvement: AIDD's graph can only describe what a spec already documents — it has nothing to say about code with no spec behind it. That's exactly what Research mode exists to bootstrap on a brownfield project.

Graph coherence — multiagent verification

Cheap and mechanical is not the same as correct. find_spec.py parses mockup-audit.md's tables with regex — it can misread a malformed row, silently drop an edge when a code gets renamed, or carry over a relationship a manual edit meant to remove. A mechanical parser can never catch its own semantic mistakes.

When it runs, and who runs it: there is no separate Graph Coherence Auditor any more. The ONE pre-build coherence audit — a fresh agent (model: sonnet, never a fork) over spec, plan, graph and estimates, dispatched before tasks.md is approved — absorbs it, and no subagent is demanded after each spec.md/plan.md edit. Scope it to the spec(s) find_spec.py named as changed. Its graph checklist:

• Every SCREEN-XX cites a COMP-nnn/CTL-nnn that actually exists in that spec's own inventories.
• Every CTL-nnn that calls an API-nnn has that API-nnn actually defined in contracts.md (or explicitly flagged [Not Verified]).
• No two specs silently claim the same COMP-nnn/CTL-nnn number for different things.
• The tree find_spec.py --tree <spec-id> prints actually matches the use case the spec's spec.md describes.

This is enforced by hooks, not left as a step someone might skip — writing tasks.md is blocked (exit 2) until an independent subagent has run after the last spec/plan/tasks edit or graph rebuild.

Issue tracker integration — GitHub, Azure DevOps, Bitbucket

Once Step 4's task list is approved, scripts/tasks_to_issues.py turns each task row into a real tracker issue. Defaults to a dry run; a .aidd-issues.json file next to tasks.md tracks what's already synced, so re-running never duplicates issues.

Three trackers, one script, one flag — --provider {github,azure_devops,bitbucket} (default github). Each provider is a small stdlib-only module under scripts/providers/ implementing the same two-function contract (available(), create_issue()).

# GitHub (default) — gh CLI must be installed and authenticated (gh auth login)
python <AIDD_HOME>/scripts/tasks_to_issues.py specs/[###-feature]/tasks.md --apply

# Azure DevOps — az CLI + azure-devops extension, az login done ahead of time
python <AIDD_HOME>/scripts/tasks_to_issues.py specs/[###-feature]/tasks.md \
  --provider azure_devops --org https://dev.azure.com/myorg --project MyProject --apply

# Bitbucket Cloud — REST API v2.0 directly (urllib, no extra dependency)
python <AIDD_HOME>/scripts/tasks_to_issues.py specs/[###-feature]/tasks.md \
  --provider bitbucket --workspace myworkspace --repo-slug myrepo --apply

--org/--project (Azure DevOps) and --workspace/--repo-slug (Bitbucket) also read from AZURE_DEVOPS_ORG/AZURE_DEVOPS_PROJECT/BITBUCKET_WORKSPACE/BITBUCKET_REPO_SLUG env vars.

Speed: what actually cuts time-to-correct-result

Run the checker before the Auditor reads anything by hand

python <AIDD_HOME>/scripts/check_spec.py specs/[###-feature]/

It greps the spec folder for mechanical gaps — dangling codes, unresolved [Not Verified], empty PR/Spec ref, orphaned COMP-nnn, missing stored-procedure/exception pairs, blank qa-audit.md statuses — in milliseconds, and exits non-zero if it finds any. Run it ONCE before the closing audit and after the last spec/plan/tasks edit, so the Auditor does not spend judgment re-reading the whole spec; never before every manual pass.

Check the project's Component Index before minting a new COMP-nnn

Keep one project-level design-system/components-index.md (not per-feature) listing every COMP-nnn ever created, its file, and which specs/screens use it. Check it in Step 1 before creating a new component.

Wave-dispatch approved tasks instead of running them one at a time

Group the approved tasks into waves — same-wave tasks touch disjoint files and have no ordering requirement between them — and dispatch every task in a wave as parallel subagent calls in one message, not one call at a time.

Take the fast lane for a small, contained change

Fast lane conditions (all must hold): touches exactly one existing SCREEN-XX, no new US-nnn, no new COMP-nnn, no navigation change. When they hold: skip visual-flow.toon and comprehensive-documentation.md entirely, amend mockup-audit.md and qa-audit.md directly, and run it as a single task with the same four-part Definition of Done. The moment any condition stops holding mid-work, stop and go back to the full pipeline from Step 1.

S1 — Automation first, parallel agents, never hand-estimate (working rule, applies before ANY estimate or proposal)

Before you quote a duration, a cost or "this needs N hours", run this check and quote the result of it, not the manual path:

1. Can a tool do the heavy part? A script, a catalog or metadata query (information_schema, pg_depend, git, the compiler/AST, a parser), a generator, a codegen, an existing runner or the aidd CLI. If yes, the estimate is the SCRIPTED path (write the script, run it, check coverage). Work done by hand or by an agent row by row (per column, per file, per record) is the exception and the plan must say why a tool cannot do it.
2. What is independent? Everything without a true dependency runs at the same time: dispatch the agents of a wave in ONE message (one owner per file), fan out read-only searches/audits to separate agents, and run long jobs (aidd verify, builds, suites, DB extraction) in the background while other independent work continues. Never serialize what has no dependency and never idle-wait on a job you can overlap.
3. Report wall time, not effort. Quote the automated, parallel wall time and tokens; keep hand-hours only as the derived Human ref. If the user questions a long estimate, that is a signal the check above was skipped: redo it instead of defending the number.
4. No idle waiting, no parallel stall. Never schedule a timed re-check ("I'll look again in 30 minutes") when nothing is running: if every remaining item needs the user, list them once and stop. A real background job reports by completion notification or a monitor, not by a timer. While a long job runs (aidd verify, a build, a graph refresh) keep working on everything outside it, or prepare the next step (auditor prompt, drafts, the other spec). To make that safe, declare Scope: auto (this spec's Target files from tasks.md; add inputs it reads, e.g. Scope: auto, db/migrations/**) or explicit globs under ## Verification: only edits inside the scope (and its own code edits) can make that verification stale or unstable, so another spec can be built in parallel; without a Scope the whole tree counts. Two heavy builds at once is still the exception (memory), but verifying one spec while editing another is not. Record the outcome in the spec's ## Optimization brief (which tool does the heavy lifting, which tasks fan out) and in tasks.md (Agent role: / waves). This is guidance, not a gate: it never blocks, but a plan that estimates manual work where a tool or parallel agents exist is a defective plan.

G1 — Structure graphs: use them, keep them fresh in the background (never mandatory, never blocking)

AIDD provides a built-in graph registry. In this repo, aidd graphs list reports the active layers: the code graph is .aidd/graphs/code.json, the methodology graph is .aidd/graphs/method.json, the spec graph is specs/index.toon, and progress is derived from spec task targets. Other projects can declare additional database or UI graphs. Use aidd graphs list and aidd graphs status to see what is actually configured; an optional external graph integration does not mean AIDD itself uses that tool. Rules: 0. Automatic, no questions. find_spec.py (Step -1, which the prompt hook runs for you) already starts the background refresh of every project graph that is missing or stale and prints the nodes that match your query, exactly like the spec graph. If the project has a database, its DB graph is therefore part of every lookup; never ask the user whether to use it.

1. Always validate the graphs first. To look up a field, a table, a function, a screen or a spec, the FIRST action is the graph tools (find_spec.py, aidd graphs show <name> <name-or-keyword>: one node and its neighbours in at most 25 lines); only then read the few lines they point to in SQL, migrations or source. Reading files first is the exception and needs a reason. aidd graphs explorer <name> writes a single-file HTML explorer of one graph; aidd graphs explorer with no name writes docs/graphs/explorer.html (versioned), the unified explorer of every registered graph: each graph is a layer with its own colour, count and checkbox, and a graph added to the registry appears there with no code change. Above 25 MB nothing is written (exit 3): pass --skip <name> or --max-mb N; every regeneration adds a blob to git history, so regenerate on demand only.
2. Refresh in the background, never wait. A spec whose tasks touch the database (migrations, tables, functions, RLS) or the UI structure should start aidd graphs refresh <name> --background at Step 3 and keep working; a hook also does it when a watched file is edited (Watch globs of the charter's ## Graphs table). Do not poll or block on it; query again when aidd graphs status says fresh. AIDD_GRAPHS=off disables the hook.
3. No graph declared? With SQL migrations present, AIDD builds one with no database (builtin:sql); otherwise a project can declare its own generator in the charter. Tools first (rule S1): never rebuild by hand what the generator produces.
4. Built-in graphs (aidd:FR-014, aidd:FR-029). code (builtin:code, Python via ast), method (builtin:method, this methodology: rules, steps, commands, templates), spec (builtin:spec), db-schema (builtin:sql-schema) and db-dml (builtin:sql-dml). All are incremental by content hash (never mtime); aidd graphs status shows each one's freshness. AIDD's native layers do not call an external graph tool; a project-declared external code row is renamed code-<tool> so it cannot shadow the built-in.

5. Graph commands (aidd:FR-017..FR-023).

   • aidd graphs repeats [--cmd <subcommand>]: sinks and calls reachable by more than one path or inside a loop (the same step running several times).
   • aidd graphs trace -- <aidd command>: runtime overlay of that command's real calls onto the code graph.
   • aidd graphs snapshot <name> --label <L>: canonical snapshot with its sha256 logged in the evidence log.
   • aidd graphs diff <A> <B>: added/removed nodes and edges plus metric deltas between two snapshots; refuses an altered snapshot.
   • aidd graphs changed --spec <id>: files whose content differs from the <id>@open baseline.

   Any before/after comparison cites aidd graphs diff <A> <B> and both snapshot hashes, never hand-edited files. Tamper-evidence means an edited snapshot or a missing event is detected; it does not mean shell access is prevented.

W1 — Graph first, filter first (working rule for every agent, subagents included)

Before reading any file, ask the graph and filter; read only what the answer points to.

1. Graph first: python <AIDD_HOME>/scripts/find_spec.py <keywords|code> and --tree <spec-id> return the spec, use case, screen, component, control and API relations without opening any spec file. python <AIDD_HOME>/scripts/find_spec.py --code <CODE> returns one node with its neighbours (tasks, requirements, acceptance cases, API, memory) and file:line in at most 25 lines. Memory the same way: aidd mem search, then aidd mem show <id> for the one hit you need.
2. Filter, never dump: grep -n / rg for a code or symbol, sed -n 'A,Bp' or Read with offset/limit for a range, | head, | cut -c1-200, wc -l before opening. Never cat an evidence log (events.toon), an index, a *.sql or a whole spec.md/plan.md/contracts.md to check one fact.
3. Whole-file reads are the exception: only the file you are about to edit, or Step 1's own exhaustive pass. State why in one line.
4. Auditors get a scope, not the world: hand each auditor the changed codes, the files in the diff since the last audit and the check_spec.py report. It reads the rest through the graph and grep.
5. Audit once per phase: collect the fixes first, then run one auditor per required domain. R7 tolerates the last AIDD_R7_FIX_EDITS code edits (default 3; 0 = strict), so a small fix after an audit does not force a re-audit. Build phases carry no per-domain audits: audit once, at close, with one auditor per required domain dispatched together (see Close sequence).
6. The nudge covers every search (aidd:FR-025..FR-027). The graph-first hint fires on Read, Grep, Glob and Bash/PowerShell searches of project code or specs, not only on spec reads. Only a graph query run BY THE AGENT silences it, for 300 s (find_spec.py, aidd graphs show|repeats|changed|status, aidd search|tree); the prompt hook's own automatic find_spec run never does. Every nudged search is counted as a miss and aidd status prints graph-first: N misses / M searches.

Grep first — never read a whole file to check one code

Every code (SCREEN-XX, CTL-nnn, COMP-nnn, API-nnn, US-nnn) is a search key by design. To check whether a code exists: grep -n "CTL-057" specs/[###]/mockup-audit.md, not a full read. To find where a screen is implemented: grep its PR/Spec ref cell or the code marker in source. To audit, use scripts/check_spec.py's report as the first source of truth. The one legitimate exception is Step 1's own audit pass — it is exhaustive by design, once.

Code markers — make source code itself greppable. aidd:CODE inside whatever comment syntax the language uses (// aidd:CTL-057, # aidd:SCREEN-08, <!-- aidd:COMP-003 -->). One grep pattern then finds the mockup-audit row, the plan.md mapping, and the exact source line together.

Keep a per-project STATE.md — don't re-investigate after losing context

One small, always-current file at the project root: STATE.md, copied from templates/STATE.md. Read it first, in full, before touching anything else. It holds: which spec is active and at which step, the last action taken, the next action to take, and pointers into the spec files that matter right now. Every step that changes what's true updates STATE.md with a short edit, not a rewrite.

At the start of each step, copy the matching template into the spec folder and fill it in — don't hand-write the table headers from scratch. contracts.md, data-model.md, and research.md are conditional — copy them only when the feature actually has a backend/data component.

Specialized agents & workflow

Each step below has a natural agent boundary. Step 6's Auditor must not be the same agent that did the implementing — an agent that just wrote code is structurally bad at spotting its own gaps.

This is a description of the discipline, not a requirement to use any specific tool — apply it with whatever mechanism is already in use as long as the Step 6 independence rule holds.

Step 6 dispatch rule (Claude Code): launch the closing auditors with the Agent tool, all in ONE message so they run in parallel, and only after the full verification has passed (it runs alone, before any auditor). Do NOT use the Workflow tool for them: the dispatch hooks match Task|Agent only, so workflow-spawned auditors are never recorded and the close gate does not count them.

Engineering standards — restate these in every agent's instructions

SOLID (applies to any code touched, not only new files)

Single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion. If a change makes a class do two jobs, split it.

Shared-First & Component-Driven Development (CDD) — eradicate code duplication (DRY)

• Shared-First Mindset (Obligatory): Assume a shared component library or Monorepo exists. Prioritize extending, modularizing, or reusing shared components over isolated/duplicate implementations.
• Abstraction Criterion: Separate repeated or reusable UI/presentation logic into atomic or compound components immediately.
• Flexible Design (Inversion of Control): Use Compound Components, composition via children/slots, and configurable props with sane defaults. Avoid monolithic blocks, repeated inline styles, and tightly-coupled components.
• Response Format for UI / Presentation: Structure any UI solution in 3 steps: [AUDITORÍA DE REUTILIZACIÓN], [PROPUESTA DE COMPONENTE COMPARTIDO], and [IMPLEMENTACIÓN LOCAL / EXTENSIÓN].

Naming contract — declared once in plan.md, never assumed

Every new class/function/component gets its name from the Mapper's plan.md mapping. Never invent a name locally and hope it matches.

Antifragile / Design for Failure — assume everything can fail

Every external call (network, disk, subprocess) can fail. Handle the failure explicitly — retry with backoff, circuit breaker, or graceful degradation. Never let an unhandled exception crash the user's workflow silently.

Data access & frontend↔backend communication — fixed rules for full-stack work

• The frontend never constructs SQL or touches the database directly.
• All API calls go through the API-nnn contract defined in contracts.md.
• Errors from the backend are surfaced to the user in their language, not as raw stack traces.

Database design, connections & indexing — fixed rules for anything that touches a database

• Use connection pooling; never open a connection per query.
• Every table has a primary key; every foreign key is indexed.
• Migrations are versioned and reversible.
• Stored procedures are verified against the engine's query plan before being called hot.

Memory — the WHY, anchored to codes

Decisions, rejected options, bug root causes and constraints go into .aidd/memory/ as curated, code-anchored entries, committed with the code. Search is progressive: aidd mem search returns one line per hit, aidd mem show <id> the full row.

Capture points — the agent runs aidd mem add ... (or python <AIDD_HOME>/scripts/aidd_memory.py add ...):

• A decision was made and the reason is non-obvious.
• A rejected option that might be proposed again.
• A bug root cause that isn't visible in the code.
• A constraint that shaped the design.

Automatically, Claude Code only — memory_context.py injects a short digest at session start. memory_file_context.py injects entries that mention a file the first time it is touched (opt-in). aidd mem file <path> is the on-demand equivalent. Both are silent when there is no .aidd/memory/.

Pipeline

spec.md carries a ## Pipeline route table | Step | Status | Reason | Confirmation | with one row each for -1, 0, 1, 1.5, 2, 3, 4; Status is run|waived|done, a waived step needs a Reason and user — "<quote ≥ 3 words>". Visual debt (R4) is declared, never silently skipped.

Step -2 — Project setup (one-time, before the first feature)

Copy templates/charter.md to the project root (see "Project charter" above). Run python <AIDD_HOME>/scripts/check_charter.py [project-root] alongside check_spec.py before Step 6 signs off.

Step -1 — Intake: classify, then search before creating

python <AIDD_HOME>/scripts/find_spec.py <keywords or a SCREEN-XX/CTL-nnn/COMP-nnn/API-nnn code>

Exit 0 → inspect the top candidate and its sources before classifying an amendment; a ranked match is not proof. Exit 1 → no candidate found, not proof of absence; check relevant specs and naming variants before creating a spec. find_spec.py --tree <spec-id> prints that spec's use-case → screen → component → control → API graph. State the classification before proceeding: AIDD intake: NEW SPEC | AMENDMENT | AMENDMENT — Fast Lane — <reason>.

Step 0 — Visual source of truth (once per feature; skip if no visual surface)

Pin the mockup/design system before any task exists. If the feature has no visual surface, skip entirely.

Step 1 — Mockup Audit (one pass, mechanical, no prose)

Assign codes the moment you read the mockup, never rename them. Fill mockup-audit.md: Screen/Component/Control inventories + ## Visual debt table. Check the project-level design-system/components-index.md before minting a new COMP-nnn.

For a new visual audit, record a project-relative local snapshot and its SHA-256 in the template's provenance fields; export a local snapshot for remote designs. A missing, unreadable or changed snapshot blocks approval. When its hash changes, prior review decisions are not carried forward unless a proven dependency map supports that; currently all are invalidated conservatively. Legacy audits without these fields remain compatible but have no automatic source-freshness guarantee.

Step 1.5 — Visual Process Flow (draw it, don't describe it)

python <AIDD_HOME>/scripts/flowmap.py specs/[###-feature]/visual-flow.toon --open

Interactive actors × processes flow with generated pseudocode. The user clicks through it and corrects the flow by node.

Step 2 — Align (before planning, not during implementation)

Draft spec.md from templates/spec.md: Minimum Requirements Checklist + functional requirements. Every answered row carries a Source: user — "<exact quote>", repo — <path[:line]>, or [Proposed — unconfirmed]. A user quote must be typed by the user: 5+ words in a recorded prompt in the active session or after the first spec.md draft, or 2+ words when quoting their answer to a question. The agent never self-answers — an answer the agent chose itself is always [Proposed — unconfirmed]. Ask the user for every open question, then replace the Source with their own words. Before planning, fill ## Optimization brief in spec.md: think about what could be better than the literal request and offer 2-3 options with cost (tokens/minutes) and risk plus a recommendation; ask the owner to pick and record Owner pick:. Also fill ## Verification (real runners or existing repo paths; the owner reviews it as a mandatory section).

Step 3 — Plan: the Screen → Code map

Dispatch a Mapper agent (fresh agent, model: sonnet) to draft plan.md: inspect the codebase for existing naming conventions, check components-index.md, fill the Screen→Code / Component→Code maps as a proposal. Include the draft in the single combined approval with the spec and tasks; ask earlier only for a decision needed to continue. Run find_spec.py first. The Mapper runs once after the first spec.md draft; do not re-dispatch a subagent after each spec/plan edit — the single pre-build coherence audit (Step 4) covers the later changes.

Step 4 — Tasks, sized as small PRs

After the spec, plan and tasks are drafted, run aidd readiness specs/<id> once and give its JSON to the independent pre-build auditor. It invokes the structural checker once, records observed fingerprints and references, and reports unstable inputs. It is not an approval, semantic audit, test result or a complete cache key; missing or uncertain evidence remains open. Resolve the findings as a batch, then review only demonstrably affected decisions; if dependencies are unknown, review the full relevant scope. One code, one file, one PR. Plan in agent minutes AND tokens using the calibration baselines (templates/calibration.toon: roughly 50-75k tokens per one-file task; Low 45k, Medium 62k, High 90k; minutes are REAL wall time: 3-10 min per one-file task, 15-25 min for a coupled task or one running the suite). Each task has Agent min: + Tokens (est): + Agent role: + Model tier:, a ## Waves table (| Wave | Tasks | Roles | Agent time (min) | Tokens (k) | Human ref (h) |; wave tokens = SUM of tasks, Human ref = Agent min x 3 / 60), Total agent time (critical path): N min and Total tokens (k): N. Organize each wave with specialized agents (role + model tier per task, one file per task, disjoint files per wave). After closing a spec run aidd calibrate record specs/<id> to feed the log.

Seven planning rules (Step 4).

Approval (one confirmation covers spec, plan and tasks). Before asking, dispatch the ONE independent pre-build coherence audit over spec, plan, graph and estimates (medium or high tier, never haiku). R5 checks that audit as a blocking gate only with AIDD_R5_AUDIT=strict; the default advisory does not block on its absence, but the workflow still calls for it. The configured edit-count tolerance is not evidence that a change is immaterial: collect fixes, assess their impact and review affected decisions; if impact or evidence is uncertain, review the full relevant scope. Then show a short summary listing the objectives and their token/minute cost. Run the review flow below and ask for one tagged approval, then aidd rules approve specs/<id>. Preflight before asking: run aidd rules check specs/<id> first; for a tasks.md still awaiting approval it also validates the ## Verification rows with the same rule aidd rules approve applies (no cd x && ... command, Expected exactly exit 0 or contains: <text>). Never ask the owner while it reports a FAIL: a refusal after the owner's click wastes it.

Review before approval (Step 4 to Step 5). Flow (aidd:FR-307): (1) write ## Executive summary in spec.md FIRST (Objective, Scope, Cost, Risks, Open decisions; a few lines, capped; a legacy spec without it gets a mechanical summary), because ANY edit to spec.md changes the sources digest and voids the page; (2) run aidd review specs/<id>: it writes the compact review.html (generated, git-ignored, zero LLM tokens; 8 tabs, one check per code, Verificación included; --full generates the old long page); (3) run aidd review specs/<id> --wait in the background; (4) the owner opens the page, ticks (Aprobar todo en esta pestaña per tab; the Verification rows are checked by hand), comments, and presses the ONE final button, which reads Guardar progreso until everything is checked and then Aprobar y guardar, with a Falta: ... list of what is missing. On Chrome and Edge the page saves review.md straight into the spec folder (the owner picks the folder once; it is validated by spec id and tasks hash); other browsers download review.md and the owner saves it over specs/<id>/review.md. Regenerating the page keeps the checks of unchanged items (only changed or new items return to pending; the owner still presses the button and the agent still asks ONE tagged question); (5) --wait prints ONE STATE=complete ... tag=[tasks:<h8>] line; (6) only when that line says comments>0 run aidd review specs/<id> --comments, and run it BEFORE editing any source file: once a source changes review.md is stale and --comments prints nothing; (7) ask ONE tagged AskUserQuestion with the tag= value, so the consent is NEWER than review.md (the owner's click is the consent); (8) aidd rules approve specs/<id>. Any edit to spec, plan or tasks voids the review and the page is regenerated. A complete review.md ALONE never approves anything; the typed line approve [tasks:<h8>] and the TTY confirmation (aidd rules approve in your own terminal) are fallbacks only. A legacy review.md (old grammar) is rejected with "regenerate": run aidd review specs/<id> again. Agents NEVER Read, cat, type, grep or open review.md or review.html (aidd:FR-309): they only run aidd review <spec> --check / --wait (one STATE= line) and, only when it says comments>0, aidd review <spec> --comments; when --wait returns STATE=complete they ask ONE tagged AskUserQuestion with the tag= value (the owner's click is the consent; review.md alone never approves). Run aidd review <spec> --comments BEFORE editing any source file, because once a source changes review.md is stale and --comments prints nothing. The agent may not write review.md or review.html. When no page exists, only too many items refuses a bare tagged answer (a review is required); sources over the 2 000 000-char per-file size cap keep the 007 answer-only route (amendment 10 FR-411, measured 2026-11-05: the compact page embeds extracted items, not whole files, so a 1 027 224-char spec gives a 378 921-byte page; its data blob is embedded gzip+base64 by default, --no-compress keeps plain JSON; batch files tasks-<name>.md are an option, not an obligation).

Review mode is the owner's choice (aidd:FR-313, aidd:AC-331). Before approval ask ONE AskUserQuestion whose QUESTION text contains the word aprobar or approve next to [tasks:<h8>] (for example ¿Aprobar las tareas [tasks:<h8>]?; the tool matches the approval topic on the question text only, never on the option labels, so a question without that word does not count) with exactly two options: Revisar en HTML visual (only then run aidd review <spec>, wait with --wait, then the one tagged consent click) and Aprobar con resumen (run aidd review --summary <spec> and show its output INSIDE the question; the owner's click is the approval, recorded with source=summary; the label must be exactly Aprobar con resumen: any variant starting aprobar con resum is refused by every route). Never generate the page unprompted, never choose the option for the owner, never Read review files. Then the CONSENT rules: for close and abandon the question text must contain [spec:<id>] (options "Yes, close" / "Abandon"). Claude Code does not fire hooks for AskUserQuestion, so the clicks are recovered from the host transcript (rule_gate and prompt_trigger run sync_ask_answers), and messages typed while the agent works are recorded from queued_messages. Fallback when nothing was recorded: ask the user to type the one-line reply (Approve [tasks:<hash8>], Yes, close [spec:<id>], Abandon [spec:<id>]) as a NEW message while the agent is idle. A typed reply starting with < or [ (subagent hand-backs) is never accepted. R9 also protects host transcripts (.claude/projects/*/*.jsonl) from agent writes.

Step 5 — Implement, one PR at a time, gated

Group approved tasks into waves (same-wave tasks touch disjoint files). Dispatch every task in a wave as parallel subagent calls in one message. Thread codes into the code: aidd:CODE in comments. Code edits are gated while the gate target spec lacks a valid approval.

Think, then propose. During build, propose improvements and record them in the brief instead of waiting for audits; do not dispatch per-domain audits while building. Validation is concentrated at close (Step 6).

E — Orchestration budget (multi-spec / multi-wave runs). Measured: a run of ~900 tasks across many specs burned 7 h because 149 of 290 agents answered "already done", one agent was launched per task, and every wave ran the full suites (memory exhaustion). Rules:

1. E1 Script prefilter before any agent. Run aidd pending <spec> (checks each task's Target file on disk; prints done/pending/unknown and the lanes). Launch agents ONLY for pending; unknown rows get one decision, not one agent each. An orchestrator that launches an agent to find out whether work exists is defective.
2. E2 One agent per lane, not per task. A lane = one feature folder / one set of exclusive files; the agent receives all its pending tasks and reads the spec once.
3. E3 One full cycle per completed batch. Lanes and waves run targeted tests only after every builder in the wave finishes. After the final wave, run full tsc / test suites / DB verification as one coordinated round covering all completed specs: shared checks run once when their identity and inputs are demonstrably identical; spec-specific checks all run. Never run shared DB verification concurrently across specs.
4. E4 Bounded loops. At most ONE audit pass per spec at close and ONE fix batch (CONFIRMED medium+ only); the rest become open exceptions. Never re-audit the fixes of an audit.
5. E5 Cap the run. Declare an agent/token/wall-time budget in the Optimization brief before launching; with half the budget spent and under half the tasks done, stop and re-plan. Items blocked on external data (real ERP data, client schema) are excluded up front and listed, not dispatched.
6. E6 Shared files have one owner (CI config, conftest, router/app registries): lanes request lines; the owner or the integrator applies them once.
7. E7 Builders build first; verification starts only when the wave's programming phase is over. Programming agents (builder, sql, docs) run alone and only do a cheap static self-check (parse / compile / lint / syntax-only); they never run the executed verification (DB run, screenshots, suites, baselines). Only when ALL builders of the wave have finished, dispatch the verifier(s) (Agent role: tests), in ONE message: one is the default; several are fine when they cover DIFFERENT things (e.g. one per domain or per runner: DB, UI, suites), never several repeating the same run. They write the R10 evidence rows for everything the wave produced. Never one verification per task: the same run/build is repeated N times (measured: a one-SP change took far longer than its analysis because each agent re-verified the same thing). Tasks that need the previous wave's output (e.g. a DB comparison) are the verifier's job or the next wave, not a builder's.
8. E8 Database work: compile first, ONE exhaustive pass per wave, the engine decides the tool. AIDD is database-agnostic (Supabase/PostgreSQL today, any engine tomorrow): the contract is fixed, the tool is NOT, and it must match the project's engine. (a) While building, a SQL change is proven by a static compile only (aidd sqlcheck <paths>: built-in --engine postgres via pglast; any other engine passes its own compiler/linter with --cmd "<checker {file}>", e.g. sqlfluff with the right dialect, or the engine's parse-only mode); a green compile is enough to proceed to the next task, never a DB run per task or per file. (b) Only when the wave's builders are done, ONE exhaustive database pass runs all the wave's pending files in order (several specs in one batch when the work is a batch), recording what it applied (a ledger keyed by file hash, as b1SycLink/Payroll/tools/apply_local_db.py does for Postgres) so the runner can avoid reapplying an unchanged file only when the database state and all dependencies are verified; production applies only what that pass recorded as validated. (c) The same file is never checked twice with the same result: sqlcheck caches by content hash and checker. (d') ONE test database per project: never create a database per agent, spec or run; the DB-pass tool resets a single fixed work database from a cached template (hash of the migration set), serializes concurrent runs itself and has a --gc for leftovers (project example: docs/RULE-ONE-TEST-DB.md). (d) Declare the project's checker and DB-pass command once in the charter (or the spec's ## Verification); an agent that cannot find them asks once instead of improvising per-file probes. (e) Database verification by rounds and batches (amendment to spec 007, measured in b1SycLink 2026-11-04: 413 s a full row alone, over 600 s in parallel, 890 s with three agents; a grouped narrow suite took 247 s against about 15 min the full one). Per round ONE full DB run, in ONE designated spec; every other spec uses the narrow form with several prefixes in one invocation (one database preparation) and its own slot, and writes its ## Verification rows in that narrow form when the full suite already covers them. Measure before optimizing (same content, same selection, free database). AIDD_VERIFY_TIMEOUT only for full rows. A test that depends on order or cluster state (e.g. pg_snapshot_xmin, EXPLAIN plans under table statistics) is detected by comparing alone vs. in-suite and made hermetic, never weakened or skipped. When the project's DB runner finds its work database busy (lock or foreign sessions) it must use a COPY from the template in another slot without disturbing the running one and, if it cannot copy, rebuild from scratch with the current migrations and seeds, with a bounded ephemeral overflow. (f) psql metacommands (\set, \gset, \i, \if, :var) are not SQL: aidd sqlcheck blanks them (line numbers kept, a note: on stderr) and only the DB pass checks what they do (amendment 10 FR-407/FR-408). (g) Light seeding (FR-405): volume for the perf tier is seeded with set-based SQL (templates/perf/seed-generate-series.sql: INSERT ... SELECT ... FROM generate_series, one transaction, ANALYZE) through the project's DB-pass tool, optionally kept as its cached template database; never through the business logic document by document (measured b1SycLink F38 2026-11-05: 38 000 lines = about 40 min).
9. E9 Verification economy (aidd:E9). (a) Do not rerun a verification while its evidence and every dependency remain valid; a repeat needs a stated reason (code changed, or a failure to reproduce). (b) Select by change: python tests/run_parallel.py --changed (sources, importers, test modules; one process per module; use --retry explicitly to investigate a failure; --changed --deep adds the dependents' modules) before sequential unittest lists; the full suite runs once per spec at close. (c) After a verification longer than 2 minutes, read the per-module times BEFORE any re-run. (d) Tests assert execution, not hopes: deterministic counts (reads, spawns) and ratios; wall times only with a margin of at least 3x. (e) Every verification reports wall time and tokens. (f) Delegated work. On receiving a builder/agent report the orchestrator makes ONE quick, targeted check (deliverable coherence: the test was not weakened, the files exist, the diff; at most one narrow run) and trusts the evidence reported (command, RED/GREEN, counts); the full repeat (aidd verify, suites) happens once per round at close and independence comes from the closing auditors. Repeating what the agent already ran defeats delegating. Exception: a concrete risk signal (a relaxed test, an incoherent result, a defect already seen). (g) Two test tiers and a capacity budget (amendment 10 FR-397..FR-406). Verification rows carry Tier: functional (default: minimal data, every round) or Tier: perf (volume/load: skipped by every aidd verify, run ONCE per spec before close with aidd verify <spec> --perf, alone, recorded as perf_verify_run); aidd rules close requires current perf evidence only when ## Verification declares Perf: required. A spec that uses tiers fills ## Capacity & test budget (RAM, Heavy runs at a time, Round budget, Not verified, one Est. s/Budget s/Data scale/justification row per Verification row): aidd rules check refuses a row over its budget, functional rows over the round budget and a seed of 1 000+ rows (or any perf row) without a justification. The scale is justified by the risk, not by production volume: behaviour shown linear with its plan at a small N needs no 200 000 rows, and what is not measured is declared not-verified. Most performance risks are functional-tier checks without volume (templates/perf/plan-risk.test.sql: plpgsql switches to a generic plan at the 6th execution, measured 80 ms -> 950 ms in F38; check proconfig plan_cache_mode=force_custom_plan, 7 calls in a row, and no Seq Scan under force_generic_plan).
10. E10 Round lessons: detect early, not at the full suite (amendment 09 to spec 007, measured in b1SycLink 2026-11-04; text of FR-294..FR-300; (h) is FR-300 (h)). (a) Visual contract shift-left. Step 1 emits per screen a machine-readable contract (main[data-screen], h1, data-ctl/data-comp set, ordered columns, states, skeleton count); component/page tests are DERIVED from it; each view task is measured against the prototype with a verdict match/differ/not-verified by a fixed rule (any missing code, column or state = differ; no measurement = not-verified) before it is done; ONE pilot screen is built and measured end to end before the rest (canary); browser measurements run serialized (one Playwright at a time). Measured: F38 0 of 32 states matched and F37 5 of 53 with vitest green (258). (b) Shared surface and blast radius. The plan lists, under Shared surface, every function/table/index/idempotency-key namespace the spec REDEFINES (CREATE OR REPLACE/ALTER of an existing object); before building, query aidd graphs show db <name> for its callers and tests; every migration touching it runs that grouped set at once (--only-tests a,b,c), and the change is announced to the orchestrator. Measured: fe_acct_link_journal (3476) broke F41, fe_period_close (3471) failed 11 of 59 in F21, OMOV_Aging_ix (3442) changed inventory_plans test 6, and an IdemKey collided between F21 and F40. (c) Defect fast lane. The plan reserves a contingency range of migration numbers per spec and a one-page defect amendment template; on a build-time defect the builder stops and reports with evidence; the orchestrator groups the round's defects into ONE amendment per owning spec. (d) RED receipt. A test task delivers the saved failing output (stored under the spec's evidence folder: command, exit code, first failing assertion) obtained BEFORE the implementation; the orchestrator rejects a NEW test file without it and checks the receipt instead of rerunning the suite. (e) Verification forms. Rejected: npm --prefix x run y, cd x && ..., bash -c, same with ..., Expected other than exit 0; accepted: node <path>/cli.js test --config=<file>, python <path>.py <args>, Expected exactly exit 0; wrap anything else in a repo script; run aidd rules check <spec> before asking the owner. (f) Spec size. Warn at 1 500 000 characters per review source (limit of aidd review: 2 000 000 per file since amendment 10 FR-411, measured; the old 300 000/400 000 forced needless splits) and split by amendment batches only if you want to; never approve by summary to dodge it (measured: F21 tasks.md 1.26 MB, F38/F37 430-460 KB). (g) Executor capacity. The Optimization brief declares tokens per executor and an alternate executor per lane; probe capacity with one cheap smoke before launching a wave; lanes writing the same tree never share an executor unless split by folder (measured: one executor hit 429 for 112 h and 4 agents died). (h) Orchestrator tools-first. The orchestrator does not do by hand what is mechanical or checkable (building verification tables from the evidence, counting, listing, comparing, applying patches, checking evidence freshness, repeating tests an agent already ran); a repo tool does it (aidd, db_verify, generators, check_spec, task_precision_check) or an agent that runs it and returns the output. If the tool does not exist and the step will repeat, build it first and add it to the backlog. The orchestrator does only what needs its own judgment: decide, ask the owner, approve with the owner's answer, judge findings and write conclusions. Measured 2026-11-04 (b1SycLink): the orchestrator built the qa-audit.md verification tables and the R10 evidence freshness of several specs by hand; the extra round of six P01 auditors cost about 370k tokens because freshness was not checked with a tool before auditing. Loads and DB verification: E8(e)/E9.
11. E12 One verification pass for several specs (amendment 10 item O, FR-419..FR-426; E11 = aidd sync, see AIDD.md). Before verifying 2+ open specs (Step 6), plan a round with aidd verify --round <ids...> --dry-run (or --all-open --round --dry-run: groups of identical row commands, executions saved, seconds estimated from each previous verify_run; nothing runs), freeze the code, run ONE pass aidd verify --round <ids...>, then ONE round of auditors per spec; verify spec by spec only when a single spec is ready. Each identical command (whitespace/plain-quote normalised; Tier: perf excluded) runs once, in series (heavy runners alone); a row is shared only when the environment fingerprint (Scope/Inputs file content or the whole code tree, minus Generated; docker exec container id + start time; the optional Round-identity: <command> output; Round-vars: and vars= values) is identical before and after it, otherwise every row of the group fails as ROUND-INVALIDATED. Every spec records its own verify_run (evidence with a ROUND-SHARED: second line; each row's Expected on the shared output, so a failure stays a failure). aidd status, aidd next and aidd verify <spec> print the round command when other open specs share rows. Before grouping (item P, FR-427..FR-432), a row its own spec's previous verify_run passed on the same Scope, code fingerprint, Inputs and environment identity (env_id), with intact evidence, is REUSED (evidence line 2 REUSED: PASS del verify_run de ...) and not run; a FAIL, a new or changed row, an uncomputable fingerprint, --full and Reuse: never run as before; the dry run lists reused rows, rows to run with the reason, and the seconds saved.
12. E13 Refusals say what they compared (AIDD.md E13). Declare screenshots/reports in Generated:: they are skipped before fingerprinting (also node_modules/, test-results/, .aidd/evidence/); the refusal names AIDD_FINGERPRINT_BUDGET. Put [spec:<id>] in every close question; the close refusal shows the last close question and the qa-audit.md time. A page-route approve refusal shows since = max(tasks, review.md) and the last consent (older than review.md = the open page autosaved: close it, or ask with option Aprobar con resumen). aidd status/R6 name the task file that voided the approval; aidd pending reads tasks-*.md and reports shared or pre-existing Targets as unverified. A rewritten-file failure says which row (or another process) wrote it. --round lists rows without a previous env_id. check_spec warns about --slot N against Protected-slot: N or another spec's perf row.

Incremental verification and reusable checks. Use aidd verify <spec> --changed [--base COMMIT] to select verification rows through Git changes and declared task coverage, or --tasks T-01,T-02 for explicit tasks. Partial evidence does not establish full-spec coverage. An eligible Python script row may reuse a passing result only with explicit Reuse: hermetic, Inputs, and Environment: contract:offline;vars=...;packages=... (use none for an empty list). The owner promises that all inputs and dependencies are declared and that no network, database, clock or other external state affects the result; this is a contract, not sandbox enforcement. AIDD checks command, input and evidence fingerprints, the interpreter and declared variables and package files. Missing or changed identity fails closed; --full executes checks again. Use a purpose-built runner for database checks and never infer their equivalence from local files alone. Agents review script verdicts and evidence; a zero-file pgTAP selection fails. A passing contract row is stored once per project; a later aidd verify of any spec with the same command, expected result, Inputs and environment takes that stored result instead of running it (CROSS-REUSED); database and container runners (db_verify, psql, pg_prove, docker, supabase, --tap) can never use the contract.

• aidd coverage <spec_dir> [--apply-to FILE] [--json] [--changed-file PATH] proposes, per ## Verification row, the task Covers and the Inputs (target files of those tasks) that --changed and --tasks need, and simulates --changed for the given paths.
• Each proposal says how it was derived: cites-tasks (Covers already names tasks), via-fr-ac-api (codes that tasks cite), whole-suite (no code or a suite word: every task, marked [Proposed — unconfirmed]) or unresolved (codes no task cites: no Inputs proposed).
• It never writes the spec: the default is a dry-run, --apply-to FILE writes only a separate proposal file, and the owner copies the accepted cells by hand; it never proposes a Reuse value.
• Under --changed, a row without declarations always runs (warning: verification row <n> declares no Inputs or no task Covers; it always runs) and a changed task no row names runs the whole-suite rows (warning: task <T> is covered by no verification row; whole-suite rows run); only malformed declarations refuse.
• --base takes any revision Git resolves to one commit, e.g. aidd verify <spec> --changed --base HEAD~1.

Every agent receives the wave contract in its dispatch prompt: wave ID, all covered task/spec IDs, ownership, and the barrier. Builders do static self-checks only and report completion; the orchestrator waits for all builders, then assigns exactly one verifier for each distinct runner. An independent auditor may own the verifier invocation after the barrier, or consume its recorded per-spec verdicts and changed scope; it must never start a second copy of an already running or valid shared check. Do not assume subagents inherited this instruction. The script decides PASS/FAIL, preserves evidence and returns errors; the auditor evaluates coverage and risk, not a guessed test result from logs. A partial wave does not replace final full-spec verification or closing audit.

T1 Tool-first (aidd:T1). Before doing by hand a step that is repetitive, long or checkable (searching code, verifying, applying migrations, counting, generating lists, triaging failures), run aidd tools <keywords> and use the tool; a manual path needs a written reason. The tools: aidd graphs (structure, builtin:code, trace, snapshot, diff), aidd job (waiting), aidd triage (failures), aidd tools (catalog), aidd size (proportion). On Claude Code the tool_first_hint.py hook advises (never blocks) after 4 edits of the same shape or to the same file within 15 minutes, or 4 shell commands in a row of the same shape (same_shape, same_file, same_command; digits, quoted literals and paths are ignored when comparing). Only an aidd tools query run by the agent silences it for 300 s. Each advisory is a tool_miss event and aidd status prints tool-first: N advisories / M edits this session.

P1 Proportional analysis (aidd:P1). The tools are sized to the task: aidd size [--spec <id> | --files <f...>] classifies XS/S/M/L (XS = 1 file, no sensitive area; S = 2; M = 3-8; L = more than 8, a sensitive area (database, hooks, CLI, gate rules) or cross-spec) and prints the analysis parameters:

Whatever the class excludes is NOT created: an XS change (one script) never builds a new graph, snapshot or job. Carry the output in the prompt line Analysis parameters: <aidd size output>.

Waiting tools (aidd:T1). aidd job run [--bg] [--key <globs>] [--name <n>] [--force] -- <cmd> returns CACHED when the same command runs on the same content hashes (it repeats nothing); aidd job wait <id> blocks and returns the tool's exit code (never poll or re-run); aidd job last <name> prints the stored verdict (exit 3 when inputs changed). Tools end with RESULT: ok|fail|stale|refused - <N> items - evidence <path> (exit 0/1/2; --plan/--check have no side effects). Failures shared by several specs: aidd triage [spec ...] groups them so they are fixed once.

Step 6 — Converge

Run python <AIDD_HOME>/scripts/check_spec.py specs/[###-feature]/ before the manual audit. Then execute the verification and close with one auditor per required domain, dispatched together (see Close sequence below); the required domains are (security and functional always, the functional one with executed evidence per R10; ui, backend, database by what the tasks touch; performance only when the change touches hot paths, the database or the UI) — fresh agents that did NOT implement the PRs. Auditors run on a medium or high model tier chosen by the spec's Risk: low|medium|high (high = writes to SAP/DB, security, money -> highest tier), never the lowest. Each (or the single closing auditor, covering all of them) re-derives its own qa-audit.md rows from the code. The Auditor must not be the same agent that implemented. Each auditor starts from find_spec.py --code for every changed code plus the check_spec.py report and the diff since the last audit, and reads full files only for what those point to. The auditor's scope starts from aidd graphs changed --spec <id> (files changed since <spec-id>@open) plus find_spec.py --code of the changed codes; it does not re-audit what did not change.

Close = executed verification + independent auditors. Run aidd verify specs/<id> first (no edit after it, or it is stale), then follow the close sequence below.

Close sequence.

1. Freeze the code: finish host sync, mirrors and every fix first.
2. Run aidd verify specs/<id> once.
3. In ONE message dispatch one auditor per required domain (the description names the domain; sonnet or opus, never haiku; read-only; they do not repeat the verification, E9). A single closing auditor with the CLOSING AUDIT [domains: ...] [tasks:<h8>] [verify:<v8>] header is still accepted, but aidd rules close also needs an auditor for every required domain recorded after the last code edit and the last verify run, so the per-domain auditors are the path that always counts.
4. Write qa-audit.md from their reports.
5. Approve if needed and run aidd rules close <id>.

Any code edit after the dispatch voids those auditors. aidd status lists, per spec, which domain has no counting auditor and why.

A management error never forces a re-execution (amendment to spec 007). A passed verification is tied to its effective code scope: changes outside that scope or status-only administration do not by themselves stale the result. Use Git impact and declared task dependencies to select affected verification rows, without reading every file line by line. Selective verification is partial and does not by itself prove a complete legacy baseline. Eligible checks may be reused only under the explicit offline contract described above; --full forces execution. Reuse neither a failure nor a database or external-state result without a verified contract for its state. Coordinate database verification in one round and avoid simultaneous heavy runs. Incremental unit audit receipts remain valid only while their declared scope and evidence remain current; unknown legacy coverage stays indeterminate.

Outputs the verification rewrites (a graph.json with a timestamp, reports, snapshots) fail that run once with the exact file list; do NOT edit the generator to make it idempotent (that edit stales the run again: an endless loop). Add Generated: <those files or globs> under ## Verification and the gate accepts THAT run as it is; later changes to generated files never stale it. Consent is not per window: an owner click whose question carries the [spec:<id>] / [tasks:<h8>] tag counts even when it was recorded under another window's session, so never ask the owner to click twice or type "listo" to relink a session.

Step 7 — Comprehensive Documentation (handoff)

Copy templates/comprehensive-documentation.md and fill it in — mechanical assembly, no new judgment calls.

File structure

<AIDD_HOME>/
├── SKILL.md              # this file
├── AIDD.md               # tool-agnostic methodology core (read for the full "why")
├── scripts/              # stdlib Python — see "Templates" above
├── templates/            # fillable skeletons for every artifact
├── hooks/                # Claude Code enforcement (see "Installation — Claude Code")
└── extensions/           # issue-tracker providers + agent adapters

When to use this skill

Use for EVERY requirement, feature, bugfix, or change request in this codebase before writing or editing any source file — not only when a mockup is mentioned. Use when the user says 'analiza este mockup', 'quiero implementar esta UI', 'necesito planificar una pantalla', 'especificación de UI', 'necesito un diagrama de flujo', 'necesito auditar la implementación', 'contrato de API', 'componentes reutilizables', 'stored procedure', 'swagger', 'arreglar/corregir un bug', 'nuevo endpoint', 'migración de base de datos', 'refactor', or asks to speed up any review-and-handoff cycle, UI or backend.

Verification and approval economy (user preference)

• Use aidd impact <spec> --changed --base <commit> to identify affected tasks and units using Git and declared dependencies; an unverified base is diagnostic, not historical audit proof. Use aidd verify <spec> --tasks T-01,T-02 to run the relevant verification-table commands once; its evidence is partial and does not close the spec. Never scan files line by line merely to identify changes.
• Reuse valid execution evidence only when the relevant inputs, dependencies and environment are established. Before running overlapping checks, compare their collected cases and required coverage; do not repeat an unchanged suite or independent audit merely to refresh administrative state. Report omissions and unverified environments explicitly.
• Present a concrete increment for the owner's review. Respect approval already given in the conversation and do not ask the owner to repeat it merely for formatting; record consent only through a supported, authentic mechanism. Optional local visual consent is available through aidd review <spec> --unit <id> --visual --open; opening the page alone does not approve it. For affected unit domains, aidd impact <spec> --run-review <id> launches a fresh independent read-only Codex review and records its actual result without requiring Codex hooks. Legacy baseline coverage with insufficient evidence remains indeterminate. Never invent approval or audit events.
• Use aidd units plan, apply, and revert to adopt an existing amendment directory with its own tasks into versioned units. The operation preserves historical approvals and evidence; an adopted unit begins without consent or audit, and rollback refuses to hide later evidence or dependents. Consult aidd units --help for the manifest and plan arguments.
• For a commit, the Git guard can recognize a runner-generated partial verify --tasks receipt when task ownership and verification Covers are explicit, offline contract inputs cover every target, the evidence and environment remain current, and the staged bytes match the tested files. Partial evidence never closes the spec. Direct test output or database state without an accredited identity does not qualify; report missing coverage instead of inventing a receipt.
• aidd provider run --coverage <path> --policy <path> supports a project-specific verification provider when a real approved unit covers its explicit task/file/test map and environment policy. The runner captures the actual provider process; the commit guard checks the recorded inputs and staged blobs offline. Existing receipts are not retroactively transformed, and partial provider evidence never closes the spec. See docs/aidd-provider-verification.md in the AIDD source for the contract; do not re-run a previously executed test just to produce a new receipt.
• Preserve historical approvals and evidence when evolving amendments. A versioned amendment or screen reference must identify its inputs and dependencies; if the current tooling cannot validate its independent seal, state that limitation and retain the applicable existing checks.