@torka/claude-workflows 0.1.0

package/commands/plan-parallelization.md

@@ -0,0 +1,194 @@
+---
+description: 'Analyze epic files to identify which epics can run in parallel Git worktrees'
+---
+
+# Epic Parallelization Analysis Command
+
+You are a project planning analyst. Analyze the provided epic files to identify which **epics** can be worked on in parallel using Git worktrees. Each epic is treated as an atomic unit that will be implemented in a separate work session.
+
+**Key assumption**: Stories within an epic are handled sequentially in their own worktree session. This analysis focuses on epic-to-epic dependencies only.
+
+## Input Handling
+
+The user may provide one or more of:
+- Epic files (markdown files with story definitions)
+- Sprint status YAML file
+- Epic folder path
+
+<steps>
+1. **Context Detection (Auto)**
+
+   **Always check for sprint-status.yaml:**
+   - Look in `_bmad-output/implementation-artifacts/sprint-status.yaml`
+   - If found, read to get current epic/story status
+   - Determine epic-level status: an epic is "done" only if ALL its stories are done
+   - An epic is "in-progress" if ANY story is in-progress
+   - Otherwise epic is "pending"
+
+   **Check for previous parallelization plan:**
+   - Glob for `_bmad-output/planning-artifacts/parallelization-analysis-*.md`
+   - If found, read the most recent one
+   - This enables delta/comparison in the output
+
+2. **Identify and Load Input Files**
+   - If a folder is provided, glob for `epic-*.md` files
+   - Read all provided epic files completely
+   - If no specific input given, default to `_bmad-output/planning-artifacts/epics/`
+
+3. **Parse Epics (Treat as Atomic Units)**
+   For each epic file:
+   - Extract epic number and title from filename/header
+   - Parse all `## Story N.M:` sections to understand scope
+   - Capture ALL acceptance criteria across ALL stories (for dependency detection)
+   - Determine epic status from sprint-status (done/in-progress/pending)
+   - If file parsing fails, log warning and skip (don't crash)
+
+4. **Categorize Epics by Status**
+
+   | Epic Status | Condition | Include in Plan? |
+   |-------------|-----------|-----------------|
+   | done | ALL stories done | No (summary only) |
+   | in-progress | ANY story in-progress | Yes (active section) |
+   | pending | No stories started | Yes (pending section) |
+
+5. **Analyze Epic-to-Epic Dependencies**
+
+   Scan ALL acceptance criteria within an epic for CAPABILITY REFERENCES:
+
+   | When any story AC mentions... | Epic depends on... | How to find it |
+   |-------------------------------|-------------------|----------------|
+   | "email is sent", "verification email", "password reset email" | Email epic | Epic with *Email* in title |
+   | "user is authenticated", "signed in", "session", "logged in" | Auth epic | Epic with *Auth* in title |
+   | "admin user", "admin role", "admin access" | Admin epic | Epic with *Admin* in title |
+   | "analytics", "track event", "metrics" | Analytics epic | Epic with *Analytics* in title |
+   | "I have verified my email", "email verified" | Auth epic | Epic with *Auth* in title |
+   | "payment", "subscription", "billing" | Payments epic | Epic with *Payment* or *Billing* in title |
+   | "notification", "notify user" | Notifications epic | Epic with *Notification* in title |
+
+   **Key insight**: Match capability names in epic TITLES, not epic numbers.
+   This makes detection project-agnostic.
+
+   **Handle completed dependencies:**
+   - If a dependency epic is already "done", don't block waiting epics
+   - Mark as "dependency satisfied"
+
+6. **Build Epic Execution Plan for Worktrees**
+   Group remaining (non-done) epics into phases:
+   - **In Progress**: Epics currently being worked on
+   - **Phase 1**: Foundation epics (no pending dependencies) - can start worktrees in parallel
+   - **Phase 2+**: Epics that depend on earlier phases
+   - **Parallel Groups**: Epics within a phase that can have concurrent worktrees
+
+7. **Generate Output**
+   Create markdown report with:
+   - Context summary (what was detected)
+   - Epic-level progress summary
+   - What's changed since last analysis (if prior plan exists)
+   - Worktree execution phases (which epics can run in parallel)
+   - Epic dependency matrix
+   - Recommended worktree strategy
+
+8. **Save Report**
+   Write to: `_bmad-output/planning-artifacts/parallelization-analysis-{YYYY-MM-DD-HHmm}.md`
+   (Includes timestamp to prevent same-day collisions)
+</steps>
+
+## Output Template
+
+Use this structure for the report:
+
+```markdown
+# Epic Parallelization Analysis
+Generated: {date}
+
+## Context
+- **Sprint Status**: Found / Not Found
+- **Previous Plan**: Found ({date}) / Not Found
+- **Analysis Mode**: Fresh / Incremental
+- **Parse Warnings**: None / [list of skipped files]
+
+## Epic Progress Summary
+| Status | Epics | Stories | Percentage |
+|--------|-------|---------|------------|
+| Completed | X | Y | Z% |
+| In Progress | X | Y | Z% |
+| Pending | X | Y | Z% |
+| **Total** | X | Y | 100% |
+
+## What's Changed Since Last Analysis
+<!-- Only include if previous plan was found -->
+- **New Epics**: [list or "None"]
+- **Completed Epics**: [list of epics that moved to done]
+- **Status Changes**: [epics that changed status]
+
+## Currently In Progress (Active Worktrees)
+<!-- Epics with any in-progress stories -->
+| Epic | Title | Stories Done | Blocked By |
+|------|-------|--------------|------------|
+| 2 | User Authentication | 2/5 | None |
+
+## Worktree Execution Plan
+
+### Phase 1: Foundation Epics
+These epics have no pending dependencies - **start worktrees in parallel**:
+
+| Epic | Title | Stories | Depends On | Notes |
+|------|-------|---------|------------|-------|
+| 1 | Core Infrastructure | 3 | None | Foundation |
+| 3 | Email System | 4 | None | Independent |
+
+**Worktree commands:**
+```bash
+git worktree add ../epic-1-core-infrastructure feature/epic-1
+git worktree add ../epic-3-email-system feature/epic-3
+```
+
+### Phase 2: Dependent Epics
+**Requires**: Phase 1 completion (or specific epics noted)
+
+| Epic | Title | Stories | Depends On | Can Parallel With |
+|------|-------|---------|------------|-------------------|
+| 2 | User Auth | 5 | Epic 1 | Epic 4 |
+| 4 | Admin Dashboard | 3 | Epic 1 | Epic 2 |
+
+### Phase 3+
+[Continue pattern for remaining phases...]
+
+## Completed Epics
+<details>
+<summary>X epics completed (Y stories)</summary>
+
+| Epic | Title | Stories |
+|------|-------|---------|
+| ... | ... | ... |
+
+</details>
+
+## Epic Dependency Matrix
+
+| Epic | Title | Depends On | Dependency Status |
+|------|-------|------------|-------------------|
+| 2 | User Auth | Epic 1 (Infrastructure) | Pending |
+| 5 | Analytics | Epic 2 (Auth) | Pending |
+
+## Worktree Strategy Recommendations
+- **Max parallel worktrees**: [recommended number based on dependencies]
+- **Critical path**: Epic X → Epic Y → Epic Z
+- **Bottleneck epics**: [epics that block the most others]
+- **Quick wins**: [small epics that can be completed to unblock others]
+```
+
+## Important Notes
+- **Epic-level focus**: Treat each epic as an atomic unit for a separate worktree
+- Stories within an epic are NOT analyzed for cross-epic parallelization
+- Auto-detect context: never require user to specify "mode"
+- Sprint status is source of truth for completion (parse slugs: `2-1-foo` → `2.1`)
+- Epic is "done" only when ALL its stories are done
+- Epic is "in-progress" if ANY story is in-progress
+- Done epics are excluded from dependency blocking
+- Highlight NEW epics when comparing to prior plan
+- Match dependencies by CAPABILITY (epic titles like "Email", "Auth") not epic numbers
+- Gracefully skip malformed files with warnings
+- Include worktree commands for easy copy-paste
+- Identify critical path and bottleneck epics
+- Keep output concise but actionable

package/examples/settings.local.example.json

@@ -0,0 +1,57 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git branch:*)",
+      "Bash(git fetch:*)",
+      "Bash(gh pr:*)",
+      "Bash(gh repo:*)",
+      "Bash(npm test:*)",
+      "Bash(npm run:*)",
+      "WebSearch"
+    ],
+    "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/hooks/auto_approve_safe.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""
+Claude Code Hook: Auto-approve safe tool usage for solo dev workflows.
+
+Handles PreToolUse events to:
+- Auto-allow known-safe commands (read-only, tests, linting)
+- Deny obviously dangerous commands
+- Defer everything else to normal permission system ("ask")
+
+Install:
+  1. mkdir -p ~/.claude/hooks && chmod 700 ~/.claude/hooks
+  2. Save this file to ~/.claude/hooks/auto_approve_safe.py
+  3. chmod +x ~/.claude/hooks/auto_approve_safe.py
+  4. Add hook config to ~/.claude/settings.json
+"""
+
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# Max-autonomy default:
+# - Allow reads/searches
+# - Allow edits/writes except for sensitive paths
+# - Allow bash commands only if they match allowlist (supports simple compound commands)
+#
+# Debugging:
+# Set this to True temporarily to log every decision to a local jsonl file.
+ENABLE_DECISION_LOG = True
+
+
+def load_rules() -> dict:
+    """Load rules from global and project-specific config files."""
+    rules = {"allow_patterns": [], "deny_patterns": [], "sensitive_paths": []}
+
+    # # Load global rules
+    # global_rules_path = Path.home() / ".claude" / "hooks" / "auto_approve_safe.rules.json"
+    # if global_rules_path.exists():
+    #     try:
+    #         with open(global_rules_path) as f:
+    #             global_rules = json.load(f)
+    #             for key in rules:
+    #                 rules[key].extend(global_rules.get(key, []))
+    #     except (json.JSONDecodeError, IOError) as e:
+    #         print(f"Warning: Could not load global rules: {e}", file=sys.stderr)
+
+    # Load project-specific rules (merge with global)
+    project_rules_path = Path.cwd() / ".claude" / "scripts" / "auto_approve_safe.rules.json"
+    if project_rules_path.exists():
+        try:
+            with open(project_rules_path) as f:
+                project_rules = json.load(f)
+                for key in rules:
+                    rules[key].extend(project_rules.get(key, []))
+        except (json.JSONDecodeError, IOError) as e:
+            print(f"Warning: Could not load project rules: {e}", file=sys.stderr)
+
+    return rules
+
+
+def matches_any_pattern(text: str, patterns: list[str]) -> bool:
+    """Check if text matches any of the given regex patterns."""
+    for pattern in patterns:
+        try:
+            if re.search(pattern, text, re.IGNORECASE):
+                return True
+        except re.error:
+            continue
+    return False
+
+
+def check_sensitive_path(file_path: str, sensitive_patterns: list[str]) -> bool:
+    """Check if file path matches sensitive path patterns."""
+    if not file_path:
+        return False
+    return matches_any_pattern(file_path, sensitive_patterns)
+
+
+def split_compound_shell_command(command: str) -> list[str]:
+    """Split a shell command on simple compound operators (heuristic, not a full parser)."""
+    command = (command or "").strip()
+    if not command:
+        return []
+    # Common patterns produced by agents: `cd x && pnpm test`, `cmd1; cmd2`
+    return [p.strip() for p in re.split(r"\s*(?:&&|;)\s*", command) if p.strip()]
+
+
+def is_shell_file_read_command(command: str) -> bool:
+    """Detect common shell file-read commands that could exfiltrate secrets."""
+    return bool(re.search(r"^\s*(cat|head|tail|less)\b", command or "", re.IGNORECASE))
+
+
+def summarize_tool_input(tool_name: str, tool_input: dict) -> dict:
+    """Small, reviewable summary for decision logs."""
+    if tool_name == "Bash":
+        return {"command": tool_input.get("command", "")}
+    if tool_name in ("Read", "Write", "Edit", "MultiEdit"):
+        return {"file_path": tool_input.get("file_path", "")}
+    return {"tool_input_keys": list((tool_input or {}).keys())}
+
+
+def log_decision(tool_name: str, tool_input: dict, decision: str, reason: str) -> None:
+    """Append a decision record to a jsonl file when debugging is enabled."""
+    if not ENABLE_DECISION_LOG:
+        return
+
+    log_path = Path.cwd() / ".claude" / "auto_approve_safe.decisions.jsonl"
+    record = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "cwd": str(Path.cwd()),
+        "tool_name": tool_name,
+        "decision": decision,
+        "reason": reason,
+        "input": summarize_tool_input(tool_name, tool_input or {}),
+    }
+
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(log_path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except Exception as e:
+        # Never break tool execution because logging failed.
+        print(f"Warning: Could not write decision log: {e}", file=sys.stderr)
+
+
+def make_decision(tool_name: str, tool_input: dict, rules: dict) -> tuple[str, str]:
+    """
+    Determine permission decision for a tool call.
+
+    Returns:
+        tuple: (decision, reason)
+            decision: "allow", "deny", or "ask"
+            reason: Human-readable explanation
+
+    Notes on integration with Claude Code:
+      - "allow" short-circuits Claude Code prompts
+      - "deny" blocks the tool
+      - "ask" defers to Claude Code's built-in permission system
+
+    This file is tuned for maximum autonomy by default, while:
+      - denying obvious dangerous commands
+      - blocking edits to sensitive paths
+      - prompting for reads of sensitive paths
+    """
+    tool_input = tool_input or {}
+
+    # Handle Bash commands
+    if tool_name == "Bash":
+        command = (tool_input.get("command", "") or "").strip()
+        if not command:
+            return "ask", "Empty command"
+
+        segments = split_compound_shell_command(command)
+        if not segments:
+            return "ask", "Empty command"
+
+        # Deny wins if any segment matches a deny pattern.
+        for seg in segments:
+            if matches_any_pattern(seg, rules["deny_patterns"]):
+                return "deny", "Command matches dangerous pattern"
+
+        # If a segment looks like it could read a file, apply sensitive path checks.
+        # (Prevents silently allowing: `cat .env`, `head ~/.ssh/id_rsa`, etc.)
+        for seg in segments:
+            if is_shell_file_read_command(seg) and matches_any_pattern(seg, rules["sensitive_paths"]):
+                return "ask", "Bash command may read sensitive data"
+
+        # Max autonomy, but still require an allowlist match per segment.
+        # Add common "glue" patterns that agents use.
+        glue_allow_patterns = [
+            r"^cd\s+\S+(\s+.*)?$",
+            r"^pushd\s+\S+(\s+.*)?$",
+            r"^popd$",
+            r"^export\s+[A-Za-z_][A-Za-z0-9_]*=.*$",
+            r"^(true|false)$",
+        ]
+
+        for seg in segments:
+            if matches_any_pattern(seg, rules["allow_patterns"]):
+                continue
+            if matches_any_pattern(seg, glue_allow_patterns):
+                continue
+            return "ask", f"Command not in allowlist: {seg}"
+
+        return "allow", "Matches safe allowlist"
+
+    # Handle Read tool - check for sensitive files
+    if tool_name == "Read":
+        file_path = tool_input.get("file_path", "")
+        if check_sensitive_path(file_path, rules["sensitive_paths"]):
+            return "ask", "File may contain sensitive data"
+        return "allow", "Read operations are generally safe"
+
+    # Handle Grep/Glob - generally safe read-only operations
+    if tool_name in ("Grep", "Glob"):
+        return "allow", "Search operations are read-only"
+
+    # Handle Write/Edit - max autonomy by default; still protect sensitive paths.
+    if tool_name in ("Write", "Edit", "MultiEdit"):
+        file_path = tool_input.get("file_path", "")
+        if check_sensitive_path(file_path, rules["sensitive_paths"]):
+            return "deny", "Cannot modify sensitive files"
+        return "allow", "Write operations are generally safe"
+
+    # Default: defer to normal permission system
+    return "ask", "Unknown tool, deferring to permission system"
+
+
+def output_decision(decision: str, reason: str) -> None:
+    """Output the hook decision in Claude Code's expected format."""
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": decision,
+            "permissionDecisionReason": reason
+        }
+    }
+    print(json.dumps(output))
+
+
+def main():
+    """Main entry point for the hook."""
+    try:
+        # Read input from stdin
+        input_data = sys.stdin.read()
+        if not input_data.strip():
+            output_decision("ask", "No input received")
+            return
+
+        data = json.loads(input_data)
+
+        # Extract tool information
+        tool_name = data.get("tool_name", "")
+        tool_input = data.get("tool_input", {})
+
+        # Load rules
+        rules = load_rules()
+
+        # Make decision
+        decision, reason = make_decision(tool_name, tool_input, rules)
+
+        # Optional debug log
+        log_decision(tool_name, tool_input, decision, reason)
+
+        # Output result
+        output_decision(decision, reason)
+
+    except json.JSONDecodeError as e:
+        print(f"Error parsing input JSON: {e}", file=sys.stderr)
+        output_decision("ask", "Failed to parse input")
+    except Exception as e:
+        print(f"Hook error: {e}", file=sys.stderr)
+        output_decision("ask", f"Hook error: {e}")
+
+
+if __name__ == "__main__":
+    main()
+
+

