@.claude/shared-imports/constitution.md
@.claude/shared-imports/CoD_Σ.md
@.claude/templates/feature-spec.md
@.claude/templates/requirements-quality-checklist.md
Specification Creation Skill
Overview
This skill creates technology-agnostic feature specifications following Article IV: Specification-First Development. It captures WHAT and WHY (user needs, requirements, success criteria) WITHOUT HOW (technical implementation, architecture, tech stack).
Core Workflow: Quality Gate → Intelligence Gathering → User Requirements → Specification → Automatic Planning
Automatic Workflow Progression: After creating spec.md, this skill automatically invokes /plan which chains through create-implementation-plan → generate-tasks → /audit → ready for /implement.
Announce at start: "I'm using the specify-feature skill to create a technology-agnostic specification."
Quick Reference
| Phase | Key Activities | Output |
|---|---|---|
| Phase 0 | Quality assessment (5 dimensions, 0-10 scale) | PROCEED/CLARIFY/BLOCK decision |
| Phase 1 | Intelligence queries (auto-number, patterns, architecture) | Evidence for spec |
| Phase 2 | Extract requirements (problem, stories, functional, success) | Technology-agnostic requirements |
| Phase 3 | Generate specification (directory, branch, spec.md) | spec.md file |
| Phase 4-5 | Report + automatic planning (invoke /plan) | Workflow to tasks.md + audit |
Workflow Files
- @.claude/skills/specify-feature/workflows/quality-assessment.md - Phase 0: Quality gate with 5 dimensions
- @.claude/skills/specify-feature/workflows/intelligence-gathering.md - Phase 1: Intel-first context
- @.claude/skills/specify-feature/workflows/user-requirements.md - Phase 2: WHAT/WHY extraction
- @.claude/skills/specify-feature/workflows/spec-generation.md - Phase 3: Create spec.md
- @.claude/skills/specify-feature/workflows/automation.md - Phase 4-5: Reporting + automatic /plan
Example & References
- @.claude/skills/specify-feature/examples/feature-creation-example.md - Complete walkthrough
- @.claude/skills/specify-feature/references/specification-rules.md - Best practices and anti-patterns
Phase 0: Pre-Specification Quality Gate
See: @.claude/skills/specify-feature/workflows/quality-assessment.md
Summary:
Validate user input quality BEFORE creating specification using 5 quality dimensions (0-10 scale):
- Problem Clarity - Clear problem statement, pain points, measurable impact
- Value Proposition - Business/user value, quantified benefits, success metrics
- Requirements Completeness - Key capabilities, scenarios, constraints
- Technology-Agnostic - Zero technical details, pure WHAT/WHY focus
- User-Centric - User needs central, personas, user value clear
Thresholds:
- ≥ 7.0: PROCEED to Phase 1
- 5.0-6.9: CLARIFY - Request specific improvements
- < 5.0: BLOCK - User description too vague
Why This Matters: Prevents wasting effort on vague or technically prescriptive inputs. Quality gate catches issues before specification creation.
Phase 1: Intelligence-First Context Gathering
See: @.claude/skills/specify-feature/workflows/intelligence-gathering.md
Summary:
Query project intelligence BEFORE creating specification to discover existing patterns:
Step 1.1: Auto-Number Next Feature
!`fd --type d --max-depth 1 '^[0-9]{3}-' specs/ 2>/dev/null | sort | tail -1`
Step 1.2: Query Existing Patterns
!`project-intel.mjs --search "<user-keywords>" --type md --json > /tmp/spec_intel_patterns.json`
Step 1.3: Understand Project Architecture
!`project-intel.mjs --overview --json > /tmp/spec_intel_overview.json`
Token Efficiency: 85% savings vs reading full spec files
Why This Matters: Intelligence evidence ensures specifications build on existing patterns rather than duplicating or conflicting with previous work.
Phase 2: Extract User Requirements (WHAT/WHY Only)
See: @.claude/skills/specify-feature/workflows/user-requirements.md
Summary:
Extract technology-agnostic requirements focusing on WHAT and WHY, not HOW.
Step 2.1: Problem Statement
- What problem are we solving and why?
- Who experiences this problem?
- Current situation and pain points
Step 2.2: User Stories with Priorities
## User Story <N> - [Title] (Priority: P1/P2/P3)
**As a** [user type]
**I want to** [capability]
**So that** [value/benefit]
**Why P1/P2/P3**: [Rationale for priority]
**Independent Test**: [How to validate this story works standalone]
**Acceptance Scenarios**:
1. **Given** [state], **When** [action], **Then** [outcome]
Priority Levels:
- P1: Must-have for MVP (core value)
- P2: Important but not blocking
- P3: Nice-to-have (deferred)
Step 2.3: Functional Requirements
- Core capabilities (WHAT, not HOW)
- Data visibility and user interactions
- Constraints and boundaries
Step 2.4: Success Criteria
- User-centric metrics (measurable outcomes)
- Business metrics
- Adoption metrics
Why This Matters: Technology-agnostic requirements survive implementation changes and enable better tech stack decisions in planning phase.
Phase 3: Generate Specification with CoD^Σ Evidence
See: @.claude/skills/specify-feature/workflows/spec-generation.md
Summary:
Create specification document with intelligence evidence.
Step 3.1: Create Feature Directory
NEXT_NUM=$(printf "%03d" $(($(fd --type d --max-depth 1 '^[0-9]{3}-' specs/ 2>/dev/null | wc -l) + 1)))
FEATURE_NAME="<derived-from-user-description>"
mkdir -p specs/$NEXT_NUM-$FEATURE_NAME
Step 3.2: Create Git Branch
if git rev-parse --git-dir >/dev/null 2>&1; then
git checkout -b "$NEXT_NUM-$FEATURE_NAME"
fi
Step 3.3: Generate Specification Content
Use @.claude/templates/feature-spec.md with:
- YAML frontmatter (feature, created, status, priority)
- Problem statement, user stories, functional requirements, success criteria
- CoD^Σ Evidence Trace (intelligence queries, findings, assumptions, clarifications)
- Edge cases
Step 3.4: Save Specification
Write specs/$NEXT_NUM-$FEATURE_NAME/spec.md
Why This Matters: Evidence trace ensures all specifications have intelligence backing, not just assumptions.
Phase 4-5: Reporting and Automatic Workflow Progression
See: @.claude/skills/specify-feature/workflows/automation.md
Summary:
Report specification completion and automatically trigger implementation planning workflow.
Phase 4: Report to User
✓ Feature specification created: specs/<number>-<name>/spec.md
Intelligence Evidence: [queries + findings]
User Stories: [P1/P2/P3 counts]
Clarifications Needed: [0-3 markers]
**Automatic Next Steps**:
1. If clarifications needed: Use clarify-specification skill
2. Otherwise: **Automatically create implementation plan**
Invoking /plan command now...
Phase 5: Automatic Implementation Planning
If [NEEDS CLARIFICATION] markers exist:
- User must run clarify-specification skill
- After clarifications, re-run specify-feature skill
If NO clarifications:
- Automatically invoke /plan command via SlashCommand tool
- Workflow progresses: /plan → create-implementation-plan → generate-tasks → /audit
- User sees: spec.md → plan.md → research.md → data-model.md → tasks.md → audit report
Why This Matters: Fully automated workflow from specification to implementation-ready state. User only needs to run /feature and /implement.
Anti-Patterns to Avoid
See: @.claude/skills/specify-feature/references/specification-rules.md
Summary:
DO NOT:
- Include tech stack choices in specification
- Design architecture or data models
- Specify implementation details ("use React hooks", "create API endpoint")
- Create more than 3 [NEEDS CLARIFICATION] markers
- Write vague requirements ("system should be fast")
DO:
- Focus on user value and business requirements
- Make requirements testable and measurable
- Prioritize user stories (P1, P2, P3)
- Document evidence from intelligence queries
- Limit unknowns (max 3 [NEEDS CLARIFICATION])
Example Execution
See: @.claude/skills/specify-feature/examples/feature-creation-example.md
User Input: "I want to build a user authentication system with social login options"
Result:
- Quality assessment passed (7.2/10)
- Intelligence queries executed
- Specification created: specs/004-auth-social-login/spec.md
- Automatic planning triggered
- Files created: spec.md, plan.md, research.md, data-model.md, tasks.md
- Audit passed
- Ready for /implement
Prerequisites
Before using this skill:
- ✅ Git repository initialized
- ✅ project-intel.mjs exists and is executable
- ✅ PROJECT_INDEX.json exists (auto-generated)
- ⚠️ Optional: product.md exists (for product-aligned features)
Dependencies
Depends On:
- None (this skill is the entry point to SDD workflow)
Integrates With:
- clarify-specification skill: Use after this skill if ambiguities exist
- create-implementation-plan skill: Use after this skill (auto-invoked via /plan)
Tool Dependencies:
- fd (file discovery for feature numbering)
- git (branch creation, feature isolation)
- project-intel.mjs (pattern discovery)
Next Steps
After specification completes, automatic workflow progression:
Automatic Chain (no manual intervention needed):
specify-feature (creates spec.md)
↓ (auto-invokes /plan)
create-implementation-plan (creates plan.md, research.md, data-model.md)
↓ (auto-invokes generate-tasks)
generate-tasks (creates tasks.md)
↓ (auto-invokes /audit)
/audit (validates consistency)
↓ (if PASS)
Ready for /implement
User Action Required:
- If audit PASS: Run /implement plan.md to begin implementation
- If audit FAIL: Fix CRITICAL issues, then re-run (audit re-validates automatically)
- If ambiguities found: clarify-specification skill may be invoked during workflow
Commands:
- /plan spec.md - Automatically invoked after spec creation
- /implement plan.md - User runs after audit passes
Agent Integration
This skill orchestrates agent delegation through the automatic workflow chain.
Implementation Planning Agent
When: Automatically after spec.md is created (via /plan invocation)
Agent: implementation-planner
Delegation Method: The /plan slash command invokes the create-implementation-plan skill, which the implementation-planner agent executes.
What the Planner Receives:
- spec.md (technology-agnostic specification)
- Constitution requirements (Article IV compliance)
- Project intelligence context (existing patterns via project-intel.mjs)
What the Planner Returns:
- plan.md (implementation plan with tasks and ACs)
- research.md (technical research and decisions)
- data-model.md (database/state schema)
Task Tool Usage (Indirect)
This skill does NOT directly use the Task tool. Instead:
specify-feature skill
↓ invokes
/plan command (SlashCommand tool)
↓ expands to
create-implementation-plan skill
↓ executed by
implementation-planner agent (isolated context)
Why This Design:
- Slash commands provide consistent user interface
- Skills provide reusable workflows
- Agents provide isolated context execution
- Separation of concerns: specify-feature focuses on WHAT/WHY, planner handles HOW
Expected Workflow
- This skill completes: spec.md created with all requirements
- Automatic /plan invocation: SlashCommand tool runs
/plan spec.md - Planner agent engaged: Receives spec, constitution, intelligence context
- Planning artifacts created: plan.md, research.md, data-model.md generated
- Automatic task generation: generate-tasks skill creates tasks.md
- Automatic audit: /audit validates consistency
- Ready for implementation: User runs
/implement plan.mdif audit passes
Failure Modes
Common Failures & Solutions
1. Feature auto-numbering fails
- Symptom: Cannot determine next feature number
- Solution: Create specs/ directory: mkdir -p specs/
- Workaround: Manually specify feature number (e.g., 001-feature-name)
2. Intelligence queries return no results
- Symptom: No existing patterns found
- Solution: This is normal for first features; continue without pattern evidence
- Note: Intelligence is opportunistic, not required
3. Specification too technical
- Symptom: Spec includes implementation details (React, PostgreSQL, etc.)
- Solution: Re-run skill with explicit "WHAT/WHY only, no HOW" instruction
- Prevention: Review @constitution.md Article IV (Specification-First)
4. Requirements unclear or incomplete
- Symptom: [NEEDS CLARIFICATION] markers in spec
- Solution: clarify-specification skill will be invoked automatically
- Action: Answer max 5 structured questions to resolve ambiguities
5. Git branch creation fails
- Symptom: Cannot create feature branch
- Solution: Commit current changes or stash them first
- Command: git stash && git checkout -b <feature-branch>
6. Duplicate feature numbers
- Symptom: Feature directory already exists
- Solution: Intelligence detected wrong next number; manually increment
- Prevention: Ensure consistent ###-name branch naming
Related Skills & Commands
Direct Integration:
- clarify-specification skill - Invoked when ambiguities detected
- create-implementation-plan skill - Automatically invoked via /plan after spec
- /feature command - User-facing command that invokes this skill
Workflow Context:
- Position: Entry point to SDD workflow (Phase 1)
- Triggers: User describes feature idea, mentions "I want to build", "implement", "create"
- Output: spec.md in specs/###-feature-name/ directory
- Next: Automatic progression to /plan → /tasks → /audit → ready for /implement
Skill Version: 1.2.0
Last Updated: 2025-10-23
Change Log:
- v1.2.0 (2025-10-23): Refactored to progressive disclosure pattern (<500 lines)
- v1.1.0 (2025-10-23): Added Phase 0 Pre-Specification Quality Gate
- v1.0.0 (2025-10-22): Initial version with cross-skill references
