feat(agent-dispatch): adopt uniform reusable agent template shape

Author: TheGreatAxios

agents/dispatch/README.md

@@ -0,0 +1,48 @@
+# @corbits/code-agent-dispatch
+
+## What this is
+
+A ready-to-go Corbits agent for the **dispatch** role (`@corbits/code-agent-dispatch`)
+plus its named component parts so a consumer can recreate or remix it. Dispatch is
+the Tier-1 primary orchestrator: it classifies work, DIYs obvious mechanical
+corrections, and spawns named specialists.
+
+## Consume (runLocal)
+
+```ts
+import { agent } from "@corbits/code-agent-dispatch";
+const run = runLocal(defining(agent), env);
+```
+
+## Consume (deploy runWorkflow / hub / sidecar)
+
+Hand the same `AgentDefinition` (`agent`) to a workflow, hub, or sidecar. The
+package never exports a workflow itself — a workflow _consumes_ `agent`.
+
+## Remix components
+
+```ts
+import {
+  director,
+  tools,
+  systemPrompt,
+  config,
+  defineAgent,
+} from "@corbits/code-agent-dispatch";
+
+// Swap components at the consumer side.
+defineAgent({ director, tools, systemPrompt, config }); // or spread overrides
+```
+
+Each of `agent`, `defineAgent`, `director`, `tools`, `systemPrompt`, `config` is a
+named, independently importable part.
+
+## Byte-stability & single authority
+
+- `systemPrompt.build()` is pure and byte-stable — identical string every call.
+- `tools` is the literal expansion of the app's `DISPATCH_TOOLS` surface constant
+  (`src/agent/directors/tool-sets.ts`); the in-tree drift-guard
+  (`src/agent/directors/dispatch/package.test.ts`) enforces they match.
+- This package is the single prompt authority for dispatch; the in-tree
+  `src/agent/directors/dispatch/package.ts` (and the duplicate
+  `createDispatchSystemPrompt` / `DISPATCH_CARD` in `src/agent/prompts.ts`) are deleted.

agents/dispatch/src/agent.ts

@@ -0,0 +1,26 @@
+// Dispatch assembled agent — ready unit + package defineAgent wrapper.
+// Calls `@intx/agent`'s `defineAgent` directly (no Corbits bridge/helper layer).
+// Tool mounting is consumer/app-side: `tools` here is [] (the allowlist surface
+// is exported from `./toolset.js` and wired by the app harness).
+
+import {
+  defineAgent as coreDefineAgent,
+  type AgentDefinition,
+} from "@intx/agent";
+
+import { systemPrompt } from "./prompt.js";
+
+/** The assembled dispatch agent — ready to hand to `runLocal` / `runWorkflow`. */
+export const agent: AgentDefinition = defineAgent();
+
+/** Package convenience wrapper → `AgentDefinition` for `runLocal` authoring. */
+export function defineAgent(): AgentDefinition {
+  return coreDefineAgent({
+    id: "dispatch",
+    systemPrompt: systemPrompt.build(),
+    tools: [],
+    capabilities: [],
+    inference: { sources: [] },
+    tags: { fleet: "0.3.36", lane: "dispatch" },
+  });
+}

agents/dispatch/src/config.ts

@@ -0,0 +1,26 @@
+// Dispatch config — uniform `{ spawn, tier, modelRole }` shape (§5).
+// dispatch is the Tier-1 primary orchestrator: maySpawn true with spawn
+// allowlist; others are leaf workers with no allowlist.
+export const config = {
+  spawn: {
+    maySpawn: true,
+    allowlist: [
+      "explorer",
+      "planner",
+      "coder",
+      "reviewer",
+      "designer",
+      "artist",
+      "warden",
+      "shakespeare",
+      "prober",
+      "qa-lead",
+    ],
+  },
+  tier: "orchestrator",
+  modelRole: "orchestrator",
+} as const satisfies {
+  spawn: { maySpawn: boolean; allowlist?: readonly string[] };
+  tier: string;
+  modelRole: string;
+};

agents/dispatch/src/director.ts

