spec

Align the user and the agent on one spec.md before any code.

What it does

/factory:spec turns the conversation, an issue, or a request into one spec.md that a planner can slice and an implementer can test against. It fires when the user runs the skill, asks to write a spec, asks to turn a conversation or issue into a spec, or asks to agree on requirements and test seams for a feature or bugfix.

It writes a local file only. Nothing goes to a tracker; /factory:plan publishes slices later.

Reads

factory.toml for spec_dir (default docs/specs) and base. If .kiro/specs/ exists and spec_dir was not set, it uses that.
The conversation, any linked issue (gh issue view, glab issue view, acli jira workitem view), nearby code, tests, glossary, and ADRs. Explore subagents gather anything that takes more than a few reads.

Writes

<spec_dir>/<slug>/spec.md with these headings in this order: Problem, Solution, Requirements, Testing decisions, Implementation decisions, Out of scope, Assumptions, Open questions. Requirements are numbered with stable ids in EARS form:

- R1. WHEN <trigger> THEN the system SHALL <observable behavior>.
- R2. IF <state> THEN the system SHALL <observable behavior>.

The slug is short kebab-case. An existing spec directory is reused when the request continues earlier work.

Rules

Facts come from the repository; decisions come from the user. Never ask the user for something the repo can answer.
Seams are the highest public boundaries tests will run against. Existing seams before new ones; the ideal number is one.
At most one grilling round, for decisions the repo cannot settle. Each question is numbered and carries a recommended answer. The round is skipped when nothing is open.
Every decision the agent made without asking goes under Assumptions so the user can overturn any of them in one pass.
Plain words, sentence-case headings, no em dashes.

Done when

spec.md has numbered requirements, named seams, no open questions, and Status: agreed. Planning and coding never start from a draft.

Upstream

Wraps mattpocock-skills/to-spec for the synthesis-first process and mattpocock-skills/grilling for design-tree rounds with a recommended answer per question. Upstream publishes the spec to the tracker with a triage label; factory keeps it local. Upstream’s long numbered user stories become requirements with stable ids.