pm:epic-decompose

Prompt file imported from rafeekpro/telegram-chat-getter (.claude/commands/pm:epic-decompose.md). Fill in {{arguments}} before use. Copyright stays with the author.

Epic Decompose

Break epic into concrete, actionable tasks.

⚠️ IMPORTANT: This is a Claude Code command file, not a standalone script.

• Execute via Claude Code as: /pm:epic-decompose <feature_name>
• Do NOT run as: node .claude/scripts/pm/epic-decompose.js
• This command has no standalone script equivalent

Usage

Single Epic:

/pm:epic-decompose <feature_name> [--local]

Multi-Epic (decomposes ALL epics at once):

/pm:epic-decompose <feature_name> [--local]
# Example: /pm:epic-decompose ecommerce-platform --local
# This will automatically decompose ALL epics:
#   - 01-infrastructure
#   - 02-auth-backend
#   - 03-product-api
#   - etc.

Single Epic from Multi-Epic structure:

/pm:epic-decompose <feature_name>/<epic_folder> [--local]
# Example: /pm:epic-decompose ecommerce-platform/01-infrastructure --local

Flags

--local, -l : Use local mode (offline workflow) : Creates task files in .claude/epics/ directory structure : No GitHub/Azure synchronization : Task files remain local-only until manually synced : Ideal for offline work or projects without remote tracking

Example:

/pm:epic-decompose user-authentication --local

Required Documentation Access

MANDATORY: Before decomposing epics, query Context7 for best practices:

Documentation Queries:

• mcp://context7/agile/epic-decomposition - Epic breakdown best practices
• mcp://context7/agile/task-sizing - Task estimation and sizing
• mcp://context7/agile/user-stories - User story formats (INVEST criteria)
• mcp://context7/project-management/task-breakdown - Work breakdown structure

Why This is Required:

• Ensures tasks follow industry-standard decomposition patterns
• Applies current best practices for task sizing and dependencies
• Validates task structure against proven methodologies
• Prevents common anti-patterns in task breakdown

Required Rules

IMPORTANT: Before executing this command, read and follow:

• .claude/rules/datetime.md - For getting real current date/time

Agent Selection Strategy

Based on the PRD content and technical requirements, automatically determine which specialized agents should be assigned to tasks.

Step 1: Analyze PRD for Technology Stack

Read .claude/prds/{{arguments}}.md and identify:

• Programming languages mentioned (Python, JavaScript/TypeScript, Go, Bash, etc.)
• Frameworks required (React, FastAPI, Next.js, Express, etc.)
• Databases needed (PostgreSQL, MongoDB, Redis, etc.)
• Cloud platforms (AWS, Azure, GCP)
• Infrastructure tools (Docker, Kubernetes, Terraform)
• Testing requirements (unit, integration, E2E)
• CI/CD platforms (GitHub Actions, Azure DevOps, GitLab CI)

Step 2: Map Technologies to Specialized Agents

Programming Languages:

• Python → .claude/agents/languages/python-backend-engineer.md
• JavaScript/TypeScript/Node.js → .claude/agents/languages/nodejs-backend-engineer.md
• React → .claude/agents/frontend/react-frontend-engineer.md
• Bash/Shell scripting → .claude/agents/languages/bash-scripting-expert.md

Databases:

• PostgreSQL → .claude/agents/databases/postgresql-expert.md
• MongoDB → .claude/agents/databases/mongodb-expert.md
• Redis → .claude/agents/databases/redis-expert.md
• Cosmos DB → .claude/agents/databases/cosmosdb-expert.md

Cloud Platforms:

• AWS → .claude/agents/cloud/aws-cloud-architect.md
• Azure → .claude/agents/cloud/azure-cloud-architect.md
• GCP → .claude/agents/cloud/gcp-cloud-architect.md

Infrastructure & Containers:

• Docker → .claude/agents/containers/docker-containerization-expert.md
• Kubernetes → .claude/agents/orchestration/kubernetes-orchestrator.md
• Terraform → .claude/agents/infrastructure/terraform-infrastructure-expert.md

Testing:

• Unit/Integration tests → .claude/agents/core/test-runner.md
• Frontend E2E testing → .claude/agents/testing/frontend-testing-engineer.md
• E2E automation → .claude/agents/testing/e2e-test-engineer.md

DevOps & CI/CD:

• GitHub operations → .claude/agents/devops/github-operations-specialist.md
• Azure DevOps → .claude/agents/devops/azure-devops-specialist.md
• Observability → .claude/agents/devops/observability-engineer.md

Step 3: Document Agent Assignments in Epic Frontmatter

Add required_agents array to epic.md frontmatter:

