Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

plan-authoring

Write or revise a plan file, proposal, design doc or handoff the user reviews before approving work; carries the Review Card contract and the addendum rules. Use before writing anything into .agent-harness/plans/, and for any markdown deliverable whose job is to get a go/no-go.

JakeSelby · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add JakeSelby/model-citizen --skill plan-authoring

About this skill


name: plan-authoring description: Write or revise a plan file, proposal, design doc or handoff the user reviews before approving work; carries the Review Card contract and the addendum rules. Use before writing anything into .agent-harness/plans/, and for any markdown deliverable whose job is to get a go/no-go.

The trigger lives in the plan-ceremony stance. This is the contract.

Why this exists

A plan has two audiences and they are not the same reader.

  • The reviewer reviews the approach. System design, steps, and the decisions that are theirs — in one screen, before they read anything else.
  • The implementing agent executes it. Paths, sequencing, edge cases, evidence.

One document written for both produces the 884-line file the reviewer gets lost in. So a plan is one file with a hard seam: a Review Card above the first ---, an Addendum below it.

Failure test: if the reviewer has to scroll to learn what is being built, the plan has failed, however good the work behind it is.

The Review Card

Everything above the first ---. Target 50 source lines, hard cap 70, diagram included. The one thing allowed to push past 70 is a full ## Decisions for the reviewer block — three lines each, five maximum. Never cut a real decision to hit a budget.

Not an introduction to the plan — the whole plan at review altitude.

These sections, this order. Do not rename them, do not add to them, do not fold one into another.

  1. # <title> — 1 line. What gets built, as a noun phrase. Not a sentence.
  2. Verdict blockquote — at most 4 lines. Two sentences, what this builds and the mechanism, then one metadata line: Effort · Risk · Blast radius.
  3. ## At a glance — 7 bullets. Outcome · Approach · Touches · New deps · Not in scope · Exit test · the one open question.
  4. ## System design — at most 15 lines. One diagram, no prose above it, one caption below.
  5. ## Steps — at most 8. Numbered, two lines each: what and where, then the exit test.
  6. ## Decisions for the reviewer — at most 5. Question, recommendation with its reason, alternative. One line each.
  7. ## Risks — at most 3 bullets. One line each: the trigger, and what we do when it fires.

TEMPLATE.md in this directory is the skeleton. EXAMPLE.md is a real long plan reduced to its card.

A plan contains no markdown tables. Anywhere.

Not in the card, not in the addendum. A markdown table renders as a bordered grid whose first column is pinned narrow, so at reading width every cell longer than a clause wraps into a tall, ragged block. That is the density a plan exists to avoid, and it is no better below the rule than above it.

  • ## At a glance — seven - **Label** — value bullets.
  • ## Steps — a numbered list, two lines per step.
  • Any pairing or mapping — one bullet per row, with the paired terms bolded together: - **old/path.ts → new/path.ts** — what changes.
  • Anything with a "why" column — fold the why into the sentence. A three-column table is almost always a list of bullets with an em dash in it.
  • Not bare bold-label lines, in any of these: many markdown previews collapse consecutive soft-wrapped lines into one paragraph. The list marker is what guarantees the break.

The validator hook rejects any line starting with | in a plan file.

There is no Context section in the card

The most common defect: every plan opens with ## Context and three paragraphs of background. Background is addendum material. The verdict's two sentences carry the why — and if they cannot, the plan is not yet understood well enough to write.

Never in the card, always in the addendum

  • Working rules, governance constraints, the agent's own operating instructions
  • Evidence tables, verification logs, what was checked and what could not be
  • ID ledgers, allocation tables, file inventories, touch matrices
  • Per-agent or per-handoff narratives
  • Gate registers beyond the one gate that actually blocks
  • Alternatives beyond the single line each already in Decisions
  • Any restatement of the request

The diagram

The card is reviewed in a plan-mode pane and a chat sidebar, and both show a mermaid fence as raw source. The card's diagram is therefore plain text, which renders everywhere.

  • A box-and-arrow drawing in a text fence — ├─▶, └─▶, ──▶, a dotted ┄┄▶ for a weak or polled link. Cap 12 nodes. If it needs more, the diagram is at the wrong altitude — draw the subsystem being changed, not the whole world.
  • Keep every line under 80 columns; a wrapped line breaks the drawing.
  • Label edges with what moves, not with verbs: api ── encrypted episode ──▶ web.
  • Mark the delta so the reader sees what is new: prefix each new or changed node with *, and name the marker in the caption.
  • Mermaid belongs below the ---, and in docs that are read on GitHub — a sequenceDiagram when ordering across processes is the actual subject. Never on the card.
  • Mandatory when the change crosses more than one component. Omit only for single-file edits.

Steps

A numbered list — these are genuinely ordered — with two lines per step:

3. **[Bake the shadow map](#step-3--bake-the-shadow-map)** — `tools/bake/shadow.py`, new file.
   *Exit:* `terrain_map_8192` writes in under 3 minutes and both shaders sample it once.
  • Line one is what happens and where, with the title linked to its addendum anchor when it has detail. Line two is the exit test, always led by *Exit:*.
  • Every step carries a real exit test — a command, a render, a passing assertion. "Implemented" is not an exit test.
  • Execution order, and step 1 is the cheapest thing that could invalidate the rest.
  • Past eight steps, group under ### Phase headings, at most three.
  • A plan names the skills it will run and the order they run in.

Spikes inside a plan

When a step is an experiment rather than a build, write it as a spike:

Read the complete source ↗