.planning/ Directory Structure

Overview of the .planning directory structure and what files live where

The .planning/ directory is the central workspace for all GSD project management files. It contains everything Claude needs to understand your project, track progress, and maintain context across sessions.

Directory Structure

.planning/
├── PROJECT.md              # Project vision and requirements
├── REQUIREMENTS.md         # Checkable requirements with traceability
├── ROADMAP.md             # Phases and execution plan
├── STATE.md               # Living memory across sessions
├── config.json            # Project configuration
├── research/              # Domain research findings
│   ├── ARCHITECTURE.md
│   ├── FEATURES.md
│   ├── PITFALLS.md
│   ├── STACK.md
│   └── SUMMARY.md
├── codebase/              # Existing codebase analysis (brownfield)
│   ├── architecture.md
│   ├── concerns.md
│   ├── conventions.md
│   ├── integrations.md
│   ├── stack.md
│   ├── structure.md
│   └── testing.md
├── phases/                # Phase-specific plans and summaries
│   ├── 01-foundation/
│   │   ├── 01-01-PLAN.md
│   │   ├── 01-01-SUMMARY.md
│   │   ├── 01-02-PLAN.md
│   │   ├── 01-02-SUMMARY.md
│   │   └── 01-RESEARCH.md
│   ├── 02-features/
│   │   └── ...
│   └── ...
├── quick/                 # Quick mode tasks
│   ├── 001-fix-login-bug/
│   │   ├── PLAN.md
│   │   └── SUMMARY.md
│   └── ...
├── todos/                 # Captured ideas
│   ├── pending/
│   └── completed/
└── milestones/            # Archived milestone work
    └── v1.0-mvp/
        └── (archived phase directories)

Root Files

Core Documents

• PROJECT.md - Living project context (vision, requirements, constraints, decisions)
• REQUIREMENTS.md - v1/v2 requirements with phase traceability
• ROADMAP.md - Phases with goals, dependencies, and success criteria
• STATE.md - Current position, metrics, decisions, blockers
• config.json - Project configuration (mode, granularity, model profile, workflow settings)

Research Directories

research/ - Domain Research (Greenfield)

Created during /gsd:new-project, contains parallel research findings:

• ARCHITECTURE.md - System design patterns and structure
• FEATURES.md - Existing feature analysis in the domain
• PITFALLS.md - Common mistakes and anti-patterns
• STACK.md - Technology choices and rationale
• SUMMARY.md - Synthesized insights for quick reference

codebase/ - Codebase Analysis (Brownfield)

Created during /gsd:map-codebase for existing projects:

• architecture.md - Current system architecture
• concerns.md - Known issues and technical debt
• conventions.md - Code standards and patterns
• integrations.md - External services and APIs
• stack.md - Current tech stack analysis
• structure.md - File organization and modules
• testing.md - Testing setup and coverage

Phase Work

phases/XX-name/ - Phase Execution

Each phase gets its own directory:

• XX-CONTEXT.md - Implementation decisions from /gsd:discuss-phase
• XX-RESEARCH.md - Phase-specific research findings
• XX-YY-PLAN.md - Executable task plan (Phase XX, Plan YY)
• XX-YY-SUMMARY.md - Completion summary with decisions and changes
• XX-VERIFICATION.md - Goal verification report
• XX-UAT.md - User acceptance testing results (from /gsd:verify-work)

Plan Naming Convention

• Format: {phase}-{plan}-PLAN.md
• Examples:
  • 01-01-PLAN.md - Phase 1, Plan 1
  • 01-02-PLAN.md - Phase 1, Plan 2
  • 02.1-01-PLAN.md - Inserted phase 2.1, Plan 1

Quick Mode

quick/NNN-description/

Ad-hoc tasks tracked separately from phases:

• PLAN.md - Quick task plan
• SUMMARY.md - Completion summary

Numbered sequentially (001, 002, 003…) with descriptive slugs.

Todos

todos/pending/ and todos/completed/

Ideas captured via /gsd:add-todo:

• Each todo is a markdown file
• Moved from pending/ to completed/ when done
• Referenced in STATE.md

Milestones

milestones/vX.Y-name/

Completed milestone work archived via /gsd:complete-milestone:

• Phase directories moved here after milestone ships
• Keeps .planning/phases/ focused on current work
• Preserves history for reference

File Size Constraints

GSD enforces size limits to keep Claude’s quality high:

File	Max Size	Reason
PROJECT.md	Small	Read first in every workflow
STATE.md	~100 lines	Quick context restoration
PLAN.md	~50% context	Room for implementation
SUMMARY.md	Varies	Complex plans get detailed summaries

Workflow File Access

Every workflow starts by reading:

1. STATE.md (current position)
2. PROJECT.md (core context)
3. ROADMAP.md (phases and progress)

Planning reads:

• REQUIREMENTS.md (what to deliver)
• Research files (how to build it)
• Prior SUMMARY.md files (what’s already done)

Execution reads:

• PLAN.md files (what to implement)
• CONTEXT.md (implementation decisions)
• RESEARCH.md (domain knowledge)

Git Tracking

By default (planning.commit_docs: true):

• All .planning/ files are committed
• Each task gets atomic commits
• History is preserved for future sessions

Disable via /gsd:settings if you prefer to keep planning docs local.

See Also

• PROJECT.md Structure
• REQUIREMENTS.md Structure
• ROADMAP.md Structure
• STATE.md Structure
• PLAN.xml Structure