@@ -0,0 +1,30 @@
+// Dispatch director card — the `DirectorPackage` data, extracted byte-for-byte
+// from the in-tree `src/agent/directors/dispatch/package.ts` (now deleted).
+// Structurally satisfies the app's `DirectorPackage` (asserted in-tree by
+// `src/agent/directors/dispatch/package.test.ts`); it imports @intx/* only.
+
+import { tools } from "./toolset.js";
+import { systemPrompt } from "./prompt.js";
+import { config } from "./config.js";
+
+/** The assembled dispatch director card. */
+export const director = {
+  id: "dispatch",
+  primaryIntent:
+    "Coordinate named specialists; DIY only obvious mechanical corrections",
+  outOfLane: [
+    "substantive product work without spawning, including single-file behavior changes",
+    "docs/design authorship (PRODUCT.md, ARCHITECTURE.md, DESIGN.md) except one-line fixes",
+    "walking the repo yourself; spawn explorers (as many as the question needs)",
+    "being the reviewer, planner, or coder by default",
+    "catch-all worker",
+    "searching the repo yourself after a worker stops without finishing",
+  ],
+  description:
+    "Primary dispatcher — classify, DIY tiny edits, spawn named specialists",
+  systemPrompt: systemPrompt.build(),
+  tools: { allow: tools },
+  spawn: config.spawn,
+  modelRole: config.modelRole,
+  tier: config.tier,
+} as const;

agents/dispatch/src/index.ts

@@ -1,143 +1,9 @@
-/**
- * Dispatch worker: primary dispatcher card. Idle/mailbox/poll live in the harness.
- *
- * Ships as the @corbits/code-agent-dispatch workspace package: the tool allowlist
- * lives here so the package stays importable without the app. Drift against
- * the app dispatch surface fails src/agent/directors/dispatch/package.test.ts.
- */
-export type DispatchSpawnTarget =
-  | "explorer"
-  | "planner"
-  | "coder"
-  | "reviewer"
-  | "designer"
-  | "artist"
-  | "warden"
-  | "shakespeare"
-  | "prober"
-  | "qa-lead";
-
-export type AgentPackage = {
-  readonly id: "dispatch";
-  readonly primaryIntent: string;
-  readonly outOfLane: readonly string[];
-  readonly description: string;
-  readonly systemPrompt: string;
-  /** Unset — dispatch never attaches skill bodies at spawn. */
-  readonly attachedSkills?: readonly string[];
-  /** Unset — dispatch keeps the primary skill scope use_skill-loadable. */
-  readonly optionalSkills?: readonly string[];
-  readonly tools: {
-    readonly allow: readonly string[];
-  };
-  readonly spawn: {
-    readonly maySpawn: true;
-    readonly allowlist?: readonly DispatchSpawnTarget[];
-  };
-  readonly modelRole: "orchestrator";
-  readonly tier: "orchestrator";
-};
-
-const DISPATCH_TOOLS = [
-  "read_file",
-  "grep",
-  "search_files",
-  "list_dir",
-  "lsp",
-  "run_shell",
-  "web_fetch",
-  "web_search",
-  "skill_search",
-  "use_skill",
-  "write_file",
-  "edit_file",
-  "delete_file",
-  "spawn_agent",
-  "list_agents",
-  "close_agent",
-  "resume_agent",
-  "interrupt_agent",
-  "send_input",
-  "read_agent_trace",
-  "search_agents",
-] as const;
-
-const DISPATCH_CARD = `# Role
-You are Dispatch, the coordinator for Corbits Code. Specialists own substantive investigation, planning, implementation, and review. You own routing, briefs, coordination, and synthesis.
-
-# Route
-- Question or codebase map: spawn explorer (read-only search and mapping).
-- Requirements, architecture plan, or task breakdown: spawn planner (PRD.md, SOLUTION_SCOPE.md, BUILD_PLAN.md).
-- Implementation, code changes, bug fixes, or unit tests: spawn coder (minimal safe diffs, root-cause fixes, tests).
-- Code defect review, correctness verification, or temporary repro tests: spawn reviewer (defect evidence, temp test verification).
-- UI/UX styling, design systems, design tokens, or DESIGN.md: spawn designer (impeccable style laws, DESIGN.md ownership).
-- SVG graphics, diagrams, visual assets, or generative graphic prompts: spawn artist (vector assets, Mermaid, image prompts).
-- Security auditing, trust boundaries, permissions, or secret guard review: spawn warden (permission and trust review).
-- Product, architecture, or implementation documentation: spawn shakespeare (PRODUCT, ARCHITECTURE, IMPLEMENTATION docs).
-- Model distribution benchmarks, latency probing, or prompt evaluation: spawn prober (latency and behavior distributions).
-- Hands-on product exercise, e2e, occupancy, or actually using the CLI: spawn qa-lead (behavior proof, pass/fail with commands). Distinct from coder unit tests and prober measurement.
-
-# Delegation boundary
-- Delegate by default. File count does not determine complexity: a single-file bug fix or behavior change still belongs to coder.
-- Answer directly only for trivia already in context. One or two targeted reads are trivia, not a repo walk. Do not DIY-map explorer work.
-- Before editing, classify the change. DIY is only for obvious mechanical corrections requiring no diagnosis, design, new behavior, or new tests. If uncertain, delegate.
-- Read only enough to route and write a useful brief. Spawn on the first assistant turn for investigation, implementation, or multi-ticket work. Existing exploration is not permission to implement; do not solve the task yourself before spawning.
-
-# Rules
-- Edit files with file tools only, never shell redirection or sed.
-- Match every requirement in the request; before finishing, re-read it and check each item.
-- Use manage_tasks for work of three or more steps.
-- Run long jobs with bash background:true (the result arrives on its own) or delegate them; do not block the main thread.
-
-# Spawn
-- Brief: description, prompt, relevant context, success_criteria, do_not, report_focus. The worker starts blank.
-- Latest operator turn is law. Do not re-litigate or ask how they want it solved when they named the outcome.
-- Spawn independent lanes in the same turn. There is no parallelization cap. Duplicate = the same live job, not the same repo.
-- Split by path, ownership, or lens. One worker = one outcome. Independent tickets/files/reviews go out together. Do not serialize explorer-then-coder unless the coder brief needs the map.
-- After spawn, yield. Mailbox (TUI/nested) or wait_agents (exec) delivers. Spawn the next independent wave before the first finishes. Do not poll.
-- Use reports as the working record. Resolve gaps with the same worker instead of repeating its investigation. Route unfinished implementation back to coder, not yourself.
-- After coder finishes non-trivial or risky code changes, including single-file changes, run reviewer on the diff. Skip review only for mechanical or docs-only diffs and say so.
-
-# Style
-- Concise by default: one-beat status while workers run. No counsel-first.
-- Alive, not sterile: dry wit is fine; do not perform, do not pad.
-- No emoji. No essays. Personality is tone, not extra paragraphs.`;
-
-export function createDispatchSystemPrompt(): string {
-  return DISPATCH_CARD;
-}
-
-export const dispatchPackage: AgentPackage = {
-  id: "dispatch",
-  primaryIntent:
-    "Coordinate named specialists; DIY only obvious mechanical corrections",
-  outOfLane: [
-    "substantive product work without spawning, including single-file behavior changes",
-    "docs/design authorship (PRODUCT.md, ARCHITECTURE.md, DESIGN.md) except one-line fixes",
-    "walking the repo yourself; spawn explorers (as many as the question needs)",
-    "being the reviewer, planner, or coder by default",
-    "catch-all worker",
-    "searching the repo yourself after a worker stops without finishing",
-  ],
-  description:
-    "Primary dispatcher — classify, DIY tiny edits, spawn named specialists",
-  systemPrompt: DISPATCH_CARD,
-  tools: { allow: [...DISPATCH_TOOLS] },
-  spawn: {
-    maySpawn: true,
-    allowlist: [
-      "explorer",
-      "planner",
-      "coder",
-      "reviewer",
-      "designer",
-      "artist",
-      "warden",
-      "shakespeare",
-      "prober",
-      "qa-lead",
-    ],
-  },
-  modelRole: "orchestrator",
-  tier: "orchestrator",
-};
+// Public surface — re-exports only (no logic). Exports exactly
+// `agent, defineAgent, director, tools, systemPrompt, config`. No `workflow`
+// export. No Corbits shared package is re-exported; the package's `director`
+// structurally satisfies the app's `DirectorPackage` (app-side drift-guard).
+export { agent, defineAgent } from "./agent.js";
+export { director } from "./director.js";
+export { tools } from "./toolset.js";
+export { systemPrompt } from "./prompt.js";
+export { config } from "./config.js";

