claude-mcp-workflow 0.1.8 → 0.1.9

package/templates/debugging.yaml

@@ -37,10 +37,14 @@ states:
       - When it started happening
       - Any recent changes
 
+      If there is no interactive user (you are running as a subagent), do NOT ask — state your assumptions and continue, or take the failure path.
+
       Choose transition:
       - `got_info` → have enough info to try reproducing again
+      - `escalate` → no way to get more information; give up
     transitions:
       got_info: reproduce
+      escalate: escalated
 
   hypothesize:
     prompt: |
@@ -51,21 +55,35 @@ states:
 
       Choose transition:
       - `trace` → ready to add targeted traces to test hypotheses
+      - `escalate` → out of hypotheses (or trace budget exhausted); report findings
     transitions:
       trace: trace
+      escalate: escalated
 
   trace:
     max_visits: 5
     prompt: |
       Add 3-5 targeted traces with unique prefixes (`[DBG1]`, `[DBG2]`).
 
-      Delegate to `general-purpose` subagent: build command, run command, what to look for, timeout.
-      **NEVER use `run_in_background: true`**.
+      Delegate the build+run to a flat `general-purpose` subagent
+      (build/run/report — no workflow, no skills) to keep build output
+      out of main context: give it the build command, run command, what
+      to look for, and a timeout.
+      A flat subagent inherits none of this project's skills or env
+      rules — it only knows what YOU put in its spawn prompt. So include
+      VERBATIM in that prompt: (a) any tooling/hook constraints that
+      apply in this project (required CLIs, blocked commands), and
+      (b) "Strip noise, but quote every error, failing assertion, and
+      number VERBATIM — don't paraphrase the signal or replace it with
+      a verdict; the parent judges."
+      Spawn with `run_in_background: false` — you need the result before transitioning.
 
       **Anti-patterns:**
       - Running builds in main context (100KB+ noise)
       - Adding Mutex/volatile "just in case" — masks real problem
 
+      Budget: 5 visits to this state (engine-enforced); when nearly exhausted, choose `escalate` instead of retrying.
+
       Choose transition:
       - `found` → root cause identified
       - `more_traces` → need more data
@@ -74,29 +92,35 @@ states:
     transitions:
       found: diagnosed
       more_traces: trace
-      bridge: bridge_debug
+      bridge: load_skills_bridge
       escalate: escalated
 
+  load_skills_bridge:
+    skills:
+      - ?debug-bridge
+    transitions:
+      continue: bridge_debug
+
   bridge_debug:
     prompt: |
-      Call `Skill("debug-bridge")` and any platform-specific debug bridge skills
-      from the available skills list (e.g. `debug-bridge-openfl`, `debug-bridge-unity`, etc.).
-
-      Use debug bridge for interactive state inspection.
-      Launch `general-purpose` subagent. Inspect state, take screenshots, simulate events.
+      Use the debug bridge for interactive state inspection.
+      Launch a `general-purpose` subagent to build and launch the app.
+      Inspect state, take screenshots, simulate events.
 
       Choose transition:
       - `found` → root cause identified via bridge
       - `back_to_trace` → need more code-level tracing
+      - `escalate` → bridge inspection exhausted (or trace budget spent); report findings
     transitions:
       found: diagnosed
       back_to_trace: trace
+      escalate: escalated
 
   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)
+      - Significant changes needed → `done` (exit to parent workflow; user decides next)
       - Unclear scope or trade-offs → `ask_user`
     transitions:
       fix: fix
@@ -106,9 +130,11 @@ states:
   ask_user:
     prompt: |
       Present findings and trade-offs. Ask user how to proceed:
-      - Quick fix here?
-      - Plan a bigger change?
-      - More investigation needed?
+      - Quick fix here? → `fix`
+      - Plan a bigger change? → `done` (exit to parent workflow)
+      - More investigation needed? → `investigate`
+
+      If there is no interactive user (you are running as a subagent), do NOT ask — state your assumptions and continue, or take the failure path.
     transitions:
       fix: fix
       done: done
@@ -159,8 +185,7 @@ states:
 
   escalated:
     prompt: |
-      Could not diagnose the root cause after maximum trace attempts.
-      Report findings to the user:
+      Could not diagnose the root cause. Report findings to the user:
       - What was tried
       - What was ruled out
       - Remaining hypotheses

package/templates/explore.yaml

@@ -1,9 +1,16 @@
 name: explore
 description: "Codebase exploration workflow — understand structure, trace code, find patterns"
