SKILL · workflow
Plan-before-code — implementation discipline
Skill enforcing plan-first: a plan presented to the user before any code change. You wait for GO, then write. Exception: batch approval ("do X and commit"). Eliminates "I already started" and unauthorized commits. Two formats: single-path proposal (default for most steps) and plan-with-variants (when there are real options).
Requires
Install as Claude Code skill
Drop into ~/.claude/skills/<name>/SKILL.md
Plan-before-code — implementation discipline
Rule
Plan before code. You present a plan to the user → wait for GO → write code.
No GO = no edits. No "it's simple" exceptions.
Two plan formats
Format A — single path (one sensible path)
When the path is one (pipeline shows an obvious next step, context leaves no real alternatives):
Plan (single path):
- What I'll do: <1-2 lines — concrete files + action>
- Verification: <build/test/run command>
- Commit: <message>
See any gaps? If not — GO.
User answers GO / gap: ... / different: .... This is the correct default format for most steps in the molecular harness.
Format B — plan with variants (when there are real options)
When you see 2–3 sensible approaches with different trade-offs:
Plan:
1. <concrete action — file + what to do>
2. <concrete action>
3. <concrete action>
4. <verification — build / test / run>
5. <commit strategy — how many commits, which>
Two options for step 2:
- A: <approach + trade-off>
- B: <approach + trade-off>
Recommend A.
Question: GO (with A)?
Three work modes (user steers)
| Steer | Meaning | What you do |
|---|---|---|
plan only / conceptually | Plan only, no code | Present plan, wait for feedback, no edits |
code it / implement | Code, but plan first | Plan → GO → code |
do X and commit | Batch approval | Execute X + commit, don't ask at each step |
review | Code review mode | Agent code-reviewer, zero edits |
stop / wait | STOP | Full stop, don't continue until released |
GO | Single-path proposal approval | Implement per proposal |
gap: ... | Gap indication in proposal | Back to plan with gap addressed |
When single-path, when variants?
Single-path (Format A) — use when:
- Pipeline has one idiomatic step (e.g. next migration in a numbered series)
- User asked for something concrete — don't invent variants
- Other approaches would require architecture/scope change
- Low irreversibility + low cost
Variants (Format B) — use when:
- Different reversibility (one irreversible, one not)
- Different blast radius (test vs prod)
- Different cost (slow + cheap vs fast + expensive)
- Different cognitive implications
Plan granularity
- Too coarse: "Add feature X" → can't steer
- Too fine: "Add line 42 in file Y" → too much friction
- Good: 3–5 bullets per logical step
Rule of thumb: if a plan has > 7 bullets, split into two phases.
Batch approval
When the user writes "do X and commit":
- Do NOT ask about GO before commit
- Do NOT ask decision prompts for cosmetics
- Execute the batch to the end
- Report in one message at the end
Batch exception: if you hit an irreversible / high-risk decision — stop and ask despite batch approval.
What to do when the agent breaks the rule
- STOP immediately. Don't commit.
- Revert edited files (
git restore <file>). - Present a post-factum plan: "I just edited X, Y — I wanted to do Z. Reverted. Plan + GO?"
- Wait for user's decision.
Better to restart than to hide.
Red flag: "I already started"
If you think "I already started, small step, I'll finish and show": STOP. Show the plan. Wait for GO.
Red flag: fake variants
If you feel tempted to "make it democratic" with A/B/C where B and C are obviously worse — don't. Use Format A (single path). Wasting time on fake options is as much a departure from the harness as no plan at all.
Effect
- User sees what will happen before it happens
- Agent doesn't make "surprises" in commit history
- Plans are an audit trail — easy to reconstruct "why this way"
- Reversibility preserved to the last possible moment
- Agent's decision-making space used — decides alone when there's one path, asks when there are real variants