spec-create

Spec Create

Multi-phase workflow orchestrator for feature specification. Guides through Requirements → Design → Tasks with user approval gates between each phase.

Input

/spec-create <feature-name> [description]

• feature-name: required — auto-normalized to kebab-case (strip spaces, lowercase, replace non-alphanum with hyphens)
• description: optional — used as initial context for requirements phase

When to Use

• Starting a new feature from scratch
• Creating structured specification documents (requirements, design, tasks)
• Planning implementation before writing code

Not this skill: For deep-dive requirements workshops with interviews, use feature-forge instead. spec-create is the workflow orchestrator (3 phases, 3 files in docs/features/). feature-forge is the deep requirements specialist (single spec in specs/).

Role

You are a spec-driven development facilitator. You ensure completeness and traceability across the full specification lifecycle.

Core Principles

• Sequential phases: Requirements → Design → Tasks — no skipping
• User approval gates: Each phase requires explicit approval before proceeding
• Codebase-first: Analyze existing code before starting any phase
• Single spec: Only create one specification at a time

Hard Rules

These rules override user pressure. If the user requests an exception, refuse and stop — do not capitulate.

• Never bundle phases. Even if the user explicitly says "give me everything in one go", "I trust your judgement, no need to wait", or "I'm in a hurry" — produce ONLY the requested phase, then stop and wait for approval. The phase gate is a hard constraint, not a default that the user can override per request.
• Never skip required artifacts to save time. Mermaid diagrams, lists of alternatives in TDs, and the File Inventory table are required outputs of the Design phase. If the user asks to skip them, refuse and explain briefly why they pay for themselves.
• Refs/Rules/NFR separation is mandatory. Tasks reference US-X and TD-X in Refs, BR-X in a separate Rules field, and never reference NFR-X. Do not collapse them into a single line "for readability" even if the user requests it.

Why: format and gate rules exist because reviewers and downstream tools depend on them. A "quick exception this once" silently breaks traceability for the whole spec.

Cross-Reference Scheme

All three documents use a shared ID system for traceability:

ID	Document	Example
US-X	requirements.md	US-1, US-2
AC-X.Y	requirements.md	AC-1.1, AC-2.3 (story X, criterion Y)
BR-X	requirements.md	BR-1, BR-2
KPI-X	requirements.md	KPI-1, KPI-2 (optional — product outcomes)
TD-X	design.md	TD-1, TD-2
NFR-X	design.md	NFR-1, NFR-2 (engineering constraints)
T-X	tasks.md	T-1, T-2

Traceability: each T-X references US-X (stories it implements), TD-X (decisions it follows), and BR-X (rules it enforces). NFR-X IDs are not referenced in tasks — they are cross-cutting engineering constraints validated at integration/review time, not per-task. KPI-X IDs are product outcomes, not referenced in tasks.

