Files gdd writes¶

Every file and folder gdd writes in a project: what gdd init leaves, the local state in .gdd/ (records, reports, the log, the Decision Inbox, the agents' outputs), which of them are committed, which only gdd may write, and what the merge commit of a change carries.

A project after gdd init¶

gdd init --name notes --platform cli --stack python --agents claude codex in an empty repository commits these files (the agents' commands are listed once per agent folder):

.agents/skills/gdd-<command>/SKILL.md   # Codex: the GDD commands and gdd-stack-python
.claude/skills/gdd-<command>/SKILL.md   # Claude Code: the same
.github/workflows/gdd.yml               # CI: the stack setup, gitleaks, gdd, bin/gdd ci
.gitignore                              # the stack's lines and .gdd/
AGENTS.md                               # instructions for agents, when the project had none
CLAUDE.md                               # @AGENTS.md, when the project had none
bin/gdd                                 # entry point of the agents and CI
docs/brief.md                           # the Project Brief
features/.gitkeep                       # the scenario folder
gdd/commands.toml
gdd/generated.toml
gdd/models.toml
gdd/project.toml
gdd/rules.toml
gdd/zones.toml
osv-scanner-licenses.toml               # from here on: the Python skeleton
osv-scanner.toml
pyproject.toml
src/notes/__init__.py
src/notes/greeting.py
tests/__init__.py
tests/acceptance/__init__.py
tests/acceptance/steps/__init__.py
tests/acceptance/test_features.py
tests/unit/__init__.py
tests/unit/test_greeting.py

gdd init never overwrites a file, never writes through a link, and commits only what it wrote (gdd init <version>), in a new repository when the folder is in none. gdd bootstrap then commits the lock files (gdd bootstrap). gdd adopt commits gdd/debt.toml.

Committed and local¶

The record of each change reaches git only through its merge commit.

.gdd/¶

The local state. Every worktree of a repository shares the .gdd/ of its main checkout (the state root): a change runs in its own worktree and still reads and writes the same records. gdd refuses to run in a worktree of a bare repository.

.gdd/
├── log.jsonl                 # one JSON line per agent call, gate decision and machine step
├── g0.json                   # G0, opened by the machines
├── zones.json                # the human's approval of the red zones
├── selftest.json             # the last harness self-test
├── headless_sessions.txt     # sessions gdd started for its agents
├── imported_requests.json    # requests of interactive sessions already in the log
├── agents.lock  launch.lock  merge.lock  state.lock
├── adoption/<command>.txt    # gdd adopt: what each failing command said
├── learn/<tool>.txt          # gdd learn: what each Learn tool said
├── selftest/kept/            # gdd selftest: a file set aside while the check runs
├── upgrade/                  # gdd upgrade: scratch folder, removed after each run
├── bin/                      # protected; gdd does not write it
└── changes/<id>/
    ├── change.json           # the record
    ├── inbox.md              # the Decision Inbox
    ├── plan.md               # the plan of a red change (the Orchestrator)
    ├── package.md            # the minimum context package (the Orchestrator)
    ├── replan.md             # the last replan (the Orchestrator, headless)
    ├── review.md             # the last review (the Reviewer's text, kept by gdd)
    ├── g2.json  g3.json      # the last report of each gate
    ├── snapshot.json         # gdd snapshot
    ├── snapshot-build.json   # the snapshot taken after test mode
    ├── run.json              # while the change waits at G4
    ├── outputs/              # every agent call: <role>-<n>.md and <role>-<n>.raw
    └── demo/                 # what the demo step leaves for G4

change.json¶

The record of a change: what it plans, what its gates decided, its notes and its state. Indented JSON. Only gdd writes it: the gdd commands an agent may run (gdd note, a gate in build mode) change only inbox and out_of_scope, and gdd puts back any other change an agent makes.

The record of a change merged and promoted in a throwaway project, trimmed:

{
  "build_start": "ca7bc9c0d5369ef863aab8d6f7651f64056215ed",
  "changelog": {
    "breaking": false,
    "line": "The cart shows its total",
    "section": "Added"
  },
  "commit": "8b14c1a9ab22d8931b010ad51499c8242ff03e4a",
  "created": "2026-10-30T13:11:40+00:00",
  "decision": {
    "builder": {
      "integration": "claude",
      "model": "sonnet"
    },
    "builder_session": "separate",
    ...
    "type": "Feature"
  },
  "features": [
    "features/cart.feature"
  ],
  "gates": {
    "G1": {
      "by": "human",
      "decision": "ok",
      "hashes": {
        "features/cart.feature": "06a581fd190d4dc2e48f33c21323302a67e522e74b8bacce3dd2b51c3fdce716"
      },
      "note": "approved at the sitting",
      "ts": "2026-10-30T13:11:46+00:00"
    },
    ...
  },
  "id": "cart-total",
  "inbox": [
    {
      "kind": "decided",
      "text": "Kept the total as an integer",
      "ts": "2026-10-30T13:11:53+00:00"
    },
    ...
  ],
  "min_color": null,
  "out_of_scope": [
    "docs/extra.md"
  ],
  "paths": [
    "src/shop/**",
    "features/cart.feature"
  ],
  "resumable": false,
  "state": "closed",
  "title": "Show the cart total",
  "type": "Feature",
  "version": "0.1.0"
}

Records written by an older tool may have other fields; gdd ignores them.

gates¶

Each entry has decision (ok or ko), by (human or machines), ts and note. G1 also has hashes: each sealed scenario file and its SHA-256.

inbox¶

Each note has kind, text and ts, and resolved (when it was resolved) once a relaunch resolved it. kind is needs (a decision for the human), decided (taken without them), parked (why it stopped) or polish (the human's notes at G4).

decision¶

The classification of the change when it was prepared, and the model of each role.

reviews¶

One entry per Reviewer call, in order, relaunches included.

variants¶

One entry per variant of a spike: option (the option it builds, or null for the same brief), branch (change/<id>-v<n>), and once built state (ready or parked), reason, g2, adrs, decision (the first line of its ADR's decision), files, minutes, usd and tokens.

States¶

inbox.md¶

The Decision Inbox: one message per change, rendered from the record and the gate reports each time they change. gdd inbox <id> prints it.

# Decision Inbox · cart-total · Show the cart total

Color yellow · lane full · state closed

## Needs your decision
- Should the total show taxes

## Decided without you
- Kept the total as an integer
- Paths outside the package, same or lower color, accepted by rule: docs/extra.md

## Parked
- Nothing.

Its groups, in order, each only when it has something (the three note groups always show): How it works (from the Reviewer's OK), Variants, Needs your decision, Decided without you, Parked, Security exceptions this change adds, Known debt, Known debt paid, Polish; then how many earlier requests were resolved before the last launch.

Gate reports¶

g2.json and g3.json hold the last run of each gate on the change.

{
  "ok": true,
  "gate": "G2",
  "color": "yellow",
  "passed": [
    "lint",
    "unit",
    "path-guard",
    "scope"
  ],
  "skipped": [],
  "failures": [],
  "out_of_scope": [
    "docs/extra.md"
  ]
}

log.jsonl¶

One JSON object per line, appended under a lock, so the lines of two runs never mix. gdd writes a line for every agent call, gate decision, gate command, Path Guard run and machine step. gdd session adds the interactive Claude Code sessions. Reports leave out the lines that are not gdd's (not JSON, or a cost that is not a number of zero or more) and say how many.

{"ts":"2026-10-30T13:11:46+00:00","change":"cart-total","phase":"2-build","gate":"G2","role":"machine","agent":"lint","model":"-","tokens_in":0,"tokens_cache":0,"tokens_out":0,"cost_usd":0.0,"duration_s":0.0,"result":"ok","retry":0,"note":""}
{"ts":"2026-10-30T13:11:46+00:00","change":"cart-total","phase":"2-build","gate":"G2","role":"machine","agent":"checks","model":"-","tokens_in":0,"tokens_cache":0,"tokens_out":0,"cost_usd":0.0,"duration_s":0.0,"result":"ok","retry":0,"note":""}

The merge commit¶

gdd merge merges a change into the main branch with a commit whose message carries its record, so what the change was and who approved it travels with the code while .gdd/ stays local. The merge commit of the same change, trimmed:

gdd(cart-total): G3 Merge Gate · Show the cart total

Color: yellow · lane full · type Feature
Approvals: G1 ok (human, 2026-10-30, 1 scenario file(s) sealed)
Decided without the human:
  - Kept the total as an integer
...
Record: .gdd/changes/cart-total/ (local)

Changelog: Added · The cart shows its total
Breaking: no

gdd changelog and gdd release read the Changelog: and Breaking: trailers of the merge commits on main to write CHANGELOG.md and to pick the next version.

See also¶

• Configuration: the files in gdd/.
• Environment variables: what the commands and agents that write these files receive.
• Get a parked change going again: reading the Decision Inbox.
• Measure the work: reports built from log.jsonl.