create-byan-agent 2.41.0 → 2.44.0

package/install/templates/_byan/INDEX.md

@@ -3,7 +3,7 @@
 > Carte du systeme de fichiers BYAN. Genere automatiquement — ne pas editer a la main.
 > Source : `_byan/_config/*-manifest.csv` + scan `_byan/projet/`. Regenerer : `byan-build-index`.
 
-## Agents (26)
+## Agents (28)
 
 ### bmb
 - `agent-builder` — Agent Building Expert — `_byan/agent/agent-builder/agent-builder.md`
@@ -18,6 +18,8 @@
 - `architect` — Architect — `_byan/agent/architect/architect.md`
 - `dev` — Developer Agent — `_byan/agent/dev/dev.md`
 - `expert-merise-agile` — Expert Merise Agile - Assistant de Conception & Rédaction — `_byan/agent/expert-merise-agile/expert-merise-agile.md`
+- `jimmy` — Spécialiste Documentation Technique & Processus Internes — `_byan/agent/jimmy/jimmy.md`
+- `mike` — Gestionnaire de Projet — Spécialiste Leantime — `_byan/agent/mike/mike.md`
 - `pm` — Product Manager — `_byan/agent/pm/pm.md`
 - `quick-flow-solo-dev` — Quick Flow Solo Dev — `_byan/agent/quick-flow-solo-dev/quick-flow-solo-dev.md`
 - `quinn` — QA Engineer — `_byan/agent/quinn/quinn.md`
@@ -41,10 +43,11 @@
 ### tea
 - `tea` — Master Test Architect and Quality Advisor — `_byan/agent/tea/tea.md`
 
-## Workflows (45)
+## Workflows (47)
 
 ### bmb
 - `agent` — Tri-modal workflow for creating, editing, and validating BMAD Core compliant agents — `_byan/workflow/simple/agent/workflow.md`
+- `byan-benchmark` — DATA-only benchmark engine for any decision fork: options x weighted-criteria matrix + best-first reco + dissent — `_byan/workflow/simple/bmb/byan-benchmark/workflow.md`
 - `module` — Quad-modal workflow for creating BMAD modules (Brief + Create + Edit + Validate) — `_byan/workflow/simple/module/workflow.md`
 - `turbo-whisper-configure` — Configure Turbo Whisper API, hotkeys, and preferences — `_byan/workflow/simple/turbo-whisper/configure-workflow.md`
 - `turbo-whisper-docker-setup` — Setup self-hosted faster-whisper-server with Docker for privacy and cost-free transcription — `_byan/workflow/simple/turbo-whisper/docker-setup-workflow.md`
@@ -86,6 +89,7 @@
 ### core
 - `brainstorming` — Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods — `_byan/workflow/simple/brainstorming/workflow.md`
 - `party-mode` — Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations — `_byan/workflow/simple/party-mode/workflow.md`
+- `project-handoff` — Export/import portable Markdown project state between Claude Code and Codex — `_byan/workflow/simple/byan/project-handoff-workflow.md`
 
 ### tea
 - `teach-me-testing` — Multi-session learning companion that teaches testing progressively through 7 structured sessions with state persistence — `_byan/workflow/simple/testarch/teach-me-testing/workflow.md`

package/install/templates/_byan/_config/workflow-manifest.csv

@@ -45,4 +45,4 @@ name,description,module,path
 "turbo-whisper-docker-setup","Setup self-hosted faster-whisper-server with Docker for privacy and cost-free transcription","bmb","_byan/workflow/simple/turbo-whisper/docker-setup-workflow.md"
 "turbo-whisper-integrate","Integrate Turbo Whisper with GitHub Copilot CLI, Claude Code, and Codex platforms","bmb","_byan/workflow/simple/turbo-whisper/integrate-workflow.md"
 "byan-benchmark","DATA-only benchmark engine for any decision fork: options x weighted-criteria matrix + best-first reco + dissent","bmb","_byan/workflow/simple/bmb/byan-benchmark/workflow.md"
-
+"project-handoff","Export/import portable Markdown project state between Claude Code and Codex","core","_byan/workflow/simple/byan/project-handoff-workflow.md"

