| name | plan |
| description | Plan multi-session work as a bon hierarchy. Outcomes narrate the journey, actions carry execution detail, understanding.md provides the frame. Replaces plan mode for work that spans sessions. Triggers on 'plan this', 'how should we approach', or when about to enter plan mode for non-trivial work. (user)
|
| allowed-tools | ["Read","Glob","Grep","Bash","Edit","Write","Agent","AskUserQuestion"] |
Bon Plan
Express your thinking as a bon hierarchy instead of a plan file.
Why this exists: Plan files are orphans. Written once, never synthesized,
never updated. understanding.md has /open and /close maintaining it every
session. Bon items have tracking, persistence, tactical steps. This skill
channels planning into artifacts that are already alive.
What it replaces: Plan mode. Don't call EnterPlanMode — stay in normal
conversation mode where writing to understanding.md and creating bon items
is natural behavior, not a format conversion.
When to Use
- Multi-session work: features, refactors, new components
- Work that needs handoff to a future Claude
- When you'd normally reach for EnterPlanMode
When NOT to Use
- Quick exploration before a small fix — just read and work
- Single-session tasks — create a bon action directly, or just do it
- Research or investigation — explore first, plan when direction is clear
The Calvino Principle
In Calvino's If on a winter's night a traveller, the chapter titles read
as a continuous story. The Table of Contents IS a narrative.
Your outcomes work the same way. Read them in sequence — they should tell
the implementation story:
- A shared Yjs document serves a CodeMirror editor
- Claude reads and edits the document as a Yjs peer
- Documents are markdown files on disk, not CRDT blobs
- Comments are a standalone messaging layer
- Documents export cleanly to Google Docs
Each title is a clause in the story. Each outcome expands into actions with
rich --how. The narrative lives in the sequence; the detail lives in the
chapters.
Phases
Phase 1: Orient
Read the terrain. Same exploration you'd do in plan mode, without entering
the mode.
- Read
.bon/understanding.md — the project's soul
- Read
CLAUDE.md — the manual
- Explore the codebase: relevant source files, tests, existing patterns
- Run
bon list — what work already exists?
Take your time. Planning quality depends on understanding what's already here.
Phase 2: Frame
Seed understanding.md with the architectural context that applies across all
outcomes. This is where cross-cutting concerns live — the content that would
have been Context, Approach, Gotchas, and Scope in a plan file.
Note — understanding.md has two authors. /plan seeds this framing;
/open then maintains it, synthesizing each session's handoff knowledge
into the same file (/open → Synthesize Knowledge). Seed the durable
architectural frame here and expect /open to grow it around what you wrote.
Write to understanding.md:
- Architectural decisions and rationale
- Key technical constraints discovered during orientation
- Scope boundaries — what we're NOT building
- Gotchas from existing code or dependencies
- Patterns to follow or avoid
The sorting question: Does it apply to multiple outcomes? →
understanding.md. Does it apply to one action? → that action's --how.
Present the understanding.md update to the user before proceeding.
Phase 3: Narrate
Create outcomes whose titles, read in sequence, tell the implementation
story.
For each outcome:
- Title: Achievement language. What's true when this chapter is complete.
- --why: Why this chapter exists in the story.
- --how: Strategy and approach at the outcome level.
- --what: What will be true when achieved.
- --done: Verifiable completion criteria.
- --order: Sequence position in the narrative.
The narrative test: Read all outcome titles in order. Ask the user:
"does this read as a story?" Reorder or reword until it does.
Create outcomes sequentially, not in parallel.
Phase 4: Detail
Create actions under each outcome. Each action is a chapter opening — rich
enough that a cold-start Claude can pick it up and execute.
For each action:
- --why: Why this action matters for its parent outcome.
- --how: Implementation detail. Reference code patterns by file:line
rather than pasting snippets — living references over stale snapshots.
Include pitfalls, things to avoid, specific APIs. This is where
execution quality lives.
- --what: Numbered steps (these become tactical steps via
bon work).
- --done: How to verify completion.
- --order: Sequence within the outcome.
Set waiting_for where real dependencies exist, not just ordering preference.
The self-containment test: For each action, ask: could a Claude with
only this brief and understanding.md execute this? If not, the --how
needs more detail.
Phase 5: Verify
Present the full hierarchy (capture bon list to a file and Read it).
Three checks:
- The Calvino test: Read outcome titles in sequence. Does it narrate?
- The cold-start test: Pick the hardest action. Could a fresh Claude
execute it from the brief + understanding.md alone?
- The frame test: Does understanding.md cover everything cross-cutting?
Iterate until the user is satisfied. The hierarchy IS the plan — there's
nothing else to write.
What Goes Where
| Content type | Home | Example |
|---|
| Architecture decisions | understanding.md | "Y.Text not Y.XmlFragment because..." |
| Cross-cutting constraints | understanding.md | "Don't import Combine anywhere" |
| Gotchas from spikes | understanding.md | "StickyIndex constructor doesn't work" |
| Scope boundaries | understanding.md | "Not multi-user beyond Sameer + Claude" |
| Implementation strategy | Outcome --how | "Redis distributed locks, not file locks" |
| Per-step approach | Action --how | "Mirror Injector.swift:89-108 pattern" |
| Deliverables | Action --what | "1. Add middleware 2. Configure limits" |
| Completion criteria | Action --done | "P99 < 500ms at 500 RPS for 10 min" |
| The story | Outcome titles in order | Table of Outcomes |
Quick Corrections
| About to do this | Do this instead |
|---|
| Call EnterPlanMode | Stay in normal mode, follow these phases |
| Write a plan file | Frame → understanding.md, work → bons |
| Paste code blocks in --how | Reference by file:line |
| Create one large outcome | Multiple outcomes that narrate a sequence |
| Skip --how on actions | --how is where execution quality lives |
| Put cross-cutting context on one action | Put it in understanding.md |