@torka/claude-workflows 0.12.0 → 0.13.2

package/.claude-plugin/plugin.json

@@ -18,6 +18,10 @@
     {
       "name": "github-pr-resolve",
       "description": "Assess open PRs, handle review comments, run CI, and merge"
+    },
+    {
+      "name": "deep-audit",
+      "description": "Multi-agent codebase audit across security, architecture, error handling, and more"
     }
   ],
   "agents": [
@@ -38,6 +42,10 @@
     {
       "name": "product-architect",
       "description": "Agent team that creates PRD + Architecture from product notes. PM and Architect collaborate, escalating only for key decisions."
+    },
+    {
+      "name": "deep-audit",
+      "description": "Agent prompts and templates for the deep-audit codebase audit"
     }
   ],
   "hooks": {

package/README.md

@@ -11,6 +11,7 @@ Claude Code workflow helpers for epic automation, git management, and developer
 | **Agent Creator** | Design and deploy custom Claude Code agents | Yes |
 | **Designer-Founder** | Transform ideas into dev-ready frontend artifacts | Yes |
 | **Epic Orchestration** | Automate multi-story epic execution with sub-agents | Requires BMAD |
+| **Deep Audit** | Multi-agent codebase audit (security, architecture, performance, etc.) | Yes |
 | **Code Review Agent** | Principal-level code review automation | Requires BMM |
 | **Story Prep Agent** | Convert requirements to developer-ready specs | Requires BMM |
 
@@ -42,6 +43,36 @@ After installation, try running one of the commands to test:
 /designer-founder
 ```
 
+### Auto-Format on Edit (optional)
+
+Auto-run linters and formatters after Claude edits files. Add to your project's `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "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; elif [[ \"$CLAUDE_TOOL_FILE_PATH\" == *.py ]]; then pylint \"$CLAUDE_TOOL_FILE_PATH\" 2>/dev/null || true; fi"
+          },
+          {
+            "type": "command",
+            "command": "if [[ \"$CLAUDE_TOOL_FILE_PATH\" == *.js || \"$CLAUDE_TOOL_FILE_PATH\" == *.ts || \"$CLAUDE_TOOL_FILE_PATH\" == *.jsx || \"$CLAUDE_TOOL_FILE_PATH\" == *.tsx || \"$CLAUDE_TOOL_FILE_PATH\" == *.json || \"$CLAUDE_TOOL_FILE_PATH\" == *.css || \"$CLAUDE_TOOL_FILE_PATH\" == *.html ]]; then npx prettier --write \"$CLAUDE_TOOL_FILE_PATH\" 2>/dev/null || true; elif [[ \"$CLAUDE_TOOL_FILE_PATH\" == *.py ]]; then black \"$CLAUDE_TOOL_FILE_PATH\" 2>/dev/null || true; elif [[ \"$CLAUDE_TOOL_FILE_PATH\" == *.go ]]; then gofmt -w \"$CLAUDE_TOOL_FILE_PATH\" 2>/dev/null || true; elif [[ \"$CLAUDE_TOOL_FILE_PATH\" == *.rs ]]; then rustfmt \"$CLAUDE_TOOL_FILE_PATH\" 2>/dev/null || true; elif [[ \"$CLAUDE_TOOL_FILE_PATH\" == *.php ]]; then php-cs-fixer fix \"$CLAUDE_TOOL_FILE_PATH\" 2>/dev/null || true; fi"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Supported languages:** JavaScript/TypeScript (ESLint + Prettier), Python (Pylint + Black), Go (gofmt), Rust (rustfmt), PHP (php-cs-fixer)
+
+> **Note:** This is a project-level setting — formatter choice varies per project. Commands fail silently (`|| true`) if tools aren't installed.
+
 ## Usage
 
 ### Commands
@@ -83,6 +114,17 @@ Orchestrates sub-agents to execute all stories in an epic sequentially with mini
 /implement-epic-with-subagents
 ```
 
+#### `/deep-audit`
+
+Multi-agent codebase audit across security, architecture, error handling, and more:
+- 9 specialized audit agents run in parallel
+- Covers security, performance, code health, test coverage, accessibility, and more
+- Generates a consolidated report with prioritized findings
+
+```
+/deep-audit
+```
+
 ### Agents
 
 #### `principal-code-reviewer`
@@ -148,6 +190,7 @@ Some components require the [BMAD Method](https://github.com/bmad-method) workfl
 **Standalone components** (no external dependencies):
 - `/git-cleanup-and-merge`
 - `/plan-parallelization`
+- `/deep-audit`
 - `/agent-creator` skill
 - `/designer-founder` skill
 
@@ -171,11 +214,15 @@ After installation, files are placed in:
     │   ├── STORY-AGENT-TEMPLATE.md
     │   ├── NON-STORY-AGENT-TEMPLATE.md
     │   └── COMMUNITY-REPOS.md
-    └── designer-founder/
-        ├── workflow.md
-        ├── steps/
-        ├── templates/
-        └── tools/
+    ├── designer-founder/
+    │   ├── workflow.md
+    │   ├── steps/
+    │   ├── templates/
+    │   └── tools/
+    └── deep-audit/
+        ├── SKILL.md
+        ├── agents/          # 9 audit agent prompts
+        └── templates/
 ```
 
 ## Uninstallation

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

@@ -221,15 +221,22 @@ Options:
 ### 7. Handle Menu Selection
 
 #### IF C (Continue):
-1. Update sidecar:
+1. CRITICAL: Execution log entries in the sidecar are **immutable history**.
+   When updating the sidecar, APPEND new entries to the `execution_log` array -
+   **never replace or truncate** the existing entries. All completed story records
+   must be preserved through session continuations. Use a read-modify-append
+   pattern: read the current execution_log, then add new entries at the end.
+
+2. Update sidecar (APPEND to existing execution_log):
    ```yaml
    execution_log:
+     # ... all existing entries preserved ...
      - event: "session_resumed"
        timestamp: "{current_timestamp}"
        from_phase: "{current_phase}"
    last_updated: "{current_timestamp}"
    ```
-2. Route based on scenario:
+3. Route based on scenario:
    - Scenario A/B → load, read entire file, then execute `{nextStepFile}`
    - Scenario C → load, read entire file, then execute `{completionStepFile}`
 

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

@@ -67,6 +67,18 @@ To autonomously execute all pending stories in the epic by orchestrating special
 - ✅ You handle failures gracefully with retry or escalation
 - ✅ You output brief progress after each story completion
 
+### Orchestrator Tool Guidance:
+
+As orchestrator, your primary tool is Task (spawning agents). Avoid using Edit or Bash
+on source code files - delegate ALL development work to sub-agents.
+
+When a phase produces issues that need fixing (review rejections, test failures, desk-check
+changes requested), spawn the dev agent again with the fix context rather than editing
+code yourself.
+
+**Reserve direct Edit for:** sidecar files and sprint-status.yaml only.
+**Reserve direct Bash for:** git commands and file existence checks only.
+
 ### Step-Specific Rules:
 
 - 🎯 Execute stories in linear order from pending list
@@ -130,6 +142,11 @@ Task tool:
     story_file: [path to created story]
     blockers: none | [list]
     next_action: proceed | escalate
+
+    # Retrospective (for orchestrator learning)
+    went_well: [what worked smoothly in this phase]
+    challenges: [what was difficult or didn't go well]
+    suggestions: [what could be improved for future stories]
     === END HANDOFF ===
 ```
 
@@ -173,6 +190,10 @@ Task tool:
     Write tests first (red-green-refactor).
     Mark tasks complete as you finish them.
 
+    Test Strategy: Run TARGETED tests (npm test -- --filter "{test-file}")
+    during development. The full test suite runs ONCE at the end of all tasks
+    (Step 8.1 Final Verification). Do NOT run the full suite after each task.
+
     Available MCP Tools (use if available):
     - Serena MCP: Code intelligence for navigation, refactoring
     - Context7 MCP: Documentation lookup
@@ -193,6 +214,11 @@ Task tool:
     blockers: none | [list]
     next_action: proceed | escalate | retry
     error_summary: null | [description]
+
+    # Retrospective (for orchestrator learning)
+    went_well: [what worked smoothly in this phase]
+    challenges: [what was difficult or didn't go well]
+    suggestions: [what could be improved for future stories]
     === END HANDOFF ===
 ```
 
@@ -236,12 +262,50 @@ Task tool:
       screenshots_folder: {screenshotsFolder}/story-N.M/
 
     Perform visual inspection per agent protocol.
+
+    Include these retrospective fields in your handoff:
+    # Retrospective (for orchestrator learning)
+    went_well: [what worked smoothly in this phase]
+    challenges: [what was difficult or didn't go well]
+    suggestions: [what could be improved for future stories]
+
     Output handoff when complete.
 ```
 
 **Parse handoff and route:**
 - `check_status: approved` → Phase D (Code Review)
-- `check_status: changes_requested` → Story already annotated by agent, back to Phase B
+- `check_status: changes_requested` → Spawn the dev agent (Opus) to fix visual issues:
+
+  ```
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "opus"
+    description: "Fix desk-check issues story N.M"
+    prompt: |
+      You are a developer agent fixing visual/desk-check issues.
+      Load and embody: [same specialist agent path used in Phase B]
+
+      Story file: [story_path]
+      IMPORTANT: Re-read the story file FIRST. The desk-check agent may have
+      annotated it with "Desk Check Feedback" or "Desk Check Review" sections
+      containing specific notes and change requests. The dev-story commands
+      (Step 4.2) already have review feedback detection - leverage this.
+
+      Files that were changed: [files_changed from Phase B dev handoff]
+
+      Desk-Check Findings to Fix:
+      [paste the desk-check handoff findings/annotations]
+      Screenshots: [screenshot paths if any]
+
+      Fix all visual issues identified by the desk-check agent.
+      Run targeted tests to verify fixes don't break anything.
+
+      Output handoff using the standard AGENT HANDOFF format.
+  ```
+
+  After fix completes → re-run Phase C (desk check) for verification.
+  Maximum desk-check fix cycles: {maxRetries}
+
 - `check_status: rejected` → Escalate to user with `escalation_reason`
 
 **Pass visual context to Code Review (Phase D):**
@@ -303,12 +367,49 @@ Task tool:
       suggestions: [count]
     summary: [brief summary]
     next_action: proceed | fix_required | escalate
+
+    # Retrospective (for orchestrator learning)
+    went_well: [what worked smoothly in this phase]
+    challenges: [what was difficult or didn't go well]
+    suggestions: [what could be improved for future stories]
     === END HANDOFF ===
 ```
 
 **Parse handoff:**
 - If review_status=approved → proceed to Phase E
-- If review_status=changes_requested → go back to Phase B (with review feedback)
+- If review_status=changes_requested → Spawn the dev agent (Opus) to fix code issues:
+
+  ```
+  Task tool:
+    subagent_type: "general-purpose"
+    model: "opus"
+    description: "Fix review issues story N.M"
+    prompt: |
+      You are a developer agent fixing code review findings.
+      Load and embody: [same specialist agent path used in Phase B]
+
+      Story file: [story_path]
+      IMPORTANT: Re-read the story file FIRST. The code reviewer may have
+      annotated it with "Senior Developer Review (AI)", "Code Review", or
+      "Review Follow-ups (AI)" sections containing specific findings and
+      change requests. The dev-story commands (Step 4.2) already have
+      review feedback detection - leverage this.
+
+      Files that were changed: [files_changed from Phase B dev handoff]
+
+      Code Review Findings to Fix:
+      [paste the review findings from handoff]
+
+      Fix all critical and major findings.
+      Run targeted tests to verify fixes.
+      Run full test suite once after all fixes.
+
+      Output handoff using the standard AGENT HANDOFF format.
+  ```
+
+  After fix completes → re-submit to Phase D (code review) for verification.
+  Maximum review fix cycles: {maxRetries}
+
 - If review_status=rejected → escalate to user
 
 ---
@@ -322,6 +423,11 @@ last_updated: "[timestamp]"
 ```
 
 **Execute git commit:**
+
+Pre-commit hooks run the full test suite. Do NOT run tests separately before committing -
+the hook handles it. If the commit hook fails tests, investigate and fix (spawn dev agent
+if needed), then re-attempt the commit.
+
 ```bash
 git add .
 git commit -m "feat(story-N.M): [story title]

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

@@ -332,7 +332,41 @@ Pull Request Created
 - Created: [timestamp]
 ```
 
-### 6.5 Worktree Cleanup (Conditional)
+### 6.5 Manual Testing Recommendations
+
+Generate a concise list of key items the user should manually test:
+
+**Analysis approach:**
+1. For each completed story, identify the primary user-facing feature or change
+2. Prioritize items that involve:
+   - New user flows (registration, form submission, navigation)
+   - API integrations (external services, auth flows)
+   - Visual/UI changes (responsive design, dark mode, new pages)
+   - Data operations (CRUD, search, filtering)
+3. Skip items that are purely internal/infrastructure
+
+**Display format:**
+```
+## Recommended Manual Testing
+
+Before merging, verify these key flows:
+
+1. **[Feature name]** (Story N.M)
+   - [ ] [Specific action to test]
+   - [ ] [Expected result to verify]
+
+2. **[Feature name]** (Story N.M)
+   - [ ] [Specific action to test]
+   - [ ] [Expected result to verify]
+
+Environment: {dev_server config}
+Test credentials: {test_credentials if applicable}
+```
+
+**Purpose:** Complement automated tests with human verification of
+end-to-end user experience before PR merge.
+
+### 6.6 Worktree Cleanup (Conditional)
 
 **Skip this section if:**
 - `execution_mode.type` = "main" (not using worktree)