AGENTS.md · git:20261112.288cd47 · 2026-11-12 · sha256 f8db1046fa04b96f

AGENTS.md git:20261112.288cd47A

Immutable. This exact content never changes and is served at /api/v1/blob/f8db1046fa04b96f.

# Super Review

Super Review is a skill, not an agent runtime. Reviewing a user's source is
read-only; developing this repository permits the requested edits and tests.
Do not confuse those scopes or install the review restrictions as a ban on
maintaining this repository.

## Instruction ownership

Keep review policy in `skills/super-review`: shared judgment and authority in
`references/review-contract.md`, domain decisions in lenses/language contexts,
coordination in `references/workflow.md`, and result fields in `assets/`.
Adapters own native tools, model selection and result collection, not a second
review policy. Version 3 has no custom source-reader or result-store runtime.

`skills/defect-review` and `skills/test-review` are separate skills, each
with its own contract, lenses or questions, roles and version.
Defect Review hunts bugs with independent readers and an independent
challenge; Test Review asks whether the tests would fail if a plausible bug
appeared. Like Super Review, both only read: no role clones, copies, builds
or runs the reviewed project or holds a tool for writing files, and a
finding is proven by a trace through quoted lines.
[The family design](docs/review-family.md) records why. No skill depends on
another at run time. Do not let one skill's criterion into another: a defect
is not a readability finding, and a weak test is not a defect.

`skills/perf-review` is a third such skill. Performance Review finds work a
Rust hot path does not need: a finding shows why the path runs often, traces
the work for one unit through quoted lines, gives a cheaper form with the
same behavior and names the resource it saves, and survives an independent
challenge. It reads only, like the others; a profile or benchmark output the
user supplies is evidence, and measuring a change is left to whoever applies
it. Slow code is not a defect, and fast code that reads badly is not a
performance finding.

For these three skills, settle the design before writing instructions, and do
not treat a model run as a step in writing them. Keep them short: state the
bar and where bugs or gaps live, and leave out procedure for recording the
reviewer's own work. A review of a real
repository is the maintainer's choice.

In every skill, say what an agent must achieve, not how to do what it can
work out itself, such as reading a long file in full or searching the code.
Spell out a step only when the agent cannot know it: a harness limit, the
user's choice, a fact about the reviewed project.

Give a lens a concrete question and a decision that can favor changing or
retaining code. Keep technical preservation constraints, the eight base
questions, stable rule IDs, independent recipients and configured model profiles.
Repeat guidance only for an independent recipient or a distinct local implication.
Generated install copies are delivery artifacts, not additional live context.

Use the files relevant to the requested change; do not load the entire reference
library or historical studies for every edit. Tool/role descriptions are
model-visible instructions too. Team references illustrate explicit rules, not
additional authority. Keep evaluator expectations and holdouts out of reviewer
packets and installed skill resources.

## Development and evidence

Edit canonical skills and adapter templates; keep generated copies byte-identical.
Select checks by changed inputs using [CONTRIBUTING.md](CONTRIBUTING.md).
For a changed agent decision, use [the evaluation protocol](evals/README.md) and
only its relevant cases. These are development resources, not review packets.
Reuse successful checks for the same revision/environment rather than repeat
an equivalent suite at each instruction layer. Fix failures caused by this change.

For instruction changes, use [the evaluation entry point](evals/README.md) to
select comparisons and run a bounded improvement cycle, not a generic rewrite.

Add contrasting evaluation inputs for a changed decision, separate from grading
expectations. Mechanical checks establish fixture/package integrity, not model
quality. Record actual model/effort and raw failures as well as successes before
claiming gains. Do not promote an experimental coverage/routing default without
its behavioral comparison; context savings alone are insufficient. Publication,
tags, marketplace updates and review comments need their own accepted scope.

An accepted release ends at pushing the `v<version>` tag on the merged main
commit: the `release` job in `.github/workflows/validate.yml` packages that tag
and creates the GitHub release itself, and fails if one already exists. Releases
are immutable: a tag whose release was published once can never carry another,
even after that release is deleted, so a broken release needs a new version. Wait for
that job, then pin the tag and its commit in the marketplace's `catalog.json`
as [CONTRIBUTING.md](CONTRIBUTING.md) describes.