yuzu482/yhwh/adaptive-subagent-router

Adaptive Subagent Router

Use this skill for every non-trivial task.

Decide whether to delegate

Before acting, classify the task:

1. Non-coding reasoning, inspection and deterministic checks may stay with the primary.
2. Any coding, including tightly coupled or small changes: delegate one bounded Pi worker; primary owns scope and acceptance but does not author code.
3. Separable implementation: delegate self-contained tasks with disjoint ownership and acceptance. If workers fail, return focused corrections to workers or report blocked coding, never silently switch to primary implementation.

Delegation is worthwhile only when it provides meaningful parallelism, independent research, specialist review, or a clear verification lane.

Required delegation route

When delegation is useful, dispatch the bounded task through the installed Pi bridge using the role's advertised provider. Native workers and researchers use openai-codex; reviewers use their separately bound provider. The built-in multi-agent runtime is disabled as the default route. Use built-in subagents only when the user explicitly requests that route for the current task.

For native Pi worker or researcher reasoning, request:

• native worker model: gpt-6-luna
• native worker reasoning effort: task-proportional (medium by default; low/high/max when justified and supported)
• role: worker or researcher; use the separate reviewer binding for reviewer
• recursion: disabled

If Pi rejects the required model, effort or role, report the blocker without substituting bindings. If Pi is unavailable, coding stays blocked; the primary may continue reasoning and diagnosis, but cannot silently implement. Built-in subagents require explicit authorization. Do not invent configuration keys or role support.

Prompt template

State:

• Role and one-sentence objective
• In-scope files, sources, or boundaries
• Out-of-scope work
• Required output and acceptance criteria
• Evidence/verification expected
• “Do not delegate further; return findings to the primary agent.”

Validate and integrate

The primary agent must:

1. Inspect the returned result and evidence.
2. Check it against acceptance criteria and current source state.
3. Request a focused revision or perform the correction if it fails.
4. Integrate only validated results.
5. Stop once the task is complete; do not fan out recursively or indefinitely.

Output contract

Each delegated result should include:

• conclusion or change made;
• evidence and verification performed;
• assumptions;
• uncertainties and known limitations;
• edge cases;
• items the primary agent must independently verify.

Current Pi routing policy

Query list_capabilities.governance.roleModels and roleProviders before model dispatch. Model-backed workers/researchers and Yesod/Binah/Malkuth/Hod/Chochmah/Chesed/Netzach use openai-codex / gpt-6-luna with task-proportional thinking (medium by default). worker maps to Chesed; researcher maps to Malkuth.

Geburah/reviewer uses anthropic / claude-sonnet-5 / max, access none, with no file scope, shell or tools. This is the explicit reviewer exception to the default openai-codex route. Supply actual material in task.reviewPacket. Kether/Tifereth remain in the host. Da'at is unavailable until a capable route is explicitly configured. Never change roles or providers to evade bindings. probe_model alone may test another approved tuple. Credentials never belong in portable packages. PI_AUTH_MISSING/INVALID/EXPIRED/INELIGIBLE requires host login repair; do not retry ordinary tasks until a Tifereth-directed recovery probe succeeds.

Independent budgets and mandatory review packet

Use queueTimeoutSeconds (default 120, maximum 900) for queue admission and timeoutSeconds for execution, still bounded by resourceProfile. Prefer submit_subagent and inspect waitReasons, queueWaitMs, executionMs; waiting does not consume execution time. Do not reduce host reserve or change providers to evade admission.

Every Geburah/reviewer task must carry task.reviewPacket with version 1, stage pre-change or post-change, and requirements, changes, context, verification sections. Each section contains status (provided, missing, or not-applicable), content (actual excerpt strings), and optional reason. Only changes/verification may be not-applicable with explicit justification. Supply actual diffs/context/test evidence; inaccessible filenames and test plans are not proof that checks ran. Missing required material blocks before model execution. The reviewer must question incomplete or contradictory evidence. Default output adds reviewDecision and missingMaterials. Only approve with completed status, evidence, and no missing materials is a passing review; request-changes or insufficient-materials blocks dependent execution. Keep Sonnet access none and do not recursively delegate. Material structure is machine checked; semantic completeness and final acceptance remain with reviewer and primary.

Direct deterministic LSP

Call lsp_request directly with cwd, file, method and optional exact-symbol query or 1-based line/character. search requires structural query and language. No provider/model/thinking or model result envelope is needed. Legacy routing fields are ignored. Single-file snapshot scope, read-only sandbox, resource admission, independent queue/execution deadlines, output bounds, audit and cleanup remain mandatory. Check ok, status, requestedTool, toolsUsed, backend and raw result. status is success, no-match, degraded, unavailable or failed. degraded is reduced syntax/structure evidence; unavailable/failed must never pass acceptance. No-match is a successful query with no match, not a tool failure. Diagnostics may report code errors even when the tool succeeded. Do not send deterministic LSP through a subagent. Interpretation and final acceptance remain with the primary.

