agent-bios 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/DEPENDENCIES.md +5 -4
- package/README.md +2 -2
- package/claude/CLAUDE.md +2 -0
- package/claude/guides/claude-prompting.md +123 -0
- package/claude/guides/gpt-prompting.md +118 -0
- package/claude/guides/review-request.md +266 -0
- package/codex/AGENTS.md +2 -0
- package/codex/guides/claude-prompting.md +123 -0
- package/codex/guides/gpt-prompting.md +118 -0
- package/codex/guides/review-request.md +266 -0
- package/config/agent-launch.toml +6 -0
- package/package.json +3 -2
- package/scripts/agent-launch.py +147 -17
- package/scripts/check-parity.sh +8 -3
- package/scripts/check-prompting-targets.sh +62 -0
- package/scripts/install.sh +136 -4
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
guide_id: claude-prompting
|
|
3
|
+
language: en
|
|
4
|
+
status: active
|
|
5
|
+
use_when:
|
|
6
|
+
- composing a prompt, packet, or tool description for a claude-family model
|
|
7
|
+
- dispatching cross-family review to the claude side from a Codex main
|
|
8
|
+
- prompting claude subagents, or prompting yourself when the main is Claude
|
|
9
|
+
- porting a prompt written for an older claude model
|
|
10
|
+
- deciding a reasoning-effort level for claude work
|
|
11
|
+
core_rules:
|
|
12
|
+
- state the goal, the constraints, and the reason behind the request; let the model choose the route
|
|
13
|
+
- de-prescribe ported prompts — step-by-step scaffolding written for older models reduces output quality on this tier
|
|
14
|
+
- put the full task specification in the first turn for long-horizon work rather than revealing it across turns
|
|
15
|
+
- make tool descriptions prescriptive about when to call, not only what the tool does
|
|
16
|
+
- require progress claims to be audited against a tool result from the same session
|
|
17
|
+
- name the boundary explicitly — what to do without asking, and what to stop and ask about
|
|
18
|
+
targets:
|
|
19
|
+
- claude-fable-5
|
|
20
|
+
- claude-opus-4-8
|
|
21
|
+
- claude-sonnet-5
|
|
22
|
+
- claude-haiku-4-5
|
|
23
|
+
verification_focus:
|
|
24
|
+
- prompt changes are A/B'd against the prior scaffolding rather than assumed
|
|
25
|
+
- effort changes are swept across levels on a real eval set, not chosen by reputation
|
|
26
|
+
- per-model constraints are confirmed against the live surface before use
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
# Claude Prompting Guide
|
|
30
|
+
|
|
31
|
+
This guide is a scoped extension of the global Coding Guidelines. Use it when
|
|
32
|
+
composing a prompt for a claude-tier model — a review packet dispatched
|
|
33
|
+
cross-family, a subagent brief, or the main's own instructions when the main is
|
|
34
|
+
Claude.
|
|
35
|
+
|
|
36
|
+
The central shift: this tier is more autonomous and more literal than its
|
|
37
|
+
predecessors, and prompts written for older models are often too prescriptive —
|
|
38
|
+
they measurably reduce output quality. Porting a prompt means removing
|
|
39
|
+
scaffolding, not adding to it. State the goal and the constraints; let the model
|
|
40
|
+
pick the path.
|
|
41
|
+
|
|
42
|
+
## Default prompt recipe
|
|
43
|
+
|
|
44
|
+
- `Goal` and the **reason behind it** — this tier connects a task to relevant
|
|
45
|
+
context when it knows the intent, instead of inferring intent on its own.
|
|
46
|
+
"I'm doing X for Y, who needs Z; with that in mind: …" outperforms the bare
|
|
47
|
+
request, most of all for long-running agents holding several workstreams.
|
|
48
|
+
- `Success criteria` — what done means and how it is checked.
|
|
49
|
+
- `Constraints and boundaries` — say what not to do. This tier sometimes takes
|
|
50
|
+
unrequested-but-adjacent actions; naming the boundary is the fix.
|
|
51
|
+
- `Tools` — each description states **when to call it**, not only what it does.
|
|
52
|
+
Prescriptive trigger conditions give measurable lift here.
|
|
53
|
+
- `Output` — the artifact shape and the register.
|
|
54
|
+
|
|
55
|
+
## When to add blocks
|
|
56
|
+
|
|
57
|
+
- Long-horizon or autonomous work: give the full spec up front in one
|
|
58
|
+
well-specified turn and run at a high effort. Add an explicit self-check
|
|
59
|
+
cadence; separate fresh-context verifier subagents beat self-critique.
|
|
60
|
+
- Review: state the evidence bar and the verdict shape. This tier follows
|
|
61
|
+
severity filters literally, so "only report high-severity" depresses measured
|
|
62
|
+
recall even as bug-finding improves — ask for every finding with confidence
|
|
63
|
+
and severity attached, and filter downstream.
|
|
64
|
+
- Delegation: say when to delegate. Left unprompted this tier under-reaches for
|
|
65
|
+
subagents, file-based memory, and custom tools — it will not spend an
|
|
66
|
+
expensive capability unless it is reasonably sure the capability is needed.
|
|
67
|
+
- Autonomous runs with no human watching: say so. Otherwise it asks permission
|
|
68
|
+
it does not need and blocks. Grant autonomy on minor choices (naming,
|
|
69
|
+
defaults, equivalent approaches) while keeping the ask for scope changes and
|
|
70
|
+
destructive actions.
|
|
71
|
+
- Progress reporting: require each claim to be traceable to a tool result from
|
|
72
|
+
the session, and unverified work to be labeled as such.
|
|
73
|
+
|
|
74
|
+
## How to choose prompt shape
|
|
75
|
+
|
|
76
|
+
- One bounded question with a self-contained packet → a single run. Default for
|
|
77
|
+
review.
|
|
78
|
+
- Independent workstreams → delegate, and prefer asynchronous subagents over
|
|
79
|
+
spawn-and-block: long-lived agents keep their context instead of rebuilding it
|
|
80
|
+
per subtask, and the orchestrator is not pinned to the slowest one.
|
|
81
|
+
- Effort ladder — `low`, `medium`, `high`, `xhigh`, `max` on the frontier, helm,
|
|
82
|
+
and workhorse bindings; `xhigh` is the best setting for most coding and
|
|
83
|
+
agentic work, `high` a sound default, `low` for cheap subagent scans. Sweep the
|
|
84
|
+
levels on a real eval set rather than reaching for the top: higher effort up
|
|
85
|
+
front often *reduces* turn count and total cost on agentic work, while some
|
|
86
|
+
tasks land equally well a level down.
|
|
87
|
+
- Per-model constraints differ across the `targets` bindings — thinking
|
|
88
|
+
configuration, sampling parameters, and effort support are not uniform, and
|
|
89
|
+
the sweep binding is the most restricted. Confirm the constraint against the
|
|
90
|
+
live surface before relying on it in a dispatch; do not assume the frontier
|
|
91
|
+
binding's rules apply to the sweep one.
|
|
92
|
+
|
|
93
|
+
## Working rules
|
|
94
|
+
|
|
95
|
+
- Expect long turns. A single request on a hard task at high effort can run for
|
|
96
|
+
minutes; plan timeouts, streaming, and progress UX around that rather than
|
|
97
|
+
treating a quiet call as a hang.
|
|
98
|
+
- Do not add "summarize every N tool calls" scaffolding — this tier narrates on
|
|
99
|
+
its own. If it narrates too much for a coding agent, set a silence default
|
|
100
|
+
instead: text only on a finding, a direction change, or a blocker.
|
|
101
|
+
- Give it somewhere to write learnings, tell it to consult that place later, and
|
|
102
|
+
give the file a format. It performs notably better with a memory surface.
|
|
103
|
+
- Keep the deliverable readable: the final message is the reader's first look at
|
|
104
|
+
work they did not watch. Lead with the outcome; drop the working shorthand.
|
|
105
|
+
- Do not show a remaining-context countdown. This tier can start conserving and
|
|
106
|
+
suggest a fresh session instead of finishing.
|
|
107
|
+
|
|
108
|
+
## Prompt assembly checklist
|
|
109
|
+
|
|
110
|
+
1. Write the goal, the reason behind it, and the success criteria.
|
|
111
|
+
2. Name the boundaries — what to do freely, what to stop and ask about.
|
|
112
|
+
3. Give each tool a when-to-call description.
|
|
113
|
+
4. Say how progress claims must be grounded, and how the deliverable should read.
|
|
114
|
+
5. Delete the step-by-step scaffolding inherited from older models, then A/B the
|
|
115
|
+
prompt with it removed before keeping either version.
|
|
116
|
+
|
|
117
|
+
## Sources
|
|
118
|
+
|
|
119
|
+
Derived from the vendor's published guidance for the `targets` models above.
|
|
120
|
+
When a `targets` model changes, re-derive this guide from current vendor
|
|
121
|
+
guidance rather than editing around the old rules — prompting guidance is
|
|
122
|
+
version-bound. `scripts/check-prompting-targets.sh` fails when the launch config
|
|
123
|
+
binds a model this guide does not list.
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
---
|
|
2
|
+
guide_id: gpt-prompting
|
|
3
|
+
language: en
|
|
4
|
+
status: active
|
|
5
|
+
use_when:
|
|
6
|
+
- composing a prompt, packet, or tool description for a gpt-family model
|
|
7
|
+
- dispatching cross-family review to the gpt side from a Claude main
|
|
8
|
+
- prompting gpt subagents, or prompting yourself when the main is Codex
|
|
9
|
+
- porting a prompt written for an older gpt model
|
|
10
|
+
- deciding a reasoning-effort level for gpt work
|
|
11
|
+
core_rules:
|
|
12
|
+
- describe the destination, not the route — state outcome, success bar, real constraints, and available evidence
|
|
13
|
+
- simplify before adding; remove one group of instructions, examples, or tools at a time and re-run the same evals
|
|
14
|
+
- keep only what changes behavior; cut repeated statements, style rules, and examples that do not
|
|
15
|
+
- replace blanket ALWAYS/NEVER with decision rules naming the condition each choice applies under
|
|
16
|
+
- fix the prompt before raising effort — weak output usually means a missing success criterion, dependency rule, tool-routing rule, or verification loop
|
|
17
|
+
- prompting habits carried from older gpt models cost tokens and can cost accuracy
|
|
18
|
+
targets:
|
|
19
|
+
- gpt-5.6-sol
|
|
20
|
+
- gpt-5.6-terra
|
|
21
|
+
- gpt-5.6-luna
|
|
22
|
+
verification_focus:
|
|
23
|
+
- prompt changes are validated by re-running the same evals, not by inspection
|
|
24
|
+
- removals are tested one group at a time so the cause of a delta is known
|
|
25
|
+
- effort changes are compared against the baseline and one level lower
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
# GPT Prompting Guide
|
|
29
|
+
|
|
30
|
+
This guide is a scoped extension of the global Coding Guidelines. Use it when
|
|
31
|
+
composing a prompt for a gpt-tier model — a review packet dispatched
|
|
32
|
+
cross-family, a subagent brief, or the main's own instructions when the main is
|
|
33
|
+
Codex.
|
|
34
|
+
|
|
35
|
+
The current gpt tier is more concise and more self-directing than its
|
|
36
|
+
predecessors, so the failure mode has inverted: the usual defect is now an
|
|
37
|
+
over-specified prompt, not an under-specified one. Leaner system prompts
|
|
38
|
+
measured roughly +10–15% eval score at 41–66% fewer tokens and 33–67% lower
|
|
39
|
+
cost in the vendor's own coding-agent sample — directional, and worth
|
|
40
|
+
validating on your own workload rather than taking on faith.
|
|
41
|
+
|
|
42
|
+
## Default prompt recipe
|
|
43
|
+
|
|
44
|
+
Compose in this order; omit any block that would not change the artifact.
|
|
45
|
+
|
|
46
|
+
- `Role` and `Personality` — who is acting and in what register. Omit
|
|
47
|
+
personality when it does not change the output.
|
|
48
|
+
- `Goal` and `Success criteria` — the outcome, and the bar that decides done.
|
|
49
|
+
This is the block most worth its tokens; write it first. If you cannot state
|
|
50
|
+
the bar, the prompt is not ready.
|
|
51
|
+
- `Constraints` — safety, business, and scope limits that must hold. Real
|
|
52
|
+
constraints only; preferences belong in output shape or nowhere.
|
|
53
|
+
- `Tools` — only task-relevant ones. Each description states what it does, when
|
|
54
|
+
to use it, its important return fields, and its error behavior.
|
|
55
|
+
- `Output` — the artifact shape. `Stop rules` — when to stop looping and answer.
|
|
56
|
+
|
|
57
|
+
## When to add blocks
|
|
58
|
+
|
|
59
|
+
- Coding and debugging: name the validation to run after changes — targeted
|
|
60
|
+
tests for the changed behavior, type/lint checks, build, a minimal smoke test.
|
|
61
|
+
Require prerequisite lookups before edits.
|
|
62
|
+
- Review: no vendor task guidance exists for review specifically. Carry the
|
|
63
|
+
general rules and be explicit about the evidence bar and the verdict shape; a
|
|
64
|
+
reviewer with no stated bar defaults to plausible-sounding findings.
|
|
65
|
+
- Research and grounded work: cite only retrieved sources, attach citations to
|
|
66
|
+
the claims they support, and label inference separately from supported fact.
|
|
67
|
+
Say to narrow the answer or report missing evidence rather than guess.
|
|
68
|
+
- Write-capable work: name the safe actions explicitly (read files, edit code,
|
|
69
|
+
run tests) and require confirmation for external writes, destructive actions,
|
|
70
|
+
or scope expansion.
|
|
71
|
+
- Implementation plans: requirements, named resources, state transitions,
|
|
72
|
+
validation checks, failure behavior, privacy/security, open questions.
|
|
73
|
+
|
|
74
|
+
## How to choose prompt shape
|
|
75
|
+
|
|
76
|
+
- One bounded question with a self-contained packet → a single hermetic run.
|
|
77
|
+
This is the default for review.
|
|
78
|
+
- Work that divides into independent workstreams → fan-out. Parallelize
|
|
79
|
+
independent reads; keep dependent steps sequential.
|
|
80
|
+
- Effort ladder — `none`, `low`, `medium`, `high`, `xhigh`, `max` are all valid.
|
|
81
|
+
Hold the current binding as the baseline, then test it and one level lower on
|
|
82
|
+
representative tasks: `low` for latency-sensitive work, `medium` as the
|
|
83
|
+
balanced default, `high`/`xhigh` only where evals show real gain, `max`
|
|
84
|
+
reserved for the hardest quality-first work and compared against `xhigh`.
|
|
85
|
+
- Prefer a self-contained packet over resuming a long history: it is cheaper to
|
|
86
|
+
reason about and cheaper to cache.
|
|
87
|
+
|
|
88
|
+
## Working rules
|
|
89
|
+
|
|
90
|
+
- One clear task per run, with an explicit output contract.
|
|
91
|
+
- Keep reusable prefixes stable and avoid churn in large system prompts. Add
|
|
92
|
+
explicit cache breakpoints only where they measurably improve cache behavior —
|
|
93
|
+
a cache write costs 1.25× the uncached input rate, so read the cached-token
|
|
94
|
+
and cache-write counters before adding one.
|
|
95
|
+
- Do not say "be concise" reflexively. This tier is concise by default, and the
|
|
96
|
+
instruction can push responses past useful into thin.
|
|
97
|
+
- After each tool result, ask whether the core request can now be answered with
|
|
98
|
+
useful evidence. If yes, answer.
|
|
99
|
+
- Render any visual artifact before finalizing; inspect layout, clipping,
|
|
100
|
+
spacing, and missing content.
|
|
101
|
+
|
|
102
|
+
## Prompt assembly checklist
|
|
103
|
+
|
|
104
|
+
1. Write the success criteria first.
|
|
105
|
+
2. Add role, goal, real constraints, and the output shape.
|
|
106
|
+
3. Add only the tools the task needs, each with when-to-use and error behavior.
|
|
107
|
+
4. Add stop rules and the verification the task must pass.
|
|
108
|
+
5. Delete every line that would not change the artifact if removed, then re-read
|
|
109
|
+
for instructions inherited from older-model habits.
|
|
110
|
+
|
|
111
|
+
## Sources
|
|
112
|
+
|
|
113
|
+
Derived from the vendor's published prompting guidance for the `targets` models
|
|
114
|
+
above. When a `targets` model changes, re-derive this guide from current vendor
|
|
115
|
+
guidance rather than editing around the old rules — prompting guidance is
|
|
116
|
+
version-bound, and the previous generation's advice inverted on this one.
|
|
117
|
+
`scripts/check-prompting-targets.sh` fails when the launch config binds a model
|
|
118
|
+
this guide does not list.
|
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
---
|
|
2
|
+
guide_id: review-request
|
|
3
|
+
language: en
|
|
4
|
+
status: active
|
|
5
|
+
use_when:
|
|
6
|
+
- writing a review request, packet, or reviewer role for any model
|
|
7
|
+
- deciding what evidence bar and verdict shape to demand from a reviewer
|
|
8
|
+
- triaging why a review returned noise, nothing, or a clean bill of health
|
|
9
|
+
- choosing which perspectives to run and whether to pay for deliberation
|
|
10
|
+
core_rules:
|
|
11
|
+
- demand a failure path, not a gap — "X is unverified" dies, "X breaks when Y" survives
|
|
12
|
+
- require every finding to anchor to file:line, and every empty result to cite what was checked
|
|
13
|
+
- say what the target is and is not — stage, boundary, and what absence means
|
|
14
|
+
- bundle the consumer the target depends on, or its most load-bearing claim is unreviewable
|
|
15
|
+
- forbid carry-forward findings — anything phrased "watch" or "document later" is not a finding
|
|
16
|
+
- read participation before believing a verdict; a crashed harness reports zero findings
|
|
17
|
+
- treat a finding's causal attribution as the reviewer's weakest claim, not its severity
|
|
18
|
+
verification_focus:
|
|
19
|
+
- a zero-findings verdict is confirmed against participation, not accepted at face value
|
|
20
|
+
- findings are checked for a stated failure path before they are acted on
|
|
21
|
+
- an empty result is trusted only when it cites the evidence it checked
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
# Review Request Guide
|
|
25
|
+
|
|
26
|
+
This guide is a scoped extension of the global Coding Guidelines. Use it when
|
|
27
|
+
composing what you ask a reviewer for — the request, the evidence bar, the
|
|
28
|
+
verdict shape. It does not cover when to review, how deep, or what counts as
|
|
29
|
+
material (the staged-workflow guide's severity ladder and review loop own that),
|
|
30
|
+
which reviewer kind to route to (the multi-model guide's convergence heuristic),
|
|
31
|
+
or how to phrase a prompt for a given model family (the per-family prompting
|
|
32
|
+
guides).
|
|
33
|
+
|
|
34
|
+
The rules below are derived from ~330 real multi-lens review sessions run in
|
|
35
|
+
this environment. That corpus is one model family in practice, so nothing here
|
|
36
|
+
is a per-model claim; these are the failures that persist regardless of who
|
|
37
|
+
reviews. Every rule names the evidence behind it, because a review guide that
|
|
38
|
+
asserts without evidence would fail its own bar.
|
|
39
|
+
|
|
40
|
+
## Demand a failure path, not a gap
|
|
41
|
+
|
|
42
|
+
The dominant reviewer failure is not hallucination. Across 372 rejected
|
|
43
|
+
findings, "asserted a gap without demonstrating a failure" accounts for the
|
|
44
|
+
largest share (~34%), while misreading correct code accounts for **one** case
|
|
45
|
+
and speculation for seven. Reviewers do not invent defects — they report
|
|
46
|
+
unverified things and call them findings.
|
|
47
|
+
|
|
48
|
+
The corpus separates these cleanly by how the finding is framed:
|
|
49
|
+
|
|
50
|
+
| Framed as | Dropped |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `evidence_gap` — "not covered / not verified" | 94% (n=143) |
|
|
53
|
+
| `needs_evidence` | 93% (n=118) |
|
|
54
|
+
| `document_only` | 92% (n=144) |
|
|
55
|
+
| `root_cause` — a defect with a cause | 3% (n=878) |
|
|
56
|
+
| `fix_now` | 3% (n=1026) |
|
|
57
|
+
|
|
58
|
+
So say it in the request: **state the input, the branch, and the observable
|
|
59
|
+
wrong behavior. "X is not verified" is not a finding; "X breaks when Y" is.**
|
|
60
|
+
A reviewer that cannot show the failure should say so as a boundary note, not
|
|
61
|
+
file it against the target.
|
|
62
|
+
|
|
63
|
+
## Set a severity floor, because low never survives
|
|
64
|
+
|
|
65
|
+
Severity is the single most decisive predictor in the corpus, and it is close to
|
|
66
|
+
deterministic:
|
|
67
|
+
|
|
68
|
+
| Severity | Reaches the deliverable |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `blocker` (n=16) | 100% |
|
|
71
|
+
| `high` (n=366) | 96% |
|
|
72
|
+
| `medium` (n=1338) | 92% |
|
|
73
|
+
| `info` (n=44) | 5% |
|
|
74
|
+
| `low` (n=226) | **0%** |
|
|
75
|
+
|
|
76
|
+
Not one low-severity finding out of 226 survived. The tokens that produced them
|
|
77
|
+
were spent for nothing, twice — once writing, once reading.
|
|
78
|
+
|
|
79
|
+
So state the floor in the request: **do not report a finding you would rate low.
|
|
80
|
+
It will be discarded; spend the effort on a medium-or-above finding instead.**
|
|
81
|
+
This is not a quality bar on the reviewer, it is a cost decision — the corpus
|
|
82
|
+
shows the discard happens regardless, so the only question is whether you pay to
|
|
83
|
+
generate it first. (What counts as each severity is the staged-workflow guide's
|
|
84
|
+
ladder, not this guide's.)
|
|
85
|
+
|
|
86
|
+
## Forbid carry-forward findings
|
|
87
|
+
|
|
88
|
+
Every finding the corpus classified as deferrable died: `planned_later` 100%
|
|
89
|
+
(n=104), `watch` 100% (n=36), `defer_watch` 97% (n=71), `out_of_scope` 92%
|
|
90
|
+
(n=26). Not one survived to the deliverable.
|
|
91
|
+
|
|
92
|
+
Ask only for what must change in this target now. Anything the reviewer would
|
|
93
|
+
phrase as "carry forward", "watch", or "document later" costs tokens to produce,
|
|
94
|
+
tokens to read, and is discarded — say that up front so it is never written.
|
|
95
|
+
|
|
96
|
+
## Say what the target is, and what absence means
|
|
97
|
+
|
|
98
|
+
The most common thing reviewers report they lacked is the stage context: they
|
|
99
|
+
review a design and cannot see the implementation, then hedge every finding into
|
|
100
|
+
a design-contract claim. Their own words, recurring across sessions: *"The packet
|
|
101
|
+
reviews a design, not an implemented patch, so the exact future API is not
|
|
102
|
+
visible."*
|
|
103
|
+
|
|
104
|
+
Name the stage and say what absence means — "this is a pre-implementation
|
|
105
|
+
design; do not treat missing implementation as a defect." A session given exactly
|
|
106
|
+
that instruction returned zero findings and proved it had looked, anchored on
|
|
107
|
+
both sides of the comparison. A session not given it filed unimplemented code as
|
|
108
|
+
blockers, and the user caught it manually.
|
|
109
|
+
|
|
110
|
+
## Bundle the consumer, not just the artifact
|
|
111
|
+
|
|
112
|
+
When a target says "see X", X is part of the target. The corpus's sharpest
|
|
113
|
+
example: a reviewer identified the most load-bearing connection in a design and
|
|
114
|
+
then could not review it — *"§6.4 is outside the review boundary, so
|
|
115
|
+
axis-consumption completeness cannot be verified within the artifact."* The
|
|
116
|
+
request bundled the child and not the parent it depended on.
|
|
117
|
+
|
|
118
|
+
What reviewers needed, almost every time, was the consumer: the code that reads
|
|
119
|
+
the field, the parent doc defining the weights, the log proving the behavior. If
|
|
120
|
+
a claim's evidence lives outside the boundary, either widen the boundary or
|
|
121
|
+
accept that the claim is unreviewable — do not expect a finding about it.
|
|
122
|
+
|
|
123
|
+
## Make evidence structural, not requested
|
|
124
|
+
|
|
125
|
+
In this corpus every finding carries a `file:line` anchor and every empty result
|
|
126
|
+
carries a rationale — 2,466/2,466 and 981/981. Not because the prompts asked
|
|
127
|
+
nicely: the submit schema refuses output without them. The result is a corpus
|
|
128
|
+
where reviewers are right about existence (0.3% of issues end unresolved after
|
|
129
|
+
argument) and where "found nothing" is a verified statement rather than silence.
|
|
130
|
+
|
|
131
|
+
This is the general rule from the capability-boundary guide applied to review:
|
|
132
|
+
when output must have a property, make it unavailable without it. If your review
|
|
133
|
+
route has a schema, put the anchor there. If it does not, the demand belongs in
|
|
134
|
+
the request — but expect the weaker result that a request-only rule gives you.
|
|
135
|
+
|
|
136
|
+
The same applies to the target: a document that cites its own facts as
|
|
137
|
+
`file:line` gives the reviewer a falsifiable surface, and the corpus's best
|
|
138
|
+
findings are refutations of exactly those cited facts. Prose gives nothing to
|
|
139
|
+
check.
|
|
140
|
+
|
|
141
|
+
## Claim only what the evidence proves, and attribute it to one root
|
|
142
|
+
|
|
143
|
+
Reviewers are calibrated on whether a defect exists and miscalibrated on why.
|
|
144
|
+
When a finding is narrowed, the defect itself almost always survives (97%,
|
|
145
|
+
n=212). What gets cut is the causal attribution (45%) or the surface the claim
|
|
146
|
+
covered (34%) — not the proposed fix (10%), and not the defect. Lenses register
|
|
147
|
+
this as a first-class stance: `narrow` appears 1,320 times against 101 for
|
|
148
|
+
`oppose`. They rarely disagree that something is broken; they routinely disagree
|
|
149
|
+
about what broke it, and about how much of the system it touches.
|
|
150
|
+
|
|
151
|
+
"Narrowed" is a misleading name for what happens. Narrowed claims get **longer**
|
|
152
|
+
— 94% of them, by a median of ~118 characters — because narrowing adds
|
|
153
|
+
qualification and re-attribution rather than deleting text. The final root cause
|
|
154
|
+
is a near-rewrite (median text similarity 0.21 against the original). What looks
|
|
155
|
+
like trimming is the reviewer being made to say what its evidence actually
|
|
156
|
+
supports.
|
|
157
|
+
|
|
158
|
+
That makes narrowing and rejection the same force at different granularity:
|
|
159
|
+
overclaim beyond your evidence and the finding is narrowed if a proven core
|
|
160
|
+
exists, dropped if it does not. The corpus language is identical in both — the
|
|
161
|
+
survivors are "narrowed to the directly evidenced command-wiring gap", "to files
|
|
162
|
+
proven in capsule authority_refs", "to the demonstrated side-effect path".
|
|
163
|
+
|
|
164
|
+
So ask for the observable failure and the evidence that proves it, scoped to the
|
|
165
|
+
surface that evidence covers. Treat the reviewer's causal story as its weakest
|
|
166
|
+
claim — a hypothesis to verify, not a conclusion — and do not let a proposed fix
|
|
167
|
+
become the design by default.
|
|
168
|
+
|
|
169
|
+
One axis is easy to miss: in ~17% of narrowings every lens accepts the defect,
|
|
170
|
+
the root, and the fix, and the only live disagreement is **how bad it is**. That
|
|
171
|
+
matters more than its share suggests, because severity decides survival — a
|
|
172
|
+
finding rated low never reaches the deliverable. If severity is contested, it is
|
|
173
|
+
the thing to adjudicate, not a detail to average out.
|
|
174
|
+
|
|
175
|
+
## Read participation before believing a verdict
|
|
176
|
+
|
|
177
|
+
Seven sessions reported `Finding count: 0` — a clean bill of health — with
|
|
178
|
+
`Participating lenses: 0/N`. Nothing was reviewed. And when the harness dies, two
|
|
179
|
+
separate channels lie about why. Twenty-two sessions recorded
|
|
180
|
+
`failure_kind: output_contract`; in the ones whose nested stderr is readable the
|
|
181
|
+
cause is a provider usage-limit rejection — *"You've hit your usage limit"*,
|
|
182
|
+
`exit=1`, no model output produced at all — so the label blames the model's
|
|
183
|
+
output format for a pre-dispatch billing refusal, when no output ever existed to
|
|
184
|
+
violate a contract. Triage by that label and you debug the prompt when you needed
|
|
185
|
+
to buy credits.
|
|
186
|
+
|
|
187
|
+
Two consequences for anyone consuming a review:
|
|
188
|
+
|
|
189
|
+
- The tell is the participation count and execution status, never the severity
|
|
190
|
+
counts. A crashed harness renders as a perfect score.
|
|
191
|
+
- Artifacts named for failure may not carry it, and the two failures compound. In
|
|
192
|
+
those same quota-killed sessions the file named `environment-warnings.yaml`
|
|
193
|
+
recorded only `non_fatal` dispatch traces with `outputTrustImpact: unknown` and
|
|
194
|
+
never once mentioned the quota; corpus-wide it holds ~9,800 warnings and has
|
|
195
|
+
never fired on a real failure. So the channel named for failures never fires,
|
|
196
|
+
the channel that fires uses the wrong name, and the truth is only in the nested
|
|
197
|
+
stderr. Read the channel the mechanism actually writes, confirmed against the
|
|
198
|
+
low-level log, not the one named for the thing you want.
|
|
199
|
+
- A review deliverable names the findings it *rejected* as well as the ones it
|
|
200
|
+
kept, so a finding's presence in the document is not its survival. Deriving
|
|
201
|
+
survival from presence returns 100% by construction — it did here, until the
|
|
202
|
+
count was scoped to the material section, at which point 16% of the same
|
|
203
|
+
findings turned out to have reached the reader explicitly flagged
|
|
204
|
+
non-material. Read the verdict field, not the mention.
|
|
205
|
+
|
|
206
|
+
## Trust an empty result only when it cites what it checked
|
|
207
|
+
|
|
208
|
+
Empty is common and usually correct: 42% of lens invocations produce nothing,
|
|
209
|
+
and those runs have *larger* inputs and sit *later* in a repo's review sequence
|
|
210
|
+
than productive ones — they are re-reviews of targets already fixed. The waste
|
|
211
|
+
worth naming is not the empty result; it is paying full pipeline cost to
|
|
212
|
+
re-review something you already repaired.
|
|
213
|
+
|
|
214
|
+
An empty result earns trust from its rationale. A reasoned null names the
|
|
215
|
+
evidence it checked on both sides of the comparison. A rationale-free empty
|
|
216
|
+
result is a failed run wearing a clean verdict — gate on the rationale, not on
|
|
217
|
+
the emptiness.
|
|
218
|
+
|
|
219
|
+
## Spend deliberation where it adjudicates, not where it agrees
|
|
220
|
+
|
|
221
|
+
Two-thirds of issues (66%, n=1153) never need deliberation, and the largest
|
|
222
|
+
single cause of halted sessions is the user cancelling. But they do not cancel
|
|
223
|
+
early: of 27 cancelled sessions all 27 reached the raw first pass, 22 reached the
|
|
224
|
+
consolidated finding ledger, and only 2 reached deliberation. Users wait for the
|
|
225
|
+
deduplicated, severity-tagged ledger, act on it, and abandon the deliberation and
|
|
226
|
+
synthesis that would have run next. Meanwhile the issues that *are* deliberated
|
|
227
|
+
and survive are the most reliable in the corpus (94% material vs 74% for
|
|
228
|
+
undeliberated).
|
|
229
|
+
|
|
230
|
+
So deliberation is worth its cost when it adjudicates a contested claim, and is
|
|
231
|
+
ceremony when every perspective already agrees — one of the largest deliberation
|
|
232
|
+
artifacts in the corpus resolved 22 of 22 issues as "no deliberation needed".
|
|
233
|
+
Front-load the actionable findings, because that is the part that gets used.
|
|
234
|
+
|
|
235
|
+
## Choose perspectives that can bite
|
|
236
|
+
|
|
237
|
+
Adding a perspective is not free. In this corpus the concept-surface lens
|
|
238
|
+
produces the fewest findings, is silent most often, and half of what it does
|
|
239
|
+
produce is discarded — because 43% of its candidates are rated low, and low
|
|
240
|
+
never survives. Naming, redundancy, and abstraction concerns count only when
|
|
241
|
+
they change runtime behavior or enforced semantics; ask for them on that
|
|
242
|
+
condition or not at all.
|
|
243
|
+
|
|
244
|
+
The inverse failure is worth watching for: when no perspective owns the real
|
|
245
|
+
risk, a reviewer files a governance gap instead of a defect — *"this is a
|
|
246
|
+
review-governance gap, not a design defect in the target."* That is the review
|
|
247
|
+
telling you its own lens set was wrong for the target.
|
|
248
|
+
|
|
249
|
+
## Evidence base
|
|
250
|
+
|
|
251
|
+
Derived 2026-07-16 from ~330 onto review sessions across 15 repositories in this
|
|
252
|
+
environment (1,738 classified issues; 2,466 anchored findings; 278 deliberations;
|
|
253
|
+
14,370 lens stances). Every count here was reproduced independently before being
|
|
254
|
+
written down, and several first attempts were wrong: survival measured by
|
|
255
|
+
document presence returns 100% by construction, and hand-rolled verb-object
|
|
256
|
+
counting undercounted the narrowing axes about fivefold. Where a share is given
|
|
257
|
+
for how narrowing splits, read it as a floor — ~19% of cases resist
|
|
258
|
+
classification — and trust the ordering (root > scope > severity > remedy) rather
|
|
259
|
+
than the magnitudes.
|
|
260
|
+
|
|
261
|
+
Two limits bound what this guide may claim. The corpus is ~95% a single model
|
|
262
|
+
family, so nothing here is a per-model claim. And it contains no under-specified
|
|
263
|
+
requests — the shortest still names its axes and its evidence bar — so these are
|
|
264
|
+
the failures that survive a *good* request, not an argument that requests need
|
|
265
|
+
specifying. Re-derive from a fresh corpus when the review route or the bound
|
|
266
|
+
models change.
|
package/config/agent-launch.toml
CHANGED
|
@@ -8,11 +8,17 @@ passthrough_args = []
|
|
|
8
8
|
command = "claude"
|
|
9
9
|
passthrough_args = ["--dangerously-skip-permissions"]
|
|
10
10
|
|
|
11
|
+
# Optional dependencies. `command` gates the route: unresolvable means the route
|
|
12
|
+
# is unavailable and the review setup degrades without it. `install` is the single
|
|
13
|
+
# source for both the one-line hint shown when it is missing and what
|
|
14
|
+
# `agent-bios install --with <name>` runs.
|
|
11
15
|
[capabilities.onto]
|
|
12
16
|
command = "onto"
|
|
17
|
+
install = "npm i -g onto-mcp"
|
|
13
18
|
|
|
14
19
|
[capabilities.ultracode]
|
|
15
20
|
command = "ultracode-for-codex"
|
|
21
|
+
install = "npm i -g ultracode-for-codex"
|
|
16
22
|
|
|
17
23
|
[hosts.codex]
|
|
18
24
|
models = ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna"]
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agent-bios",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "A thin, low-level instruction layer for LLM CLI agents: one set of principles and behavior whichever model you run. Deploys into $HOME by copy via an explicit `agent-bios install`.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"agent-bios": "scripts/install.sh"
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"shell/agent-launch.zsh",
|
|
16
16
|
"scripts/agent-launch.py",
|
|
17
17
|
"scripts/check-parity.sh",
|
|
18
|
+
"scripts/check-prompting-targets.sh",
|
|
18
19
|
"scripts/codex-run.sh",
|
|
19
20
|
"scripts/codex-helm.sh",
|
|
20
21
|
"scripts/install.sh",
|
|
@@ -48,7 +49,7 @@
|
|
|
48
49
|
],
|
|
49
50
|
"repository": {
|
|
50
51
|
"type": "git",
|
|
51
|
-
"url": "git+https://github.com/kangminlee-maker/agent-
|
|
52
|
+
"url": "git+https://github.com/kangminlee-maker/agent-bios.git"
|
|
52
53
|
},
|
|
53
54
|
"license": "MIT"
|
|
54
55
|
}
|