@torka/claude-workflows 0.2.0 → 0.3.1

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

@@ -0,0 +1,101 @@
+---
+name: implement-epic-with-subagents
+description: "Automate entire epic execution by orchestrating sub-agents to execute all stories sequentially with minimal human intervention"
+web_bundle: true
+---
+
+# Implement Epic with Sub-Agents
+
+**Goal:** Automate entire epic execution by orchestrating specialized sub-agents to implement all stories sequentially, with minimal human intervention. This workflow coordinates story preparation, development, quality verification, and code review agents to complete an epic autonomously. Supports optional git worktree isolation for parallel development.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also an Epic Execution Orchestrator collaborating with developers and project managers. This is a partnership, not a client-vendor relationship. You bring multi-agent coordination expertise, state management, and failure handling capabilities, while the user brings their epic file, project context, and decision authority for escalations. Work together as equals.
+
+> **Meta-Workflow Notice:** This is an autonomous orchestration workflow designed for minimal human intervention during execution. Unlike standard BMAD workflows that use frequent user checkpoints, this workflow operates autonomously once initiated, only pausing for critical escalations or failures. This is an intentional design choice for the meta-workflow/orchestrator pattern.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** with autonomous execution patterns:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file that is part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until directed
+- **Sequential Enforcement**: Sequence within step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in epic-specific sidecar state files (`epic-{N}-state.yaml`) for execution tracking and resumption
+- **Append-Only Building**: Build completion reports by appending content as directed to output files
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: At initialization and escalation points, halt and wait for user input
+4. **CHECK CONTINUATION**: Proceed to next step only when current step logic completes
+5. **SAVE STATE**: Update sidecar state file before transitioning between steps or phases
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously
+- **ALWAYS** read entire step file before execution
+- **NEVER** skip steps or optimize the sequence
+- **ALWAYS** update sidecar state after every phase completion
+- **ALWAYS** follow the exact instructions in the step file
+- **ALWAYS** halt at escalation points and wait for user input
+- **NEVER** proceed after quality gate failure without retry or escalation
+
+### Autonomous Execution Pattern
+
+This workflow uses an **autonomous loop pattern** in step-02-orchestrate:
+- Stories are processed sequentially without user confirmation between stories
+- User intervention occurs only at: initialization, failures, escalations, and completion
+- Progress is reported after each story completion
+- State is persisted to allow resumption if interrupted
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `output_folder`, `user_name`, `communication_language`, `document_output_language`, `implementation_artifacts`
+
+Additional configuration is available in `workflow.yaml` including:
+- Agent references (story-prep, quality-gate, code-reviewer, specialists)
+- Execution settings (coverage threshold, max retries, auto-commit)
+- Input/output file paths
+
+### 2. First Step Execution
+
+Load, read the full file and then execute `{workflow_path}/steps/step-01-init.md` to begin the workflow.
+
+If a sidecar state file exists with pending work, step-01 will automatically route to `step-01b-continue.md` for resumption.
+
+---
+
+## WORKFLOW STEPS
+
+| Step | File | Purpose |
+|------|------|---------|
+| 1 | step-01-init.md | Entry router - detect context (worktree/main), discover sidecars, route to appropriate step |
+| 1b | step-01b-continue.md | Resume from previous session using sidecar state |
+| 1c | step-01c-new.md | New epic setup - mode selection, worktree creation, prerequisites, agent creation |
+| 2 | step-02-orchestrate.md | Main autonomous loop - execute all stories with sub-agents |
+| 3 | step-03-complete.md | Generate completion report, create PR, handle worktree cleanup |
+
+---
+
+## AGENT COORDINATION
+
+This workflow orchestrates three specialized agents per story:
+
+| Agent | Purpose | Handoff |
+|-------|---------|---------|
+| **story-prep-master** | Create developer-ready story file from epic | Story file path |
+| **specialist/dev agent** | Implement story with tests (TDD) | Files changed, coverage, test results |
+| **principal-code-reviewer** | Code review, quality assessment, auto-fixes | Approval status, findings |
+
+Each agent receives fresh context and returns structured handoff messages for orchestration.

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/workflow.yaml

