Aidd Core

---
name: aidd-core
description: The AI-Driven Development framework — three phases (Ideate, Research, Execute) separated by a human decision gate rendered in the browser. Load when starting, resuming, or reasoning about an AIDD run, or when .aidd/ exists in the project.
---

# AIDD — the framework

Three phases. One gate. The gate is the point.

```
  IDEATE            RESEARCH                 [ GATE ]              EXECUTE
  sharpen     ->    sweep everything    ->   human chooses    ->   build
  the idea          findable                 in the browser        under contract
```

Most AI development fails in the same place: the model quietly makes a hundred technical decisions the human never saw, and by the time anyone notices, the decisions are load-bearing. AIDD moves those decisions into one visible moment where a human can actually act on them — and then holds the build to what was decided.

## Two modes

`init` auto-detects which one you are in and records it in `state.json`. `aidd.mjs scan` reports the evidence.

**Greenfield** — an empty or near-empty directory. Every decision is open.

**Brownfield** — a project already exists here. Most foundation decisions are closed, and re-asking them is worse than useless: it teaches the user to click through the gate without reading, which destroys the only thing the gate is for.

In brownfield mode:

- `aidd-surveyor` maps the codebase first, into `.aidd/00-context/codebase.md`.
- Closed decisions become `"locked": true` segments — rendered read-only on the gate, excluded from the submit requirement, delivered to the contract as `LOCKED`. They still get a note box, because "fine for now, but I want this gone next quarter" is real information.
- The stack, its constraints, and the must-not-break list go in the top-level `context` block of `options.json`. Every stack entry needs `evidence` — the file that proves it — or validation fails.
- Only genuinely open decisions get stances.

Locking is a judgement with teeth. Lock something that was actually open and you have made the user's decision for them behind their back. When it is borderline, leave it open with a strong recommendation and state what switching would cost.

## Phase 1 — Ideate

Make the idea **clear**, not bigger. No technology, no feature lists, no roadmap.

Exit artifact: `.aidd/01-ideate/brief.md` — one line, the one job, who it's for, the moment it earns its keep, and a **deliberately not** list. That last list does more work than anything else in the file.

## Phase 2 — Research

Sweep every dimension the project actually needs: stack, storage, interface, data sources, deployment, design language, licensing, whatever this project's shape demands. Everything findable, from docs and GitHub and registries and critiques — not the first three results.

Exit artifacts:
- `.aidd/02-research/dossier.md` — the long record, including what was rejected and why
- `.aidd/02-research/options.json` — the structured segments that drive the gate
- `.aidd/02-research/gate.html` — the themed page

## The gate

`options.json` renders as a tabbed page, one tab per decision segment, each option showing pros, cons, and links to real sources. Every option carries three buttons:

| Button | Contract |
| --- | --- |
| **Apply** | Build exactly this. Binding. At most one per segment. |
| **Infer** | Use it as a source and nothing more. Claude reads it, then decides independently. |
| **Innovate** | This is ground already covered. Claude invents something else for this segment. |
| *(locked)* | Not a button. Segments the existing codebase already settled render read-only, with the reason and the file that proves it. |

Plus a per-segment note box, a per-segment "Claude decides this one", and a global comment box.

**Nothing reaches Claude until Submit is pressed.** On submit, the gate server writes `decisions.md` + `decisions.json`, flips the phase to `execute`, and exits — its exit is the signal that the gate has passed.

The gate is served locally by `scripts/gate-server.mjs` because a browser page cannot otherwise hand data back to a terminal agent. Claude launches it in the background and waits.

## Phase 3 — Execute

`decisions.md` is a contract, not a suggestion. It binds the decisions it names and says nothing about the rest — and everything it doesn't name is Claude's to design well.

The `craft-bar` skill sets how well. It is domain-agnostic — use the strongest technique the domain actually offers, aim at what *excellent* looks like for that kind of work, and ship no borrowed filler. It carries worked examples for CLI, data, mobile, games, backend, embedded, and visual work. The bar operates inside the contract, never around it.

Exit artifacts: `.aidd/03-execute/charter.md` (decisions restated as build rules, plus every `[claude-call]`), `tasks.md`, and the working code.

## Rules that hold across every phase

1. **Never skip the gate.** Not because the choice seems obvious, not because the user seems in a hurry. If they want to skip it, they can say so — but they have to say so.
2. **Never fabricate a source.** A URL you did not open does not go in `options.json`.
3. **Never write product code while the gate is open.** Waiting is the correct behaviour.
4. **One `APPLY` per segment.** More than one binding choice is not a decision.
5. **Deferred means decide and disclose** — pick, record why, tag `[claude-call]`.
6. **Contract drift gets reported, never absorbed.** If an `APPLY` turns out impossible, that goes back to the user with evidence.
7. **Verify by running it.** A passing type-check is not an observation of behaviour.

## Layout

```
.aidd/
  state.json                    mode + phase + gate status (the CLI owns this)
  00-context/codebase.md        brownfield only — the surveyor's map
  01-ideate/brief.md
  02-research/
    dossier.md                  long-form research record
    options.json                segments -> options -> pros/cons/sources + theme
    gate.html                   themed decision page
    decisions.json              normalised submission
    decisions.md                THE CONTRACT
  03-execute/
    charter.md                  contract restated as build rules
    tasks.md
```

Add `.aidd/` to `.gitignore`, or commit it — both are defensible. Committed, it is the best record of *why* the project looks like it does that the repo will ever have.

## Commands

| Command | Does |
| --- | --- |
| `/aidd [idea]` | Start or resume; routes to the right phase |
| `/aidd:ideate <idea>` | Phase 1 |
| `/aidd:research` | Phase 2 sweep |
| `/aidd:gate` | Build, serve, and wait on the gate |
| `/aidd:execute` | Phase 3 build under contract |
| `/aidd:status` | Where the run is |

## CLI

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/aidd.mjs" init | scan | status | validate | scaffold-gate | phase <p> | ingest <f>
node "${CLAUDE_PLUGIN_ROOT}/scripts/gate-server.mjs" [--port N] [--timeout MIN] [--no-open]
```

Gate server exit codes: `0` submitted · `2` timed out or interrupted · `3` bad inputs.