@torka/claude-workflows 0.2.0 → 0.3.1

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/completion-summary-implement-epic-with-subagents.md

@@ -0,0 +1,103 @@
+---
+workflowName: implement-epic-with-subagents
+creationDate: 2026-01-04
+module: bmm
+phase: 4-implementation
+status: COMPLETE
+stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8, 9]
+reviewPassed: true
+reviewDate: 2026-01-04
+---
+
+# Workflow Creation Summary
+
+## Workflow Information
+
+- **Name:** implement-epic-with-subagents
+- **Module:** bmm (BMAD Method Module)
+- **Phase:** 4-implementation
+- **Created:** 2026-01-04
+- **Location:** `_bmad-output/bmb-creations/workflows/implement-epic-with-subagents/`
+- **Target Installation:** `_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents/`
+
+## Purpose
+
+Automate entire epic execution by orchestrating sub-agents to execute all stories sequentially, with minimal human intervention.
+
+## Generated Files
+
+### Workflow Configuration
+- `workflow.yaml` - Main workflow configuration
+
+### Step Files
+- `steps/step-01-init.md` - Epic initialization and prerequisite validation
+- `steps/step-01b-continue.md` - Session resumption and state recovery
+- `steps/step-02-orchestrate.md` - Main orchestration loop (story execution)
+- `steps/step-03-complete.md` - Completion and report generation
+
+### Templates
+- `templates/epic-completion-report.md` - Epic completion report template
+
+### Validation
+- `validation/checklist.md` - Pre-execution validation checklist
+
+## Quick Start Guide
+
+### 1. Install the Workflow
+
+```bash
+cp -r _bmad-output/bmb-creations/workflows/implement-epic-with-subagents _bmad/bmm/workflows/4-implementation/
+```
+
+### 2. Create Required Agents
+
+Before running, ensure these agents exist:
+- `.claude/agents/story-prep-master.md`
+- `.claude/agents/quality-gate-verifier.md`
+- `.claude/agents/principal-code-reviewer.md`
+
+### 3. Optional: Create Specialist Dev Agents
+
+Populate `.claude/agents/vt-bmad-dev-agents/` with specialist agents for automatic agent selection based on story requirements.
+
+### 4. Run the Workflow
+
+The workflow will:
+1. Load and parse the epic file
+2. For each story: create → develop → quality gate → code review → git commit
+3. Update sprint-status.yaml throughout
+4. Generate completion report
+
+## Key Features
+
+- **Autonomous Execution:** Runs with minimal human intervention
+- **Smart Agent Selection:** Automatically picks specialist dev agents based on story content
+- **Quality Gate:** Independent verification via quality-gate-verifier agent
+- **Resume Capability:** Sidecar file enables session recovery
+- **Auto-Commit:** Git commits after each story completion
+
+## Failure Handling
+
+| Failure Type | Action |
+|--------------|--------|
+| Simple (lint, types) | Auto-retry up to 3 attempts |
+| Moderate (test failures) | Agent attempts fix, escalate after 2 failures |
+| Complex (architectural) | Stop immediately, escalate with context |
+
+## Next Steps
+
+1. **Install to bmm module** - Copy to final location
+2. **Create quality-gate-verifier agent** - Required for quality gate phase
+3. **Optionally create specialist agents** - For automatic agent matching
+4. **Test with small epic** - Validate workflow before full use
+5. **Configure Context-7 MCP** - Required for documentation access
+
+## Dependencies
+
+| Dependency | Status | Notes |
+|------------|--------|-------|
+| Context-7 MCP | Required | Must be configured |
+| Playwright MCP | Optional | Use if available |
+| story-prep-master | Required | Create if not exists |
+| quality-gate-verifier | Required | Create if not exists |
+| principal-code-reviewer | Required | Create if not exists |

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/steps/step-01-init.md

