--- allowed-tools: run_command, view_file, write_to_file, list_dir, Task command: pm:epic-decompose description: "Break epic into concrete, actionable tasks." --- # Epic Decompose Break epic into concrete, actionable tasks. **⚠️ IMPORTANT**: This is a OpenCode Code command file, not a standalone script. - Execute via OpenCode Code as: `/pm:epic-decompose ` - Do NOT run as: `node .opencode/scripts/pm/epic-decompose.js` - This command has no standalone script equivalent ## Usage **Single Epic:** ```bash /pm:epic-decompose [--local] ``` **Multi-Epic (decomposes ALL epics at once):** ```bash /pm:epic-decompose [--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:** ```bash /pm:epic-decompose / [--local] # Example: /pm:epic-decompose ecommerce-platform/01-infrastructure --local ``` ## Flags `--local`, `-l` : Use local mode (offline workflow) : Creates task files in `.opencode/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: - `.opencode/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 `.opencode/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 → `.opencode/agents/languages/python-backend-engineer.md` - JavaScript/TypeScript/Node.js → `.opencode/agents/languages/nodejs-backend-engineer.md` - React → `.opencode/agents/frontend/react-frontend-engineer.md` - Bash/Shell scripting → `.opencode/agents/languages/bash-scripting-expert.md` **Databases**: - PostgreSQL → `.opencode/agents/databases/postgresql-expert.md` - MongoDB → `.opencode/agents/databases/mongodb-expert.md` - Redis → `.opencode/agents/databases/redis-expert.md` - Cosmos DB → `.opencode/agents/databases/cosmosdb-expert.md` **Cloud Platforms**: - AWS → `.opencode/agents/cloud/aws-cloud-architect.md` - Azure → `.opencode/agents/cloud/azure-cloud-architect.md` - GCP → `.opencode/agents/cloud/gcp-cloud-architect.md` **Infrastructure & Containers**: - Docker → `.opencode/agents/containers/docker-containerization-expert.md` - Kubernetes → `.opencode/agents/orchestration/kubernetes-orchestrator.md` - Terraform → `.opencode/agents/infrastructure/terraform-infrastructure-expert.md` **Testing**: - Unit/Integration tests → `.opencode/agents/core/test-runner.md` - Frontend E2E testing → `.opencode/agents/testing/frontend-testing-engineer.md` - E2E automation → `.opencode/agents/testing/e2e-test-engineer.md` **DevOps & CI/CD**: - GitHub operations → `.opencode/agents/devops/github-operations-specialist.md` - Azure DevOps → `.opencode/agents/devops/azure-devops-specialist.md` - Observability → `.opencode/agents/devops/observability-engineer.md` ### Step 3: Document Agent Assignments in Epic Frontmatter Add `required_agents` array to epic.md frontmatter: ```yaml --- name: user-authentication prd: user-authentication status: backlog created: 2025-12-17T10:00:00Z updated: 2025-12-17T10:00:00Z required_agents: - path: .opencode/agents/languages/python-backend-engineer.md role: API implementation tasks: [001, 002, 003] - path: .opencode/agents/databases/postgresql-expert.md role: Database schema and migrations tasks: [004, 005] - path: .opencode/agents/testing/frontend-testing-engineer.md role: Test suite development tasks: [006, 007] - path: .opencode/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: ```yaml --- name: Implement JWT authentication endpoints status: open created: 2025-12-17T10:00:00Z updated: 2025-12-17T10:00:00Z assigned_agent: .opencode/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 `.opencode/epics/$ARGUMENTS` directory exists - Check for either: a) Single epic: `.opencode/epics/$ARGUMENTS/epic.md` exists b) Multiple epics: Subdirectories like `.opencode/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 `.opencode/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 `.opencode/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 `.opencode/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 `.opencode/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 `.opencode/epics/$ARGUMENTS/epic.md` - Create tasks in `.opencode/epics/$ARGUMENTS/` **Multi-Epic Mode (from epic-split):** - Find all subdirectories in `.opencode/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 `.opencode/epics/$ARGUMENTS/epic.md` - For multi-epic: Load each `.opencode/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 `.opencode/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**: ```markdown 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 OpenCode 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**: ```markdown Creating task 001 (API endpoint): - assigned_agent: .opencode/agents/languages/python-backend-engineer.md - agent_context: {framework: "fastapi", auth: "jwt"} - File: .opencode/epics/$ARGUMENTS/001.md ✓ Created Creating task 002 (Database schema): - assigned_agent: .opencode/agents/databases/postgresql-expert.md - agent_context: {orm: "sqlalchemy", migrations: "alembic"} - File: .opencode/epics/$ARGUMENTS/002.md ✓ Created ``` ### 4. Task File Format with Frontmatter For each task, create a file with this exact structure: ```markdown --- name: [Task Title] status: open created: [Current ISO date/time] updated: [Current ISO date/time] assigned_agent: .opencode/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 `.opencode/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: `.opencode/epics/$ARGUMENTS/{task_number}.md` **For Multi-Epic:** Save tasks as: `.opencode/epics/$ARGUMENTS/{epic_folder}/{task_number}.md` Example: `.opencode/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., `.opencode/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: ```markdown 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:** ```markdown 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: ```markdown ## 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.