Configuration¶

Every file in gdd/ and every key gdd reads from it: its type, the value gdd uses when the key is missing, and what it does. The files are TOML.

The files¶

gdd init writes the first five files and gdd/generated.toml; gdd adopt writes gdd/debt.toml. All of them are committed with the project.

There is no gdd/release.toml: see release.toml.

A file gdd cannot parse stops the command with the file's name and the TOML error. Keys gdd does not read are ignored, except where a section below says otherwise.

Who may change them¶

Every path under gdd/ is harness:

• gdd init puts gdd/** in [protected] all of gdd/rules.toml, so Path Guard fails any Builder or Reviewer that touches it, in G2 and in CI (gdd ci fails a change branch that changes a path of all).
• gdd init puts gdd/** in the red harness zone of gdd/zones.toml, so a change that plans it is red.

Only a person changes these files, on the main branch, after the human agrees: the Orchestrator proposes, the human decides (the red zones and the plan of a red change are approved at the sitting). A change that edits gdd/zones.toml again needs the red zones approved again.

Path Guard judges a build with the [protected] lists of gdd/rules.toml as it is now and as it was at the commit where the build started: deleting a protection, or the whole file, frees no role from it.

project.toml¶

The project basics. gdd init writes it from its flags. The file that marks the project root: gdd looks for gdd/project.toml in the folder it runs in and the folders above it, and refuses to run outside a project (not a GDD project).

Read by gdd status (name, language, platform), by every command that needs the stacks (stack), and by the agents, whose commands tell them to read it (language, scenario_runner).

name = "notes"
description = "A command-line notes tool"
language = "en"   # language the agents use with the human
platform = "cli"   # mobile | desktop | web | cli | other
stack = ["python"]   # the stack sheets (gdd stacks)
scenario_runner = "pytest-bdd"

zones.toml¶

The zone map: which paths have which color. Read by gdd classify, gdd new-change, gdd prepare, the gates (to classify the change and for the scope check), gdd status and gdd gate zones. The Orchestrator maps the red zones at the end of Discover; the human approves them (gdd gate zones ok). See How risk picks the gates.

The color of a path is the highest color among the zones that match it; a path no zone matches takes default. The color of a change is the highest color among its paths, raised to its --min-color when that is higher.

Path patterns: ** crosses folders (docs/** matches everything inside docs; **/x also matches x at the root), * and ? stay inside one folder. *.md matches README.md but not notes/readme.md.

Top level¶

[[zone]]¶

One table per zone, in any number, in file order. When several zones of the same color match a path, the first one gives its reason.

