Claude-Code-Workflow/.claude/commands/task/breakdown.md

name, description, argument-hint

name	description	argument-hint
breakdown	Decompose complex task into subtasks with dependency mapping, creates child task JSONs with parent references and execution order	[-y|--yes] task-id

Auto Mode

When --yes or -y: Auto-confirm breakdown, use recommended subtask structure.

Task Breakdown Command (/task:breakdown)

Overview

Breaks down complex tasks into executable subtasks with context inheritance and agent assignment.

Core Principles

File Cohesion: Related files must stay in same task 10-Task Limit: Total tasks cannot exceed 10 (triggers re-scoping)

Core Features

CRITICAL: Manual breakdown with safety controls to prevent file conflicts and task limit violations.

Breakdown Process

1. Session Check: Verify active session contains parent task
2. Task Validation: Ensure parent is pending status
3. 10-Task Limit Check: Verify breakdown won't exceed total limit
4. Manual Decomposition: User defines subtasks with validation
5. File Conflict Detection: Warn if same files appear in multiple subtasks
6. Similar Function Warning: Alert if subtasks have overlapping functionality
7. Context Distribution: Inherit parent requirements and scope
8. Agent Assignment: Auto-assign agents based on subtask type
9. TODO_LIST Update: Regenerate TODO_LIST.md with new structure

Breakdown Rules

• Only pending tasks can be broken down
• Manual breakdown only: Automated breakdown disabled to prevent violations
• Parent becomes container status (not executable)
• Subtasks use format: IMPL-N.M (max 2 levels)
• Context flows from parent to subtasks
• All relationships tracked in JSON
• 10-task limit enforced: Breakdown rejected if total would exceed 10 tasks
• File cohesion preserved: Same files cannot be split across subtasks

Usage

Basic Breakdown

/task:breakdown impl-1

Interactive process:

Task: Build authentication module
Current total tasks: 6/10

MANUAL BREAKDOWN REQUIRED
Define subtasks manually (remaining capacity: 4 tasks):

1. Enter subtask title: User authentication core
   Focus files: models/User.js, routes/auth.js, middleware/auth.js

2. Enter subtask title: OAuth integration
   Focus files: services/OAuthService.js, routes/oauth.js

FILE CONFLICT DETECTED:
   - routes/auth.js appears in multiple subtasks
   - Recommendation: Merge related authentication routes

SIMILAR FUNCTIONALITY WARNING:
   - "User authentication" and "OAuth integration" both handle auth
   - Consider combining into single task

# Use AskUserQuestion for confirmation
AskUserQuestion({
  questions: [{
    question: "File conflicts and/or similar functionality detected. How do you want to proceed?",
    header: "Confirm",
    options: [
      { label: "Proceed with breakdown", description: "Accept the risks and create the subtasks as defined." },
      { label: "Restart breakdown", description: "Discard current subtasks and start over." },
      { label: "Cancel breakdown", description: "Abort the operation and leave the parent task as is." }
    ],
    multiSelect: false
  }]
})

User selected: "Proceed with breakdown"

Task IMPL-1 broken down:
IMPL-1: Build authentication module (container)
  ├── IMPL-1.1: User authentication core -> @code-developer
  └── IMPL-1.2: OAuth integration -> @code-developer

Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md

Decomposition Logic

Agent Assignment

• Design/Planning → @planning-agent
• Implementation → @code-developer
• Testing → @code-developer (type: "test-gen")
• Test Validation → @test-fix-agent (type: "test-fix")
• Review → @universal-executor (optional)

Context Inheritance

• Subtasks inherit parent requirements
• Scope refined for specific subtask
• Implementation details distributed appropriately

Safety Controls

File Conflict Detection

Validates file cohesion across subtasks:

• Scans focus_paths in all subtasks
• Warns if same file appears in multiple subtasks
• Suggests merging subtasks with overlapping files
• Blocks breakdown if critical conflicts detected

Similar Functionality Detection

Prevents functional overlap:

• Analyzes subtask titles for similar keywords
• Warns about potential functional redundancy
• Suggests consolidation of related functionality
• Examples: "user auth" + "login system" → merge recommendation

10-Task Limit Enforcement

Hard limit compliance:

• Counts current total tasks in session
• Calculates breakdown impact on total
• Rejects breakdown if would exceed 10 tasks
• Suggests re-scoping if limit reached

Manual Control Requirements

User-driven breakdown only:

• No automatic subtask generation
• User must define each subtask title and scope
• Real-time validation during input
• Confirmation required before execution

Implementation Details

• Complete task JSON schema
• Implementation field structure
• Context inheritance rules
• Agent assignment logic

Validation

Pre-breakdown Checks

1. Active session exists
2. Task found in session
3. Task status is pending
4. Not already broken down
5. 10-task limit compliance: Total tasks + new subtasks ≤ 10
6. Manual mode enabled: No automatic breakdown allowed

Post-breakdown Actions

1. Update parent to container status
2. Create subtask JSON files
3. Update parent subtasks list
4. Update session stats
5. Regenerate TODO_LIST.md with new hierarchy
6. Validate file paths in focus_paths
7. Update session task count

Examples

Basic Breakdown

/task:breakdown impl-1

impl-1: Build authentication (container)
  ├── impl-1.1: Design schema -> @planning-agent
  ├── impl-1.2: Implement logic + tests -> @code-developer
  └── impl-1.3: Execute & fix tests -> @test-fix-agent

Error Handling

# Task not found
Task IMPL-5 not found

# Already broken down
Task IMPL-1 already has subtasks

# Wrong status
Cannot breakdown completed task IMPL-2

# 10-task limit exceeded
Breakdown would exceed 10-task limit (current: 8, proposed: 4)
Suggestion: Re-scope project into smaller iterations

# File conflicts detected
File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2
Recommendation: Merge subtasks or redistribute files

# Similar functionality warning
Similar functions detected: "user login" and "authentication"
Consider consolidating related functionality

# Manual breakdown required
Automatic breakdown disabled. Use manual breakdown process.

System ensures: Manual breakdown control with file cohesion enforcement, similar functionality detection, and 10-task limit compliance