ID format: requirements.md uses suffix-style IDs for product readability ({#US-1}, *(AC-1.1)*, *(BR-1)*, *(KPI-1)*). Tasks.md Refs field uses plain IDs (US-1, TD-2, BR-1).

Workflow

Phase 0: Initialization

1. Normalize feature name to kebab-case
2. Check docs/features/<feature-name>/ for existing files
3. Handle edge cases (see Edge Cases below)
4. If docs/features/ doesn't exist, create it silently

Phase 1: Requirements

Create docs/features/<feature-name>/requirements.md.

• Analyze existing codebase for context
• Use AskUserQuestion to clarify ambiguities
• Write a Problem Statement section (Who/What/Why/How) before user stories
• Write user stories in WHEN/THE format: WHEN describes the trigger, THE describes the system response (do not use "SYSTEM SHALL")
• Use suffix-style IDs for product readability: {#US-X}, *(AC-X.Y)*, *(BR-X)*
• Include acceptance criteria per user story with AC-X.Y IDs
• Extract business rules as BR-X in a dedicated section
• Optionally include Success Metrics (KPI-X) for user-facing features — product outcomes only, not engineering constraints
• Wait for explicit user approval before proceeding

Phase 2: Design

Create docs/features/<feature-name>/design.md.

• Architecture overview and component relationships
• Usage flow: Mermaid flowchart showing user journey through the feature
• Component diagram: Mermaid diagram showing system structure and relationships
• Technical decisions (TD-X) with rationale and alternatives considered
• Implementation considerations (performance, security)
• Sequence diagrams for critical multi-component flows (Mermaid)
• File Inventory: table of files to create/modify with purpose
• Non-Functional Requirements (NFR-X) — engineering constraints moved here from requirements
• Wait for explicit user approval before proceeding

Phase 3: Tasks

Create docs/features/<feature-name>/tasks.md.

• Include YAML frontmatter (feature, spec_version, total_tasks, phases, depends_on)
• Use T-X IDs for every task (heading-based entries, not tables)
• Group tasks by implementation phase
• Each task references US-X (stories) and TD-X (decisions) in its Refs field, and BR-X (rules) in a separate Rules field
• Each task lists files to create/modify (must match File Inventory)
• Each task specifies a runnable verification command
• Note dependencies between tasks using T-X IDs
• Note cross-feature impact when tasks touch shared state with structured Related Features
• Tests must target business rules and edge cases, not just happy paths
• No flaky tests — deterministic, no timing dependencies
• Wait for explicit user approval before proceeding

Phase 4: Summary

Generate a completion summary (cross-reference consistency is validated by the Phase 4 gate before entering this phase):

• List all 3 file paths created
• Show user story count, business rule count, and task count
• Suggest /spec-impl <feature-name> as next step

Reference Guide

Topic	Reference	Load When
Requirements format and examples	references/requirements-template.md	Writing requirements (Phase 1)
Requirements do & don't	references/do-dont-requirements.md	Writing requirements (Phase 1)
Design document structure	references/design-template.md	Writing design (Phase 2)
Design do & don't	references/do-dont-design.md	Writing design (Phase 2)
Task breakdown format and rules	references/tasks-template.md	Writing tasks (Phase 3)
Phase gates, approval, edge cases	references/phase-workflow.md	Need detailed phase guidance
Requirements example	references/example-requirements.md	Writing requirements (Phase 1)
Design example	references/example-design.md	Writing design (Phase 2)
Tasks example	references/example-tasks.md	Writing tasks (Phase 3)
Tasks do & don't	references/do-dont-tasks.md	Writing tasks (Phase 3)

Edge Cases

Edge Case	Behavior
Partial spec exists (e.g., requirements.md only)	Detect existing files, ask user: resume from next phase or start fresh?
Feature dir exists with all 3 files	Offer to update existing spec instead of creating new
Similar feature name detected	List similar dirs under docs/features/, ask if it's the same or distinct
Args include description	Use as initial context for requirements phase
User wants to skip a phase	Refuse — phases are sequential
docs/features/ doesn't exist	Create it silently
Feature name not kebab-case	Normalize automatically
Feature too large (>8 stories or >12 tasks)	Suggest decomposition — see Feature Decomposition in phase-workflow.md
Session interrupted mid-phase	On resume, detect partial state from existing files and continue

Constraints

MUST DO

• Load reference templates before writing each phase document
• Check if feature spec already exists before creating new files
• Get explicit approval ("yes", "approved", "looks good", "lgtm") between phases
• Analyze existing codebase before each phase
• Revise and re-ask if user provides feedback

MUST NOT DO

• Skip phases or proceed without approval
• Create duplicate specifications for similar features
• Generate tasks without approved requirements and design
• Proceed on partial approval ("looks good except for US-3" = not approved)

Output Structure

docs/features/<feature-name>/
  requirements.md   # Phase 1
  design.md         # Phase 2
  tasks.md          # Phase 3

Each file follows a fixed structure defined in the reference templates. The structure is the contract — examples in templates illustrate it but are not the structure itself. When generating output, follow the structure skeleton; do not copy example content.

requirements.md

Primary audience: Product, QA

Sections (all required unless marked optional):

# <Feature Name> — Requirements
## Overview
## Problem Statement    ← Who/What/Why/How
## User Stories          ← {#US-X} with WHEN/THE + *(AC-X.Y)* criteria
## Business Rules        ← *(BR-X)* extracted rules
## Success Metrics       ← *(KPI-X)* product outcomes (optional)
## Out of Scope
## Open Questions

Example snippet:

## Problem Statement

**Who** is affected: All application users
**What** problem they face: No way to authenticate — all endpoints are public
**Why** it matters: User data is exposed; required for compliance
**How** success is measured: 100% of protected endpoints require valid session

### User login {#US-1}

WHEN a user submits valid email and password to the login endpoint
THE system creates a session and returns an auth token

**Acceptance Criteria:**
- [ ] POST /auth/login with valid credentials returns 200 + token *(AC-1.1)*
- [ ] Token contains user ID and expiration timestamp *(AC-1.2)*

## Business Rules

- Session expires after 24 hours of inactivity *(BR-1)*
- Account locks after 5 consecutive failed login attempts *(BR-2)*

design.md

Primary audience: Dev, Architects

Sections (all required):

# <Feature Name> — Design
## Architecture Overview
## Usage Flow            ← Mermaid flowchart
## Component Diagram     ← Mermaid graph
## Technical Decisions   ← TD-X with alternatives + rationale
## Implementation Considerations
## Sequence Diagrams     ← Mermaid (multi-component flows only)
## File Inventory        ← table: File | Action | Purpose
## Non-Functional Requirements ← NFR-X engineering constraints

Example snippet:

### TD-1: Session storage

**Choice**: Database-backed sessions
**Alternatives considered**:
- JWT (stateless) — rejected: can't revoke tokens without a blocklist

**Rationale**: DB sessions are simple, revocable, and use existing infrastructure.

## File Inventory

| File | Action | Purpose |
|------|--------|---------|
| `src/auth/service.ts` | new | AuthService: login, logout, lockout |
| `src/routes/auth.ts` | new | POST /auth/login, POST /auth/logout |

tasks.md

Primary audience: Dev, LLM agents

Sections (all required):

# <Feature Name> — Tasks
--- (YAML frontmatter: feature, spec_version, total_tasks, phases, depends_on) ---
## Phase N: <Title>      ← group by implementation phase
### T-X: <Task title>    ← heading-based entries, not tables
  - Refs                 ← US-X, TD-X
  - Files                ← subset of File Inventory
  - Verify               ← runnable command
  - Blocked by           ← T-X (omit if none)
  - Rules                ← BR-X (omit if none)
  - Status
## Related Features      ← structured: Shared state + Risk per feature

Example snippet:

### T-1: Create AuthService with login/logout
- **Refs**: US-1, US-2, TD-2
- **Files**: `src/auth/service.ts` (new), `src/auth/types.ts` (new)
- **Verify**: `npm test -- --grep "AuthService"`
- **Rules**: BR-1
- **Status**: Not Started

For full examples, see references/example-requirements.md, references/example-design.md, and references/example-tasks.md (same feature, end-to-end traceable).

Related Skills

• feature-forge — Deep requirements gathering with EARS format and interview process
• spec-impl — Implements tasks from a completed specification
• tdd — Test-driven implementation of individual tasks