package/install/templates/_byan/core/activation/soul-activation.md

@@ -144,14 +144,14 @@ Il n'est PAS un worker isole — il est un orchestrateur dans l'ecosysteme BMAD.
 
 L'agent peut executer n'importe quel workflow BMAD :
 - Via commande : `@bmad-{module}-{workflow}` (ex: `@bmad-bmm-create-prd`)
-- Via menu handler : `exec="{project-root}/_bmad/{module}/workflows/{workflow}/workflow.md"`
-- Manifeste : `{project-root}/_bmad/_config/workflow-manifest.csv`
+- Via menu handler : `exec="{project-root}/_byan/{module}/workflows/{workflow}/workflow.md"`
+- Manifeste : `{project-root}/_byan/_config/workflow-manifest.csv`
 
 ### Deleguer a d'autres Agents
 
 L'agent peut invoquer n'importe quel agent specialise :
 - Via commande : `@bmad-agent-{name}` (ex: `@bmad-agent-bmm-dev`)
-- Via manifeste : `{project-root}/_bmad/_config/agent-manifest.csv`
+- Via manifeste : `{project-root}/_byan/_config/agent-manifest.csv`
 - L'agent delegue reprend le controle — l'agent courant se retire
 
 ### Acceder aux Contextes

package/install/templates/_byan/mcp/byan-mcp-server/bin/byan-lint-workflows.js

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { validateContract, untieredExplorationViolations } from '../lib/workflows-lint.js';
+import { validateContract, untieredExplorationViolations, untieredAnalysisViolations } from '../lib/workflows-lint.js';
 
 // Validate native workflow scripts under .claude/workflows/ against the full
 // contract (state-coupling + clock/RNG + meta-literal) AND node --check syntax.
@@ -57,10 +57,13 @@ for (const file of files) {
     }
   }
 
-  // Non-blocking tiering advisory: exploration leaves that run deep.
+  // Non-blocking tiering advisory: exploration + analysis leaves that run deep.
   for (const a of untieredExplorationViolations(src)) {
     advisories.push({ file, ...a });
   }
+  for (const a of untieredAnalysisViolations(src)) {
+    advisories.push({ file, ...a });
+  }
 }
 
 // Tiering advisory is informational only — it never changes the exit code.
@@ -71,7 +74,7 @@ if (advisories.length) {
     }
   } else {
     process.stdout.write(
-      `[byan-lint-workflows] advisory: ${advisories.length} exploration leaf(s) run deep (rerun with --advise to list; keep deep if they bear a gate/judgment, else add model: 'haiku')\n`
+      `[byan-lint-workflows] advisory: ${advisories.length} downgrade-eligible leaf(s) run deep (rerun with --advise to list; exploration -> model: 'haiku', analysis -> model: 'sonnet', or keep deep if genuinely hard)\n`
     );
   }
 }

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

