Spec Writing
Write specifications for this project using a standard template and conventions.
Constraints
- •Specs live in
docs/specs/(subfolders allowed for logical grouping) - •Filenames: lowercase, hyphenated (e.g.,
authentication.md,job-scheduler.md) - •All template sections required (use "None" if not applicable)
- •Acceptance criteria must be verifiable by an agent (observable outcomes, no subjective judgment)
- •New specs start with
status: draft
Workflow
- •Ask clarifying questions to gather context about what spec is needed
- •Invoke
/doc-coauthoringto develop the spec through structured collaboration - •Ensure output conforms to the template structure
- •If separable concerns exist (multiple distinct features that could be implemented independently), advise splitting into separate specs
Template
All specs follow this structure:
markdown
--- title: <Title> version: 0.1.0 last_updated: <ISO 8601 date> status: draft | review | approved | deprecated --- # <Title> ## Overview What this is and why it exists. ## Constraints Hard boundaries. Must/must not. Non-negotiable rules. ## Specification The core details. What it does, how it works. Precise enough to implement against. ## Acceptance Criteria - [ ] Given <precondition>, when <action>, then <outcome> ## Dependencies What this relies on to function. ## References Related specs, external docs, prior art.
Frontmatter
| Field | Description |
|---|---|
title | Human-readable name |
version | Semver. MAJOR for breaking changes to acceptance criteria, MINOR for additions/clarifications, PATCH for typos |
last_updated | ISO 8601 date (e.g., 2026-02-06) |
status | draft (WIP), review (ready for approval), approved (ready for implementation), deprecated (no longer active) |
Section Guidance
| Section | Purpose |
|---|---|
| Overview | One paragraph. What this is, why it exists. Orient the reader. |
| Constraints | Hard rules. What it must/must not do. Non-negotiable. |
| Specification | The core details. How it works. Precise enough to implement against. Use subsections if needed. |
| Acceptance Criteria | Verifiable conditions for completeness. Agent must be able to confirm pass/fail. |
| Dependencies | What this requires to function. Other specs, skills, tools, external systems. |
| References | Related context. Links to other specs, external docs, prior art. Not required to function. |
Acceptance Criteria Format
Use Given/When/Then format. Each criterion must be verifiable with observable outcomes.
Good examples:
markdown
- [ ] Given a valid spec file path, when the skill is invoked, then the output file exists in `docs/specs/` - [ ] Given the generated spec, when reviewed, then all sections from the template are present - [ ] Given acceptance criteria in the output, when evaluated, then each criterion references an observable outcome
What makes these good:
- •Precondition is clear (Given)
- •Action is specific (When)
- •Outcome is observable and verifiable (Then)
- •No subjective judgment required
Avoid:
- •"Given X, when reviewed, then it is well-written" (subjective)
- •"Given X, when tested, then it works correctly" (vague)