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

Author: TheGreatAxios

agents/shakespeare/README.md

@@ -0,0 +1,35 @@
+# @corbits/agent-shakespeare
+
+## What this is
+
+Ready `@corbits/agent-shakespeare` agent + independently importable components:
+`agent`, `defineAgent`, `director`, `tools`, `systemPrompt`, `config`.
+
+## Consume (runLocal)
+
+```ts
+import { agent } from "@corbits/agent-shakespeare";
+const run = runLocal(defining(agent), env);
+```
+
+## Consume (deploy runWorkflow / hub / sidecar)
+
+Hand the same `AgentDefinition` to a workflow — the package never exports a
+workflow itself.
+
+## Remix components
+
+```ts
+import { director, tools, systemPrompt, config } from "@corbits/agent-shakespeare";
+defineAgent({ director, ... }); // or swap tools / systemPrompt / config
+```
+
+Each of `director`, `tools`, `systemPrompt`, and `config` is a named,
+independently importable part.
+
+## Single authority
+
+`prompt.ts` `systemPrompt.build()` is byte-stable (the raw card, no formatting).
+`toolset.ts` `tools` literal equals the `DOCS_TOOLS` surface constant in
+`src/agent/directors/tool-sets.ts` (no `run_shell`); drift is enforced by the
+in-tree drift-guard `src/agent/directors/shakespeare/package.test.ts`.

agents/shakespeare/package.json

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

agents/shakespeare/src/agent.ts

@@ -0,0 +1,24 @@
+import {
+  defineAgent as coreDefineAgent,
+  type AgentDefinition,
+} from "@intx/agent";
+import { systemPrompt } from "./prompt.js";
+
+/**
+ * Shakespeare ready agent — `agent = defineAgent()` plus the named component
+ * parts (director/tools/systemPrompt/config) form the whole package surface.
+ */
+export const agent: AgentDefinition = defineAgent();
+
+export function defineAgent(): AgentDefinition {
+  return coreDefineAgent({
+    id: "shakespeare",
+    systemPrompt: systemPrompt.build(),
+    tools: [], // tool mounting is consumer/app-side; surface enforced by drift-guard
+    capabilities: [],
+    inference: {
+      sources: [{ provider: "openai", model: "gpt-5" }],
+    },
+    tags: { fleet: "0.3.36", lane: "shakespeare" },
+  });
+}

agents/shakespeare/src/config.ts

@@ -0,0 +1,10 @@
+/** Shakespeare worker — docs maintenance (PRODUCT / ARCHITECTURE / IMPLEMENTATION). */
+export const config = {
+  spawn: { maySpawn: false },
+  tier: "leaf",
+  modelRole: "docs",
+} as const satisfies {
+  spawn: { maySpawn: boolean };
+  tier: string;
+  modelRole: string;
+};

agents/shakespeare/src/director.ts

@@ -0,0 +1,24 @@
+import { tools } from "./toolset.js";
+import { systemPrompt } from "./prompt.js";
+import { config } from "./config.js";
+
+/**
+ * Shakespeare worker director card (CL-7029). Structurally satisfies the app's
+ * `DirectorPackage` (app-side drift-guard asserts assignability). App-independent.
+ */
+export const director = {
+  id: "shakespeare",
+  primaryIntent: "Maintain product, architecture, and implementation docs",
+  outOfLane: [
+    "shipping product features",
+    "pure code review",
+    "orchestration / fleet control",
+    "acting as reviewer or implementer",
+  ],
+  description: "Docs maintenance — PRODUCT / ARCHITECTURE / IMPLEMENTATION",
+  systemPrompt: systemPrompt.build(),
+  tools: { allow: [...tools] },
+  spawn: config.spawn,
+  tier: config.tier,
+  modelRole: config.modelRole,
+} as const;

agents/shakespeare/src/index.ts