-initial: scope
+initial: load_skills
 max_transitions: 20
 
 states:
+  load_skills:
+    skills:
+      - coding-skill-selector
+      - ?project-skill-selector
+    transitions:
+      continue: scope
+
   scope:
     prompt: |
       Determine what we're looking for and where.
@@ -26,16 +33,45 @@ states:
       Explore the codebase using available tools.
 
       **Preferred approach:**
-      - Launch parallel `Explore` subagents for independent questions
+      - Launch parallel subagents for independent questions. Location-only
+        fan-out (find files/symbols, paste back what's there, zero judgement)
+        may use flat `Explore`-type agents; any agent that returns judgement,
+        analysis, or a recommendation is ANALYTICAL — never spawn it flat,
+        use the VERBATIM preamble below.
       - Use Glob to find files by pattern
-      - Use Grep to search for symbols, strings, patterns
-      - Use Read to examine specific files
+      - For "where is X / what is X's shape / which decls carry Y" use the
+        STRUCTURAL navigation tool your loaded skills prescribe for the
+        language (a parser-aware query CLI, LSP, etc.) — NOT grep — when
+        one exists. Grep/Read only for non-parsing files or prose inside
+        comments/strings. The loaded coding skills are authoritative here;
+        follow the tool-usage gate defined by the loaded skills, do not
+        default to grep.
+      - Use Read to examine specific files — targeted (offset/limit on the
+        located window), never a blind whole-file dump as a grep substitute
 
       **Rules:**
-      - Start broad (Glob/Grep), then narrow (Read specific files)
+      - Locate with the structural tool first, then narrow with Read
       - Follow imports and call chains to understand flow
       - Note key files, patterns, and architectural decisions
 
+      For an ANALYTICAL subagent, include in its 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: "subagent", parent_session_id: "<SESSION_ID>" })
+      where <SESSION_ID> is the current session ID (substitute it before sending).
+      Then follow the subagent workflow until completion — its `route` state
+      self-classifies (analytical → skill-loaded sub-workflow; trivial → execute).
+      start() returns `SESSION: <id>` — pass that session_id explicitly in every
+      subsequent workflow tool call; parallel siblings share the same ppid.
+      ---
+      After collecting reports: `sessions` → `abort` orphaned child `subagent`
+      sessions.
+
+      Budget: 4 visits to this state (engine-enforced); when nearly exhausted,
+      choose `not_found` instead of retrying.
+
       Choose transition:
       - `found` → gathered enough information to answer
       - `deeper` → need to explore further (follow a lead, check another area)
@@ -55,6 +91,9 @@ states:
       Present what you've found so far concisely, then ask your question(s).
       Use AskUserQuestion for critical decisions that affect the direction of exploration.
 
+      If there is no interactive user (you are running as a subagent), do NOT
+      ask — state your assumptions and continue, or take the failure path.
+
       After getting user's answer → transition `continue` to resume investigation
       with the new context, or `enough` if the answer completes the picture.
     transitions:
@@ -73,18 +112,13 @@ states:
 
       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)
+      When the synthesis is presented → transition `done`. If the findings
+      indicate code changes, say so in the synthesis — the parent workflow
+      decides what happens next.
     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
+    outcome: complete

package/templates/file-code.yaml

@@ -1,5 +1,5 @@
 name: file-code
-description: "Per-file coding — spawned by coding/bug-fix for each file to implement"
+description: "Per-file coding — spawned as an agent by coding/bug-fix for each file, or run inline as a sub-workflow for a single file"
 initial: load_skills
 max_transitions: 25
 
@@ -15,7 +15,8 @@ states:
     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.
+      The file path, plan, and interface contracts come from your task prompt
+      (spawned agent) or from the conversation so far (inline sub-workflow).
 
       1. Read the existing file (if it exists) to understand current structure.
       2. Read related files: imports, callers, siblings in the same module.
@@ -35,7 +36,8 @@ states:
       - Loaded preference/style skills
       - Existing patterns in the file and its neighbors
 
-      Check original before changing: `git diff HEAD -- <file>` to understand original values.
+      Check the original before changing: `git show HEAD:<file>` shows the
+      pre-change content (original values, structure).
 
       Write the code, then → transition `done`.
     transitions:
@@ -71,5 +73,12 @@ states:
       **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.
+      Output this report — as your final response (spawned agent) or into the
+      conversation for the parent workflow (inline sub-workflow).
+      Then → transition `done`.
+    transitions:
+      done: finish
+
+  finish:
     terminal: true
+    outcome: complete

