feat(planner): ship planner as a workspace agent package

Author: TheGreatAxios

agents/planner/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@corbits/agent-planner",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  }
+}

agents/planner/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * Planner worker (CL-9797): sawyer-skills artifact planner.
+ * Authors requirements (PRD.md), solution scopes (SOLUTION_SCOPE.md),
+ * and concrete ordered build plans (BUILD_PLAN.md).
+ *
+ * Ships as the @corbits/agent-planner 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/planner/package.test.ts.
+ */
+export type AgentPackage = {
+  readonly id: "planner";
+  readonly primaryIntent: string;
+  readonly outOfLane: readonly string[];
+  readonly description: string;
+  readonly systemPrompt: string;
+  /** Unset — planner never attaches skill bodies at spawn. */
+  readonly attachedSkills?: readonly string[];
+  /** Unset — planner declares no skill scope. */
+  readonly optionalSkills?: readonly string[];
+  readonly tools: {
+    readonly allow: readonly string[];
+  };
+  readonly spawn: {
+    readonly maySpawn: false;
+  };
+  readonly modelRole: "plan";
+  readonly tier: "leaf";
+};
+
+const PLANNER_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 plannerPackage: AgentPackage = {
+  id: "planner",
+  primaryIntent:
+    "Author requirements (PRD.md), solution scopes (SOLUTION_SCOPE.md), and ordered build plans (BUILD_PLAN.md)",
+  outOfLane: [
+    "shipping product implementation code",
+    "fleet orchestration or spawning",
+    "pure code defect review",
+    "becoming Coder or Reviewer as primary",
+  ],
+  description:
+    "Planning specialist — PRD.md, SOLUTION_SCOPE.md, and BUILD_PLAN.md authoring",
+  systemPrompt: `You are PlannerDirector (Planner), a specialist in Corbits Code.
+
+PRIMARY INTENT: author concrete, agent-proof engineering artifacts and plans. You are the planning lane only — not Coder, not Reviewer, not an orchestrator. Do not ship product implementation code yourself; author the plan and artifacts that Coder can execute without guessing.
+
+Sawyer-skills discipline & core artifacts:
+1. PRD.md (Requirements):
+   - Problem statement & user/operator value.
+   - User stories and detailed acceptance criteria.
+   - Edge cases, error modes, and boundary behaviors.
+2. SOLUTION_SCOPE.md (Boundaries & Invariants):
+   - Explicit in-scope deliverables.
+   - Non-goals (what we deliberately do NOT build).
+   - Architectural assumptions, subsystem invariants, and ownership boundaries.
+   - Backward compatibility implications and migration impact.
+3. BUILD_PLAN.md (Execution Steps):
+   - Exact files and paths to create, modify, or delete.
+   - Ordered, phased implementation sequence designed for incremental verification.
+   - Specific verification command for each phase (unit tests, types, lint, check).
+   - Rollback or fallback strategy if an approach fails.
+
+Workflow:
+1. Clarify requirements: read the brief's goals and success_criteria. If critical unknowns remain, ask the parent via ask_director; otherwise resolve ambiguity under explicit Assumptions.
+2. Inspect the codebase: read relevant paths, existing contracts, and test patterns to ground the plan in reality.
+3. Produce the plan: author the requested artifacts (PRD.md / SOLUTION_SCOPE.md / BUILD_PLAN.md when requested, or include the structured plan directly in Findings).
+4. Report: use the standard Summary / Findings / Blockers / Paths report envelope. Findings must carry the complete ordered plan, acceptance criteria, non-goals, and risks.
+
+OUT OF LANE: shipping product implementation code, executing test suites for product verification, fleet orchestration or spawning, becoming Coder or Reviewer as primary.`,
+  tools: { allow: [...PLANNER_TOOLS] },
+  spawn: { maySpawn: false },
+  tier: "leaf",
+  modelRole: "plan",
+};

bun.lock

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

package.json

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+
+import { plannerPackage } from "@corbits/agent-planner";
+import { BUILD_TOOLS } from "../tool-sets.js";
+import { DIRECTOR_REGISTRY } from "../registry.js";
+import type { DirectorPackage } from "../types.js";
+
+describe("plannerPackage", () => {
+  test("workspace package satisfies the director contract and feeds the registry", () => {
+    const asDirector: DirectorPackage = plannerPackage;
+    expect(asDirector.id).toBe("planner");
+    expect(DIRECTOR_REGISTRY.planner).toBe(plannerPackage);
+    expect([...plannerPackage.tools.allow]).toEqual([...BUILD_TOOLS]);
+  });
+
+  test("extracted copy stays build-scoped and non-spawning", () => {
+    expect(plannerPackage.tools.allow).toContain("write_file");
+    expect(plannerPackage.tools.allow).toContain("edit_file");
+    expect(plannerPackage.tools.allow).toContain("delete_file");
+    expect(plannerPackage.tools.allow).not.toContain("spawn_agent");
+    expect(plannerPackage.tools.allow).not.toContain("ask_operator");
+    expect(plannerPackage.spawn.maySpawn).toBe(false);
+    expect(plannerPackage.tier).toBe("leaf");
+    expect(plannerPackage.modelRole).toBe("plan");
+  });
+});

src/agent/directors/planner/package.test.ts

@@ -1,10 +1,10 @@
+import { plannerPackage } from "@corbits/agent-planner";
 import type { AgentProfile, CapabilityFilter } from "../profile-types.js";
 import { artistPackage } from "./artist/package.js";
 import { coderPackage } from "./coder/package.js";
 import { designerPackage } from "./designer/package.js";
 import { dispatchPackage } from "./dispatch/package.js";
 import { explorerPackage } from "./explorer/package.js";
-import { plannerPackage } from "./planner/package.js";
 import { proberPackage } from "./prober/package.js";
 import { qaLeadPackage } from "./qa-lead/package.js";
 import { reviewerPackage } from "./reviewer/package.js";

src/agent/directors/registry.ts

@@ -5,6 +5,7 @@
     "composite": false,
     "baseUrl": ".",
     "paths": {
+      "@corbits/agent-planner": ["./agents/planner/src/index.ts"],
       "@corbits/provider-opencode-go": ["./packages/opencode-go/src/index.ts"],
       "@corbits/first-class-providers": [
         "./packages/first-class-providers/src/index.ts"
@@ -17,6 +18,7 @@
     "src/**/*.ts",
     "testkit/**/*.ts",
     "packages/**/*.ts",
+    "agents/**/*.ts",
     "e2e/**/*.ts",
     "evals/**/*.ts",
     "scripts/**/*.ts"