package/hooks/auto_approve_safe.rules.json

@@ -0,0 +1,134 @@
+{
+  "allow_patterns": [
+    "^pwd$",
+    "^whoami$",
+    "^date$",
+    "^uname(\\s+-a)?$",
+    "^which\\s+\\S+$",
+    "^echo\\s+",
+
+    "^ls(\\s+.*)?$",
+    "^cat\\s+",
+    "^head\\s+",
+    "^tail\\s+",
+    "^wc\\s+",
+    "^less\\s+",
+    "^file\\s+",
+    "^stat\\s+",
+    "^du\\s+",
+    "^df\\s+",
+    "^tree(\\s+.*)?$",
+
+    "^python(3)?\\s+--version$",
+    "^node\\s+--version$",
+    "^npm\\s+--version$",
+    "^pnpm\\s+--version$",
+    "^yarn\\s+--version$",
+    "^uv\\s+--version$",
+
+    "^git\\s+(status|diff|log|show|branch|remote|stash\\s+list)(\\s+.*)?$",
+
+    "^pnpm\\s+(test|run\\s+(test|lint|typecheck|type-check|check|build|dev|start)|install|i|add|remove)(\\s+.*)?$",
+    "^npm\\s+(test|run\\s+(test|lint|typecheck|type-check|check|build|dev|start)|install|i|ci)(\\s+.*)?$",
+    "^yarn\\s+(test|lint|typecheck|type-check|check|build|dev|start|install|add|remove)(\\s+.*)?$",
+    "^npx\\s+(tsc|eslint|prettier|vitest|jest)(\\s+.*)?$",
+
+    "^pytest(\\s+.*)?$",
+    "^python(3)?\\s+-m\\s+pytest(\\s+.*)?$",
+    "^uv\\s+run\\s+(pytest|python|ruff|mypy)(\\s+.*)?$",
+    "^ruff\\s+(check|format)(\\s+.*)?$",
+    "^mypy(\\s+.*)?$",
+    "^black\\s+--check(\\s+.*)?$",
+    "^isort\\s+--check(\\s+.*)?$",
+    "^pip\\s+(list|show|freeze)$",
+    "^uv\\s+(pip\\s+list|pip\\s+show|sync|lock)(\\s+.*)?$",
+
+    "^cargo\\s+(check|test|clippy|fmt\\s+--check|build)(\\s+.*)?$",
+    "^go\\s+(test|vet|fmt|build)(\\s+.*)?$",
+
+    "^jq\\s+",
+    "^grep\\s+",
+    "^rg\\s+",
+    "^find\\s+",
+    "^fd\\s+",
+    "^ag\\s+",
+    "^awk\\s+",
+    "^sed\\s+-n\\s+",
+    "^sort(\\s+.*)?$",
+    "^uniq(\\s+.*)?$",
+    "^cut\\s+",
+    "^tr\\s+",
+    "^diff\\s+",
+    "^comm\\s+",
+
+    "^curl\\s+.*--head",
+    "^curl\\s+-I\\s+",
+    "^ping\\s+-c\\s+\\d+\\s+",
+    "^dig\\s+",
+    "^nslookup\\s+",
+    "^host\\s+",
+
+    "^mkdir(\\s+.*)?$",
+    "^touch\\s+",
+    "^cp\\s+",
+    "^mv\\s+",
+
+    "^git\\s+(add|commit|checkout|fetch|pull|push|worktree|merge|rebase|stash\\s+(push|pop|drop|apply)|tag|switch|restore)(\\s+.*)?$",
+
+    "^gh\\s+(pr|issue|repo|release|workflow|run|api)(\\s+.*)?$",
+
+    "^chmod\\s+[0-6][0-7][0-7]\\s+"
+  ],
+
+  "deny_patterns": [
+    "^sudo\\b",
+    "^doas\\b",
+    "\\brm\\s+.*(-r|-rf|-fr|--recursive)",
+    "\\brm\\s+-[^\\s]*r",
+    "^rm\\s+/",
+    "\\bmkfs\\.",
+    "\\bdd\\b.*\\bof=",
+    "\\bshutdown\\b",
+    "\\breboot\\b",
+    "\\bsystemctl\\s+(start|stop|restart|enable|disable)",
+    "\\bchmod\\s+777",
+    "\\bchown\\s+.*:.*\\s+/",
+    ">\\s*/etc/",
+    ">\\s*~/\\.",
+    "\\bcurl\\b.*\\|.*\\b(bash|sh|zsh)\\b",
+    "\\bwget\\b.*\\|.*\\b(bash|sh|zsh)\\b",
+    "\\beval\\s+.*\\$\\(",
+    ":(){ :|:& };:",
+    "\\bfork\\s*bomb",
+    "\\bkill\\s+-9\\s+-1",
+    "\\bpkill\\s+-9",
+    "\\bkillall\\b"
+  ],
+
+  "sensitive_paths": [
+    "\\.env$",
+    "\\.env\\.",
+    "\\.pem$",
+    "\\.key$",
+    "\\.crt$",
+    "\\.p12$",
+    "\\.pfx$",
+    "id_rsa",
+    "id_ed25519",
+    "id_ecdsa",
+    "\\.ssh/",
+    "\\.gnupg/",
+    "\\.git/config$",
+    "\\.gitconfig$",
+    "credentials",
+    "\\.aws/",
+    "\\.gcloud/",
+    "\\.azure/",
+    "\\.npmrc$",
+    "\\.pypirc$",
+    "\\.netrc$",
+    "\\bsecrets?\\b",
+    "\\bpassw",
+    "\\btoken"
+  ]
+}