.gdd/ Folder Structure

The .gdd/ directory is the governance layer of your project. It is append-only — files are updated and extended, never deleted or rewritten.

Directory Layout

.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)
    YYYY-MM-DD-[name].md
  SPEC/              ← optional: domain specifications feeding the cycle

CONSTRAINTS.md

The primary artifact. Each 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

Status meanings:

Status	Meaning	Agent directive
[RESOLVED]	Confirmed — source documented	Implement exactly as stated
[ASSUMED]	Believed but unverified	Implement + flag for verification
[UNKNOWN]	Cannot resolve without a decision	Stop — surface to human
[CONFLICT]	Contradicts another constraint	Stop — surface both sides

RESIDUE.md

Every [UNKNOWN] and [CONFLICT] from the current ICR cycle. Format:

## ITEM-001
Statement: [what cannot be resolved]
Cannot resolve because: [reason — what information is missing]
Decision required from: [role or person]
Options: [known options, if any]
Consequence if unresolved: [what breaks if this proceeds without a decision]
Deadline: [before which phase or date]
Status: OPEN / RESOLVED / ACKNOWLEDGED

When an item is resolved, update its status and record the decision here before closing it in GATES.md.

GATES.md

The append-only record of every human gate decision. Format:

## GATE-001
Date: [YYYY-MM-DD]
Residue item: ITEM-001
Decision: [what was decided]
Owner: [who made the decision]
Rationale: [why this decision, if not obvious]
Constraint update: CONSTRAINT-001 → [RESOLVED]

GATES.md is institutional memory. It answers the question "why is this the way it is?" for every governed constraint — especially valuable when the project is handed to a new team or a new AI agent.

CYCLES/

Each ICR cycle run gets its own file — a snapshot of the domain state at that point in the project lifecycle.

Naming convention: YYYY-MM-DD-[domain-area].md

Examples:

CYCLES/
  2026-06-26-init.md           ← first cycle, initial domain
  2026-07-14-joint-applications.md  ← new feature cycle
  2026-08-01-self-employed-path.md  ← deferred workstream

Cycle files are never modified after creation. They are the audit trail of how the constraint set evolved.

SPEC/ (optional)

Domain specifications that feed the ICR cycle — regulatory documents, API contracts, business rules documents, legacy system printouts. Referenced by constraints but not generated by GDD.

---

Back to CLAUDE.md Template