Writing Your Plans

Exactly two files are actually yours to write. Everything under syntaxis/context/ gets generated from them afterward.

syntaxis/project-plan.md

This is the product itself, in words: what’s being built, for whom, and why.

Write down what’s genuinely settled:

• The problem, and whose problem it actually is
• Users, and what each of them needs to be able to do
• Core features, described in prose rather than as a checklist
• Data the product holds, along with the rules governing it
• Stack — languages, frameworks, services, where it’s hosted
• Business model, assuming there is one
• UX decisions that have already been made

Whatever’s genuinely still open, mark as open. Inventing an answer just to fill the section turns a non-decision into a constraint nobody actually chose.

syntaxis/build-plan.md

An ordered list of features, each with a number that never changes. This is the roadmap /feature works through.

# Build Plan

- [ ] 1. Project setup and layout shell
- [ ] 2. Account signup and signin
- [ ] 3. Create and edit articles
- [ ] 4. Publish flow with draft state
- [ ] 5. Reader-facing article pages

The rules that actually matter here:

• Numbers don’t move. History, archives, and findings all refer back to work using them — an existing item never gets renumbered.
• One item, one deliverable. Something needing three specs is three items, not one.
• Ordered by what depends on what, not by whatever sounds most fun to build first.
• Stay high-level. The detail belongs in the spec; the plan just states intent.

A plain bulleted feature list is genuinely enough to get started.

Two ways to actually write these

Just write them. Open the files and start typing — fully supported, and usually the fastest route when you already know the product cold.

Talk them through instead. /discovery runs a guided conversation and only drafts both files once you’re actually ready. It’s optional, and /overview never requires it first.

Turning the plans into context

/overview

/overview handles two jobs:

1. It formats the build plan into a tracked checklist — purely syntax: wording, order, feature count, notes, headings, nesting, existing IDs, and completion markers all stay byte-for-byte the same. That formatting pass needs no extra approval; a genuine question about scope or order still does.
2. It generates syntaxis/context/project-overview.md, which becomes the durable source of truth every other skill reads from.

Run it again whenever either plan changes in a way that matters. /doctor and /status both flag it when the overview has drifted out of sync.

Slotting in a feature later

Resist the urge to renumber things to make room for it. Append the new item, or let /feature propose a reviewed addition when what you’re describing is genuinely new. A tidy sequence isn’t worth as much as numbers that stay stable.

Checking work off

/complete handles the checkboxes as work actually lands — you’re not meant to maintain them by hand.