claude-mcp-workflow 0.1.0

package/templates/skills/lang-haxe/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: lang-haxe
+description: Haxe language gotchas
+---
+
+# Haxe — Verified Gotchas
+
+## String Interpolation: Single Quotes Only
+
+Inverted from most languages. Double quotes are plain strings.
+
+```haxe
+var name = "world";
+var greeting = 'Hello, $name!';        // ✓ Simple variable — no braces
+var result = 'Sum is ${a + b}';        // ✓ Expression — braces required
+var plain = "No $interpolation here";  // ✗ Literal text, no parsing
+```
+
+- `$name` for simple variables — NO braces
+- `${expr}` only for expressions (field access, math, function calls)
+- `'${_name}'` is wrong → `'$_name'`
+
+## Properties: Never Call set_/get_ Directly
+
+Haxe properties with `(default, set)` or `(get, default)` **always** route through the getter/setter — even for self-assignment inside the owning class. Never bypass the property syntax by calling `set_X()` / `get_X()` directly.
+
+```haxe
+public var thumbSize(default, set):Float = 0;
+
+// WRONG — bypasses property system, anti-pattern
+set_thumbSize(thumbSize);
+
+// RIGHT — property syntax, calls setter
+this.thumbSize = thumbSize;
+
+// BETTER — if value unchanged, call only what's needed
+redrawThumb(thumbSize);  // when only the side-effect matters
+```
+
+- `this.thumbSize = thumbSize` (self-assignment) **does** trigger the setter — Haxe does not optimize it away
+- Direct `set_X()` calls are a Java/C# habit — in Haxe, always use property access
+
+## Null Safety: Narrowing Limitations
+
+### Basic (`@:nullSafety`)
+`if (x != null)` narrows for **argument passing** only. Does NOT narrow for:
+- **Lambda captures**: `() -> useString(x)` — x still nullable
+- **Method calls on nullable**: `handler.bind(...)`, `handler("x")` — error
+
+Fix: pass narrowed value through a helper with non-null param, or use `.bind()` at call site for value types.
+
+### Strict (`@:nullSafety(Strict)`)
+Fields are NEVER narrowed — compiler assumes another thread/callback could modify them. Local variables narrow normally.
+
+**Pattern: capture field into local immediately after null check:**
+```haxe
+// WRONG — field not narrowed in Strict, any statement between check and use resets it
+if (_animate == null) return;
+_transitioning = true;             // ← field write invalidates narrowing
+final animate:AnimatePanel = _animate;  // ERROR: nullable
+
+// RIGHT — local assigned immediately after null check, before any field writes
+if (_animate == null) return;
+final animate:AnimatePanel = _animate;  // ✓ narrowed
+_transitioning = true;
+```
+
+**Pattern: field used multiple times — capture into local:**
+```haxe
+// WRONG — field access, Strict won't narrow
+if (_logo != null) _logo.y = h - _logo.height;  // ERROR
+
+// RIGHT — local variable narrows normally
+final logo:Null<DisplayObject> = _logo;
+if (logo != null) logo.y = h - logo.height;  // ✓
+```
+
+**Pattern: field assigned then used — use local for the non-null path:**
+```haxe
+// WRONG — _logo is Null<T> field, stays nullable after assignment
+_logo = new Bitmap(data);
+_logo.alpha = 0.3;  // ERROR
+
+// RIGHT — assign to local first, then store in field
+final logo:DisplayObject = new Bitmap(data);
+_logo = logo;
+logo.alpha = 0.3;  // ✓
+```
+
+**Key rule:** in Strict mode, ANY intervening statement (even writing to a *different* field) can invalidate narrowing of a nullable field. Always capture to local **immediately** after the null check.
+
+## Map Key-Value Iteration
+
+Use `for (key => value in map)` — cleaner than iterating keys and looking up values separately. Value is guaranteed non-null.
+
+```haxe
+// WRONG — extra lookup + unnecessary null check
+for (f in _frames.keys()) {
+    final fData:Null<Map<Int, Data>> = _frames[f];
+    if (fData != null) { ... }
+}
+
+// WRONG — _ => is redundant, Haxe iterates values by default
+for (_ => data in frameData) { ... }
+
+// RIGHT — key-value destructuring, no lookup, no null check
+for (f => fData in _frames) { ... }
+
+// RIGHT — values only (key unused), just iterate directly
+for (data in frameData) { ... }
+```
+
+**Rule: NEVER use `_ =>` in map iteration.** If the key is unused, drop it — `for (val in map)` iterates values directly.
+
+## Null Coalescing Operator `??`
+
+Use `??` to provide a fallback when left side is null. Combines well with `?.` for chained nullable access.
+
+```haxe
+// WRONG — verbose ternary chains
+fe != null && fe.action != null ? fe.action : (be != null ? be.action : null)
+
+// RIGHT — null-safe access + coalescing
+fe?.action ?? be?.action
+```
+
+- `a ?? b` → returns `a` if non-null, else `b`
+- `fe?.field ?? be?.field` → try `fe.field`, fall back to `be.field`
+
+## Enum Abstract for Simple Enums
+
+For marker enums without associated data, use `enum abstract(Int)` — zero-cost at runtime, compiles to a primitive. Use `final` instead of `var` for values (immutable by intent).
+
+```haxe
+// WRONG — runtime enum objects, unnecessary overhead
+enum ScrollDirection {
+    HORIZONTAL;
+    VERTICAL;
+    BOTH;
+}
+
+// RIGHT — zero-cost, compiles to Int
+enum abstract ScrollDirection(Int) {
+    final HORIZONTAL = 0;
+    final VERTICAL = 1;
+    final BOTH = 2;
+}
+```
+
+- Use regular `enum` only when you need associated data (`case Node(left, right)`) or pattern matching
+- `enum abstract` supports `==` comparison, switch, and all typical enum usage
+
+## Optional Parameters: Type-Based Skipping
+
+Parameters with default values (`param:Type = default`) can be **skipped** at call site. Haxe compiler matches arguments to parameters by type, not just position.
+
+```haxe
+function new(?children:Array<DisplayObject>, ?w:Int, ?h:Int,
+    bgColor:Int = -1, bgAlpha:Float = 1, bgRadius:UInt = 0,
+    alignment:String = "start")
+
+// Skip bgColor, bgAlpha, bgRadius — compiler matches String to alignment:
+super(items, 30, 30, "end");  // ✓ Clean
+super(items, 30, 30, -1, 1, 0, "end");  // ✗ Hardcoding someone else's defaults
+```
+
+**Never hardcode intermediate default values** to reach a later parameter — use type-based skipping instead.
+
+**DANGER: Float constant passed to Int parameter silently skips it.** An `inline final X:Float = 180` looks like an integer but is typed Float. When passed to `new Row(children, X, 16, ...)` where `boxWidth:Int`, the Float skips `boxWidth` and lands on the next Float parameter (e.g. `bgAlpha`). Fix: use `Int` type for constants passed to Int parameters, or cast with `Std.int()`.
+
+## Abstract Classes (Haxe 4.2+)
+
+Native `abstract class` keyword — NOT the same as `abstract` types (which are compile-time wrappers over existing types).
+
+```haxe
+// Abstract base — cannot be instantiated directly
+@:nullSafety abstract class ScrollAxis {
+    abstract private function contentMeasure(content:DisplayObject):Float;
+    abstract private function getScroll(content:DisplayObject):Float;
+
+    // Concrete methods can call abstract ones (template method pattern)
+    public function maxScroll(content:DisplayObject, vp:Float):Float {
+        return Math.max(0, contentMeasure(content) - vp);
+    }
+}
+
+// Subclass — implements abstract methods WITHOUT `override`
+@:nullSafety(Strict) final class VerticalScrollAxis extends ScrollAxis {
+    private function contentMeasure(content:DisplayObject):Float {
+        return content.getBounds(content).bottom * content.scaleY;
+    }
+    private function getScroll(content:DisplayObject):Float {
+        return content.y;
+    }
+}
+```
+
+**Key rules:**
+- `abstract` methods have **no body** — just the signature
+- Subclasses implement abstract methods **WITHOUT** `override` keyword
+- Subclasses override concrete methods **WITH** `override` keyword
+- `abstract class` **cannot** combine with `final` or `inline`
+- Subclasses **can** be `final class`
+- Abstract method calls from constructor work fine (vtable is ready)
+
+## Switch Without Parentheses
+
+In Haxe, `switch` does not require parentheses around the expression (unlike `if`/`while` where they are mandatory).
+
+```haxe
+// WRONG — C-style parentheses
+switch (value) { ... }
+
+// RIGHT — idiomatic Haxe
+switch value { ... }
+```
+
+## If-Expression for Conditional Assignment
+
+`if/else` in Haxe is an expression — use it to assign `final` instead of `var` with mutation.
+
+```haxe
+// WRONG — var with overwrite, dummy initial value
+var target:Float = currentScroll;
+if (condA)
+    target = valueA;
+else if (condB)
+    target = valueB;
+else
+    return;
+
+// RIGHT — final + if-expression
+final target:Float = if (condA)
+    valueA;
+else if (condB)
+    valueB;
+else
+    return;
+
+// RIGHT — with fallback value instead of return
+final target:Float = if (condA) valueA;
+else if (condB) valueB;
+else currentScroll;
+```
+
+- `else return` works inside if-expression — exits function, never assigns
+- Eliminates `var` + mutation pattern
+- Works with `switch` too: `final x:Int = switch v { case A: 1; case B: 2; }`
+
+**Null safety with `?.` on abstract method returns:**
+```haxe
+// WRONG — && narrowing fails for method calls on nullable
+final scrolling:Bool = (_axis != null && _axis.isScrolling());
+
+// RIGHT — safe navigation + explicit comparison
+final scrolling:Bool = (_axis?.isScrolling() == true);
+```

