spec-writing
npx machina-cli add skill LiorCohen/sdd/spec-writing --openclawSpec Writing Skill
Templates
Use templates below as starting points.
Input
Schema: schemas/input.schema.json
Accepts spec type, change type, title, domain, and optional issue reference.
Output
Schema: schemas/output.schema.json
Returns complete SPEC.md markdown and validation results for required fields, sections, and format.
Spec Types: Product vs Tech
Product Specs (external input):
- Focus on WHAT and WHY
- Typically authored by product managers or stakeholders
- Archived as-is when imported via external spec workflow
spec_type: product
Tech Specs (generated SPEC.md files):
- Focus on HOW
- Generated from product specs + solicitation
- Full implementation details
spec_type: tech
Spec Lifecycle
Git is the state machine:
- In PR = draft (implicit, no status field needed)
- Merged to main = active
- Explicit statuses only for:
active,deprecated,superseded,archived
Spec Locations
| Type | Location |
|---|---|
| Change specs | changes/YYYY/MM/DD/<change-name>/SPEC.md |
| Implementation plans | changes/YYYY/MM/DD/<change-name>/PLAN.md |
| Domain definitions | specs/domain/definitions/<definition-name>.md |
| API contracts | specs/architecture/api-contracts.md |
Date-based organization:
- Changes are organized by creation date (YYYY/MM/DD)
- This provides chronological traceability
- Plans live alongside their specs in the same directory
Acceptance Criteria Format
Always use Given/When/Then:
- [ ] **AC1:** Given [precondition], when [action], then [expected result]
Resource Files
For detailed guidance, read these on-demand:
- feature-spec-template.md — Complete feature spec template
- epic-spec-template.md — Epic structure with child changes
- other-templates.md — Domain definition + product spec templates
- frontmatter-validation.md — Frontmatter fields + validation rules
Source
git clone https://github.com/LiorCohen/sdd/blob/main/plugin/core/skills/spec-writing/SKILL.mdView on GitHub Overview
Spec Writing Skill provides templates and validation to craft complete SPEC.md. It explains the distinction between Product specs (WHAT/WHY) and Tech specs (HOW), outlines the spec lifecycle, and maps where specs live in the repository. It also includes guidance on acceptance criteria and validation rules to ensure consistency.
How This Skill Works
Inputs are passed through a schema that captures spec_type, change_type, title, domain, and optional issue reference. It outputs a complete SPEC.md and a validation report that checks required fields, sections, and format against the defined schemas. It supports both product specs (external input) and tech specs (generated from product specs) and references the prescribed file locations and lifecycle rules.
When to Use It
- When drafting a new feature requirement (Product spec) for WHAT/WHY.
- When preparing a detailed implementation plan (Tech spec) from a product spec.
- When organizing changes or plans under date-based folders like changes/YYYY/MM/DD.
- When defining domain terms or API contracts in the specified specs/ paths.
- When enforcing acceptance criteria using Given/When/Then checks.
Quick Start
- Step 1: Fill in the input schema (spec_type, title, domain, etc.).
- Step 2: Generate SPEC.md and review validation results.
- Step 3: Commit to the appropriate repo path under the correct lifecycle state.
Best Practices
- Define spec_type early to drive focus (Product vs Tech).
- Keep Product specs external-input oriented; Tech specs should include HOW.
- Follow the designated locations for changes, plans, and domain definitions.
- Validate required fields and sections with the provided acceptance criteria format.
- Leverage templates and resource files for consistent structure.
Example Use Cases
- Product spec for a new onboarding flow detailing WHAT users will see and WHY.
- Tech spec for an API change, generated from the product spec, outlining endpoints and implementation details.
- Domain definition for a new payment domain stored at specs/domain/definitions/payment.md.
- Change spec for a UI refresh stored in changes/2024/11/feat-ui-refresh/SPEC.md.
- API-contracts.md updated with a new contract in specs/architecture/api-contracts.md.
