feat(style): give agents a house writing style so their prose is readable

[pgebheim]

Why

Agents produce a lot of prose — PR bodies, ticket descriptions, review findings, plans, status hand-backs — and left unconstrained they write it badly. Conclusions buried under process narration, passive voice, hedge stacks, filler, jargon. A human reads all of it, usually in a hurry, usually while deciding something.

Rig already constrains what agents do. This constrains how they report it.

What

templates/STYLE.md — a house style following the Google developer documentation style guide. 13 rules with do/don't pairs:

• Answer first; reasoning after. Never narrate the path you took.
• One idea per sentence. Active voice, named actor. Present tense.
• Condition before instruction — so a reader can skip what doesn't apply.
• Concrete nouns, anchored to a file:line, command, count, or SHA.
• Cut filler (basically, simply, it's worth noting that) and jargon (blast radius → affected callers).
• Mark what you didn't verify. No preamble, no apology, no offer of further help.

Plus target shapes for the artifacts rig actually emits — commit message, PR body, ticket, review finding, plan, hand-back — and a 5-question self-check. It ships as a starter, so a project can prune or extend it like REVIEWER.md.

How it's plumbed

Same shape as the review catalog:

Piece	Change
Config	new style.guideFile (default .claude/STYLE.md) in rig.schema.json, rig.config.example.json, docs/config.md
Delivery	install.sh copies it beside REVIEWER.md for all three targets (.claude/ for claude-code, .rig/ for agents-md and pi); the AGENTS.md pointer block names it
Personas	each of the five gains a ## How you write section
Skills	the nine prose-emitting skills read style.guideFile
Doctor	checks the file exists, --fix copies it in
Onboard	delivers it and sets the key per target

The core rules are inlined in each persona, not just referenced, so they hold even when the file is missing — then role specifics on top: commit/PR shape for coder, finding format for reviewer, observed-vs-inferred for debugger, test naming for qa, ticket titles and Decision needed: for architect. The architect's old ## Output style section folds into the new one rather than sitting beside it.

Skills get a concrete instruction at the point of writing for the durable artifacts: ticket title/body (rig-issue), commit + PR body + hand-back line (rig-task), plan presentation (rig-plan), findings writeup (rig-spike), finding format (rig-review).

Side fixes

rig-reviewer was using jargon the same file now bans — its Blast radius step is renamed Affected callers, and a nested-backtick span is unbroken.

Base branch

Stacked on #72 (feat/pi-target), not main. Two edits land in docs/pi.md and the pi half of install.sh, neither of which exists on main yet — basing here keeps the pi target's .rig/STYLE.md delivery in the same change instead of leaving it as a follow-up somebody has to remember.

Test plan

• bun run test — 67 pass, 0 fail.
• Three-target install into a scratch repo (install.sh --target claude-code,agents-md,pi): .claude/STYLE.md and .rig/STYLE.md both delivered, no-clobber on the second pass, AGENTS.md block carries the writing-style paragraph.
• Assembled pi persona (.pi/agents/rig-coder.md) carries the ## How you write section — confirms the frontmatter/body split still flows persona changes through to the pi target.
• rig.schema.json and rig.config.example.json both parse.

bun run typecheck fails on this branch, but pre-existing and unrelated: tooling/prepare-smithers-typecheck.sh:15 copies smithers/agents.example.ts, which isn't present in a clean checkout. No TypeScript is touched here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MBaTgFSa8va6PTaFfuSRsz