claude-mcp-workflow 0.1.0

package/templates/coding.yaml

@@ -0,0 +1,176 @@
+name: coding
+description: "Code writing workflow — from thinking to verified implementation"
+initial: think
+max_transitions: 40
+
+states:
+  think:
+    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.
+
+      Then think before writing:
+      1. What will I write? Outline the approach
+      2. Does it smell like a utility? Check framework built-ins first
+      3. Search project for existing utilities/helpers — use if found, create if broadly useful
+      4. Before creating new files: verify name/path doesn't already exist
+
+      For multi-file tasks (2+ files changing):
+      5. Produce a **per-file plan** listing each file and what changes it needs
+      6. Define **interface contracts** between files — function signatures, types, imports
+         that must match across file boundaries
+      7. Identify dependencies between files — which must be written first
+
+      Route based on scope:
+      - `single` → 1 file to change (or tightly coupled changes best done together)
+      - `multi` → 2+ independent files to change in parallel via agents
+      - `multi_self` → 2+ files but high coupling / detailed plan already exists → write yourself
+    transitions:
+      single: write_single
+      multi: delegate
+      multi_self: write_multi
+
+  write_single:
+    sub_workflow: file-code
+    on_complete: review
+    on_fail: review
+
+  write_multi:
+    task: "Implement multi-file changes (self)"
+    prompt: |
+      Write changes across multiple files yourself (high coupling or detailed plan).
+      Implement layer by layer respecting dependencies.
+      Build after all changes to verify compilation.
+      Then → transition `done`.
+    transitions:
+      done: review
+
+  delegate:
+    task: "Delegate per-file coding to agents"
+    prompt: |
+      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 per-file plan for this specific file
+      - The interface contracts — what signatures/types/exports this file must provide
+        and what it can expect from other files
+      - How to get current state: `git diff HEAD -- <filepath>`
+
+      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-code` sessions that are children of this session,
+         then `abort` each one.
+      2. Transition `done`.
+    transitions:
+      done: integrate
+
+  integrate:
+    task: "Cross-file integration check"
+    prompt: |
+      All file agents have completed. Now verify integration:
+
+      1. **Interface contracts** — do all files satisfy the contracts defined in think?
+         Check function signatures, types, imports match across boundaries.
+      2. **Import resolution** — are all cross-file imports correct and present?
+      3. **Conflict resolution** — did agents make conflicting assumptions?
+         Fix any inconsistencies.
+      4. **Missing glue** — any wiring code needed to connect the pieces?
+
+      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 — 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: verify
+    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` — review only the changed lines
+
+      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.
+      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: 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?
+      - [ ] Integration: do the changed components work together correctly?
+      - [ ] Blast radius: are there callers/dependents that weren't updated?
+
+      Choose transition:
+      - `ok` → no issues, proceed to testing
+      - `fix` → found issues that need fixing
+    transitions:
+      ok: verify
+      fix: write_fix
+
+  write_fix:
+    task: "Fix review issues"
+    prompt: |
+      Fix the issues found during review. After fixing, transition back to review
+      for re-verification.
+    transitions:
+      done: review
+
+  verify:
+    sub_workflow: testing
+    on_complete: done
+    on_fail: write_fix
+
+  done:
+    prompt: "Code written, reviewed, and verified. Implementation complete."
+    terminal: true

package/templates/debugging.yaml