@@ -26,10 +26,13 @@ export const TIERS = Object.freeze({ CHEAP: 'cheap', BALANCED: 'balanced', DEEP:
 //
 // deep MUST be null. Omitting opts.model lets the leaf inherit whatever model the
 // session runs (Opus by default, but Sonnet if the user chose Sonnet). We never
-// PIN UP — pinning a leaf to a fixed high tier would override the user's session
-// choice and could silently DOWNGRADE a Sonnet/Opus session's heavy leaf. Only
-// cheap/balanced carry a value: exploration leaves get cheap, explicit mech-
-// leaves get balanced, nothing else ever gets one.
+// PIN UP (nothing is ever forced to opus). cheap/balanced carry a value:
+// exploration leaves get cheap (haiku); explicit mech- leaves AND analysis leaves
+// get balanced (sonnet). Analysis routing to balanced is a deliberate downgrade of
+// the session model for judgment-but-not-frontier work (score/rank/assess/nfr/
+// coverage/recommend) — the heaviest workflow prompts, which rarely need the top
+// model; the 'deep-' label prefix opts a hard analysis leaf back to the session
+// model. VERIFICATION and IMPLEMENTATION still inherit (deep).
 //
 // Values are the harness model-selection aliases (same set as the Agent tool:
 // 'haiku' | 'sonnet' | 'opus'). They are version-independent. If a future
@@ -37,11 +40,14 @@ export const TIERS = Object.freeze({ CHEAP: 'cheap', BALANCED: 'balanced', DEEP:
 // flags every script literal that drifts from it, so the fan-out stays bounded.
 export const TIER_MODEL = Object.freeze({ cheap: 'haiku', balanced: 'sonnet', deep: null });
 
-// Leaf task-type taxonomy. EXPLORATION and MECHANICAL are the two
-// downgrade-safe classes; the other three are protected (never downgraded).
-// MECHANICAL is verification whose outcome is binary and judgment-free (JSON
-// parses, schema matches, lint passes, a test suite exits 0) — it earns the
-// balanced tier. Semantic/adversarial verification stays VERIFICATION (deep).
+// Leaf task-type taxonomy. EXPLORATION (cheap) and MECHANICAL + ANALYSIS
+// (balanced) are the downgrade classes; VERIFICATION and IMPLEMENTATION stay
+// protected (deep, inherit the session model). MECHANICAL is verification whose
+// outcome is binary and judgment-free (JSON parses, schema matches, lint passes,
+// a test suite exits 0). ANALYSIS bears judgment (score/rank/assess/design/nfr/
+// coverage) but rarely the frontier reasoning that needs the top model, so it
+// auto-routes to balanced (sonnet) — escapable per-leaf via the 'deep-' prefix.
+// Semantic/adversarial VERIFICATION stays deep (a wrong check corrupts silently).
 export const LEAF_TYPES = Object.freeze({
   EXPLORATION: 'exploration',
   MECHANICAL: 'mechanical',
@@ -57,6 +63,14 @@ export const LEAF_TYPES = Object.freeze({
 // script to it (a mech- leaf must carry model: 'sonnet', nothing else).
 export const MECHANICAL_PREFIX = 'mech-';
 
+// DEEP_PREFIX is the ANALYSIS escape hatch. Analysis auto-routes to balanced
+// (sonnet); a 'deep-' label prefix opts a specific analysis leaf back OUT of that
+// downgrade and onto the protected deep default (inherit the session model), for
+// genuinely frontier reasoning. Parallel to MECHANICAL_PREFIX: an explicit
+// authoring act the linter honours. 'deep-assess-architecture' rides the session
+// model; 'assess-architecture' rides sonnet. The prefix wins over keyword class.
+export const DEEP_PREFIX = 'deep-';
+
 // Label keyword sets, matched as substrings on the leaf LABEL (not the prompt —
 // see classifyLeaf). Protected sets are checked first so any protected signal
 // beats an exploration signal (conservative: when in doubt, do not downgrade).
@@ -66,7 +80,7 @@ export const MECHANICAL_PREFIX = 'mech-';
 // check/review/gate/audit/assert/lint; a leaf that runs tests is labelled
 // 'verify-*' in practice.
 const VERIFICATION_KEYWORDS = ['verify', 'validate', 'check', 'assert', 'gate', 'lint', 'audit', 'review'];
-const ANALYSIS_KEYWORDS = ['analy', 'design', 'architect', 'assess', 'evaluate', 'strategy', 'risk', 'nfr', 'recommend', 'judge', 'score', 'coverage'];
+const ANALYSIS_KEYWORDS = ['analy', 'design', 'architect', 'assess', 'evaluate', 'strategy', 'risk', 'nfr', 'recommend', 'judge', 'score', 'coverage', 'synthes'];
 const IMPLEMENTATION_KEYWORDS = ['implement', 'build', 'write', 'generate', 'create', 'dev', 'rgr', 'refactor', 'fix', 'scaffold', 'save', 'optimize', 'aggregate', 'report', 'present', 'plan', 'map', 'select', 'subprocess', 'sub-'];
 const EXPLORATION_KEYWORDS = ['load', 'read', 'scan', 'list', 'parse', 'detect', 'discover', 'fetch', 'lookup', 'source-tree', 'mode-detection'];
 
@@ -85,9 +99,11 @@ function matchesAny(text, keywords) {
 export function classifyLeaf(leaf) {
   const label = String((leaf && leaf.label) || '').toLowerCase();
   if (!label) return LEAF_TYPES.IMPLEMENTATION;
-  // Explicit opt-in beats every keyword class: 'mech-validate-json' contains a
-  // verification keyword, but the author's declared intent is the signal.
+  // Explicit opt-in prefixes beat every keyword class (the author's declared
+  // intent is the signal): mech- -> balanced; deep- -> the protected deep default
+  // (the analysis escape hatch, classified as the deep IMPLEMENTATION bucket).
   if (label.startsWith(MECHANICAL_PREFIX)) return LEAF_TYPES.MECHANICAL;
+  if (label.startsWith(DEEP_PREFIX)) return LEAF_TYPES.IMPLEMENTATION;
   if (matchesAny(label, VERIFICATION_KEYWORDS)) return LEAF_TYPES.VERIFICATION;
   if (matchesAny(label, ANALYSIS_KEYWORDS)) return LEAF_TYPES.ANALYSIS;
   if (matchesAny(label, IMPLEMENTATION_KEYWORDS)) return LEAF_TYPES.IMPLEMENTATION;
@@ -95,14 +111,16 @@ export function classifyLeaf(leaf) {
   return LEAF_TYPES.IMPLEMENTATION;
 }
 
-// tierFor(taskType) -> a TIERS value. Conservative auto-routing: EXPLORATION
-// downgrades to cheap, MECHANICAL to balanced, every other type stays deep.
-// BALANCED is reachable ONLY through the explicit mech- label opt-in (see
-// MECHANICAL_PREFIX) — never through keyword classification — so automation
-// still cannot land it on judgment-bearing work.
+// tierFor(taskType) -> a TIERS value. Auto-routing: EXPLORATION -> cheap (haiku);
+// MECHANICAL and ANALYSIS -> balanced (sonnet); VERIFICATION and IMPLEMENTATION
+// stay deep (inherit the session model). MECHANICAL reaches balanced only through
+// the explicit mech- opt-in; ANALYSIS reaches it by keyword classification (it is
+// the judgment-but-not-frontier class), with the deep- prefix as the per-leaf
+// escape back to deep. No path ever lands opus (no pin-up).
 export function tierFor(taskType) {
   if (taskType === LEAF_TYPES.EXPLORATION) return TIERS.CHEAP;
   if (taskType === LEAF_TYPES.MECHANICAL) return TIERS.BALANCED;
+  if (taskType === LEAF_TYPES.ANALYSIS) return TIERS.BALANCED;
   return TIERS.DEEP;
 }
 

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

@@ -181,6 +181,18 @@ export function modelRoutingViolations(src) {
       }
       continue;
     }
+    // ANALYSIS floors at balanced (sonnet), like MECHANICAL: sonnet is its tier,
+    // haiku sits below it. Analysis auto-routes to sonnet (tierFor); a 'deep-'
+    // labelled analysis classifies as IMPLEMENTATION and never reaches here.
+    if (cls === LEAF_TYPES.ANALYSIS) {
+      if (model !== TIER_MODEL.balanced) {
+        out.push({
+          id: 'analysis-below-tier',
+          msg: `analysis leaf '${label}' carries '${model}' but the analysis tier is '${TIER_MODEL.balanced}' (sonnet); haiku sits below it — prefix the label 'deep-' to keep a hard analysis on the session model instead`,
+        });
+      }
+      continue;
+    }
     out.push({
       id: 'protected-leaf-downgraded',
       msg: `leaf '${label}' is protected (${cls}) but carries downgrade model '${model}'; only exploration (read/load/parse/detect) and explicit mech- leaves may downgrade (STRICT-2 No Downgrade)`,
@@ -274,6 +286,32 @@ export function untieredExplorationViolations(src) {
   return out;
 }
 
+// The ANALYSIS half of the same non-blocking advisory. An analysis-labelled leaf
+// that pins no downgrade model runs on the session model (Opus, esp. under a
+// high-effort session) for judgment-but-not-frontier work — the single biggest
+// source of the all-Opus workflow pattern. Surfaces 'add model: sonnet' (or the
+// 'deep-' prefix to keep it deep on purpose). Same permissive-classifier caveat
+// as exploration, so it ships as ADVISORY, not a hard contract rule: the human
+// owns whether a given analysis leaf is truly frontier-hard.
+export function untieredAnalysisViolations(src) {
+  const code = stripComments(src);
+  const out = [];
+  let m;
+  LABEL_RE.lastIndex = 0;
+  while ((m = LABEL_RE.exec(code))) {
+    const label = m[2];
+    if (classifyLeaf({ label }) !== LEAF_TYPES.ANALYSIS) continue;
+    const objText = sameOptsObjectText(code, m.index, m.index + m[0].length);
+    if (!objectHasDowngradeModel(objText)) {
+      out.push({
+        id: 'untiered-analysis',
+        msg: `analysis leaf '${label}' pins no downgrade model; add model: 'sonnet' so judgment-but-not-frontier analysis does not run on the session model (token waste), or prefix the label 'deep-' to keep it on the session model deliberately`,
+      });
+    }
+  }
+  return out;
+}
+
 // Shared parsing primitive — every statically-labelled opts object with its
 // order-independent model (or null). This is the ONE place that knows how to
 // read agent() opts out of a script source; tier-script.js (the per-leaf

package/install/templates/_byan/mcp/byan-mcp-server/skill-bundles-manifest.json

@@ -94,7 +94,7 @@
       "name": "byan-byan",
       "module": "core",
       "tier": "connector-bound",
-      "sourceHash": "a0d73cf82fcf228965de722e7d01c785ae79a6382975e3045b4eeb902633062a"
+      "sourceHash": "6798beb68df9831e0b9bf3ca17100174316c51b2671d96b2ef5bff6def4eabc7"
     },
     "byan-byan-v2": {
       "name": "byan-byan-v2",
@@ -154,7 +154,7 @@
       "name": "byan-codex",
       "module": "core",
       "tier": "standalone",
-      "sourceHash": "0f0d7a1108a43a0c0c8093cc5600bc2649d6766c6ae94c2a2a9dafa315180627"
+      "sourceHash": "32f2ae4a9bfe7a0f90f2ca9787e472c57b847bc36ac9bc6fa0050af70c0af27c"
     },
     "byan-drawio": {
       "name": "byan-drawio",

package/install/templates/_byan/worker/workers.md

@@ -496,7 +496,7 @@ src/
 - **Worker Pool Implementation:** `src/core/worker-pool/worker-pool.js`
 - **Dispatcher Logic:** `src/byan-v2/dispatcher/`
 - **Launcher Workers:** `_byan/worker/launchers/README.md`
-- **Architecture:** `_bmad-output/conception/01-vision-et-principes.md`
+- **Architecture:** `_byan-output/conception/01-vision-et-principes.md`
 
 ---
 

package/install/templates/_byan/workflow/simple/byan/project-handoff-workflow.md

@@ -0,0 +1,90 @@
+---
+name: project-handoff
+description: "Export/import portable Markdown project state between Claude Code and Codex"
+version: "1.0.0"
+module: byan
+phases: 4
+---
+
+# BYAN Project Handoff Workflow
+
+## Purpose
+
+Use this workflow when a BYAN session must move between Claude Code and Codex,
+usually because one assistant is close to a usage limit. The handoff artifact is
+a Markdown file under `_byan-output/handoffs/`; it is portable repo state, not
+native assistant memory.
+
+## Contract
+
+- Source of truth: repository files plus `_byan/` and `_byan-output/`.
+- Artifact: `_byan-output/handoffs/<timestamp>-<from>-to-<to>-<task>.md`.
+- Format: human-readable Markdown with a parseable `json byan-handoff` block.
+- Direction: Claude -> Codex and Codex -> Claude use the same format.
+- Native memories (`~/.claude`, `~/.codex`) may help locally but are not needed
+  to resume.
+
+## Commands
+
+Export from the current assistant:
+
+```bash
+byan-handoff export --from claude --to codex \
+  --task "current feature" \
+  --summary "what happened so far" \
+  --next "first action for the next assistant"
+```
+
+Import on the next assistant:
+
+```bash
+byan-handoff latest --from claude --prompt
+```
+
+Or import a specific file:
+
+```bash
+byan-handoff import _byan-output/handoffs/<file>.md --prompt
+```
+
+## Phase 1: Export
+
+1. Re-read the active request and any locked BYAN strict scope.
+2. Run `byan-handoff export` with explicit `--from`, `--to`, `--task`,
+   `--summary`, and at least one `--next`.
+3. Add useful optional details:
+   - `--decision "..."` for architectural or product decisions.
+   - `--command "..."` for tests or checks already run.
+   - `--blocker "..."` for gaps, failures, or risks.
+   - `--note "..."` for context the next assistant should not rediscover.
+4. Report the generated file path to the user.
+
+## Phase 2: Transfer
+
+The user opens the same repository with the other assistant. No hidden copy step
+is required when both assistants share the same working tree. If the handoff is
+moving to another machine, copy the Markdown file with the repo or paste its
+`Resume Prompt` section.
+
+## Phase 3: Import
+
+1. Run `byan-handoff latest --from <source> --prompt` or
+   `byan-handoff import <file> --prompt`.
+2. Treat the printed prompt as the starting context.
+3. Inspect the listed files before editing.
+4. Check `_byan-output/fd-state.json` and strict status if the handoff names an
+   active FD.
+
+## Phase 4: Continue
+
+1. Continue from the `Next Actions` section.
+2. Update the same FD rather than starting a parallel one unless the handoff says
+   the old FD is complete or aborted.
+3. Before switching back, create a new handoff in the opposite direction.
+
+## Validation Checklist
+
+- [ ] Handoff file exists under `_byan-output/handoffs/`.
+- [ ] `byan-handoff latest --from <source> --prompt` prints a usable resume prompt.
+- [ ] The next assistant inspected files listed in `Files Touched`.
+- [ ] Any strict-mode gaps are surfaced, not hidden.

package/install/templates/docs/codex-auto-delegation.md

@@ -0,0 +1,140 @@
+# Codex Auto-Delegation
+
+Hand delegable work to Codex on your **ChatGPT subscription** (no API credit)
+when Claude nears its 5h limit — automatically, from inside Claude Code.
+
+This is the native, opt-in layer on top of the Codex load-balancer pool
+(`docs/loadbalancer-multipool.md`). It does not replace judgment: only delegable
+work crosses the line.
+
+## What it does
+
+Every turn, a `UserPromptSubmit` hook estimates how much of the Claude 5h window
+you have burned and looks at the task you just asked for. If the task is
+delegable (code / mechanical) — or if you are over the pressure threshold — BYAN
+injects a one-line advisory nudge proposing you hand it to Codex via
+`codex:codex-rescue --model gpt-5.4`. You still decide, and you still verify
+Codex's output before commit.
+
+Three triggers, in priority order:
+
+1. **Pressure** — estimated Claude 5h usage `>= threshold` (default **80%**) ->
+   propose offloading **everything** delegable this session.
+2. **Nature** — the request looks like delegable coding work -> propose handing
+   **that** task over. Works with no gauge at all.
+3. **Perf** (opt-in, off by default) — a configurable forces table says Codex is
+   reputed stronger for this kind of task. See "Perf routing" below.
+
+**The red line** (held): only delegable natures are proposed. Judgment,
+analysis, soul and verification stay on Claude.
+
+## Enable it
+
+At install (`npx create-byan-agent`), the Codex step asks:
+
+> Add Codex as a backup pool?
+
+Before that optional backup-pool prompt, the yanstaller performs the native Codex
+setup whenever Codex is selected (Codex-only or Claude+Codex):
+
+1. it writes the BYAN MCP entry into `~/.codex/config.toml`;
+2. it installs BYAN's native Codex skills into `~/.codex/skills`, including the
+   `byan` entrypoint skill used by `$byan`;
+3. it keeps the project-local `.codex/prompts/` stubs for backward
+   compatibility.
+
+If `~/.codex` does not exist yet, the yanstaller creates it because Codex was
+explicitly selected.
+
+Those are separate from auto-delegation. Without the native skills, Codex may
+have the MCP server wired but still fail to expose `$byan` / BYAN skill
+invocations on a fresh machine.
+
+Answer yes to the backup-pool prompt and it links your local Codex (the
+`codex login` session — your ChatGPT subscription, **not** an API key) and writes
+`_byan/_config/autodelegate.json`, which **arms** the hook. Without that file the
+hook is a silent no-op (disarmed by default).
+
+Non-interactive install: set `BYAN_CODEX_AUTODELEGATE=1`.
+
+If Codex is not linked yet, the installer prints the device-flow to run on the
+machine (needed on a headless server, where the default localhost browser
+redirect fails):
+
+```
+codex login --device-auth
+```
+
+then re-run the installer.
+
+### The entitled model (why gpt-5.4)
+
+On a ChatGPT subscription the OpenAI backend rejects every `-codex`-suffixed
+model (`gpt-5-codex`, `gpt-5.x-codex`) — those ids are API-key only. The plain
+`gpt-5.x` family (e.g. `gpt-5.4`) is the entitled one. That is why the invocation
+pins `--model gpt-5.4`. See `src/loadbalancer/providers/codex-provider.js`
+(`resolveCodexModel`).
+
+## Configure it
+
+`_byan/_config/autodelegate.json`:
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `enabled` | `true` (once written) | Master switch. Delete the file or set `false` to disarm. |
+| `threshold` | `80` | Pressure percentage that flips to "offload everything delegable". |
+| `budget` | `null` | Your plan's rough token ceiling for the 5h window. Without it, `pct` is null and only the nature trigger fires (see caveat). |
+| `invocation` | `codex:codex-rescue --model gpt-5.4` | What the nudge tells BYAN to run. |
+| `perfRouting` | `false` | Enable the perf trigger. |
+| `perfForces` | `[]` | The forces table (see below). |
+
+Session escape hatch: `touch .byan-codex-autodelegate/off` silences the nudge
+without editing the config; remove it to re-enable.
+
+## The honest caveats
+
+- **The 5h gauge is an ESTIMATE, not Anthropic's number.** No provider exposes a
+  machine-readable 5h quota; `/usage` fetches the authoritative figure live and
+  does not persist it. The estimator sums the real per-message token counts from
+  your local transcripts (`~/.claude/projects/*/*.jsonl`) over the rolling 5h
+  window, weighting cache reads at 0.1 (they are billed roughly a tenth and
+  repeat every turn). It is proportional, not exact — and `pct` is only computed
+  when you set a `budget`. Without a budget, delegation runs on the nature
+  trigger alone.
+- **`~/.claude` is a native accelerator, not a source of truth** (PORTABLE-3).
+  If it is absent the estimator degrades to `pct: null` and the feature falls
+  back to nature-based delegation. The feature keeps working.
+- **Perf routing is a heuristic below the L2 floor.** "Model X is better at task
+  Y" is a performance claim; BYAN's fact-check floor for performance is L2 (a
+  reproducible benchmark). A community arena such as designarena.ai is weaker
+  than that. So the forces table ships empty — it asserts nothing until you
+  populate it, and every match is tagged `heuristic`, not presented as measured.
+
+## Perf routing (opt-in)
+
+Set `perfRouting: true` and fill `perfForces` with entries:
+
+```json
+{
+  "perfRouting": true,
+  "perfForces": [
+    { "category": "bulk-refactor", "pattern": "rename across|codemod", "favors": "codex" }
+  ]
+}
+```
+
+`pattern` is a case-insensitive regex matched against your request. `favors:
+"codex"` pushes a delegation nudge even below the pressure threshold. Populate it
+from your own benchmarks, or from an arena taken as a weak signal — BYAN tags it
+heuristic either way.
+
+## Files
+
+| Piece | File |
+|-------|------|
+| Usage estimator | `.claude/hooks/lib/usage-estimator.js` |
+| Decision core + nudge | `.claude/hooks/lib/autodelegate-decision.js` |
+| Perf routing | `.claude/hooks/lib/perf-routing.js` |
+| Hook | `.claude/hooks/codex-autodelegate.js` |
+| Installer opt-in | `install/lib/codex-autodelegate-setup.js` |
+| Native Codex MCP + skills setup | `install/lib/codex-native-setup.js` |

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "create-byan-agent",
-  "version": "2.41.0",
+  "version": "2.44.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 (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {
     "create-byan-agent": "./install/bin/create-byan-agent-v2.js",
     "byan-v2": "./install/bin/create-byan-agent-v2.js",
     "byan-cleanup": "./install/bin/byan-cleanup.js",
+    "byan-handoff": "./install/bin/byan-handoff.js",
     "byan-ledger": "./install/bin/byan-ledger.js",
     "byan-kanban": "./install/bin/byan-kanban.js",
     "update-byan-agent": "./update-byan-agent/bin/update-byan-agent.js"

package/src/byan-v2/dispatcher/task-router.js

@@ -1,6 +1,6 @@
 /**
  * TaskRouter - Routes tasks based on complexity
- * Integrates ComplexityScorer + TaskToolInterface
+ * Integrates ComplexityScorer
  * 
  * Thresholds:
  * - < 30: task-tool only

package/src/byan-v2/lib/layout-resolver.js

@@ -10,7 +10,7 @@
 //
 // This module is the single READ-side authority: "where does logical thing X
 // physically live?". It answers Gen3-first, then falls back through the real
-// on-disk Gen2 variants (flat AND per-module) and finally Gen1 (_bmad/). Every
+// on-disk Gen2 variants (flat AND per-module). Every
 // lookup is a pure existence check — no writes, no side effects — so it is
 // idempotent and additive: before migration it finds Gen2, after migration it
 // finds Gen3, during migration either works. That is what lets the FS migrator
@@ -68,8 +68,7 @@ function locate(root, gen3rel, gen2rel) {
 
 // Resolve an agent source file by name. Gen3 _byan/agent/<name>/<name>.md (or
 // agent.md) first, then Gen2 flat _byan/agents/<name>.md, then Gen2 per-module
-// _byan/<module>/agents/<name>.md, then Gen1 _bmad/<module>/agents/<name>.md.
-// Returns {path, rel, layout} or null.
+// _byan/<module>/agents/<name>.md. Returns {path, rel, layout} or null.
 function resolveAgent(name, opts = {}) {
   const root = resolveProjectRoot(opts.projectRoot);
   const candidates = [
@@ -78,7 +77,6 @@ function resolveAgent(name, opts = {}) {
     { rel: `_byan/agents/${name}.md`, layout: 'gen2-flat' },
   ];
   for (const m of MODULES) candidates.push({ rel: `_byan/${m}/agents/${name}.md`, layout: 'gen2-module' });
-  for (const m of MODULES) candidates.push({ rel: `_bmad/${m}/agents/${name}.md`, layout: 'gen1' });
   return firstExisting(root, candidates);
 }
 
@@ -95,7 +93,6 @@ function agentDirs(opts = {}) {
   push('_byan/agent', 'gen3', true);
   push('_byan/agents', 'gen2-flat', false);
   for (const m of MODULES) push(`_byan/${m}/agents`, 'gen2-module', false);
-  for (const m of MODULES) push(`_bmad/${m}/agents`, 'gen1', false);
   return out;
 }
 
@@ -105,7 +102,7 @@ function isSoulSibling(fileName) {
 
 // Discover all agents across layouts. Returns [{name, path, rel, layout}],
 // deduped by name with the highest-priority directory winning (Gen3 > flat >
-// module > gen1). Soul/tao siblings are not agents and are skipped.
+// module). Soul/tao siblings are not agents and are skipped.
 function listAgents(opts = {}) {
   const root = resolveProjectRoot(opts.projectRoot);
   const seen = new Map();