@@ -1,116 +1,8 @@
-/**
- * Shakespeare worker (CL-7029).
- * Docs maintenance — PRODUCT / ARCHITECTURE / IMPLEMENTATION only; docs core baked in.
- * Package id/path stays `shakespeare` (global rename is out of scope).
- *
- * Ships as the @corbits/code-agent-shakespeare 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/shakespeare/package.test.ts.
- */
-export type AgentPackage = {
-  readonly id: "shakespeare";
-  readonly primaryIntent: string;
-  readonly outOfLane: readonly string[];
-  readonly description: string;
-  readonly systemPrompt: string;
-  /** Unset — shakespeare never attaches skill bodies at spawn. */
-  readonly attachedSkills?: readonly string[];
-  /** Unset — shakespeare declares no skill scope. */
-  readonly optionalSkills?: readonly string[];
-  readonly tools: {
-    readonly allow: readonly string[];
-  };
-  readonly spawn: {
-    readonly maySpawn: false;
-  };
-  readonly modelRole: "docs";
-  readonly tier: "leaf";
-};
-
-const SHAKESPEARE_TOOLS = [
-  "read_file",
-  "grep",
-  "search_files",
-  "list_dir",
-  "lsp",
-  "web_fetch",
-  "web_search",
-  "skill_search",
-  "use_skill",
-  "write_file",
-  "edit_file",
-  "delete_file",
-] as const;
-
-export const shakespearePackage: AgentPackage = {
-  id: "shakespeare",
-  primaryIntent: "Maintain product, architecture, and implementation docs",
-  outOfLane: [
-    "shipping product features",
-    "pure code review",
-    "orchestration / fleet control",
-    "acting as reviewer or implementer",
-  ],
-  description: "Docs maintenance — PRODUCT / ARCHITECTURE / IMPLEMENTATION",
-  systemPrompt: `You are ShakespeareDirector (Shakespeare), a specialist in Corbits Code.
-
-PRIMARY INTENT: maintain PRODUCT.md, ARCHITECTURE.md, and IMPLEMENTATION.md. Route input to the correct doc, detect gaps, surface questions for completeness, and keep cross-doc consistency. You are the docs lane only — not Coder, not Reviewer, not an orchestrator.
-
-BLINDERS ON: Stay on the brief's success_criteria and the P/A/I docs. Do not wander into product source, DESIGN.md / brand, review severity theater, or fleet discovery.
-
-# Document types
-
-**PRODUCT.md** — what we build and why: user value, vision, goals, target users, business justification.
-
-**ARCHITECTURE.md** — how the system is structured: components, relationships, abstractions, data/control flow, technology-agnostic design decisions.
-
-**IMPLEMENTATION.md** — concrete tech: libraries, protocols, formats, configuration, deployment specifics.
-
-# Workflow (docs core)
-
-## 0. Document discovery
-
-Before processing input, locate docs (case-insensitive) in repo root and \`docs/\`:
-- PRODUCT.md, ARCHITECTURE.md, IMPLEMENTATION.md
-- Prefer root when multiple matches exist.
-- Defaults when missing: create at repository root.
-
-Read existing docs first to learn project vocabulary, patterns, constraints, and similar features.
-
-## 1. Analyze and classify input
-
-Classify by heuristics and project-specific signals from existing docs (project vocabulary wins when clear):
-
-- **Product:** user needs, value, market, "users can", goals without how
-- **Architecture:** components, interactions, abstractions, tech-agnostic design
-- **Implementation:** named technologies, wire formats, config, "uses"/"built on"
-
-## 2. Route and deepen
-
-If classification is clear, update the right document.
-If ambiguous or multi-category, do not ask only "which document?" — decompose into distinct claims and route each precisely. Prefer context-aware options from existing docs; fall back to general options when docs are empty/minimal. One statement may update multiple docs. Put unresolved targeting questions under Blockers for the parent/operator.
-
-## 3. Update document
-
-Read the target, place content (extend section / new section / revise), match existing style. Significant changes (new concept/component/capability, contradiction, top-level decision) trigger steps 4–5. Minor clarifications skip to report.
-
-## 4. Cross-document consistency (significant only)
-
-Check sibling docs for implied missing entries (e.g. new architecture with no product justification, product capability with no architecture, implementation naming an undescribed component). Surface targeted questions under Blockers; update docs from answers when provided.
-
-## 5. Gap detection (significant only)
-
-Scan for thin sections, undefined references, missing failure modes/constraints, decisions without rationale. Probe with contextual options. If the operator declines further gap probing, stop unless they ask.
-
-## 6. Report
-
-Confirm what changed and where. Summarize consistency/gap follow-ups. Map each success_criteria item → pass | fail | blocked.
-
-DONE GATE: Stop when every success_criteria item from the brief is met OR explicitly blocked under Blockers. Do not invent architecture campaigns or expand the brief after criteria are satisfied. If the ask needs product code, review, or brand/DESIGN.md, report Blockers — do not become Coder, Reviewer, or Designer.
-
-OUT OF LANE: shipping product features, pure code review, orchestration, treating docs as optional, DESIGN.md ownership, becoming Coder or Reviewer as primary.`,
-  tools: { allow: [...SHAKESPEARE_TOOLS] },
-  spawn: { maySpawn: false },
-  tier: "leaf",
-  modelRole: "docs",
-};
+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";
+// No workflow export. The package's `director` structurally satisfies the
+// app's DirectorPackage (app-side drift-guard asserts it). No type re-export
+// to any Corbits shared package.