@@ -0,0 +1,87 @@
+name: implement-epic-with-subagents
+description: "Automate entire epic execution by orchestrating sub-agents to execute all stories sequentially with minimal human intervention"
+author: "BMad"
+web_bundle: true
+
+# Critical variables from config
+config_source: "{project-root}/_bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+implementation_artifacts: "{config_source}:implementation_artifacts"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents"
+workflow_file: "{installed_path}/workflow.yaml"
+first_step: "{installed_path}/steps/step-01-init.md"
+
+# Input files
+epic_file: "" # User provides or auto-discover
+sprint_status: "{implementation_artifacts}/sprint-status.yaml"
+project_context: "**/project-context.md"
+
+# Output files (legacy - kept for reference, see sidecar_folder below)
+# sidecar_file: "{output_folder}/epic-execution-state.yaml"  # DEPRECATED
+completion_report: "{output_folder}/epic-reports/epic-completion-{epic_name}-{date}.md"
+
+# Agent references
+story_prep_agent: ".claude/agents/story-prep-master.md"
+code_review_agent: ".claude/agents/principal-code-reviewer.md"
+specialist_agents_folder: ".claude/agents/vt-bmad-dev-agents/"
+fallback_dev_agent: "_bmad/bmm/agents/dev.md"
+
+# Execution configuration
+coverage_threshold: 80
+max_retries: 3
+auto_commit: true
+
+# Git workflow settings
+feature_branch_prefix: "feature/epic-"
+auto_create_branch: true
+base_branch: "main"
+
+# Agent creation settings
+agent_creator_skill: ".claude/skills/agent-creator/SKILL.md"
+specialist_agents_created: []  # Populated by init step
+
+# PR settings
+auto_create_pr: true
+pr_base_branch: "main"
+
+# Retrospective settings
+retrospective_workflow: "_bmad/bmm/workflows/4-implementation/retrospective"
+
+standalone: true
+
+# ═══════════════════════════════════════════
+# WORKTREE CONFIGURATION
+# ═══════════════════════════════════════════
+
+# Worktree mode: "ask" | "always" | "never"
+#   ask    - Prompt user each time (default)
+#   always - Always use worktree, skip prompt
+#   never  - Never use worktree, classic behavior
+worktree_mode: "ask"
+
+# Directory pattern for worktrees (relative to main repo parent)
+# Available variables: {project_name}, {epic_number}, {epic_name_sanitized}
+worktree_directory_pattern: "../{project_name}-epic-{epic_number}-{epic_name_sanitized}"
+
+# Branch pattern for worktree branches
+worktree_branch_pattern: "feature/epic-{epic_number}-{epic_name_sanitized}"
+
+# Dependency installation command (auto-detected if empty)
+# Examples: "npm install", "yarn", "pnpm install", "bun install"
+dependency_command: ""
+
+# ═══════════════════════════════════════════
+# SIDECAR CONFIGURATION
+# ═══════════════════════════════════════════
+
+# Sidecar storage folder (will be gitignored)
+sidecar_folder: "{output_folder}/epic-executions"
+
+# Sidecar file pattern
+sidecar_file_pattern: "epic-{epic_number}-state.yaml"

package/install.js

@@ -129,10 +129,17 @@ function install() {
   };
 
   // Define what to copy and where
