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

name, description, usage, argument-hint

name	description	usage	argument-hint
breakdown	Intelligent task decomposition with context-aware subtask generation	/task:breakdown <task-id>	task-id

Task Breakdown Command (/task:breakdown)

Overview

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

Core Principles

Task System: @~/.claude/workflows/workflow-architecture.md 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

Proceed with breakdown? (y/n): y

✅ 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 → @general-purpose (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

See @~/.claude/workflows/workflow-architecture.md for:

• 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.

Related Commands

• /task:create - Create new tasks
• /task:execute - Execute subtasks
• /workflow:status - View task hierarchy
• /workflow:plan - Plan within 10-task limit

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