Plan-PRD Pattern: Markdown-Staged Planning Flow

A lightweight, SDLC-aligned planning workflow where each phase of the lifecycle produces a committable markdown staging file that the next command consumes.

Short version: /plan-prd writes a PRD, /plan writes a plan, the tdd-workflow skill implements it, and /pr ships it. Each arrow is a file on disk, not a conversation in memory.

Feature: Markdown Staging Files

Every planning artifact is a plain .md file under .claude/:

.claude/
  prds/      # Product Requirements Documents from /plan-prd
  plans/     # Implementation plans from /plan
  reviews/   # Code review artifacts from /code-review

These files are:

• Plain markdown — readable by humans, diffable in PRs, grep-able at CLI.
• Committable — check them in alongside code so the intent travels with the implementation.
• Composable — each command accepts the previous stage's file as its $ARGUMENTS, so the toolchain composes via paths rather than in-context state.
• Resumable — close the session, open a new one tomorrow, pass the file path back in.

Flow

┌───────────────────────────┐
│ /plan-prd "<idea>"        │  Requirements phase
│  → .claude/prds/X.prd.md  │   Problem · Users · Hypothesis · Scope
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ /plan <prd-path>          │  Design phase
│  → .claude/plans/X.plan.md│   Patterns · Files · Tasks · Validation
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ tdd-workflow skill         │  Implementation phase
│  → code + tests           │   Test-first, minimal diff
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ /pr                        │  Delivery phase
│  → GitHub PR               │   Links back to PRD + plan
└───────────────────────────┘

Each box is a gate. You can:

• Stop between gates — the artifact persists.
• Restart from any gate using the artifact path.
• Skip gates for small work — feed /plan free-form text and ignore /plan-prd.
• Run a gate standalone — /plan "refactor X" produces a conversational plan with no artifact.

Why /plan-prd Is Additional to /plan

They answer different questions. Mixing them causes scope creep.

Why not combine them?

• Separation of concerns. PRDs ask why; plans ask how. Bundling them creates one oversized command that does both poorly, as the old /prp-prd → /prp-plan pair demonstrated (8-phase interrogation with implementation-phase tables mixed into requirements).
• Different audiences. A stakeholder reviewing a PRD does not care about file paths or type-check commands. An engineer reading a plan does not need the market-research phase.
• Different lifespans. A PRD can remain stable while its plan is rewritten multiple times as implementation assumptions change.
• Optional step. Many changes (bug fixes, small refactors, single-file additions) don't need a PRD. /plan alone is enough. Forcing a PRD on every change is bureaucracy.

When to use each

Use /plan-prd when:

• Scope is unclear or contested.
• Multiple stakeholders need to align on the problem before solutioning.
• The change is large enough that writing down the hypothesis is cheaper than relitigating scope mid-implementation.

Use /plan directly when:

• Requirements are already clear (a bug report, a scoped refactor, a known migration).
• The work is small enough that a conversational plan + confirmation gate is sufficient.
• You already have a PRD — pass it to /plan and skip /plan-prd.

Usage

Full flow (feature with unclear scope)

# 1. Draft the PRD
/plan-prd "Per-user rate limits on the public API"

# → .claude/prds/per-user-rate-limits.prd.md created
# Answer the framing questions, provide evidence, define hypothesis and scope.

# 2. Pick the next pending milestone and produce a plan
/plan .claude/prds/per-user-rate-limits.prd.md

# → .claude/plans/per-user-rate-limits.plan.md created
# The plan includes patterns to mirror, files to change, and validation commands.
# PRD's Delivery Milestones table updates the selected row to `in-progress`.

# 3. Implement test-first
Use the tdd-workflow skill

# 4. Open the PR
/pr
# → PR body auto-references .claude/prds/... and .claude/plans/...

Quick flow (scope already clear)

/plan "Add retry with exponential backoff to the notifier"
# Conversational planning, no artifact.
# Confirm, then use the tdd-workflow skill.

Reference an existing PRD from elsewhere

# PRD was written by someone else, lives in your repo
/plan docs/rfcs/0042-rate-limiting.prd.md

/plan detects any .prd.md path and switches to artifact mode, parsing the Delivery Milestones table.

Why staging files beat in-context state

• Transferable: drop the PRD path into a fresh session and you're caught up — no replaying a long conversation.
• Auditable: the PR reviewer sees what you intended next to what you built.
• Versioned: the staging file evolves in git history, same as code.
• Machine-parseable: /plan programmatically picks the next pending milestone; /pr programmatically links artifacts in the PR body. No prompt engineering required.

Related commands

• /plan-prd — requirements (this pattern entry point).
• /plan — planning (consumes PRDs or free-form text).
• tdd-workflow skill — test-first implementation.
• /pr — open a PR that references PRDs and plans.
• /code-review — reviews local diffs or PRs; auto-detects .claude/prds/ and .claude/plans/ as context.

Compatibility

This pattern adds ECC-native staging-file commands alongside the existing prp-* command set. The legacy PRP commands remain available for deeper PRP workflows and for users who already have .claude/PRPs/ artifacts.

• /plan-prd is the lean requirements entry point for .claude/prds/.
• /plan can consume .prd.md files and produce .claude/plans/ artifacts without requiring the legacy PRP directory layout.
• /pr is the ECC-native PR creation command and can reference .claude/prds/ and .claude/plans/.
• /prp-prd, /prp-plan, /prp-implement, /prp-commit, and /prp-pr remain valid legacy/deep workflow commands.