---
name: user-authentication
prd: user-authentication
status: backlog
created: 2025-12-17T10:00:00Z
updated: 2025-12-17T10:00:00Z
required_agents:
  - path: .claude/agents/languages/python-backend-engineer.md
    role: API implementation
    tasks: [001, 002, 003]
  - path: .claude/agents/databases/postgresql-expert.md
    role: Database schema and migrations
    tasks: [004, 005]
  - path: .claude/agents/testing/frontend-testing-engineer.md
    role: Test suite development
    tasks: [006, 007]
  - path: .claude/agents/devops/github-operations-specialist.md
    role: CI/CD pipeline setup
    tasks: [008]
---

Step 4: Assign Agents to Individual Tasks

Each task file should include assigned_agent in frontmatter:

---
name: Implement JWT authentication endpoints
status: open
created: 2025-12-17T10:00:00Z
updated: 2025-12-17T10:00:00Z
assigned_agent: .claude/agents/languages/python-backend-engineer.md
agent_context:
  framework: fastapi
  auth_method: jwt
  libraries: [pyjwt, passlib]
github: [Will be updated when synced to GitHub]
depends_on: [004]  # Depends on user schema
parallel: true
conflicts_with: []
---

Benefits of Agent Assignment:

• ✅ Automatic selection of specialized agents based on technology
• ✅ Clear agent responsibilities per task
• ✅ Easier task assignment when starting work
• ✅ Better parallel execution planning with appropriate agents
• ✅ Consistent expertise application across similar tasks

Preflight Checklist

Before proceeding, complete these validation steps. Do not bother the user with preflight checks progress ("I'm not going to ..."). Just do them and move on.

1. Verify epic exists:

   • Check if .claude/epics/{{arguments}} directory exists
   • Check for either: a) Single epic: .claude/epics/{{arguments}}/epic.md exists b) Multiple epics: Subdirectories like .claude/epics/{{arguments}}/01-infrastructure/epic.md
   • If neither found, tell user: "❌ Epic not found: {{arguments}}. First create it with: /pm:prd-parse {{arguments}} or /pm:epic-split {{arguments}}"
   • Stop execution if no epics found

2. Detect epic structure:

   • If .claude/epics/{{arguments}}/epic.md exists → Single epic mode
   • If subdirectories with epic.md files exist → Multi-epic mode
   • Store the mode for later processing

3. Check for existing tasks:

   • For single epic: Check .claude/epics/{{arguments}}/ for numbered task files
   • For multi-epic: Check each subdirectory for numbered task files
   • If tasks exist, list them and ask: "⚠️ Found {count} existing tasks. Delete and recreate all tasks? (yes/no)"
   • Only proceed with explicit 'yes' confirmation
   • If user says no, suggest: "View existing tasks with: /pm:epic-show {{arguments}}"

4. Validate epic frontmatter:

   • For single epic: Verify .claude/epics/{{arguments}}/epic.md has valid frontmatter
   • For multi-epic: Verify each subdirectory's epic.md has valid frontmatter
   • If invalid, tell user which epic file has invalid frontmatter

5. Check epic status:

   • For each epic, check if status is already "completed"
   • If any epic is completed, warn user: "⚠️ Epic(s) marked as completed. Are you sure you want to decompose again?"

⚠️ TDD REMINDER

CRITICAL: All tasks MUST follow Test-Driven Development (TDD).

When creating tasks, ensure each task includes:

• TDD Requirements section (RED-GREEN-REFACTOR cycle)
• "Tests written FIRST" as first item in Definition of Done
• References to .claude/rules/tdd.enforcement.md

Every generated task file will remind developers to write tests first.

Instructions

You are decomposing epic(s) into specific, actionable tasks for: {{arguments}}

1. Determine Processing Mode

Single Epic Mode:

• Process .claude/epics/{{arguments}}/epic.md
• Create tasks in .claude/epics/{{arguments}}/

Multi-Epic Mode (from epic-split):

• Find all subdirectories in .claude/epics/{{arguments}}/
• Process each subdirectory's epic.md file separately
• Create tasks in each respective subdirectory
• Show progress for each epic being processed

2. Read the Epic(s)

