@torka/claude-workflows 0.1.0 → 0.3.0

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/examples/settings.local.example.json

@@ -14,44 +14,5 @@
     ],
     "deny": [],
     "ask": []
-  },
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash|Read|Grep|Glob|Write|Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 .claude/scripts/auto_approve_safe.py"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "if [[ \"$CLAUDE_TOOL_FILE_PATH\" == *.js || \"$CLAUDE_TOOL_FILE_PATH\" == *.ts || \"$CLAUDE_TOOL_FILE_PATH\" == *.jsx || \"$CLAUDE_TOOL_FILE_PATH\" == *.tsx ]]; then npx eslint \"$CLAUDE_TOOL_FILE_PATH\" --fix 2>/dev/null || true; fi"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "if command -v osascript >/dev/null 2>&1; then osascript -e 'display notification \"Claude Code task completed\" with title \"Claude Code\"'; elif command -v notify-send >/dev/null 2>&1; then notify-send 'Claude Code' 'Task completed'; fi"
-          }
-        ]
-      }
-    ]
-  },
-  "statusLine": {
-    "type": "command",
-    "command": "python3 .claude/scripts/context-monitor.py"
   }
 }

package/install.js

@@ -129,12 +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' },
-    { src: 'hooks', dest: 'scripts' },  // Hooks go to scripts directory
-    { src: 'scripts', dest: 'scripts' },
+    // 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) {
@@ -154,21 +159,19 @@ function install() {
 
   // Post-install instructions
   log('\n' + colors.bold + '📝 Next Steps' + colors.reset);
-  log('   1. Configure hooks in .claude/settings.local.json');
-  log('   2. See examples/settings.local.example.json for configuration');
-  log('   3. Run /git-cleanup-and-merge or /plan-parallelization to test\n');
+  log('   1. Run /git-cleanup-and-merge or /plan-parallelization to test');
+  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('   ✓ auto_approve_safe hook');
-  log('   ✓ context-monitor status line\n');
+  log('   ✓ designer-founder skill\n');
 }
 
 // Run installation

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@torka/claude-workflows",
-  "version": "0.1.0",
-  "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, hooks, and status line",
+  "version": "0.3.0",
+  "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, and design workflows",
   "keywords": [
     "claude-code",
     "ai-workflows",
@@ -14,14 +14,6 @@
   ],
   "author": "Varun Torka",
   "license": "MIT",
