Turn requirements and technical decisions already settled in the conversation into a specification in the configured project tracker.
Install and prepare
Run the following in your project terminal, then use the prompt below in Claude Code. This installs editable, project-scoped skill files.
npx skills@latest add mattpocock/skills --skill to-spec --skill setup-matt-pocock-skills --agent claude-code
For Codex, replace claude-code with codex in the command and /to-spec with $to-spec in the prompt. With the complete Claude Code plugin, select /mattpocock-skills:to-spec instead; avoid installing the same skills twice.
For the Claude Code file install above, first enter /setup-matt-pocock-skills in the agent conversation; it is a slash-menu Skill, not a terminal command. With the Claude Code plugin, choose its setup Skill from that menu; with the Codex file install, enter $setup-matt-pocock-skills. Choose GitHub, GitLab, or local Markdown as the publication target. Linear and other trackers require your actual write workflow. When setup finishes, open docs/agents/issue-tracker.md and docs/agents/domain.md in the repo and confirm the tracker, docs location, and domain-document paths. Expect docs/agents/triage-labels.md only if you installed triage. If these files are missing, finish setup before calling to-spec. Return to the same conversation where the requirements were decided and identify open decisions.
Your first task
Adapt the scenario and paths to your project, then enter this in the agent conversation:
/to-spec
Synthesize our team-purchase discussion. Version one lets administrators allocate seats and excludes resale. Confirm the test boundary, save to our configured local tracker, and list unresolved refund details separately.
Work through the task
Keep settled scope intact
This is a synthesis step rather than a fresh interview, so the discussion must still be available. Check that the problem, users and first-version scope are clear. An unresolved refund rule belongs in open questions, not in invented detail added to make the template look complete.
Agree how the feature will be tested
Before drafting, the skill proposes testing boundaries. For team seats, discuss allocation, learner access and duplicate allocation through existing interfaces where possible. Describe observable outcomes so a later implementation session can tell what completion means.
Review and save the specification
Review the problem, solution, user stories, implementation and testing decisions, and exclusions. Record agreed contracts and constraints instead of a long list of fragile file paths. A remote tracker receives a project issue; local mode creates a document in the configured location.
Check the result
Imagine handing the document to someone who missed the discussion. Can they explain the problem, exclusions and acceptance conditions? Confirm its location and open questions before splitting it with to-tickets. If an unattended agent polls the ready-for-agent label, do not let it treat the parent spec as one implementable ticket: explicitly exclude parent specs from the polling rule, or remove that label from the parent after to-tickets creates the smaller tickets.
Common questions
Why is it not interviewing me again? It synthesizes the existing discussion; use grill-with-docs first if the requirements remain vague.
Where is to-prd? The current name is to-spec.
Does it guarantee completeness? Review it against the scope you actually agreed, especially exceptions.
Why is to-tickets reading only part of a long spec? A remote tracker may return a truncated issue body. Run to-tickets in the same conversation immediately after generating the spec, before clearing or compacting it, so ticketing can use the complete content already in context. If you have switched sessions, check that the retrieved body is complete before proceeding; a fragment or summary is not the full specification. [5]
Decide whether a spec is needed
If the requirement is settled and one agent can build it in one session, going straight to implementation is often simpler. Use to-spec when work must survive several sessions and will be sliced into tickets. It records decisions made in the earlier conversation; it does not discover the requirements again. Configure the project's publication target first and list undecided refund, exception, or permission rules separately, rather than letting empty template sections tempt the agent to invent them.
Before publication, inspect the proposed test seams: where will you observe assigning a seat, a learner gaining access, and duplicate assignment? Which checks can use existing interfaces? Then read the out-of-scope section for features you actually declined, not generic someday statements. Give the saved spec to someone who was not in the conversation. If they cannot identify the goal, decisions, open questions, and observable acceptance conditions, a polished heading structure is not yet ready for ticketing.
Record decisions for a multi-session activity log
Suppose the team has decided to add a searchable account activity log and implementation will span sessions. Ask: “Use to-spec to record the decisions we just made: administrators can filter by time and actor; export is out of scope for the first version. Confirm whether the list or API is the best test boundary. Leave log-retention duration unresolved rather than choosing one for me.” Check that these decisions appear in the saved spec.
If the agent starts asking who the user is from scratch, the earlier decisions may be missing from context; restore them rather than turning to-spec into a fresh interview. Remove invented real-time updates or compliance claims. Give the recorded spec to a fresh session: it should know what to build, what to exclude, and which decisions must return to you.
Carry test decisions into tickets
After writing the spec, make Testing Decisions easy for an implementer to find: which behaviors need checks at which boundary, where existing tests live, and what remains undecided. A community investigation of to-spec → to-tickets → implement found that agreed test seams could disappear when the spec became tickets. Give the decisions a stable section in the spec and require relevant tickets to link to it. Sample a published ticket before implementation to see whether the agreement survived.