j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan/addons/ai-diff-reviewer
deepworkplan-addon-ai-diff-reviewer
VerifiedDeepWorkPlan addon — required local review (baseline since standard 2.3.0), optional CI surface — connects an AI-first repo to the AI Diff Reviewer. Onboarding installs the vendored coding-agent skill and extension with consent; the Final Review runs the local pass when present or records a missing-reviewer finding without bootstrapping. Flow B CI setup remains an explicit opt-in delegated to upstream. Invocation errors never block, completed-review critical findings still follow the Final Review contract, and all install/auth/wizard details defer to upstream consent flows.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 24.6 KB |
| SPEC.md | markdown | 32.5 KB |
| addon.json | config | 302 B |
| templates/INTEGRATION.md | markdown | 17.9 KB |
SPEC.md
View on GitHub# SPEC.md — AI Diff Reviewer Addon (Normative)
## Abstract
This document is the **normative specification** of the DeepWorkPlan **AI Diff
Reviewer addon**: a capability — **required in its local form since standard
2.3.0, optional in its CI form** — that connects an AI-first repository to
the **AI Diff Reviewer** (`DailybotHQ/ai-diff-reviewer`, marketplace listing
"AI Diff Reviewer", pinned **v3.3.14**, moving `@v3` for workflows) so DWP work — the mandatory
security pass of the mandatory **Final Review** — is augmented with a structured local review
(verdict + findings table + severity), and (in **Flow B — dual-surface**,
optionally) every pull request to the target repo is gated by a CI-side
review Action fed by the same prompt bytes as the local pass — methodology
and severity parity, not identical findings. It defines the
**two officially-supported adoption flows** (§3), **what the addon
installs/configures** (local review required, CI surface opt-in, §4), how it **defers authentication and
wizard orchestration** to the upstream skill's own consent flows (§5), how
the **security-pass augmentation** and the optional **`apply-review` /
`address-review` post-CI companions** are wired into DWP execution (§6), the **never-block**
rule (§7), the **reconcile-don't-clobber** behavior (§8), the **validation
checklist** (§9), and the **archetype compatibility** notes (§10).
The addon is governed by [`../README.md`](../README.md) and
[`spec/ADDONS.md`](../../spec/ADDONS.md) §6.5: its **local review is part of
baseline conformance** for repositories declaring standard 2.3.0 or newer; its
CI surface is never required.
## Status of This Document
| Field | Value |
|-------|-------|
| **Version** | 3.0.0 |
| **Status** | Stable |
| **Companions** | `SKILL.md`, `templates/INTEGRATION.md`, `../README.md`, `spec/ADDONS.md`, `../../create/SKILL.md`, `../../guide/authoring.md` §5.4 |
| **License** | MIT |
| **Upstream reference** | `DailybotHQ/ai-diff-reviewer` v3.3.14 (marketplace: "AI Diff Reviewer"); workflows pin the moving `@v3` |
## 1. Conventions
The RFC 2119 keywords (**MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**,
**MAY**, **OPTIONAL**) are interpreted as in
[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
Throughout, the **upstream skill** is the vendored coding-agent skill
([`DailybotHQ/ai-diff-reviewer`](https://github.com/DailybotHQ/ai-diff-reviewer)),
a **router with six coordinated sub-skills**:
1. **Parent default flow** — run the local review on the current branch.
2. **`generate-extension`** — author repo-tailored `.review/extension.md`.
3. **`setup`** — install the CI workflow (also the reference manual for every
`action.yml` input via `setup/reference.md`).
4. **`open-pr`** — draft the PR title + body from the diff.
5. **`apply-review`** (included since v1.7.0) — read the CI review on the current
branch's PR and walk through findings per-finding (apply / defer / skip)
with explicit consent. Read-only by default; edits require per-finding
yes; never commits or pushes.
6. **`address-review`** (new in v3.2.1) — the one-invocation loop: find the
branch's open PR(s), check the review is fresh for the current head
(marker SHA or the `review-output/3.0` artifact), present the findings
with an apply / defer / skip plan, then — on one yes — apply, commit
(small Conventional Commits batches), push, and re-arm the reviewer the
way the repo triggers it (label-gated → toggle the label off/on or add
it; push-triggered → confirm the new run; no workflow → offer the local
review). Unlike `apply-review` it commits and pushes — that is the
loop's point.
The **CI Action** is the GitHub Marketplace listing "AI Diff Reviewer"
([`DailybotHQ/ai-diff-reviewer@v3`](https://github.com/marketplace/actions/ai-diff-reviewer)),
same repository as the skill. The skill's `prompt.md` is **byte-identical**
to the Action's shipped `prompts/default.md` at the same tag (enforced by
upstream CI's `Skills — prompt-sync invariant` job).
---
## 2. Vendor-Neutral Guardrail (the rule that frames everything)
- The **local review is part of the DeepWorkPlan baseline** since standard
2.3.0: `onboard` **MUST** install the vendored skill and bootstrap an
extension file (Phase 7a), a targeted harness upgrade **MUST** reconcile
both when missing, and the Final Review's security pass **MUST** run the
local review (§6.1). A repository declaring standard 2.3.0 or newer without
the vendored skill and an extension file is **not** conformant; `verify`
reports the gap as a failure (as a harness-version finding for a legacy
repository).
- The **CI surface (Flow B) MUST remain opt-in**: never installed unrequested,
never the default, never a precondition of any DWP flow.
- What stays vendor-neutral: the reviewer is an MIT-licensed, tag-pinned skill
executed by the developer's own coding agent. DWP **MUST NOT** require a
commercial service, a CI provider or a provider secret for any of
create / execute / refine / resume / status / verify / onboard to succeed.
- Since upstream v2.1.0 the runner and the backend are **separate inputs** —
`provider` names who runs the review loop, `api-base` names where the model
lives — so the same local review can run against any compatible endpoint.
That strengthens this guardrail rather than changing it: the choice of
backend is the developer's, and DWP still requires none of them.
- A developer **MAY** decline the local reviewer; the decline **MUST** be
recorded as a declared exception in `AGENTS.md` and in the onboarding
report, and the repository is reported as non-conformant on that point until
the reviewer is installed. Nothing else in the baseline changes.
---
## 3. Two Supported Adoption Flows
The upstream skill (pinned v3.3.14; the moving `@v3` for workflows) defines two flows explicitly. This addon applies
Flow A as the baseline and **MUST** offer Flow B as an explicit opt-in.
### 3.1 Flow A — local-only
- Vendored skill installed; the CI Action is **NOT** installed.
- Sub-skills used: **parent default flow** (security-pass augmentation) +
**`generate-extension` (required)** + optionally `open-pr`.
- Extension requirement: addon onboarding **MUST NOT** complete Flow A
without an extension file at a recognized path (or an explicit
`.review/.skip-bootstrap` opt-out, which means the local SR pass will not
fire). Skill-only install is incomplete for SR detection (§6.1).
- Sub-skills skipped: `setup` (would install the workflow, opting the repo
into Flow B against the developer's intent), `apply-review` and
`address-review` (no CI review posts back to any PR without the Action
installed — neither has anything to consume in Flow A).
- Suitable for: personal repos, experimental repos, or teams not (yet) ready
for automated PR review.
### 3.2 Flow B — dual-surface
- Vendored skill installed + `setup` sub-skill runs the wizard to write
`.github/workflows/pr-review.yml` referencing `.review/extension.md`.
- Sub-skills used: **all six** — parent + `generate-extension` + `setup` +
`open-pr` + `apply-review` + `address-review`.
- Suitable for: team repos, production-facing repos, and anything where an
automated PR merge gate is wanted.
### 3.3 Consent-time rules
- The addon **MUST** apply Flow A (the baseline) and offer Flow B at consent
time. It **MUST NOT** default to Flow B or install the CI workflow
unrequested.
- When the developer's signal about Flow B is ambiguous, the addon **MUST**
ask or stay on Flow A; it **MUST NOT** infer Flow B. The ambiguity
resolution mirrors the upstream skill's own policy: unrelated
workflows (CI tests, deploy pipelines, dependency bots) are **NOT**
evidence of Flow B — only an existing ai-diff-reviewer workflow is.
- The addon **SHOULD** surface the concrete Flow-A-vs-B tradeoff at consent
time: token-cost predictability (Flow A: only when the developer asks) vs
merge-gate enforcement (Flow B: every labeled PR).
- The recorded flow decision **SHOULD** be documented in the target repo's
`AGENTS.md` so future maintainers see it.
---
## 4. What the Addon Installs / Configures (local review REQUIRED, CI surface OPT-IN)
The addon installs or configures the following — §4.1 and §4.2 under the
onboarding consent (required, §2), §4.3 and §4.5 only on explicit Flow B
acceptance — each reconciled if already present (§8):
### 4.1 The upstream skill (both flows)
- The addon **MUST** install the vendored skill (the only supported install
path) unless the developer recorded a declared exception (§2).
Supported install method:
- `npx --yes skills add https://github.com/DailybotHQ/ai-diff-reviewer/tree/v3.3.14 --skill ai-diff-reviewer -y`
(**tag-pinned**; both flags are required — `--yes` covers npm's own "Ok to
proceed?" prompt; the subcommand `-y` covers the `skills` CLI's own "Which
agents do you want to install to?" picker, which hangs in non-TTY without
it — upstream fixed this bug in v1.7.0. Pin the current published tag at
install time (here `@v3.3.14`); the moving `@v3` is the documented default
pin for CI workflows. The pin is what makes the install verifiable and
the local↔CI parity guarantee exact.)
- Bump to the latest published tag: `npx --yes skills update ai-diff-reviewer -y`.
- The vendored skill lands at `.agents/skills/ai-diff-reviewer/`. Its
source + content hash are recorded in `skills-lock.json` for reproducible
restores.
- The addon **MUST NOT** substitute a one-line remote-installer pipe (any
variant of "fetch from the network and execute in one command") — that
pattern is unverifiable at the reader's terminal and is flagged as a
critical delivery-vector risk by every mainstream security auditor (Snyk
rule E005, Socket W012).
### 4.2 Repo-tailored `.review/extension.md` (both flows)
- The addon **MUST** ensure an extension file exists (or an explicit
`.review/.skip-bootstrap` opt-out is recorded) **before** finishing
onboarding. Prefer handing off to the upstream `generate-extension`
sub-skill (≥12 tool-call Discovery followed by a ~100-line file of
concrete overrides). This is the primary customization surface — where
consumers encode their own severity rules and "don't comment on" scopes.
Without an extension, security-pass detection (§6.1) fails and the
advertised local pass never runs.
- The addon **MUST** honor the upstream's three-path precedence when
detecting an existing extension file (first match wins):
1. `.review/extension.md` (recommended, runtime-agnostic).
2. `.github/ai-diff-reviewer/extension.md` (fallback for teams that
prefer `.github/` sibling to workflow files).
3. `.github/ai-pr-reviewer/extension.md` (pre-v1.5 back-compat, still
recognized by upstream).
- The addon **MUST NOT** invent a third location. When writing a new file,
the addon **SHOULD** use `.review/extension.md` (runtime-agnostic).
- The addon **MUST** respect the `.review/.skip-bootstrap` opt-out marker
(a tracked 0-byte file created when a developer previously answered
"never" to upstream's bootstrap offer). When that marker is present, the
addon **MUST NOT** bootstrap during onboarding or during later `execute`
the Final Review's security pass — document that the local augmentation stays inactive
until the marker is removed and an extension is created.
- Mid-plan `execute` **MUST NOT** surprise-bootstrap an extension file as a
side effect of the Final Review (aligns with `execute/SKILL.md`).
### 4.3 CI workflow `pr-review.yml` (Flow B only)
- When the developer chose Flow B, the addon **MUST** hand off to the
upstream `setup` sub-skill's 6-question wizard rather than hand-rolling
the workflow file. The wizard produces `.github/workflows/pr-review.yml`
adapted to the consumer's answers (runner and backend / strictness /
trigger mode / external-contributor policy / PR-description mode /
complexity labels). It can scaffold the v3 topology — a single review
with the verifier and risk-tiered budgets on by default, or the RFC-04
ensemble matrix (`mode: emit` read-only legs + one `mode: aggregate`
job); consumers on pre-v3 workflows keep working.
- The workflow **MUST** pin the upstream Action to the **v3** major-line tag
(`DailybotHQ/ai-diff-reviewer@v3`) so patch-level fixes flow automatically.
Pinning to a frozen tag (`@v3.x.y`) is also acceptable — parity with the
vendored skill's version is what makes local ≡ CI worth it. New installs
**MUST NOT** pin `@v1`/`@v2`; existing `@v2` pins keep working (frozen
maintenance line on `release/v2`, six months of security/catalog fixes).
- The workflow **SHOULD** enable the emergency-bypass input
`skip-review-label: skip-ai-review` (opt-in; empty means the feature is
OFF). Document that anyone who can apply that label can bypass the LLM
review — protect it with a repository ruleset when the AI review is a
merge gate. This is distinct from the IAR escape label
(`iteration-escape-label`, default `full-review-please`: one full review,
not a skip).
- CI reviews run **Iteration-Aware Review (IAR)** by default
(`convergence-policy: first-pass-exhaustive`). Local skill reviews remain
a full pass (no IAR dedup). Soften "local ≡ CI" claims accordingly —
shared `prompt.md` + extension still align methodology/severity (the
prompt-sync byte-identity holds at the same tag); round 2+ CI may be
shorter, and since v3 the budget follows the change's deterministic risk
tier (`budget-profile: auto`, 8/20/30/40 turns; a no-code-change push
runs a verifier-only round). `budget-profile: fixed` restores the
pre-v3 constants during the transition.
- Follow-up rounds review the **actual new diff** and carry outstanding
findings forward. `prior-findings-resolution` defaults to **`advisory`**:
a model's `resolved` verdict is reported, but the finding keeps gating
until a maintainer resolves the thread. Since v3 (BC-08), retiring a
prior finding requires re-reading the finding's anchor at the new head —
an edited file alone no longer retires anything. When the anchor re-read
corroborates the fix on a `collapse-previous`-minimized thread, the
finding retires so a stuck PR can go green. Opting into `verified`
restores runtime-corroborated auto-resolution. The addon **MUST NOT**
assume a model's own "resolved" claim retires a finding on a live thread
— under the default it does not, and a Final Review reading a CI round
treats an unresolved live thread as still open.
- The addon **MUST NOT** duplicate the wizard, the input reference manual
([`setup/reference.md`](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/skills/ai-diff-reviewer/setup/reference.md)),
or the workflow shape into its own templates. `templates/INTEGRATION.md`
provides a minimal fallback shape when the developer wants to skip the
wizard; the wizard is the primary path.
### 4.4 Documentation notes in AGENTS.md (both flows)
- The addon **SHOULD** append a short section to the target repo's
`AGENTS.md` documenting:
- Which flow was chosen (A or B) and why.
- The Final Review security-pass augmentation (both flows).
- (Flow B) the `pr-review.yml` behavior, the provider-secret requirement,
the label workflow (`ready` / `pr-reviewed` / optional `skip-ai-review`),
the `AI review gate` branch-protection target, and the `apply-review`
post-CI walkthrough companion.
- The section is short-form; the full detail lives in the vendored skill's
own `SKILL.md` (which any agent already reads).
### 4.5 Provider secret documentation (Flow B only)
- The addon **MUST** point the maintainer at the CI provider secret setup
(typical: `CURSOR_API_KEY` for the Cursor provider): Settings > Secrets
and variables > Actions > New repository secret. The addon **MUST NOT**
prompt for or store the secret itself.
---
## 5. Deferred Authentication and Wizard Handoff
- The addon **MUST** defer all authentication and workflow authoring to the
upstream skill's own flows (`setup/SKILL.md`, `setup/reference.md`).
- The addon **MUST NOT** prompt for API keys, MUST NOT bypass or weaken any
upstream consent flow, and **MUST NOT** store any credential in any file
it creates.
- The addon **MUST NOT** reimplement the `setup` wizard, the `open-pr`
Conventional-Commits inference, the `generate-extension` Discovery, the
`apply-review` walkthrough, or the review formatting — every one of these
belongs to the upstream skill; the addon points at them.
- If the developer declines any part of the setup, the addon **MUST** skip
that part and continue — installation issues **MUST NOT** block the
primary work (§7).
---
## 6. Integration Points into DWP Execution
This is the "why": when present, the **security pass** of the mandatory
**Final Review** in every DWP plan gets a structured local review pass, and in Flow B a
developer-invoked companion sub-skill closes the loop on any post-push CI
review.
### 6.1 Augment the Final Review's security pass (both flows — MUST, with honest degradation)
The addon **MUST** wire an additive step into the DWP `create` sub-skill's
`{N}.task_final_review.md` template's security pass. When the addon is installed
(detected by `.agents/skills/ai-diff-reviewer/` present + an extension file
at one of the three recognized paths from §4.2), the Final Review's security pass gains
an additional post-existing-checks step:
1. Invoke the upstream **parent default flow** ("Review my current branch").
2. Capture the reviewer's output: **verdict + findings table + per-finding
body + notes + recommendation** (the parity contract from the upstream
skill's Step 4).
3. Append the output to `analysis_results/SECURITY_REVIEW.md` under a
dedicated `## AI Diff Reviewer local review` heading — so a reader can
see the manual SR findings and the AI-augmented findings side by side.
4. Severity handling: since v3 (BC-07) a `critical` finding means a
**verified** critical — the verifier (default `on`; `verifier-model`
resolves the backend's `economy` alias) confirmed it with a second,
short, code-grounded call. Verified criticals follow the existing SR
contract and block completion until fixed or explicitly accepted;
unverified critical claims arrive as annotated warnings — visible and
non-blocking unless `strict-unverified-criticals: true`. `warning` and
`info` findings are appended and reported but do not block.
5. **Incomplete review — a fourth state, distinct from a clean pass
(upstream v2.2.0).** A run that started and exited **without writing a
findings file** is an **incomplete review**, not a completed pass with no
findings. Upstream posts it as an explicit incomplete review: every
blocking strictness fails it, the reviewed label is not stamped, and no
open finding is retired by that round. The security pass **MUST** treat it
the same way — record it in `SECURITY_REVIEW.md` as an incomplete review,
**MUST NOT** count it as evidence that the diff is clean, and **MUST NOT**
close the Final Review on it. Re-run once; if it recurs, carry it into the
completion report as an open finding. Under v3 (BC-04) the same red-gate
treatment covers every unfinished review: a run stopped at its turn cap
posts `status: incomplete`, a wall-clock-capped run posts `timeout`, and
both fail blocking strictness — an unfinished review is never counted as
a clean pass. The distinction is load-bearing:
without it, "no findings" cannot be told apart from "never looked", and a
plan could close on a review that did not happen.
- The step is **MUST**, with honest degradation: when the vendored skill or
the extension file is absent, the security pass **MUST** record a `local
reviewer not installed` finding in `SECURITY_REVIEW.md` and carry it into
the completion report. Installation is an onboarding action; the Final
Review **MUST NOT** surprise-bootstrap a missing piece. A coding-agent /
upstream-skill invocation error of a review that could start follows §7.
Do **not** treat an unset CI provider secret as an invocation skip — that
secret is Flow B CI/gate only. Once a local review **did** run, severity
handling above (§6.1 item 4) still applies.
- The augmentation is **additive**. The Final Review's own manual security
reasoning is preserved. Every new 2.3.0 Final Review template includes this
local-review step; when the reviewer is absent, the step records its missing-
reviewer finding instead of being omitted. Legacy plans retain their own
recorded shape.
- **Legacy plans.** A plan created under the pre-2.3.0 lifecycle carries a
separate `{N-2}.task_security_review.md`. The addon augments *that* task in
such a plan — same additive step, same severity contract — because a plan is
always executed under its own recorded shape and is never silently migrated.
### 6.2 CI merge gate (Flow B only)
- The Flow B workflow is separate from any single plan; it applies going
forward to every PR to the repo's default branch when the maintainer
applies the configured label (default: `ready`).
- The `AI review gate` job is stable-named (chosen by the upstream `setup`
wizard) for branch protection.
- **Skipped ≠ Failed.** A PR without the trigger label reports the gate as
Skipped (green-adjacent grey), which the branch-protection rule treats as
passing. This is the designed idle behavior — MUST NOT be interpreted as
a bug. Under v3 (BC-04), label/author scope skips are the only
non-blocking skips — an `incomplete` or `timeout` review is red under
blocking strictness.
### 6.3 Post-CI review companions — `apply-review` / `address-review` (Flow B only, OPTIONAL)
- When a plan's PR has been pushed and CI has posted its review, the
developer **MAY** invoke the upstream `apply-review` sub-skill from within
the same DWP `execute` session to walk through CI findings per-finding
(apply / defer / skip) with explicit per-finding consent.
- `apply-review` is **read-only by default**. Source-file edits require an
explicit yes per finding. It **never commits and never pushes** — commit +
push remains the developer's judgment call.
- The `address-review` sub-skill (new in v3.2.1) is the one-invocation
alternative with the same availability rules — MAY-invoke, never a plan
task — but it **commits and pushes**: it finds the branch's open PR(s),
checks the review is fresh for the current head, presents the findings
with an apply / defer / skip plan, then on one yes applies, commits
(small Conventional Commits batches), pushes, and re-arms the reviewer
adaptively (label-gated → toggle the label off/on, or add it when
missing; push-triggered → confirm the new run started; no reviewer
workflow → says so and offers the local review). The never-block rule
(§7) and the mandatory-final-task boundary apply identically.
- Multi-leg awareness: if consumers change the workflow to a matrix (e.g.
an RFC-04 ensemble of `mode: emit` legs plus one `mode: aggregate` job),
`apply-review` attributes each finding to its leg and surfaces cross-leg
consensus automatically (BC-09); on aggregated reviews the companions
read the aggregate document and the `ai-pr-reviewer-aggregate` marker.
- The addon **MUST** describe both companions in the target repo's docs as
*available options* during `execute` — never as mandatory extra tasks.
The addon **MUST NOT** materialize `apply-review` or `address-review` as
a plan task file — doing so would violate the mandatory-final-task rule
(a plan ends with the single Final Review, and nothing may follow it) and
turn a developer-invoked convenience into a scheduled plan step.
- A review body that says `Recommendation: approve`
is **not** evidence the check passed. `apply-review` **MUST** read the
tracking marker's Highest severity / Strictness gate / Check status
block first — the runtime rewrites a model `approve` to
`request-changes` whenever the gate is failing.
### 6.4 Structured output — the machine path (Flow B, v3)
- Automation wired by consumers or agents **SHOULD** read the structured
output instead of scraping review bodies: the `review-output/3.0`
document (`.aiprr/review-output.json`, uploaded as the
`ai-diff-reviewer-<head12>-<provider>-<kind>-<model>` artifact) carries
the run record, the change inventory, findings with typed evidence and
verification results, refuted findings, the prior-findings ledger, the
generated summary, and the gate (BC-11). The step outputs
`structured-output-path` / `-sha256` / `-artifact` locate it; the
tracking marker + threads remain the human fallback.
---
## 7. Never-Block Rule (mandatory)
Soft-fail applies to **invocation** of the local review pass only — not to
the Final Review's gate results after a review completed. Post-run severity
is governed by §6.1 (item 4): **verified** `critical` findings block the
Final Review's completion until fixed or explicitly accepted; unverified
critical claims are annotated warnings (BC-07).
- **Local augmentation — invocation soft-fail (Flow A and Flow B):** if the
network is **down** or any upstream skill invocation **errors**, the
addon's wired local-review step **MUST**: warn briefly once, record the
failed invocation in `SECURITY_REVIEW.md`, continue the primary task,
**not** retry automatically, and **not** enter a diagnostic loop. An
**absent** skill or extension file is not an invocation failure: it is
handled by §6.1 (recorded finding; installation is onboarding-only), never by
a silent skip. This mirrors the upstream skill's own
trust-boundary guarantees. The local parent default flow runs via the
coding agent and does **not** require a CI provider secret — an unset
`CURSOR_API_KEY` (or other provider secret) **MUST NOT** suppress the
local security pass.
- **Local augmentation — after a review ran:** open/`critical` findings
from that pass **MUST** follow §6.1. Agents **MUST NOT** mark the Final
Review `[x]` while those criticals remain unfixed and unaccepted. §7 does
**not** override that gate.
- **Local augmentation — a review that produced no findings file is
*incomplete*, not soft-failed.** Soft-fail covers an invocation that
**errored**; it does **not** cover a run that exited cleanly without
writing findings. That case is §6.1 item 5: recorded as an incomplete
review, never counted as a clean pass, never a reason to close the Final
Review. Three states, three different handlings — absent reviewer (§6.1
degradation), errored invocation (soft-fail here), incomplete review
(§6.1 item 5) — and none of them is "the diff is clean".
- **Flow B CI / gate only:** when the dual-surface workflow is installed,
document that the provider secret MUST be set for the CI Action to run;
warn maintainers when it is unset. That warning **MUST NOT** skip or
weaken the local SR augmentation.
- Plan execution **MUST** proceed when the local review was **skipped or
errored** at invocation (soft-fail above). Plan execution **MUST NOT**
treat "review ran with open criticals" as an invocation skip.
- The CI merge gate (Flow B) **MUST NOT** block merges when the trigger
label is not applied — Skipped, not Failed. This is enforced by the
upstream `setup` wizard's default output.
---
## 8. Reconcile, Don't Clobber
- The addon **MUST** detect existing setup before acting: an already-vendored
skill at `.agents/skills/ai-diff-reviewer/`, an existing extension file at
any of the three recognized paths, an existing `pr-review.yml` or any
workflow with `uses: DailybotHQ/ai-diff-reviewer` (or the pre-rename
`DailybotHQ/ai-pr-reviewer`), a `.review/.skip-bootstrap` opt-out marker,
or provider-secret documentation.
- Where a piece already exists, the addon **MUST** preserve it and only
fill gaps.
- **Migration constraint.** If an extension file exists at the fallback
path (`.github/ai-diff-reviewer/extension.md`) or the back-compat path
(`.github/ai-pr-reviewer/extension.md`), the addon **MUST NOT** migrate
it silently to the recommended `.review/extension.md` — ask.
- Any destructive change to an existing file **MUST** be approved by the
user first (`AGENT_PROTOCOL.md`); the addon **MUST** record what it
changed.
---
## 9. Conformance + Validation Step
A repo is **conformant to this addon** when **all** hold (after acceptance):
1. The vendored skill is installed at `.agents/skills/ai-diff-reviewer/`
with the version invariant asserted against `skills-lock.json`, **or**
the addon recorded why it could not install here (sandbox/CI, or a
declared exception per §2) without failing onboarding — a recorded gap,
never a silent one.
2. An extension file is present at one of the three recognized paths (or
the developer explicitly opted out via `.review/.skip-bootstrap`).
3. Authentication was **deferred** to the upstream skill's own consent flow
— no API-key prompting and **no credential** written by this addon.
4. The chosen flow (A or B) is recorded in `AGENTS.md` (or equivalent
docs), and the DWP execution docs describe the security-pass
local review as **required with honest degradation**: a missing skill or
extension is a recorded finding and installation remains onboarding-only
(§6.1), invocation errors soft-fail (§7); `critical` findings from a
**completed** pass still follow the SR contract (§6.1 / §7).
5. (Flow B only) `.github/workflows/pr-review.yml` exists with the upstream
Action pinned to `@v3` (or a specific tag), the stable-named gate job
is present for branch protection, the provider secret is documented in
AGENTS.md, and the label-gate + author-association policies match what
the maintainer chose during the `setup` wizard.
6. Existing vendored-skill / extension-file / workflow files were
**reconciled**, not clobbered.
7. The vendor-neutral guardrail holds (§2): nothing in the repo implies DWP
requires a commercial service, CI provider or secret; the CI surface is
documented as optional.
8. No one-line remote-installer / fetch-and-execute install path was
recommended anywhere in the addon.
---
## 10. Compatibility
### 10.1 Individual repo archetype
- Standard use case. Both flows apply directly. The security-pass
augmentation wires into the repo's own DWP plans.
### 10.2 Orchestrator hub archetype
- Orchestrator hubs typically install this addon **per sub-repo**, not on
the hub itself. Each sub-repo picks its own flow (some sub-repos may
choose Flow A; others may choose Flow B).
- The hub's own workflows MAY or MAY NOT use the AI Diff Reviewer
independently. The addon does not prescribe hub behavior.
- Child DWPs materialized inside sub-repos gain the SR augmentation from
each sub-repo's own installation (or don't, if the sub-repo declined
the addon) — the hub-level plan does not need to know.
### 10.3 v2 → v3 for existing addon installs
- Nothing breaks for `@v2` pins: the v2 line is frozen on `release/v2`
with six months of security/catalog maintenance. Adopting v3 is
`npx --yes skills update ai-diff-reviewer -y` plus, optionally, a re-run
of the upstream `setup` wizard; the `.review/extension.md` file carries
over unchanged.
- Behavior deltas to communicate to developers (the must-change rows of
the upstream `docs/MIGRATION_v3.md`): BC-04 (an `incomplete`/`timeout`
review is red under blocking strictness), BC-07 (a `critical` publishes
— and gates — only when the verifier confirms it;
`strict-unverified-criticals` restores claim-based gating), and BC-13
(risk-tiered budgets; `budget-profile: fixed` restores the pre-v3
constants). The latter inputs are one-minor-cycle transition knobs.
---
## 11. References
- [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
- `SKILL.md` (the onboarding hook + flow), `templates/INTEGRATION.md` (reasoning aid)
- `../README.md` (addon mechanism), [`../../spec/ADDONS.md`](../../spec/ADDONS.md) (concept + pointer)
- Upstream skill: [`DailybotHQ/ai-diff-reviewer`](https://github.com/DailybotHQ/ai-diff-reviewer)
— `skills/ai-diff-reviewer/SKILL.md` (documented pin **v3.3.14**; workflows
use the moving `@v3`), sub-skills: `generate-extension/SKILL.md`,
`setup/SKILL.md` +
[`setup/reference.md`](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/skills/ai-diff-reviewer/setup/reference.md),
`open-pr/SKILL.md`, `apply-review/SKILL.md`, `address-review/SKILL.md`.
- Marketplace listing: ["AI Diff Reviewer"](https://github.com/marketplace/actions/ai-diff-reviewer).
- [`../../create/SKILL.md`](../../create/SKILL.md) Step 4.4 (“Local review step (required)”) — where the Final Review local-review wiring is authored into every 2.3.0 plan.
- [`../../guide/authoring.md`](../../guide/authoring.md) §5.4 — the canonical security-discipline rules the Final Review's security pass applies.
---
*Part of the DeepWorkPlan methodology, MIT License, by [Dailybot](https://dailybot.com) / dailybotops.*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |