SuperAPI AI Directory

plan

General & other

View repository

Updated 10-16 09:30

About this skill

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:

  1. A shared Yjs document serves a CodeMirror editor
  2. Claude reads and edits the document as a Yjs peer
  3. Documents are markdown files on disk, not CRDT blobs
  4. Comments are a standalone messaging layer
  5. 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.

  1. Read .bon/understanding.md — the project's soul
  2. Read CLAUDE.md — the manual
  3. Explore the codebase: relevant source files, tests, existing patterns
  4. 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.

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:

  1. The Calvino test: Read outcome titles in sequence. Does it narrate?
  2. The cold-start test: Pick the hardest action. Could a fresh Claude execute it from the brief + understanding.md alone?
  3. 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