Project Initialization

GDD lives in a .gdd/ directory at the root of your project.

Step Zero — Add the CLAUDE.md

Step zero is separable from the ICR cycle

Placing a CLAUDE.md in your project root is immediately actionable even before a full ICR cycle has run. It makes Claude Code governance-aware: it reads .gdd/ before acting, surfaces [UNKNOWN] items before generating, and stops at the Synthesis Gate. Step zero makes the agent a governed participant. Step one fills the constraint set it operates within.

Copy the CLAUDE.md template from this repo into your project root. It instructs Claude Code to:

• Read .gdd/CONSTRAINTS.md before every implementation pass
• Surface [UNKNOWN] and [CONFLICT] items before generating
• Trace every governed output back to its constraint ID
• Stop at the Synthesis Gate when ambiguity cannot be resolved

Step 1 — Create the Structure

mkdir -p .gdd/CYCLES .gdd/SPEC

touch .gdd/CONSTRAINTS.md
touch .gdd/RESIDUE.md
touch .gdd/GATES.md

Or say to Claude Code:

Initialize a GDD layer for this project.
Create the .gdd/ folder structure and scaffold
CONSTRAINTS.md, RESIDUE.md, and GATES.md.

The folder structure:

your-project/
  .gdd/
    CONSTRAINTS.md     ← the governed constraint set (primary artifact)
    RESIDUE.md         ← open items requiring human decision
    GATES.md           ← record of human gate decisions
    CYCLES/            ← ICR cycle history (append-only)
      2026-06-26-init.md
    SPEC/              ← optional: domain specs feeding the cycle
  src/
  CLAUDE.md            ← instructs AI agents to respect the GDD layer

The dot-prefix signals to both humans and AI models: this is the governance layer, not the source.

Step 2 — Scaffold CONSTRAINTS.md

Every constraint follows this format:

## CONSTRAINT-001
Status: [RESOLVED / ASSUMED / UNKNOWN / CONFLICT]
Statement: [what must be true]
Stress: [what would break it]
Resolution: [decision made, who made it, when]  ← RESOLVED only
Owner: [person or role responsible]
Date: [YYYY-MM-DD]
Downstream: [src/path/to/file.ts]  ← fill in after implementation

Start with your first ICR cycle output. Use the starter ritual to generate the first pass.

Step 3 — Run the First ICR Cycle

With the structure in place, say to Claude Code:

Read CLAUDE.md and the .gdd/ folder.
Then guide me through the first GDD ICR cycle for this project.
Ask me the questions. Help me stress the assumptions.
Surface the residue. Do not generate any implementation code
until we have a governed constraint set with at least one
resolved constraint and an explicit list of open residue items.

Claude Code will:

1. Ask you to name the domain and the stakes
2. Walk you through writing and stressing assumptions
3. Help you classify each one
4. Compile the unresolvable residue
5. Write the output to .gdd/CONSTRAINTS.md and .gdd/RESIDUE.md
6. Wait for your gate decisions before proceeding to build

Step 4 — Gate and Build

Once the first ICR cycle is complete:

1. Review RESIDUE.md with the relevant stakeholders
2. Record decisions in GATES.md
3. Update CONSTRAINTS.md — move resolved items from [UNKNOWN] to [RESOLVED]
4. Tell Claude Code: "The gate is clear. Proceed."

From this point forward, Claude Code operates within the governed constraint set.

The Ongoing Rhythm

GDD is not a one-time init. It is a cycle that runs alongside the project.

Trigger	GDD action
New feature or phase approaching	Trigger a new ICR cycle → new CYCLES/YYYY-MM-DD-[feature].md
Unexpected discovery during implementation	Claude Code proposes a new constraint → you classify → gate records decision
Project handoff to new team or agent	They read .gdd/ first — it is the onboarding document and the institutional memory