@@ -0,0 +1,162 @@
+name: debugging
+description: "Debugging workflow — diagnose first, fix never (until diagnosed)"
+initial: reproduce
+max_transitions: 40
+
+states:
+  reproduce:
+    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.
+
+      **Rule #1: Diagnose FIRST, fix NEVER.**
+      **Rule #2: Reproduce BEFORE fixing.**
+
+      1. Build with diagnostic flags from loaded skills
+      2. Reproduce the bug via debug bridge or manual steps
+      3. Confirm the crash/error happens
+
+      Do NOT jump to fixing based on code reading alone.
+
+      Choose transition:
+      - `reproduced` → bug confirmed, ready to diagnose
+      - `need_info` → can't reproduce, need more details from user
+    transitions:
+      reproduced: hypothesize
+      need_info: clarify
+
+  clarify:
+    prompt: |
+      Ask the user for more details about the bug:
+      - Exact steps to reproduce
+      - Error messages or logs
+      - When it started happening
+      - Any recent changes
+
+      Choose transition:
+      - `got_info` → have enough info to try reproducing again
+    transitions:
+      got_info: reproduce
+
+  hypothesize:
+    prompt: |
+      **Step 1: Hypothesize WHERE, not WHY.**
+
+      Before adding traces, narrow down WHERE the problem is — not why it happens.
+      Form 1-3 hypotheses about the location of the bug.
+
+      Choose transition:
+      - `trace` → ready to add targeted traces to test hypotheses
+    transitions:
+      trace: trace
+
+  trace:
+    max_visits: 5
+    prompt: |
+      Add 3-5 targeted traces with unique prefixes (`[DBG1]`, `[DBG2]`).
+
+      Delegate to `debugger` subagent: build command, run command, what to look for, timeout.
+      **NEVER use `run_in_background: true`**.
+
+      **Anti-patterns:**
+      - Running builds in main context (100KB+ noise)
+      - Adding Mutex/volatile "just in case" — masks real problem
+
+      Choose transition:
+      - `found` → root cause identified
+      - `more_traces` → need more data
+      - `bridge` → need interactive debug bridge inspection
+      - `escalate` → exhausted trace attempts
+    transitions:
+      found: diagnosed
+      more_traces: trace
+      bridge: bridge_debug
+      escalate: escalated
+
+  bridge_debug:
+    prompt: |
+      Call `Skill("debug-bridge")`.
+
+      Use debug bridge for interactive state inspection.
+      Launch `interactive-openfl-debugger` subagent. Inspect state, take screenshots, simulate events.
+
+      Choose transition:
+      - `found` → root cause identified via bridge
+      - `back_to_trace` → need more code-level tracing
+    transitions:
+      found: diagnosed
+      back_to_trace: trace
+
+  diagnosed:
+    prompt: |
+      Root cause identified. Present diagnosis to the user, then decide:
+      - Trivial fix (1-2 lines, obvious, no risk) → `fix`
+      - Significant changes needed → `done` (exit to master; user decides next)
+      - Unclear scope or trade-offs → `ask_user`
+    transitions:
+      fix: fix
+      done: done
+      ask_user: ask_user
+
+  ask_user:
+    prompt: |
+      Present findings and trade-offs. Ask user how to proceed:
+      - Quick fix here?
+      - Plan a bigger change?
+      - More investigation needed?
+    transitions:
+      fix: fix
+      done: done
+      investigate: hypothesize
+
+  fix:
+    prompt: |
+      Root cause identified. Fix the bug.
+      Apply the minimal fix that addresses the root cause.
+      Do NOT add defensive code "just in case" — fix the actual problem.
+      After fixing → transition `review`.
+    transitions:
+      review: mini_review
+
+  mini_review:
+    prompt: |
+      Re-read what you just wrote. Code review only — do NOT build or run tests.
+      1. Typos, edge cases, off-by-one, null refs
+      2. Does the change affect surrounding logic?
+      3. Ripple check — grep all call sites of changed functions
+      - `ok` → proceed to testing
+      - `fix` → go back and fix
+    transitions:
+      ok: verify
+      fix: fix
+
+  verify:
+    sub_workflow: testing
+    on_complete: final_review
+    on_fail: fix
+
+  final_review:
+    prompt: |
+      Tests pass. Full review of all changes made during debugging.
+      1. New + old code together — do they fit?
+      2. Dead code — did the fix make something unnecessary?
+      3. Constants/config — magic values?
+      4. Simplification opportunities?
+      - `ok` → done
+      - `fix` → needs more work
+    transitions:
+      ok: done
+      fix: fix
+
+  done:
+    prompt: "Debugging complete. Present findings to user."
+    terminal: true
+
+  escalated:
+    prompt: |
+      Could not diagnose the root cause after maximum trace attempts.
+      Report findings to the user:
+      - What was tried
+      - What was ruled out
+      - Remaining hypotheses
+    terminal: true
+    outcome: fail

package/templates/explore.yaml

