/decompose

description: Break down a validated specification into actionable implementation tasks
category: validation
allowed-tools: Read, Task, Write, TodoWrite, Bash(mkdir:*), Bash(cat:*), Bash(grep:*), Bash(echo:*), Bash(basename:*), Bash(date:*), Bash(claudekit:status stm), Bash(stm:*)
argument-hint: "<path-to-spec-file>"

Decompose Specification into Tasks

Decompose the specification at: $ARGUMENTS

Process Overview

This command takes a validated specification and breaks it down into: 1. Clear, actionable tasks with dependencies 2. Implementation phases and milestones 3. Testing and validation requirements 4. Documentation needs

!claudekit status stm

⚠️ CRITICAL: Content Preservation Requirements

**THIS IS THE MOST IMPORTANT PART**: When creating STM tasks, you MUST copy ALL content from the task breakdown into the STM tasks. Do NOT summarize or reference the spec - include the ACTUAL CODE and details.

Pre-Flight Checklist

Before creating any STM tasks, confirm your understanding:

• [ ] I will NOT write summaries like "Create X as specified in spec"
• [ ] I will COPY all code blocks from the task breakdown into STM --details
• [ ] I will USE heredocs or temp files for multi-line content
• [ ] I will INCLUDE complete implementations, not references
• [ ] Each STM task will be self-contained with ALL details from the breakdown

**If you find yourself typing phrases like "as specified", "from spec", or "see specification" - STOP and copy the actual content instead!**

Instructions for Claude:

0. **Task Management System**:

• Check the STM_STATUS output above
• If status is "Available but not initialized", run: `stm init`
• If status is "Available and initialized", use STM for task management
• If status is "Not installed", fall back to TodoWrite

1. **Read and Validate Specification**:

• Read the specified spec file
• Verify it's a valid specification (has expected sections)
• Extract implementation phases and technical details

2. **Analyze Specification Components**:

• Identify major features and components
• Extract technical requirements
• Note dependencies between components
• Identify testing requirements
• Document success criteria

3. **Create Task Breakdown**:

Break down the specification into concrete, actionable tasks.

Key principles:

• Each task should have a single, clear objective
• **PRESERVE ALL CONTENT**: Copy implementation details, code blocks, and examples verbatim from the spec
• Define clear acceptance criteria with specific test scenarios
• Include tests as part of each task
• Document dependencies between tasks
• Write meaningful tests that can fail to reveal real issues
• Follow project principle: "When tests fail, fix the code, not the test"
• Create foundation tasks first, then build features on top
• Each task should be self-contained with all necessary details

**CRITICAL REQUIREMENT**: When creating tasks, you MUST preserve:

• Complete code examples (including full functions, not just snippets)
• All technical requirements and specifications
• Detailed implementation steps
• Configuration examples
• Error handling requirements
• All acceptance criteria and test scenarios

Think of each task as a complete mini-specification that contains everything needed to implement it without referring back to the original spec.

📋 THE TWO-STEP PROCESS YOU MUST FOLLOW:

**Step 1**: Create the task breakdown DOCUMENT with all details **Step 2**: Copy those SAME details into STM tasks

The task breakdown document is NOT just for reference - it's the SOURCE for your STM task content!

Task structure:

• Foundation tasks: Core infrastructure (database, frameworks, testing setup)
• Feature tasks: Complete vertical slices including all layers
• Testing tasks: Unit, integration, and E2E tests
• Documentation tasks: API docs, user guides, code comments

4. **Generate Task Document**:

Create a comprehensive task breakdown document:

   # Task Breakdown: [Specification Name]
   Generated: [Date]
   Source: [spec-file]
   
   ## Overview
   [Brief summary of what's being built]
   
   ## Phase 1: Foundation
   
   ### Task 1.1: [Task Title]
   **Description**: One-line summary of what needs to be done
   **Size**: Small/Medium/Large
   **Priority**: High/Medium/Low
   **Dependencies**: None
   **Can run parallel with**: Task 1.2, 1.3
   
   **Technical Requirements**:
   - [All technical details from spec]
   - [Specific library versions]
   - [Code examples from spec]
   
   **Implementation Steps**:
   1. [Detailed step from spec]
   2. [Another step with specifics]
   3. [Continue with all steps]
   
   **Acceptance Criteria**:
   - [ ] [Specific criteria from spec]
   - [ ] Tests written and passing
   - [ ] [Additional criteria]
   
   ## Phase 2: Core Features
   [Continue pattern...]

Example task breakdown:

   ### Task 2.3: Implement file system operations with backup support
   **Description**: Build filesystem.ts module with Unix-focused operations and backup support
   **Size**: Large
   **Priority**: High
   **Dependencies**: Task 1.1 (TypeScript setup), Task 1.2 (Project structure)
   **Can run parallel with**: Task 2.4 (Config module)
   
   **Source**: specs/feat-modernize-setup-installer.md
   
   **Technical Requirements**:
   - Path validation: Basic checks for reasonable paths
   - Permission checks: Verify write permissions before operations
   - Backup creation: Simple backup before overwriting files
   - Error handling: Graceful failure with helpful messages
   - Unix path handling: Use path.join, os.homedir(), standard Unix permissions
   
   **Functions to implement**:
   - validateProjectPath(input: string): boolean - Basic path validation
   - ensureDirectoryExists(path: string): Promise<void>
   - copyFileWithBackup(source: string, targ