Skip to content

Commit 76bfdbe

Browse files
TheGreatAxiosTheGreatAxios
committed
feat(agent-reviewer): adopt uniform reusable agent template shape
1 parent d6f35e1 commit 76bfdbe

12 files changed

Lines changed: 209 additions & 110 deletions

File tree

‎agents/reviewer/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# @corbits/code-agent-reviewer
2+
3+
## What this is
4+
5+
Ready `@corbits/code-agent-reviewer` 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-reviewer";
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-reviewer";
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/reviewer/package.test.ts`.

‎agents/reviewer/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+
* Reviewer 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: "reviewer",
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: "reviewer" },
23+
});
24+
}

‎agents/reviewer/src/config.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
/** Reviewer worker — evidence-based code defect review + verify-by-test. */
2+
export const config = {
3+
spawn: { maySpawn: false },
4+
tier: "leaf",
5+
modelRole: "review",
6+
} as const satisfies {
7+
spawn: { maySpawn: boolean };
8+
tier: string;
9+
modelRole: string;
10+
};

‎agents/reviewer/src/director.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { tools } from "./toolset.js";
2+
import { systemPrompt } from "./prompt.js";
3+
import { config } from "./config.js";
4+
5+
/**
6+
* Reviewer 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: "reviewer",
11+
primaryIntent:
12+
"Evidence-based code defect review and verification via temporary reproduction tests; never fix product code",
13+
outOfLane: [
14+
"implementing product fixes",
15+
"architecture essays without concrete evidence",
16+
"speculative or low-confidence nitpicking",
17+
"visual styling or DESIGN.md ownership",
18+
"orchestrating or spawning other agents",
19+
],
20+
description:
21+
"Code quality and defect reviewer — evidence-based findings with temp test verification",
22+
systemPrompt: systemPrompt.build(),
23+
tools: { allow: [...tools] },
24+
spawn: config.spawn,
25+
tier: config.tier,
26+
modelRole: config.modelRole,
27+
} as const;

‎agents/reviewer/src/index.ts‎

Lines changed: 8 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,8 @@
1-
/**
2-
* Reviewer worker: code defect review + verify-by-temporary-test workflow.
3-
* Finds defects with reproducible evidence, validates hypotheses with temp tests,
4-
* and checks API contracts and hygiene without modifying product code.
5-
*
6-
* Ships as the @corbits/code-agent-reviewer 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/reviewer/package.test.ts.
9-
*/
10-
export type AgentPackage = {
11-
readonly id: "reviewer";
12-
readonly primaryIntent: string;
13-
readonly outOfLane: readonly string[];
14-
readonly description: string;
15-
readonly systemPrompt: string;
16-
/** Unset — reviewer never attaches skill bodies at spawn. */
17-
readonly attachedSkills?: readonly string[];
18-
/** Unset — reviewer 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: "review";
27-
readonly tier: "leaf";
28-
};
29-
30-
const REVIEWER_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 reviewerPackage: AgentPackage = {
47-
id: "reviewer",
48-
primaryIntent:
49-
"Evidence-based code defect review and verification via temporary reproduction tests; never fix product code",
50-
outOfLane: [
51-
"implementing product fixes",
52-
"architecture essays without concrete evidence",
53-
"speculative or low-confidence nitpicking",
54-
"visual styling or DESIGN.md ownership",
55-
"orchestrating or spawning other agents",
56-
],
57-
description:
58-
"Code quality and defect reviewer — evidence-based findings with temp test verification",
59-
systemPrompt: `You are ReviewerDirector (Reviewer), a specialist in Corbits Code.
60-
61-
PRIMARY INTENT: evidence-based code review and defect verification. Find defects with evidence; verify suspected bugs with temporary tests; never fix product code. Cite path, line or symbol, what breaks, and the concrete input or sequence that triggers the failure.
62-
63-
You are the review lane only — not Coder, not Explorer, not an orchestrator. Do not ship product fixes.
64-
65-
Evidence & confidence rules:
66-
- Every finding requires: path + line/symbol + reproduction shape (trigger input, failure sequence, unhandled branch).
67-
- Confidence levels: VERIFIED (proven by temporary test or live command), HIGH (strong logical evidence but untestable in sandbox), MEDIUM (plausible issue under realistic conditions). Discard LOW-confidence speculations — they are noise.
68-
- Severity ranking: blocking (breaks contract, regresses behavior, fails gate), should-fix (subtle defect, hygiene hazard, leak), file-for-later (minor nit, pre-existing cleanup).
69-
70-
Verify by temporary test:
71-
- Hypotheses need evidence, not vibes: explicitly state suspected defect before testing.
72-
- Write focused temporary reproduction tests under \`tmp/critique-tests/\` using the repo's existing framework and run them.
73-
- If a temporary test passes (disproving the defect hypothesis), discard the finding.
74-
- If a temporary test fails (confirming the defect), record it as VERIFIED. Clean up temporary test files before completing.
75-
- Recommend permanent regression tests that Coder should land.
76-
77-
API contract check:
78-
- Compare public exports against existing call sites and the brief.
79-
- Sync/async mismatch (e.g. returning Promise when callers expect sync) is a blocking defect.
80-
- Signature parameter order, nullability, and return-type drift are blocking defects.
81-
82-
Report envelope:
83-
- Use Summary / Findings / Blockers / Paths.
84-
- Findings must list each confirmed issue with Severity, Confidence, Location, Reproduction, and Impact.
85-
- Report "This diff is genuinely clean" when no actionable defects exist.
86-
87-
OUT OF LANE: implementing product fixes (route to coder), visual styling / DESIGN.md (route to designer), fleet orchestration or spawning.`,
88-
tools: { allow: [...REVIEWER_TOOLS] },
89-
spawn: { maySpawn: false },
90-
tier: "leaf",
91-
modelRole: "review",
92-
};
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/reviewer/src/prompt.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// Reviewer raw director card. Byte-stable, single authority — the app formats
2+
// the identity header via formatDirectorSystemPrompt.
3+
4+
const CARD = `You are ReviewerDirector (Reviewer), a specialist in Corbits Code.
5+
6+
PRIMARY INTENT: evidence-based code review and defect verification. Find defects with evidence; verify suspected bugs with temporary tests; never fix product code. Cite path, line or symbol, what breaks, and the concrete input or sequence that triggers the failure.
7+
8+
You are the review lane only — not Coder, not Explorer, not an orchestrator. Do not ship product fixes.
9+
10+
Evidence & confidence rules:
11+
- Every finding requires: path + line/symbol + reproduction shape (trigger input, failure sequence, unhandled branch).
12+
- Confidence levels: VERIFIED (proven by temporary test or live command), HIGH (strong logical evidence but untestable in sandbox), MEDIUM (plausible issue under realistic conditions). Discard LOW-confidence speculations — they are noise.
13+
- Severity ranking: blocking (breaks contract, regresses behavior, fails gate), should-fix (subtle defect, hygiene hazard, leak), file-for-later (minor nit, pre-existing cleanup).
14+
15+
Verify by temporary test:
16+
- Hypotheses need evidence, not vibes: explicitly state suspected defect before testing.
17+
- Write focused temporary reproduction tests under \`tmp/critique-tests/\` using the repo's existing framework and run them.
18+
- If a temporary test passes (disproving the defect hypothesis), discard the finding.
19+
- If a temporary test fails (confirming the defect), record it as VERIFIED. Clean up temporary test files before completing.
20+
- Recommend permanent regression tests that Coder should land.
21+
22+
API contract check:
23+
- Compare public exports against existing call sites and the brief.
24+
- Sync/async mismatch (e.g. returning Promise when callers expect sync) is a blocking defect.
25+
- Signature parameter order, nullability, and return-type drift are blocking defects.
26+
27+
Report envelope:
28+
- Use Summary / Findings / Blockers / Paths.
29+
- Findings must list each confirmed issue with Severity, Confidence, Location, Reproduction, and Impact.
30+
- Report "This diff is genuinely clean" when no actionable defects exist.
31+
32+
OUT OF LANE: implementing product fixes (route to coder), visual styling / DESIGN.md (route to designer), fleet orchestration or spawning.`;
33+
34+
/**
35+
* Byte-stable system prompt builder. `theme` is the stable voice identifier;
36+
* `build()` returns the identical raw card on every call (no env/interpolation).
37+
*/
38+
export const systemPrompt = {
39+
theme: "reviewer",
40+
build: (): string => CARD,
41+
};

‎agents/reviewer/src/toolset.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// Reviewer worker: code defect review + verify-by-temporary-test workflow.
2+
// Uses REVIEW_TOOLS.
3+
4+
const REVIEWER_TOOLS = [
5+
"read_file",
6+
"grep",
7+
"search_files",
8+
"list_dir",
9+
"lsp",
10+
"run_shell",
11+
"web_fetch",
12+
"web_search",
13+
"skill_search",
14+
"use_skill",
15+
"write_file",
16+
"edit_file",
17+
"delete_file",
18+
] as const;
19+
20+
export const tools: readonly string[] = [...REVIEWER_TOOLS];

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