@@ -0,0 +1,90 @@
+name: explore
+description: "Codebase exploration workflow — understand structure, trace code, find patterns"
+initial: scope
+max_transitions: 20
+
+states:
+  scope:
+    prompt: |
+      Determine what we're looking for and where.
+
+      Exploration types:
+      - **Structure** — project layout, module boundaries, dependency graph
+      - **Feature** — how a specific feature is implemented end-to-end
+      - **Pattern** — recurring code patterns, conventions, idioms
+      - **Code path** — trace execution flow through the codebase
+
+      1. Check loaded skills, MEMORY.md, and project CLAUDE.md first
+      2. If the answer is already available → transition `already_known`
+      3. If exploration is needed → transition `explore`
+    transitions:
+      already_known: synthesize
+      explore: investigate
+
+  investigate:
+    prompt: |
+      Explore the codebase using available tools.
+
+      **Preferred approach:**
+      - Launch parallel `Explore` subagents for independent questions
+      - Use Glob to find files by pattern
+      - Use Grep to search for symbols, strings, patterns
+      - Use Read to examine specific files
+
+      **Rules:**
+      - Start broad (Glob/Grep), then narrow (Read specific files)
+      - Follow imports and call chains to understand flow
+      - Note key files, patterns, and architectural decisions
+
+      Choose transition:
+      - `found` → gathered enough information to answer
+      - `deeper` → need to explore further (follow a lead, check another area)
+      - `ask_user` → need user input to decide direction (e.g., "is this feature needed?", "which approach do you prefer?")
+      - `not_found` → exhausted search avenues, nothing relevant found
+    max_visits: 4
+    transitions:
+      found: synthesize
+      deeper: investigate
+      ask_user: clarify
+      not_found: synthesize
+
+  clarify:
+    prompt: |
+      Findings so far require user input before proceeding.
+
+      Present what you've found so far concisely, then ask your question(s).
+      Use AskUserQuestion for critical decisions that affect the direction of exploration.
+
+      After getting user's answer → transition `continue` to resume investigation
+      with the new context, or `enough` if the answer completes the picture.
+    transitions:
+      continue: investigate
+      enough: synthesize
+
+  synthesize:
+    prompt: |
+      Compile findings into a structured answer.
+
+      Format:
+      - Start with a concise summary (1-2 sentences)
+      - Key files and their roles
+      - Architecture/patterns discovered
+      - Code flow if traced
+
+      If this reveals a recurring knowledge gap → note it for reflection.
+
+      Choose transition:
+      - `done` → exploration is complete, no further action needed (pure research)
+      - `needs_action` → findings indicate code changes are needed (delete, refactor, fix, implement)
+    transitions:
+      done: done
+      needs_action: needs_action
+
+  needs_action:
+    prompt: "Exploration complete. Findings indicate action is needed."
+    terminal: true
+    outcome: needs_action
+
+  done:
+    prompt: "Codebase exploration complete."
+    terminal: true

package/templates/file-code.yaml

