Frontmatter contract

Every plan in a SpecRider workspace begins with YAML frontmatter between --- fences. SpecRider parses it Rust-side during list_plans and uses it to drive sorting, filtering, search, the Diff Explorer’s commit discovery, and the outline pane status glyphs. Keep it valid YAML.

Required fields

---
status: draft
owner: jake
iteration: 1
last_review: claude · 2026-05-08
tags: [accessibility, a11y, keyboard]
---

• status: — lifecycle marker. Conventional values, in roughly the order a plan moves through them: draft, upcoming, in-progress, shipped, implemented, superseded, backlog, fixture. The Plans browser shows this verbatim, so spell it consistently. When a plan moves folders, update status: to match.
• owner: — single handle. The person accountable for the plan, not necessarily the only contributor.
• iteration: — integer. Bump it when the plan is meaningfully rewritten (scope cut, approach changed, post-review revision). A plan at iteration: 3 is on its third pass; reviewers can use it to tell whether they’re seeing a fresh draft or a polished one.
• last_review: — <reviewer> · <YYYY-MM-DD>. Reviewer is a handle (jake, claude, codex, or a model id like claude-opus-4-7). Always update both the reviewer and the date when you do a real read-through; do not bump it for typo fixes.
• tags: — flow-style YAML list. Used by search and as filterable chips. Keep them lowercase, kebab-case where multi-word, and prefer reusing existing tags over inventing synonyms (grep across the tree before adding a new one).

Optional fields

• name: / description: — override the title/subtitle the Plans browser displays. Default is the file’s first # Heading and a derived blurb; set these explicitly when you want a different display string from the document title.
• branches: — YAML list of branch names that scope the Diff Explorer’s commit history rail to this plan. Use when a plan’s work lives on dedicated branches and you want the rail to show only those commits.
• commit_shas: — YAML list of explicit SHAs to attach to the plan, on top of (or instead of) branch- and file-touch-based discovery. Useful for cherry-picks or commits that don’t touch any file the plan mentions.
• links: — YAML array of linked repo review targets, each with repo, branch, and optional base. See Link code repos to a spec for the workspace config and review workflow.

Important: branches: and commit_shas: values flow into git argv. Treat them like code — don’t paste untrusted strings into them.

Style notes

• Use flow-style lists for short collections (tags: [a, b, c]), block-style only when entries need multiple lines or comments.
• Don’t quote scalar values unless YAML requires it (colons, leading symbols, etc.). Plain status: in-progress is preferred over status: "in-progress".
• Dates are ISO 8601 (YYYY-MM-DD). The · separator in last_review: is a literal middle dot (U+00B7).
• One plan per file. File name = slug; no dates, no status prefix. Lifecycle lives in the folder + status:, not the filename.

Body conventions

Beyond frontmatter, a few body-level conventions help SpecRider surface the right things:

• The first H1 is the plan title. The first paragraph after it is the elevator pitch.
• A ## Why section right after the pitch is the norm. Reviewers read this first.
• Implementation steps are GFM task lines (- [ ] …), not plain bullets. They live under an ## Implementation section (or ### Batch N — … subsections when the work splits into independently-shippable chunks).
• Task lines that touch source files should annotate them with an HTML comment: - [ ] Do thing <!-- src/foo.ts -->. One file annotation per task. The planned jump-to-code feature will surface these.
• Cross-link other plans by relative path: [Workspace trust](../active/workspace-trust.md).

SpecRider’s outline pane and progress counts read these checkboxes, so anything you’d want to track or hand to an agent should be a task.