+  // Note: dest is relative to targetBase (.claude/)
+  // Use '../' to go to project root for _bmad/ paths
   const mappings = [
     { src: 'commands', dest: 'commands' },
     { src: 'agents', dest: 'agents' },
     { src: 'skills', dest: 'skills' },
+    // BMAD workflows (installed to project root, not .claude/)
+    {
+      src: 'bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents',
+      dest: '../_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents',
+    },
   ];
 
   for (const { src, dest } of mappings) {
@@ -156,13 +163,13 @@ function install() {
   log('   2. Try /designer-founder for UI/UX design workflows\n');
 
   // Note about BMAD dependencies
-  log(colors.yellow + '⚠️  Note: Some components require BMAD Method workflows:' + colors.reset);
-  log('   - implement-epic-with-subagents');
-  log('   - principal-code-reviewer');
-  log('   - story-prep-master');
-  log('\n   Standalone components work without dependencies:');
+  log(colors.yellow + '⚠️  Note: Some components work better with BMAD Method installed:' + colors.reset);
+  log('   - principal-code-reviewer (uses BMAD code-review workflow)');
+  log('   - story-prep-master (uses BMAD story workflows)');
+  log('\n   Fully included (no external dependencies):');
   log('   ✓ git-cleanup-and-merge');
   log('   ✓ plan-parallelization');
+  log('   ✓ implement-epic-with-subagents (workflow files included)');
   log('   ✓ agent-creator skill');
   log('   ✓ designer-founder skill\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torka/claude-workflows",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, and design workflows",
   "keywords": [
     "claude-code",
@@ -22,6 +22,7 @@
     "commands",
     "agents",
     "skills",
+    "bmad-workflows",
     "examples",
     ".claude-plugin",
     "install.js",

package/uninstall.js

@@ -80,6 +80,32 @@ const INSTALLED_FILES = {
   ],
 };
 
+/**
+ * BMAD workflow files installed to _bmad/ (relative to project root)
+ * These use ../ from .claude/ to reach project root
+ */
+const BMAD_INSTALLED_FILES = {
+  '../_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents': [
+    'workflow.md',
+    'workflow.yaml',
+    'workflow-plan-implement-epic-with-subagents.md',
+    'completion-summary-implement-epic-with-subagents.md',
+  ],
+  '../_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents/steps': [
+    'step-01-init.md',
+    'step-01b-continue.md',
+    'step-01c-new.md',
+    'step-02-orchestrate.md',
+    'step-03-complete.md',
+  ],
+  '../_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents/templates': [
+    'epic-completion-report.md',
+  ],
+  '../_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents/validation': [
+    'checklist.md',
+  ],
+};
+
 /**
  * Determine the target .claude directory based on installation context
  */
@@ -181,6 +207,37 @@ function uninstall() {
     }
   }
 
+  // Remove BMAD workflow files (installed to _bmad/ relative to project root)
+  log('\n' + colors.bold + 'BMAD Workflows' + colors.reset);
+  for (const [dir, files] of Object.entries(BMAD_INSTALLED_FILES)) {
+    const displayDir = dir.replace('../', '');
+    log(`\n${colors.bold}${displayDir}/${colors.reset}`);
+    for (const file of files) {
+      const filePath = path.join(targetBase, dir, file);
+      removeFile(filePath, stats);
+    }
+
+    // Try to remove empty directories
+    const dirPath = path.join(targetBase, dir);
+    if (removeEmptyDir(dirPath)) {
+      log(`  ○ Removed empty directory: ${displayDir}/`, 'yellow');
+    }
+  }
+
+  // Clean up empty BMAD directories (from deepest to shallowest)
+  const bmadDirs = [
+    '../_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents/validation',
+    '../_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents/templates',
+    '../_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents/steps',
+    '../_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents',
+  ];
+  for (const bmadSubDir of bmadDirs) {
+    const dirPath = path.join(targetBase, bmadSubDir);
+    if (removeEmptyDir(dirPath)) {
+      log(`  ○ Removed empty directory: ${bmadSubDir.replace('../', '')}/`, 'yellow');
+    }
+  }
+
   // Try to remove skill directories if empty
   const skillDirs = [
     'skills/designer-founder/tools/superdesign-assets',