---

name: spec-flow:spec-create description: Create or update project specifications interactively through an interview process. Use when starting a new project, adding major features, or when the user asks to create a spec, plan a project, or define requirements. Guides through requirements gathering, architecture decisions, and task breakdown. allowed-tools: Read, Write, Edit, Glob, Grep

Spec Creator

Interactive workflow for creating comprehensive project specifications through structured interviews.

When Claude Should Use This Skill

• User says "create a spec" or "let's plan this project"
• User says "I need to define requirements" or "what should we build"
• User starts a new project and needs structure
• User says "help me think through this feature"
• After /spec-flow:init without --skip-interview

Arguments

Parse from conversation context:

• Project name (ask if not provided)
• Project type hints (CLI, web app, library, etc.)
• --from-readme - Seed from existing README.md
• --from-existing - Update existing spec

Interview Workflow

Phase 1: Discovery (Understanding What Exists)

1. Check for existing context:

   Copy- .claude/spec/SPEC.md (existing spec)
   - README.md (project description)
   - CLAUDE.md (project instructions)
   - package.json / go.mod / pyproject.toml (project type hints)
   

2. If existing spec found:

   • Ask: "I found an existing spec. Would you like to update it or start fresh?"
   • If update: Load existing requirements as context

3. If README found:

   • Extract project description, features mentioned
   • Use as seed for interview

Phase 2: Project Scope (The "What")

Ask these questions one at a time, building on answers:

Q1: Problem Statement

"What problem does this project solve? Who has this problem?"

Listen for: user types, pain points, current alternatives

Q2: Core Value

"If this project does ONE thing really well, what is it?"

Listen for: primary feature, key differentiator

Q3: Success Criteria

"How will you know when this is 'done enough' to use?"

Listen for: MVP scope, must-have vs nice-to-have

Q4: Scope Boundaries

"What is explicitly OUT of scope for this project?"

Listen for: features to avoid, complexity limits

Phase 3: Technical Context (The "How")

Q5: Technology Stack

"What language/framework are you using, or do you have preferences?"

If unsure, suggest based on project type:

• CLI tool: Go, Rust, Python
• Web app: TypeScript/React, Go, Python/Django
• Library: Match target ecosystem

Q6: Constraints

"Any technical constraints I should know about? (Performance requirements, integrations, compatibility, etc.)"

Listen for: existing systems, performance needs, deployment targets

Q7: Patterns

"Are there code patterns or architectural styles you prefer?"

Listen for: testing preferences, error handling, modularity

Phase 4: Requirements Synthesis

Based on interview answers:

1. Generate functional requirements (REQ-xxx):

   • Map each feature/capability to a requirement
   • Include acceptance criteria inline
   • Prioritize: Must-have first, then nice-to-have

2. Generate non-functional requirements (NFR-xxx):

   • Performance targets (if mentioned)
   • Security considerations
   • Compatibility requirements

3. Present for review:

   "Based on our conversation, here are the requirements I captured. Please review and let me know if anything is missing or incorrect."

Phase 5: Architecture & Milestones

1. Propose component structure:

   • Based on requirements and stack
   • Keep it minimal - avoid over-engineering

2. Define milestones:

   • Group requirements into logical phases
   • MVP first, then iterations
   • Each milestone should be independently valuable

3. Generate initial task breakdown:

   • Create task file per milestone
   • Tasks should be session-sized (< 1 hour of work)
   • Include file paths where known

Phase 6: Output Generation

1. Write .claude/spec/SPEC.md:

   • Use template structure
   • Fill in all sections from interview
   • Leave placeholders for unknown details

2. Write .claude/steering/:

   • product.md with vision and users
   • tech.md with stack and patterns
   • decisions.md with initial "chose X over Y" entries

3. Write .claude/spec/tasks/:

   • One file per milestone
   • Tasks with acceptance criteria
   • Dependencies noted

4. Present summary:

   "I've created the spec structure. Here's what was generated:

   • SPEC.md with N requirements
   • M milestone task files
   • Steering docs for ongoing context

   Run /spec-flow:status to see your project overview."

Interview Tips

• Ask one question at a time
• Acknowledge answers before moving on
• If answer is vague, ask a follow-up
• Offer examples when helpful
• Skip questions if answer is obvious from context
• Summarize understanding before generating

Example Interview Flow

CopyClaude: "What problem does this project solve? Who has this problem?"

User: "I want to build a CLI tool that helps me track time spent on projects"

Claude: "Got it - a time tracking CLI for personal productivity. If this tool
does ONE thing really well, what would that be?"

User: "Quick time entry - I want to log time without opening an app"

Claude: "Speed of entry is key. So something like `tt start project-name` to
begin tracking. How will you know when it's 'done enough' to use daily?"

User: "When I can start/stop timers and see a daily summary"

Claude: "So MVP is: start/stop timers + daily summary view. What's explicitly
OUT of scope? What should this NOT try to do?"

User: "No syncing to cloud services, no team features, no billing"

Claude: "Perfect - keeping it local and personal. What language are you
thinking? Given it's a CLI..."

User: "Go"

Claude: "Great choice for CLIs. Any specific patterns or constraints?"

User: "Just make it fast and simple"

Claude: "Based on our conversation, here are the requirements I captured:

**Functional:**
- [REQ-001] Start timer for a named project
- [REQ-002] Stop current timer
- [REQ-003] View daily time summary
- [REQ-004] Persist time entries locally

**Non-Functional:**
- [NFR-001] Sub-100ms command execution
- [NFR-002] Single binary, no dependencies

**Out of Scope:**
- Cloud sync, team features, billing integration

Does this capture it correctly?"

Reference Files

For question templates by project type, see questions.md. For example completed specs, see examples.md.