claude-mcp-workflow 0.1.7 → 0.1.9

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

package/templates/planning.yaml

@@ -1,9 +1,16 @@
 name: planning
 description: "Planning sub-workflow — explore, design plan, record workflow context"
-initial: explore_needed
+initial: load_skills
 max_transitions: 30
 
 states:
+  load_skills:
+    skills:
+      - coding-skill-selector
+      - ?project-skill-selector
+    transitions:
+      continue: explore_needed
+
   explore_needed:
     prompt: |
       Determine if codebase exploration is needed before planning.
@@ -24,10 +31,15 @@ states:
     on_fail: design
 
   design:
+    # The Resume line in the plan-file template below — `transition("<session_id>", "planned")`
+    # — is load-bearing: hooks/workflow-start.sh regex-matches this exact positional
+    # form (transition\(\\"[a-f0-9]+\\") to recover the session ID on plan resume.
+    # Keep it EXACTLY as is; do not normalize to named arguments.
     prompt: |
-      Load architecture skill: `Skill("architecture")`.
-
-      Design the implementation plan.
+      Design the implementation plan. (Coding skills incl. architecture
+      and the project's structural-navigation skill were loaded at the
+      `load_skills` gate — follow them; do not default to grep on
+      parseable source.)
 
       **Plan mode**: if system prompt says "Plan mode is active" — you're already in it,
       do NOT call EnterPlanMode. Otherwise call `EnterPlanMode`.
@@ -56,8 +68,12 @@ states:
       running automatically in its review/testing states. Including them causes
       the agent to run manual builds that conflict with the automated pipeline.
 
+      **Brevity**: fewer steps. Skip what the user can infer from the task. Don't
+      restate the task back at the top of the plan. No filler sections (`Overview`,
+      `Background`) unless the task is genuinely novel and context is needed.
+
       **Steps in plan mode:**
-      1. Explore codebase (Read/Glob/Grep or Plan/Explore subagents)
+      1. Explore codebase (directly or via Plan/Explore subagents)
       2. Design approach
       3. Write plan to the plan file specified in plan mode system prompt
       4. Plan file MUST end with Workflow section (get session_id via `status`):
@@ -66,17 +82,21 @@ states:
          - **Session**: `<session_id>`
          - **Current state**: `planning @ design`
          - **After approve**: transition `planned` → returns to parent
