Spec Workflow

Spec Workflow

Use this skill when behavior, acceptance criteria, compatibility, or product direction needs durable alignment before implementation. Routine work with clear behavior and validation does not need a spec.

Goal

Create lightweight specs that keep humans and coding agents aligned without adding heavy process overhead.

Use Clarification Gate output when available. If the feature behavior, non-goals, compatibility constraints, or acceptance criteria are not clear, run clarification-gate before drafting the spec.

Location

Use docs/specs/ by default.

Recommended file names:

docs/specs/
  auth-system.md
  editor-upgrade.md
  cloud-sync.md

Use a stable, descriptive kebab-case slug. Do not couple the file name to a release version or rename the spec when the release version changes.

Status Values

• Draft
• Planned
• In Progress
• Implemented
• Verified

Release Impact

Draft and name the spec without waiting for version confirmation.

Use version-governance only when the proposed change is release-visible. When useful, record an optional Release Impact section with:

• change type
• proposed release version
• confirmation status

The release manifest, release changelog, and tags remain authoritative for the released version.

Spec Sections

Use templates/SPEC.template.md as the baseline:

• Background
• Goals
• Non-Goals
• User Stories
• Requirements
• Existing System Review
• Technical Approach
• Release Impact when release-visible
• Acceptance Criteria
• Risks
• Open Questions
• Changelog

Rules

• Keep specs concrete and implementation-facing.
• Include only sections relevant to the change. Keep implementation sequencing in docs/plans/* and active coordination in docs/TASKS.md instead of duplicating either inside the spec.
• Do not create a spec solely because a change touches multiple files.
• Separate goals from non-goals.
• Include acceptance criteria that can be verified.
• Preserve Clarification Gate decisions in Background, Goals, Non-Goals, Requirements, Risks, or Open Questions instead of creating a separate intake document by default.
• Update status and changelog after implementation.
• Do not use specs as a dumping ground for unrelated product ideas.
• Use the spec changelog for spec revisions, not as the source of truth for release versions.