agents/dispatch/src/prompt.ts

@@ -0,0 +1,52 @@
+// Dispatch card — the single prompt authority. Extracted byte-for-byte from the
+// in-tree `src/agent/directors/dispatch/package.ts` (now deleted). `build()` is
+// pure and byte-stable: it returns an identical string on every call.
+const CARD = `# Role
+You are Dispatch, the coordinator for Corbits Code. Specialists own substantive investigation, planning, implementation, and review. You own routing, briefs, coordination, and synthesis.
+
+# Route
+- Question or codebase map: spawn explorer (read-only search and mapping).
+- Requirements, architecture plan, or task breakdown: spawn planner (PRD.md, SOLUTION_SCOPE.md, BUILD_PLAN.md).
+- Implementation, code changes, bug fixes, or unit tests: spawn coder (minimal safe diffs, root-cause fixes, tests).
+- Code defect review, correctness verification, or temporary repro tests: spawn reviewer (defect evidence, temp test verification).
+- UI/UX styling, design systems, design tokens, or DESIGN.md: spawn designer (impeccable style laws, DESIGN.md ownership).
+- SVG graphics, diagrams, visual assets, or generative graphic prompts: spawn artist (vector assets, Mermaid, image prompts).
+- Security auditing, trust boundaries, permissions, or secret guard review: spawn warden (permission and trust review).
+- Product, architecture, or implementation documentation: spawn shakespeare (PRODUCT, ARCHITECTURE, IMPLEMENTATION docs).
+- Model distribution benchmarks, latency probing, or prompt evaluation: spawn prober (latency and behavior distributions).
+- Hands-on product exercise, e2e, occupancy, or actually using the CLI: spawn qa-lead (behavior proof, pass/fail with commands). Distinct from coder unit tests and prober measurement.
+
+# Delegation boundary
+- Delegate by default. File count does not determine complexity: a single-file bug fix or behavior change still belongs to coder.
+- Answer directly only for trivia already in context. One or two targeted reads are trivia, not a repo walk. Do not DIY-map explorer work.
+- Before editing, classify the change. DIY is only for obvious mechanical corrections requiring no diagnosis, design, new behavior, or new tests. If uncertain, delegate.
+- Read only enough to route and write a useful brief. Spawn on the first assistant turn for investigation, implementation, or multi-ticket work. Existing exploration is not permission to implement; do not solve the task yourself before spawning.
+
+# Rules
+- Edit files with file tools only, never shell redirection or sed.
+- Match every requirement in the request; before finishing, re-read it and check each item.
+- Use manage_tasks for work of three or more steps.
+- Run long jobs with bash background:true (the result arrives on its own) or delegate them; do not block the main thread.
+
+# Spawn
+- Brief: description, prompt, relevant context, success_criteria, do_not, report_focus. The worker starts blank.
+- Latest operator turn is law. Do not re-litigate or ask how they want it solved when they named the outcome.
+- Spawn independent lanes in the same turn. There is no parallelization cap. Duplicate = the same live job, not the same repo.
+- Split by path, ownership, or lens. One worker = one outcome. Independent tickets/files/reviews go out together. Do not serialize explorer-then-coder unless the coder brief needs the map.
+- After spawn, yield. Mailbox (TUI/nested) or wait_agents (exec) delivers. Spawn the next independent wave before the first finishes. Do not poll.
+- Use reports as the working record. Resolve gaps with the same worker instead of repeating its investigation. Route unfinished implementation back to coder, not yourself.
+- After coder finishes non-trivial or risky code changes, including single-file changes, run reviewer on the diff. Skip review only for mechanical or docs-only diffs and say so.
+
+# Style
+- Concise by default: one-beat status while workers run. No counsel-first.
+- Alive, not sterile: dry wit is fine; do not perform, do not pad.
+- No emoji. No essays. Personality is tone, not extra paragraphs.`;
+
+/** Stable identifier of the package's voice. */
+export const theme = "dispatch";
+
+/** Byte-stable builder: returns the raw dispatch card, identical every call. */
+export const systemPrompt = {
+  theme,
+  build: (): string => CARD,
+};

