GDD Folder Plan

Status: DRAFT
Updated: July 19, 2026

Goal

The gdd/ folder is the single source of truth for all project knowledge — not just game design but architecture, references, and implementation context. No document about this project lives anywhere else.

Folder Structure (Proposed)

gdd/
├── master_gdd.md                  # Master Game Design Document (already exists)
├── gdd-folder-plan.md             # This file
│
├── design/                        # Feature-level design docs
│   ├── battle-system.md           # CT timeline deep dive, damage formulas, turn order
│   ├── aspect-catalog.md          # Every aspect: stats, abilities, upgrade trees
│   ├── enemy-catalog.md           # Enemy stats, behaviors, factions, AI scripts
│   ├── level-generation.md        # Grammar rules, templates, validator details
│   ├── roguelike-structure.md     # Island/floor specs, node types, relic tables
│   ├── meta-progression.md        # Unlock shop, currencies, difficulty modifiers
│   ├── co-op-design.md            # Cross-player synergies, ghost mode, netcode
│   ├── narrative-tone.md          # Character voices, last-will templates, meta-story
│   └── ui-ux-design.md            # HUD layout, tooltips, timeline bar, ping system
│
├── architecture/                  # Technical design & architecture decisions
│   ├── tech-stack.md              # Unity version, packages, rendering pipeline
│   ├── grid-system.md             # Coordinate system, height layers, tile data model
│   ├── aspect-data-model.md       # ScriptableObject schema, slot system, serialization
│   ├── proc-gen-pipeline.md       # Generation pipeline stages, grammar engine
│   ├── save-system.md             # Run state serialization, meta-progress persistence
│   ├── networking.md              # Co-op model, turn-passing protocol, Steamworks
│   └── folder-structure.md        # Unity Assets/ directory conventions
│
├── reference/                     # External references & inspiration
│   ├── fft-mechanics.md           # FFT mechanics we're borrowing / adapting
│   ├── itb-mechanics.md           # Into the Breach mechanics reference
│   ├── disgaea-tone.md            # Tone/comedy reference from Disgaea
│   └── roguelike-benchmarks.md    # Slay the Spire / ITB run lengths, meta-progression
│
└── archive/                       # Superseded / deprecated docs
    └── breach_tactics_gdd-v1.md   # v1.0 GDD (now consolidated into master_gdd.md)

Rules

Rule	Why
One folder for all docs. No docs in Assets/MCP/Context/ or READMEs scattered in code.	Single source of truth.
Design and architecture are separate. Design = what the player experiences. Architecture = how the code is shaped.	Avoids mixing "should fireballs cost 10 MP?" with "should SpellData be a struct or class?"
Architecture docs live in gdd/, not in code. No architecture.md inside Assets/.	Designers read design docs; engineers read architecture docs. Both live in the same tree.
Markdown only. No Word, Google Docs, or Notion.	Git-friendly, diffable, searchable.
Master GDD is the overview. Feature docs drill into one topic. No duplication.	Single source of truth per fact.
Archive, don't delete. Old/deprecated docs move to archive/.	History is free in git. Keep the pointer.

Implementation Steps

Create folder structure — design/, architecture/, reference/, archive/
Extract from master_gdd.md — Sections 3–10 are dense enough to warrant standalone docs. Create stub files with > (extracted from master_gdd.md §X) headers.
Replace master GDD sections with links — After extraction, each section becomes a 1-paragraph summary + link to the full doc.
Write architecture docs — Start with tech-stack.md, grid-system.md, aspect-data-model.md as blockers before Unity prototyping begins.
Add reference docs — Capture the specific mechanics being borrowed from FFT, ITB, Disgaea, and StS.
Update Unity MCP context — Point the Assets/MCP/Context/ system to read from gdd/ instead of maintaining separate context files.

Migration Notes

master_gdd.md §13 (Open Questions) lists items needing migration from the old job-system GDD. Those answers get written into design/aspect-catalog.md.
The old breach_tactics_gdd.md (v1.0) and aspect-system-design.md (v1.0) are already consolidated into master_gdd.md. Move originals to archive/ if they still exist on disk.
Any docs currently in Assets/MCP/Context/ should be audited and either moved to gdd/ or deleted (if the gdd version supersedes them).

GDD Folder Plan ​

Goal ​

Folder Structure (Proposed) ​

Rules ​