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:

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

1. 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

1. 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

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

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

1. 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

1. Define milestones:

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

1. 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

1. Write .claude/steering/:

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

1. Write .claude/spec/tasks/:

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

1. 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

Claude: "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](questions.md). For example completed specs, see [examples.md](examples.md).