Skip to content

Commit b413228

Browse files
TheGreatAxiosTheGreatAxios
committed
feat(agent-planner): adopt uniform reusable agent template shape
1 parent 4971924 commit b413228

12 files changed

Lines changed: 207 additions & 107 deletions

File tree

‎agents/planner/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# @corbits/code-agent-planner
2+
3+
## What this is
4+
5+
Ready `@corbits/code-agent-planner` agent + independently importable components:
6+
`agent`, `defineAgent`, `director`, `tools`, `systemPrompt`, `config`.
7+
8+
## Consume (runLocal)
9+
10+
```ts
11+
import { agent } from "@corbits/code-agent-planner";
12+
const run = runLocal(defining(agent), env);
13+
```
14+
15+
## Consume (deploy runWorkflow / hub / sidecar)
16+
17+
Hand the same `AgentDefinition` to a workflow — the package never exports a
18+
workflow itself.
19+
20+
## Remix components
21+
22+
```ts
23+
import { director, tools, systemPrompt, config } from "@corbits/code-agent-planner";
24+
defineAgent({ director, ... }); // or swap tools / systemPrompt / config
25+
```
26+
27+
Each of `director`, `tools`, `systemPrompt`, and `config` is a named,
28+
independently importable part.
29+
30+
## Single authority
31+
32+
`prompt.ts` `systemPrompt.build()` is byte-stable (the raw card, no formatting).
33+
`toolset.ts` `tools` literal equals the `REVIEW_TOOLS` surface constant in
34+
`src/agent/directors/tool-sets.ts`; drift is enforced by the in-tree drift-guard
35+
`src/agent/directors/planner/package.test.ts`.

‎agents/planner/src/agent.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import {
2+
defineAgent as coreDefineAgent,
3+
type AgentDefinition,
4+
} from "@intx/agent";
5+
import { systemPrompt } from "./prompt.js";
6+
7+
/**
8+
* Planner ready agent — `agent = defineAgent()` plus the named component parts
9+
* (director/tools/systemPrompt/config) form the whole package surface.
10+
*/
11+
export const agent: AgentDefinition = defineAgent();
12+
13+
export function defineAgent(): AgentDefinition {
14+
return coreDefineAgent({
15+
id: "planner",
16+
systemPrompt: systemPrompt.build(),
17+
tools: [], // tool mounting is consumer/app-side; surface enforced by drift-guard
18+
capabilities: [],
19+
inference: {
20+
sources: [{ provider: "openai", model: "gpt-5" }],
21+
},
22+
tags: { fleet: "0.3.36", lane: "planner" },
23+
});
24+
}

‎agents/planner/src/config.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
/** Planner worker — sawyer-skills artifact planner (PRD/SOLUTION_SCOPE/BUILD_PLAN). */
2+
export const config = {
3+
spawn: { maySpawn: false },
4+
tier: "leaf",
5+
modelRole: "plan",
6+
} as const satisfies {
7+
spawn: { maySpawn: boolean };
8+
tier: string;
9+
modelRole: string;
10+
};

‎agents/planner/src/director.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import { tools } from "./toolset.js";
2+
import { systemPrompt } from "./prompt.js";
3+
import { config } from "./config.js";
4+
5+
/**
6+
* Planner worker director card. Structurally satisfies the app's
7+
* `DirectorPackage` (app-side drift-guard asserts assignability). App-independent.
8+
*/
9+
export const director = {
10+
id: "planner",
11+
primaryIntent:
12+
"Author requirements (PRD.md), solution scopes (SOLUTION_SCOPE.md), and ordered build plans (BUILD_PLAN.md)",
13+
outOfLane: [
14+
"shipping product implementation code",
15+
"fleet orchestration or spawning",
16+
"pure code defect review",
17+
"becoming Coder or Reviewer as primary",
18+
],
19+
description:
20+
"Planning specialist — PRD.md, SOLUTION_SCOPE.md, and BUILD_PLAN.md authoring",
21+
systemPrompt: systemPrompt.build(),
22+
tools: { allow: [...tools] },
23+
spawn: config.spawn,
24+
tier: config.tier,
25+
modelRole: config.modelRole,
26+
} as const;