package/templates/skills/lang-python/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: lang-python
+description: Python language gotchas
+---
+
+# Python — Verified Gotchas
+
+## Walrus Operator `:=` Scope Leak in Comprehensions
+
+```python
+results = [c for raw in data if (c := normalize(raw)) is not None]
+# c IS accessible outside the comprehension! (PEP 572 design)
+# Unlike regular loop variables, := leaks to enclosing scope
+```
+
+Sonnet confidently says "c is NOT accessible" — this is wrong. The walrus operator in comprehensions intentionally binds in the containing scope.

package/templates/skills/math/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: math
+description: Math overflow boundary gotchas
+---
+
+# Math — Verified Gotchas
+
+## Central Binomial Coefficient C(n, n/2) overflow
+
+| Type | Last fits | First overflow |
+|------|-----------|----------------|
+| Int64 | C(66, 33) = 7,219,428,434,016,265,740 | C(67, 33) |
+
+Sonnet consistently underestimates this boundary (says n=62, correct is n=66).

package/templates/skills/preferences/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: preferences
+description: User's general coding preferences
+---
+
+## User's personal coding preferences
+
+These rules are set by the user through direct feedback.
+They ALWAYS take priority over base skills.
+
+<!-- Add your preferences here. Examples: -->
+
+### Immutability
+
+- Prefer immutable by default — use `final`/`const`/`readonly`/`val` when value is not reassigned
+
+### Naming
+
+- Private fields (variables) must start with `_` prefix: `_count`, `_items`
+
+### Error handling
+
+- Never silently swallow invalid state — throw exceptions instead of returning quietly
+
+<!-- See https://github.com/anthropics/claude-code/wiki/Skills for more examples -->

package/templates/skills/task-delegation/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: task-delegation
+description: When and how to delegate to subagents
+---
+
+# Task Delegation
+
+## Quick Check
+
+1. **Independent parts?** → if < 2, do it yourself
+2. **Interfaces known?** → if no, do it yourself
+3. **Different skills needed?** → if same, maybe don't split
+4. **Plan ready?** → if no, plan first
+
+**3+ yes → delegate**
+
+## Available Agents
+
+| Agent | Use for |
+|-------|---------|
+| **researcher** | Information gathering, docs, APIs |
+| **coder-python** | Python code |
+| **debugger** | Build, run, test |
+| **general-purpose** | Complex tasks needing MCP tools |
+
+<!-- Add your own agent mappings here, e.g.: -->
+<!-- | **coder-haxe** | Haxe code | -->
+<!-- | **coder-csharp** | C# code | -->
+
+## ALWAYS Delegate to Subagent
+
+Build, run, and test operations → **always** use `debugger` subagent.
+Heavy output (compilation logs, long files, web content) → through subagent with **precise extraction prompt** ("extract only X"), never dump raw output into main context.
+Preserves main context for decision-making.
+
+## Do It Yourself When
+
+- Small task (< 3 files), high coupling, unclear scope, refactoring
+
+## Split By
+
+- **Language**: different languages → different agents
+- **Layer**: Backend / Frontend / Database
+- **Domain**: separate independent domains
+
+## Rules
+
+- **Maximize parallelism** — launch ALL independent agents in **one message**, not sequentially
+- Split by **logical component**, not per file
+- Stabilize interfaces **before** parallelizing
+- Give agents **specific prompts** with file paths and signatures
+- After agents complete: verify integration, link components, test
+- **Review subagent code against loaded skills** — subagent fixes compile but may violate style rules. ALWAYS read changed files and apply loaded preference/lang skills before considering done

