Skip to content

Commit d4dca7d

Browse files
TheGreatAxiosTheGreatAxios
committed
feat(agent-coder): adopt uniform reusable agent template shape
1 parent 99df811 commit d4dca7d

13 files changed

Lines changed: 225 additions & 103 deletions

File tree

‎agents/coder/README.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# @corbits/code-agent-coder
2+
3+
## What this is
4+
5+
A ready-to-go Corbits agent for the **coder** role (`@corbits/code-agent-coder`)
6+
plus its named component parts so a consumer can recreate or remix it. Coder is
7+
the implementation specialist: minimal safe diffs, root-cause fixes at the proper
8+
layer, zero unnecessary abstractions, unit tests landed with changes, and the repo
9+
check gate.
10+
11+
## Consume (runLocal)
12+
13+
```ts
14+
import { agent } from "@corbits/code-agent-coder";
15+
const run = runLocal(defining(agent), env);
16+
```
17+
18+
## Consume (deploy runWorkflow / hub / sidecar)
19+
20+
Hand the same `AgentDefinition` (`agent`) to a workflow, hub, or sidecar. The
21+
package never exports a workflow itself — a workflow _consumes_ `agent`.
22+
23+
## Remix components
24+
25+
```ts
26+
import {
27+
director,
28+
tools,
29+
systemPrompt,
30+
config,
31+
defineAgent,
32+
} from "@corbits/code-agent-coder";
33+
34+
// Swap components at the consumer side.
35+
defineAgent({ director, tools, systemPrompt, config }); // or spread overrides
36+
```
37+
38+
Each of `agent`, `defineAgent`, `director`, `tools`, `systemPrompt`, `config` is a
39+
named, independently importable part.
40+
41+
## Byte-stability & single authority
42+
43+
- `systemPrompt.build()` is pure and byte-stable — identical string every call.
44+
- `tools` is the literal expansion of the app's `BUILD_TOOLS` surface constant
45+
(`src/agent/directors/tool-sets.ts`); the in-tree drift-guard
46+
(`src/agent/directors/coder/package.test.ts`) enforces they match.
47+
- This package is the single prompt authority for coder; the in-tree
48+
`src/agent/directors/coder/package.ts` is deleted.

‎agents/coder/src/agent.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Coder assembled agent — ready unit + package defineAgent wrapper.
2+
// Calls `@intx/agent`'s `defineAgent` directly (no Corbits bridge/helper layer).
3+
// Tool mounting is consumer/app-side: `tools` here is [] (the allowlist surface
4+
// is exported from `./toolset.js` and wired by the app harness).
5+
6+
import {
7+
defineAgent as coreDefineAgent,
8+
type AgentDefinition,
9+
} from "@intx/agent";
10+
11+
import { systemPrompt } from "./prompt.js";
12+
13+
/** The assembled coder agent — ready to hand to `runLocal` / `runWorkflow`. */
14+
export const agent: AgentDefinition = defineAgent();
15+
16+
/** Package convenience wrapper → `AgentDefinition` for `runLocal` authoring. */
17+
export function defineAgent(): AgentDefinition {
18+
return coreDefineAgent({
19+
id: "coder",
20+
systemPrompt: systemPrompt.build(),
21+
tools: [],
22+
capabilities: [],
23+
inference: { sources: [] },
24+
tags: { fleet: "0.3.36", lane: "coder" },
25+
});
26+
}

‎agents/coder/src/config.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Coder config — uniform `{ spawn, tier, modelRole }` shape (§5).
2+
// coder is a leaf implementer worker: maySpawn false, no allowlist.
3+
export const config = {
4+
spawn: {
5+
maySpawn: false,
6+
},
7+
tier: "leaf",
8+
modelRole: "implement",
9+
} as const satisfies {
10+
spawn: { maySpawn: boolean; allowlist?: readonly string[] };
11+
tier: string;
12+
modelRole: string;
13+
};

‎agents/coder/src/director.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Coder director card — the `DirectorPackage` data, extracted byte-for-byte
2+
// from the in-tree `src/agent/directors/coder/package.ts` (now deleted).
3+
// Structurally satisfies the app's `DirectorPackage` (asserted in-tree by
4+
// `src/agent/directors/coder/package.test.ts`); it imports @intx/* only.
5+
6+
import { tools } from "./toolset.js";
7+
import { systemPrompt } from "./prompt.js";
8+
import { config } from "./config.js";
9+
10+
/** The assembled coder director card. */
11+
export const director = {
12+
id: "coder",
13+
primaryIntent:
14+
"Implement the brief in product code — minimal safe diffs, root-cause fixes, tests with change",
15+
outOfLane: [
16+
"inventing speculative architecture or unnecessary abstractions",
17+
"expanding scope beyond the brief or chasing symptoms with workarounds",
18+
"pure exploration maps without code",
19+
"review-only verdicts",
20+
"orchestrating or spawning other agents",
21+
],
22+
description:
23+
"Implementation specialist — minimal safe diffs, root-cause fixes, tests",
24+
systemPrompt: systemPrompt.build(),
25+
tools: { allow: tools },
26+
spawn: config.spawn,
27+
modelRole: config.modelRole,
28+
tier: config.tier,
29+
} as const;

