aidd

AI-Driven Development for Claude Code — with a human decision gate in the middle.

Most AI development fails the same way: the model quietly makes a hundred technical decisions nobody saw, and by the time you notice, they're load-bearing.

aidd moves those decisions into one visible moment. Claude researches your idea exhaustively, then hands you a themed page in your browser — every option with its pros, its real costs, and links to the sources it came from. You choose. Then the build is held to what you picked.

IDEATE  ──►  RESEARCH  ──►  [ GATE ]  ──►  EXECUTE
sharpen      sweep          you choose     build under
the idea     everything     in a browser   contract

The twist: three stances, not one choice

Every option on the gate page has three buttons.

Apply	Build exactly this. Binding. Max one per segment.
Infer	Use it as a source and nothing more — Claude reads it, then decides independently.
Innovate	This is ground already covered. Go invent something better.

Mix them freely. Apply React, Infer from three state libraries, Innovate past every charting option you were shown. Plus a note box per segment and one at the end for everything the tabs didn't cover.

Nothing reaches Claude until you press Submit.

It works on projects that already exist

Point it at a five-year-old Django service and it will not ask you whether to use React.

init detects an existing codebase and switches to brownfield mode. A surveyor agent maps what is actually there — stack, conventions, constraints, what must not break — and every decision the code has already made becomes a locked segment: shown on the gate read-only, with the file that proves it, excluded from the things you have to choose. Only the genuinely open decisions get the three buttons.

Locked segments still get a comment box, because "fine for now, but I want Redis replaced next quarter" is real information, and it lands in the contract as a design constraint rather than being lost.

| # | Segment               | Stance     | Option        |
| 1 | Background Job Runner | `LOCKED`   | Celery + Redis|
| 2 | Export Format         | `APPLY`    | Streamed CSV  |
| 3 | Export Format         | `INNOVATE` | Parquet       |

In brownfield mode the build also inherits stricter rules: match the surrounding conventions, no opportunistic refactors, extend the existing seams instead of adding parallel ones, and run the existing test suite — not just the new tests.

The build has a craft bar

Passing the gate doesn't mean shipping default-looking output. The execution phase loads a standard: use the strongest technique the domain actually offers — and work out what excellent looks like in that specific domain before aiming at it.

It's domain-agnostic. Default-looking output is the same failure wearing different clothes: a purple-gradient hero, a CLI whose error message is a stack trace, an API returning 200 for everything, a chart with unlabelled axes. Two rules hold everywhere — nothing default, and no borrowed filler: nothing placeholder, lorem, stock, or hotlinked. Real or generated by you, for this project.

The skill carries worked examples per domain — CLI, data and pipelines, mobile, games, backend and APIs, embedded, and anything with a visual surface.

That last one is the most opinionated, as an illustration of how specific the bar gets. For visual work it means reaching for real technique where it serves the subject — WebGL and custom shaders, raymarching and SDFs, post-processing, particle systems and flow fields, fluid simulation, SVG filters and blend-mode compositing, scroll-driven narrative, View Transitions, spring physics, variable fonts and kinetic typography, art-directed dark and light modes, a designed preloader, real depth and parallax. Every visual generated rather than hotlinked; tool-generated imagery treated in-browser (duotone, grain, displacement) rather than dropped raw onto the page.

The bar is craft, not spectacle: honest degradation without WebGL, a designed reduced-motion version, keyboard and screen-reader access intact, contrast held in both themes, 60fps profiled rather than assumed. A fluid simulation on a tax form fails the same way a flat white page for a music label does.

And it operates inside the contract — if you APPLYed a minimal text-first design, the craft goes into typography and rhythm, not into a particle field you didn't ask for.

Install

/plugin marketplace add rchase999/aidd

/plugin install aidd@aidd-marketplace

Requires Node 18+. The plugin has zero npm dependencies — the gate server is Node standard library only.

Use

/aidd a tide and swell log for coastal photographers

That's the whole entry point. It routes to the right phase and resumes correctly in later sessions.

Command
/aidd [idea]	start or resume
/aidd:ideate <idea>	phase 1 — sharpen the idea, no tech talk
/aidd:research	phase 2 — exhaustive sweep, parallel scouts
/aidd:gate	build, theme, serve the gate; wait for you
/aidd:execute	phase 3 — build under the contract
/aidd:status	where the run is

How the gate talks back

A browser page can't hand data to a terminal agent, so the gate ships its own server. Claude starts it in the background; you choose in a real browser; on submit the server writes the contract, advances the phase, and exits — and that exit is what tells Claude the gate has passed. No polling, no copy-paste, no clipboard.

Opened the page without the server? It downloads a JSON file and tells you to run /aidd:gate --ingest <file>. Same validation, same output.

Guarantees enforced by code, not by prompt

• No lazy gates. options.json fails validation unless every option has pros, cons, and a real http(s) source. You cannot ship a page that hides costs.
• One binding choice per segment. Two Applys in a tab is rejected server-side with a readable error, and the page lets you fix it without losing state.
• Deterministic contract. decisions.md is rendered by code, not by a model — the same submission always produces the same file.
• A timeout is not a pass. No submission means the gate stays unpassed.

What lands in your project

.aidd/
  state.json                    mode + phase + gate status
  00-context/codebase.md        brownfield only — the surveyor's map of what exists
  01-ideate/brief.md            the idea, sharp, with a "deliberately not" list
  02-research/
    dossier.md                  the full record — including what was rejected and why
    options.json                segments -> options -> pros/cons/sources + theme
    gate.html                   the themed decision page
    decisions.md                THE CONTRACT
    decisions.json              same, machine-readable
  03-execute/
    charter.md                  contract restated as build rules + every [claude-call]
    tasks.md

Commit .aidd/ and you get the best record of why the project looks the way it does that the repo will ever have.

Try the gate without a project

git clone https://github.com/rchase999/aidd && mkdir demo && cd demo
node ../aidd/aidd/scripts/aidd.mjs init --name Tidepool
mkdir -p .aidd/02-research && cp ../aidd/aidd/templates/options.example.json .aidd/02-research/options.json
node ../aidd/aidd/scripts/aidd.mjs scaffold-gate
node ../aidd/aidd/scripts/gate-server.mjs

Your browser opens on a working two-segment gate. Submitting writes .aidd/02-research/decisions.md.

Repo layout

.claude-plugin/marketplace.json    marketplace manifest
aidd/                              the plugin
  commands/    aidd, ideate, research, gate, execute, status
  agents/      aidd-surveyor, aidd-scout, aidd-gate-designer, aidd-executor
  skills/      aidd-core, research-dossier, decision-gate, execution-charter, craft-bar
  scripts/     aidd.mjs, gate-server.mjs, lib/, hooks/
  templates/   gate.template.html, options.example.json, options.brownfield.example.json
  hooks/       SessionStart — reminds Claude where a run left off

Full plugin reference: aidd/README.md

License

MIT