-  "homepage": "https://github.com/varuntorka/vt-claude-workflows#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/varuntorka/vt-claude-workflows.git"
-  },
-  "bugs": {
-    "url": "https://github.com/varuntorka/vt-claude-workflows/issues"
-  },
   "scripts": {
     "postinstall": "node install.js",
     "preuninstall": "node uninstall.js"
@@ -30,8 +22,7 @@
     "commands",
     "agents",
     "skills",
-    "hooks",
-    "scripts",
+    "bmad-workflows",
     "examples",
     ".claude-plugin",
     "install.js",

package/skills/designer-founder/steps/step-01-context.md

@@ -0,0 +1,171 @@
+# Step 1: Context & Mode Selection
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 NEVER assume project state without checking
+- 📖 CRITICAL: Read complete step file before taking action
+- ✅ ALWAYS treat this as collaborative discovery
+- 🎯 Goal: Understand where we are and what mode to use
+
+---
+
+## YOUR TASK
+
+Establish context and select the appropriate workflow mode based on project state and user intent.
+
+---
+
+## TASK SEQUENCE
+
+### 1. Greet and Understand Intent
+
+Start with a brief greeting using `{user_name}` and ask what they'd like to design:
+
+```
+Hey {user_name}! I'm ready to help you design.
+
+What are you looking to create today?
+```
+
+Wait for user input describing what they want to design.
+
+---
+
+### 2. Detect Project State
+
+After user describes their intent, quickly assess:
+
+**Check for existing project artifacts:**
+- `_bmad-output/planning-artifacts/` - Do specs exist?
+- `_bmad-output/planning-artifacts/ux-design/` - Existing design docs?
+- Epic/story files related to user's intent?
+
+**Determine project phase:**
+- **Greenfield**: No relevant specs found → Need to establish design direction
+- **Mid-project**: Specs exist → Pull context, focus on specific scope
+
+**Report findings concisely:**
+```
+Project Context:
+- [Greenfield / Existing project with specs]
+- Related artifacts found: [list or "none"]
+- Relevant epics/stories: [list or "none"]
+```
+
+---
+
+### 3. Check Available Tools
+
+Detect and report tool availability:
+
+```
+Available Tools:
+✓ SuperDesign - HTML/CSS prototyping
+[✓/✗] MagicPatterns MCP - React component generation
+[✓/✗] shadcn MCP - Component search & install
+[✓/✗] Playwright MCP - Screenshot verification
+```
+
+Note: shadcn CLI (`npx shadcn@latest add`) is always available as fallback.
+
+---
+
+### 4. Present Mode Selection
+
+Based on context, recommend a mode and let user choose:
+
+```
+WORKFLOW MODE
+
+Based on your request, I recommend: [Quick Prototype / Production Flow]
+
+[Q] Quick Prototype
+    → Fast visual exploration
+    → Output: HTML prototype or wireframe
+    → Best for: Testing ideas, exploring directions
+
+[P] Production Flow
+    → Full dev-ready artifacts
+    → Output: Component strategy, layouts, user journeys
+    → Best for: Features going into the product
+
+Which mode? [Q/P]
+```
+
+**Recommendation logic:**
+- User says "explore", "try", "prototype", "quick" → Recommend Quick
+- User mentions specific epic/story, "build", "implement" → Recommend Production
+- Greenfield project, first design → Recommend Production (establish foundation)
+- Uncertain → Ask user
+
+---
+
+### 5. Confirm and Route
+
+Once user selects mode, confirm and route:
+
+**If Quick Prototype:**
+```
+Quick Prototype mode selected.
+
+We'll skip detailed specs and focus on rapid visualization.
+Ready to move to design tool selection.
+```
+→ Proceed to Step 3 (skip Step 2)
+
+**If Production Flow:**
+```
+Production Flow selected.
+
+We'll create dev-ready artifacts including:
+- Component strategy with shadcn mappings
+- Page layouts (responsive)
+- User journeys (if multi-step flow)
+
+Let's define the scope first.
+```
+→ Proceed to Step 2
+
+---
+
+## COLLABORATION MENU
+
+After confirming mode, present:
+
+```
+[A] Advanced - Deep dive into project context
+[P] Party Mode - Get multiple agent perspectives
+[C] Continue - Proceed to next step
+```
+
+**Menu Handlers:**
+- **A**: Load `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml` for deeper discovery
+- **P**: Load `{project-root}/_bmad/core/workflows/party-mode/workflow.md` for multi-perspective input
+- **C**: Proceed to next step based on mode selection
+
+---
+
+## STATE TO CARRY FORWARD
+
+Store in working memory for subsequent steps:
+
+```yaml
+mode: [quick_prototype | production]
+user_intent: "[what user wants to design]"
+project_state: [greenfield | existing]
+related_artifacts: [list of relevant files found]
+tools_available:
+  superdesign: true
+  magicpatterns: [true/false]
+  shadcn_mcp: [true/false]
+  playwright: [true/false]
+```
+
+---
+
+## NEXT STEP
+
+- If mode = `quick_prototype`: Load `./step-03-design.md`
+- If mode = `production`: Load `./step-02-scope.md`
+
+Remember: Do NOT proceed until user explicitly selects [C]

package/skills/designer-founder/steps/step-01b-continue.md

@@ -0,0 +1,75 @@
+# Step 1b: Continue Existing Session
+
+## PURPOSE
+
+Handle resumption of an interrupted designer-founder workflow session.
+
+---
+
+## DETECTION
+
+This step is loaded when:
+- User invokes designer-founder workflow
+- Existing design session state is detected
+- User confirms they want to continue (not start fresh)
+
+---
+
+## TASK SEQUENCE
+
+### 1. Detect Previous State
+
+Check for indicators of previous session:
+- Recent files in `{planning_artifacts}/ux-design/` matching current date
+- Incomplete artifacts (missing expected files)
+- SuperDesign files created recently in `.superdesign/design_iterations/`
+
+### 2. Present Recovery Options
+
+```
+EXISTING SESSION DETECTED
+
+I found evidence of a previous design session:
+- {list what was found}
+
+Would you like to:
+
+[C] Continue - Resume from where we left off
+[R] Review - Show me what was created
+[N] New - Start fresh (previous work preserved)
+```
+
+### 3. If Continue
+
+Reconstruct state:
+```yaml
+mode: {infer from artifacts}
+scope: {infer from artifact names}
+design:
+  tool_used: {infer from output files}
+  output_location: {found files}
+last_completed_step: {infer from artifacts present}
+```
+
+Route to appropriate step:
+- Only design brief exists → Step 3 (Design) or Step 4 (Artifacts)
+- Component strategy exists but incomplete → Step 4
+- All artifacts exist → Offer to refine or start new
+
+### 4. If Review
+
+Display summary of found artifacts and their contents.
+Return to recovery options after review.
+
+### 5. If New
+
+Proceed to `step-01-context.md` for fresh start.
+Do not delete previous work.
+
+---
+
+## NEXT STEP
+
+Based on user selection, route to:
+- Appropriate step for continuation
+- `step-01-context.md` for fresh start