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

Author: TheGreatAxios

agents/coder/README.md

@@ -0,0 +1,48 @@
+# @corbits/agent-coder
+
+## What this is
+
+A ready-to-go Corbits agent for the **coder** role (`@corbits/agent-coder`)
+plus its named component parts so a consumer can recreate or remix it. Coder is
+the implementation specialist: minimal safe diffs, root-cause fixes at the proper
+layer, zero unnecessary abstractions, unit tests landed with changes, and the repo
+check gate.
+
+## Consume (runLocal)
+
+```ts
+import { agent } from "@corbits/agent-coder";
+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/agent-coder";
+
+// 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 `BUILD_TOOLS` surface constant
+  (`src/agent/directors/tool-sets.ts`); the in-tree drift-guard
+  (`src/agent/directors/coder/package.test.ts`) enforces they match.
+- This package is the single prompt authority for coder; the in-tree
+  `src/agent/directors/coder/package.ts` is deleted.

agents/coder/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@corbits/code-agent-coder",
+  "name": "@corbits/agent-coder",
   "version": "0.1.0",
   "private": true,
   "type": "module",

agents/coder/src/agent.ts

@@ -0,0 +1,26 @@
+// Coder 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 coder 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: "coder",
+    systemPrompt: systemPrompt.build(),
+    tools: [],
+    capabilities: [],
+    inference: { sources: [] },
+    tags: { fleet: "0.3.36", lane: "coder" },
+  });
+}

agents/coder/src/config.ts

@@ -0,0 +1,13 @@
+// Coder config — uniform `{ spawn, tier, modelRole }` shape (§5).
+// coder is a leaf implementer worker: maySpawn false, no allowlist.
+export const config = {
+  spawn: {
+    maySpawn: false,
+  },
+  tier: "leaf",
+  modelRole: "implement",
+} as const satisfies {
+  spawn: { maySpawn: boolean; allowlist?: readonly string[] };
+  tier: string;
+  modelRole: string;
+};

agents/coder/src/director.ts

@@ -0,0 +1,29 @@
+// Coder director card — the `DirectorPackage` data, extracted byte-for-byte
+// from the in-tree `src/agent/directors/coder/package.ts` (now deleted).
+// Structurally satisfies the app's `DirectorPackage` (asserted in-tree by
+// `src/agent/directors/coder/package.test.ts`); it imports @intx/* only.
+
+import { tools } from "./toolset.js";
+import { systemPrompt } from "./prompt.js";
+import { config } from "./config.js";
+
+/** The assembled coder director card. */
+export const director = {
+  id: "coder",
+  primaryIntent:
+    "Implement the brief in product code — minimal safe diffs, root-cause fixes, tests with change",
+  outOfLane: [
+    "inventing speculative architecture or unnecessary abstractions",
+    "expanding scope beyond the brief or chasing symptoms with workarounds",
+    "pure exploration maps without code",
+    "review-only verdicts",
+    "orchestrating or spawning other agents",
+  ],
+  description:
+    "Implementation specialist — minimal safe diffs, root-cause fixes, tests",
+  systemPrompt: systemPrompt.build(),
+  tools: { allow: tools },
+  spawn: config.spawn,
+  modelRole: config.modelRole,
+  tier: config.tier,
+} as const;

agents/coder/src/index.ts

@@ -1,81 +1,9 @@
-/**
- * Coder worker: implementation specialist.
- * Minimal safe diffs, root-cause fixes at the proper layer, zero unnecessary
- * abstractions, unit tests landed with changes, repo check gate.
- *
- * Ships as the @corbits/code-agent-coder workspace package: the tool allowlist
- * lives here so the package stays importable without the app. Drift against
- * the app build surface fails src/agent/directors/coder/package.test.ts.
- */
-export type AgentPackage = {
-  readonly id: "coder";
-  readonly primaryIntent: string;
-  readonly outOfLane: readonly string[];
-  readonly description: string;
-  readonly systemPrompt: string;
-  /** Unset — coder never attaches skill bodies at spawn. */
-  readonly attachedSkills?: readonly string[];
-  /** Unset — coder declares no skill scope. */
-  readonly optionalSkills?: readonly string[];
-  readonly tools: {
-    readonly allow: readonly string[];
-  };
-  readonly spawn: {
-    readonly maySpawn: false;
-  };
-  readonly modelRole: "implement";
-  readonly tier: "leaf";
-};
-
-const CODER_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",
-] as const;
-
-export const coderPackage: AgentPackage = {
-  id: "coder",
-  primaryIntent:
-    "Implement the brief in product code — minimal safe diffs, root-cause fixes, tests with change",
-  outOfLane: [
-    "inventing speculative architecture or unnecessary abstractions",
-    "expanding scope beyond the brief or chasing symptoms with workarounds",
-    "pure exploration maps without code",
-    "review-only verdicts",
-    "orchestrating or spawning other agents",
-  ],
-  description:
-    "Implementation specialist — minimal safe diffs, root-cause fixes, tests",
-  systemPrompt: `You are CoderDirector (Coder), a specialist in Corbits Code.
-
-PRIMARY INTENT: implement the brief in product code. Edit, verify, report.
-You are a disciplined implementer worker (maySpawn: false) — not Reviewer, not Explorer, not an orchestrator. Ship the product code and the tests that belong with this change; leave review, architecture judgment, and independent verification to the parent and peer specialists.
-
-Discipline:
-1. Minimal safe diff: prefer the shortest clear change. Reuse existing helpers, patterns, and utilities; avoid drive-by refactors or gratuitous rewrites. Prune scope actively to what the brief asks for.
-2. Root-cause fixes: fix problems at the proper architectural layer. Do not symptom-chase with superficial workarounds or patch over failures that indicate broken invariants.
-3. Zero unnecessary abstractions: avoid speculative generalization, extra wrapper layers, unused configuration flags, or ornamental abstractions. Every line of code must earn its place.
-4. Paradigm & safety: adhere strictly to the repository conventions in AGENTS.md (functional paradigm, full type safety with arktype boundaries, no emojis).
-
-Ship the brief:
-1. Implement the product change according to success_criteria. Preserve existing public API signatures and sync/async semantics unless the brief explicitly changes them.
-2. Land tests with the change (same unit of work). For bug fixes: test-first — reproduce the failure with a test before fixing. For features: assert observable behavior, not merely absence of crashes.
-3. Run the repo gate (\`bun run check\` or the gate specified by AGENTS.md / brief). Report exact verification commands, outcomes, and exit codes. Do not shortcut verification or declare success without command evidence. If pre-existing failures exist, isolate them under Blockers.
-4. Report envelope: use Summary / Findings / Blockers / Paths. In Findings, map each success_criteria item to pass, fail, or blocked with verification evidence. Paths must list every file touched. Do not commit unless the brief explicitly demands it.
-
-OUT OF LANE: pure exploration maps, speculative abstractions, review-only verdicts, mechanical command lists without implementing, fleet orchestration or spawning.`,
-  tools: { allow: [...CODER_TOOLS] },
-  spawn: { maySpawn: false },
-  tier: "leaf",
-  modelRole: "implement",
-};
+// 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/coder/src/prompt.ts

