create-byan-agent 2.21.0 → 2.22.0

package/CHANGELOG.md

@@ -9,6 +9,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.22.0] - 2026-06-09
+
+### Changed - byan_dispatch routes the model tier by task nature, not by size
+
+`byan_dispatch` fused two unrelated decisions into one route string
+(`mcp-worker-haiku`, `main-thread-opus`): a short sequential task was downgraded
+to haiku purely on its length, and a long one was pinned up to opus. That is the
+size-driven mis-tiering the native-workflow doctrine (`native-tiers.js`) was built
+to forbid, so the two routers disagreed. This decouples the two axes and makes
+`native-tiers.js` the single source of truth for the model tier across both worlds.
+
+- **Two independent axes.** `dispatch.js` now returns
+  `{ score, strategy, nature, tier, model, parallelizable, reasoning }`. STRATEGY
+  (where the work runs: `main-thread` / `agent-subagent-worktree` / `mcp-worker`)
+  stays derived from the scalar score + `parallelizable`. TIER (which model) is
+  derived from the task NATURE, decoupled from size.
+- **One source of truth.** `dispatch.js` imports `classifyLeaf` / `tierFor` /
+  `TIER_MODEL` directly from `native-tiers.js` — a one-way dependency toward the
+  tier authority rather than a duplicated rule. Only an `exploration` nature
+  downgrades to `haiku`; `implementation` / `verification` / `analysis` (and any
+  unmatched task) stay `deep` (inherit the session model). No pin-up to opus.
+- **Conservative by default.** An optional `nature` arg sets the tier directly;
+  absent or invalid, the task text is classified, whose own default is
+  `implementation` (deep) — so a miss protects the work instead of downgrading it.
+- **Consumers realigned.** The `byan_dispatch` tool schema gains an optional
+  `nature` enum; the three consuming skills (byan-byan Phase 4, byan-hermes-dispatch
+  step 3, byan-orchestrate) read `strategy` + `model` from the new shape. The
+  fused-route strings are dropped from the live routing path.
+- 22 dispatch unit tests pin the contract (no downgrade for protected natures,
+  exploration to haiku, no pin-up, conservative fallback, strategy preserved across
+  the score bands) plus the hermes-e2e non-regression. Template re-synced.
+
+### Known debt
+
+The legacy fused-route vocabulary (`mcp-worker-haiku` / `main-thread-opus`) still
+appears in two doctrine docs (`_byan/worker/workers.md`,
+`_byan/workflow/simple/byan/feature-workflow.md`) and a dead, unreferenced parallel
+router (`src/core/dispatcher/execution-router.js` + its test). These have no live
+consumer and are scoped to a follow-up cleanup.
+
 ## [2.21.0] - 2026-06-08
 
 ### Added - Template fidelity sync (the published package matches its CHANGELOG)

package/install/templates/.claude/skills/byan-byan/SKILL.md

@@ -56,11 +56,16 @@ Never call `byan_update_apply` without explicit user consent. That tool returns
 
 ### Phase 4 — DISPATCH
 - **Who** : you + user. Route each feature to the right BYAN component.
-- **Decision table** per feature :
-  - **Score < 15** → inline main-thread, no subagent
-  - **Score 15-39 parallelizable** → agent-subagent-worktree (use `byan_dispatch` MCP tool to verify)
-  - **Score 15-39 sequential** → mcp-worker-haiku
-  - **Score ≥ 40** → main-thread-opus or delegate to `byan-hermes-dispatch`
+- **Decision table** per feature — TWO independent axes (`byan_dispatch` returns both) :
+  - **Strategy** (WHERE it runs), from the score :
+    - **Score < 15** → inline main-thread, no subagent
+    - **Score 15-39 parallelizable** → agent-subagent-worktree
+    - **Score 15-39 sequential** → mcp-worker
+    - **Score ≥ 40** → main-thread (heavy) or delegate to `byan-hermes-dispatch`
+  - **Model tier** (WHICH model), from the task NATURE — not its size (`byan_dispatch` returns it as `model`, via native-tiers, the single source of truth) :
+    - nature `exploration` (load/read/scan/list/parse/fetch...) → `haiku`
+    - nature `implementation` / `verification` / `analysis` / unknown → deep = **inherit the session model**
+    - Keep protected work (verify/analysis/implement) off haiku regardless of size ; no pin-up to opus. Pass an explicit `nature` to `byan_dispatch` when you know it.
 - **Output** : a table `{ feature → specialist → model → strategy → estimated_tokens }`.
 - **If no specialist matches** : halt. Ask user whether to run INT (agent recruitment) first. Do NOT fallback silently to general-purpose.
 - **Exit gate** : user validates the mapping.