‎agents/planner/src/index.ts‎

Lines changed: 8 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,8 @@
1-
/**
2-
* Planner worker (CL-9797): sawyer-skills artifact planner.
3-
* Authors requirements (PRD.md), solution scopes (SOLUTION_SCOPE.md),
4-
* and concrete ordered build plans (BUILD_PLAN.md).
5-
*
6-
* Ships as the @corbits/code-agent-planner workspace package: the tool allowlist
7-
* lives here so the package stays importable without the app. Drift against
8-
* the app build surface fails src/agent/directors/planner/package.test.ts.
9-
*/
10-
export type AgentPackage = {
11-
readonly id: "planner";
12-
readonly primaryIntent: string;
13-
readonly outOfLane: readonly string[];
14-
readonly description: string;
15-
readonly systemPrompt: string;
16-
/** Unset — planner never attaches skill bodies at spawn. */
17-
readonly attachedSkills?: readonly string[];
18-
/** Unset — planner declares no skill scope. */
19-
readonly optionalSkills?: readonly string[];
20-
readonly tools: {
21-
readonly allow: readonly string[];
22-
};
23-
readonly spawn: {
24-
readonly maySpawn: false;
25-
};
26-
readonly modelRole: "plan";
27-
readonly tier: "leaf";
28-
};
29-
30-
const PLANNER_TOOLS = [
31-
"read_file",
32-
"grep",
33-
"search_files",
34-
"list_dir",
35-
"lsp",
36-
"run_shell",
37-
"web_fetch",
38-
"web_search",
39-
"skill_search",
40-
"use_skill",
41-
"write_file",
42-
"edit_file",
43-
"delete_file",
44-
] as const;
45-
46-
export const plannerPackage: AgentPackage = {
47-
id: "planner",
48-
primaryIntent:
49-
"Author requirements (PRD.md), solution scopes (SOLUTION_SCOPE.md), and ordered build plans (BUILD_PLAN.md)",
50-
outOfLane: [
51-
"shipping product implementation code",
52-
"fleet orchestration or spawning",
53-
"pure code defect review",
54-
"becoming Coder or Reviewer as primary",
55-
],
56-
description:
57-
"Planning specialist — PRD.md, SOLUTION_SCOPE.md, and BUILD_PLAN.md authoring",
58-
systemPrompt: `You are PlannerDirector (Planner), a specialist in Corbits Code.
59-
60-
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.
61-
62-
Sawyer-skills discipline & core artifacts:
63-
1. PRD.md (Requirements):
64-
- Problem statement & user/operator value.
65-
- User stories and detailed acceptance criteria.
66-
- Edge cases, error modes, and boundary behaviors.
67-
2. SOLUTION_SCOPE.md (Boundaries & Invariants):
68-
- Explicit in-scope deliverables.
69-
- Non-goals (what we deliberately do NOT build).
70-
- Architectural assumptions, subsystem invariants, and ownership boundaries.
71-
- Backward compatibility implications and migration impact.
72-
3. BUILD_PLAN.md (Execution Steps):
73-
- Exact files and paths to create, modify, or delete.
74-
- Ordered, phased implementation sequence designed for incremental verification.
75-
- Specific verification command for each phase (unit tests, types, lint, check).
76-
- Rollback or fallback strategy if an approach fails.
77-
78-
Workflow:
79-
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.
80-
2. Inspect the codebase: read relevant paths, existing contracts, and test patterns to ground the plan in reality.
81-
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).
82-
4. Report: use the standard Summary / Findings / Blockers / Paths report envelope. Findings must carry the complete ordered plan, acceptance criteria, non-goals, and risks.
83-
84-
OUT OF LANE: shipping product implementation code, executing test suites for product verification, fleet orchestration or spawning, becoming Coder or Reviewer as primary.`,
85-
tools: { allow: [...PLANNER_TOOLS] },
86-
spawn: { maySpawn: false },
87-
tier: "leaf",
88-
modelRole: "plan",
89-
};
1+
export { agent, defineAgent } from "./agent.js";
2+
export { director } from "./director.js";
3+
export { tools } from "./toolset.js";
4+
export { systemPrompt } from "./prompt.js";
5+
export { config } from "./config.js";
6+
// No workflow export. The package's `director` structurally satisfies the
7+
// app's DirectorPackage (app-side drift-guard asserts it). No type re-export
8+
// to any Corbits shared package.

