Spec Writer — Structured Implementation Spec Generator
Generate high-quality, AI-agent-friendly spec documents from vague requirements.
When to Use
- User has a requirement, feature idea, bug report, or GitHub issue
- User wants a structured document before coding starts
- User says "write a spec", "plan this out", "spec this feature", etc.
- dev-workflow Phase 2 needs a detailed spec (can be called as a sub-step)
Output
A single Markdown spec document saved to the project directory (default: SPEC.md or spec/.md).
Workflow
Step 1: Gather Context
Collect information from available sources. Do not ask the user for things you can find yourself.
From the user's input:
- What to build and why
- Any explicit constraints or preferences
From the project (if accessible):
- Tech stack (package.json, Cargo.toml, pyproject.toml, go.mod, etc.)
- Project structure (directory layout)
- Existing architecture docs (llmdoc/, README, ARCHITECTURE.md, etc.)
- Code style patterns (sample existing code)
- Test setup (test framework, where tests live, how to run them)
- Git workflow (branch conventions, CI config)
From external sources (if referenced):
- GitHub issue details (title, body, comments, labels)
- Linked docs, designs, or API references
Step 2: Draft the Spec
Use the spec template at references/spec-template.md. Read it before generating.
Fill every section based on gathered context. Key principles:
- Be specific, not vague. "React 18 with TypeScript and Vite" not "React project."
- Focus on what and why first. User stories and success criteria anchor everything.
- Include real commands. Full commands with flags, not just tool names.
- Show, don't describe. One code example beats three paragraphs of explanation.
- State what NOT to do. Explicit exclusions prevent agent drift.
- Use three-tier boundaries. ✅ Always / ⚠️ Ask first / 🚫 Never.
Step 3: Review with User
Present the draft to the user. Common discussion points:
- Are the user stories complete? Any missing scenarios?
- Is the technical approach acceptable? Alternative architectures?
- Are boundaries correct? Anything too strict or too loose?
- Are verification criteria testable and sufficient?
- Is the task breakdown granularity right?
Revise until the user confirms. Mark status as "✅ Confirmed" when approved.
Step 4: Save and Deliver
Save the confirmed spec to the project. Suggested locations:
- Single feature:
SPEC.md in project root - Multiple specs:
spec/.md - With dev-workflow: the spec replaces the requirement doc in Phase 2
Tell the user the spec is ready and suggest next steps:
- Hand to a coding agent (dev-workflow, Claude Code, Codex, etc.)
- Use as a reference for manual implementation
- Share with team for review
Adapting to Project Scale
Small task (bug fix, small feature):
- Skip or compress sections that don't apply
- Focus on: Objective, Changes, Boundaries, Verification
- Total spec: ~50-100 lines
Medium task (feature, refactor):
- Use full template
- Total spec: ~100-250 lines
Large task (new module, major feature):
- Use full template with extended task breakdown
- Consider splitting into multiple specs (one per component/module)
- Include architecture diagram description or data model
- Total spec: ~200-400 lines
Principles
These come from industry best practices (GitHub's study of 2,500+ agent files, Anthropic's context engineering research, and practical spec-driven development patterns):
- Spec is the source of truth — It persists across sessions, anchoring the agent when context gets long or sessions restart.
- Structure for parseability — Clear Markdown headings, consistent format. AI models handle well-structured text better than free-form prose.
- Six core areas — Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries. Use as a completeness checklist.
- Three-tier boundaries — ✅ Always do (proceed without asking) / ⚠️ Ask first (need human approval) / 🚫 Never do (hard stop). More effective than flat rule lists.
- Modularity — Each section should be independently useful. A coding agent working on the backend doesn't need the frontend spec section in its context.
- Living document — Update the spec when decisions change. An outdated spec is worse than no spec.