claude-mcp-workflow 0.1.0

package/hooks/workflow-cleanup.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# SessionEnd hook: abandon active workflow sessions for this Claude Code instance.
+# Skips sessions referenced in plan files (they should survive context clears).
+# Modifies JSON files directly — does NOT depend on MCP server / dashboard being alive.
+read -t 1 -r INPUT
+STATE_DIR="${STATE_DIR:-$HOME/.claude/workflow-state}"
+PLANS_DIR="$HOME/.claude/plans"
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
+ABANDONED_SIDS=()
+
+for f in "$STATE_DIR"/*.json; do
+  [ -f "$f" ] || continue
+  SID=$(jq -r "select(.stack | length > 0) | select(.context.claude_code_pid == $PPID) | .session_id" "$f" 2>/dev/null)
+  [ -n "$SID" ] || continue
+  # Skip if session referenced in plan files
+  [ -d "$PLANS_DIR" ] && grep -rql "$SID" "$PLANS_DIR"/ 2>/dev/null && continue
+  # Abandon: clear stack, set outcome, append history entry
+  TMP="${f}.tmp"
+  jq --arg now "$NOW" '
+    .history += [{ frame: .active_frame, event: "abandon", at: $now }] |
+    .stack = [] |
+    .active_frame = -1 |
+    .outcome = "abandoned" |
+    .updated_at = $now
+  ' "$f" > "$TMP" 2>/dev/null && mv "$TMP" "$f" || rm -f "$TMP"
+  ABANDONED_SIDS+=("$SID")
+done
+
+# Cascade: abandon children of abandoned sessions
+cascade_abandon() {
+  local parent_sid="$1"
+  for f in "$STATE_DIR"/*.json; do
+    [ -f "$f" ] || continue
+    local child_sid
+    child_sid=$(jq -r --arg pid "$parent_sid" 'select(.parent_session_id == $pid) | select(.stack | length > 0) | .session_id' "$f" 2>/dev/null)
+    [ -n "$child_sid" ] || continue
+    TMP="${f}.tmp"
+    jq --arg now "$NOW" '
+      .history += [{ frame: .active_frame, event: "cascade_abandon", at: $now }] |
+      .stack = [] |
+      .active_frame = -1 |
+      .outcome = "abandoned" |
+      .updated_at = $now
+    ' "$f" > "$TMP" 2>/dev/null && mv "$TMP" "$f" || rm -f "$TMP"
+    cascade_abandon "$child_sid"
+  done
+}
+
+for sid in "${ABANDONED_SIDS[@]}"; do
+  cascade_abandon "$sid"
+done

package/hooks/workflow-start.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# SessionStart hook: detect context (new session / plan resume / context clear)
+# and instruct agent accordingly.
+
+# --- 0. Ensure base skills exist ---
+# lang-* skills are dependencies of coding-skill-selector — only copied together with it.
+# If user deletes a lang-* skill, it stays deleted until coding-skill-selector is also removed.
+SKILLS_SRC="${CLAUDE_PLUGIN_ROOT}/templates/skills"
+SKILLS_DST="$HOME/.claude/skills"
+if [ -d "$SKILLS_SRC" ]; then
+  mkdir -p "$SKILLS_DST"
+  COPY_LANG=false
+  [ ! -d "$SKILLS_DST/coding-skill-selector" ] && COPY_LANG=true
+  for skill_dir in "$SKILLS_SRC"/*/; do
+    [ -d "$skill_dir" ] || continue
+    skill_name=$(basename "$skill_dir")
+    if [ "$COPY_LANG" = false ] && [[ "$skill_name" == lang-* ]]; then continue; fi
+    if [ ! -d "$SKILLS_DST/$skill_name" ]; then
+      cp -r "$skill_dir" "$SKILLS_DST/$skill_name"
+    fi
+  done
+fi
+
+read -t 1 -r INPUT
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+STATE_DIR="${STATE_DIR:-$HOME/.claude/workflow-state}"
+PLANS_DIR="$HOME/.claude/plans"
+
+ZED_SUFFIX=""
+if [[ -n "$ZED_ENVIRONMENT" ]]; then
+  ZED_SUFFIX=" Then load skill ide-zed (Skill tool)."
+fi
+
+# --- Helper: find active planning session from plan files ---
+find_plan_session() {
+  [ -d "$PLANS_DIR" ] || return
+  for plan in "$PLANS_DIR"/*.md; do
+    [ -f "$plan" ] || continue
+    # Extract session ID from ## Workflow section (Session line: `<hex>`)
+    local sid
+    sid=$(grep -A5 '^## Workflow' "$plan" | grep 'Session' | grep -oE '[a-f0-9]{7,}' | head -1)
+    [ -n "$sid" ] || continue
+    # Check if this session is active and in planning state
+    local state_file="$STATE_DIR/${sid}.json"
+    [ -f "$state_file" ] || continue
+    local wf
+    wf=$(jq -r 'select(.stack | length > 0) | .stack[-1].workflow // empty' "$state_file" 2>/dev/null)
+    if [ "$wf" = "planning" ]; then
+      echo "$sid"
+      return
+    fi
+  done
+}
+
+# --- 1. Transcript exists and has content → same process ---
+if [ -n "$TRANSCRIPT" ] && [ -s "$TRANSCRIPT" ]; then
+  # Check for ExitPlanMode → plan resume after context clear
+  if grep -q 'ExitPlanMode' "$TRANSCRIPT" 2>/dev/null; then
+    PLAN_SID=$(grep -oE 'transition\(\\"[a-f0-9]+\\"' "$TRANSCRIPT" | tail -1 | grep -oE '[a-f0-9]{7,}')
+    if [ -n "$PLAN_SID" ]; then
+      echo "PLAN RESUME (same process): call transition(\"$PLAN_SID\", \"planned\") to resume planning session.$ZED_SUFFIX"
+      exit 0
+    fi
+  fi
+  # Has content but no plan → context clear
+  echo "Context was cleared. Call status() to check for active session and restore context.$ZED_SUFFIX"
+  exit 0
+fi
+
+# --- 2. Transcript empty or missing → new process ---
+# Check plans/ for active planning sessions (cross-process plan resume)
+PLAN_SID=$(find_plan_session)
+if [ -n "$PLAN_SID" ]; then
+  echo "PLAN RESUME (new process): active planning session $PLAN_SID found. Call transition(\"$PLAN_SID\", \"planned\") to resume.$ZED_SUFFIX"
+  exit 0
+fi
+
+# --- 3. Nothing found → fresh start ---
+echo "STOP. Call mcp__plugin_workflow_wf__start (no args) first.$ZED_SUFFIX"

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "claude-mcp-workflow",
+  "version": "0.1.0",
+  "description": "Structured workflow orchestration for AI agents via finite-state machines",
+  "author": "AxGord <axgord@gmail.com> (https://github.com/AxGord)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AxGord/claude-workflow.git"
+  },
+  "homepage": "https://github.com/AxGord/claude-workflow",
+  "type": "module",
+  "main": "build/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node build/index.js"
+  },
+  "dependencies": {
+    "@dagrejs/dagre": "^1.1.4",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "express": "^4.21.0",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.6.0",
+    "zod": "^3.24.0"
+  },
+  "files": [
+    "build/",
+    "templates/",
+    "hooks/",
+    "dashboard/",
+    ".claude-plugin/",
+    ".mcp.json"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "typescript": "^5.7.0"
+  }
+}

package/templates/bug-fix.yaml

@@ -0,0 +1,283 @@
+name: bug-fix
+description: "Standard bug fix workflow"
+initial: classify
+max_transitions: 50
+
+states:
+  classify:
+    task: "Classify bug type"
+    prompt: |
+      Classify the bug before proceeding.
+
+      Look at the user's report:
+      - Does it include a screenshot or describe a VISUAL problem (layout, overlap, wrong color, missing element)?
+      - Or is it a LOGIC problem (wrong data, crash, incorrect calculation, serialization error)?
+
+      Choose:
+      - `visual` → UI/layout bug — requires debug bridge, screenshots, visual reproduction
+      - `logic` → data/logic bug — reproducible via unit tests or logs
+    transitions:
+      visual: reproduce_visual
+      logic: reproduce_logic
+
+  reproduce_visual:
+    task: "Reproduce the bug visually"
+    prompt: |
+      Reproduce the bug VISUALLY before proceeding — reading code is NOT reproduction.
+
+      DO NOT fix the bug here. You may add trace/log statements to help reproduce,
+      but do NOT modify production logic. The fix belongs in the `fix` state.
+
+      MANDATORY STEPS (all required, in order):
+      1. Understand the exact user path that triggers the bug (which button, which file, which action)
+      2. Build and launch the app with debug bridge (`-debug -DFASTBOOT -DDEBUG_API -DHEADLESS`)
+      3. Follow the SAME path the user described to trigger the bug
+      4. Take a screenshot and VERIFY the bug is visible
+      5. Describe what you see — compare with the user's report
+
+      STOP — self-check before transitioning:
+      - Did you LAUNCH the app and take a SCREENSHOT? If not, you haven't reproduced.
+      - Can you show the screenshot? If not, you haven't reproduced yet.
+      - "I can see from the code that..." is NOT evidence. Run the app.
+
+      DO NOT skip visual reproduction. Running unit tests is NOT reproduction for visual bugs.
+      DO NOT transition to `reproduced` without a screenshot proving the bug exists.
+
+      If the bug requires file operations, use the tm-interactive-debug skill recipes.
+    transitions:
+      reproduced: diagnose
+      cant_reproduce: clarify
+
+  reproduce_logic:
+    task: "Reproduce the bug with tests"
+    prompt: |
+      Reproduce the bug by EXECUTING code — reading source is NOT reproduction.
+
+      DO NOT fix the bug here. You may add trace/log statements or write test code
+      to help reproduce, but do NOT modify production logic. The fix belongs in the `fix` state.
+
+      MANDATORY STEPS (all required, in order):
+      1. Understand the exact scenario that triggers the bug
+      2. Write a minimal FAILING test that demonstrates the wrong behavior
+      3. BUILD and RUN the test — show the actual output
+      4. Describe: EXPECTED vs ACTUAL — what should happen vs what does happen
+
+      STOP — self-check before transitioning:
+      - Did you EXECUTE something (build + run)? Reading code ≠ reproduction.
+      - Can you paste the failing output? If not, you haven't reproduced yet.
+      - "I can see from the code that..." is NOT evidence. Run the code.
+
+      DO NOT transition to `reproduced` without concrete executed evidence
+      (test failure output, wrong runtime output, crash log).
+
+      If the bug is hard to cover with a unit test (UI state, complex setup, timing),
+      transition `try_visual` to reproduce via debug bridge instead.
+    transitions:
+      reproduced: diagnose
+      try_visual: reproduce_visual
+      cant_reproduce: clarify
+
+  diagnose:
+    task: "Diagnose root cause"
+    prompt: |
+      Find the root cause of the bug.
+
+      DO NOT fix the bug here. You may add trace/log statements to narrow down
+      the cause, but do NOT modify production logic. The fix belongs in the `fix` state.
+
+      After diagnosing, assess how many files need fixing:
+      - 1 file → `single`
+      - 2+ files → `multi`
+    transitions:
+      single: fix_single
+      multi: fix_delegate
+      unclear: add_logging
+
+  add_logging:
+    task: "Add diagnostic logging"
+    prompt: "Add logging for diagnostics, run again."
+    max_visits: 3
+    transitions:
+      single: fix_single
+      multi: fix_delegate
+      still_unclear: escalate
+
+  fix_single:
+    sub_workflow: file-code
+    on_complete: review
+    on_fail: review
+
+  fix_delegate:
+    task: "Delegate per-file fixes to agents"
+    prompt: |
+      MANDATORY FIRST ACTION — call `Skill("coding-skill-selector")` to load language/domain skills BEFORE doing anything else in this state. Do NOT skip this step.
+
+      The fix spans multiple files. Produce a per-file plan with interface contracts,
+      then spawn one Agent per file for parallel implementation.
+      Use `subagent_type="general-purpose"`, `model="opus"`.
+
+      For each file, include in the agent prompt VERBATIM:
+      ---
+      IMPORTANT: Override the default CLAUDE.md rule about start().
+      Do NOT call start() without arguments.
+      Instead, your FIRST action must be:
+        mcp__plugin_workflow_wf__start({ workflow: "file-code", parent_session_id: "<SESSION_ID>" })
+      where <SESSION_ID> is the current session ID (substitute it before sending).
+      Then follow the file-code workflow states until completion.
+      ---
+      Also include:
+      - The file path
+      - The diagnosis and root cause
+      - The per-file fix plan
+      - Interface contracts with other files
+
+      Launch ALL file agents in parallel. Wait for all to complete. Collect reports.
+
+      After ALL reports are collected:
+      1. Abort orphaned child workflow sessions.
+      2. Transition `done`.
+    transitions:
+      done: integrate
+
+  integrate:
+    task: "Cross-file integration check"
+    prompt: |
+      All file agents have completed. Verify integration:
+
+      1. **Interface contracts** — do all files satisfy the contracts?
+      2. **Import resolution** — are all cross-file imports correct?
+      3. **Conflict resolution** — did agents make conflicting assumptions? Fix any.
+      4. **Missing glue** — any wiring code needed?
+
+      Fix any issues found directly. Then → transition `done`.
+    transitions:
+      done: review
+
+  review:
+    task: "Route review by scope"
+    prompt: |
+      Route to the correct review approach based on how many files were changed:
+      - `single` → 1 file changed
+      - `multi` → 2+ files changed
+    transitions:
+      single: review_single
+      multi: review_delegate
+
+  review_single:
+    sub_workflow: file-review
+    on_complete: test
+    on_fail: write_fix
+
+  review_delegate:
+    task: "Delegate per-file review to agents"
+    prompt: |
+      Spawn one Agent per changed file for deep review.
+      Use `subagent_type="general-purpose"`, `model="opus"`.
+
+      For each file, include in the agent prompt VERBATIM:
+      ---
+      IMPORTANT: Override the default CLAUDE.md rule about start().
+      Do NOT call start() without arguments.
+      Instead, your FIRST action must be:
+        mcp__plugin_workflow_wf__start({ workflow: "file-review", parent_session_id: "<SESSION_ID>" })
+      where <SESSION_ID> is the current session ID (substitute it before sending).
+      Then follow the file-review workflow states until completion.
+      ---
+      Also include:
+      - The file path
+      - How to get the diff: `git diff HEAD -- <filepath>`
+      - Review scope: `diff`
+
+      Launch ALL file agents in parallel. Collect reports.
+
+      After ALL reports are collected:
+      1. Abort orphaned child workflow sessions.
+      2. Transition `done`.
+    transitions:
+      done: cross_file
+
+  cross_file:
+    task: "Cross-file review analysis"
+    prompt: |
+      Review the big picture — things per-file agents can't see:
+      - [ ] Duplication across files
+      - [ ] Missing updates to consumers of changed interfaces
+      - [ ] Consistency across files
+      - [ ] Integration between changed components
+
+      Choose:
+      - `ok` → no issues, proceed to testing
+      - `fix` → found issues that need fixing
+    transitions:
+      ok: test
+      fix: write_fix
+
+  write_fix:
+    task: "Fix review issues"
+    prompt: |
+      Fix the issues found during review. After fixing, transition back to review.
+    transitions:
+      done: review
+
+  test:
+    sub_workflow: testing
+    on_complete: verify_route
+    on_fail: write_fix
+
+  verify_route:
+    task: "Route to correct verification"
+    prompt: |
+      Route to the correct verification based on the bug type classified at the start.
+
+      Check the classify decision:
+      - Was the bug classified as `visual`? → transition `visual`
+      - Was the bug classified as `logic`? → transition `logic`
+    transitions:
+      visual: verify_visual
+      logic: verify_logic
+
+  verify_visual:
+    task: "Verify the fix visually"
+    prompt: |
+      Verify the original bug is fixed VISUALLY.
+
+      MANDATORY STEPS:
+      1. Build and launch the app with debug bridge
+      2. Follow the SAME path used during reproduction
+      3. Take a screenshot and VERIFY the bug is gone
+      4. Compare before/after — describe the visual difference
+
+      DO NOT transition to `confirmed` without a screenshot proving the fix works.
+    transitions:
+      confirmed: done
+      still_broken: diagnose
+
+  verify_logic:
+    task: "Verify the fix with tests"
+    prompt: |
+      Verify the original bug is fixed.
+
+      MANDATORY STEPS:
+      1. Run the same test/scenario used during reproduction
+      2. Confirm it now passes — show the output
+      3. Check for regressions in related tests
+
+      DO NOT transition to `confirmed` without concrete evidence (test passing, correct output).
+    transitions:
+      confirmed: done
+      still_broken: diagnose
+
+  clarify:
+    task: "Clarify bug details"
+    prompt: "Ask the user for more details about the bug."
+    transitions:
+      got_info_visual: reproduce_visual
+      got_info_logic: reproduce_logic
+
+  escalate:
+    prompt: "Could not diagnose. Report to the user."
+    terminal: true
+
+  done:
+    prompt: "Bug fixed and verified."
+    terminal: true

package/templates/code-review.yaml

@@ -0,0 +1,164 @@
+name: code-review
+description: "Code review workflow"
+initial: overview
+max_transitions: 50
+
+states:
+  overview:
+    task: "Review the changes overview"
+    prompt: |
+      Do these steps in order, then transition `understood`:
+
+      1. Determine review scope:
+         - **First check git status in system prompt** — if it shows uncommitted changes
+           (staged or unstaged), those ARE the changes to review. Do NOT ask the user.
+         - User specified files/commits/PR → use that scope
+         - Nothing specified AND no changes in system prompt → ask the user
+         - NEVER default to `git diff master` or full branch diff
+      2. Determine review depth from user's request:
+         - "check changes" / "review diff" / default → `scope: diff` (only review changed lines)
+         - "review file" / "check whole file" / "bring to order" → `scope: full` (review entire file)
+         Save the scope via `context_set(key: "review_scope", value: "diff" or "full")`.
+      3. Get changed file names ONLY (`--name-only`). Do NOT read full diffs.
+         **Git pathspec gotcha (zsh):** to exclude paths, use `-- . ':(exclude)path'`,
+         NOT `-- ':!path'` — the latter silently returns empty results in zsh.
+
+      Output the file list, then → transition `understood`.
+    transitions:
+      understood: deep_review
+
+  deep_review:
+    task: "Route review by scope"
+    prompt: |
+      Call `Skill("coding-skill-selector")` to load language/domain skills — you will
+      need them for cross-file analysis and summarization.
+
+      Route based on how many files changed:
+      - `single` → 1 file changed — review via file-review sub-workflow (yourself)
+      - `multi` → 2+ files changed — spawn file-review agents in parallel
+    transitions:
+      single: review_single
+      multi: review_delegate
+
+  review_single:
+    sub_workflow: file-review
+    on_complete: cross_file
+    on_fail: cross_file
+
+  review_delegate:
+    task: "Deep per-file review via agents"
+    prompt: |
+      Spawn one Agent per changed file for deep review.
+      Use `subagent_type="general-purpose"`, `model="opus"`.
+
+      For each file, include in the agent prompt VERBATIM:
+      ---
+      IMPORTANT: Override the default CLAUDE.md rule about start().
+      Do NOT call start() without arguments.
+      Instead, your FIRST action must be:
+        mcp__plugin_workflow_wf__start({ workflow: "file-review", parent_session_id: "<SESSION_ID>" })
+      where <SESSION_ID> is the current session ID (substitute it before sending).
+      Then follow the file-review workflow states until completion.
+      ---
+      Also include:
+      - The file path
+      - How to get the diff (e.g. `git diff HEAD~1 -- <filepath>`)
+      - The review scope (from context key `review_scope`):
+        - `diff` → "Review ONLY the changed lines. Report pre-existing issues separately as 'pre-existing' severity, do NOT mix with diff issues."
+        - `full` → "Review the ENTIRE file for all issues, not just the diff."
+
+      Launch ALL file agents in parallel (single message, multiple Agent tool calls).
+      Wait for all to complete. Collect their reports.
+
+      After ALL reports are collected:
+      1. Abort orphaned child workflow sessions — call `sessions` to find
+         any active `file-review` sessions that are children of this session,
+         then `abort` each one. Agents may finish without reaching
+         the terminal workflow state, leaving zombie sessions behind.
+      2. Immediately transition `done`. Do not stop to report status.
+    transitions:
+      done: cross_file
+
+  cross_file:
+    task: "Cross-file analysis"
+    prompt: |
+      Now look at the big picture — things a per-file agent can't see:
+
+      - [ ] Duplication across files: did different files introduce similar code?
+      - [ ] Missing updates: if an interface/type changed, are all consumers updated?
+      - [ ] Consistency: do the changes follow the same patterns across files?
+      - [ ] Test coverage: are changed behaviors covered by tests? Missing test files?
+      - [ ] Integration: do the changed components work together correctly?
+      - [ ] Blast radius: are there callers/dependents that weren't updated?
+
+      Add any cross-file findings to the review.
+    transitions:
+      done: summarize
+
+  summarize:
+    task: "Summarize review findings"
+    prompt: |
+      Aggregate all findings from per-file reviews and cross-file analysis.
+      Categorize every finding into one of two buckets:
+
+      **Obvious fixes** — clear bugs, typos, style violations, missing error handling,
+      naming issues — things that have an objectively correct fix and don't need discussion.
+
+      **Debatable concerns** — architectural choices, alternative approaches, trade-offs,
+      style preferences where the codebase has no clear convention — things that need
+      the user's input before changing.
+
+      Present the summary clearly with both buckets. If there are no issues at all → `approve`.
+      If there are any issues → `has_issues`.
+    transitions:
+      approve: done
+      has_issues: apply_fixes
+
+  apply_fixes:
+    task: "Apply obvious fixes"
+    prompt: |
+      Apply all obvious fixes identified in the summary — bugs, typos, style violations,
+      missing error handling, naming issues. Fix them directly without asking.
+
+      Do NOT touch debatable concerns — those go to discussion.
+
+      After fixing: if there are debatable concerns remaining → `has_concerns`.
+      If everything was obvious and already fixed → `all_clear`.
+    transitions:
+      has_concerns: discuss
+      all_clear: done
+
+  discuss:
+    task: "Discuss debatable concerns"
+    prompt: |
+      Present each debatable concern to the user. For each one, explain:
+      - What the current code does
+      - What the concern is
+      - Your suggestion (if any)
+
+      Discuss with the user and reach agreement on what to change and what to leave.
+
+      After discussion, route based on scope of agreed changes:
+      - Many changes / architectural / multi-file refactoring → `plan` (enters planning mode)
+      - Few small stylistic or localized fixes → `code` (direct coding)
+      - User decided to change nothing → `skip`
+    transitions:
+      plan: plan_changes
+      code: code_changes
+      skip: done
+
+  plan_changes:
+    task: "Plan agreed changes"
+    sub_workflow: planning
+    on_complete: done
+    on_fail: done
+
+  code_changes:
+    task: "Apply agreed changes"
+    sub_workflow: coding
+    on_complete: done
+    on_fail: done
+
+  done:
+    prompt: "Review complete."
+    terminal: true