-         - **Execution workflow**: coding / code-review / <workflow-name>
+         - **Execution workflow**: coding / feature / bug_fix / testing / refactoring / <workflow-name>
          - **Resume**: `transition("<session_id>", "planned")`
          ```
       5. Call `ExitPlanMode` for user approval
 
       **After plan approved → transition `planned`.**
+      **If the user rejects the plan** → revise the plan file per their feedback,
+      then call `ExitPlanMode` again. Do NOT transition until approved.
     transitions:
       planned: done
       dynamic: create_workflow
 
   create_workflow:
+    # Resume line in the template below: same load-bearing positional form as in
+    # `design` (hook regex) — keep `transition("<session_id>", "planned")` exactly.
     prompt: |
       The task is operational/dynamic — create the execution workflow directly.
       The workflow IS the plan.
@@ -97,10 +117,21 @@ states:
       4. Write plan file with:
          - Brief context of what the workflow does
          - Reference to the created workflow name
-         - Workflow section with `Execution workflow: <workflow-name>` (actual name, not "dynamic")
+         - The FULL Workflow section (get session_id via `status`):
+           ```
+           ## Workflow
+           - **Session**: `<session_id>`
+           - **Current state**: `planning @ create_workflow`
+           - **After approve**: transition `planned` → returns to parent
+           - **Execution workflow**: <workflow-name> (actual name, not "dynamic")
+           - **Resume**: `transition("<session_id>", "planned")`
+           ```
       5. Call `ExitPlanMode` for user approval
 
       **After plan approved → transition `planned`.**
+      **If the user rejects the plan** → revise the plan file (and the workflow
+      definition if needed) per their feedback, then call `ExitPlanMode` again.
+      Do NOT transition until approved.
     transitions:
       planned: done
 

package/templates/reflection.yaml

@@ -12,6 +12,7 @@ states:
       - Any hallucinations (made-up names, paths, APIs)?
       - Unnecessary complexity added?
       - User had to correct you or wait?
+      - Workflow/skill friction — wrong routing, missing skills, redundant states?
 
       Choose transition:
       - `has_lesson` → found something worth recording
@@ -43,11 +44,17 @@ states:
       - `suggest_improvements` → the lesson itself IS about workflow/skill friction
         (not a side observation — the primary lesson is about process inefficiency)
     transitions:
-      enrich_skill: action
-      create_skill: action
+      enrich_skill: load_skill_manager
+      create_skill: load_skill_manager
       update_memory: action
       suggest_improvements: suggest_improvements
 
+  load_skill_manager:
+    skills:
+      - skill-manager
+    transitions:
+      continue: action
+
   action:
     prompt: |
       Execute the classified action:
@@ -59,7 +66,7 @@ states:
       After acting, acknowledge the lesson to the user honestly.
 
       Choose transition:
-      - `more` → have more lessons to classify
+      - `more` → more lessons to classify, or remaining actions for this lesson
       - `suggest_improvements` → also noticed workflow/skill friction
       - `done` → all lessons handled
     transitions:
@@ -86,7 +93,7 @@ states:
       Only suggest changes you're confident about — no speculative ideas.
 
       Choose transition:
-      - `more` → still have lessons to classify from evaluate
+      - `more` → still have lessons to classify
       - `done` → finished
     transitions:
       more: classify

package/templates/review-push.yaml

@@ -1,5 +1,5 @@
 name: review-push
-description: "Review uncommitted changes, then commit and push to GitHub if clean"
+description: "Review uncommitted changes, then build, commit, and push to the remote if clean"
 initial: review
 max_transitions: 60
 
@@ -26,11 +26,17 @@ states:
 
   fix_build:
     task: "Fix build errors"
+    max_visits: 5
     prompt: |
       Build failed. Fix the errors, then build again.
+
+      Budget: 5 visits to this state (engine-enforced); when nearly exhausted
+      and the build still fails, choose `give_up` instead of retrying.
+
       After fixing → `retry`.
     transitions:
       retry: build
+      give_up: failed
 
   commit:
     task: "Commit changes"
@@ -40,9 +46,14 @@ states:
       1. `git status` to see what's being committed
       2. `git diff --stat` for a summary
       3. `git log --oneline -5` to match commit message style
-      4. Stage relevant files (prefer specific files over `git add -A`)
-      5. Write a clear commit message following the repo's convention
-      6. Commit
+      4. Confirm you are on the intended branch (`git branch --show-current`) —
+         if not, stop and sort the branch out first
+      5. Stage relevant files (prefer specific files over `git add -A`)
+      6. Scan the staged diff for secrets (`git diff --cached` — API keys,
+         tokens, passwords, credentials, .env contents). Found any → unstage
+         the file, add it to .gitignore, and report it
+      7. Write a clear commit message following the repo's convention
+      8. Commit
 
       Then → `push`.
     transitions:
@@ -52,12 +63,20 @@ states:
     task: "Push to remote"
     prompt: |
       Push the commit to the remote repository.
-      Run `git push` and verify it succeeds.
-      Report the commit hash and remote URL.
+
+      1. Run `git push`
+      2. Verify it succeeded — push output shows the ref update and
+         `git status` reports the branch is up to date with the remote
+      3. Report the commit hash and remote URL
+
+      Then → transition `done`.
+    transitions:
+      done: finish
+
+  finish:
     terminal: true
     outcome: complete
 
   failed:
-    prompt: "Review or build failed."
     terminal: true
     outcome: fail