Structured Project Planning

This workflow connects the techniques from Sessions 2-5 into a single disciplined process for tackling non-trivial projects. It is not a new method — it is EPCC, TDD, plan mode, and self-review wired together with explicit checkpoints so nothing gets skipped.

Use it when the task is large enough that skipping a phase would cost you hours of rework: new features, migrations, multi-file refactors, or any work that spans more than one session.

Phase 0 — Context: Read CLAUDE.md, git log, project state
Phase 1 — Explore: Ask every question before planning
Phase 2 — Plan:    Use /plan to propose the approach read-only
Phase 3 — Build:   TDD Red-Green-Refactor for each step
Phase 4 — Persist: Update CLAUDE.md, progress files, /compact
Phase 5 — Verify:  Self-review against acceptance criteria

Global Rules

These apply at every phase. Encode them in your project’s CLAUDE.md so Claude follows them automatically.

1. Never assume. If something is unclear, ask. One question now saves an hour of rework later.
2. Never write implementation code without a confirmed failing test. The RED phase is not optional.
3. Never skip or reorder phases. The phases exist because each one prevents a specific category of mistake.
4. Review at every checkpoint. After exploration, after planning, after each RED/GREEN/REFACTOR cycle — check before proceeding.
5. Tests define correctness. Never change a test to match broken implementation. If the test is wrong, that is a separate deliberate decision with its own rationale.
6. Only build what is specified. No extras, no improvements, no refactors outside the current step’s scope.

Phase 0 — Context Check

What it does: Establishes shared understanding of where the project stands before you start working.

Native features: CLAUDE.md loads automatically. Use claude -c to resume a previous session. Run /context to check how full your context window is.

What to check:

Read CLAUDE.md, then check:
1. Recent git log (last 10-20 commits) -- what changed recently?
2. Any failing tests or CI status
3. Open TODOs and FIXMEs in the area I'll be working
4. Any progress.txt or decisions.md from a prior session

Summarize the current project state in bullet points.

If this is a fresh project, state that. If resuming work, summarize what was completed, what is in progress, and what is blocked.

Checkpoint: Review the context summary. Does it match your understanding? If Claude missed something important, correct it before moving on.

Phase 1 — Explore (Zero Assumptions)

What it does: Eliminates assumptions by asking every question before planning begins. This is the Explore phase of EPCC applied with more rigor.

Native features: Use subagents for parallel investigation when there are multiple independent areas to examine.

Categories to cover:

I need to build [describe the feature/change]. Before we plan anything,
I want to eliminate all assumptions. Ask me questions about:
- Scope and non-goals
- Expected behavior and edge cases
- Existing code conventions and constraints
- Testing requirements and acceptance criteria
- Scale, dependencies, and risks

Keep asking until you have zero open questions.

Checkpoint: Claude should list every open question. Answer all of them before moving to Phase 2. If you cannot answer a question, mark it as a known risk — do not guess.

Phase 2 — Plan (Read-Only)

What it does: Produces a concrete implementation plan with acceptance criteria and planned tests for each step — all before writing any code.

Native features: Enter plan mode with /plan or Shift+Tab. Claude cannot write files in plan mode, which enforces the read-only constraint. Exit with Shift+Tab when you approve the plan.

Implementation plan structure

Each step in the plan must include:

1. What to build — specific files, methods, or components
2. Acceptance criteria — testable conditions that define “done”
3. Planned tests — described but not yet coded (tests are written in Phase 3)
4. Dependencies — which prior steps must be complete first

/plan

