Planning Artifacts
Everything PP Core knows about a project is written to the .planning/ directory. These artifacts are the project's durable memory: they capture intent, decisions, plans, results, and verdicts as files on disk, so the work never depends on a conversation that will eventually be lost.
The Directory Layout
A .planning/ directory holds a set of root-level documents that describe the project as a whole, a phases/ tree where each phase keeps its own artifacts, and several supporting directories for research and other long-running material.
.planning/
├── PROJECT.md
├── REQUIREMENTS.md
├── ROADMAP.md
├── STATE.md
├── continue-here.md
├── config.json
├── phases/
│ └── 01-phase-name/
│ ├── 01-CONTEXT.md
│ ├── 01-DISCUSSION-LOG.md
│ ├── 01-RESEARCH.md
│ ├── 01-01-PLAN.md
│ ├── 01-01-SUMMARY.md
│ ├── 01-VERIFICATION.md
│ └── 01-UAT.md
├── research/
│ ├── SUMMARY.md
│ ├── STACK.md
│ ├── FEATURES.md
│ ├── ARCHITECTURE.md
│ └── PITFALLS.md
├── codebase/
├── debug/
├── spikes/
├── sketches/
├── threads/
├── seeds/
└── todos/
Root-Level Artifacts
These files describe the project at the top level and persist for its entire lifetime.
| File | Contents |
|---|---|
PROJECT.md | The single source of truth for the project's vision, architectural constraints, and non-negotiable decisions, with an optional business context section |
REQUIREMENTS.md | Scoped, numbered requirements grouped into tiers (v1, v2, out of scope), each with a stable ID for traceability |
ROADMAP.md | The ordered list of milestones and phases, showing status and the requirement IDs each phase satisfies |
STATE.md | The living memory of the project: current loop position, active decisions, blockers, and metrics |
continue-here.md | A cross-session handoff summarizing completed work and concrete next steps |
config.json | Workflow configuration such as feature flags, model profiles, and behavior settings |
Per-Phase Artifacts
Each phase gets its own directory under phases/, named with a numeric prefix (for example 01-phase-name/). File prefixes encode the phase number and, for plans and summaries, the plan number within the phase.
| File | Contents |
|---|---|
XX-CONTEXT.md | Implementation preferences as numbered decisions on libraries, patterns, and testing |
XX-DISCUSSION-LOG.md | The full audit trail of the discuss step, including reasoning |
XX-RESEARCH.md | Synthesized research on stack, features, architecture, and package legitimacy |
XX-YY-PLAN.md | An atomic execution plan with tasks, acceptance criteria, dependencies, and requirement mappings |
XX-YY-SUMMARY.md | Post-execution record of what was implemented, deviations, and issues resolved |
XX-VERIFICATION.md | The verifier's pass or fail verdict, backed by evidence of requirement satisfaction |
XX-UAT.md | Manual acceptance testing results and the human judgment on phase readiness |
A phase that also produces a spec contract during planning will record it in a SPEC.md alongside these files, defining exactly what the phase delivers before the plan is written.
Supporting Directories
The remaining directories hold material that spans phases or supports specific workflows.
research/— domain research outputs such asSUMMARY.md,STACK.md,FEATURES.md,ARCHITECTURE.md, andPITFALLS.md.codebase/— structured mapping of an existing (brownfield) codebase.debug/— active debugging sessions with persistent state.spikes/— feasibility experiments.sketches/— throwaway HTML mockups for UI exploration.threads/— persistent cross-session knowledge.seeds/— forward-looking ideas not yet scheduled.todos/— captured ideas, split into pending and done.
Why It Is Organized This Way
The naming and nesting are what make the artifacts useful rather than just numerous. Numeric prefixes keep phases and their plans in order, requirement IDs let any line of work trace back to the need it serves, and the strict separation between root-level and per-phase files keeps project-wide truth distinct from phase-specific detail. Because all of it lives in .planning/, the directory is portable, reviewable, and version-controllable like any other part of the codebase.