spec-to-plan

name

spec-to-plan

description

Transform project descriptions and feature requests into comprehensive specifications and actionable task lists. Use when the user wants to: (1) Create a specification from a project/feature description, (2) Generate a detailed plan with task breakdown, (3) Clarify requirements before implementation, (4) Convert ideas into structured development plans with progress tracking. Works with or without existing codebase files.

Spec-to-Plan Skill

This skill guides the process of transforming project descriptions into clear specifications and actionable task lists for developers.

Process Overview

The skill follows a five-phase workflow:

1. Create Initial Specification - Analyze the feature/project description
2. Clarify Questions - Identify and resolve all ambiguities
3. Generate Markdown Spec - Produce detailed specification document (presented as spec.md in chat)
4. Create Comprehensive Todo - Break down into implementable tasks
5. Output Plan Markdown - Generate final plan.md with progress tracking (presented in chat)

Final deliverables: Both specification and plan content are provided as markdown in the conversation.

Phase 1: Initial Specification

Load the prompt template from references/phase1_spec_prompt.md and fill in the feature description provided by the user.

Key principles:

• If files are provided, analyze the codebase thoroughly
• If no files, work from the task description or ask for detailed project description
• Identify dependencies, structure, and integration points
• Note edge cases (within reason - ask about scope depth)
• List ALL unclear or ambiguous points

Do NOT implement yet - only analyze and prepare questions.

Phase 2: Clarify Questions

Ask all clarification questions at once. After receiving answers:

• If more questions persist, ask them
• Continue until no ambiguities remain
• Do NOT assume any requirements beyond explicitly described details

Scope control:

• Ask the user about desired depth and scope when uncertain
• Avoid going overboard with edge cases unless specifically requested
• Focus on what's explicitly needed

Phase 3: Generate Markdown Spec

After all questions are answered, create a comprehensive specification document and present it in the chat:

Content requirements:

• No specific template required (flexible format)
• Should be clear, detailed, and implementation-ready
• Include all decisions and clarifications from the Q&A phase
• Document the full feature/project specification

Output:

• Present the complete spec.md content directly in the chat
• Use a clear header to indicate this is the specification document

Phase 4: Create Comprehensive Todo

Load the prompt template from references/phase2_plan_prompt.md.

Generate a detailed task breakdown that includes:

• Status tracking with emojis (🟩 Done, 🟨 In Progress, 🟥 To Do)
• Overall progress percentage at the top
• Confirmed decisions section
• Modular, minimal steps
• Important implementation details
• File-level changes (Add/Modify/Keep sections)
• Progress calculations

Critical: Do NOT add extra scope or unnecessary complexity beyond what was explicitly clarified.

Phase 5: Output Plan Markdown

Create the final plan.md content and present it in the chat:

Content requirements:

• Clear structure following the template in phase2_plan_prompt.md
• Checkbox tasks with status emojis
• Dynamic progress tracking
• Implementation details section
• File changes section listing specific files and modifications needed

Output:

• Present the complete plan.md content directly in the chat
• Use a clear header to indicate this is the implementation plan

Both the specification and plan are provided as markdown content in the conversation.

Workflow Tips

When to analyze codebase:

• If user provides files → analyze them thoroughly
• If no files → work from description or ask for project details

Question iteration:

• Ask comprehensive questions in each round
• Wait for all answers before proceeding
• Continue asking until complete clarity is achieved

Scope management:

• Always ask about desired depth when uncertain
• Keep steps elegant and minimal
• Ensure seamless integration with existing codebase

Output quality:

• Plans should lead to simple, elegant, minimal code
• No extra complexity beyond discussed requirements
• All steps should be modular and implementable

Reference Files

• references/phase1_spec_prompt.md - Initial specification prompt template
• references/phase2_plan_prompt.md - Plan generation prompt with examples