spec

Quick Reference

/spec "idea"               # Start interview from idea description
/spec @file.md             # Start interview from file content
/spec run @SPEC-*.md       # Execute tasks in specified SPEC file
/spec import @plan.md      # Import Claude Code plan file to SPEC format

Spec Skill - Requirements Refinement & Task Execution

Route to the appropriate mode based on $ARGUMENTS:

Mode Routing

1. Run Mode

Trigger: $ARGUMENTS starts with run Example: run @SPEC-user-auth.md Required: Must specify a SPEC file. If not provided, prompt user to specify one.

2. Import Mode

Trigger: $ARGUMENTS starts with import Example: import @plan.md Required: Must specify a plan file to import.

3. Interview Mode (Default)

Trigger: All other cases

• @file - Start from file content
• Plain text - Start from idea description

---

Mode 1: Interview Mode

Input Handling

• Idea mode: Use text from $ARGUMENTS directly
• File mode: Read file content as starting point

Interview Process

Conduct adaptive interviews using AskUserQuestion. No fixed rounds — continue until the user signals completion.

Core Principles:

• Ask 1-3 focused questions per round
• Dig deep rather than staying surface-level
• Challenge assumptions and explore alternatives
• Before each round, briefly summarize what has been collected so far

Topic Areas to Explore (adapt order and depth based on context):

• Problem definition and success criteria
• Target users and their needs
• Technical constraints and integration points
• User experience and interaction patterns
• Risks, tradeoffs, and scope boundaries
• Dependencies and open questions

Slug Generation

Generate a short English slug: lowercase, hyphen-separated, 2-4 words (e.g., user-auth, dark-mode, api-rate-limit).

Plan Mode Handling

If plan mode is currently active, call ExitPlanMode before generating the SPEC file. The spec interview process itself serves as the planning phase — the SPEC document is the deliverable, not a plan file.

Output File

Ensure directory exists, then generate SPEC-{slug}.md using the template in references/spec-template.md. Adapt sections based on the interview — omit sections that are not relevant, expand those that are.

---

Mode 2: Import Mode

Import a Claude Code plan file and convert it to SPEC format for subagent execution. This enables isolated execution of each task with fresh context, avoiding context window overflow.

Execution Flow

1. Read plan file — Parse the specified file
2. Extract content — Title from first heading, background from pre-task text, tasks from checkbox/numbered items
3. Generate slug — Derive from title or ask user
4. Convert to SPEC format — Create SPEC-{slug}.md with requirements, task list, and empty execution log
5. Save and confirm — Write to ./plans/SPEC-{slug}.md and show summary

Task Conversion Rules

Plan Format	SPEC Format
- [ ] Task	⬜ Pending
- [x] Task	✅ Completed
1. Task	⬜ Pending
Nested items	Merged into Notes column

---

Mode 3: Run Mode

Execute tasks sequentially using subagents. Main context handles scheduling and progress tracking only.

Execution Flow

Phase 1: Parse and Plan

1. Locate SPEC file — Must be specified in the command. If missing, prompt user.
2. Parse tasks — Extract all tasks, identify status (⬜/🔄/✅), count pending.
3. Display execution plan — Show task table with status. Ask user to confirm before proceeding.

Phase 2: Sequential Execution

For each pending task in order:

1. Update status — Change to 🔄, write file immediately.
2. Execute via subagent — Use Task tool with task description, acceptance criteria, and relevant spec context.
3. Handle result:
   • Success: Update to ✅, add timestamp, update progress count and last-updated
   • Failure: Keep as 🔄, stop execution immediately, display error report with recovery instructions
4. Report progress — Show completion status after each task.

Error Handling

On failure, stop and report: which task failed, error details, current progress, and how to retry (/spec run @SPEC-xxx.md resumes from the failed task).

---

Guidelines

File Handling

• If file exists, ask user: Overwrite / Use new slug / Cancel
• Auto-create directory if it doesn't exist
• Single SPEC file contains both requirements and tasks

Task Table Format

• Use table format for all tasks
• Status icons: ⬜ Pending | 🔄 In Progress | ✅ Completed
• Include acceptance criteria in Notes column