gdd init writes three zones: docs/** and *.md green; the harness (gdd/**, bin/**, .github/**, .claude/**, .agents/**, .opencode/**, .gdd/bin/**) red; the supply chain of the stacks (for example pyproject.toml, uv.lock, osv-scanner.toml, osv-scanner-licenses.toml) red.

The red zone approval keeps a hash of every [[zone]] whose color is red, with every key it has. Any change to a red zone, an added key included, asks for a new approval.

rules.toml¶

The rules table: which gates each color and lane asks for, where the scenarios live, the limits of every loop and the paths each role must not touch. Read by gdd classify, gdd new-change, gdd prepare, gdd g2, gdd g3, gdd guard, gdd scope, gdd launch, gdd resume, gdd merge, gdd release, gdd selftest and gdd ci.

Top level¶

[acceptance]¶

G3 counts the lines of the .feature files in dir and its subfolders that start with Scenario:, Scenario Outline:, Escenario: or Esquema del escenario:.

[limits]¶

[spike]¶

[parallel]¶

Not written by gdd init.

[versions]¶

Not written by gdd init.

[color]¶

What each color asks for in each lane. A color has a table of its own, [color.<color>], and one per lane, [color.<color>.fast] and [color.<color>.full]. The rule of a color in a lane is its lane table when it has one, else its color table. A lane table does not inherit from the color table: a key it leaves out takes the default below. A color the file does not mention gets the defaults.

When the file has no [color] section at all, gdd uses the table built into it instead:

gdd init writes the same tables with mutation = false for yellow, and review for every lane.

The core of GDD cannot be switched off for red. A red table (with or without a lane) that says mutation = false, reviewer = false, g4_if_g1 = false or review = "quick" refuses the whole file:

error: gdd/rules.toml: red changes always get mutation testing, the Reviewer and the human G4 (the core of GDD): remove color.red.full.mutation = false from gdd/rules.toml

A review depth other than quick or deep, and a color other than green, yellow or red, are refused too. Red never travels the fast lane: [color.red.fast] is never used.

The lane of a change is fast when its color is not red, it has no new or changed scenarios and it was created with --resumable; full otherwise. See Lanes.

[protected]¶

The paths each role must not change, as patterns (see zones.toml). Path Guard checks them in G2 and G3, before and after the commands, after each test-mode round, and in gdd guard.

A role must not touch the paths of all plus its own list. Independently of these lists, every role fails Path Guard when a scenario file approved at G1 changed after the approval.

gdd init writes all as gdd/**, bin/**, .github/**, .claude/**, .agents/**, .opencode/**, .gdd/bin/**, AGENTS.md and CLAUDE.md, and builder_build and builder_test from the stack sheets.

models.toml¶

Who plays each role: an agent (integration) and its model. Read by gdd new-change, gdd classify and gdd prepare (the model of each role goes into the decision of the change), by gdd launch and gdd resume (which agent to start), by gdd status and by gdd agents. gdd init writes it from --agents and the defaults of each agent; see Roles.

[orchestrator]
integration = "claude"
model = "opus"

[builder.green]
integration = "claude"
model = "haiku"

[builder.yellow]
integration = "claude"
model = "sonnet"

[builder.red]
integration = "claude"
model = "opus"

[builder_test]
integration = "claude"
model = "sonnet"

[reviewer]
integration = "codex"
model = "gpt-6-astra"
effort = "high"

[families]
"claude" = "anthropic"
"codex" = "openai"

[orchestrator], [builder.\<color>], [builder_test], [reviewer]¶

The model of each role. [builder.<color>] is the Builder in build mode for changes of that color (green, yellow, red); [builder_test] is the Builder in test mode for every color; [orchestrator] replans a change stuck in G2; [reviewer] reviews every change that has a Reviewer. A role without a table has no agent: its call fails.

Other keys of a role table are kept, as they are, in the decision of the change.

[families]¶

Which model family each model belongs to. The Reviewer must be of another family than the Builder, so it does not share its blind spots.

The family of a model is that of the first key, in file order, its model name starts with or its integration equals; else the integration itself. gdd init writes one key per agent: claude is anthropic, codex is openai, opencode is minimax.

[session]¶

Not written by gdd init.

A change gets a shared session only when [builder_test] and its [builder.<color>] use the same integration and that agent's sheet says how to resume a session (Claude Code today); else it runs separate and gdd status says why. The Reviewer and the Orchestrator never join it. gdd launch and gdd resume read this table from the main checkout.

[env]¶

Not written by gdd init.

[prices.\<model>]¶

Not written by gdd init. The price of a model, for agents that report no cost (Codex): one table per model name, as model writes it.

The estimate goes to the call's line in the log. The record of the change, and so the spike budget, keeps only what the agent reported.

commands.toml¶

The commands the machines run: the gate commands, the Learn tools, how to count known debt, the self-test's failing test and the release steps. Every command is one line of shell, run with sh -c from the project root, with nothing on its standard input; it passes with exit code 0. gdd init writes this file from the stack sheets (what gdd stacks compose prints) followed by the [release] section. Text an agent writes never reaches a shell: only these commands do.

Top level¶

[g2]¶

The commands of the Loop Gate (G2), run on every Builder round and by gdd g2.

• A value that is blank, or not a string, is not configured: it never runs and is not listed.
• A gate without any configured command fails (G2 not configured).
• A command whose name starts with mutation runs only when the change needs mutation testing; otherwise it is listed under skipped.
• Every command gets GDD_CHANGE, GDD_COLOR, GDD_DIFF_FILES and GDD_FEATURES; see Environment variables.
• A failed command keeps, in the gate report, the first 40 lines of its output that report a failure (they start with error or hold FAILED, Failed, failed, panicked, Error:, Traceback or ✘), then the last 2,500 characters.

The stack sheets name G2 commands lint, types, unit, acceptance and architecture.

[g3]¶

The commands of the Merge Gate (G3), run by the recipe after G2 and by gdd g3. Same rules as [g2]. The stack sheets name them acceptance_full, lockfile, security, dependencies, secrets and mutation. gdd status warns when no [g3] command starts with mutation: red changes would go without mutation testing.

gdd adopt runs each G2 and G3 command once, except the ones whose name starts with acceptance, mutation or secrets.

[learn]¶

The tools gdd learn runs once on the project: warnings, never a gate.

The stack sheets name them duplication and unused.

[count]¶

How to count what a command with known debt reports, so its debt has a ceiling (a ratchet).

A command with known debt that fails passes the gate while its count stays at or below the count in gdd/debt.toml. Reporting more, or a count gdd cannot read, fails the gate.

[selftest]¶

The deliberately failing test of the harness self-test (gdd selftest, check 1).

[protected]¶

gdd init writes the [protected] table of the composed stack sheets here too. gdd does not read it from this file: the lists Path Guard uses are in gdd/rules.toml.

[release]¶

The release steps. Read by gdd merge, gdd release and gdd selftest. Each step runs its command, never anything else, within [limits] command_seconds, with GDD_CHANGE and, once the change has a version, GDD_VERSION.

A blank value counts as no command.

release.toml¶

There is no gdd/release.toml in a project. The release steps live in the [release] table of gdd/commands.toml: gdd init appends them there from its template.

generated.toml¶

What gdd init wrote once and what it was asked, so gdd upgrade can render the same files with a newer gdd and merge them with the project's edits. Written by gdd init; rewritten by gdd upgrade on its gdd-upgrade branch. Do not edit it by hand.

Top level¶

[answers]¶

gdd upgrade refuses a project without this file or without [answers].

debt.toml¶

The known debt of a project that already had code: the gate commands that failed when gdd adopt ran. They warn instead of failing a gate until a change makes each pass. Written by gdd adopt, which commits it alone and refuses to run once it exists; a merge removes the debt its gates paid and lowers the counts its gates reported lower.

adopted = "2026-10-30"

[[debt]]
command = "lint"
gate = "g2"
since = "2026-10-30"
count = 3

Top level¶

[[debt]]¶

A debt file gdd cannot read fails the gate check debt, and the first check of gdd selftest, which holds G2 to the same debt.

See also¶

• Gates: what each gate runs with these settings, by color.
• Stacks: where the commands and protected paths of gdd init come from.
• Tune the gates: change commands and limits step by step.
• Command reference: the flags that fill these files.