• For single epic: Load from .claude/epics/{{arguments}}/epic.md
• For multi-epic: Load each .claude/epics/{{arguments}}/*/epic.md
• Understand the technical approach and requirements
• Review the task breakdown preview

3. Analyze PRD and Select Agents

IMPORTANT: Before creating tasks, determine which specialized agents should be used:

1. Read the PRD from .claude/prds/{{arguments}}.md (or linked PRD in epic frontmatter)

2. Identify Technology Stack:

   • Scan for programming languages (Python, JavaScript, Go, etc.)
   • Find frameworks (React, FastAPI, Django, Express, etc.)
   • Note databases (PostgreSQL, MongoDB, Redis, etc.)
   • Identify cloud platforms (AWS, Azure, GCP)
   • Check for infrastructure tools (Docker, K8s, Terraform)

3. Map to Specialized Agents using the Agent Selection Strategy section above:

   • Backend tasks → python-backend-engineer or nodejs-backend-engineer
   • Frontend tasks → react-frontend-engineer or javascript-frontend-engineer
   • Database tasks → postgresql-expert, mongodb-expert, or redis-expert
   • Cloud tasks → aws-cloud-architect, azure-cloud-architect, or gcp-cloud-architect
   • Container tasks → docker-containerization-expert
   • Orchestration → kubernetes-orchestrator
   • IaC tasks → terraform-infrastructure-expert
   • Testing → test-runner, frontend-testing-engineer, e2e-test-engineer
   • CI/CD → github-operations-specialist or azure-devops-specialist

4. Update Epic Frontmatter with required_agents array (see Agent Selection Strategy section)

5. Prepare Agent Assignments for each task to be created

Example:

Technology Stack Detected:
- Backend: Python + FastAPI
- Database: PostgreSQL
- Testing: pytest
- Deployment: Docker

Agent Mapping:
- Tasks 001-003 (API): python-backend-engineer
- Tasks 004-005 (Database): postgresql-expert
- Tasks 006-007 (Tests): test-runner
- Task 008 (Docker): docker-containerization-expert

4. Analyze for Parallel Creation

Determine if tasks can be created in parallel:

• If tasks are mostly independent: Create in parallel using Task agents
• If tasks have complex dependencies: Create sequentially
• For best results: Group independent tasks for parallel creation

5. Parallel Task Creation (When Possible)

If tasks can be created in parallel, spawn sub-agents.

IMPORTANT: Do NOT use generic "general-purpose" agents. Task creation should be done directly by Claude Code, not delegated to sub-agents, as it requires careful analysis of PRD, agent selection, and proper frontmatter generation.

Task Creation Process:

1. For each task, determine the appropriate assigned_agent based on PRD analysis
2. Create task file with complete frontmatter including agent assignment
3. Generate proper task content with all required sections
4. Ensure sequential numbering (001.md, 002.md, etc.)

Example Task Creation:

Creating task 001 (API endpoint):
- assigned_agent: .claude/agents/languages/python-backend-engineer.md
- agent_context: {framework: "fastapi", auth: "jwt"}
- File: .claude/epics/{{arguments}}/001.md
✓ Created

Creating task 002 (Database schema):
- assigned_agent: .claude/agents/databases/postgresql-expert.md
- agent_context: {orm: "sqlalchemy", migrations: "alembic"}
- File: .claude/epics/{{arguments}}/002.md
✓ Created

4. Task File Format with Frontmatter

For each task, create a file with this exact structure:

---
name: [Task Title]
status: open
created: [Current ISO date/time]
updated: [Current ISO date/time]
assigned_agent: .claude/agents/{category}/{agent-name}.md  # Specialized agent for this task
agent_context:  # Optional: Agent-specific configuration
  framework: [framework_name]
  language: [language_name]
  approach: [implementation_approach]
github: [Will be updated when synced to GitHub]
depends_on: []  # List of task numbers this depends on, e.g., [001, 002]
parallel: true  # Can this run in parallel with other tasks?
conflicts_with: []  # Tasks that modify same files, e.g., [003, 004]
---

# Task: [Task Title]

## Description
Clear, concise description of what needs to be done

## ⚠️ TDD Requirements
**This project uses Test-Driven Development. You MUST:**
1. 🔴 RED: Write failing test first
2. 🟢 GREEN: Write minimal code to make test pass
3. 🔵 REFACTOR: Clean up code while keeping tests green

See `.claude/rules/tdd.enforcement.md` for complete requirements.

## Acceptance Criteria
- [ ] Specific criterion 1
- [ ] Specific criterion 2
- [ ] Specific criterion 3

## Technical Details
- Implementation approach
- Key considerations
- Code locations/files affected

## Dependencies
- [ ] Task/Issue dependencies
- [ ] External dependencies

## Effort Estimate
- Size: XS/S/M/L/XL
- Hours: estimated hours
- Parallel: true/false (can run in parallel with other tasks)

## Definition of Done
- [ ] Tests written FIRST (RED phase)
- [ ] Code implemented (GREEN phase)
- [ ] Code refactored (REFACTOR phase)
- [ ] All tests passing
- [ ] Documentation updated
- [ ] Code reviewed
- [ ] Deployed to staging

3. Task Naming Convention

For Single Epic: Save tasks as: .claude/epics/{{arguments}}/{task_number}.md

For Multi-Epic: Save tasks as: .claude/epics/{{arguments}}/{epic_folder}/{task_number}.md Example: .claude/epics/ecommerce/01-infrastructure/001.md

• Use sequential numbering: 001.md, 002.md, etc.
• Keep task titles short but descriptive
• Each epic gets its own task number sequence

4. Frontmatter Guidelines

• name: Use a descriptive task title (without "Task:" prefix)
• status: Always start with "open" for new tasks
• created: Get REAL current datetime by running: date -u +"%Y-%m-%dT%H:%M:%SZ"
• updated: Use the same real datetime as created for new tasks
• assigned_agent: Path to specialized agent file (e.g., .claude/agents/languages/python-backend-engineer.md)
  • Select based on technology stack from PRD
  • Use most specific agent for the task type
  • See Agent Selection Strategy section for mapping
• agent_context: Optional object with agent-specific configuration
  • framework: Specific framework being used (e.g., "fastapi", "react", "express")
  • language: Programming language if multiple options (e.g., "python", "typescript")
  • approach: Implementation approach or pattern to use
  • Add any task-specific parameters the agent needs
• github: Leave placeholder text - will be updated during sync
• depends_on: List task numbers that must complete before this can start (e.g., [001, 002])
• parallel: Set to true if this can run alongside other tasks without conflicts
• conflicts_with: List task numbers that modify the same files (helps coordination)

5. Task Types to Consider

• Setup tasks: Environment, dependencies, scaffolding
• Data tasks: Models, schemas, migrations
• API tasks: Endpoints, services, integration
• UI tasks: Components, pages, styling
• Testing tasks: Unit tests, integration tests
• Documentation tasks: README, API docs
• Deployment tasks: CI/CD, infrastructure

6. Parallelization

Mark tasks with parallel: true if they can be worked on simultaneously without conflicts.

7. Execution Strategy

Choose based on task count and complexity:

Small Epic (< 5 tasks): Create sequentially for simplicity

Medium Epic (5-10 tasks):

• Batch into 2-3 groups
• Spawn agents for each batch
• Consolidate results

Large Epic (> 10 tasks):

• Analyze dependencies first
• Group independent tasks
• Launch parallel agents (max 5 concurrent)
• Create dependent tasks after prerequisites

Example for parallel execution:

Spawning 3 agents for parallel task creation:
- Agent 1: Creating tasks 001-003 (Database layer)
- Agent 2: Creating tasks 004-006 (API layer)
- Agent 3: Creating tasks 007-009 (UI layer)

Multi-Epic Processing Example:

Processing multiple epics from split:

📂 01-infrastructure/epic.md
   Creating 8 tasks...
   ✅ Done

📂 02-auth-backend/epic.md
   Creating 12 tasks...
   ✅ Done

📂 03-frontend/epic.md
   Creating 10 tasks...
   ✅ Done

8. Task Dependency Validation

When creating tasks with dependencies:

• Ensure referenced dependencies exist (e.g., if Task 003 depends on Task 002, verify 002 was created)
• Check for circular dependencies (Task A → Task B → Task A)
• If dependency issues found, warn but continue: "⚠️ Task dependency warning: {details}"

9. Update Epic with Task Summary

After creating all tasks, update the epic file by adding this section:

## Tasks Created
- [ ] 001.md - {Task Title} (parallel: true/false)
- [ ] 002.md - {Task Title} (parallel: true/false)
- etc.

Total tasks: {count}
Parallel tasks: {parallel_count}
Sequential tasks: {sequential_count}
Estimated total effort: {sum of hours}

Also update the epic's frontmatter progress if needed (still 0% until tasks actually start).

9. Quality Validation

Before finalizing tasks, verify:

• All tasks have clear acceptance criteria
• Task sizes are reasonable (1-3 days each)
• Dependencies are logical and achievable
• Parallel tasks don't conflict with each other
• Combined tasks cover all epic requirements

10. Post-Decomposition

For Single Epic: After successfully creating tasks:

1. Confirm: "✅ Created {count} tasks for epic: {{arguments}}"
2. Show summary:
   • Total tasks created
   • Parallel vs sequential breakdown
   • Total estimated effort
3. Suggest next step: "Ready to sync to GitHub? Run: /pm:epic-sync {{arguments}}"

For Multi-Epic: After processing all epics:

1. Show per-epic summary:

   ✅ Epic Decomposition Complete
   
   📂 01-infrastructure: 8 tasks created
   📂 02-auth-backend: 12 tasks created
   📂 03-frontend: 10 tasks created
   
   Total: 30 tasks across 3 epics
   

2. Show combined statistics:
   • Total tasks across all epics
   • Total estimated effort
   • Breakdown by epic
3. Suggest next step: "Ready to sync all epics? Run: /pm:epic-sync {{arguments}}"

Error Recovery

If any step fails:

• If task creation partially completes, list which tasks were created
• Provide option to clean up partial tasks
• Never leave the epic in an inconsistent state

Aim for tasks that can be completed in 1-3 days each. Break down larger tasks into smaller, manageable pieces for the "{{arguments}}" epic.