Writing specs

Every feature has one spec: a Markdown file in docs/, in the same format. The Markdown is the only source. The wiki renders it with its figures, links and roadmap badges; nobody maintains a second copy. This page is the rulebook, for people and Claude sessions alike.

The three files

File	Holds	Never holds
A spec (docs/game/grass.md)	Every idea for the feature, each with a code and its full detail	Versions, statuses, "built on..." notes
Roadmap (docs/plan/roadmap.yaml)	Per code: version, status, why it moved	Any design detail
Inbox	Raw ideas with no spec yet	Anything older than the next spec session

The Roadmap page, the badges next to every code and the coloured code links are generated from the roadmap file.

The spec format

Copy the template (docs/_template.md). The sections, in this order:

1. Front matter: prefix (2+ letters, unique) and a one-line summary.
2. Pitch: a quote block, 2-4 sentences.
3. The player's view: the whole feature as the player lives it, built or not. No numbers.
4. Ideas: one ### CODE: title section per idea. This is the only place the idea is detailed.
5. Tuning: every number in one table, with the idea it belongs to.
6. Co-op: the golden-rule checklist.
7. Tech: data, save, seeds, tests, code pointers.
8. Open questions
9. Rejected: dropped ideas and why, so nobody proposes them again.

Non-spec pages (this one, testing, tooling) are free-form.

Ideas and codes

• A code is an idea: the smallest thing that can be built and tested on its own. Its section ends with **Needs:** ... · **Done when:** ....
• Every idea has a code, even far-off ones. "For later" is a status in the roadmap, not a separate list.
• An idea grows in place. An idea needs a paragraph; specced needs the full detail and Done when.
• A code never spans two versions. If part of it fits and part doesn't, split it: GR4 stays, GR4b moves later.
• Codes are never reused or renumbered once built (they're in commit messages). New ideas take the next number.

The roadmap rules

1. Update the roadmap in the same commit that completes a step: the code goes to built.
2. Only the user sets polished, after playing it.
3. When writing or updating a spec, check the roadmap. For a new idea: which version does it serve? For an idea added to a code that already has a version: does it still fit that version's goal and "Done when" (the version charters are on the Roadmap page)? If not, split it into a new code for a later version.
4. Moving later is free; moving earlier needs a yes. Any session may move a code to a later version (add a history line with the reason, and tell the user). Adding anything to the current or an earlier version needs the user's yes.

The fit check, for an idea against its version:

• Does it serve the version's goal?
• Is it needed to pass the version's "Done when"?
• Does it finish an existing system, or start a new one?
• Could the version ship without it?

Markdown conventions

Write	Gets you
GR1, MO5a, J3 in plain text	A link to where the code is defined, coloured by status, with a hover card
### GR1: grass that moves	The code's anchor (#gr1) and its badge (version · status)
[[jobs]], [[jobs#offers]], [[DAY]]	A link to a page or a section. [[jobs|the jobs page]] sets the text
[text](../game/grass.md)	A normal relative link; it works on GitHub too
::figure[Caption]{src=grass/trample}	The figure docs/figures/grass/trample.html, embedded, with its caption
The first > quote before any ##	The page's pitch, drawn large
:::cards, a list of - **Title**: text, :::	A grid of cards, one per item
:::flow, a numbered list, :::	Numbered steps side by side (layers, a sequence)
> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]	A callout (GitHub's alert syntax)
**Needs:** ... · **Done when:** ...	The idea card's footer

Each ### CODE: title section is drawn as a card, its top edge in the status colour. The ::: lines must be paragraphs on their own (a blank line before and after). Use [[...]] links outside tables: the | in [[a|b]] splits a table cell. These blocks read as plain text in the Markdown, so Claude and GitHub still read them fine.

Figures

A figure illustrates. It never specifies: every rule, number and idea must be in the Markdown, because Claude reads the Markdown, not the figure. If something only exists in a figure, that's a bug.

• A figure is docs/figures/<folder>/<name>.html: an HTML fragment (markup, a <style>, a <script>), no <html> or <head>. Vanilla JS, SVG or canvas, no libraries.
• It gets the wiki's tokens and fonts. Use the tokens for every colour (var(--ink), var(--grass), var(--st-built)...) so it follows light and dark mode.
• The wiki sizes its frame to its content.

The wiki

npm --prefix tools/wiki install

npm --prefix tools/wiki run dev

Then open http://localhost:4321. Pages re-render on every change, roadmap badges included.

npm --prefix tools/wiki run check

check fails on roadmap problems, codes missing from the specs or the roadmap, broken links and missing figures. It warns about specs not on the template yet. npm --prefix tools/wiki run build runs it, then writes the static site to docs/site/ (not committed).