| name | spec-writer | |
|---|---|---|
| description | Interactive specification writer that captures requirements and creates focused, phased implementation plans with requirements as GitHub issues or local spec files | |
| argument-hint |
|
Generate focused, precise implementation specs through an interactive Q&A process, breaking features into logical phases and creating specs in dependency order.
Audience: the specs are consumed by LLM implementing agents (of varying models and capabilities), not humans. Different models fill spec gaps differently — wherever a spec is ambiguous, each implementer invents a different answer. Precision converges them; narrative prose does not. Every rule below serves that goal: exact contracts, machine-checkable done-ness, explicit anti-goals, and zero undefined qualifiers.
When running in interactive mode, use the /grill-me skill to build agreement as needed.
- Interface-first precision. Any new or changed endpoint, DTO, config property, schema, collection, CLI, or event is stated EXACTLY: path, name, type, default, error codes/status codes. Ambiguity in contracts makes implementations diverge; ambiguity in internals is fine — grant it explicitly: "Internal design is implementer's choice provided the stated contract holds."
- Context split rule. Include everything non-discoverable from the repo: decisions made during the interview, policies (deploy windows, compatibility guarantees), cross-system gotchas, production knowledge. Point to (file path/symbol) rather than duplicate what's greppable — implementing agents research the codebase themselves.
- Verification-first. Every acceptance criterion must be objectively checkable: an exact command, a named test that must exist and pass, a request→expected-response pair, or a greppable condition. If it can't be checked mechanically or by a named observation, rewrite it until it can.
- Traceability. Every requirement maps to ≥1 acceptance criterion; no criterion exists without a requirement behind it.
- No undefined qualifiers. See the Ambiguity Lint (Step 5) — it is a mandatory gate.
- Agent-executed specs verify without a running environment. When the spec will be handed to an autonomous agent (Composer task, cloud agent, any run on a host you don't control), Acceptance Criteria and Verification may use only the test runner, the build, and greppable conditions. Never
npm run dev, never a curl against a port, never a database outside a test-created temp directory. Checks that need a running app go in a separate section titled "Post-merge manual check (human, local dev machine only — NOT for the implementing agent)", and the Do NOT list gets a standing bullet forbidding server start-up, the project's fixed ports, and non-temp databases. Cite the repo's in-process test pattern (anexpress()app onlisten(0)with a temp DB, or the equivalent) so implementers converge on it. Why: [host-specific rationale redacted for publication.]
When the user invokes this command, they will provide initial context about what they want to specify. Read the context carefully and:
-
Identify the feature type:
- New feature implementation
- Extension of existing stubbed functionality
- Enhancement/refinement of existing feature
- Bug fix requiring specification
- Refactoring with behavior changes
-
Locate relevant code:
- Use Explore agent to find related files in the codebase
- Read existing implementations, interfaces, or stubs
- Identify dependencies and integration points
- Review related documentation (README, docs/, wiki, etc.)
-
Inspect the live UI (MANDATORY GATE whenever the work touches a UI):
This step may not be passed over silently. Before Step 2, do exactly ONE of the following, and carry the outcome into the Step 4 outline:
a. Ask the scripted question, then inspect:
"Does this project have a running UI I should inspect? If so, what URL and credentials should I use?"
Use the instrument that matches the surface being changed:
- Web / Thymeleaf / any browser UI → Chrome DevTools MCP or the in-app browser
- Mobile (React Native / Expo) → the iOS Simulator MCP, or Maestro with deep links
- Both surfaces changed → both instruments; one is not evidence for the other
b. Record an explicit skip, naming a reason from this closed list:
- No UI surface is touched (API-only, CLI, library, data migration, infra).
- The user declined, or has no running instance available.
- The UI is already pinned down by a design artifact the spec cites by path.
"I read the templates/components instead" is NOT a valid skip reason. Static reading gives you structure and class names. It does not show layout pressure, cramped containers, what a real empty or loading state looks like, or whether a new control has anywhere to go. Those are exactly what a UI phase's spec has to get right, and they are the things a spec author invents plausibly and wrongly.
Boundary note. Core Principle 6 (agent-executed specs verify without a running environment) governs what the IMPLEMENTING AGENT may do when verifying the finished spec on a host you do not control. It places no restriction on the spec author's own research on the user's machine. Do not cite it as grounds to skip this step; the two rules do not conflict.
When inspecting UI, look for:
- Current UI layout and component structure
- Existing navigation patterns
- Visual design patterns and consistency
- Form patterns and validation styles
- Loading states, empty states, and error handling patterns
- Any stubbed features or placeholder content related to the request
-
Review project context:
- Check for CLAUDE.md, AGENTS.md, or similar instruction files for coding standards
- Look for documentation on the tech stack, architecture, or conventions
- Check for database schemas or API contracts if relevant
- Look for similar features in the codebase to follow established patterns — and record the file/symbol references now; the spec must cite them, not gesture at them
Break the feature into logical, independent phases (think PRD). Sizing is scope-based — no time units anywhere. Each phase must be:
- One PR, one concern — a single coherent change with one reason to exist
- Independently verifiable — its Verification section can pass with later phases unstarted
- A reviewable diff — if the change set would be unreviewably large or mixes concerns, split it
- Clearly scoped — no ambiguity about what's included, what's forbidden, and what's deferred
Good Phase Boundaries:
- Backend data model → Frontend UI → Advanced features
- Read-only display → Basic editing → Advanced editing
- Core functionality → Notifications → Analytics
- Database/API structure → CRUD operations → Business logic
- Basic form → Validation → Integration with existing features
Phase Sizing Rules:
- If a phase mixes concerns (e.g. a wire-visible change AND an internal refactor), split it
- If a phase can't be verified independently, reconsider boundaries
- If a phase delivers nothing verifiable on its own, combine it with another phase
- If phases have circular dependencies, redesign the breakdown
Common Decomposition Patterns:
Pattern 1: Data → UI → Features
- Phase 1: Data model, schema, migrations, API endpoints
- Phase 2: Basic CRUD UI (create, read, update, delete)
- Phase 3: Advanced features (filtering, sorting, pagination)
- Phase 4: Notifications and integrations
Pattern 2: Foundation → Enhancement → Polish
- Phase 1: Core functionality (minimum viable feature)
- Phase 2: User experience improvements (validation, feedback)
- Phase 3: Edge cases and error handling
- Phase 4: Performance and optimization
Pattern 3: Layer-Based
- Phase 1: Data layer (models, storage, queries)
- Phase 2: Service/business logic layer
- Phase 3: Presentation/API layer
- Phase 4: Integration and end-to-end testing
- Present the proposed phases to the user with clear boundaries
- Explain dependencies between phases (what must come first)
- Ask for feedback on the breakdown
- Adjust based on user priorities or constraints
- Confirm the final phase structure before proceeding
Example Output:
I've analyzed the feature request and propose breaking it into 3 phases:
**Phase 1: Data Model & API**
- Database schema/models, API endpoints (exact contracts below)
- Validation and constraints
- Unit tests for the data layer
**Phase 2: Basic CRUD UI**
- List view + create/edit form
- Validation, success/error states
**Phase 3: Advanced Features**
- Filtering, search, pagination
- Notifications; integration with existing features
Dependencies: none by default. A phase depends on another only when it consumes that phase's artifact or code contract (name which one and why)
Does this breakdown make sense? Should we adjust the scope of any phase?
Ask only the essential questions for THIS phase. Focus on what's needed now, not future phases. Keep questions conversational and adaptive. Use the AskUserQuestion tool whenever possible.
The interview has one extra job now: every decision resolved here must land in the spec (context split rule) — the implementing agent was not in the room.
- What does this phase accomplish? (specific, verifiable outcome)
- Who can use it? (roles and permissions, if applicable)
- Where does it live? (UI location, API route, module, etc.)
- What data is involved? (inputs, outputs, validation — exact shapes)
- What happens when it fails? (specific error behavior: status codes, messages, fallbacks — never "handle errors gracefully")
- How do we verify it? (commands, tests, observable outcomes)
- Database changes? → Exact schema details, migrations
- New API endpoints? → Exact contract (paths, request/response shapes, status codes), authentication, rate limits
- External integrations? → API keys, rate limits, failure behavior
- Notifications? → Channels, templates, triggers
- Performance concerns? → Pagination, caching, quotas (with numbers)
- Auth/permissions? → Who can do what, and what the denied case returns
Keep it focused: Don't ask about features in future phases. Don't over-specify internals — contracts must be exact; implementation inside the contract belongs to the implementer.
For each phase, create a focused specification:
- Summarize what this phase accomplishes (2-3 sentences)
- Confirm any gaps or uncertainties — unresolved items go back to the interview, never into the issue
- State the Step 1.3 outcome — one line: what was inspected and with which instrument, or the recorded skip reason
- Show the spec outline for approval
Before any issue or file is created, lint every spec draft. A draft failing any check goes back to Step 3/4 — never ship the ambiguity to the implementer.
- Banned undefined qualifiers: "appropriate", "properly", "correctly", "gracefully", "robust", "as needed", "if necessary", "handle errors" (without defined behavior), "etc." / trailing open enumerations. Each occurrence is either replaced with the concrete behavior or explicitly delegated: "implementer's choice, provided ".
- Pattern citations: every "follow existing pattern" names a file and symbol (e.g.
src/.../FantasyContestController.javadual@RequestMapping). No uncited "as done elsewhere". - Complete enumerations: lists of endpoints, fields, screens, or cases are complete, or the rule generating them is stated precisely ("every key in API_ENDPOINTS whose path starts with /api/tournaments").
- Contract exactness: every wire-visible or persisted artifact (endpoint, DTO field, config property, schema, collection, event) appears with its exact name/path/type/default/error behavior.
- Traceability: every requirement has ≥1 acceptance criterion; every criterion traces to a requirement.
- Checkability: every acceptance criterion is machine-checkable or a named observation (command, test name, request→response, greppable condition). "Works correctly" never survives the lint.
- Non-discoverable context present: interview decisions, policies, and gotchas that cannot be found in the repo are in the spec; greppable facts are cited by path, not duplicated at length.
- No running-environment verification for agent-executed specs: grep the draft for
npm run dev,npm start,localhost:,curl, and the project's dev/prod port numbers. Any hit outside the "Post-merge manual check" section fails the lint. The Do NOT list must contain the no-server bullet (Core Principle 6).
Ask the user how they want the specs delivered:
How would you like the specs delivered?
1. **GitHub Issues** - Create linked issues in dependency order
2. **Local Spec Files** - Write markdown files to a specs/ or docs/ directory
Create a concise, precise GitHub issue per phase using this template:
## Phase [N]: [Clear, Descriptive Title]
> Part of [Feature Name] - [Link to related phases if applicable]
### What This Phase Delivers
[1-2 sentences describing the specific outcome of THIS phase only]
**Why:** [One sentence — the motivation/benefit. No user-story ritual.]
### Requirements
1. [Numbered, verifiable requirement — exact contracts inline or referenced below]
2. [Another requirement]
3. [Keep the list short and complete — every item traceable to an acceptance criterion]
**Permissions:** [Which roles can access this, and what the denied case returns. Omit if not applicable]
**Error behavior:** [Specific: status codes, messages, fallbacks, retries. Never "handle gracefully"]
### Contracts
[Exact definitions of every wire-visible or persisted artifact this phase adds/changes: endpoint paths + methods + request/response shapes + status codes; DTO/field names + types; config properties + defaults; schema/collection changes. Omit the section only if the phase changes no contract.]
[Close with the freedom grant where applicable: "Internal design is implementer's choice provided these contracts hold."]
### UI/UX (if applicable)
- **Location:** [Where in the app]
- **Pattern:** [Follow [component/pattern] at [file path / symbol] — always cited]
- **States:** Loading, Empty, Error, Success [concrete description of each]
### Technical Notes
**Non-discoverable context:** [Decisions made during spec'ing, policies, cross-system gotchas, prod knowledge — everything the implementer cannot find in the repo]
**Integration points:** [Files that need modification — specific paths]
**Patterns to follow:** [Existing code to imitate — file:line or file+symbol references]
### Acceptance Criteria
- [ ] [Machine-checkable criterion: exact command + expected result, named test that must exist and pass, request→expected response, or greppable condition]
- [ ] [Another — each traces to a numbered requirement]
- [ ] All affected apps' full test suites pass ([exact commands per app])
- [ ] API test collection (e.g. Bruno) updated for any API surface change
- [ ] Docs updated for any behavior/config change (AGENTS.md, docs/, in-app help as applicable)
[The last three are STANDING criteria — include them in every issue, tailored to the repo's actual commands/paths. Drop only those provably inapplicable (e.g. no API change → no Bruno item).]
### Verification
1. [Exact test/build command(s) and the expected outcome — e.g. `npm test` green including <named new tests>]
2. [Named new tests that must exist, and what each proves]
3. [Greppable condition: exact `grep` and what it must show]
[2-5 items; every item runs without a server. Agent-executed specs never start the app here — see Core Principle 6.]
### Post-merge manual check (human, local dev machine only — NOT for the implementing agent)
1. [Steps that need a running app: start the dev server locally, precise clicks/requests, precise expected observation]
[Include only when a running-app check adds something the tests cannot. Omit the section otherwise.]
### Do NOT
- [Forbidden actions in this PR: no drive-by refactors, no renames beyond spec, no new dependencies unless listed, no changes to (specific protected surfaces)]
- Do not start the server or dev server in any form ([project's exact commands]), do not connect to ports [project's dev/prod ports], and do not open any database outside a directory the test itself created. Verify only with [test command], [build command], and the grep checks above. [Standing bullet for agent-executed specs; tailor commands and ports to the repo.]
[Anti-goals converge implementers of different models; be explicit.]
### Dependencies
**Requires:** [Link to previous phase issues, or "None"]
**Blocks:** [Link to next phase issues, or leave empty until created]
### Out of Scope
- [Deferred/future work this phase explicitly does NOT include — distinct from Do NOT, which is forbidden action]
---
**Labels:** `phase-[N]`, `[feature-name]`, `[area]`, `priority-[level]`Create issues in phase order. Add a Requires: line only for a concrete prerequisite (the phase consumes an artifact or code contract from another phase) and say why:
- Show all issue outlines to the user for final approval
- Confirm the user is ready to create all issues
- Create Phase 1 issue first
- Update each subsequent issue to reference the previous one
- Track all created issue URLs
Ask the user where to save spec files (default: specs/ or docs/specs/ in the project root).
Create one markdown file per phase, named: [feature-name]-phase-[N].md
Use the same template as the GitHub issue format above, but written as a standalone document.
Also create a summary file: [feature-name]-overview.md containing:
- Feature overview
- Phase breakdown
- Dependency graph
- Links to individual phase files
Present a complete summary to the user:
Created [N] phase specs for [Feature Name]:
**Phase 1: [Title]**
[Issue URL or file path]
[1-line summary]
**Phase 2: [Title]**
[Issue URL or file path]
[1-line summary]
Depends on: Phase 1
**Phase 3: [Title]**
[Issue URL or file path]
[1-line summary]
Depends on: Phase 2
**Recommended Order:**
Phases without a `Requires:` line are independent and can be worked in parallel. A phase with one waits for the prerequisite phase's PR to merge.
Only when the GitHub Issues output format was used. Using the standard persistent memory system, save one project-type memory (name: project-[feature-slug]-issues) listing each phase title and issue number, so future sessions can resume the work without re-searching GitHub. Note in the memory that issues should be verified as still open before acting on them.
Skip this step if: local spec files were chosen (the files themselves serve as the index), or the feature is a single small phase with one issue (no set to track).
- Write for LLM implementers of varying capability - Precision converges heterogeneous models; gaps make them diverge
- State contracts exactly, grant internals freely - Wire-visible = exact; internal design = implementer's choice within the contract
- Make done-ness machine-checkable - Commands, named tests, request→response pairs, greppable conditions
- Run the Ambiguity Lint on every draft - It is a gate, not a suggestion
- Include non-discoverable context; cite discoverable context - The implementer can grep the repo but wasn't in the interview
- Explore the codebase first - Understand existing patterns before specifying, and capture file/symbol references for citation
- Inspect the live UI, or record why you didn't - Step 1.3 is a gate, not a suggestion; a silent skip is a defect, and Core Principle 6 is not grounds to skip it
- Add explicit Do-NOT anti-goals - Different models overreach in different directions; anti-goals converge them
- Declare only concrete prerequisites - A phase depends on another only when it consumes its artifact or code contract; state the reason in the dependent issue
- Size by scope, never by time - One PR, one concern, independently verifiable
- Don't ship undefined qualifiers - "appropriate", "gracefully", "as needed", trailing "etc." never survive the lint
- Don't write user stories or hour estimates - Human-planning artifacts that spend tokens without informing an LLM implementer
- Don't create monolithic specs - Break large features into phases
- Don't over-specify internals - Contracts exact, implementation free; prescribing internals wastes precision where divergence is harmless
- Don't duplicate greppable facts at length - Cite the path; the implementer researches the repo itself
- Don't chain by habit - Shared project, similar labels, or list order are not prerequisites; independent phases stay standalone
- Don't mix phases - Keep each phase independently deliverable and verifiable
- Don't assume the tech stack - Discover it from the project, don't guess
- Don't skip codebase exploration - Always understand existing code first
- Gather - Context, codebase, project standards (capture citations)
- Inspect - Live UI via the instrument matching each changed surface, or an explicit recorded skip (gate)
- Decompose - Scope-based phases: one PR, one concern, independently verifiable
- Question - Essential details per phase; every decision lands in the spec
- Synthesize - Precise spec per phase (exact contracts, verification, anti-goals)
- Lint - Ambiguity Lint gate; failures return to the interview
- Create - GitHub issues or local spec files in dependency order
- Summarize - Present all specs with dependencies
- Record - Write a project-type auto-memory entry indexing the issue set (GitHub-issues output only)
Remember: The spec is the only channel between the decisions made here and an implementer who wasn't in the room and may be any model. Exact contracts, checkable criteria, explicit anti-goals — when in doubt, make it verifiable.