package/install/templates/.claude/skills/byan-hermes-dispatch/SKILL.md

@@ -50,18 +50,19 @@ Match keywords against the routing table below. Pick the single best match. If n
 
 ### 3. Pick the execution strategy (MCP call)
 
-Call the `byan_dispatch` MCP tool with `{ task: <goal>, parallelizable: <bool> }`. It returns `{ strategy, score, reasoning }` where strategy is one of :
+Call the `byan_dispatch` MCP tool with `{ task: <goal>, parallelizable: <bool>, nature?: <leaf-type> }`. It returns `{ score, strategy, nature, tier, model, reasoning }` — TWO independent axes :
 
-- `main-thread` — do it inline, no delegation
-- `agent-subagent-worktree` — spawn Agent tool with isolation worktree
-- `mcp-worker-haiku` — spawn Agent tool with Haiku model, no worktree
-- `main-thread-opus` — keep in the current thread (don't delegate, Opus needed)
+- **strategy** (WHERE it runs), from the score :
+  - `main-thread` — do it inline, no delegation
+  - `agent-subagent-worktree` — spawn Agent tool with isolation worktree
+  - `mcp-worker` — spawn Agent tool, no worktree
+- **model** (WHICH model), from the task NATURE via native-tiers, not its size : `haiku` (exploration only) or `null` = deep (inherit the session model). Pass an explicit `nature` (`exploration`/`implementation`/`verification`/`analysis`) when you know it; protected natures stay off haiku.
 
 ### 4. Spawn the work
 
-Depending on strategy :
+Depending on strategy (apply the returned `model` whenever you spawn) :
 
-**`main-thread` or `main-thread-opus`** : do not spawn. Execute inline yourself.
+**`main-thread`** : do not spawn. Execute inline yourself — the work runs on the session model.
 
 **`agent-subagent-worktree`** : call the Agent tool with :
 ```
@@ -76,7 +77,9 @@ prompt: |
   When done, write a concise report (< 200 words).
 ```
 
-**`mcp-worker-haiku`** : same Agent tool call but without `isolation`, and add `model: "haiku"` in the prompt's instruction block if the receiving subagent honors it.
+**`mcp-worker`** : same Agent tool call but without `isolation`. Set the Agent's `model` to the returned `model` — `haiku` for exploration nature, otherwise omit `model` to inherit the session model. The tier follows the task nature, not its size.
+
+For any spawned strategy : pass `model` to the Agent tool when it is non-null; omit it when null so the subagent inherits the session model.
 
 ### 5. Specialist stub path lookup
 

package/install/templates/.claude/skills/byan-orchestrate/SKILL.md

@@ -9,7 +9,7 @@ You compose three existing building blocks into one multi-role flow :
 
 | Block | Role |
 |-------|------|
-| `byan_dispatch` MCP tool | Per-task execution strategy (main-thread / agent-subagent-worktree / mcp-worker-haiku / main-thread-opus) + complexity score |
+| `byan_dispatch` MCP tool | Per-task strategy (main-thread / agent-subagent-worktree / mcp-worker) from the score + model tier by NATURE (haiku for exploration, else inherit the session model) + complexity score |
 | `byan-hermes-dispatch` skill | Specialist lookup (architect, dev, analyst, …) from a routing table |
 | `party-mode-native` workflow | Parallel spawn via Agent tool + worktree + coordination JSON |
 
@@ -42,7 +42,7 @@ Use this a priori mapping — override only if the task clearly needs more :
 | architect, quinn, tea, creative-problem-solver | opus | Deep reasoning, trade-offs |
 | carmack, rachid, marc, patnote | haiku | Narrow mechanical tasks |
 
-Then call `byan_dispatch` with each role's goal to get a complexity score. If the score demands a different tier (score >= 40 → bump to opus ; score < 15 → inline, no subagent), **override the default for that role**.
+Then call `byan_dispatch` with each role's goal (and `nature` when known). Use its `score` for the STRATEGY only (score < 15 → inline, no subagent ; 15-39 → subagent/worker ; ≥ 40 → keep the heavy role in the main thread) and its nature-based `model` as the tier signal. The score sets WHERE the role runs, not WHICH model — keep protected roles (verify/analysis/implement) off haiku regardless of size, and avoid pinning a role up to opus on size alone. The per-role table above is the a-priori floor; `byan_dispatch`'s nature `model` refines it.
 
 ### 3. Compute the execution plan
 
@@ -69,7 +69,7 @@ Group roles by `parallelizable_with` graph. For each parallel cluster :
 
 - If cluster has N > 1 roles AND all use `agent-subagent-worktree` strategy → use the **party-mode-native** workflow : `coordination.initSession(roles, …)`, then dispatch all Agent tool calls in a single message.
 - If cluster has N = 1 OR strategy = `main-thread` → execute inline in the current turn.
-- If strategy = `mcp-worker-haiku` → spawn an Agent tool call WITHOUT worktree (faster boot, single-turn).
+- If strategy = `mcp-worker` → spawn an Agent tool call WITHOUT worktree (faster boot, single-turn) ; set the Agent's model to the role's nature-based `model` (haiku for exploration, omit otherwise to inherit the session model).
 
 For each Agent tool call, the prompt must start with :
 ```

package/install/templates/_byan/mcp/byan-mcp-server/lib/dispatch.js

@@ -1,23 +1,75 @@
-export function dispatch({ task, complexity, parallelizable }) {
+import { classifyLeaf, tierFor, TIER_MODEL, LEAF_TYPES } from './native-tiers.js';
+
+// byan_dispatch routes a unit of work along TWO independent axes:
+//
+//   STRATEGY  — WHERE the work runs (inline / isolated subagent / mcp worker).
+//               Derived from the scalar score + parallelizable. This is
+//               dispatch's own concern: orchestration.
+//   TIER      — WHICH model the work deserves. Delegated to native-tiers (the
+//               single source of truth), keyed on the task's NATURE, never on its
+//               size. Only exploration downgrades to a cheap tier; implementation,
+//               verification, analysis (and anything unmatched) stay deep =
+//               inherit the session model. We never PIN UP to opus.
+//
+// Before this split the two axes were fused into one route string
+// ('mcp-worker-haiku', 'main-thread-opus'), so a short sequential task was
+// silently downgraded to haiku purely on length, and a long one was pinned up to
+// opus — exactly the size-driven mis-tiering native-tiers' anti-downgrade doctrine
+// forbids. The score still picks the strategy; the model now comes from nature.
+//
+// The dependency on native-tiers is intentional and one-directional: dispatch
+// CONSUMES the tier source of truth, it does not duplicate it. native-tiers is a
+// pure, IO-free module, so the import is safe and keeps the tiering doctrine in a
+// single place.
+
+const VALID_NATURES = new Set(Object.values(LEAF_TYPES));
+
+export function dispatch({ task, complexity, parallelizable, nature } = {}) {
   const score =
     typeof complexity === 'number'
       ? complexity
       : Math.min(100, Math.floor((task?.length || 0) / 10));
   const isPar = parallelizable === true;
 
-  let route, reasoning;
+  // Axis 1 — strategy (where). Scalar, as before, minus the fused model suffix.
+  let strategy, strategyReason;
   if (score < 15) {
-    route = 'main-thread';
-    reasoning = `Score ${score} < 15. Inline in current context, no delegation overhead.`;
+    strategy = 'main-thread';
+    strategyReason = `score ${score} < 15: inline, no delegation overhead`;
   } else if (score < 40 && isPar) {
-    route = 'agent-subagent-worktree';
-    reasoning = `Score ${score} + parallelizable. Spawn Claude Code Agent tool with worktree isolation.`;
+    strategy = 'agent-subagent-worktree';
+    strategyReason = `score ${score} + parallelizable: isolated subagent (worktree)`;
   } else if (score < 40) {
-    route = 'mcp-worker-haiku';
-    reasoning = `Score ${score}, sequential. Delegate to lightweight Haiku worker via MCP.`;
+    strategy = 'mcp-worker';
+    strategyReason = `score ${score}, sequential: delegated MCP worker`;
   } else {
-    route = 'main-thread-opus';
-    reasoning = `Score ${score} >= 40. Complex task, keep in main thread with Opus reasoning.`;
+    strategy = 'main-thread';
+    strategyReason = `score ${score} >= 40: heavy, kept in the main thread`;
   }
-  return { score, route, reasoning, parallelizable: isPar };
+
+  // Axis 2 — tier (which model). By nature, via native-tiers. An explicit, valid
+  // nature wins; otherwise classify the task text. An unknown nature falls back to
+  // classification rather than guessing, and classification's own default is
+  // IMPLEMENTATION (deep), so the conservative path is the worst case — protected
+  // work is never downgraded on a miss.
+  const leafType = VALID_NATURES.has(nature) ? nature : classifyLeaf({ label: task || '' });
+  const tier = tierFor(leafType);
+  const model = TIER_MODEL[tier]; // 'haiku' (exploration) or null (every other nature -> inherit session model). tierFor never auto-picks balanced/'sonnet'.
+
+  const tierReason =
+    model === null
+      ? `nature=${leafType} -> ${tier}: inherit the session model (protected, not downgraded)`
+      : `nature=${leafType} -> ${tier}: ${model}`;
+
+  // model applies to a DELEGATED strategy (subagent / mcp-worker leaf); for a
+  // main-thread strategy the work runs on the session model and model is advisory.
+  return {
+    score,
+    strategy,
+    nature: leafType,
+    tier,
+    model,
+    parallelizable: isPar,
+    reasoning: `${strategyReason}. ${tierReason}.`,
+  };
 }

package/install/templates/_byan/mcp/byan-mcp-server/server.js

@@ -292,7 +292,7 @@ const tools = [
   {
     name: 'byan_dispatch',
     description:
-      'BYAN Dispatcher: given a task description and complexity score (0-100), route it to the optimal execution target. Rule-based, no API call. Returns route and reasoning.',
+      'BYAN Dispatcher: routes a unit of work along two independent axes. STRATEGY (where it runs: main-thread / agent-subagent-worktree / mcp-worker) from the scalar score + parallelizable. TIER (which model) from the task NATURE via native-tiers (the single source of truth): only exploration downgrades to haiku; implementation/verification/analysis stay deep (inherit the session model); never pins up to opus. Rule-based, no API call. Returns { score, strategy, nature, tier, model, reasoning }.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -305,6 +305,11 @@ const tools = [
           type: 'boolean',
           description: 'Is the task parallelizable with other tasks?',
         },
+        nature: {
+          type: 'string',
+          enum: ['exploration', 'implementation', 'verification', 'analysis'],
+          description: 'Optional task nature. A valid value sets the model tier directly; otherwise the nature is classified from the task text. Only exploration is downgrade-safe.',
+        },
       },
       required: ['task'],
       additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Copilot CLI, Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {