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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add JakeSelby/model-citizen --skill plan-authoring技能说明
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.
# <title>— 1 line. What gets built, as a noun phrase. Not a sentence.- Verdict blockquote — at most 4 lines. Two sentences, what this builds and the mechanism, then one metadata line: Effort · Risk · Blast radius.
## At a glance— 7 bullets. Outcome · Approach · Touches · New deps · Not in scope · Exit test · the one open question.## System design— at most 15 lines. One diagram, no prose above it, one caption below.## Steps— at most 8. Numbered, two lines each: what and where, then the exit test.## Decisions for the reviewer— at most 5. Question, recommendation with its reason, alternative. One line each.## 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** — valuebullets.## 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
textfence —├─▶,└─▶,──▶, 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 — asequenceDiagramwhen 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
### Phaseheadings, 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:
阅读完整来源 ↗