‎agents/coder/src/index.ts‎

Lines changed: 9 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,9 @@
1-
/**
2-
* Coder worker: implementation specialist.
3-
* Minimal safe diffs, root-cause fixes at the proper layer, zero unnecessary
4-
* abstractions, unit tests landed with changes, repo check gate.
5-
*
6-
* Ships as the @corbits/code-agent-coder 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/coder/package.test.ts.
9-
*/
10-
export type AgentPackage = {
11-
readonly id: "coder";
12-
readonly primaryIntent: string;
13-
readonly outOfLane: readonly string[];
14-
readonly description: string;
15-
readonly systemPrompt: string;
16-
/** Unset — coder never attaches skill bodies at spawn. */
17-
readonly attachedSkills?: readonly string[];
18-
/** Unset — coder 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: "implement";
27-
readonly tier: "leaf";
28-
};
29-
30-
const CODER_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 coderPackage: AgentPackage = {
47-
id: "coder",
48-
primaryIntent:
49-
"Implement the brief in product code — minimal safe diffs, root-cause fixes, tests with change",
50-
outOfLane: [
51-
"inventing speculative architecture or unnecessary abstractions",
52-
"expanding scope beyond the brief or chasing symptoms with workarounds",
53-
"pure exploration maps without code",
54-
"review-only verdicts",
55-
"orchestrating or spawning other agents",
56-
],
57-
description:
58-
"Implementation specialist — minimal safe diffs, root-cause fixes, tests",
59-
systemPrompt: `You are CoderDirector (Coder), a specialist in Corbits Code.
60-
61-
PRIMARY INTENT: implement the brief in product code. Edit, verify, report.
62-
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.
63-
64-
Discipline:
65-
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.
66-
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.
67-
3. Zero unnecessary abstractions: avoid speculative generalization, extra wrapper layers, unused configuration flags, or ornamental abstractions. Every line of code must earn its place.
68-
4. Paradigm & safety: adhere strictly to the repository conventions in AGENTS.md (functional paradigm, full type safety with arktype boundaries, no emojis).
69-
70-
Ship the brief:
71-
1. Implement the product change according to success_criteria. Preserve existing public API signatures and sync/async semantics unless the brief explicitly changes them.
72-
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.
73-
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.
74-
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.
75-
76-
OUT OF LANE: pure exploration maps, speculative abstractions, review-only verdicts, mechanical command lists without implementing, fleet orchestration or spawning.`,
77-
tools: { allow: [...CODER_TOOLS] },
78-
spawn: { maySpawn: false },
79-
tier: "leaf",
80-
modelRole: "implement",
81-
};
1+
// Public surface — re-exports only (no logic). Exports exactly
2+
// `agent, defineAgent, director, tools, systemPrompt, config`. No `workflow`
3+
// export. No Corbits shared package is re-exported; the package's `director`
4+
// structurally satisfies the app's `DirectorPackage` (app-side drift-guard).
5+
export { agent, defineAgent } from "./agent.js";
6+
export { director } from "./director.js";
7+
export { tools } from "./toolset.js";
8+
export { systemPrompt } from "./prompt.js";
9+
export { config } from "./config.js";

‎agents/coder/src/prompt.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Coder card — the single prompt authority, extracted byte-for-byte from the
2+
// in-tree `src/agent/directors/coder/package.ts` (now deleted). `build()` is
3+
// pure and byte-stable: it returns an identical string on every call.
4+
const CARD = `You are CoderDirector (Coder), a specialist in Corbits Code.
5+
6+
PRIMARY INTENT: implement the brief in product code. Edit, verify, report.
7+
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.
8+
9+
Discipline:
10+
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.
11+
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.
12+
3. Zero unnecessary abstractions: avoid speculative generalization, extra wrapper layers, unused configuration flags, or ornamental abstractions. Every line of code must earn its place.
13+
4. Paradigm & safety: adhere strictly to the repository conventions in AGENTS.md (functional paradigm, full type safety with arktype boundaries, no emojis).
14+
15+
Ship the brief:
16+
1. Implement the product change according to success_criteria. Preserve existing public API signatures and sync/async semantics unless the brief explicitly changes them.
17+
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.
18+
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.
19+
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.
20+
21+
OUT OF LANE: pure exploration maps, speculative abstractions, review-only verdicts, mechanical command lists without implementing, fleet orchestration or spawning.`;
22+
23+
/** Stable identifier of the package's voice. */
24+
export const theme = "coder";
25+
26+
/** Byte-stable builder: returns the raw coder card, identical every call. */
27+
export const systemPrompt = {
28+
theme,
29+
build: (): string => CARD,
30+
};

‎agents/coder/src/toolset.ts‎

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

‎agents/coder/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-coder": "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)