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}

Register in task_artifacts (artifact_type = 'plan-first', round_num = R).

---

Step 4 — Execute per mode

Mode 1 (Autopilot): run each step in order. Report only when done.

Mode 2 (Step-by-step): after each step ask "next?". User writes "ok" → continue. User writes anything else → treat as feedback, adjust.

Mode 3 (Draft only): stop after saving the plan. Do not execute.

Handle failures per step:

• Non-critical error → log and continue
• Critical error → stop, report, wait for the user

---

Step 5 — Deploy (default embedded, opt-out only)

Unless the user says "no deploy" or the changes are draft-only:

• Commit the changes with a message referencing the block
• Push to origin main
• Sync to sibling projects if the change affects shared skills / commands (sync-agents.sh)

Rule: deploy is the default. Only pause for confirmation when the diff touches non-whitelist paths (per CLAUDE.md push policy).

---

Principles

1. Every code / doc change goes through plan-first — otherwise the actual scope drifts silently
2. 7–15 rows — the sweet spot. Under 7 = block too small, over 15 = decompose the block
3. Verb + object per step — makes progress checkable
4. Explicit out-of-scope — prevents feature creep during execution
5. Save the plan even in draft mode — future you can resume

---

Anti-patterns

❌ Skipping plan-first for "quick" edits

"It's just one line" — until it accidentally breaks three consumers. Plan-first anchors the change.

❌ Research steps in the plan table

"Read X to figure out Y" belongs in flow-first / library-first, not plan-first. Plan-first steps are actions, not investigations.

❌ Empty "short summary" column

"TBD" or blank means the plan isn't real. Every step must be concretely described.

❌ Skipping "Risks" and "Out of scope" sections

Even if you write —, mark them explicitly. Silence = these dimensions weren't thought about.

❌ Executing before user picks a mode

Wait for mode selection. Even in autopilot orchestration, the mode is picked via automated answer, not silent execution.

❌ Inlining instead of Skill()

Always via the Skill tool.

---

Related skills

• flow-first — landscape check before planning (Tier 1 cycle)
• library-first — reuse audit before planning (Tier 1 and Tier 2 cycles)
• ship-first — finalization after execution

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bearded-illirian
• Source: bearded-illirian/trailmark
• License: MIT

Install and usage instructions live in the source repository linked above.