Based on our discussion, create an implementation plan. For each step:
1. What to build (specific files and methods)
2. Acceptance criteria (testable conditions)
3. Tests to write first (describe, don't code yet)
4. Dependencies on prior steps

Order steps by dependency -- nothing should reference something
that hasn't been built yet.

Choosing the right planning docs

Not every project needs every document. Generate only what applies:

Checkpoint: Review the complete plan. Check that every step has testable acceptance criteria and that the dependency order makes sense. Approve before any code is written.

Phase 3 — Build (TDD Red-Green-Refactor)

What it does: Implements each step from the plan using strict TDD. This is the same Red-Green-Refactor cycle from Session 3, applied with explicit checkpoints between phases.

For each step in the implementation plan, execute in strict order:

3A — RED (Write Failing Tests)

Write tests for step [N] based on these acceptance criteria:
[paste criteria from the plan]

After writing the tests, run them. Do NOT write any implementation yet.

• Confirm tests fail with a meaningful assertion error (not a compile or import error)
• If tests pass before implementation exists: stop, diagnose, and fix the test

Use /diff to review exactly what test code was written.

Checkpoint: Review the failing test output. Does each test capture the intended behavior?

3B — GREEN (Minimal Implementation)

Write the minimum code to make these tests pass.
Only implement what the tests require -- nothing more.
Run the tests after.

• If tests still fail, fix the implementation — never change the tests to match broken code
• Use /diff to verify Claude did not add logic beyond what the tests demand

Checkpoint: Review the passing test output and the diff. Is the implementation minimal?

3C — REFACTOR

All tests pass. Refactor for clarity and structure.
Run tests after each change to confirm they stay green.
Do not add new behavior -- new behavior requires a new RED cycle.

Checkpoint: Confirm tests still pass. Summarize what was refactored and why.

Phase 4 — Persist

What it does: Captures session state so you (or a teammate) can resume cleanly in a new session.

Native features: Use /compact to compress the conversation while keeping key findings. Use claude -c to resume. Use /rename to name the session for findability. See Sessions & Context for more.

After each completed step, update:

• CLAUDE.md — if conventions or rules changed during implementation
• Progress tracking — what is complete, in progress, next, blocked, and any known issues
• Decisions log — non-obvious decisions and their rationale (why approach A over B)
• Lessons learned — mistakes, fixes, or patterns discovered

/compact focus on the implementation plan, what we've completed
through step [N], and the decisions we made. Forget exploration
details -- I need the plan and progress going forward.

Phase 5 — Verify

What it does: Confirms each step meets its acceptance criteria before moving on. This is the self-review technique from Session 4 applied systematically.

Review the changes we made for step [N]. For each acceptance
criterion from the plan, state PASS or FAIL with evidence.

Be critical -- I'd rather catch issues now than in code review.

Verification checklist:

• RED phase occurred — state the test file and exact failure message
• GREEN phase occurred — paste the passing output
• Each acceptance criterion: PASS or FAIL with evidence
• Progress files updated
• If anything failed: documented what, why, and what prevents it next time

Checkpoint: Review the verification. If everything passes, proceed to the next step (back to Phase 3A). If anything failed, fix it before moving on.

Session Start Checklist

When resuming a project across sessions:

[ ] Context loaded -- CLAUDE.md read, git log checked
[ ] Progress reviewed -- what's done, what's next
[ ] Current step identified: _______
[ ] Current TDD phase: RED / GREEN / REFACTOR
[ ] Zero open questions about the current step

When to Use This Workflow

For simpler tasks, use EPCC alone. This workflow adds value when the cost of skipping a phase is measured in hours, not minutes.

Quick Reference

Create This as a Skill

You can turn this entire workflow into a reusable skill that anyone on your team invokes with a slash command. Once installed, /project-planning add user authentication to the API launches the full phased workflow with your project description pre-loaded.

Setup

mkdir -p .claude/skills/project-planning

Create .claude/skills/project-planning/SKILL.md with the content below, then commit it to git so the entire team has access.

SKILL.md

---
name: project-planning
description: Structured project planning with TDD-enforced phases -- context check, interrogation, documentation, red-green-refactor cycle, persistence, and verification. Use for any non-trivial feature, migration, or refactor.
user-invocable: true
argument-hint: describe the project or feature
---

# Structured Project Planning (TDD-Enforced)

You are executing a disciplined, phased project planning and implementation workflow. The user's project description is:

**$ARGUMENTS**

## Global Rules

1. Never assume. Never guess. Ask.
2. Never write implementation code without a confirmed failing test.
3. Never skip or reorder phases.
4. At every STOP gate, output the required checkpoint and wait for "proceed" before continuing.
5. Tests define correctness. Never change a test to match broken implementation.
6. Only build what is specified. No extras, no improvements, no refactors outside scope.

---

## Phase 0 -- Context Check

Check for and summarize: `CLAUDE.md`, `lessons.md`, `progress.txt`, `decisions.md`, recent git log (last 10-20 commits), open TODOs/FIXMEs, failing tests or CI status.

State: "Fresh project" or summarize current state in bullet points.

**STOP 0:** Output context summary. Wait for "proceed."

---

## Phase 1 -- Interrogation

Ask questions about the project described above until zero assumptions remain. Cover:

- **Scope:** Problem, target user, definition of done, explicit non-goals
- **Behavior:** Primary user action, success/failure states, data operations, critical flows
- **Existing code:** Greenfield or existing, conventions, constraints, prior decisions
- **Testing:** Acceptance criteria, required test types, manual flows
- **Scale:** Performance targets, expected load, budget/resource limits
- **Dependencies:** External systems, blocking teams, shared infrastructure
- **Risks:** Hardest parts, edge cases, unknowns

Do not move to Phase 2 until all questions are answered.

**STOP 1:** List every open question. Wait for all answers before continuing.

---

## Phase 2 -- Documentation

Generate only the docs that apply to this project type:

**All projects:** `TESTING_PLAN.md`

**New features/products:** `PRD.md`, `APP_FLOW.md`, `TECH_STACK.md`, `IMPLEMENTATION_PLAN.md`
Add if applicable: `FRONTEND_GUIDELINES.md`, `BACKEND_STRUCTURE.md`, `ROLLOUT_PLAN.md`

**Migrations/refactors:** `SCOPE.md`, `BREAKING_CHANGES.md`, `DEPENDENCY_AUDIT.md`, `MIGRATION_PLAN.md`, `ROLLOUT_PLAN.md`

**Bug fixes:** `PROBLEM_STATEMENT.md`, `HYPOTHESES.md`, `INVESTIGATION_PLAN.md`, `FIX_PLAN.md`

`IMPLEMENTATION_PLAN.md` must list steps in dependency order. Each step must include:
- What to build
- Acceptance criteria
- The test(s) that will be written first (described, not yet coded)
- Definition of done: tests written, confirmed RED, implementation, confirmed GREEN, refactored

**STOP 2:** Output all docs. Wait for approval before writing any code.

---

## Phase 3 -- TDD Cycle (Repeat for Every Step)

For each step in `IMPLEMENTATION_PLAN.md`, execute in strict order:

### 3A -- RED

First, set the TDD gate to block implementation writes:

```bash
echo "RED" > .claude/tdd-phase
```

- Write tests based on acceptance criteria
- Run tests
- Confirm tests FAIL with a meaningful assertion error (not a compile/import error)
- Show exact failure output

If tests pass before implementation exists: STOP. Diagnose why and fix the test.

**STOP 3A:** Show failing test code + failure output. Wait for "proceed."

After the user confirms tests are failing, unlock implementation writes:

```bash
echo "GREEN" > .claude/tdd-phase
```

### 3B -- GREEN
- Write the minimum implementation to pass the tests
- Run tests
- Confirm all tests PASS
- Show passing test output

Do not add logic not required by a failing test. If tests still fail, fix implementation -- never the tests.

**STOP 3B:** Show passing test output. Wait for "proceed."

Transition to refactor phase:

```bash
echo "REFACTOR" > .claude/tdd-phase
```

### 3C -- REFACTOR
- Refactor for clarity, structure, or performance
- Run tests after each change
- Confirm tests remain GREEN
- Note any decisions made in `decisions.md`

Do not add new behavior here. New behavior = new RED cycle.

**STOP 3C:** Confirm tests still GREEN. Summarize what was refactored. Wait for "proceed."

Clear the TDD gate after the step is complete:

```bash
echo "DONE" > .claude/tdd-phase
```

---

## Phase 4 -- Session Persistence

After every completed step, update:

- `progress.txt` -- COMPLETED / IN PROGRESS (include current TDD phase) / NEXT / BLOCKED / KNOWN ISSUES
- `lessons.md` -- any mistakes, fixes, or patterns discovered this step
- `decisions.md` -- any non-obvious decisions and why
- `CLAUDE.md` -- update if conventions or rules changed

---

## Phase 5 -- Step Verification

After each completed step:

1. Confirm RED phase occurred -- state test file and exact failure message
2. Confirm GREEN -- paste passing output
3. Check each acceptance criterion: PASS / FAIL with evidence
4. Update `progress.txt`
5. If anything failed: state what, why, and what rule prevents it next time. Add to `lessons.md`.

**STOP 5:** Output verification checklist. Wait for "proceed" to begin next step.

---

## Recommended First Output

After Phase 0, begin Phase 1 interrogation based on: **$ARGUMENTS**

After Phase 2 approval, present:
1. Project summary (1 paragraph)
2. Key decisions (for decisions.md)
3. Explicit assumptions for confirmation
4. Risks and mitigations
5. First step from IMPLEMENTATION_PLAN.md -- including exact test(s) to be written and expected failure message

Enforcing TDD-first with hooks

The SKILL.md above instructs Claude to write tests before implementation, but skill instructions are non-deterministic — Claude follows them most of the time, not all of the time. For hard enforcement, add a hook that deterministically blocks writes to non-test files during the RED phase.

How it works: The skill writes the current TDD phase (RED, GREEN, REFACTOR, DONE) to .claude/tdd-phase. A PreToolUse hook reads this file before every Write or Edit and blocks non-test files when the phase is RED.

Step 1: Create the gate script at .claude/scripts/tdd-gate.sh:

#!/usr/bin/env bash
# TDD gate hook -- blocks non-test file writes during RED phase.
# Reads .claude/tdd-phase for current state.

PHASE_FILE=".claude/tdd-phase"

# If no state file, allow everything (don't break normal workflows)
if [ ! -f "$PHASE_FILE" ]; then
  exit 0
fi

PHASE=$(cat "$PHASE_FILE" | tr -d '[:space:]')

# Only enforce during RED phase
if [ "$PHASE" != "RED" ]; then
  exit 0
fi

# Extract file_path from JSON on stdin
INPUT=$(cat /dev/stdin)
FILE_PATH=$(echo "$INPUT" | grep -o '"file_path" *: *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"//')

# If we couldn't parse a file path, allow (don't break other tools)
if [ -z "$FILE_PATH" ]; then
  exit 0
fi

# Allow writes to test files
if echo "$FILE_PATH" | grep -qiE '(test|spec|_test\.|\.test\.|\.spec\.)'; then
  exit 0
fi

# Block non-test files during RED phase
echo "TDD GATE: Phase is RED -- write tests first." >&2
echo "Only test files (matching *test*, *spec*) are allowed during the RED phase." >&2
echo "The skill will transition to GREEN after you confirm the tests fail." >&2
exit 2

Make it executable:

chmod +x .claude/scripts/tdd-gate.sh

Step 2: Add the hook to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/scripts/tdd-gate.sh"
          }
        ]
      }
    ]
  }
}

Step 3: Add .claude/tdd-phase to .gitignore — it is session state, not project configuration:

.claude/tdd-phase

The lifecycle:

If you are working outside the skill (normal Claude Code usage), the hook does nothing because no .claude/tdd-phase file exists. It only activates when the skill creates the file.

Using the skill

Once committed, any team member can invoke it:

/project-planning add rate limiting to the API with per-endpoint controls

/project-planning migrate the user service from REST to GraphQL

/project-planning fix the duplicate order bug in checkout flow

Claude will begin Phase 0 (context check), then move through each phase with STOP gates, waiting for your “proceed” at each checkpoint. The $ARGUMENTS text flows into Phase 1 as the project description that drives the interrogation questions.

Customizing for your team

After installing, tailor the skill to your team:

• Add your test framework to Phase 3 prompts (e.g., “Use pytest with fixtures” or “Use JUnit 5 with Mockito”)
• Add your doc templates to Phase 2 if your team uses specific formats
• Adjust STOP gates — if your team finds them too frequent, you can combine 3A/3B into a single checkpoint
• Add to CLAUDE.md — reference the skill so Claude suggests it for non-trivial tasks: For features or migrations, use /project-planning to start with the structured workflow