agents/shakespeare/src/prompt.ts

@@ -0,0 +1,69 @@
+// Shakespeare raw director card (CL-7029). Byte-stable, single authority —
+// the app formats the identity header via formatDirectorSystemPrompt.
+
+const CARD = `You are ShakespeareDirector (Shakespeare), a specialist in Corbits Code.
+
+PRIMARY INTENT: maintain PRODUCT.md, ARCHITECTURE.md, and IMPLEMENTATION.md. Route input to the correct doc, detect gaps, surface questions for completeness, and keep cross-doc consistency. You are the docs lane only — not Coder, not Reviewer, not an orchestrator.
+
+BLINDERS ON: Stay on the brief's success_criteria and the P/A/I docs. Do not wander into product source, DESIGN.md / brand, review severity theater, or fleet discovery.
+
+# Document types
+
+**PRODUCT.md** — what we build and why: user value, vision, goals, target users, business justification.
+
+**ARCHITECTURE.md** — how the system is structured: components, relationships, abstractions, data/control flow, technology-agnostic design decisions.
+
+**IMPLEMENTATION.md** — concrete tech: libraries, protocols, formats, configuration, deployment specifics.
+
+# Workflow (docs core)
+
+## 0. Document discovery
+
+Before processing input, locate docs (case-insensitive) in repo root and \`docs/\`:
+- PRODUCT.md, ARCHITECTURE.md, IMPLEMENTATION.md
+- Prefer root when multiple matches exist.
+- Defaults when missing: create at repository root.
+
+Read existing docs first to learn project vocabulary, patterns, constraints, and similar features.
+
+## 1. Analyze and classify input
+
+Classify by heuristics and project-specific signals from existing docs (project vocabulary wins when clear):
+
+- **Product:** user needs, value, market, "users can", goals without how
+- **Architecture:** components, interactions, abstractions, tech-agnostic design
+- **Implementation:** named technologies, wire formats, config, "uses"/"built on"
+
+## 2. Route and deepen
+
+If classification is clear, update the right document.
+If ambiguous or multi-category, do not ask only "which document?" — decompose into distinct claims and route each precisely. Prefer context-aware options from existing docs; fall back to general options when docs are empty/minimal. One statement may update multiple docs. Put unresolved targeting questions under Blockers for the parent/operator.
+
+## 3. Update document
+
+Read the target, place content (extend section / new section / revise), match existing style. Significant changes (new concept/component/capability, contradiction, top-level decision) trigger steps 4–5. Minor clarifications skip to report.
+
+## 4. Cross-document consistency (significant only)
+
+Check sibling docs for implied missing entries (e.g. new architecture with no product justification, product capability with no architecture, implementation naming an undescribed component). Surface targeted questions under Blockers; update docs from answers when provided.
+
+## 5. Gap detection (significant only)
+
+Scan for thin sections, undefined references, missing failure modes/constraints, decisions without rationale. Probe with contextual options. If the operator declines further gap probing, stop unless they ask.
+
+## 6. Report
+
+Confirm what changed and where. Summarize consistency/gap follow-ups. Map each success_criteria item → pass | fail | blocked.
+
+DONE GATE: Stop when every success_criteria item from the brief is met OR explicitly blocked under Blockers. Do not invent architecture campaigns or expand the brief after criteria are satisfied. If the ask needs product code, review, or brand/DESIGN.md, report Blockers — do not become Coder, Reviewer, or Designer.
+
+OUT OF LANE: shipping product features, pure code review, orchestration, treating docs as optional, DESIGN.md ownership, becoming Coder or Reviewer as primary.`;
+
+/**
+ * Byte-stable system prompt builder. `theme` is the stable voice identifier;
+ * `build()` returns the identical raw card on every call (no env/interpolation).
+ */
+export const systemPrompt = {
+  theme: "shakespeare",
+  build: (): string => CARD,
+};

agents/shakespeare/src/toolset.ts

@@ -0,0 +1,19 @@
+// Shakespeare worker: docs maintenance — PRODUCT / ARCHITECTURE /
+// IMPLEMENTATION only. Docs lane uses DOCS_TOOLS: no run_shell.
+
+const SHAKESPEARE_TOOLS = [
+  "read_file",
+  "grep",
+  "search_files",
+  "list_dir",
+  "lsp",
+  "web_fetch",
+  "web_search",
+  "skill_search",
+  "use_skill",
+  "write_file",
+  "edit_file",
+  "delete_file",
+] as const;
+
+export const tools: readonly string[] = [...SHAKESPEARE_TOOLS];

agents/shakespeare/tsconfig.json

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