claude-mcp-workflow 0.1.0

package/templates/investigate.yaml

@@ -0,0 +1,84 @@
+name: investigate
+description: "Investigation workflow — resolve unknowns before deciding on action. For tasks that describe desired changes but contain questions, uncertainties, or assumptions that need verification first."
+initial: parse
+max_transitions: 25
+
+states:
+  parse:
+    prompt: |
+      The user's task contains unknowns that need investigation before coding.
+
+      1. Extract from the user's message:
+         - **Goal**: what the user ultimately wants changed
+         - **Unknowns**: questions, uncertainties, assumptions to verify
+           (markers: "вроде", "кажется", "если это так", "не уверен", "should",
+            "not sure", "?", conditional language, hedging)
+         - **Knowns**: concrete facts or behaviors stated as certain
+
+      2. Formulate 1-3 specific investigation questions to resolve the unknowns
+
+      Present the breakdown to the user briefly, then → transition `explore`.
+    transitions:
+      explore: run_explore
+
+  run_explore:
+    sub_workflow: explore
+    on_complete: assess
+    on_fail: assess
+
+  assess:
+    prompt: |
+      Investigation complete. Review findings against the original unknowns.
+
+      Present to the user:
+      1. For each unknown — what did investigation reveal?
+      2. Does the desired change still make sense given the findings?
+      3. Recommended action and scope
+
+      Choose transition:
+      - `trivial` → fix is obvious and small (1-3 lines), apply it now
+      - `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: quick_fix
+      needs_plan: needs_plan
+      no_action: done
+      unclear: clarify
+
+  clarify:
+    prompt: |
+      Present findings and remaining questions to the user.
+      Use AskUserQuestion for critical decisions.
+
+      After getting user's answer → transition based on clarity:
+      - `reassess` → re-evaluate with new info
+      - `done` → user says no action needed
+    transitions:
+      reassess: assess
+      done: done
+
+  quick_fix:
+    prompt: |
+      MANDATORY FIRST ACTION — call `Skill("coding-skill-selector")` to load
+      language/domain skills BEFORE writing code.
+
+      The fix is trivial (1-3 lines). Apply it directly.
+      After fixing → transition `done`.
+    transitions:
+      done: fixed
+
+  fixed:
+    prompt: "Investigation + quick fix complete."
+    terminal: true
+    outcome: complete
+
+  needs_plan:
+    prompt: "Investigation complete. Changes need planning — escalating."
+    terminal: true
+    outcome: fail
+
+  done:
+    prompt: "Investigation complete. No code changes needed."
+    terminal: true
+    outcome: complete

package/templates/master.yaml

@@ -0,0 +1,202 @@
+name: master
+description: "Master workflow — single entry point replacing skill-selector. Analyzes task, loads knowledge skills, routes to process sub-workflows."
+initial: route
+max_transitions: 100
+
+states:
+  route:
+    prompt: |
+      STOP. This is a routing state. Do NOT perform any work. Do NOT answer the user.
+      The ONLY tool calls allowed here are list and transition.
+
+      **Step 1 — Check for project workflows.**
+      Call `list`. Look for workflows NOT in the global set (coding, debugging,
+      bug-fix, new-feature, refactoring, code-review, explore, web-research, planning,
+      testing, reflection, investigate, master). If a project workflow exists and its description
+      matches the user's task → transition `project` and set context key
+      `project_workflow` to that workflow's name.
+
+      **Step 2 — Standard routing (only if no project workflow matched).**
+
+      Plan mode active in system prompt? → plan
+
+      Plan override — always `plan` when ANY apply:
+      - 5+ files touched, mixed actions, cascade risk, user asks to plan
+
+      Route the user's message:
+      - understand/investigate → debugging or explore (NEVER coding)
+      - questions about code behavior ("will X break?", "how does Y work?",
+        "what happens when Z?") → explore (requires reading code before answering)
+      - task describes desired changes BUT contains unknowns, questions, or
+        uncertainty about current behavior → investigate (NEVER coding)
+        Markers: "вроде", "кажется", "если это так", "не уверен", "should X?",
+        "not sure if", conditional "если/if", multiple interleaved questions,
+        hedging language. When in doubt between coding and investigate → investigate.
+      - write/modify code (1-4 files), scope is clear → coding
+      - new feature e2e → feature
+      - fix known bug → bug_fix
+      - restructure code → refactoring
+      - review PR/code → code_review
+      - look up docs/web → research
+      - conversation that does NOT require reading code (greetings, meta-questions
+        about workflow, preferences, general knowledge) → chat
+      - unclear → unclear
+
+      Code reference in system-reminder → code-related (code_review, explore, or coding), NEVER chat.
+
+      → Call transition NOW.
+    transitions:
+      plan: plan
+      project: run_project
+      coding: run_coding
+      feature: run_feature
+      bug_fix: run_bug_fix
+      debugging: run_debugging
+      investigate: run_investigate
+      refactoring: run_refactoring
+      code_review: run_code_review
+      research: run_research
+      explore: run_explore
+      chat: chat
+      unclear: clarify
+
+  clarify:
+    prompt: |
+      The task is unclear. Ask the user to clarify:
+      - What exactly do they need?
+      - Is this a bug fix, new feature, refactoring, research, or codebase exploration?
+      - What files/areas are involved?
+
+      After getting clarification → transition `got_info` to re-analyze.
+    transitions:
+      got_info: route
+
+  plan:
+    sub_workflow: planning
+    on_complete: route_execution
+    on_fail: reflect
+
+  route_execution:
+    prompt: |
+      The plan has been approved. Now route to the correct execution workflow.
+
+      Read the plan file — check the "Execution workflow" field in the Workflow section.
+
+      Choose transition:
+      - `coding` → plan says coding
+      - `refactoring` → plan says refactoring
+      - `feature` → plan says feature
+      - `bug_fix` → plan says bug_fix
+      - `project` → plan says project-specific workflow (set context key `project_workflow`)
+      - `dynamic` → plan says dynamic (complex multi-step, needs create)
+    transitions:
+      coding: run_coding
+      refactoring: run_refactoring
+      feature: run_feature
+      bug_fix: run_bug_fix
+      project: run_project
+      dynamic: create_dynamic
+
+  create_dynamic:
+    prompt: |
+      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:
+         - add_state: {name: "run_dynamic", sub_workflow: "<workflow name>", on_complete: "reflect", on_fail: "reflect"}
+         - add_transition: {from: "create_dynamic", name: "execute", to: "run_dynamic"}
+      3. Transition `execute`
+    transitions:
+      execute: reflect
+
+  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:
+         - add_state: {name: "run_project_sub", sub_workflow: "<workflow name>", on_complete: "reflect", on_fail: "reflect"}
+         - add_transition: {from: "run_project", name: "execute", to: "run_project_sub"}
+      3. Transition `execute`
+    transitions:
+      execute: reflect
+
+  run_investigate:
+    sub_workflow: investigate
+    on_complete: reflect
+    on_fail: plan
+
+  run_coding:
+    sub_workflow: coding
+    on_complete: reflect
+    on_fail: reflect
+
+  run_debugging:
+    sub_workflow: debugging
+    on_complete: reflect
+    on_fail: reflect
+
+  run_feature:
+    sub_workflow: new-feature
+    on_complete: reflect
+    on_fail: reflect
+
+  run_bug_fix:
+    sub_workflow: bug-fix
+    on_complete: reflect
+    on_fail: reflect
+
+  run_code_review:
+    sub_workflow: code-review
+    on_complete: done
+    on_fail: done
+
+  run_refactoring:
+    sub_workflow: refactoring
+    on_complete: reflect
+    on_fail: reflect
+
+  run_research:
+    sub_workflow: web-research
+    on_complete: done
+    on_fail: done
+
+  run_explore:
+    sub_workflow: explore
+    on_complete: explore_outcome
+    on_fail: done
+
+  explore_outcome:
+    prompt: |
+      Exploration is complete. Decide what happens next based on the findings:
+
+      - If the findings indicate code changes are needed (delete dead code, refactor,
+        fix a bug, implement something) → transition `plan` to enter planning.
+      - If the exploration was purely informational (understand how something works,
+        answer a question, no action needed) → transition `done`.
+
+      Review the synthesized findings and decide.
+    transitions:
+      plan: plan
+      done: done
+
+  chat:
+    terminal: true
+    outcome: complete
+    prompt: |
+      Pure conversation — no code, no sub-workflow.
+
+      Answer the user's question or respond to their message directly.
+
+      If the user's next message changes scope (coding, research, etc.) → transition `next_task`.
+    transitions:
+      next_task: route
+
+  reflect:
+    sub_workflow: reflection
+    on_complete: done
+    on_fail: done
+
+  done:
+    terminal: true
+    outcome: complete

package/templates/new-feature.yaml

@@ -0,0 +1,41 @@
+name: new-feature
+description: "New feature implementation workflow"
+initial: requirements
+max_transitions: 80
+
+states:
+  requirements:
+    task: "Clarify requirements"
+    prompt: "Clarify requirements with the user. What exactly should this feature do?"
+    transitions:
+      clear: plan
+
+  plan:
+    sub_workflow: planning
+    on_complete: implement
+    on_fail: requirements
+
+  implement:
+    task: "Implement the feature"
+    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.
+
+      Implement the feature according to the plan.
+    transitions:
+      done: test
+
+  test:
+    sub_workflow: testing
+    on_complete: review
+    on_fail: implement
+
+  review:
+    task: "Review implementation"
+    prompt: "Review the implementation. Check for edge cases, code quality, and adherence to project conventions."
+    transitions:
+      approved: done
+      changes_needed: implement
+
+  done:
+    prompt: "Feature implemented, tested, and reviewed."
+    terminal: true

package/templates/planning.yaml

@@ -0,0 +1,85 @@
+name: planning
+description: "Planning sub-workflow — explore, design plan, record workflow context"
+initial: explore_needed
+max_transitions: 30
+
+states:
+  explore_needed:
+    prompt: |
+      Determine if codebase exploration is needed before planning.
+
+      1. Check loaded skills, MEMORY.md, and project CLAUDE.md
+      2. Read the user's task description — do you already understand the scope?
+
+      Choose transition:
+      - `explore` → need to explore codebase first
+      - `skip` → scope is clear, go straight to planning
+    transitions:
+      explore: run_explore
+      skip: design
+
+  run_explore:
+    sub_workflow: explore
+    on_complete: design
+    on_fail: design
+
+  design:
+    prompt: |
+      Load architecture skill: `Skill("architecture")`.
+
+      Design the implementation plan.
+
+      **Plan mode**: if system prompt says "Plan mode is active" — you're already in it,
+      do NOT call EnterPlanMode. Otherwise call `EnterPlanMode`.
+
+      **Dynamic check**: If the task is operational/multi-step (not pure code changes —
+      e.g. git operations, deployment, file management, CI/CD setup) → transition `dynamic`
+      to create the execution workflow directly instead of writing a text plan.
+
+      **Steps in plan mode:**
+      1. Explore codebase (Read/Glob/Grep or 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`):
+         ```
+         ## Workflow
+         - **Session**: `<session_id>`
+         - **Current state**: `planning @ design`
+         - **After approve**: transition `planned` → returns to parent
+         - **Execution workflow**: coding / refactoring / dynamic
+         - **Resume**: `transition("<session_id>", "planned")`
+         ```
+      5. Call `ExitPlanMode` for user approval
+
+      **After plan approved → transition `planned`.**
+    transitions:
+      planned: done
+      dynamic: create_workflow
+
+  create_workflow:
+    prompt: |
+      The task is operational/dynamic — create the execution workflow directly.
+      The workflow IS the plan.
+
+      **Plan mode**: if system prompt says "Plan mode is active" — you're already in it,
+      do NOT call EnterPlanMode. Otherwise call `EnterPlanMode`.
+
+      1. Design the step-by-step workflow
+      2. Call `create("task-<name>", definition)` with focused states
+         - Each state should be small and actionable
+         - Always have `done` (terminal, outcome: complete) and `failed` (terminal, outcome: fail)
+         - Use `on_fail` for recovery paths
+      3. Save workflow name to context: `context_set(session_id, "dynamic_workflow", "task-<name>")`
+      4. Write plan file with:
+         - Brief context of what the workflow does
+         - Reference to the created workflow name
+         - Workflow section with `Execution workflow: dynamic`
+      5. Call `ExitPlanMode` for user approval
+
+      **After plan approved → transition `planned`.**
+    transitions:
+      planned: done
+
+  done:
+    prompt: "Plan approved. Returning to parent workflow for execution."
+    terminal: true

