@torka/claude-workflows 0.1.0 → 0.3.0

package/README.md

@@ -9,8 +9,7 @@ Claude Code workflow helpers for epic automation, git management, and developer
 | **Git Cleanup & Merge** | Intelligent branch management, PR creation, CI monitoring | Yes |
 | **Parallelization Analysis** | Identify which epics can run in parallel with Git worktrees | Yes |
 | **Agent Creator** | Design and deploy custom Claude Code agents | Yes |
-| **Auto-Approve Hook** | Safe command auto-approval for solo dev workflows | Yes |
-| **Context Monitor** | Real-time context usage status line | Yes |
+| **Designer-Founder** | Transform ideas into dev-ready frontend artifacts | Yes |
 | **Epic Orchestration** | Automate multi-story epic execution with sub-agents | Requires BMAD |
 | **Code Review Agent** | Principal-level code review automation | Requires BMM |
 | **Story Prep Agent** | Convert requirements to developer-ready specs | Requires BMM |
@@ -35,45 +34,14 @@ The installer automatically copies files to your `.claude/` directory:
 
 ## Post-Installation Setup
 
-### 1. Configure Hooks (recommended)
-
-Copy the hooks configuration from `examples/settings.local.example.json` to your `.claude/settings.local.json`.
-
-**Auto-approve hook** (auto-approves safe commands):
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash|Read|Grep|Glob|Write|Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 .claude/scripts/auto_approve_safe.py"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### 2. Configure Status Line (optional)
+After installation, try running one of the commands to test:
 
-Add to your `.claude/settings.local.json`:
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "python3 .claude/scripts/context-monitor.py"
-  }
-}
+```bash
+/git-cleanup-and-merge
+/plan-parallelization
+/designer-founder
 ```
 
-This shows a real-time context usage bar with percentage and warnings.
-
 ## Usage
 
 ### Commands
@@ -150,44 +118,22 @@ Design and deploy custom Claude Code agents:
 /agent-creator
 ```
 
-### Hooks
-
-#### `auto_approve_safe.py`
-
-PreToolUse hook that auto-approves safe commands:
-- **Allowed**: Read-only commands, tests, linting, git status/diff/log
-- **Denied**: Dangerous commands (sudo, rm -rf, etc.)
-- **Prompted**: Everything else defers to normal permissions
-
-Customize rules in `.claude/scripts/auto_approve_safe.rules.json`:
-
-```json
-{
-  "allow_patterns": [
-    "^npm test",
-    "^git status"
-  ],
-  "deny_patterns": [
-    "^sudo",
-    "rm.*-rf"
-  ],
-  "sensitive_paths": [
-    "\\.env$",
-    "credentials"
-  ]
-}
-```
+#### `/designer-founder`
 
-### Scripts
+Transform design ideas into production-ready frontend artifacts:
+- UI/UX design workflow optimized for solo developers
+- Component-first approach using shadcn/ui + Tailwind CSS
+- Multiple design tools: wireframes, MagicPatterns, SuperDesign
+- Dev-ready output: component strategies, layouts, user journeys
 
-#### `context-monitor.py`
+**Philosophy:**
+- Library-first: Start from "what existing component can I use?"
+- Decision-focused: Capture choices, not specifications
+- Speed over perfection: Working prototype beats perfect mockup
 
-Status line script showing:
-- Current model name
-- Working directory
-- Git branch
-- Context usage bar with percentage
-- Warnings at 75%, 90%, 95% usage
+```
+/designer-founder
+```
 
 ## Dependencies
 
@@ -203,8 +149,7 @@ Some components require the [BMAD Method](https://github.com/bmad-method) workfl
 - `/git-cleanup-and-merge`
 - `/plan-parallelization`
 - `/agent-creator` skill
-- `auto_approve_safe` hook
-- `context-monitor` status line
+- `/designer-founder` skill
 
 ## File Structure
 
@@ -219,17 +164,18 @@ After installation, files are placed in:
 ├── agents/
 │   ├── principal-code-reviewer.md
 │   └── story-prep-master.md
-├── skills/
-│   └── agent-creator/
-│       ├── SKILL.md
-│       ├── REGISTRY.yaml
-│       ├── STORY-AGENT-TEMPLATE.md
-│       ├── NON-STORY-AGENT-TEMPLATE.md
-│       └── COMMUNITY-REPOS.md
-└── scripts/
-    ├── auto_approve_safe.py
-    ├── auto_approve_safe.rules.json
-    └── context-monitor.py
+└── skills/
+    ├── agent-creator/
+    │   ├── SKILL.md
+    │   ├── REGISTRY.yaml
+    │   ├── STORY-AGENT-TEMPLATE.md
+    │   ├── NON-STORY-AGENT-TEMPLATE.md
+    │   └── COMMUNITY-REPOS.md
+    └── designer-founder/
+        ├── workflow.md
+        ├── steps/
+        ├── templates/
+        └── tools/
 ```
 
 ## Uninstallation
@@ -248,27 +194,11 @@ rm -rf .claude/commands/implement-epic-with-subagents.md \
        .claude/agents/principal-code-reviewer.md \
        .claude/agents/story-prep-master.md \
        .claude/skills/agent-creator \
-       .claude/scripts/auto_approve_safe.py \
-       .claude/scripts/auto_approve_safe.rules.json \
-       .claude/scripts/context-monitor.py
+       .claude/skills/designer-founder
 ```
 
-**Note**: Your `settings.local.json` is not modified—you may want to manually remove hook/statusLine configurations.
-
 ## Customization
 
-### Extending Auto-Approve Rules
-
-Edit `.claude/scripts/auto_approve_safe.rules.json`:
-
-```json
-{
-  "allow_patterns": [
-    "^your-custom-command"
-  ]
-}
-```
-
 ### Creating Custom Agents
 
 Use the `/agent-creator` skill to create project-specific agents:
@@ -294,6 +224,5 @@ Varun Torka
 
 ## Links
 
-- [GitHub Repository](https://github.com/varuntorka/vt-claude-workflows)
-- [Issue Tracker](https://github.com/varuntorka/vt-claude-workflows/issues)
 - [Claude Code Documentation](https://code.claude.com/docs)
+- [npm Package](https://www.npmjs.com/package/@torka/claude-workflows)

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,228 @@
+---
+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:
+
+```bash
+ls -la {sidecarFolder}/epic-*-state.yaml 2>/dev/null
+```
+
+**For each sidecar found, extract:**
+- Epic number (from filename pattern)
+- `current_phase` value
+- `worktree_config.worktree_path` (if present)
+- `stories_pending` count
+
+**Build sidecar list:**
+```
+sidecars_found:
+  - file: "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.
+
+Routing to continuation...
+```
+
+→ 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: `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.