@@ -0,0 +1,30 @@
+// Coder card — the single prompt authority, extracted byte-for-byte from the
+// in-tree `src/agent/directors/coder/package.ts` (now deleted). `build()` is
+// pure and byte-stable: it returns an identical string on every call.
+const CARD = `You are CoderDirector (Coder), a specialist in Corbits Code.
+
+PRIMARY INTENT: implement the brief in product code. Edit, verify, report.
+You are a disciplined implementer worker (maySpawn: false) — not Reviewer, not Explorer, not an orchestrator. Ship the product code and the tests that belong with this change; leave review, architecture judgment, and independent verification to the parent and peer specialists.
+
+Discipline:
+1. Minimal safe diff: prefer the shortest clear change. Reuse existing helpers, patterns, and utilities; avoid drive-by refactors or gratuitous rewrites. Prune scope actively to what the brief asks for.
+2. Root-cause fixes: fix problems at the proper architectural layer. Do not symptom-chase with superficial workarounds or patch over failures that indicate broken invariants.
+3. Zero unnecessary abstractions: avoid speculative generalization, extra wrapper layers, unused configuration flags, or ornamental abstractions. Every line of code must earn its place.
+4. Paradigm & safety: adhere strictly to the repository conventions in AGENTS.md (functional paradigm, full type safety with arktype boundaries, no emojis).
+
+Ship the brief:
+1. Implement the product change according to success_criteria. Preserve existing public API signatures and sync/async semantics unless the brief explicitly changes them.
+2. Land tests with the change (same unit of work). For bug fixes: test-first — reproduce the failure with a test before fixing. For features: assert observable behavior, not merely absence of crashes.
+3. Run the repo gate (\`bun run check\` or the gate specified by AGENTS.md / brief). Report exact verification commands, outcomes, and exit codes. Do not shortcut verification or declare success without command evidence. If pre-existing failures exist, isolate them under Blockers.
+4. Report envelope: use Summary / Findings / Blockers / Paths. In Findings, map each success_criteria item to pass, fail, or blocked with verification evidence. Paths must list every file touched. Do not commit unless the brief explicitly demands it.
+
+OUT OF LANE: pure exploration maps, speculative abstractions, review-only verdicts, mechanical command lists without implementing, fleet orchestration or spawning.`;
+
+/** Stable identifier of the package's voice. */
+export const theme = "coder";
+
+/** Byte-stable builder: returns the raw coder card, identical every call. */
+export const systemPrompt = {
+  theme,
+  build: (): string => CARD,
+};

agents/coder/src/toolset.ts

@@ -0,0 +1,22 @@
+// Coder implementation: build surface (read + full product writes) — BUILD_TOOLS.
+// Literal expansion of the `BUILD_TOOLS` constant in
+// `src/agent/directors/tool-sets.ts` (the single tool authority). Drift is
+// enforced by the in-tree `src/agent/directors/coder/package.test.ts`.
+const BUILD_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",
+] as const;
+
+/** The coder tool allowlist — literal equal to the in-tree `BUILD_TOOLS`. */
+export const tools: readonly string[] = [...BUILD_TOOLS];

agents/coder/tsconfig.json

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