To spec
Contract
| Field |
Bound contract |
| Trigger |
Settled decisions need synthesis into an implementation spec. |
| Authority |
Reversible local: write only a named local spec file; the rollback path is deleting that file. |
| Side effect |
Writes an agent-ready specification file locally and stops before publishing or distributing it; a human performs any publication. |
| Done |
Problem, solution, stories, decisions, tests, and exclusions are agent-ready in a verified local specification file; publication remains an unexecuted human handoff. |
Inputs
- Conversation context. The current conversation must contain settled decisions: what is being built, why, and how completion will be judged. If the conversation lacks settled decisions, stop and state what is missing.
- Codebase state. Explore the repository to understand the current state. Use the project's domain glossary vocabulary throughout the spec and respect any ADRs in the area being touched.
- Optional: CONTEXT.md or domain docs. If present, read them for vocabulary and constraints. Do not require them.
Refusals
- Will not interview the user or open a new round of questioning — synthesize what has already been decided.
- Will not fabricate decisions or fill gaps with assumptions.
- Will not publish, distribute, or assign labels — publication is a human handoff.
- Will not proceed to spec writing until the user confirms the identified seams.
Procedure
- Explore the repository to understand the current state of the codebase if not already done. Identify the project's domain vocabulary and any ADRs in the relevant area. Done when: the codebase state and domain vocabulary are understood.
- Identify the seams at which the feature will be tested. Prefer existing seams to new ones, and use the highest existing seam possible. If a new seam is needed, propose it at the highest practical point. Fewer seams across the codebase are better; the ideal number is one. Done when: the testing seams are identified.
- Present the identified seams to the user and confirm they match expectations. Do not proceed until the user confirms. Done when: the user confirms the seams.
- Synthesize the spec from the conversation context, codebase understanding, and confirmed seams. Do not interview the user or open a new round of questioning. Capture what has already been decided. Done when: the spec content is synthesized from settled decisions.
- Write the spec to
docs/specs/<feature-slug>-spec.md using the template below. Done when: the spec file is written to disk.
- Verify the written file contains all seven sections populated with substantive content. If any section is empty or stubbed, fill it before declaring done. Done when: all seven sections are substantive.
- Stop. Do not publish, distribute, or assign labels. Report the file path and that publication is a human handoff. Done when: the file path is reported and no publication action is taken.
Spec template
Write the spec using this structure:
# <Feature name> - spec
### Problem statement
The problem from the user's perspective.
### Solution
The solution from the user's perspective.
### User stories
A numbered list of user stories. Each in the format:
1. As an <actor>, I want a <feature>, so that <benefit>
Cover all aspects of the feature exhaustively.
### Implementation decisions
A list of implementation decisions:
- Modules to build or modify
- Interfaces to modify
- Technical clarifications
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions
Do NOT include specific file paths or code snippets unless a prototype produced a snippet that encodes a decision more precisely than prose (state machine, reducer, schema, type shape). Trim to the decision-rich part.
### Testing decisions
- What makes a good test (external behavior only, not implementation details)
- Which modules will be tested
- Prior art for similar tests in the codebase
### Out of scope
What is deliberately excluded from this spec.
### Further notes
Any additional notes about the feature.
Failure and recovery
| Failure class |
Behavior |
| Missing settled decisions |
Stop. Report exactly which decisions are missing. Do not fabricate decisions or fill gaps with assumptions. |
| No seams identifiable |
Propose seams at the highest reasonable points and present them as proposals, not facts. |
| User rejects seams |
Ask what they would prefer and iterate. Do not proceed to spec writing until seams are confirmed. |
| Write failure |
Report the error. No partial artifact is acceptable; delete any incomplete file. |
| Non-convergent synthesis |
Name the contradiction and stop rather than choosing a side silently. |
Output
A local specification file at docs/specs/<feature-slug>-spec.md with all seven sections (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes) populated and agent-ready — publication is a separate human step.
1---2name: to-spec3description: Use when settled conversation decisions need synthesis into an agent-ready implementation spec at docs/specs/<feature-slug>-spec.md, stopping before publication. Not for turning plans into tickets — use to-tickets; not for remote, credential, publish, deploy, or irreversible changes.4---5
6# To spec
7
8## Contract
9
10| Field | Bound contract |
11|---|---|
12| Trigger | Settled decisions need synthesis into an implementation spec. |
13| Authority | Reversible local: write only a named local spec file; the rollback path is deleting that file. |
14| Side effect | Writes an agent-ready specification file locally and stops before publishing or distributing it; a human performs any publication. |
15| Done | Problem, solution, stories, decisions, tests, and exclusions are agent-ready in a verified local specification file; publication remains an unexecuted human handoff. |
16
17## Inputs
18
19- **Conversation context.** The current conversation must contain settled decisions: what is being built, why, and how completion will be judged. If the conversation lacks settled decisions, stop and state what is missing.
20- **Codebase state.** Explore the repository to understand the current state. Use the project's domain glossary vocabulary throughout the spec and respect any ADRs in the area being touched.
21- **Optional: CONTEXT.md or domain docs.** If present, read them for vocabulary and constraints. Do not require them.
22
23## Refusals
24
25- Will not interview the user or open a new round of questioning — synthesize what has already been decided.
26- Will not fabricate decisions or fill gaps with assumptions.
27- Will not publish, distribute, or assign labels — publication is a human handoff.
28- Will not proceed to spec writing until the user confirms the identified seams.
29
30## Procedure
31
321. Explore the repository to understand the current state of the codebase if not already done. Identify the project's domain vocabulary and any ADRs in the relevant area. **Done when:** the codebase state and domain vocabulary are understood.
332. Identify the seams at which the feature will be tested. Prefer existing seams to new ones, and use the highest existing seam possible. If a new seam is needed, propose it at the highest practical point. Fewer seams across the codebase are better; the ideal number is one. **Done when:** the testing seams are identified.
343. Present the identified seams to the user and confirm they match expectations. Do not proceed until the user confirms. **Done when:** the user confirms the seams.
354. Synthesize the spec from the conversation context, codebase understanding, and confirmed seams. Do not interview the user or open a new round of questioning. Capture what has already been decided. **Done when:** the spec content is synthesized from settled decisions.
365. Write the spec to `docs/specs/<feature-slug>-spec.md` using the template below. **Done when:** the spec file is written to disk.
376. Verify the written file contains all seven sections populated with substantive content. If any section is empty or stubbed, fill it before declaring done. **Done when:** all seven sections are substantive.
387. Stop. Do not publish, distribute, or assign labels. Report the file path and that publication is a human handoff. **Done when:** the file path is reported and no publication action is taken.
39
40### Spec template
41
42Write the spec using this structure:
43
44```markdown
45# <Feature name> - spec
46
47### Problem statement
48
49The problem from the user's perspective.
50
51### Solution
52
53The solution from the user's perspective.
54
55### User stories
56
57A numbered list of user stories. Each in the format:
58
591. As an <actor>, I want a <feature>, so that <benefit>
60
61Cover all aspects of the feature exhaustively.
62
63### Implementation decisions
64
65A list of implementation decisions:
66- Modules to build or modify
67- Interfaces to modify
68- Technical clarifications
69- Architectural decisions
70- Schema changes
71- API contracts
72- Specific interactions
73
74Do NOT include specific file paths or code snippets unless a prototype produced a snippet that encodes a decision more precisely than prose (state machine, reducer, schema, type shape). Trim to the decision-rich part.
75
76### Testing decisions
77
78- What makes a good test (external behavior only, not implementation details)
79- Which modules will be tested
80- Prior art for similar tests in the codebase
81
82### Out of scope
83
84What is deliberately excluded from this spec.
85
86### Further notes
87
88Any additional notes about the feature.
89```
90
91## Failure and recovery
92
93| Failure class | Behavior |
94|---|---|
95| Missing settled decisions | Stop. Report exactly which decisions are missing. Do not fabricate decisions or fill gaps with assumptions. |
96| No seams identifiable | Propose seams at the highest reasonable points and present them as proposals, not facts. |
97| User rejects seams | Ask what they would prefer and iterate. Do not proceed to spec writing until seams are confirmed. |
98| Write failure | Report the error. No partial artifact is acceptable; delete any incomplete file. |
99| Non-convergent synthesis | Name the contradiction and stop rather than choosing a side silently. |
100
101## Output
102
103A local specification file at `docs/specs/<feature-slug>-spec.md` with all seven sections (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes) populated and agent-ready — publication is a separate human step.
majiayu000