package/templates/refactoring.yaml

@@ -0,0 +1,56 @@
+name: refactoring
+description: "Refactoring workflow — bring every touched file to current standards"
+initial: prepare
+max_transitions: 40
+
+states:
+  prepare:
+    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.
+
+      Before writing any code:
+
+      1. **Read every file you will touch** — understand before changing
+
+      Refactoring = bringing touched files to standards from loaded skills.
+      Don't cargo-cult the original — it may predate current skills.
+
+      When files are read and understood → transition `ready`.
+    transitions:
+      ready: write
+
+  write:
+    prompt: |
+      Apply refactoring. For each touched file, apply ALL loaded preference/lang skill checklists.
+
+      Check every pattern against loaded skills before preserving it.
+
+      Choose transition:
+      - `review` → done writing, ready for review
+    transitions:
+      review: review
+
+  review:
+    prompt: |
+      Review the complete refactoring:
+
+      1. Compare before/after — verify no behavior changes
+      2. Check all touched files against ALL loaded skills at once
+      3. Look for new extraction opportunities created by refactoring
+      4. Dead code — remove anything made unnecessary
+
+      Choose transition:
+      - `verify` → review passed, ready for testing
+      - `fix` → found issues, go back to write
+    transitions:
+      verify: verify
+      fix: write
+
+  verify:
+    sub_workflow: testing
+    on_complete: done
+    on_fail: write
+
+  done:
+    prompt: "Refactoring complete. All touched files conform to current standards. Tests pass."
+    terminal: true

