gdd¶

Build software with AI coding agents, one gate at a time. Risk decides how many gates a change meets; machines check what can be checked; you decide only what needs a person, in as few sittings as possible.

Your first change GDD in one page

A change moves from G0 to G4: the harness, the scenarios you approve, the machines' gates,
the Reviewer and your Release Gate. Green, yellow or red decides how strict each gate
is.

Learn

From an empty folder to a released change in about half an hour, then the method in one page.

Start the tutorial →
Do

Run changes, write scenarios, answer the Release Gate, adopt an existing project, fix what breaks.

Run a change →
Look up

Every command, configuration key, gate, role, stack and file. Exact and complete.

Command reference →
Understand

Why gates, how risk is judged, what keeps agents safe, why you stop so rarely.

The life of a change →

Learn¶

Step by step, from nothing to a released change.

Your first change: set up a project, write and approve a scenario, launch the change and answer its Release Gate.
GDD in one page: the phases, the gates and the traffic light, with a diagram of each.

Do¶

Guides for a goal you already have.

Day to day

Install gdd: the binary, the agents and the tools the gates use.
Run a change: create it, launch it and follow it on the Board.
Write and approve scenarios: Gherkin, hidden examples and the Scenario Gate (G1).
Answer the Release Gate: OK, KO or polish at G4.
Get a parked change going again: the Decision Inbox, relaunches and merge conflicts.

Shaping the work

Map and approve red zones: tell gdd which paths are risky.
Explore with a spike: a fixed budget, variants side by side, an ADR.
Run changes in parallel: the cap, overlaps and the merge queue.

Setting up and tuning

Bring gdd to an existing project: init, bootstrap and adopt.
Choose agents and models: who builds, who reviews, per color.
Tune the gates: the commands each gate runs, limits and mutation testing.
Release versions and keep a changelog: tags, gdd release, CHANGELOG.md.
Run the gates in CI: what the workflow checks on every pull request.
Measure the work: tokens, flow time, DORA and Learn.
Upgrade gdd in a project: new versions of the files gdd wrote.
Troubleshooting: symptoms, causes and fixes.

Look up¶

Exact and complete. The command reference is generated from the code.

Command reference: every command of gdd and its options.
Configuration: every file in gdd/ and every key.
Gates: what each gate checks, who decides and its limits, by color.
Roles: the human, the Orchestrator, the Builder and the Reviewer.
Stacks: the Python, Rust and TypeScript sheets.
Files gdd writes: records, the log, the Decision Inbox and outputs.
Environment variables: what gdd reads and what it gives agents.
Glossary: the words these pages use.

Understand¶

Why GDD works the way it does.

GDD in one page: phases, gates, colors and roles.
The life of a change: every step of a launch, in order.
How risk picks the gates: the traffic light and why color wins.
Keeping agents honest: Path Guard, hidden examples and what the agents cannot touch.
Few stops for the human: sittings, polish and why done is not good.
Measuring what matters: tokens, DORA and the kill rule.
Design decisions: what was chosen, and what was not.

This project, built with GDD¶

gdd is built with GDD, so its own GDD files are real examples of every artifact:

The method's full rules and the roadmap.
Project Brief, standards, decisions and Discover notes.
Scenarios: the executable specification of gdd.

Contribute¶

Contributing: set up, test and send a change.
Writing the docs: how these pages are organised and written.
Changelog.