plan-first

Plan-First Protocol

Mandatory protocol before any of the following:

• Writing a document (spec, README, guide, architecture)
• Writing new code (file, module, component)
• Refactoring existing code
• Database migration
• Writing tests / test plan
• Git operations (commit, PR, merge)

Input

The approved library-first-{N}.{R}.md with atomic rows the plan will execute.

Output

A 7-15 row plan table saved as plan-first-{N}.{R}.md; after execution — report-{N}.{R}.md and user-note-{N}.{R}.md.

Hands off to

ship-first — per-block mode closes the block and moves to next; task-level mode closes the task.

---

Step 0 — Task context

Ensure {log_dir} and {slug} are known.

---

Step 1 — Build the plan table

A table of 7–15 rows. Each row = one atomic step.

Columns:

• # — sequential number
• Step title — verb + object ("create X", "update Y", "delete Z")
• Short summary — 1 sentence what this step actually does

Rules:

• 7 to 15 rows — fewer means the block is too small (skip planning), more means it's too big (decompose)
• Right column is a concrete summary, not "TBD" or empty
• No research steps ("read X", "figure out Y") — those belong in flow-first / library-first, not plan-first

---

Step 2 — Show table + pick mode

Show the plan table to the user. Ask for one of three modes:

Mode:
1 — Autopilot: I execute every step without pauses, then a final report
2 — Step-by-step: I pause after each step, wait for "ok" to continue
3 — Draft only: I don't execute, just save the plan for later

Wait for the user's response.

Auto-execution context (e.g. dev-auto-first): mode = 1 (autopilot) chosen automatically.

---

Step 3 — Save the artifact

Write {log_dir}/plan-first-{N}.{R}.md where:

• N = current block number
• R = round (1 by default, 2+ on revision)

Structure:

> 🔗 Task: tasks/log/{slug}/task.md

# plan-first — plan for block {N}

**Date:** {date}
**Mode:** {chosen mode}

## Plan

| # | Step title | Short summary |
|:-:|---|---|
| 1 | ... | ... |
| ... | ... | ... |

## Risks

- {risk 1}
- ...

## Out of scope

- {what is deliberately not done in this block}