package/templates/reflection.yaml

@@ -0,0 +1,61 @@
+name: reflection
+description: "Self-reflection after significant tasks — evaluate, classify, act"
+initial: evaluate
+max_transitions: 15
+
+states:
+  evaluate:
+    prompt: |
+      Evaluate the completed task:
+
+      - Was it a clean pass, or were there errors/retries?
+      - Any hallucinations (made-up names, paths, APIs)?
+      - Unnecessary complexity added?
+      - User had to correct you or wait?
+
+      Choose transition:
+      - `has_lesson` → found something worth recording
+      - `clean` → task went smoothly
+    transitions:
+      has_lesson: classify
+      clean: done
+
+  classify:
+    prompt: |
+      Classify the lesson — where does it belong?
+
+      | Type | Destination | Example |
+      |------|------------|---------|
+      | Factual error, gotcha | Skill (ENRICH) | "Fib(47) overflows Int32" |
+      | Missing domain knowledge | New skill (CREATE) | No skill for gRPC |
+      | Process/approach pattern | Skill (ENRICH) | "Always verify packages" |
+      | Project-specific quirk | MEMORY.md | "Custom ORM, not EF" |
+      | Project build/config | MEMORY.md | "Needs --legacy-peer-deps" |
+
+      Choose transition:
+      - `enrich_skill` → update existing skill via skill-manager ENRICH
+      - `create_skill` → systemic gap, create new skill via skill-manager CREATE
+      - `update_memory` → project-specific, write to MEMORY.md
+    transitions:
+      enrich_skill: action
+      create_skill: action
+      update_memory: action
+
+  action:
+    prompt: |
+      Execute the classified action:
+
+      - **ENRICH**: identify which skill → research correct answer → use skill-manager ENRICH
+      - **CREATE**: only if systemic gap → use skill-manager CREATE
+      - **MEMORY.md**: write project-specific knowledge to auto-memory
+
+      After acting, acknowledge the lesson to the user honestly.
+
+      Choose transition:
+      - `done` → action completed
+    transitions:
+      done: done
+
+  done:
+    prompt: "Reflection complete."
+    terminal: true

