Skip to content

Project Structure

Jump to bottom
David Sienkowski edited this page Mar 16, 2026 · 3 revisions

Project Structure

When you run /pbr:new-project or /pbr:setup, Plan-Build-Run creates a .planning/ directory in your project root. This directory holds all project state and survives across sessions, context resets, and machine reboots.

Directory Layout

.planning/
├── PROJECT.md              # Project vision, scope, goals, and context (locked decisions)
├── REQUIREMENTS.md         # Scoped requirements with REQ-IDs (traceable)
├── ROADMAP.md              # Phase structure with status tracking
├── STATE.md                # Current position + history — the source of truth
├── config.json             # Workflow preferences (12 top-level keys)
├── phases/
│   ├── 01-foundation/
│   │   ├── 01-01-PLAN.md       # Executable plan with must-haves and wave assignment
│   │   ├── 01-02-PLAN.md       # Second plan in the phase
│   │   ├── SUMMARY-01-01.md    # Execution results from the executor
│   │   ├── SUMMARY-01-02.md    # Execution results for plan 02
│   │   └── VERIFICATION.md     # 3-layer verification report
│   └── 02-auth/
│       ├── 02-01-PLAN.md
│       ├── SUMMARY-02-01.md
│       └── VERIFICATION.md
├── research/               # Phase research outputs from researcher agents
│   ├── phase-01-domain.md
│   ├── phase-01-approach.md
│   └── phase-02-domain.md
├── seeds/                  # Future-phase idea triggers from /pbr:explore
│   └── auth-approach.seed.md
├── todos/
│   ├── pending/            # Active todo items (one file per todo)
│   │   ├── 001-setup-ci.md
│   │   └── 002-add-tests.md
│   └── done/               # Completed todos (moved here by /pbr:check-todos)
│       └── 003-init-repo.md
├── notes/                  # Idea captures from /pbr:note (one file per note)
│   └── 2026-03-01-auth-approach.md
├── debug/                  # Hypothesis-driven debug sessions from /pbr:debug
│   └── session-001/
├── milestones/             # Milestone archives (directory-based)
│   └── v1.0.0/
│       ├── ROADMAP.md
│       ├── STATS.md
│       └── phases/
├── quick/                  # Quick task tracking from /pbr:quick
│   └── 001-fix-typo/
│       ├── PLAN.md
│       └── SUMMARY.md
├── audits/                 # Session audit reports from /pbr:audit
│   └── 2026-03-01-session-audit.md
├── codebase/               # Codebase scan outputs from /pbr:map-codebase
│   └── map.md
└── logs/                   # Hook activity logs (JSONL, max 200 entries)
    └── .hook-log

Key Changes from v1

v1 v2.0.0 Migration
CONTEXT.md (standalone file) PROJECT.md ## Context section Locked decisions are now part of the project file
HISTORY.md (standalone file) STATE.md ## History section State and history are unified in one file
PLAN-01.md naming {NN}-{MM}-PLAN.md naming (e.g., 01-01-PLAN.md) Phase number prefix enables cross-phase references
27 skills 28 skills + 41 commands New skills: statusline, plus command aliases

Key Files

STATE.md

The single source of truth for where you are in the project. Updated automatically by hooks and CLI tools.

Contains:

  • Current phase number and name
  • Current step (planning, building, reviewing)
  • Phase progress (plans completed / total)
  • Last action taken
  • History of completed phases and milestones
  • Any active locks or in-progress operations

ROADMAP.md

A markdown table listing all phases with:

  • Phase number and name
  • Goal description
  • Status (planned, in-progress, complete)
  • Plan count (completed/total)
  • Dependencies on other phases

PROJECT.md

Project vision, scope, and high-level goals. Includes a ## Context section with locked decisions and constraints (previously stored in the separate CONTEXT.md). Written by /pbr:new-project and updated by /pbr:discuss-phase.

PLAN Files

Each plan file follows a required format (enforced by hooks):

  • YAML frontmatter with wave assignment, plan number, description
  • Must-haves section declaring what the plan must achieve
  • XML <task> elements with action steps and verification commands
  • Dependencies on other plans

Plan naming: {NN}-{MM}-PLAN.md where NN is the phase number and MM is the plan number within the phase.

VERIFICATION.md

Written by the verifier agent after /pbr:verify-work. Contains three-layer check results:

  • Existence: Does the file/function/route exist?
  • Substance: Is it implemented (not a stub or placeholder)?
  • Wiring: Is it connected to the rest of the system (imported, called, routed)?

config.json

Workflow configuration with 12 top-level keys. See Configuration for the full reference.

File Ownership

File Written By Read By
PROJECT.md /pbr:new-project, /pbr:discuss-phase All skills and agents
REQUIREMENTS.md /pbr:new-project Planner, verifier
ROADMAP.md /pbr:new-project, planner, pbr-tools.cjs All skills
STATE.md pbr-tools.cjs CLI, hooks All skills, progress-tracker.js
{NN}-{MM}-PLAN.md Planner agent Executor, plan-checker, verifier
SUMMARY-*.md Executor agent Verifier, review skill
VERIFICATION.md Verifier agent Review skill, /pbr:plan-milestone-gaps
research/*.md Researcher agent Planner
seeds/*.seed.md /pbr:explore Planner (auto-injected)
todos/pending/*.md /pbr:add-todo /pbr:check-todos, /pbr:statusline
quick/*/PLAN.md /pbr:quick Executor
milestones/*/ /pbr:complete-milestone /pbr:audit-milestone
codebase/map.md /pbr:map-codebase Planner, researcher

Gitignore Recommendation

Add .planning/ to your .gitignore unless you want to track planning state in version control. Some teams find it useful to commit planning artifacts for audit trails.

Clone this wiki locally