From a8229e11d39855bcf9ad53080f62ad71c3a5f2e4 Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Fri, 28 Aug 2026 14:58:31 -0600
Subject: [PATCH] docs: Added documentation for the new skills and agent
 updates for the best practices quality gate

---
 Agents.md | 23 +++++++++++++++++++----
 Skills.md | 20 ++++++++++++++++++--
 2 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/Agents.md b/Agents.md
index 495e171..000c3fb 100644
--- a/Agents.md
+++ b/Agents.md
@@ -863,13 +863,20 @@ Coyote comes packaged with some useful built-in agents:
    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,
    plus follow-up task files for every manual action the code can't do for itself. Supports opt-in
-   worktree-based parallel task execution.
+   worktree-based parallel task execution. Plans declare a quality bar: `rigor` (poc/prototype/production)
+   plus the `surfaces` being built (rest-api, cli, library, worker, iac, db-migration, frontend, ci-cd, or
+   `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.
+   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).
 * `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 
 * `explore`: An agent designed to help you explore and understand your codebase
@@ -877,7 +884,11 @@ Coyote comes packaged with some useful built-in agents:
    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.
+   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
+   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.
 * `gatekeeper`: A plan self-containedness gate (via the `plan-gatekeeping` skill). Audits a plan against
    the "sealed container" standard, meaning every question a context-free implementer will hit is either answered
    inline or delegated via a VERIFIED pointer to the exact code/docs that answer it (where infra code goes,
@@ -914,7 +925,11 @@ Coyote comes packaged with some useful built-in agents:
    `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. Also supports plan-driven workflows: authoring phased implementation plans (via the `plan-authoring` 
-   skill), having `oracle` review them, and executing them one reviewed step at a time.
+   skill), having `oracle` review them, and executing them one reviewed step at a time. Handles review findings
+   quality-bar-aware: the plan's `rigor` calibrates which severities block (🔴 always does) and maps to a default
+   `security_posture`; below-threshold `[convention]` findings defer into follow-ups instead of blocking; and a
+   convention finding can be rejected only with cited evidence (a repo convention at file:line or a recorded plan
+   decision). Never 🔴 or `[correctness]` findings.
 * `sql`: A universal SQL agent that enables you to talk to any relational database in natural language
 * `step-runner`: A graph-based agent that executes ONE step of a phased implementation plan (a `plans/` repo authored 
    with the `plan-authoring` skill) with the step protocol enforced as graph edges: orient from the previous handoff -> 
diff --git a/Skills.md b/Skills.md
index 2fb2089..639043b 100644
--- a/Skills.md
+++ b/Skills.md
@@ -380,25 +380,41 @@ whitelist — but their processes stay cached for fast re-load.
 
 # Built-in Skills
 
-Coyote ships with nineteen built-in skills, installed automatically on first run:
+Coyote ships with thirty-five built-in skills, installed automatically on first run:
 
 | Skill                 | Granted tools / MCP servers                                              | Purpose                                                                     |
 |-----------------------|--------------------------------------------------------------------------|------------------------------------------------------------------------------|
 | `git-master`          | `execute_command`                                                        | Atomic commits, rebase methodology, conflict resolution, investigation.     |
 | `code-review`         | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Correctness/tests/clarity/coupling/footguns review checklist.               |
+| `security-review`     | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Security analysis of a code change: traces untrusted data to dangerous sinks (injection, committed secrets, authz gaps, path traversal, SSRF, unsafe deserialization, supply chain); posture-gated `PASS`/`FAIL` verdict. |
+| `transactional-integrity` | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                           | Review state-changing code for atomicity gaps, read-modify-write races, non-idempotent handlers of at-least-once inputs, and dual-writes with no reconciliation. |
+| `logging-discipline`  | none (knowledge-only)                                                    | Calibrate log output to the repo's existing logging conventions; review diffs for under- and over-logging (silent new failure paths, log-and-rethrow duplication, register mismatches). |
+| `comment-discipline`  | none (knowledge-only)                                                    | Calibrate comment density and style to the repo's existing comment register (self-documenting / api-documented / comment-heavy) before writing code. |
+| `observability-review` | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                              | Post-implementation observability analysis: decide what monitoring, metrics, and alerts the new code needs (accounting for what exists) and produce alert-as-code changes or a concrete monitoring TODO. |
+| `incident-prior-art`  | `execute_command`                                                        | Check a code change against operational history (i.e. git archaeology on deleted/weakened guards plus incident-record sweeps) so reviews catch regressions of hard-won production lessons. |
+| `rest-api-review`     | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Surface-contract review of REST/HTTP routes and handlers (plus gRPC/GraphQL sections): pagination, per-route auth decisions, PUT/DELETE idempotency, error shape, breaking published shapes. Routed by the plan's declared `surfaces`. |
+| `cli-review`          | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Surface-contract review of command-line changes: exit codes, stdout/stderr channel discipline, help text, non-interactive escape hatches, signal/cleanup behavior, config precedence. |
+| `library-review`      | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Surface-contract review of a library's public API: semver discipline against the manifest version, panic reachability from public entry points, doc coverage, error-type information, dependency weight. |
+| `worker-review`       | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Surface-contract review of queue/stream consumers and scheduled jobs: retry/backoff policy, DLQ/poison-message routing, graceful-shutdown drain, concurrency bounds. |
+| `iac-review`          | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Surface-contract review of Terraform/Helm/K8s manifests/Dockerfiles/compose: pinning, plaintext secret material, IAM/RBAC scope, resource limits, mutable tags, destructive operations. |
+| `migration-review`    | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Review of DB schema migrations: expand/contract compatibility with running code, reversibility, online/concurrent index creation, backfills mixed into DDL transactions. |
+| `cicd-review`         | `fs_read, fs_grep, fs_glob, fs_cat, fs_ls`                               | Review of CI/CD pipeline definitions: SHA-pinned actions, token/credential permission scoping, secret exposure to fork-PR triggers, cross-branch cache poisoning. |
 | `ai-slop-remover`     | none (knowledge-only)                                                    | Detect and remove AI slop from code and prose.                              |
 | `diagnostics`         | `execute_command`                                                        | Systematic troubleshooting of technical issues (services, networking, containers, OS) by running diagnostic commands directly. |
+| `diagnosing-bugs`     | `execute_command`                                                        | Feedback-loop-first debugging for hard bugs and performance regressions: build a tight, red-capable reproduction loop BEFORE forming hypotheses, minimise it, then test falsifiable hypotheses. |
+| `codebase-design`     | none (knowledge-only)                                                    | Shared vocabulary and principles for designing deep modules (depth, seams, adapters, leverage, locality) plus the deletion test and design-it-twice. |
 | `frontend-ui-ux`      | `fs_read, fs_write, fs_patch, fs_grep, fs_glob, fs_cat, fs_ls, fs_mkdir` | Designer-turned-developer crafting UI/UX even without mockups.              |
 | `delegation-protocol` | none (knowledge-only)                                                    | Structured 6-section delegation template and session-continuity rules for sub-agents. |
 | `parallel-research`   | none (knowledge-only)                                                    | Fan-out exploration protocol; parallel research agents without duplicated work. |
 | `oracle-protocol`     | none (knowledge-only)                                                    | Discipline for when and how to consult Oracle.                              |
+| `grilling`            | none (knowledge-only)                                                    | Interview the user relentlessly about a plan, decision, or design until shared understanding is reached, and structured as a design tree worked in frontier rounds. |
 | `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. |
-| `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. |
+| `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. |
 | `handoff-protocol`    | `fs_read, fs_cat, fs_ls, fs_write`                                       | Schema and discipline for writing and reading step handoff documents between implementation steps. |