@@ -0,0 +1,250 @@
+---
+name: 'step-01-init'
+description: 'Entry router - detect context and route to appropriate initialization path'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-init.md'
+continueFile: '{workflow_path}/steps/step-01b-continue.md'
+newSetupFile: '{workflow_path}/steps/step-01c-new.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# State files
+sidecarFolder: '{output_folder}/epic-executions'
+sprintStatus: '{implementation_artifacts}/sprint-status.yaml'
+---
+
+# Step 1: Entry Router
+
+## STEP GOAL:
+
+To detect the execution context (worktree vs main repo), discover any existing epic execution state, and route to the appropriate next step.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER skip detection steps
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A ROUTER, not an executor
+
+### Role Reinforcement:
+
+- ✅ You are an Epic Execution Orchestrator
+- ✅ This step ONLY detects context and routes
+- ✅ All initialization logic is in step-01c
+- ✅ All continuation logic is in step-01b
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on detection and routing
+- 🚫 FORBIDDEN to start epic setup in this step
+- 🚫 FORBIDDEN to start story execution in this step
+- 🚪 ROUTE to appropriate step based on detection results
+
+## DETECTION SEQUENCE:
+
+### 1. Detect Worktree Context
+
+Execute git commands to determine if running in a worktree:
+
+```bash
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
+```
+
+**Interpretation:**
+- If `$GIT_DIR` != `$GIT_COMMON` → Running in a WORKTREE
+- If `$GIT_DIR` == `$GIT_COMMON` → Running in MAIN REPO
+
+**Store context:**
+```
+is_worktree: true | false
+current_path: $(pwd)
+```
+
+### 2. Discover Sidecar Files
+
+Scan for existing epic execution state files.
+
+**IMPORTANT:** When running in a worktree, the sidecar was created in the **main repo** before session restart. You must search the main repo's sidecar folder, not just the local worktree folder.
+
+**If running in MAIN REPO (`is_worktree` = false):**
+```bash
+ls -la {sidecarFolder}/epic-*-state.yaml 2>/dev/null
+```
+
+**If running in WORKTREE (`is_worktree` = true):**
+```bash
+# Derive main repo path from git
+MAIN_REPO_PATH=$(dirname "$(git rev-parse --git-common-dir)")
+MAIN_SIDECAR_FOLDER="$MAIN_REPO_PATH/_bmad-output/epic-executions"
+
+# Search main repo sidecar folder (canonical location where setup created it)
+ls -la "$MAIN_SIDECAR_FOLDER"/epic-*-state.yaml 2>/dev/null
+```
+
+**Store main repo sidecar path for later use:**
+```
+main_sidecar_folder: "$MAIN_SIDECAR_FOLDER"  # Only when is_worktree=true
+```
+
+**For each sidecar found, extract:**
+- Epic number (from filename pattern)
+- `current_phase` value
+- `worktree_config.worktree_path` (if present)
+- `stories_pending` count
+- `sidecar_path` (full path to the sidecar file)
+
+**Build sidecar list:**
+```
+sidecars_found:
+  - file: "epic-2-state.yaml"
+    sidecar_path: "/main/repo/_bmad-output/epic-executions/epic-2-state.yaml"
+    epic_number: 2
+    phase: "executing"
+    worktree_path: "/path/to/worktree" | null
+    pending_stories: 5
+```
+
+### 3. Route Decision
+
+Based on detection results, determine the appropriate path:
+
+#### Scenario A: In Worktree with Matching Sidecar
+
+**Conditions:**
+- `is_worktree` = true
+- Found sidecar where `worktree_config.worktree_path` == `current_path`
+- Sidecar has `stories_pending` > 0
+
+**Action:** Route to `{continueFile}` with matched sidecar
+
+**Display:**
+```
+Detected: Running in worktree for Epic {N}
+Found matching execution state with {X} stories pending.
+Sidecar location: {sidecar_path}
+
+Routing to continuation...
+```
+
+→ Pass `sidecar_path` context for subsequent steps to use
+→ Load, read entire file, then execute `{continueFile}`
+
+---
+
+#### Scenario B: In Worktree, Awaiting Session Restart
+
+**Conditions:**
+- `is_worktree` = true
+- Found sidecar where `worktree_config.worktree_path` == `current_path`
+- Sidecar has `current_phase` = "awaiting_session_restart"
+
+**Action:** Update sidecar phase to "executing", route to orchestration
+
+**Display:**
+```
+Detected: Fresh session in worktree for Epic {N}
+Setup was completed in previous session.
+
+Ready to begin story execution...
+```
+
+→ Update sidecar at `{sidecar_path}` (the matched sidecar's full path): `current_phase: "executing"`
+→ Load, read entire file, then execute step-02-orchestrate.md
+
+---
+
+#### Scenario C: In Worktree, No Matching Sidecar
+
+**Conditions:**
+- `is_worktree` = true
+- No sidecar matches `current_path`
+
+**Action:** Error state - worktree exists but no state found
+
+**Display:**
+```
+⚠️ Warning: Running in a worktree but no matching execution state found.
+
+This worktree may have been created manually or state was lost.
+
+Options:
+[N] Start new epic setup (will use this worktree)
+[X] Exit and investigate
+```
+
+- IF N: Route to `{newSetupFile}` (skip worktree creation, use current)
+- IF X: EXIT workflow
+
+---
+
+#### Scenario D: In Main Repo with Pending Sidecars
+
+**Conditions:**
+- `is_worktree` = false
+- Found sidecars with `stories_pending` > 0
+
+**Action:** Show existing executions, ask user intent
+
+**Display:**
+```
+Found existing epic execution(s):
+
+  Epic 2: "Auth Experience" - 5 stories pending
+    └─ Worktree: ../vt-saas-template-epic-2-auth/
+  Epic 3: "User Onboarding" - 7 stories pending (main repo)
+
+Options:
+[1] Continue Epic 2 (requires: cd ../vt-saas-template-epic-2-auth/)
+[2] Continue Epic 3
+[N] Start NEW epic execution
+```
+
+- IF number selected for worktree epic: Display cd command and exit
+- IF number selected for main repo epic: Route to `{continueFile}`
+- IF N: Route to `{newSetupFile}`
+
+---
+
+#### Scenario E: In Main Repo, No Active Sidecars
+
+**Conditions:**
+- `is_worktree` = false
+- No sidecars found OR all sidecars have `current_phase` = "complete"
+
+**Action:** Fresh start - route to new epic setup
+
+**Display:**
+```
+Welcome to the Epic Execution Orchestrator!
+
+No active epic executions found.
+Starting new epic setup...
+```
+
+→ Load, read entire file, then execute `{newSetupFile}`
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Correctly detected worktree vs main repo context
+- Found and parsed all existing sidecar files
+- Routed to appropriate step based on scenario
+- User given clear options when multiple paths exist
+
+### ❌ SYSTEM FAILURE:
+
+- Starting epic setup directly (that's step-01c's job)
+- Starting continuation directly (that's step-01b's job)
+- Not detecting worktree context
+- Not scanning for existing sidecars
+- Making assumptions without detection
+
+**Master Rule:** This step ONLY detects and routes. All execution logic belongs in subsequent steps.

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/steps/step-01b-continue.md

@@ -0,0 +1,305 @@
+---
+name: 'step-01b-continue'
+description: 'Resume epic execution from previous session using sidecar state'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01b-continue.md'
+nextStepFile: '{workflow_path}/steps/step-02-orchestrate.md'
+completionStepFile: '{workflow_path}/steps/step-03-complete.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# State files
+sidecarFolder: '{output_folder}/epic-executions'
+sprintStatus: '{implementation_artifacts}/sprint-status.yaml'
+---
+
+# Step 1B: Epic Execution Continuation
+
+## STEP GOAL:
+
+To resume epic execution from a previous session by loading the sidecar state, determining the exact resume point (which story, which phase), and seamlessly continuing autonomous execution.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Orchestrator-Specific Rules:
+
+- 🛑 NEVER modify completed story results
+- 🔄 CRITICAL: Determine exact resume point from sidecar state
+- 📋 YOU ARE AN ORCHESTRATOR resuming execution
+
+### Role Reinforcement:
+
+- ✅ You are an Epic Execution Orchestrator
+- ✅ You are resuming a previously started epic execution
+- ✅ You maintain execution continuity without loss of progress
+- ✅ You communicate resume status clearly
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on analyzing state and resuming
+- 🚫 FORBIDDEN to re-execute completed stories
+- 💬 Confirm resume point with user
+- 🚪 DETECT if all stories are already complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show current state analysis before resuming
+- 💾 Update sidecar with resume timestamp
+- 📖 Preserve all completed story data
+- 🚫 FORBIDDEN to modify historical execution data
+
+## CONTEXT BOUNDARIES:
+
+- Sidecar file contains complete execution state
+- Previous stories may be completed, in-progress, or pending
+- Current phase indicates where to resume within a story
+- Sprint-status.yaml reflects actual story states
+- Worktree context affects where execution continues
+
+## CONTINUATION SEQUENCE:
+
+### 0. Context Awareness
+
+**Note:** This step is routed from step-01-init which already detected:
+- Whether we're in a worktree or main repo
+- Which sidecar file to use (passed as `sidecar_path` context)
+
+If `sidecar_path` was NOT specified by router (edge case):
+
+```bash
+# Detect worktree context
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
+CURRENT_PATH=$(pwd)
+
+# Determine sidecar search location
+if [ "$GIT_DIR" != "$GIT_COMMON" ]; then
+  # In worktree - sidecar is in main repo
+  MAIN_REPO_PATH=$(dirname "$GIT_COMMON")
+  SIDECAR_FOLDER="$MAIN_REPO_PATH/_bmad-output/epic-executions"
+else
+  # In main repo - use local folder
+  SIDECAR_FOLDER="{sidecarFolder}"
+fi
+
+# Find sidecar with matching worktree_path (if in worktree)
+# Parse each epic-*-state.yaml and match worktree_config.worktree_path == CURRENT_PATH
+```
+
+**Worktree-specific notes:**
+- Sidecar files are ALWAYS created in the **main repo's** `_bmad-output/epic-executions/`
+- When in a worktree, you must derive the main repo path to find the sidecar
+- `worktree_config.worktree_path` in sidecar identifies which worktree it belongs to
+
+### 1. Load Sidecar State
+
+Read the sidecar file at the path determined above (use `sidecar_path` from router context, or derive it as shown in section 0):
+
+Extract:
+- `epic_execution_state.epic_file`: Path to epic being executed
+- `epic_execution_state.epic_name`: Name of the epic
+- `epic_execution_state.epic_number`: Epic number
+- `epic_execution_state.current_story`: Story that was being processed (may be null)
+- `epic_execution_state.current_phase`: Phase within story (create/dev/visual/review/commit)
+- `epic_execution_state.stories_completed`: List of finished stories
+- `epic_execution_state.stories_pending`: List of remaining stories
+- `epic_execution_state.stories_skipped`: List of skipped stories
+- `epic_execution_state.stories_failed`: List of failed stories
+- `epic_execution_state.started_at`: Original start timestamp
+- `epic_execution_state.last_updated`: Last activity timestamp
+- `execution_mode.type`: "worktree" | "main"
+- `worktree_config` (if worktree mode):
+  - `worktree_path`: Absolute path to worktree
+  - `branch_name`: Feature branch name
+  - `main_repo_path`: Path to main repository
+
+### 2. Validate Execution Context
+
+**If sidecar indicates worktree mode:**
+
+Check current working directory matches expected worktree:
+
+```bash
+EXPECTED_PATH=$(grep 'worktree_path:' sidecar.yaml | awk '{print $2}')
+CURRENT_PATH=$(pwd)
+
+if [ "$CURRENT_PATH" != "$EXPECTED_PATH" ]; then
+  # Wrong directory - warn user
+fi
+```
+
+**If mismatch detected:**
+```
+⚠️ Context Mismatch
+
+This epic execution was configured for worktree mode:
+  Expected: {worktree_path}
+  Current:  {current_path}
+
+Options:
+[P] Proceed anyway (may cause issues)
+[X] Exit and navigate to correct directory
+```
+
+### 3. Analyze Execution State
+
+Determine resume scenario:
+
+**Scenario A: Mid-Story Resume**
+If `current_story` is set and `current_phase` is not "between_stories":
+- Resume at the specific phase of that story
+- Example: Story 2.3 was in "dev" phase → resume dev
+
+**Scenario B: Between Stories**
+If `current_story` is null or phase is "between_stories":
+- Start next story from `stories_pending[0]`
+
+**Scenario C: All Stories Complete**
+If `stories_pending` is empty:
+- Route to step-03-complete for report generation and cleanup
+
+### 4. Display Resume Summary
+
+```
+**Welcome Back!**
+
+**Epic:** {epic_name} (Epic {epic_number})
+**Mode:** {execution_mode.type}
+**Started:** {started_at}
+**Last Activity:** {last_updated}
+
+**Location:**
+{If worktree: "Worktree: {worktree_path}"}
+{If main: "Main repository"}
+
+**Progress:**
+- ✅ Completed: {X} stories
+- ⏸️ Skipped: {X} stories
+- ❌ Failed: {X} stories
+- ⏳ Pending: {X} stories
+
+**Resume Point:**
+{Based on scenario - describe where we'll resume}
+
+Example outputs:
+- 'Resuming Story 2.3 at development phase'
+- 'Starting Story 2.4 (previous story completed)'
+- 'All stories complete - ready to generate report'
+```
+
+### 5. Validate Resume Readiness
+
+Quick prerequisite check:
+- Epic file still exists and readable
+- Sprint-status.yaml accessible
+- Required agents still available
+- If worktree: worktree still exists and is valid
+
+If any critical issue → report and ask user how to proceed.
+
+### 6. Confirm Continuation Intent
+
+```
+**Ready to continue?**
+
+Options:
+[C] Continue from {resume point}
+[R] Restart epic from beginning (will lose progress)
+[S] Show detailed execution log
+```
+
+### 7. Handle Menu Selection
+
+#### IF C (Continue):
+1. Update sidecar:
+   ```yaml
+   execution_log:
+     - event: "session_resumed"
+       timestamp: "{current_timestamp}"
+       from_phase: "{current_phase}"
+   last_updated: "{current_timestamp}"
+   ```
+2. Route based on scenario:
+   - Scenario A/B → load, read entire file, then execute `{nextStepFile}`
+   - Scenario C → load, read entire file, then execute `{completionStepFile}`
+
+#### IF R (Restart):
+1. Confirm: "This will clear all progress. Are you sure? [Y/N]"
+2. If Y:
+   - If worktree mode: Also ask about worktree cleanup
+   - Delete sidecar file
+   - Route to step-01-init.md (will go to step-01c for new setup)
+3. If N: Redisplay menu
+
+#### IF S (Show Log):
+1. Display execution_log entries with timestamps
+2. Show per-story details:
+   ```
+   Execution Log:
+
+   [timestamp] Session started
+   [timestamp] Story 2.1 - create phase completed
+   [timestamp] Story 2.1 - dev phase completed (auth-specialist)
+   [timestamp] Story 2.1 - review approved
+   [timestamp] Story 2.1 - committed
+   [timestamp] Session interrupted
+   [timestamp] Session resumed ← current
+   ```
+3. Redisplay menu
+
+### 8. Present MENU OPTIONS
+
+Display: **Select an Option:** [C] Continue | [R] Restart | [S] Show Log
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user selection
+- Confirm restart with double-check
+- Show execution context before continuing
+
+#### Menu Handling Logic:
+
+- IF C: Update sidecar with resume timestamp, then:
+  - If stories pending → load `{nextStepFile}`
+  - If all complete → load `{completionStepFile}`
+- IF R: Confirm and handle restart
+- IF S: Display log and redisplay menu
+- IF Any questions: Respond and redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Sidecar state loaded and analyzed correctly
+- Worktree context validated (if applicable)
+- Resume point determined accurately
+- User confirmed continuation
+- Proper routing to next step
+- Resume timestamp recorded
+
+### ❌ SYSTEM FAILURE:
+
+- Not loading complete sidecar state
+- Not validating worktree context
+- Incorrect resume point determination
+- Re-executing completed stories
+- Not confirming with user before resuming
+- Modifying historical execution data
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN user selects [C] and sidecar is updated with resume info, will you then load the appropriate next step file based on execution state.