package/templates/file-review.yaml

@@ -1,5 +1,5 @@
 name: file-review
-description: "Per-file deep review — spawned by code-review for each changed file"
+description: "Per-file deep review — spawned as an agent for each changed file, or run inline as a sub-workflow for a single file"
 initial: load_skills
 max_transitions: 25
 
@@ -15,7 +15,8 @@ states:
     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.
+      The file path and diff info come from your task prompt (spawned agent)
+      or from the conversation so far (inline sub-workflow).
 
       1. Read the diff for this file to understand what changed.
       2. Check the review scope from your task prompt:
@@ -66,7 +67,8 @@ states:
 
       Otherwise (user-authored), build a concrete style checklist from loaded skills:
 
-      Process each loaded `lang-*` and `preferences-*` skill ONE AT A TIME.
+      Process the bare `preferences` skill plus 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
@@ -76,6 +78,10 @@ states:
       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.
 
+      Escape hatch: if NO lang/preferences skills apply to this file type
+      (e.g. config, YAML, docs), state so explicitly and continue — the
+      language-agnostic checks in the following states still run.
+
       Output the full checklist, then → transition `done`.
     transitions:
       done: check_correctness
@@ -110,7 +116,11 @@ states:
 
         Line <N>: `<the loop header>` — iterates <what> to access <what> → verdict: ok / issue
 
-      Check each loop against these anti-patterns:
+      Check each loop against these anti-patterns. The examples are
+      Haxe-flavored — translate each pattern to the file's language.
+      Rules 5-6 are personal style preferences — apply them ONLY when
+      `{{context.is_user_authored}}` is not "false" (treat empty as "true");
+      for external/forked/vendored code check rules 1-4 only.
 
       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
@@ -251,12 +261,21 @@ states:
       **What changed**: <one-paragraph summary of the changes>
       **Issues found**:
       For each issue:
-      - Severity: bug / risk / style / nit
+      - Severity: bug / risk / style / nit / pre-existing
+        (`pre-existing` = issue outside the changed lines, found during
+        a diff-scope review — report separately, do NOT mix with diff issues)
       - 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.
+      Output this report — as your final response (spawned agent) or into the
+      conversation for the parent workflow (inline sub-workflow).
+      Then → transition `done`.
+    transitions:
+      done: finish
+
+  finish:
     terminal: true
+    outcome: complete

package/templates/github-init.yaml

@@ -1,5 +1,5 @@
 name: github-init
-description: "Initialize git repo and create private GitHub repository"
+description: "Initialize git repo and create a private GitHub repository for a project not yet on GitHub"
 initial: check_state
 max_transitions: 20
 
@@ -9,17 +9,20 @@ states:
       Check the current state of the project:
       1. `git status` — is it already a git repo?
       2. `gh auth status` — is GitHub CLI authenticated?
-      3. Check if `.gitignore` exists
+      3. `git remote -v` — is a GitHub remote already configured?
+      4. Check if `.gitignore` exists
 
       Choose transition:
       - `needs_gitignore` → not a git repo, no .gitignore
       - `needs_init` → .gitignore exists but not a git repo
       - `needs_repo` → already a git repo, just needs GitHub remote
+      - `already_done` → git repo with GitHub remote already set — just verify
       - `fail` → gh CLI not authenticated or other blocker
     transitions:
       needs_gitignore: create_gitignore
       needs_init: git_init
       needs_repo: create_repo
+      already_done: verify
       fail: failed
 
   create_gitignore:
@@ -27,7 +30,8 @@ states:
       Create `.gitignore` appropriate for the project.
 
       Detect the project type (look at package.json, Cargo.toml, *.csproj, etc.)
-      and generate a suitable .gitignore. Always include OS artifacts (.DS_Store).
+      and generate a suitable .gitignore. Always include OS artifacts (.DS_Store)
+      and secrets: `.env*`, key files, credentials.
 
       Ask the user if unsure what to exclude.
 