package/templates/skills/web-reading/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: web-reading
+description: Fetch web content via subagents
+---
+
+## Goal: protect main context from web content bloat
+
+Every web fetch MUST go through a subagent (Task tool).
+Never put raw web content into main conversation context.
+
+### Step 1: Source-specific tools (no fetch needed)
+
+Pick the right tool before reaching for the web:
+
+- GitHub repos/issues/PRs → `gh` CLI
+- GitHub raw file URLs (.md, .json, .yaml, .txt, etc.) → `gh api` or direct WebFetch (NOT Jina)
+- npm packages → `npm info <pkg>`
+- PyPI packages → `pip show <pkg>`
+- Local files → Read tool
+
+If none apply → Step 2.
+
+### Step 2: Jina Reader via subagent (HTML pages only)
+
+Jina converts HTML → clean markdown. Use ONLY for web pages with HTML content.
+Do NOT use Jina for raw files (.md, .json, .yaml, .txt, .xml, .csv) — use direct WebFetch instead (Step 3).
+
+Use Task tool. Subagent fetches clean content:
+
+```
+https://r.jina.ai/<original-url>
+```
+
+With a precise extraction prompt specifying WHAT to extract.
+
+### Step 3: Direct WebFetch via subagent
+
+If Jina failed (ECONNREFUSED, empty response, error page).
+Subagent uses WebFetch with strict prompt:
+
+> "Extract ONLY the main article content as clean markdown.
+> Ignore navigation, sidebars, headers, footers, ads, cookie banners.
+> Return structured content with headings, code blocks, and lists."
+
+### Step 4: WebSearch
+
+If the page itself is inaccessible — search for the same
+content in mirrors, official docs, blogs, cached versions.
+
+### Step 5: Browser via Playwright MCP (last resort)
+
+When content requires JS rendering or visual analysis:
+
+- Use browser_navigate to open the page
+- Prefer browser_snapshot (text accessibility tree) over screenshots — much lighter
+- Use browser_take_screenshot ONLY when visual layout matters
+- If routing through subagent: subagent analyzes, returns TEXT summary only
+- NEVER pass raw screenshots or DOM dumps to main context
+
+### Prompt rules
+
+ALWAYS specify exactly what to extract. Never "get the page content" or "summarize this page" — state precisely what data you need.

package/templates/subagent.yaml

@@ -0,0 +1,67 @@
+name: subagent
+description: "Workflow for sub-agents spawned by the Task tool. Routes to appropriate sub-workflow, completes task, and exits. No chat, planning, or reflection."
+initial: route
+max_transitions: 50
+
+states:
+  route:
+    prompt: |
+      You are a sub-agent with a specific assigned task.
+      Route based on your task type — do NOT enter chat or planning mode.
+
+      - Read/understand/explore code → explore
+      - Write/modify code → coding
+      - Debug/investigate an issue → debugging
+      - Fix a known bug → bug_fix
+      - Look up docs or web info → research
+      - Run or write tests → testing
+      - Simple direct task (single command, quick answer) → execute
+    transitions:
+      coding: run_coding
+      explore: run_explore
+      debugging: run_debugging
+      bug_fix: run_bug_fix
+      research: run_research
+      testing: run_testing
+      execute: execute
+
+  execute:
+    prompt: |
+      Execute the assigned task directly. No sub-workflow needed.
+      When done → transition `done`.
+    transitions:
+      done: done
+
+  run_coding:
+    sub_workflow: coding
+    on_complete: done
+    on_fail: done
+
+  run_explore:
+    sub_workflow: explore
+    on_complete: done
+    on_fail: done
+
+  run_debugging:
+    sub_workflow: debugging
+    on_complete: done
+    on_fail: done
+
+  run_bug_fix:
+    sub_workflow: bug-fix
+    on_complete: done
+    on_fail: done
+
+  run_research:
+    sub_workflow: web-research
+    on_complete: done
+    on_fail: done
+
+  run_testing:
+    sub_workflow: testing
+    on_complete: done
+    on_fail: done
+
+  done:
+    terminal: true
+    outcome: complete

package/templates/testing.yaml