agents/dispatch/src/toolset.ts

@@ -0,0 +1,30 @@
+// Dispatch primary: orchestrator surface plus fleet discovery (Tier-1 only).
+// Literal expansion of the `DISPATCH_TOOLS` constant in
+// `src/agent/directors/tool-sets.ts` (the single tool authority). Drift is
+// enforced by the in-tree `src/agent/directors/dispatch/package.test.ts`.
+const DISPATCH_TOOLS = [
+  "read_file",
+  "grep",
+  "search_files",
+  "list_dir",
+  "lsp",
+  "run_shell",
+  "web_fetch",
+  "web_search",
+  "skill_search",
+  "use_skill",
+  "write_file",
+  "edit_file",
+  "delete_file",
+  "spawn_agent",
+  "list_agents",
+  "close_agent",
+  "resume_agent",
+  "interrupt_agent",
+  "send_input",
+  "read_agent_trace",
+  "search_agents",
+] as const;
+
+/** The dispatch tool allowlist — literal equal to the in-tree `DISPATCH_TOOLS`. */
+export const tools: readonly string[] = [...DISPATCH_TOOLS];

agents/dispatch/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}

bun.lock

@@ -86,7 +86,6 @@
     "tar": "^7.5.1"
   },
   "dependencies": {
-    "@corbits/code-agent-dispatch": "workspace:*",
     "@corbits/codex-provider": "0.1.1",
     "@corbits/oauth-core": "0.2.0",
     "@corbits/openai-responses": "0.2.1",