@@ -0,0 +1,69 @@
+name: file-code
+description: "Per-file coding — spawned by coding/bug-fix for each file to implement"
+initial: understand
+max_transitions: 25
+
+states:
+  understand:
+    task: "Understand file context"
+    prompt: |
+      You are implementing changes in a single file as part of a larger task.
+      The file path, plan, and interface contracts were provided in your task prompt.
+
+      1. Call `Skill("coding-skill-selector")` to load language/domain skills.
+      2. Read the existing file (if it exists) to understand current structure.
+      3. Read related files: imports, callers, siblings in the same module.
+         Understand the interfaces this file must satisfy.
+      4. Review the plan and interface contracts from your task prompt.
+         Identify exactly what needs to change in this file.
+
+      Then → transition `done`.
+    transitions:
+      done: write
+
+  write:
+    task: "Write implementation"
+    prompt: |
+      Write the implementation for this file following:
+      - The plan and interface contracts from your task prompt
+      - Loaded preference/style skills
+      - Existing patterns in the file and its neighbors
+
+      Check original before changing: `git diff HEAD -- <file>` to understand original values.
+
+      Write the code, then → transition `done`.
+    transitions:
+      done: self_review
+
+  self_review:
+    task: "Self-review code"
+    prompt: |
+      Re-read what you just wrote. Code review only — do NOT build or run tests.
+
+      1. **Skills as checklist** — re-read loaded `lang-*` and `preferences-*` skills.
+         For every WRONG pattern listed, scan your new code for matches.
+      2. **Typos, edge cases, off-by-one, null refs**
+      3. **Interface contracts** — does your code satisfy the contracts from the plan?
+         Check function signatures, return types, side effects match what other files expect.
+      4. **Ripple check** — if you added a call to function F, grep ALL existing call sites.
+         Some may now fire twice through your new path. Flag for the parent agent.
+      5. **DRY check** — duplicating existing code? Extract if obvious.
+
+      If issues found → fix them, then re-review.
+      When clean → transition `done`.
+    transitions:
+      done: report
+
+  report:
+    task: "Write implementation report"
+    prompt: |
+      Write a structured report for this file:
+
+      **File**: <path>
+      **What was done**: <one-paragraph summary of changes>
+      **Decisions made**: <any implementation choices and rationale>
+      **Interface notes**: <how this file connects to others — exports, imports, contracts satisfied>
+      **Concerns**: <anything the parent agent should verify — edge cases, assumptions, integration risks>
+
+      Output this report as your final response.
+    terminal: true

package/templates/file-review.yaml

