@torka/claude-workflows 0.3.0 → 0.3.1

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

@@ -67,22 +67,42 @@ current_path: $(pwd)
 
 ### 2. Discover Sidecar Files
 
-Scan for existing epic execution state 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
@@ -106,10 +126,12 @@ Based on detection results, determine the appropriate path:
 ```
 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}`
 
 ---
@@ -131,7 +153,7 @@ Setup was completed in previous session.
 Ready to begin story execution...
 ```
 
-→ Update sidecar: `current_phase: "executing"`
+→ Update sidecar at `{sidecar_path}` (the matched sidecar's full path): `current_phase: "executing"`
 → Load, read entire file, then execute step-02-orchestrate.md
 
 ---

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

@@ -72,9 +72,9 @@ To resume epic execution from a previous session by loading the sidecar state, d
 
 **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 context)
+- Which sidecar file to use (passed as `sidecar_path` context)
 
-If sidecar was NOT specified by router (edge case):
+If `sidecar_path` was NOT specified by router (edge case):
 
 ```bash
 # Detect worktree context
@@ -82,21 +82,28 @@ GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
 GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
 CURRENT_PATH=$(pwd)
 
-# If in worktree, find matching sidecar
+# Determine sidecar search location
 if [ "$GIT_DIR" != "$GIT_COMMON" ]; then
-  # Search for sidecar with matching worktree_path
-  # Parse each epic-*-state.yaml and match worktree_config.worktree_path
+  # 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 in main repo's `{sidecarFolder}`
-- When in worktree, sidecar is accessed via the shared git history
-- `worktree_config.worktree_path` in sidecar identifies the worktree
+- 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 `{sidecarFolder}/epic-{N}-state.yaml`:
+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

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

@@ -79,11 +79,14 @@ To autonomously execute all pending stories in the epic by orchestrating special
 
 ## CONTEXT BOUNDARIES:
 
+- **Sidecar path:** Use `sidecar_path` from router context (step-01-init). In worktree mode, the sidecar is in the main repo's `_bmad-output/epic-executions/`, NOT the worktree's folder.
 - Sidecar file tracks current story and phase
 - Each agent gets fresh context with specific instructions
 - Sprint-status.yaml is source of truth for story states
 - Handoff messages provide phase completion status
 
+**CRITICAL for worktree mode:** All sidecar updates must use the absolute `sidecar_path` passed from step-01-init. Do NOT use `{sidecarFolder}` directly as it resolves to the wrong location in worktrees.
+
 ---
 
 ## STORY EXECUTION LOOP

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

@@ -74,6 +74,7 @@ To generate the Epic Completion Report, create a Pull Request, handle worktree c
 
 ## CONTEXT BOUNDARIES:
 
+- **Sidecar path:** Use `sidecar_path` from router context (step-01-init). In worktree mode, the sidecar is in the main repo's `_bmad-output/epic-executions/`, NOT the worktree's folder.
 - Sidecar file contains complete execution history
 - All story outcomes recorded in execution_log
 - Sprint-status reflects final story states
@@ -86,7 +87,9 @@ To generate the Epic Completion Report, create a Pull Request, handle worktree c
 
 ### 1. Load Execution Data
 
-Read the sidecar file at `{sidecarFolder}/epic-{N}-state.yaml`:
+Read the sidecar file using `sidecar_path` from router context (passed through step-01-init → step-01b/02):
+
+**Note:** In worktree mode, this path points to the main repo's sidecar location, not the worktree's.
 
 Gather:
 - `epic_execution_state.epic_file`, `epic_execution_state.epic_name`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torka/claude-workflows",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, and design workflows",
   "keywords": [
     "claude-code",