Dark-Alex-17/coyote
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Added documentation for the new and improved code review suite

Dark-Alex-17 committed 2026-09-11 14:16:46 -06:00
1 parent 91243f95b0
commit d5b4531c22
3 files changed
+62 -29
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

Agents.md
+59 -27
@@ -547,7 +547,7 @@ Claude Code or OpenCode handle complex multi-step tasks.
For a working example of an orchestrator agent that uses sub-agent spawning, see the built-in
[sisyphus](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/sisyphus) agent. For an example of the teammate messaging pattern with parallel sub-agents,
see the [code-reviewer](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/code-reviewer) agent.
see the [domain-reviewer](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/domain-reviewer) agent.
> **Jobs vs. sub-agents:** sub-agents are for work that needs *reasoning*: they run a full LLM loop. To background a
> single long-running **tool call** (a build, a test suite, a slow MCP invocation), use the
@@ -726,7 +726,7 @@ agent__check_inbox
Messages are routed through the parent's supervisor. A parent can message its children, and children can message
their siblings. For a working example of the teammate pattern, see the built-in
[code-reviewer](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/code-reviewer) agent, which spawns file-specific reviewers that share
[domain-reviewer](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/domain-reviewer) agent, which spawns file-specific reviewers that share
cross-cutting findings with each other.
Sub-agents run by [graph agent nodes](Graph-Agents#agent) can also form per-fan-out teams: set `teammates: true` on the
@@ -828,7 +828,7 @@ otherwise. For the full skills model, including the frontmatter format, validati
the graph-agent variant, see the [Skills Guide](Skills).
For working examples of agents that use skills heavily, see the bundled
[`file-reviewer`](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/file-reviewer) and [`code-reviewer`](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/code-reviewer) agents.
[`file-reviewer`](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/file-reviewer) and [`domain-reviewer`](https://github.com/Dark-Alex-17/coyote/blob/main/assets/agents/domain-reviewer) agents.
## 10. Auto-Injected Prompts
@@ -852,12 +852,16 @@ available; only the auto-injected prompt text is suppressed.
# Built-In Agents
Coyote comes packaged with some useful built-in agents:
* `adversary`: An adversarial plan-conformance reviewer. Where `code-reviewer` asks "is this code good?",
`adversary` asks "is this the code the plan asked for — all of it, and only it?". Given a diff plus the
task/plan's acceptance criteria, it maps every criterion to evidence in the diff and hunts for silently
skipped criteria, scope drift, interface substitution, and requirements that never landed ("the dog that
didn't bark"), returning a blocking `ADVERSARIAL_REVIEW: CONFORMS`/`DIVERGES` verdict (via the
`adversarial-review` skill). The post-implementation counterpart to `oracle`'s pre-implementation
* `adversary`: A graph-based adversarial plan-conformance reviewer. Where `code-reviewer` asks "is this code good?",
`adversary` asks "is this the code the plan asked for? All of it, and only it?". The graph extracts the plan's
acceptance criteria into a list and fans out one fresh-context verification branch per criterion, so partial
coverage ("checked 8 of 12 and waved the rest through") is structurally impossible. Each verdict passes a
deterministic contract gate: `MET` requires evidence including the test proving the behavior (no test means at
best `PARTIAL`), malformed output is rejected once then recorded as `PARTIAL` (unproven). Then, a holistic
ADDITIVE-only pass hunts what per-criterion checks can't see: absence ("the dog that didn't bark"), scope drift,
interface substitution, silently-overridden recorded decisions, and gamed tests. A script computes the blocking
`ADVERSARIAL_REVIEW: CONFORMS`/`DIVERGES` verdict: CONFORMS requires every criterion MET with zero holistic
complaints, and a missing plan fails closed. The post-implementation counterpart to `oracle`'s pre-implementation
`plan-review`. Designed to be delegated to by `sisyphus` alongside `code-reviewer` (they cover different
failure modes: quality vs. conformance).
* `architecture-reviewer`: An on-demand architecture improvement scout (via the `codebase-design` skill). Scans a
@@ -869,8 +873,8 @@ Coyote comes packaged with some useful built-in agents:
doc, decomposes it into a quality-gated plan (`gatekeeper` self-containedness gate + `oracle`
plan-review) and ~1-engineer-day task files (via the `design-session` and `task-tracking` skills,
tracked on disk in a `plans/` directory), spawns one `sisyphus` per task on a single run branch with a
per-task `adversary` conformance check (plus a `probe` usage-pattern check when the task changes
consumer-facing surface), and finishes with ONE draft PR, CI checks watched to green,
per-task `review-gauntlet` done-gate (forced `adversary` conformance lane, plus `probe` when the task
changes consumer-facing surface), and finishes with ONE draft PR, CI checks watched to green,
plus follow-up task files for every manual action the code can't do for itself. Ends with a
`whetstone` continuous-improvement pass when the run addressed review feedback from outside its
own lanes. Supports opt-in
@@ -879,31 +883,47 @@ Coyote comes packaged with some useful built-in agents:
`other:<label>` via a design-time `librarian` lookup), which flows into every downstream reviewer, with
an evidence-cited rejection protocol for convention findings.
* `coder`: An agent to assist you with all your coding tasks
* `code-reviewer`: A [CodeRabbit](https://coderabbit.ai)-style code reviewer that spawns per-file reviewers using the
teammate messaging pattern and synthesizes their findings into a severity-tagged report. Includes an optional
operational-history lane (via the `incident-prior-art` skill): git archaeology on guards the diff deletes or
weakens, plus, when the `prior_art_agent` variable names an incident-historian agent, a sweep of your incident
record for past outages the change risks reintroducing. Resolves a quality bar (`rigor` + `surfaces`), which
are caller-passed, read from the active plan's frontmatter, or detected from the diff, and runs domain linters
(tflint/checkov, hadolint, actionlint, kubeconform) once orchestrator-side, routes the matching
surface-review skills into each file-reviewer, and folds below-threshold `[convention]` findings into a
`## Deferred by quality bar` section per the rigor level (🔴 findings never fold).
* `code-reviewer`: A [CodeRabbit](https://coderabbit.ai)-style graph-based review orchestrator — the deterministic
shell around LLM review judgment. Scripts resolve the diff, the quality bar (`rigor` + `surfaces`: caller-passed,
read from the active plan's frontmatter, or detected from the diff), repo conventions, matching review-miss
ledger patterns, and repo-history signals (fix/revert clusters plus prior PR review comments on fragile paths);
domain linters (tflint, hadolint, actionlint, `buf breaking`) run unconditionally when installed. Changed files
are grouped into DOMAIN slices — deterministic proposal, LLM refinement, and an exact-cover gate so no file can
be lost — and each slice is reviewed in parallel by a `domain-reviewer` leader with peer messaging between
leaders; every leader report passes a completeness gate (mandatory sections present even when clean,
reject-and-retry once). A synthesis node with NO verdict authority merges findings, `finding-verifier`
re-validates every 🔴/🟡 on an unskippable graph edge, and a SCRIPT computes the rigor folding
(below-threshold `[convention]` findings defer; 🔴 never folds) and the `MERGE-READY`/`NEEDS-HUMAN` verdict with
deterministic always-human triggers (destructive migrations, auth surface) — the model that wrote the findings
never grades its own homework. Optional lanes: operational history (`prior_art_agent`), org context
(`org_context_agent`), and a downstream-consumers sweep (`consumers_root`/`github_org`).
* `demo`: An example agent to use for reference when learning to create your own agents
* `deep-research`: A graph-based agent designed to perform deep web research
* `domain-reviewer`: A domain-slice review leader (used by the `code-reviewer` graph). Where `file-reviewer`
reviews one file in isolation, `domain-reviewer` reviews a group of RELATED changed files (e.g. the DB migration
plus the queries that use it, the routes plus their handlers, etc.) as one coherent unit: guard symmetry across the
slice's sibling paths, literal/enum drift between files, schema↔usage mismatch, and slice-level blast-radius /
test-adequacy / removed-guard checks reported even when clean. Small slices are reviewed directly with the full
skill stack; larger ones fan out one `file-reviewer` per file with a sibling roster. Leaders run as parallel
map branches with teammate messaging armed, so the DB leader can warn the API leader about a renamed column
mid-review. Emits a machine-checked report contract ending in `DOMAIN_REVIEW_COMPLETE`.
* `explore`: An agent designed to help you explore and understand your codebase
* `file-reviewer`: An agent designed to perform code-review on a single file (used by the `code-reviewer` agent).
* `file-reviewer`: An agent designed to perform code-review on a single file (used by `domain-reviewer` inside the `code-reviewer` graph).
Reviews with the `code-review` and `ai-slop-remover` skills, and additionally loads the `transactional-integrity`
skill when the diff touches state-changing code (e.g. DB writes, transactions, queue/webhook/job handlers, retries, or
external side effects, etc.) to catch atomicity gaps, read-modify-write races, non-idempotent handlers of at-least-once
inputs, and dual-writes with no reconciliation. Also loads `logging-discipline` on diffs with operational
surface, and, when the orchestrating `code-reviewer`'s surface routing names them, the surface-contract
surface, and, when the orchestrator's surface routing names them, the surface-contract
review skills (`rest-api-review`, `cli-review`, `library-review`, `worker-review`, `iac-review`,
`migration-review`, `cicd-review`), whose findings carry `[convention]`/`[correctness]` markers used for
rigor folding and the evidence-cited rejection protocol downstream.
* `finding-verifier`: A graph-based fact-checker for code-review findings (used by the `code-reviewer` agent).
* `finding-verifier`: A graph-based fact-checker for code-review findings (wired into the `code-reviewer`
graph as an unskippable edge).
Maps over a review's 🔴/🟡 findings in parallel, fresh context per finding, so the verifier inherits none of
the reviewer's assumptions, re-reads the cited code, and returns `VERIFIED` (with quoted evidence), `FALSE`
(only with proof, e.g. the "missing" guard exists at another path:line), or `UNVERIFIABLE` (kept, marked).
(only with proof, e.g. the "missing" guard exists at another path:line), or `UNVERIFIABLE` (kept, marked). Each branch's verdict passes a deterministic contract gate
(machine-validated JSON, authoritative id stamped from the finding itself, retry once; malformed output
records `UNVERIFIABLE` — a bad branch never sinks the run).
It never re-judges severity. It only tests whether a claim is true. `code-reviewer` uses the verdicts to
drop provably-false findings before the final report; dropped findings are tallied, never silently vanished.
* `gatekeeper`: A plan self-containedness gate (via the `plan-gatekeeping` skill). Audits a plan against
@@ -929,16 +949,28 @@ Coyote comes packaged with some useful built-in agents:
its tests are deliverables adopted as permanent regression coverage. Designed to be delegated to by
`sisyphus` and `architect` when a change touches consumer-visible surface.
* `report-writer`: An agent to polish research findings into clear, citation-preserving final reports
* `review-gauntlet`: A graph-based "done gate" that runs the whole review stack as ONE spawn. A script derives
deterministic change signals (auth surface, dependency/migration/exec changes, consumer-facing surface), an LLM
node may ADD lanes but never remove them, and a rules floor guarantees the minimum panel: `code-reviewer`
always, `adversary` whenever plan context exists, `security-reviewer` on security-relevant signals, and `probe`
when consumer surface changed and a local-run recipe exists. Lanes run in parallel with verdict independence
(no teammate messaging between reviewers), each lane's sentinel is machine-parsed (a missing or malformed
verdict BLOCKS, it never passes), and a script computes the final `GAUNTLET: PASS`/`BLOCKED` verdict (probe
`INCONCLUSIVE` blocks with an environment note, never coerced to pass or fail). The preferred way for
`sisyphus` and `architect` to run the review stack.
* `security-reviewer`: A security analyst for code changes (via the `security-review` skill). Traces untrusted data
from sources to dangerous sinks (injection, committed secrets, authn/authz gaps, path traversal, SSRF, unsafe
deserialization, supply chain), then returns a posture-gated `SECURITY_REVIEW: PASS`/`FAIL` verdict. The
`security_posture` variable (`prototype`/`standard`/`hardened`) sets the blocking threshold so POCs aren't held to
production strictness, while Critical findings (leaked credentials, host-endangering code) block in every posture.
production strictness, while Critical findings (leaked credentials, host-endangering code) block in every posture. Runs a
mechanized pre-pass first (gitleaks/semgrep/dependency audits when already installed) whose hits are leads
to trace, never pasted findings.
Designed to be delegated to by `sisyphus` alongside `code-reviewer` and `adversary`.
* `sisyphus`: A powerhouse orchestrator agent for writing complex code and acting as a natural language interface for
your codebase (similar to ClaudeCode, Gemini CLI, Codex, or OpenCode). Uses sub-agent spawning to delegate to
`explore`, `librarian`, `coder`, `oracle`, `code-reviewer`, `adversary`, `security-reviewer`, `probe`, `step-runner`, and `whetstone`. On
non-trivial work it runs up to four complementary independent review passes: `code-reviewer` for code quality,
`explore`, `librarian`, `coder`, `oracle`, `review-gauntlet`, `code-reviewer`, `adversary`, `security-reviewer`, `probe`, `step-runner`, and `whetstone`. On
non-trivial work it runs the review stack, preferably as ONE `review-gauntlet` spawn (the done gate
that machine-parses every lane's verdict), else as up to four individual review passes: `code-reviewer` for code quality,
`adversary` for plan conformance, and `security-reviewer` for exploitability when the change touches attack
surface, and `probe` for black-box usage-pattern verification when the change touches
consumer-facing surface. After a run that addressed review feedback from outside its own lanes (humans,
Macros.md
+2
@@ -210,6 +210,8 @@ on how to make your own macros, so be sure to check out the [built-in macro defi
looking for more examples.
* `generate-commit-message` - Generate a Git commit message based on the staged changes in the current directory
* `record-miss` - Record a code review suite miss into the review miss ledger at `<config_dir>/share/review-misses.md` so that it is not missed
on future code review suite runs.
Built-in macros are written to your macros directory on first run and never overwritten afterward, so your edits are
preserved across Coyote updates. To discard local changes and reinstall the built-in macros from the current Coyote build,
Skills.md
+1 -2
@@ -411,10 +411,9 @@ Coyote ships with thirty-five built-in skills, installed automatically on first
| `verification-gates` | `execute_command` | Evidence requirements (diagnostics, builds, tests) before claiming completion. |
| `plan-authoring` | `fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write` | Author executable high-level plans and per-step implementation plans for phased work; defines the plan repo layout and step-plan schema. |
| `plan-review` | `fs_read, fs_grep, fs_glob, fs_ls, fs_cat` | Adversarial review of implementation plans against executability, verifiability, and completeness standards. |
| `adversarial-review` | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls` | Adversarial plan-conformance review of an *implementation* against the plan it should satisfy (skipped criteria, scope drift, interface substitution); verdict `CONFORMS`/`DIVERGES`. Complements `code-review` (quality) and is the post-implementation counterpart to `plan-review`. |
| `plan-gatekeeping` | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls` | Gatekeep a plan for *self-containedness* before finalization: the "sealed container" test — every implementer question answered inline or via a verified pointer; verdict `PLAN_GATE: SEALED`/`LEAKY` with the missing questions. |
| `usage-pattern-testing` | `fs_read, fs_cat, fs_grep, fs_glob, fs_ls, fs_write, fs_patch, execute_command` | Black-box verification of a change's consumer-facing surface (HTTP APIs, RPCs, CLIs) against a locally running instance with clean state: run the repo's existing usage suites first (regression check, whatever their format, e.g. Hurl files, curl scripts, collections), then author spec-first tests for the uncovered delta in the repo's suite conventions (tools like Hurl/grpcurl are examples, not requirements); every failure classified BUG / EXPECTED-CHANGE / ENV; verdict `USAGE_PROBE: PASS`/`FAIL`/`INCONCLUSIVE`. The only review gate that tests *behavior* by using the thing, not reading it. |
| `review-misses` | none (knowledge-only) | The review-miss ledger: escaped defects (bugs that survived review and were caught later) recorded as reusable detection patterns in `~/.config/coyote/share/review-misses.md`. Review orchestrators load the skill, read the ledger, and route matching entries to reviewers as first-class checks. The feedback loop that makes the review stack converge instead of plateau. Companion macros: `record-miss` (record one escape) and `mine-review-misses` (batch-mine PR history); `whetstone` also writes entries. |
| `review-misses` | none (knowledge-only) | The review-miss ledger: escaped defects (bugs that survived review and were caught later) recorded as reusable detection patterns in `~/.config/coyote/share/review-misses.md`. Review orchestrators load the skill, read the ledger, and route matching entries to reviewers as first-class checks. The feedback loop that makes the review stack converge instead of plateau. Companion macro: `record-miss` (record one escape); `whetstone` and PR-review-round reconciliation feed a candidates inbox automatically. Promotion into the ledger stays approval-gated. |
| `design-session` | `fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write` | AI-first design decomposition: ground a design doc in the actual codebase, produce a PLAN file with approach, alternatives, and a ~1-engineer-day task breakdown with measurable acceptance criteria. Includes a quality-bar round declaring `rigor` (poc/prototype/production) and `surfaces`, which calibrate every downstream review gate. |
| `task-tracking` | `fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write, fs_patch, fs_mkdir` | File-based task tracking for plan-driven runs: TASK-NNN directory schema (`index.md` + append-only `log.md`), frontmatter lifecycle, numbering, follow-up tasks, and end-of-run consistency checks. |
| `step-implementation` | `execute_command` | End-to-end protocol for executing one step of a phased implementation plan. |