try-claudekit/.claude/commands/spec/decompose.md

description, category, allowed-tools, argument-hint

description	category	allowed-tools	argument-hint
Break down a validated specification into actionable implementation tasks	validation	Read, Task, Write, TodoWrite, Bash(mkdir:*), Bash(cat:*), Bash(grep:*), Bash(echo:*), Bash(basename:*), Bash(date:*), Bash(claudekit:status stm), Bash(stm:*)	<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, target: string, backup: boolean): Promise<void>
   - setExecutablePermission(filePath: string): Promise<void> - chmod 755
   - needsUpdate(source: string, target: string): Promise<boolean> - SHA-256 comparison
   - getFileHash(filePath: string): Promise<string> - SHA-256 hash generation
   
   **Implementation example from spec**:
   ```typescript
   async function needsUpdate(source: string, target: string): Promise<boolean> {
     if (!await fs.pathExists(target)) return true;
   
     const sourceHash = await getFileHash(source);
     const targetHash = await getFileHash(target);
   
     return sourceHash !== targetHash;
   }
   

   Acceptance Criteria:

   • All file operations handle Unix paths correctly
   • SHA-256 based idempotency checking implemented
   • Backup functionality creates timestamped backups
   • Executable permissions set correctly for hooks (755)
   • Path validation prevents directory traversal
   • Tests: All operations work on macOS/Linux with proper error handling

5. Create Task Management Entries:

   🚨 STOP AND READ: Common Mistake vs Correct Approach

   ❌ WRONG - What NOT to do:

   stm add "[P1.3] Implement common hook utilities" \
     --description "Create shared utilities module for all hooks" \
     --details "Create cli/hooks/utils.ts with readStdin() with 1-second timeout, findProjectRoot() using git rev-parse, detectPackageManager() checking lock files" \
     --validation "readStdin with timeout. Project root discovery. Package manager detection."
   

   ✅ CORRECT - What you MUST do:

   # For each task in the breakdown, find the corresponding section and COPY ALL its content
   # Use temporary files for large content to preserve formatting
   
   cat > /tmp/task-details.txt << 'EOF'
   Create cli/hooks/utils.ts with the following implementations:
   
   ```typescript
   import { exec } from 'child_process';
   import { promisify } from 'util';
   import * as fs from 'fs-extra';
   import * as path from 'path';
   
   const execAsync = promisify(exec);
   
   // Standard input reader
   export async function readStdin(): Promise<string> {
     return new Promise((resolve) => {
       let data = '';
       process.stdin.on('data', chunk => data += chunk);
       process.stdin.on('end', () => resolve(data));
       setTimeout(() => resolve(''), 1000); // Timeout fallback
     });
   }
   
   // Project root discovery
   export async function findProjectRoot(startDir: string = process.cwd()): Promise<string> {
     try {
       const { stdout } = await execAsync('git rev-parse --show-toplevel', { cwd: startDir });
       return stdout.trim();
     } catch {
       return process.cwd();
     }
   }
   
   // [Include ALL other functions from the task breakdown...]
   

   Technical Requirements:

   • Standard input reader with timeout
   • Project root discovery using git
   • Package manager detection (npm/yarn/pnpm)
   • Command execution wrapper
   • Error formatting helper
   • Tool availability checker EOF

   stm add "[P1.3] Implement common hook utilities"
   --description "Create shared utilities module for all hooks with stdin reader, project root discovery, package manager detection, command execution wrapper, error formatting, and tool availability checking"
   --details "$(cat /tmp/task-details.txt)"
   --validation "readStdin with 1-second timeout. Project root discovery via git. Package manager detection for npm/yarn/pnpm. Command execution with timeout and output capture. Error formatting follows BLOCKED: pattern. Tool availability checker works."
   --tags "phase1,infrastructure,utilities"

   rm /tmp/task-details.txt

   
   **Remember**: The task breakdown document you created has ALL the implementation details. Your job is to COPY those details into STM, not summarize them!
   
   ```bash
   # Example: Creating a task with complete specification details
   
   # Method 1: Using heredocs for multi-line content
   stm add "Implement auto-checkpoint hook logic" \
     --description "Build the complete auto-checkpoint functionality with git integration to create timestamped git stashes on Stop events" \
     --details "$(cat <<'EOF'
   Technical Requirements:
   - Check if current directory is git repository using git status
   - Detect uncommitted changes using git status --porcelain
   - Create timestamped stash with configurable prefix from config
   - Apply stash to restore working directory after creation
   - Handle exit codes properly (0 for success, 1 for errors)
   
   Implementation from specification:
   ```typescript
   const hookName = process.argv[2];
   if (hookName !== 'auto-checkpoint') {
     console.error(`Unknown hook: ${hookName}`);
     process.exit(1);
   }
   
   const hookConfig = config.hooks?.['auto-checkpoint'] || {};
   const prefix = hookConfig.prefix || 'claude';
   
   const gitStatus = spawn('git', ['status', '--porcelain'], {
     stdio: ['ignore', 'pipe', 'pipe']
   });
   
   let stdout = '';
   gitStatus.stdout.on('data', (data) => stdout += data);
   
   gitStatus.on('close', (code) => {
     if (code !== 0) {
       console.log('Not a git repository, skipping checkpoint');
       process.exit(0);
     }
   
     if (!stdout.trim()) {
       console.log('No changes to checkpoint');
       process.exit(0);
     }
   
     const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
     const message = `${prefix}-checkpoint-${timestamp}`;
   
     const stash = spawn('git', ['stash', 'push', '-m', message], {
       stdio: ['ignore', 'pipe', 'pipe']
     });
   
     stash.on('close', (stashCode) => {
       if (stashCode !== 0) {
         console.error('Failed to create checkpoint');
         process.exit(1);
       }
   
       spawn('git', ['stash', 'apply'], {
         stdio: 'ignore'
       }).on('close', () => {
         console.log(`✅ Checkpoint created: ${message}`);
         process.exit(0);
       });
     });
   });
   

   Key implementation notes:

   • Use child_process.spawn for git commands
   • Capture stdout to check for changes
   • Generate ISO timestamp and sanitize for git message
   • Chain git stash push and apply operations EOF )"
     --validation "$(cat <<'EOF'
   • Correctly identifies git repositories
   • Detects uncommitted changes using git status --porcelain
   • Creates checkpoint with format: ${prefix}-checkpoint-${timestamp}
   • Restores working directory after stash
   • Exits with code 0 on success, 1 on error
   • Respects configured prefix from .claudekit/config.json
   • Handles missing config file gracefully

   Test scenarios:

   1. Run in non-git directory - should exit 0
   2. Run with no changes - should exit 0
   3. Run with changes - should create checkpoint
   4. Run with custom config - should use custom prefix EOF )"
      --tags "phase2,core,high-priority,large"
      --status pending
      --deps "35,36"

   Method 2: Using temporary files for very large content

   cat > /tmp/stm-details.txt << 'EOF' [Full technical requirements and implementation details from spec...] EOF

   cat > /tmp/stm-validation.txt << 'EOF' [Complete acceptance criteria and test scenarios...] EOF

   stm add "Task title"
   --description "Brief what and why"
   --details "$(cat /tmp/stm-details.txt)"
   --validation "$(cat /tmp/stm-validation.txt)"
   --tags "appropriate,tags"
   --status pending

   rm /tmp/stm-details.txt /tmp/stm-validation.txt

   
   **Important STM field usage**:
   - `--description`: Brief what & why (1-2 sentences max)
   - `--details`: Complete technical implementation including:
     - All technical requirements from spec
     - Full code examples with proper formatting (COPY from breakdown, don't summarize!)
     - Implementation steps and notes
     - Architecture decisions
     - **MUST be self-contained** - someone should be able to implement the task without seeing the original spec
   - `--validation`: Complete acceptance criteria including:
     - All test scenarios
     - Success/failure conditions
     - Edge cases to verify
   
   ## Content Size Guidelines
   
   - **Small tasks (< 20 lines)**: Can use heredocs directly in command
   - **Medium tasks (20-200 lines)**: Use temporary files to preserve formatting
   - **Large tasks (> 200 lines)**: Always use temporary files
   - **Tasks with code blocks**: MUST use heredocs or files (never inline)
   
   Example for medium/large content:
   ```bash
   # Extract the full implementation from your task breakdown
   cat > /tmp/stm-task-details.txt << 'EOF'
   [PASTE THE ENTIRE "Technical Requirements" and "Implementation" sections from the task breakdown]
   [Include ALL code blocks with proper formatting]
   [Include ALL technical notes and comments]
   EOF
   
   cat > /tmp/stm-task-validation.txt << 'EOF'
   [PASTE THE ENTIRE "Acceptance Criteria" section]
   [Include ALL test scenarios]
   EOF
   
   stm add "[Task Title]" \
     --description "[One line summary]" \
     --details "$(cat /tmp/stm-task-details.txt)" \
     --validation "$(cat /tmp/stm-task-validation.txt)" \
     --tags "appropriate,tags" \
     --deps "1,2,3"
   
   rm /tmp/stm-task-*.txt
   

   If STM is not available, use TodoWrite:

   [
     {
       id: "1",
       content: "Phase 1: Set up TypeScript project structure",
       status: "pending",
       priority: "high"
     },
     {
       id: "2",
       content: "Phase 1: Configure build system with esbuild",
       status: "pending",
       priority: "high"
     },
     // ... additional tasks
   ]
   

6. Save Task Breakdown:

   • Save the detailed task breakdown document to specs/[spec-name]-tasks.md
   • Create tasks in STM or TodoWrite for immediate tracking
   • Generate a summary report showing:
     • Total number of tasks
     • Breakdown by phase
     • Parallel execution opportunities
     • Task management system used (STM or TodoWrite)

Output Format

Task Breakdown Document

The generated markdown file includes:

• Executive summary
• Phase-by-phase task breakdown
• Dependency graph
• Risk assessment
• Execution strategy

Task Management Integration

Tasks are immediately available in STM (if installed) or TodoWrite for:

• Progress tracking
• Status updates
• Blocking issue identification
• Parallel work coordination
• Dependency tracking (STM only)
• Persistent storage across sessions (STM only)

Summary Report

Displays:

• Total tasks created
• Tasks per phase
• Critical path identification
• Recommended execution order

Usage Examples

# Decompose a feature specification
/spec:decompose specs/feat-user-authentication.md

# Decompose a system enhancement spec
/spec:decompose specs/feat-api-rate-limiting.md

Success Criteria

The decomposition is complete when:

• ✅ Task breakdown document is saved to specs directory
• ✅ All tasks are created in STM (if available) or TodoWrite for tracking
• ✅ Tasks preserve ALL implementation details from the spec including:
  • Complete code blocks and examples (not summarized)
  • Full technical requirements and specifications
  • Detailed step-by-step implementation instructions
  • All configuration examples
  • Complete acceptance criteria with test scenarios
• ✅ Foundation tasks are identified and prioritized
• ✅ Dependencies between tasks are clearly documented
• ✅ All tasks include testing requirements
• ✅ Parallel execution opportunities are identified
• ✅ STM tasks use all three fields properly:
  • --description: Brief what & why (1-2 sentences)
  • --details: Complete technical implementation from spec (ACTUAL CODE, not references)
  • --validation: Full acceptance criteria and test scenarios
• ✅ Quality check passed: Running stm show [any-task-id] displays full code implementations
• ✅ No summary phrases: Tasks don't contain "as specified", "from spec", or similar references

Post-Creation Validation

After creating STM tasks, perform these checks:

1. Sample Task Review:

   # Pick a random task and check it has full implementation
   stm show [task-id] | grep -E "(as specified|from spec|see specification)"
   # Should return NO matches - if it does, the task is incomplete
   

2. Content Length Check:

   # Implementation tasks should have substantial details
   stm list --format json | jq '.[] | select(.details | length < 500) | {id, title}'
   # Review any tasks with very short details - they likely need more content
   

3. Code Block Verification:

   # Check that tasks contain actual code blocks
   stm grep "```" | wc -l
   # Should show many matches for tasks with code implementations
   

Integration with Other Commands

• Prerequisites: Run /spec:validate first to ensure spec quality
• Next step: Use /spec:execute to implement the decomposed tasks
• Progress tracking:
  • With STM: stm list --pretty or stm list --status pending
  • With TodoWrite: Monitor task completion in session
• Quality checks: Run /validate-and-fix after implementation

Best Practices

1. Task Granularity: Keep tasks focused on single objectives
2. Dependencies: Clearly identify blocking vs parallel work
3. Testing: Include test tasks for each component
4. Documentation: Add documentation tasks alongside implementation
5. Phases: Group related tasks into logical phases