@@ -0,0 +1,164 @@
+name: file-review
+description: "Per-file deep review — spawned by code-review for each changed file"
+initial: read_context
+max_transitions: 25
+
+states:
+  read_context:
+    task: "Read file and context"
+    prompt: |
+      You are reviewing a single file as part of a code review.
+      The file path and diff info were provided in your task prompt.
+
+      1. Call `Skill("coding-skill-selector")` to load language/domain skills.
+      2. Read the diff for this file to understand what changed.
+      3. Check the review scope from your task prompt:
+         - `diff` scope → read the diff, then read the full methods/blocks containing changes.
+           Changes can affect surrounding code, so always understand the logical context.
+         - `full` scope → read the FULL file
+      4. Read related files: imports, files that call this one, siblings in the same module.
+         Check if similar code already exists elsewhere that could be reused or unified.
+      5. Understand what changed and why.
+
+      Then → transition `done`.
+    transitions:
+      done: build_checklist
+
+  build_checklist:
+    task: "Build style checklist from skills"
+    prompt: |
+      Build a concrete style checklist from loaded skills:
+
+      Process each loaded `lang-*` and `preferences-*` skill ONE AT A TIME.
+      For each skill:
+      1. Re-read the FULL skill text
+      2. Extract EVERY rule — each `// WRONG` example, explicit rule, or convention
+         becomes a one-line check with the wrong pattern AND the correct one
+      3. Count rules extracted from this skill and output the count
+
+      Do NOT summarize, group, or prioritize — every rule matters equally.
+      If your total is under 25 rules across all skills, you missed some — re-read.
+
+      Output the full checklist, then → transition `done`.
+    transitions:
+      done: check_correctness
+
+  check_correctness:
+    task: "Check correctness"
+    prompt: |
+      Check based on review scope (`diff` or `full`).
+      For `diff` scope: changed lines are entry points, but always check the
+      logical context around them — the full method, callers of changed signatures,
+      other uses of changed fields. A change can break surrounding code.
+      - [ ] Logic errors: wrong conditions, off-by-one, inverted booleans, wrong operators
+      - [ ] Edge cases: null/undefined, empty collections, zero, negative, boundary values
+      - [ ] Error handling: uncaught exceptions, swallowed errors, wrong error types
+      - [ ] Race conditions: async without awaits, shared mutable state
+      - [ ] Resource leaks: unclosed handles, missing cleanup in error paths
+      - [ ] Type mismatches: wrong argument types, unsafe casts
+      - [ ] Regression risk: does this break existing callers or assumptions?
+
+      Then → transition `done`.
+    transitions:
+      done: check_loops
+
+  check_loops:
+    task: "Audit every loop and iteration pattern"
+    prompt: |
+      Find loops based on review scope (`diff` = only loops in changed code, `full` = ALL loops in file). For each one, output:
+
+        Line <N>: `<the loop header>` — iterates <what> to access <what> → verdict: ok / issue
+
+      Check each loop against these anti-patterns:
+
+      1. **Range-over-sparse-container**: the loop iterates an index range (`0...n`,
+         `i++`) but uses the index to look up a Map/Dict/HashMap, with a null check
+         to skip missing entries. This means the container is sparse and should be
+         iterated directly instead of via index range.
+         WRONG: `for (i in 0...n) { val = map[i]; if (val == null) continue; ... }`
+         RIGHT: `for (key => val in map) { ... }` (with filter if needed)
+
+      2. **Keys-then-lookup**: iterates `.keys()` then does a separate `map[key]`
+         lookup inside the body. Use key-value destructuring instead.
+         WRONG: `for (k in map.keys()) { v = map[k]; ... }`
+         RIGHT: `for (k => v in map) { ... }`
+
+      3. **Repeated linear scan**: the same collection is scanned multiple times in
+         the same method or call chain to find related data that could be found in
+         a single pass.
+
+      4. **Wrong container for access pattern**: Array with `.contains()` checks
+         (should be Set/Map), unsorted Array with binary-search-like access, etc.
+
+      5. **Continue instead of guard**: when a single condition filters the entire
+         loop body, use guard-style `for (...) if (cond) {` instead of
+         `if (!cond) continue;`. But when multiple independent checks follow
+         sequentially (each with its own variable), `continue` is fine.
+         WRONG: `for (x in list) { if (x.type != Foo) continue; doWork(x); }`
+         RIGHT: `for (x in list) if (x.type == Foo) { doWork(x); }`
+         OK:    `for (f in range) { val = map[f]; if (val == null) continue; ... }`
+
+      6. **If/else-if chain instead of switch**: when a loop body checks the same
+         variable with `if/else if` chain (e.g. `if (x == "a") ... else if (x == "b")`),
+         use `switch` instead — cleaner, exhaustive, idiomatic.
+         WRONG: `if (node.name == "a") { ... } else if (node.name == "b") { ... }`
+         RIGHT: `switch node.name { case "a": ... case "b": ... }`
+
+      You MUST list ALL loops with verdicts. Do not summarize or skip "obvious" ones.
+
+      Then → transition `done`.
+    transitions:
+      done: check_style
+
+  check_style:
+    task: "Check code style"
+    prompt: |
+      Go through EVERY item in your style checklist from build_checklist.
+      Scope: `diff` = scan only lines in the diff; `full` = scan entire file.
+      If a line appears in the diff, it is part of the change and must meet
+      current style standards. Report with file:line.
+
+      Additionally check:
+      - [ ] Naming: consistent with conventions in neighboring files
+      - [ ] Duplication: does this duplicate existing code? Search the codebase.
+      - [ ] Dead code: unused imports, unreachable branches, commented-out code
+      - [ ] Complexity: overly nested logic, functions doing too many things
+      - [ ] Consistency: does new code follow patterns in the same module?
+
+      Then → transition `done`.
+    transitions:
+      done: check_security
+
+  check_security:
+    task: "Check security"
+    prompt: |
+      Check code for security issues (scope: `diff` = changed code, `full` = entire file):
+      - [ ] Injection: unsanitized inputs reaching dangerous APIs
+      - [ ] Auth/authz: missing or insufficient access controls
+      - [ ] Data exposure: secrets, credentials, or sensitive data leaking
+      - [ ] Input validation: missing validation at system boundaries
+      - [ ] Unsafe operations: anything exploitable by malicious input
+
+      Only flag real risks — don't invent hypothetical issues.
+      Then → transition `done`.
+    transitions:
+      done: report
+
+  report:
+    task: "Write file review report"
+    prompt: |
+      Write a structured report for this file:
+
+      **File**: <path>
+      **What changed**: <one-paragraph summary of the changes>
+      **Issues found**:
+      For each issue:
+      - Severity: bug / risk / style / nit
+      - Line: <line number>
+      - Description: <what's wrong>
+      - Suggestion: <how to fix>
+
+      If no issues found, say so explicitly.
+
+      Output this report as your final response.
+    terminal: true