@@ -0,0 +1,120 @@
+name: testing
+description: "Testing verification sub-workflow — unit tests first, then integration"
+initial: assess
+max_transitions: 30
+
+states:
+  assess:
+    prompt: |
+      Assess what verification is needed for the current change.
+
+      **Decision matrix:**
+      | Change type                        | Unit tests | Integration |
+      |------------------------------------|-----------|-------------|
+      | Pure logic (data, state, algorithms)| YES       | only if affects UI |
+      | Logic + UI (commands, properties)   | YES       | YES |
+      | Pure UI (layout, visual, wiring)    | no        | YES |
+
+      **IMPORTANT**: Steps are strictly sequential. Never parallelize unit and integration —
+      they often share the same output binary and will conflict.
+
+      Choose transition:
+      - `has_unit` → change touches logic with existing or meaningful tests
+      - `skip_to_integration` → pure UI change, no unit-testable logic
+      - `skip_all` → trivial wiring fix fully covered by existing tests
+    transitions:
+      has_unit: unit_tests
+      skip_to_integration: check_integration
+      skip_all: done
+
+  unit_tests:
+    max_visits: 5
+    prompt: |
+      Write and run unit tests for the changed behavior.
+
+      **If bug fix — Red-Green workflow (mandatory):**
+      1. Write test targeting buggy behavior → run → confirm FAILS (red)
+      2. Apply fix → run → confirm PASSES (green)
+
+      **Otherwise:**
+      1. Find existing test files for patterns
+      2. Write tests covering new/changed behavior
+      3. Register new test class if needed
+
+      Run via `debugger` subagent to keep build output out of main context.
+
+      Choose transition:
+      - `pass` → all unit tests pass
+      - `fail` → tests failing, need fixes
+    transitions:
+      pass: check_integration
+      fail: fix_unit
+
+  fix_unit:
+    prompt: |
+      Unit tests are failing. Analyze the failures and fix the code.
+
+      Do NOT fix tests to match wrong behavior — fix the implementation.
+      After fixing, transition back to re-run unit tests.
+
+      Choose transition:
+      - `retry` → fixed, re-run unit tests
+      - `give_up` → unable to fix after multiple attempts
+    transitions:
+      retry: unit_tests
+      give_up: failed
+
+  check_integration:
+    prompt: |
+      Does this change affect what the user sees or interacts with?
+
+      - If yes AND project has a debug bridge → `need_integration`
+      - If no (pure backend/data change fully covered by unit tests) → `skip`
+
+      Choose transition:
+      - `need_integration` → must verify via integration test
+      - `skip` → unit tests are sufficient
+    transitions:
+      need_integration: integration
+      skip: done
+
+  integration:
+    max_visits: 5
+    prompt: |
+      Run integration verification.
+
+      1. Build and launch via `debugger` subagent
+      2. Simulate the actual user workflow end-to-end
+      3. Verify state changes propagated correctly (screenshots, state inspection)
+
+      **Bug fixes**: reproduce the EXACT user scenario that triggered the bug.
+      Check for regressions in related workflows.
+
+      Choose transition:
+      - `pass` → integration verified, behavior correct
+      - `fail` → integration broken, need fixes
+    transitions:
+      pass: done
+      fail: fix_integration
+
+  fix_integration:
+    prompt: |
+      Integration test failed. Analyze what broke and fix it.
+
+      After fixing, transition back to re-run integration.
+
+      Choose transition:
+      - `retry` → fixed, re-run integration tests
+      - `give_up` → unable to fix after multiple attempts
+    transitions:
+      retry: integration
+      give_up: failed
+
+  done:
+    prompt: "All required tests pass. Verification complete."
+    terminal: true
+
+  failed:
+    prompt: "Testing failed after maximum attempts. Report failures to the user."
+    terminal: true
+    outcome: fail

package/templates/web-research.yaml

@@ -0,0 +1,53 @@
+name: web-research
+description: "Web research workflow — check existing knowledge, then delegate to web subagents"
+initial: check_existing
+max_transitions: 20
+
+states:
+  check_existing:
+    prompt: |
+      Before researching externally, check what you already know:
+
+      1. Check loaded skills and MEMORY.md
+      2. Check project documentation (CLAUDE.md, README)
+      3. If answer is already available → transition `already_known`
+      4. If not enough → transition `need_research`
+
+      **When NOT to research:**
+      - Confident and routine task
+      - Answer is in a loaded skill
+    transitions:
+      already_known: apply
+      need_research: delegate
+
+  delegate:
+    prompt: |
+      Call `Skill("web-reading")` for the web access tool hierarchy.
+
+      Delegate to `researcher` subagents:
+      - Split broad questions into 3-5 narrow ones, launch in parallel
+      - Each returns only a concise answer
+      - Follow tool hierarchy from loaded web-reading skill
+      - Extract ONLY what's needed
+
+      Choose transition:
+      - `found` → got the answer, ready to apply
+      - `not_found` → could not find reliable information
+    transitions:
+      found: apply
+      not_found: done
+
+  apply:
+    prompt: |
+      Apply research results to the current task.
+
+      If this reveals a recurring knowledge gap → note it for reflection.
+
+      Choose transition:
+      - `done` → results applied or communicated to user
+    transitions:
+      done: done
+
+  done:
+    prompt: "Web research complete."
+    terminal: true