package/templates/skills/architecture/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: architecture
+description: Simplicity-first architecture decisions
+---
+
+# Architecture — Behavioral Correction
+
+Claude's #1 architecture mistake: **adding complexity before pain exists.**
+
+## Before Suggesting ANY Pattern
+
+Three questions (if you can't answer all three concretely, suggest the simpler option):
+1. **What specific pain exists RIGHT NOW?** (not theoretical)
+2. **What's the simplest thing that solves just this pain?**
+3. **How will I know when this decision becomes wrong?** (exit criteria)
+
+## The Interface Trap (Verified Gotcha)
+
+**DON'T:** Create interfaces "for testability" or "future flexibility"
+**DO:** Create interfaces when you have 2+ real implementations OR a package boundary
+**GOTCHA:** Single implementation behind interface is ceremony, not architecture
+**EXCEPTION:** Public library APIs only
+
+Sonnet defaults to "interfaces for testing are fine" — this skill corrects that.
+
+## Response Template
+
+```
+Simple approach: [simplest solution]
+This works until: [specific pain point]
+
+If you hit that pain, then consider: [next step up]
+This adds: [specific cost]
+But solves: [specific problem]
+```
+
+## Initialization Belongs to the Owner
+
+When a component needs setup logic (creating initial children, dispatching init events, setting initial state), that logic belongs **inside** the component — not in its parent.
+
+**DON'T:** Parent creates component, then manually triggers component's internal logic from outside
+**DO:** Component exposes an `open()` / `init()` method or handles it in constructor — parent just calls that
+
+**Why:** Parent shouldn't know component's internal structure. If internals change, only the component changes — parent stays untouched.
+
+## Serialization Doesn't Belong in Runtime State
+
+**DON'T:** Put `serialize()`/`deserialize()` methods directly in runtime/state classes
+**DO:** Keep serialization in a separate class or in the persistence layer
+
+**Why:** Runtime state manages current values, interpolation, transitions. Serialization is I/O concern — different reason to change, different dependencies (XML, JSON, etc.). Mixing them inflates the class and hides the boundary.
+
+**GOTCHA at review:** Inline serialization "works" and passes tests — the violation is structural, not functional. Actively check for it: if a class has both state logic AND `serialize`/`deserialize`, flag it.
+
+When in doubt: **suggest the boring, proven, simple solution.**

package/templates/skills/coding-skill-selector/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: coding-skill-selector
+description: Select and load coding skills by file extensions and domains
+---
+
+## Coding skill selector
+
+Load coding skills for files/context in this task.
+
+1. Always: `Skill("preferences")` + `Skill("architecture")`
+2. By extension:
+   - .py → `Skill("lang-python")`
+   - .hx → `Skill("lang-haxe")`
+   <!-- Add your own language/domain mappings here, e.g.: -->
+   <!-- - .cs → `Skill("preferences-csharp")` -->
+3. By domain:
+   <!-- Add domain-specific skills here, e.g.: -->
+   <!-- - gamedev → `Skill("domain-gamedev")` -->
+   <!-- - CMake → `Skill("build-cmake")` -->
+4. If 3+ files: `Skill("task-delegation")`
+
+Call `Skill(name)` for EVERY matched skill.
+
+**Gap check**: If files involve a language/domain with no matching skill,
+ask the user: "No skill for [X] — proceed without, or create one first?"