Spec writer
How the agent writes each spec, and how to extend it for your team.
A spec is one buildable thing: what it does, and how you will know it works. This is the skill that writes one.
It is one of the four built-in skills your team can wrap.
What it does
It asks before it writes, per spec. Which of two behaviours you want, what happens on the failure path, who is allowed to do this, what happens to what is already there. Two to four questions, one round per spec, even when you asked for several at once.
It writes the spec in the shape your format defines, with acceptance criteria a developer can act on.
It walks coverage before calling anything ready. Every behaviour the spec describes has to trace to a criterion, and every criterion has to be owned by something the spec promised. Something uncovered means the spec is not ready yet, and the agent fixes the gap before it scores.
It scores down when you skip the questions. Nobody agreed to the parts it guessed, and Ready is the claim a developer acts on.
A second reader looks before a spec is Ready. A different model reads the finished spec and holds it at Shaping if a criterion is not something a tester could observe, if a question or a TBD is still open, or if the spec describes behaviour nothing covers. The reason is written on the spec, and the agent fixes it in the same turn. The checklist runs first and runs always; the second reader is the extra pair of eyes on top of it.
Where the shape comes from
Your spec format is a separate document, and it is yours. It decides the sections, the shapes, and the grammar of your acceptance criteria, including a house structure that looks nothing like the standard one. This skill decides how the conversation runs. Change the sections in Settings → Formats; add your team's own rules with a wrapper, below.
The agent reads your format in force before its first spec, every time.
Hooks
A wrapper is a company or project skill that extends this one rather than replacing it. It names the hooks rather than repeating the steps, so it keeps working when we reword one.
| Hook | What it adds |
|---|---|
extra-questions | Questions your team always asks before a spec |
extra-sources | Sources the agent must read first, before it writes |
extra-checks | Checks to run over the spec before it is offered |
coverage-bar | Raise what the coverage walk has to prove |
after-spec | What happens once a spec is written |
A wrapper can add rules and raise the bar. It cannot lower one. If a wrapper asks the agent to skip a step this skill states, the agent follows this skill and tells you it did.
The bar here is coverage-bar, and the readiness review has its own
ready-bar. They are different bars on different passes, which is why they have different names:
one governs the spec as it is written, the other governs the review that judges it afterwards.
A worked wrapper
Write this under Settings → Skills. Copy it and change the parts in your own words.
Paste the body only. The settings form writes the header for you. Pasting a whole file that carries its own header gives you two, and the inner one quietly becomes body text.
Set Extends to Spec writer on the form, then paste this as the body. The pointer sentence
wrappers used to carry is gone: the field is what connects the two now.
[HOOK: extra-sources]
Read the house examples in Context before writing your first spec, and match their
decomposition. Never use the generic product examples as a model for scope.
[HOOK: coverage-bar]
Every permission rule in the spec needs its own criterion, including the denial case.
[HOOK: after-spec]
Offer to run /our-pre-dev-analysis on the spec you just wrote.Leave a hook out and that part behaves exactly as it does today.
Your extension reaches every spec turn. A skill that sets extends: spec-writer is merged into
this one, so the agent reads your rules and ours as one document whether it was sent here by name
or invoked by yours. See Extending a skill.
See also
- Epic writer: the same shape, one level up
- Readiness review: the pass that judges a spec once it exists
- Formats: the sections and criteria grammar your specs use