Host Claude API credentials

The released reviewer uses the native Pi anthropic / claude-sonnet-5 / max route with user-owned API billing. Configure the key through Configure-Claude-API.cmd, or run install/Set-ClaudeApiKey.ps1 -TargetHome <Windows user home>. Only .local/state/pi-kether/anthropic-api-key.json is used. Never read, renew or forward Claude subscription credentials; environment keys, custom endpoints and CLI-token fallbacks are not accepted.

check_claude_auth validates local configuration only and makes no network/model call. It does not establish key validity, quota or model availability and does not clear an open circuit. After the user repairs configuration, Tifereth must explicitly authorize probe_model with recovery:true for the pinned route. Only a successful probe permits resuming ordinary work. Keys enter trusted Pi memory through FD3, never prompts, logs, CLI arguments, environment variables or portable packages. The reviewer retains access:none and no tools.

Async result acceptance and review timing

Use submit_subagent for review and other delegated work. get_subagent_status reports progress, not the full evidence. When terminal, call get_subagent_result with requestId. Require ready=true; then check state, result.ok, formatValidation and structuredResult/reviewValidation. For large responses concatenate resultJsonChunk pages by nextOffset and verify the SHA-256 of the reconstructed UTF-8 JSON before parsing. Offsets are JavaScript UTF-16 units. Redaction precedes pagination. Results are retained only in this gateway instance and may be evicted with old terminal monitor entries; RESULT_NOT_FOUND does not authorize repeating a write task. Reconcile writes through the existing ledger.

For nontrivial reviews, Tifereth should prefer standard resources with up to 300 seconds when admission permits, keep the pinned model/thinking, and submit one independently reviewable change per material packet. Tiny format probes can use small. Never omit required review evidence to fit the budget. Inspect authenticationMs, startupMs, timeToFirstResponseMs, firstResponseSource, generationMs, processTailMs and cleanupMs. Missing measurements are null, not proof of zero work. Timings are host observations of Pi stream events; timeToFirstResponseMs includes startup and may only observe the completed message when streaming is unavailable. Generation is measured until agent_end, not provider-only GPU time.

Claude API keys have no local expiry-renewal guarantee. Local checks do not validate remote account access; failures require user key repair and an authorized recovery probe.

Typed role contracts and stage handoffs (v2)

All model-backed Pi tasks use contractVersion 2 (the gateway default); version 1 and reduced returnFields are rejected. Omit returnFields to use the role schema exposed in list_capabilities.governance.resultContract.schemas. Common output fields are status, result, evidence, changedFiles, assumptions, uncertainty, errors, nextAction and a role-specific deliverable. Arrays remain arrays. Completed requires a nonempty result, evidence and no errors. Failed, blocked and unverified never satisfy dependencies. Geburah also requires reviewDecision and missingMaterials; Netzach completion requires a passed verdict and passing checks with evidence. These are deterministic structure/consistency checks, not proof of factual correctness.

Linked tasks can use the existing handoff {version:1, stage, inputs:[{requestId, role, stage, resultSha256}]} or opt into {version:2, stage, inputs, runGoal, runAcceptance, phaseIndex}. The handoff version is distinct from result contractVersion 2. Version 2 requires one bounded nonblank overall goal, a nonempty bounded array of overall acceptance criteria, and a positive phase index. Keep runGoal and runAcceptance exactly the same across linked stages; each stage may have its own objective and task.acceptance. The gateway computes a SHA-256 anchor from the two run fields and records it with the phase index in each successful v2 contract. It verifies both against every v2 predecessor. A v1 predecessor cannot enter a v2 chain.

Use canonical roles. Each resultSha256 is the predecessor response.contract.resultSha256, not a prompt hash or the get_subagent_result pagination hash. The inputs must exactly match dependsOnRequestIds. Every linked task needs stable requestId and parentRunId. Predecessors must have successful linked result contracts for the same workspace and parentRunId. Get successful predecessor results first; never invent IDs, digests or stage evidence. The anchor fixes the declared goal and acceptance within a chain; it does not fingerprint source files or prove that the declaration matches the user's intent.

Admitted linked roots are compiled (Yesod), classified (Hod), and scouted (Malkuth). In v2, roots are phase 1. clarified requires compiled; planned requires scouted; pre-review requires planned; implementing requires an approved pre-review; verifying requires implementing; post-review requires verifying. In v2, a new scouted phase N>1 requires exactly one approved post-review predecessor from phase N-1; every other predecessor stays in phase N. This does not permit direct implementing→implementing. Same-run branching from an approved post-review checkpoint is allowed; checkpoints are not single-use. V1 transition rules remain unchanged. Optional additional predecessors must match the allowed stage table. Geburah reviewPacket.stage pre-change maps to pre-review, post-change to post-review. Unknown/missing/evicted records cannot establish a handoff. Linked requests use the persistent idempotency ledger; changed payloads may not reuse request IDs.