@@ -42,7 +46,10 @@ states:
       2. Check for files excluded by global gitignore that should be tracked
          (e.g. CLAUDE.md if it's part of the project). Force-add them if needed.
       3. `git add -A`
-      4. `git commit -m "Initial commit"`
+      4. Review the staged file list (`git status`) before committing — no
+         secrets (.env files, keys, credentials) may be staged. If found,
+         unstage them and add to .gitignore.
+      5. `git commit -m "Initial commit"`
 
       Transition `next`.
     transitions:
@@ -52,11 +59,14 @@ states:
     prompt: |
       Create a private GitHub repo and push:
       1. Determine repo name from the current directory name
-      2. Determine GitHub username from `gh auth status`
-      3. Run: `gh repo create <user>/<repo> --private --source=. --push`
+      2. Run: `gh repo create <repo> --private --source=. --push`
+         (a bare name creates the repo under the authenticated account —
+         no username parsing needed)
 
       If it succeeds → transition `next`.
-      If it fails → transition `fail`.
+      If the name is already taken → retry once with a more specific name,
+      then transition `next` on success.
+      If it fails otherwise → transition `fail`.
     transitions:
       next: verify
       fail: failed
@@ -66,9 +76,15 @@ states:
       Verify the repo was created:
       - `gh repo view --json isPrivate,url`
       - `git remote -v`
-      Confirm it's private and remote is set. Transition `next`.
+      Confirm it's private and the remote is set.
+
+      Choose transition:
+      - `next` → confirmed
+      - `fail` → verification failed (repo missing, wrong visibility, or no
+        remote) — report what exactly failed
     transitions:
       next: done
+      fail: failed
 
   done:
     prompt: "GitHub repo created and code pushed successfully."

package/templates/investigate.yaml

@@ -11,8 +11,8 @@ states:
       1. Extract from the user's message:
          - **Goal**: what the user ultimately wants changed
          - **Unknowns**: questions, uncertainties, assumptions to verify
-           (markers: "seems like", "I think", "if that's the case", "not sure", "should",
-            "not sure", "?", conditional language, hedging)
+           (markers: "seems like", "I think", "if that's the case", "not sure",
+            "should", "?", conditional language, hedging)
          - **Knowns**: concrete facts or behaviors stated as certain
 
       2. Formulate 1-3 specific investigation questions to resolve the unknowns
@@ -28,7 +28,9 @@ states:
 
   assess:
     prompt: |
-      Investigation complete. Review findings against the original unknowns.
+      Investigation finished — successfully or not (a failed exploration also
+      lands here; treat missing findings as unresolved unknowns).
+      Review findings against the original unknowns.
 
       Present to the user:
       1. For each unknown — what did investigation reveal?
@@ -36,17 +38,21 @@ states:
       3. Recommended action and scope
 
       Choose transition:
-      - `trivial` → fix is obvious and small (1-3 lines), apply it now
+      - `trivial` → fix is obvious and small (1-3 lines); it will be applied in
+        the quick_fix state after the skill gate — do NOT apply it here
         **Before choosing trivial, verify ALL:**
         ☐ Only 1 file changed
         ☐ No UI positioning/layout/scaling involved (needs visual verification)
         ☐ No unknowns about API behavior in the fix path
         If any check fails → `needs_plan`
+      - `investigate_more` → findings raised new specific questions that need
+        another exploration round
       - `needs_plan` → changes needed but require planning (multi-file, risk, unclear scope)
       - `no_action` → investigation showed the change is unnecessary or already works correctly
       - `unclear` → still unclear after investigation, need user input
     transitions:
       trivial: load_skills
+      investigate_more: run_explore
       needs_plan: needs_plan
       no_action: done
       unclear: clarify
@@ -56,6 +62,9 @@ states:
       Present findings and remaining questions to the user.
       Use AskUserQuestion for critical decisions.
 
+      If there is no interactive user (you are running as a subagent), do NOT
+      ask — state your assumptions and continue, or take the failure path.
+
       After getting user's answer → transition based on clarity:
       - `reassess` → re-evaluate with new info
       - `done` → user says no action needed

package/templates/master.yaml

@@ -1,5 +1,5 @@
 name: master
-description: "Master workflow — single entry point replacing skill-selector. Analyzes task, loads knowledge skills, routes to process sub-workflows."
+description: "Master workflow — single entry point. Analyzes task, loads knowledge skills, routes to process sub-workflows."
 initial: route
 max_transitions: 100
 
@@ -12,8 +12,8 @@ states:
 
       **Step 1 — Check for project workflows.**
       If project workflows are listed below this prompt, check if any match the
-      user's task. If a match → transition `project` and set context key
-      `project_workflow` to that workflow's name.
+      user's task. If a match → set context key `project_workflow` to that
+      workflow's name, THEN transition `project`.
 
       **Step 2 — Standard routing (only if no project workflow matched).**
 
@@ -23,7 +23,8 @@ states:
       - 5+ files touched, mixed actions, cascade risk, user asks to plan
 
       Route the user's message:
-      - understand/investigate → debugging or explore (NEVER coding)
+      - understand how code works → explore; diagnose why behavior occurs →
+        debugging (NEVER coding for either)
       - questions about code behavior ("will X break?", "how does Y work?",
         "what happens when Z?") → explore (requires reading code before answering)
       - broken behavior / suspected bug → bug_fix (EVEN with hedging language).
@@ -41,7 +42,8 @@ states:
       - new feature e2e → feature
       - restructure code, refactoring, fix formatting, cleanup, lint across files/directories → code_review
       - review PR/code → code_review
-      - test / verify / check on device or simulator → testing
+      - test / verify / check runtime behavior (locally, on a device, in a
+        simulator, against a running service) → testing
       - review changes + commit + push ("review and push",
         "check and push", "push to github") → review_push
       - /init or "generate CLAUDE.md" or "create CLAUDE.md" → init
@@ -113,24 +115,26 @@ states:
       The dynamic workflow was already created during planning.
 
       1. Read context key `dynamic_workflow` to get the workflow name
-      2. Call `modify` to add execution state:
+      2. Call `modify` to add the execution state and its edge:
          - add_state: {name: "run_dynamic", sub_workflow: "<workflow name>", on_complete: "doc_sync", on_fail: "doc_sync"}
          - add_transition: {from: "create_dynamic", name: "execute", to: "run_dynamic"}
       3. Transition `execute`
-    transitions:
-      execute: doc_sync
+
+      The `execute` transition does not exist until the `modify` call adds it —
+      skipping step 2 makes the transition fail loudly.
 
   run_project:
     prompt: |
       A project-specific workflow was selected. Wire it up dynamically:
 
       1. Read context key `project_workflow` to get the workflow name
-      2. Call `modify` to update THIS state:
+      2. Call `modify` to add a new state and its edge:
          - add_state: {name: "run_project_sub", sub_workflow: "<workflow name>", on_complete: "doc_sync", on_fail: "doc_sync"}
          - add_transition: {from: "run_project", name: "execute", to: "run_project_sub"}
       3. Transition `execute`
-    transitions:
-      execute: doc_sync
+
+      The `execute` transition does not exist until the `modify` call adds it —
+      skipping step 2 makes the transition fail loudly.
 
   run_investigate:
     sub_workflow: investigate
@@ -183,10 +187,9 @@ states:
 
   run_review_push:
     sub_workflow: review-push
-    on_complete: done
+    on_complete: doc_sync
     on_fail: done
 
-
   run_research:
     sub_workflow: web-research
     on_complete: done

package/templates/new-feature.yaml

@@ -1,14 +1,28 @@
 name: new-feature
 description: "New feature implementation workflow"
-initial: requirements
+initial: check_plan
 max_transitions: 80
 
 states:
+  check_plan:
+    prompt: |
+      ROUTING STATE — decide where to start based on plan status.
+
+      - A plan for this feature was already approved in this conversation
+        → transition `have_plan` (skip straight to implementation).
+      - No approved plan yet → transition `no_plan` (clarify requirements,
+        then plan).
+    transitions:
+      have_plan: implement
+      no_plan: requirements
+
   requirements:
     task: "Clarify requirements"
     prompt: |
       Clarify requirements with the user. What exactly should this feature do?
 
+      If the request is unambiguous → transition `clear` without asking anything.
+
       **Do NOT explore the codebase here** — no Read, Grep, Glob, or Explore agents.
       Only ask the user questions. Codebase exploration happens in the planning phase.
     transitions:
@@ -16,35 +30,19 @@ states:
 
   plan:
     sub_workflow: planning
-    on_complete: load_skills
+    on_complete: implement
     on_fail: requirements
 
-  load_skills:
-    skills:
-      - coding-skill-selector
-      - ?project-skill-selector
-    transitions:
-      continue: implement
-
   implement:
-    task: "Implement the feature"
-    prompt: |
-      Implement the feature according to the plan.
-    transitions:
-      done: test
-
-  test:
-    sub_workflow: testing
-    on_complete: review
-    on_fail: load_skills
-
-  review:
-    task: "Review implementation"
-    prompt: "Review the implementation. Check for edge cases, code quality, and adherence to project conventions."
-    transitions:
-      approved: done
-      changes_needed: load_skills
+    sub_workflow: coding
+    on_complete: done
+    on_fail: failed
 
   done:
     prompt: "Feature implemented, tested, and reviewed."
     terminal: true
+    outcome: complete
+
+  failed:
+    terminal: true
+    outcome: fail