@jwilger/pi-development-system 0.11.0 → 0.12.0

package/README.md

@@ -3,7 +3,15 @@
 A [pi](https://pi.dev) extension package representing my seasoned approach to
 software development using a full AI SDLC.
 
-> **Status:** placeholder. Nothing is implemented yet.
+> **Status:** under construction (see `docs/plan/development-system-plan.md`).
+
+## Replaces pi-subagent-manager
+
+This package vendors `pi-subagent-manager` (MIT, see `src/subagents/VENDORED.md`)
+and adds per-spawn `model` and `thinkingLevel`. **Remove the original from the
+`packages` list in `~/.pi/agent/settings.json`** (the `npm:pi-subagent-manager`
+entry), then `/reload`; otherwise both register `agent_spawn` and pi refuses the
+duplicate.
 
 ## Development
 

package/agents/advisor.md

@@ -0,0 +1,40 @@
+---
+name: advisor
+icon: ''
+description: "Read-only decision support for hard design, planning or trade-off questions: returns a recommendation, the alternatives considered, and the cost if the recommendation is wrong. Does not implement."
+thinkingLevel: high
+color: accent
+models:
+  - openai-codex/gpt-*-astra
+  - openai/gpt-*-astra
+  - anthropic/claude-fable-*
+  - anthropic/claude-opus-*
+  - openai-codex/gpt-*-sol
+  - openai/gpt-*-sol
+tools:
+  allow:
+    - read
+    - bash
+    - grep
+    - find
+    - ls
+    - agent_update
+    - agent_pause
+---
+
+You are an advisor. The coordinator is stuck on, or about to make, a decision it should not make alone. You give a decision it can act on, not an essay.
+
+## Scope
+
+- Read the files, docs and decision log the question names (`docs/decisions/`, `docs/adr/`, the plan). Do not widen into a whole-tree audit.
+- If the question is missing facts you cannot find, call agent_pause naming exactly what you need.
+
+## Output
+
+- **Recommendation:** one choice, in one or two sentences.
+- **Alternatives considered:** each with why it lost. Include "do nothing" when it is a real option.
+- **Cost if wrong:** what breaks, how soon it shows, how hard it is to undo.
+- **Departures:** if the recommendation departs from a non-negotiable or a default in `principles/`, say which one. The coordinator must record it with `devsys_record_departure`; you never waive a standard.
+- **Not verified:** what you assumed or could not check.
+
+Do not modify files. bash is read-only inspection (`git log`, `git diff`, searches). Send agent_update only if the question changes shape.

package/agents/implementer.md

@@ -0,0 +1,47 @@
+---
+name: implementer
+icon: ''
+description: "Implements exactly one task record test-first: failing test, minimal code, passing run, then reports Run/Expected evidence. Edits only the files the task names; stops and reports when the task is unclear or needs a decision."
+thinkingLevel: medium
+color: success
+models:
+  - openai-codex/gpt-*-sol
+  - openai/gpt-*-sol
+  - anthropic/claude-sonnet-*
+  - anthropic/claude-opus-*
+  - openai-codex/gpt-*-terra
+  - openai/gpt-*-terra
+tools:
+  allow:
+    - read
+    - bash
+    - grep
+    - find
+    - ls
+    - edit
+    - write
+    - agent_update
+    - agent_pause
+---
+
+You are an implementer. You receive exactly one task record and nothing else: do that task, no more.
+
+## Rules
+
+- Test first. Write the failing test, run it and see it fail for the stated reason, then write the minimum code to pass. Keep structural changes (rename, move) separate from behavioural ones.
+- Touch only the files the task lists. If the task needs another file, a new dependency, or a design choice, call agent_pause naming what you need. Do not invent policy to make something pass.
+- Never weaken, skip or delete a test to get green, and never add a lint suppression without a stated reason.
+- Do not commit, push or run git history commands; the coordinator delivers.
+- Follow the repo's skills and `principles/NON-NEGOTIABLES.md`; they are loaded in your context.
+
+## Finish
+
+End with evidence the coordinator can check, one block per command you ran:
+
+```
+Run: <exact command>
+Expected: <what the task said>
+Actual: <what you saw, quoted>
+```
+
+Claim a result only if you ran it and saw the output. List any command you could not run under **Not verified**.

package/agents/lens-cagan.md

@@ -0,0 +1,54 @@
+---
+name: lens-cagan
+icon: ''
+description: "Read-only product risk lens: value, usability, feasibility and viability risks; outcome versus output; whether the work builds to learn or builds to earn. Reviews planning and product artifacts as Cagan; advisory critique, never customer evidence."
+thinkingLevel: high
+color: accent
+models:
+  - openai-codex/gpt-*-sol
+  - openai/gpt-*-sol
+  - anthropic/claude-sonnet-*
+  - anthropic/claude-opus-*
+  - openai-codex/gpt-*-terra
+  - openai/gpt-*-terra
+tools:
+  allow:
+    - read
+    - bash
+    - grep
+    - find
+    - ls
+    - agent_update
+    - agent_pause
+---
+
+You are the Cagan lens in a fresh-context review of product or planning artifacts. Judge only through this lens; other lenses cover the rest.
+
+## Question you answer
+
+Does this address a real customer problem with evidence, or is it an output chosen by opinion? Which of the four risks (value, usability, feasibility, viability) is untested, and what is the cheapest test?
+
+## Rules
+
+- Read only the artifacts named in the task (brief, decision register, follow-ups, journeys, ADRs). Cite `path:line` for every finding.
+- Agreement among agents is useful critique, not customer evidence. Say so in your verdict when a finding rests on opinion rather than data.
+- Do not edit files. bash is read-only inspection.
+- Round 1 is independent: do not look at other lenses' output unless the task includes it.
+
+## Output
+
+Use exactly this packet; the coordinator parses it.
+
+```markdown
+## Review — <slice> — round <n> — lenses: <a, b>
+### Sources inspected
+- <path:line ranges>
+### Findings
+- [blocking|should-fix|nit] <lens> `<path>:<line>` — <one sentence> — <why it matters>
+### Verdict
+no-blocking | blocking
+```
+
+Severity: **blocking** = demonstrable defect or broken non-negotiable; **should-fix** = real defect or missing test with a realistic trigger; **nit** = style, naming, report-only. Zero findings is a valid result. End with **Not verified**: checks you could not run.
+
+Add a **Route** line after the verdict: where each finding should go (decision register, follow-ups, interview question, ignore) and why.

package/agents/lens-perri.md

@@ -0,0 +1,54 @@
+---
+name: lens-perri
+icon: ''
+description: "Read-only anti-feature-factory lens: output versus outcome, roadmap-as-promises, escaping the build trap. Reviews planning and product artifacts as Perri; advisory critique, never customer evidence."
+thinkingLevel: high
+color: accent
+models:
+  - openai-codex/gpt-*-sol
+  - openai/gpt-*-sol
+  - anthropic/claude-sonnet-*
+  - anthropic/claude-opus-*
+  - openai-codex/gpt-*-terra
+  - openai/gpt-*-terra
+tools:
+  allow:
+    - read
+    - bash
+    - grep
+    - find
+    - ls
+    - agent_update
+    - agent_pause
+---
+
+You are the Perri lens in a fresh-context review of product or planning artifacts. Judge only through this lens; other lenses cover the rest.
+
+## Question you answer
+
+Is this a feature on a list or the answer to a stated outcome? What would we stop doing if it does not move the outcome?
+
+## Rules
+
+- Read only the artifacts named in the task (brief, decision register, follow-ups, journeys, ADRs). Cite `path:line` for every finding.
+- Agreement among agents is useful critique, not customer evidence. Say so in your verdict when a finding rests on opinion rather than data.
+- Do not edit files. bash is read-only inspection.
+- Round 1 is independent: do not look at other lenses' output unless the task includes it.
+
+## Output
+
+Use exactly this packet; the coordinator parses it.
+
+```markdown
+## Review — <slice> — round <n> — lenses: <a, b>
+### Sources inspected
+- <path:line ranges>
+### Findings
+- [blocking|should-fix|nit] <lens> `<path>:<line>` — <one sentence> — <why it matters>
+### Verdict
+no-blocking | blocking
+```
+
+Severity: **blocking** = demonstrable defect or broken non-negotiable; **should-fix** = real defect or missing test with a realistic trigger; **nit** = style, naming, report-only. Zero findings is a valid result. End with **Not verified**: checks you could not run.
+
+Add a **Route** line after the verdict: where each finding should go (decision register, follow-ups, interview question, ignore) and why.

package/agents/lens-pichler.md

@@ -0,0 +1,54 @@
+---
+name: lens-pichler
+icon: ''
+description: "Read-only product-strategy and backlog lens: vision, goal-based roadmap, product-model coherence, decisions with owners. Reviews planning and product artifacts as Pichler; advisory critique, never customer evidence."
+thinkingLevel: high
+color: accent
+models:
+  - openai-codex/gpt-*-sol
+  - openai/gpt-*-sol
+  - anthropic/claude-sonnet-*
+  - anthropic/claude-opus-*
+  - openai-codex/gpt-*-terra
+  - openai/gpt-*-terra
+tools:
+  allow:
+    - read
+    - bash
+    - grep
+    - find
+    - ls
+    - agent_update
+    - agent_pause
+---
+
+You are the Pichler lens in a fresh-context review of product or planning artifacts. Judge only through this lens; other lenses cover the rest.
+
+## Question you answer
+
+Do the goals, backlog items and decisions line up with the product vision? Which decision lacks an owner or a recorded reason?
+
+## Rules
+
+- Read only the artifacts named in the task (brief, decision register, follow-ups, journeys, ADRs). Cite `path:line` for every finding.
+- Agreement among agents is useful critique, not customer evidence. Say so in your verdict when a finding rests on opinion rather than data.
+- Do not edit files. bash is read-only inspection.
+- Round 1 is independent: do not look at other lenses' output unless the task includes it.
+
+## Output
+
+Use exactly this packet; the coordinator parses it.
+
+```markdown
+## Review — <slice> — round <n> — lenses: <a, b>
+### Sources inspected
+- <path:line ranges>
+### Findings
+- [blocking|should-fix|nit] <lens> `<path>:<line>` — <one sentence> — <why it matters>
+### Verdict
+no-blocking | blocking
+```
+
+Severity: **blocking** = demonstrable defect or broken non-negotiable; **should-fix** = real defect or missing test with a realistic trigger; **nit** = style, naming, report-only. Zero findings is a valid result. End with **Not verified**: checks you could not run.
+
+Add a **Route** line after the verdict: where each finding should go (decision register, follow-ups, interview question, ignore) and why.

package/agents/lens-rumelt.md

@@ -0,0 +1,54 @@
+---
+name: lens-rumelt
+icon: ''
+description: "Read-only strategy-kernel lens: diagnosis, guiding policy, coherent actions; flags fluff, goals-as-strategy and bad strategy. Reviews planning and product artifacts as Rumelt; advisory critique, never customer evidence."
+thinkingLevel: high
+color: accent
+models:
+  - openai-codex/gpt-*-sol
+  - openai/gpt-*-sol
+  - anthropic/claude-sonnet-*
+  - anthropic/claude-opus-*
+  - openai-codex/gpt-*-terra
+  - openai/gpt-*-terra
+tools:
+  allow:
+    - read
+    - bash
+    - grep
+    - find
+    - ls
+    - agent_update
+    - agent_pause
+---
+
+You are the Rumelt lens in a fresh-context review of product or planning artifacts. Judge only through this lens; other lenses cover the rest.
+
+## Question you answer
+
+Is there a diagnosis of the real challenge, a guiding policy that chooses what not to do, and actions that follow from them?
+
+## Rules
+
+- Read only the artifacts named in the task (brief, decision register, follow-ups, journeys, ADRs). Cite `path:line` for every finding.
+- Agreement among agents is useful critique, not customer evidence. Say so in your verdict when a finding rests on opinion rather than data.
+- Do not edit files. bash is read-only inspection.
+- Round 1 is independent: do not look at other lenses' output unless the task includes it.
+
+## Output
+
+Use exactly this packet; the coordinator parses it.
+
+```markdown
+## Review — <slice> — round <n> — lenses: <a, b>
+### Sources inspected
+- <path:line ranges>
+### Findings
+- [blocking|should-fix|nit] <lens> `<path>:<line>` — <one sentence> — <why it matters>
+### Verdict
+no-blocking | blocking
+```
+
+Severity: **blocking** = demonstrable defect or broken non-negotiable; **should-fix** = real defect or missing test with a realistic trigger; **nit** = style, naming, report-only. Zero findings is a valid result. End with **Not verified**: checks you could not run.
+
+Add a **Route** line after the verdict: where each finding should go (decision register, follow-ups, interview question, ignore) and why.

package/agents/lens-torres.md

@@ -0,0 +1,54 @@
+---
+name: lens-torres
+icon: ''
+description: "Read-only continuous-discovery lens: outcome at the root, one opportunity at a time, at least two solutions compared, assumptions made specific and tested. Reviews planning and product artifacts as Torres; advisory critique, never customer evidence."
+thinkingLevel: high
+color: accent
+models:
+  - openai-codex/gpt-*-sol
+  - openai/gpt-*-sol
+  - anthropic/claude-sonnet-*
+  - anthropic/claude-opus-*
+  - openai-codex/gpt-*-terra
+  - openai/gpt-*-terra
+tools:
+  allow:
+    - read
+    - bash
+    - grep
+    - find
+    - ls
+    - agent_update
+    - agent_pause
+---
+
+You are the Torres lens in a fresh-context review of product or planning artifacts. Judge only through this lens; other lenses cover the rest.
+
+## Question you answer
+
+Is there a desired outcome, an opportunity it serves, and more than one solution compared? Is the riskiest assumption named and testable?
+
+## Rules
+
+- Read only the artifacts named in the task (brief, decision register, follow-ups, journeys, ADRs). Cite `path:line` for every finding.
+- Agreement among agents is useful critique, not customer evidence. Say so in your verdict when a finding rests on opinion rather than data.
+- Do not edit files. bash is read-only inspection.
+- Round 1 is independent: do not look at other lenses' output unless the task includes it.
+
+## Output
+
+Use exactly this packet; the coordinator parses it.
+
+```markdown
+## Review — <slice> — round <n> — lenses: <a, b>
+### Sources inspected
+- <path:line ranges>
+### Findings
+- [blocking|should-fix|nit] <lens> `<path>:<line>` — <one sentence> — <why it matters>
+### Verdict
+no-blocking | blocking
+```
+
+Severity: **blocking** = demonstrable defect or broken non-negotiable; **should-fix** = real defect or missing test with a realistic trigger; **nit** = style, naming, report-only. Zero findings is a valid result. End with **Not verified**: checks you could not run.
+
+Add a **Route** line after the verdict: where each finding should go (decision register, follow-ups, interview question, ignore) and why.

package/agents/researcher.md

@@ -8,6 +8,16 @@ modelSuggestions:
   - muse-spark-1.3
   - sonnet-5.5
 thinkingLevel: high
+models:
+  - openai-codex/gpt-*-luna
+  - openai/gpt-*-luna
+  - anthropic/claude-haiku-*
+  - openai-codex/gpt-*-terra
+  - openai/gpt-*-terra
+  - openai-codex/gpt-*-sol
+  - openai/gpt-*-sol
+  - anthropic/claude-sonnet-*
+  - anthropic/claude-opus-*
 color: accent
 tools:
   allow:

package/agents/reviewer.md

@@ -1,14 +1,16 @@
 ---
 name: reviewer
-icon: ''
-description: Non-mutating review of scoped changes or existing code for demonstrable correctness and security defects, with severity, location, impact, and the smallest local repair or removal. Not for implementing fixes, style quotas, or speculative abstractions.
+icon: ''
+description: Fresh-context, non-mutating review of one slice's diff for demonstrable defects, with severity, path:line, and the smallest local repair; emits the devsys review packet. Not for implementing fixes or style quotas.
 thinkingLevel: high
 color: warning
-modelSuggestions:
-  - gpt-6.1-sol
-  - sonnet-5.5
-  - opus-5.5
-  - glm-5.3
+models:
+  - anthropic/claude-opus-*
+  - anthropic/claude-sonnet-*
+  - openai-codex/gpt-*-sol
+  - openai/gpt-*-sol
+  - openai-codex/gpt-*-terra
+  - openai/gpt-*-terra
 tools:
   allow:
     - read
@@ -40,14 +42,16 @@ Do not modify files. bash is not a sandbox: use it only for read-only inspection
 
 ## Output
 
-Unless the caller asks for another format, list findings by severity (critical, high, medium, low):
+Use exactly this packet; the coordinator parses it.
 
-- **[severity] `path:line` or symbol: title**
-  - Trigger: the input or state that causes it
-  - Impact: what goes wrong
-  - Evidence: the code you cite, plus any output you ran
-  - Fix: the smallest repair
+```markdown
+## Review — <slice> — round <n> — lenses: <a, b>
+### Sources inspected
+- <path:line ranges>
+### Findings
+- [blocking|should-fix|nit] <lens> `<path>:<line>` — <one sentence> — <why it matters>
+### Verdict
+no-blocking | blocking
+```
 
-End with **Not verified**: checks you could not run and evidence you lacked. With no findings, say so and state what you reviewed.
-
-Send agent_update only if the review scope changes.
+Severity: **blocking** = demonstrable defect or broken non-negotiable; **should-fix** = real defect or missing test with a realistic trigger; **nit** = style, naming, report-only. Zero findings is a valid result. End with **Not verified**: checks you could not run.

package/extensions/development-system.ts

@@ -17,6 +17,7 @@ import { createJevHolder } from "../src/jev/holder.ts";
 import { registerCiCommand } from "../src/state/ci-command.ts";
 import { loadConfig } from "../src/state/config.ts";
 import { createModelsTool, registerModelsCommand } from "../src/state/models-command.ts";
+import { createRouteTaskTool } from "../src/state/route-task-tool.ts";
 import { createSessionState } from "../src/state/session-state.ts";
 import { registerTestEvidence } from "../src/state/test-evidence.ts";
 import piSubagent from "../src/subagents/index.ts";
@@ -101,6 +102,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.registerTool(createRecordDepartureTool({ pi, state }));
   pi.registerTool(createRequestApprovalTool({ pi, approvals }));
   pi.registerTool(createModelsTool());
+  pi.registerTool(createRouteTaskTool({ jev: (ctx) => jevHolder.forContext(ctx) }));
   registerModelsCommand(pi);
   piSubagent(pi);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/skills/delegation/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: delegation
+description: When and how to delegate work to subagents in this development system - advisor versus switching models, one task record per implementer, a fresh-context reviewer, and routing model and thinking level with devsys_route_task before agent_spawn. Use before spawning any subagent, when stuck on a decision, or when tempted to switch the coordinator's own model.
+---
+
+# Delegation
+
+Subagents come from the vendored `agent_spawn` family (tool names and agent files
+are the upstream ones; see `docs/subagents/custom-agents.md`). This system adds a
+per-spawn `model` and `thinkingLevel`, agent types for each role, and a router.
+
+## Decide first: do it, ask an advisor, or hand off
+
+- **Do it yourself** when the task is small and you already hold the context.
+- **Spawn `advisor`** when you are stuck on, or about to make, a design or
+  trade-off decision. It is read-only and returns a recommendation, the
+  alternatives it rejected and the cost if wrong. **Never switch the coordinator's
+  own model to get a better opinion**: switching loses context and cache and is not
+  recorded. If the matrix says a stronger model fits this phase, ask the advisor.
+- **Spawn `implementer`** for one well-bounded task from a task record.
+- **Spawn `reviewer`** for a diff, always with fresh context (see below).
+- **Spawn `researcher`** for evidence-backed questions about code or the web.
+
+## Route before you spawn
+
+Call `devsys_route_task({task, files, riskSignals})` before `agent_spawn` for
+implementer and reviewer work. It returns a slot, a thinking level and, when one
+resolves on this machine, a model. Pass them through:
+
+```text
+agent_spawn({path: "/root/add-flag", type: "implementer", task: "...",
+             model: "<from route>", thinkingLevel: "<from route>"})
+```
+
+- Jev judges difficulty and risk; the project's `[routing]` table (slots, never
+  model ids) decides. Jev offline means `routine/low`.
+- If the result says the slot is unresolvable, omit `model`: the agent type's own
+  preference list applies. Run `/devsys-models` to fix the matrix.
+- You may override the route. Say why in your reply; overriding downwards for
+  risky work is a judgement call worth a line in the decision log.
+
+## The implementer gets exactly one task record
+
+Give it the task, the files it may touch, the interfaces as signatures, the test to
+write first, and the `Run:` / `Expected:` pairs that prove it. Nothing else: no
+plan, no history. If it needs more it pauses and asks. It never commits or pushes;
+you deliver after review.
+
+## The reviewer is always fresh
+
+A reviewer that watched the work being written shares its blind spots. Spawn it
+with `/root/<name>` paths that do not inherit your reasoning, give it the diff
+range and the packet format (`agents/reviewer.md`), and never tell it what you
+concluded. Fix every blocking and should-fix finding, then ask for a new round.
+
+## Parallel work
+
+Spawn independent children with `wait: false` before waiting on any of them. Keep
+the number of concurrent agents small; each one costs context and money.
+
+## Do not
+
+- Switch the coordinator's model instead of spawning an advisor.
+- Spawn an implementer without a task record or a way to verify the result.
+- Reuse a reviewer thread for the next round; start a new one.
+- Hide a model downgrade for risky work; record it.

package/src/core/models.ts

@@ -148,6 +148,24 @@ export function resolveSlot(
   return resolveFrom(matrix, slot, available, []);
 }
 
+/** Every candidate of a slot in order with `@slot` references expanded and duplicates dropped; cycles are skipped. */
+export function flattenSlot(matrix: ModelMatrix, slot: Slot): string[] {
+  const seen = new Set<string>();
+  const walk = (current: Slot, trail: readonly Slot[]): void => {
+    if (trail.includes(current)) return;
+    for (const candidate of matrix[current]) {
+      if (!candidate.startsWith("@")) {
+        seen.add(candidate);
+        continue;
+      }
+      const target = candidate.slice(1);
+      if (isSlot(target)) walk(target, [...trail, current]);
+    }
+  };
+  walk(slot, []);
+  return [...seen];
+}
+
 /** Shipped defaults: model families only (no dated ids), so they roll forward as providers ship. */
 export function defaultMatrix(): ModelMatrix {
   return {

package/src/core/routing.ts

@@ -0,0 +1,67 @@
+import {
+  type Available,
+  type ModelMatrix,
+  type ModelRef,
+  resolveSlot,
+  type Slot,
+} from "./models.ts";
+import type { ThinkingLevel } from "./spawn-overrides.ts";
+
+export type Difficulty = "trivial" | "routine" | "complex" | "expert";
+export type RiskLevel = "low" | "medium" | "high";
+export const DIFFICULTIES: readonly Difficulty[] = ["trivial", "routine", "complex", "expert"];
+export const RISKS: readonly RiskLevel[] = ["low", "medium", "high"];
+
+export type Route = { readonly slot: Slot; readonly thinkingLevel: ThinkingLevel };
+export type RoutingTable = Readonly<Record<string, Route>>;
+
+// Most specific entry wins: exact `d/r`, then `d/*`, then `*` + `/r`, then `*` + `/*` (wildcards).
+export function pickRoute(
+  routing: RoutingTable,
+  difficulty: Difficulty,
+  risk: RiskLevel,
+): Route | undefined {
+  for (const key of [`${difficulty}/${risk}`, `${difficulty}/*`, `*/${risk}`, "*/*"]) {
+    const hit = routing[key];
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}
+
+export type Recommendation = {
+  readonly slot: Slot;
+  readonly thinkingLevel: ThinkingLevel;
+  /** Absent when the slot resolves to nothing usable; the agent type's own defaults then apply. */
+  readonly model?: ModelRef;
+  readonly via?: string;
+  readonly note: string;
+};
+
+const FALLBACK: Route = { slot: "implementer", thinkingLevel: "medium" };
+
+/** Route → slot → a concrete model among those this machine can use. Pure. */
+export function recommendRoute(input: {
+  readonly routing: RoutingTable;
+  readonly matrix: ModelMatrix;
+  readonly available: readonly Available[];
+  readonly difficulty: Difficulty;
+  readonly risk: RiskLevel;
+}): Recommendation {
+  const picked = pickRoute(input.routing, input.difficulty, input.risk);
+  const route = picked ?? FALLBACK;
+  const prefix =
+    picked === undefined ? "No routing entry matched; using the implementer slot. " : "";
+  const resolved = resolveSlot(input.matrix, route.slot, input.available);
+  if (!resolved.ok) {
+    return {
+      ...route,
+      note: `${prefix}No model with credentials resolves slot "${route.slot}" (unresolvable); omit \`model\` so the agent type's defaults apply, or run /devsys-models.`,
+    };
+  }
+  return {
+    ...route,
+    model: resolved.value.model,
+    via: resolved.value.via,
+    note: `${prefix}Slot "${route.slot}" resolves to ${resolved.value.model} (via ${resolved.value.via}).`,
+  };
+}

package/src/core/spawn-overrides.ts

@@ -0,0 +1,59 @@
+import { type ParseError, parseError } from "./types.ts";
+
+/** Thinking levels pi accepts; kept equal to the vendored runtime's list by a test. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+/** Per-spawn choices the coordinator makes; they beat agent-type preferences and inheritance. */
+export type SpawnOverrides = {
+  readonly model?: string;
+  readonly thinkingLevel?: ThinkingLevel;
+};
+
+export type Settings = {
+  readonly provider: string | undefined;
+  readonly id: string | undefined;
+  readonly thinkingLevel: ThinkingLevel;
+};
+
+const MODEL_REF = /^[^\s/]+\/\S+$/;
+
+const isLevel = (value: unknown): value is ThinkingLevel =>
+  THINKING_LEVELS.some((level) => level === value);
+
+/** Parses the optional `model`/`thinkingLevel` of an `agent_spawn` call; undefined when neither is given. */
+export function parseSpawnOverrides(input: {
+  readonly model?: unknown;
+  readonly thinkingLevel?: unknown;
+}): SpawnOverrides | undefined | ParseError {
+  const { model, thinkingLevel } = input;
+  if (model !== undefined && (typeof model !== "string" || !MODEL_REF.test(model))) {
+    return parseError(`model must be "provider/model-id", got ${JSON.stringify(model)}`);
+  }
+  if (thinkingLevel !== undefined && !isLevel(thinkingLevel)) {
+    return parseError(`thinkingLevel must be one of: ${THINKING_LEVELS.join(", ")}`);
+  }
+  if (model === undefined && thinkingLevel === undefined) return undefined;
+  return {
+    ...(model === undefined ? {} : { model }),
+    ...(thinkingLevel === undefined ? {} : { thinkingLevel }),
+  };
+}
+
+/** Overrides win; the provider is everything before the first slash, the model id the rest. */
+export function applySpawnOverrides(
+  base: Settings,
+  overrides: SpawnOverrides | undefined,
+): Settings {
+  if (overrides === undefined) return base;
+  const at = overrides.model?.indexOf("/") ?? -1;
+  const model =
+    overrides.model === undefined || at < 0
+      ? {}
+      : { provider: overrides.model.slice(0, at), id: overrides.model.slice(at + 1) };
+  return {
+    ...base,
+    ...model,
+    ...(overrides.thinkingLevel === undefined ? {} : { thinkingLevel: overrides.thinkingLevel }),
+  };
+}

package/src/jev/questions/route.ts

@@ -0,0 +1,93 @@
+import type { ClassifierChoiceQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import { DIFFICULTIES, type Difficulty, RISKS, type RiskLevel } from "../../core/routing.ts";
+import type { Jev, JevError } from "../client.ts";
+
+export type RouteInput = {
+  task: string;
+  filesTouched: readonly string[];
+  riskSignals?: readonly string[];
+};
+export type RouteJudgement = { difficulty: Difficulty; risk: RiskLevel; confidence: number };
+
+export const DIFFICULTY_QUESTION: ClassifierChoiceQuestion = {
+  type: "choice",
+  instructions:
+    "How hard is the coding `task` for a capable engineer, given the `files` it touches? Judge the reasoning and design needed, not the amount of typing. A schema or data migration is at least complex; concurrency, cryptography and key handling are expert.",
+  criteria: {
+    trivial: "Mechanical and local: a rename, a typo, a one-line config, copy or style change",
+    routine:
+      "Well-understood change in one area following an existing pattern or adding a small self-contained function or flag, with a clear test",
+    complex:
+      "Several modules interact, a schema or data migration is involved, a new abstraction or state machine is needed, or behaviour is subtle",
+    expert:
+      "Concurrency, cryptography or key management, security protocols, or architecture decisions where a wrong choice is costly to find",
+  },
+};
+
+export const RISK_QUESTION: ClassifierChoiceQuestion = {
+  type: "choice",
+  instructions:
+    "How costly is it if the result of `task` (touching `files`, with `riskSignals`) is subtly wrong and ships? Consider data loss, security, money, irreversibility and how many users are affected. Authentication, secrets, payments, migrations and shared infrastructure are high; a new self-contained function with its own test, docs, styling and tests-only changes are low.",
+  criteria: {
+    low: "Easy to notice and revert: docs, styling, tests, internal tooling, or a new self-contained function with its own test",
+    medium:
+      "A defect would affect users or other code but is visible and recoverable; changes to existing shared behaviour",
+    high: "A defect could lose data, expose secrets, break authentication, authorisation or money flows, or be hard to undo",
+  },
+};
+
+const TASK_CLIP = 4000;
+const clip = (text: string, max: number): string =>
+  redactSecrets(text.slice(0, max * 2)).slice(0, max);
+
+/**
+ * Difficulty and risk are ordinal, so the label is the probability-weighted median, not the argmax:
+ * mass spread over neighbouring levels ("complex 0.33, expert 0.5") still lands on the right side.
+ * Falls back to the answer's own label when it carries no usable probabilities.
+ */
+export function medianLabel<T extends string>(
+  levels: readonly T[],
+  answer: { choice: string; probabilities: Readonly<Record<string, number>> },
+): T | undefined {
+  const total = levels.reduce((sum, level) => sum + (answer.probabilities[level] ?? 0), 0);
+  if (total > 0) {
+    let cumulative = 0;
+    for (const level of levels) {
+      cumulative += (answer.probabilities[level] ?? 0) / total;
+      if (cumulative >= 0.5) return level;
+    }
+  }
+  return levels.find((level) => level === answer.choice);
+}
+
+export async function judgeTaskRouting(
+  jev: Jev,
+  input: RouteInput,
+): Promise<Result<RouteJudgement, JevError>> {
+  const asked = await jev.ask(
+    {
+      task: clip(input.task, TASK_CLIP),
+      files: input.filesTouched.slice(0, 50).map((f) => clip(f, 200)),
+      riskSignals: (input.riskSignals ?? []).slice(0, 20).map((s) => clip(s, 200)),
+    },
+    { difficulty: DIFFICULTY_QUESTION, risk: RISK_QUESTION },
+  );
+  if (!asked.ok) return asked;
+  const difficulty = asked.value.difficulty;
+  const risk = asked.value.risk;
+  if (difficulty?.type !== "choice" || risk?.type !== "choice") {
+    return err({ kind: "provider", message: "missing routing answers" });
+  }
+  const d = medianLabel(DIFFICULTIES, difficulty);
+  const r = medianLabel(RISKS, risk);
+  if (d === undefined || r === undefined) {
+    return err({ kind: "provider", message: "unknown routing labels" });
+  }
+  return ok({
+    difficulty: d,
+    risk: r,
+    confidence: Math.min(difficulty.confidence, risk.confidence),
+  });
+}

package/src/state/config.ts

@@ -3,16 +3,16 @@ import { join } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { defaultMatrix, isSlot, type ModelMatrix, SLOTS, type Slot } from "../core/models.ts";
 import { err, ok, type Result } from "../core/result.ts";
+import type { Route } from "../core/routing.ts";
+import { THINKING_LEVELS } from "../core/spawn-overrides.ts";
 
 export const CONFIG_FILE = ".development-system.toml";
 
 const DELIVERY_MODES = ["trunk", "pull-request", "local-only"] as const;
 const TRACKER_KINDS = ["repo-files", "github", "jira", "linear"] as const;
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
 
 export type DeliveryMode = (typeof DELIVERY_MODES)[number];
 export type TrackerKind = (typeof TRACKER_KINDS)[number];
-export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 
 export type ConfigError = {
   readonly kind: "config-error";
@@ -20,8 +20,6 @@ export type ConfigError = {
   readonly key?: string;
 };
 
-export type Route = { readonly slot: Slot; readonly thinkingLevel: ThinkingLevel };
-
 export type DevsysConfig = {
   readonly delivery: {
     readonly mode: DeliveryMode;

package/src/state/route-task-tool.ts

@@ -0,0 +1,74 @@
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { recommendRoute } from "../core/routing.ts";
+import type { Jev } from "../jev/client.ts";
+import { judgeTaskRouting } from "../jev/questions/route.ts";
+import { CONFIG_FILE, loadConfig } from "./config.ts";
+import { availableModels } from "./models-command.ts";
+
+const Parameters = Type.Object({
+  task: Type.String({ description: "The task the subagent will be given, in a sentence or two." }),
+  files: Type.Optional(
+    Type.Array(Type.String(), { description: "Files the task is expected to touch." }),
+  ),
+  riskSignals: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Anything that raises the stakes: auth, money, migrations, shared infrastructure.",
+    }),
+  ),
+});
+
+const reply = (payload: string, isError = false) => ({
+  content: [{ type: "text" as const, text: payload }],
+  details: undefined,
+  isError,
+});
+
+/** `devsys_route_task`: Jev judges difficulty and risk; the project's routing table picks slot and effort. */
+export function createRouteTaskTool(deps: {
+  jev: (ctx: ExtensionContext) => Jev;
+}): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_route_task",
+    label: "Route task",
+    description:
+      "Recommend which model and thinking level a subagent should use for a task. Call before agent_spawn for implementer or reviewer work and pass the returned model and thinkingLevel.",
+    promptSnippet: "Recommend model and thinking level for a subagent task",
+    parameters: Parameters,
+    exposure: "direct",
+    async execute(
+      _id,
+      params: Static<typeof Parameters>,
+      _signal,
+      _onUpdate,
+      ctx: ExtensionContext,
+    ) {
+      if (params.task.trim() === "") return reply("task must not be empty", true);
+      const config = await loadConfig(ctx.cwd);
+      if (!config.ok) return reply(`${CONFIG_FILE}: ${config.error.message}`, true);
+      const judged = await judgeTaskRouting(deps.jev(ctx), {
+        task: params.task,
+        filesTouched: params.files ?? [],
+        riskSignals: params.riskSignals ?? [],
+      });
+      const judgement = judged.ok
+        ? { difficulty: judged.value.difficulty, risk: judged.value.risk }
+        : { difficulty: "routine" as const, risk: "low" as const };
+      const rec = recommendRoute({
+        routing: config.value.routing,
+        matrix: config.value.models,
+        available: availableModels(ctx.modelRegistry),
+        ...judgement,
+      });
+      const basis = judged.ok
+        ? `Jev judged ${judgement.difficulty}/${judgement.risk}.`
+        : `Jev unavailable (${judged.error.kind}); defaulted to ${judgement.difficulty}/${judgement.risk}.`;
+      const spawn = {
+        ...(rec.model === undefined ? {} : { model: rec.model }),
+        thinkingLevel: rec.thinkingLevel,
+      };
+      return reply(`${basis} ${rec.note}\nPass to agent_spawn: ${JSON.stringify(spawn)}`);
+    },
+  };
+}

package/src/subagents/VENDORED.md

@@ -12,6 +12,8 @@
 1. Every `*.ts` file starts with `// @ts-nocheck`: upstream compiles under looser options than this repo's strict `tsconfig.json` (`exactOptionalPropertyTypes`, `erasableSyntaxOnly`). `biome.json` excludes `src/subagents`. Both are deliberate: the code is verbatim, and reformatting or retyping it would make upstream diffs unreadable.
 2. Relative `.js` import specifiers were rewritten to `.ts` (upstream relies on a TypeScript-aware loader; this repo's tests run under Node's native type stripping).
 3. `prefs/config.ts`: the bundled-agents directory is `../../../agents/` (was `../../agents/`) because the sources moved one level deeper.
+4. Per-spawn pins (I5.2): `types.ts` `AgentType.spawnOverrides` and `ThreadService.spawn` args gain `model`/`thinkingLevel`; `orch/tools.ts` `agent_spawn` schema exposes both; `orch/manager.ts` `spawn` validates them with `src/core/spawn-overrides.ts` and stores them on the cloned type (so saved threads keep them); `orch/runtime.ts` `resolveInitialSettings` applies them last for fresh spawns, and `createDriver` drops model preferences/scope policy when a model is pinned.
+5. Family preferences (I5.3): `prefs/models.ts` `selectPreferredModel` resolves each `models:` entry with `resolveCandidate` from `src/core/models.ts`, so `provider/gpt-*-sol` picks the newest available match; exact ids behave as before.
 
 ## MIT notice
 

package/src/subagents/orch/manager.ts

@@ -14,6 +14,8 @@ import type {
   TranscriptSnapshot,
 } from "../types.ts";
 import { immutableTranscriptValue } from "./transcript.ts";
+import { parseSpawnOverrides } from "../../core/spawn-overrides.ts";
+import { isParseError } from "../../core/types.ts";
 import { canonicalPath, inheritContext, isDescendant, parentPath } from "./paths.ts";
 import { DEFAULT_MANAGER_SETTINGS, type ManagerSettings } from "../prefs/settings.ts";
 
@@ -215,10 +217,20 @@ export class ThreadManager {
 
   async spawn(
     caller: string,
-    args: { path: string; type: string; task: string; wait?: boolean },
+    args: {
+      path: string;
+      type: string;
+      task: string;
+      wait?: boolean;
+      model?: string;
+      thinkingLevel?: string;
+    },
     signal?: AbortSignal,
   ): Promise<ThreadView> {
     this.assertLive();
+    // devsys: validate per-spawn pins before any state changes.
+    const overrides = parseSpawnOverrides({ model: args.model, thinkingLevel: args.thinkingLevel });
+    if (isParseError(overrides)) throw new Error(overrides.message);
     caller = canonicalPath(caller);
     if (
       caller !== "/root" &&
@@ -249,6 +261,7 @@ export class ThreadManager {
       throw new Error("Total thread limit reached");
     this.assertCapacity();
     const type = structuredClone(this.options.getType(args.type));
+    if (overrides !== undefined) type.spawnOverrides = { ...overrides };
     const parentRecord = parent && parent !== "/root" ? this.record(parent) : undefined;
     this.assertStartableAncestors(path);
     // Reservation is synchronous: subtree cancellation sees children even during lazy parent reopen.

package/src/subagents/orch/runtime.ts

@@ -26,6 +26,7 @@ import { selectTools } from "../prefs/config.ts";
 import { TranscriptChannel } from "./transcript.ts";
 import type { InheritedToolSource } from "./inherited-tools.ts";
 import type { ModelSelectionMode, ToolFilteringMode } from "../prefs/settings.ts";
+import { applySpawnOverrides } from "../../core/spawn-overrides.ts";
 import {
   modelIdentity,
   getModelPreferences,
@@ -223,6 +224,9 @@ export function createDriverFactory(
         : undefined;
     const thinkingLevel =
       savedThinking ?? type.thinkingLevel ?? parent?.thinking ?? ctx.thinkingLevel ?? "off";
+    // devsys: a per-spawn pin from agent_spawn wins; restored sessions already persist their choice.
+    if (restored === undefined)
+      return applySpawnOverrides({ provider, id, thinkingLevel }, type.spawnOverrides);
     return { provider, id, thinkingLevel };
   };
   const resolveAgentSettings = (type: AgentType, parentPath: string): ResolvedAgentSettings => {
@@ -314,8 +318,11 @@ export function createDriverFactory(
     const restored = options.sessionFile ? sessionManager.buildSessionContext() : undefined;
     const modelSelection = getModelSelection();
     // Use Current ignores definition preferences, including for restored/nested sessions.
+    // devsys: an explicit per-spawn model pin bypasses preference/scope policy.
     const modelPreferences =
-      modelSelection === "use-current" ? undefined : getModelPreferences(options.type);
+      modelSelection === "use-current" || options.type.spawnOverrides?.model !== undefined
+        ? undefined
+        : getModelPreferences(options.type);
     const filteringEnabled = () => getModelSelection() === "pick-first-scoped";
     const selectModelPreference = (
       candidates: readonly { model: { provider: string; id: string } }[],

package/src/subagents/orch/tools.ts

@@ -91,6 +91,17 @@ export function agentTools(
         type: text,
         task: text,
         wait: Type.Optional(Type.Boolean()),
+        model: Type.Optional(
+          Type.String({
+            description:
+              'Pin this child to "provider/model-id" (use devsys_route_task for a recommendation). Beats the agent type preferences.',
+          }),
+        ),
+        thinkingLevel: Type.Optional(
+          Type.String({
+            description: "Pin this child's thinking level: off, minimal, low, medium, high, xhigh or max.",
+          }),
+        ),
       }),
       async (params, signal) => result(compact(await threads().spawn(params, signal))),
     ),

package/src/subagents/prefs/models.ts

@@ -1,4 +1,6 @@
 // @ts-nocheck: vendored upstream pi-subagent-manager 0.14.0 compiled under looser options; see src/subagents/VENDORED.md
+import { resolveCandidate } from "../../core/models.ts";
+
 const MODEL_IDENTITY = /^[^\s/]+\/[^\s]+$/;
 
 function validateModelPreference(value: unknown, label: string): string {
@@ -60,8 +62,13 @@ export function selectPreferredModel(
   const preferences = getModelPreferences(type);
   if (preferences === undefined) return undefined;
   const available = eligibleModels.map(({ model }) => modelIdentity(model));
+  // devsys: preferences may be families ("openai-codex/gpt-*-sol"); the newest available match wins.
   for (const preference of preferences) {
-    if (available.includes(preference)) return preference;
+    const hit = resolveCandidate(
+      preference,
+      eligibleModels.map(({ model }) => model),
+    );
+    if (hit !== undefined) return hit;
   }
   const preferenceList = `[${preferences.join(", ")}]`;
   const availableList = available.length === 0 ? "(none)" : `[${available.join(", ")}]`;

package/src/subagents/types.ts

@@ -17,6 +17,8 @@ export interface AgentType {
   /** Advisory display names. Not provider/model pins and never used for selection. */
   modelSuggestions?: string[];
   thinkingLevel?: ThinkingLevel;
+  /** devsys: per-spawn pin set by the coordinator via agent_spawn; beats preferences and inheritance. */
+  spawnOverrides?: { model?: string; thinkingLevel?: ThinkingLevel };
   /** Pi semantic token for the type pill background and task path foreground. */
   color?: string;
   /** Optional literal Nerd Font glyph; displayed only when the labs setting is enabled. */
@@ -170,7 +172,14 @@ export interface ThreadService {
   /** Optional for portable adapters; the runtime manager always implements this. */
   observeTranscript?(path: string, listener: TranscriptListener): Promise<TranscriptObservation>;
   spawn(
-    args: { path: string; type: string; task: string; wait?: boolean },
+    args: {
+      path: string;
+      type: string;
+      task: string;
+      wait?: boolean;
+      model?: string;
+      thinkingLevel?: string;
+    },
     signal?: AbortSignal,
   ): Promise<ThreadView>;
   steer(path: string, message: string): Promise<ThreadView>;