Plan scaffold workflow

Three prompts for surviving a long build: scaffold tracking docs from a plan, audit them back against it, then validate the finished build against the docs. Paste them in order.

claude · claude-code · planning · long-builds

For builds too long to hold in one session. The docs are the memory: the agent writes them before it writes code, and every later session re-reads them instead of re-deriving them. Paste these in order.

1.Plan scaffold

Paste the moment the agent finishes describing a plan, before it touches code.

Good plan. Before you execute anything, turn this into tracked
documentation.

Create four files in the project root:

## 1. BUILD_[plan-name].md

Take the plan you just described and write it out as a detailed
reference doc with:
- Overview (what we're doing and why)
- Every phase/section with:
  - Description of what happens
  - Every file that will be created, modified, or deleted — by name
  - The pattern or approach for each change
  - Gotchas or things to watch for
  - Verification command to confirm it worked
- Architecture decisions (if any patterns are being established)

## 2. PROGRESS_[plan-name].md

Create a machine-readable progress tracker:
[Plan Name] Progress
Last Updated: [today]
Current Phase: 1
Status Key: [ ] not started | [~] in progress | [x] complete | [!] blocked

>>> RESUME HERE <<<
Phase 1, Step 1: [first action]

Phase 1: [name]
| # | Step | Status | Notes |
|---|------|--------|-------|
| 1.1 | [action] [filename] | [ ] | |

Rules:
- EVERY file gets its own row — never group files
- Include a Blockers Log table at the bottom
- Include a Session Log table at the bottom
- The >>> RESUME HERE <<< marker must exist exactly once

## 3. CHECKLIST_[plan-name].md

Verification gates per phase. Nothing gets marked complete in
PROGRESS_[plan-name].md until its CHECKLIST gate passes.

```
# [Plan Name] — Verification Checklist

> Do NOT mark a phase complete in PROGRESS until ALL items
> in that phase's checklist pass.
> If a check fails, document in the Blockers Log of PROGRESS.

## Phase 1: [name]
- [ ] **Gate 1.1:** [exact bash/SQL command to run]
  - Expected: [what success looks like]
- [ ] **Gate 1.2:** [next verification command]
  - Expected: [expected output]

## Phase 1 Sign-off
| Gate | Result | Notes |
|------|--------|-------|
| 1.1  |        |       |
| 1.2  |        |       |
```

Rules:
- Every phase gets its own gate section
- Include exact bash commands, grep patterns, SQL queries — not vague descriptions
- Include expected output so a fresh session can verify without context
- Include a Sign-off table per phase for recording PASS/FAIL
- For UI phases, include manual test steps
- Final phase should include a full E2E flow checklist

## 4. PLAYBOOK_[plan-name].md

This is MY copy-paste reference. I paste prompts from this file into
Claude Code at the start of each phase. Include ALL of these sections:

### Session Start Prompt
Read BUILD_[plan-name].md and PROGRESS_[plan-name].md.
Find >>> RESUME HERE <<<. Report:

Current phase and step
What was last completed
What's next
Any blockers
Do NOT write code yet.


### Recovery Prompt
Context lost. Read PROGRESS_[plan-name].md, find >>> RESUME HERE <<<,
read BUILD_[plan-name].md for current phase details.
Report what you found. Don't execute until I confirm.

### Phase Completion Prompt
Phase [X] should be complete. Verify:

Run the verification commands from CHECKLIST_[plan-name].md for Phase [X]
Report pass/fail for each gate
Fill in the Phase [X] Sign-off table in CHECKLIST_[plan-name].md
If all pass: mark items [x] in PROGRESS, move >>> RESUME HERE <<<
to next phase, update session log, commit
If any fail: report what's broken
Show results before committing.


### Blocker Prompt
Blocked on [issue]. Add to Blockers Log in PROGRESS, mark step [!],
propose 2-3 alternatives. Don't proceed until I pick one.

### Phase Kickoff Prompts

Generate a SPECIFIC kickoff prompt for EVERY phase in the plan.
Each must include:
1. "Starting Phase [X]: [name]."
2. "Read PROGRESS_[plan-name].md and BUILD_[plan-name].md (Phase [X])."
3. The source and target paths for this phase
4. Every file by name
5. "SHOW ME [simplest or most representative file] first."
6. Conversion rules or patterns specific to this phase
7. Gotchas for this phase
8. "Don't proceed to next batch until pnpm typecheck passes."

For phases with 15+ files, split into sub-phase prompts (e.g. 3a, 3b).

### Tips & Correction Prompts

Include these exact prompts:

**Focus Control**
STOP — focus only on the current step in PROGRESS.
Don't jump ahead. What's the exact next thing to do?

**Pattern Matching**
STOP — find an existing example in the codebase that does
something similar. Match that pattern exactly. Show me the
example before writing new code.

**Checkpoint**
Pause — checkpoint what we have.

Run pnpm typecheck (or relevant check)
If it passes, commit: "wip: Phase X.Y - [description]"
Update PROGRESS with what's done


**Session Split**
Split session. Update PROGRESS — mark completed items, move
>>> RESUME HERE <<<, update session log, commit all work.
Tell me the exact prompt to use next session.


**Slow Down**
Too fast. For each file:

Show me the current/source content
Show me your new/converted version
Explain changes
Wait for approval
One file at a time.


**Verify Before Proceeding**
Before continuing, verify the last batch:

Run pnpm typecheck
Show me any errors
Don't proceed until clean.


### Quick Reference Table

| Action | Prompt |
|--------|--------|
| New session | "Read BUILD and PROGRESS, find RESUME marker" |
| Lost context | "Recovery prompt" |
| Phase done | "Phase [X] complete, run CHECKLIST verification" |
| Stuck | "Blocked on [issue]" |
| Too fast | "STOP — focus only on current step" |
| Wrong approach | "STOP — find existing example first" |
| Save progress | "Pause — checkpoint" |
| End session | "Split session" |

## After creating all four files:
- Commit: "chore: scaffold [plan-name] tracking"
- Do NOT start executing the plan yet
- Tell me: "Files created. Paste the Phase 1 kickoff prompt
  from PLAYBOOK_[plan-name].md to begin."

2.Scaffold audit

Paste straight after the four files exist. Catches the gaps before they cost you a session.

Read the original plan discussion above, then read BUILD_[plan-name].md,
PROGRESS_[plan-name].md, CHECKLIST_[plan-name].md, and PLAYBOOK_[plan-name].md.

Audit for gaps:

1. Compare every action, file, and step from the original plan against BUILD.
   List anything missing or vague.
2. Confirm every file mentioned in BUILD has its own row in PROGRESS —
   no grouped rows.
3. Confirm every phase in BUILD has a corresponding gate section in CHECKLIST
   with exact commands, not vague descriptions.
4. Confirm PLAYBOOK has a specific kickoff prompt for every phase (not generic),
   and that phases with 15+ files are split into sub-phases.
5. Confirm >>> RESUME HERE <<< exists exactly once in PROGRESS.

Report findings as a table:
| File | Issue | Fix needed |

Then make the fixes. Don't start executing the plan.

3.Build validation

Paste when the agent claims the build is done. Assume it isn't.

Full build is allegedly complete. Validate everything:

1. Read BUILD_[plan-name].md — for every file listed as created/modified/deleted,
   confirm it actually exists (or was actually deleted) and matches the
   described pattern.
2. Read PROGRESS_[plan-name].md — confirm every step is marked [x].
   Flag any [ ], [~], or [!] still present.
3. Read CHECKLIST_[plan-name].md — run EVERY verification command in EVERY
   phase gate. Report pass/fail for each. Fill in ALL sign-off tables.
4. Run the full E2E checklist from the final phase of CHECKLIST.
5. Run pnpm typecheck (or relevant project-wide check). Zero errors required.
6. Check for orphaned imports, unused files, or dead references introduced
   by this work.

Report as:

| Check | Result | Details |
|-------|--------|---------|

If anything fails: list exact fixes needed, don't apply them yet.
If everything passes: confirm "BUILD COMPLETE — all gates passed" and commit
any remaining sign-off table updates.