‎agents/planner/src/prompt.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// Planner raw director card. Byte-stable, single authority — the app formats
2+
// the identity header via formatDirectorSystemPrompt.
3+
4+
const CARD = `You are PlannerDirector (Planner), a specialist in Corbits Code.
5+
6+
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.
7+
8+
Sawyer-skills discipline & core artifacts:
9+
1. PRD.md (Requirements):
10+
- Problem statement & user/operator value.
11+
- User stories and detailed acceptance criteria.
12+
- Edge cases, error modes, and boundary behaviors.
13+
2. SOLUTION_SCOPE.md (Boundaries & Invariants):
14+
- Explicit in-scope deliverables.
15+
- Non-goals (what we deliberately do NOT build).
16+
- Architectural assumptions, subsystem invariants, and ownership boundaries.
17+
- Backward compatibility implications and migration impact.
18+
3. BUILD_PLAN.md (Execution Steps):
19+
- Exact files and paths to create, modify, or delete.
20+
- Ordered, phased implementation sequence designed for incremental verification.
21+
- Specific verification command for each phase (unit tests, types, lint, check).
22+
- Rollback or fallback strategy if an approach fails.
23+
24+
Workflow:
25+
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.
26+
2. Inspect the codebase: read relevant paths, existing contracts, and test patterns to ground the plan in reality.
27+
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).
28+
4. Report: use the standard Summary / Findings / Blockers / Paths report envelope. Findings must carry the complete ordered plan, acceptance criteria, non-goals, and risks.
29+
30+
OUT OF LANE: shipping product implementation code, executing test suites for product verification, fleet orchestration or spawning, becoming Coder or Reviewer as primary.`;
31+
32+
/**
33+
* Byte-stable system prompt builder. `theme` is the stable voice identifier;
34+
* `build()` returns the identical raw card on every call (no env/interpolation).
35+
*/
36+
export const systemPrompt = {
37+
theme: "planner",
38+
build: (): string => CARD,
39+
};

‎agents/planner/src/toolset.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Planner worker: sawyer-skills artifact planner. Authors requirements
2+
// (PRD.md), solution scopes (SOLUTION_SCOPE.md), and concrete ordered build
3+
// plans (BUILD_PLAN.md). Uses REVIEW_TOOLS.
4+
5+
const PLANNER_TOOLS = [
6+
"read_file",
7+
"grep",
8+
"search_files",
9+
"list_dir",
10+
"lsp",
11+
"run_shell",
12+
"web_fetch",
13+
"web_search",
14+
"skill_search",
15+
"use_skill",
16+
"write_file",
17+
"edit_file",
18+
"delete_file",
19+
] as const;
20+
21+
export const tools: readonly string[] = [...PLANNER_TOOLS];

‎agents/planner/tsconfig.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"extends": "../../tsconfig.base.json",
3+
"compilerOptions": {
4+
"noEmit": true
5+
},
6+
"include": ["src/**/*.ts"]
7+
}

‎bun.lock‎

Lines changed: 0 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,6 @@
8686
"tar": "^7.5.1"
8787
},
8888
"dependencies": {
89-
"@corbits/code-agent-planner": "workspace:*",
9089
"@corbits/codex-provider": "0.1.1",
9190
"@corbits/oauth-core": "0.2.0",
9291
"@corbits/openai-responses": "0.2.1",

0 commit comments

Comments
 (0)