deepworkplan-addon-ai-diff-reviewer

DeepWorkPlan — AI Diff Reviewer Addon

Connect the target repo to the AI Diff Reviewer (GitHub repo DailybotHQ/ai-diff-reviewer, marketplace listing "AI Diff Reviewer", pinned v3.2.2, moving @v3 for workflows) so DWP work — the mandatory security pass of the mandatory Final Review — runs a structured local review (verdict + findings table + severity), and (in Flow B, optionally) every pull request is gated by the same review in CI. Since standard 2.3.0 the local review is part of the baseline: onboard installs it (Phase 7a), a targeted harness upgrade reconciles it, and every Final Review runs it. Only the CI surface is opt-in.

The rule that overrides everything: this addon DEFERS, it does not reinvent

The upstream DailybotHQ/ai-diff-reviewer skill (pinned v3.2.2; moving @v3 for workflows) already owns install, review methodology, the CI-workflow wizard, the extension-file authoring flow, the PR-body drafting flow, and the post-CI review walkthroughs — as six coordinated sub-skills (parent default flow, generate-extension, setup, open-pr, apply-review, address-review). This addon's job is narrow: (1) install the vendored skill, pinned, under the onboarding consent (a decline is a recorded declared exception), (2) apply Flow A (local-only) as the baseline and offer Flow B (dual-surface) as an explicit opt-in — never install the CI surface unrequested, (3) if Flow B, defer to the upstream setup sub-skill for the CI workflow, and (4) wire the parent default flow into DWP create/execute so the Final Review's security pass is augmented with a local review pass, plus (Flow B only) surface apply-review / address-review as available companions for post-CI walkthrough. It MUST NOT duplicate, bypass, or weaken any upstream consent, auth, wizard, or review flow — it points at them. (Normative source: SPEC.md.)

Positioning guardrail (read before anything)

The local review is part of the DeepWorkPlan baseline since standard 2.3.0 (spec/ADDONS.md §6.5): every onboarded repository gets the vendored skill and a repo-tailored extension file, and every Final Review runs the local review over the plan's accumulated change set. What stays vendor-neutral, MIT and agent-agnostic is the boundary that matters: the reviewer is a tag-pinned skill executed by the developer's own coding agent — no commercial service, no CI provider and no provider secret is ever required by any DWP flow. The CI surface (Flow B) is the only piece that touches a provider, and it is offered, never assumed. A developer may decline the local reviewer; the decline is recorded as a declared exception in AGENTS.md and verify reports the repository as non-conformant on that point until it is installed. A repo with zero optional addons is fully conformant.

Two officially-supported adoption flows

The upstream skill (v3.2.2, the documented pin; moving @v3 for workflows) ships a router plus six sub-skills (review, generate-extension, setup, open-pr, apply-review, address-review). This addon applies Flow A as the baseline every onboarded repo gets and offers Flow B as an explicit opt-in; it MUST NOT install the CI surface unrequested.

Flow	Use when	Sub-skills used	Sub-skills skipped
A — local-only	Personal repos, experimental repos, or teams not (yet) ready for automated PR review. The vendored skill runs locally; the CI Action is NOT installed.	parent default flow (security-pass augmentation) + generate-extension (required for SR detection) + optionally open-pr	setup (would install the workflow), apply-review and address-review (nothing to apply back — no CI review posts)
B — dual-surface	Team repos, production-facing repos, and anything where automated PR review is wanted. Skill + CI Action, both wired to the same .review/extension.md for byte-identical parity. Recommended for team repos.	All six: parent + generate-extension + setup + open-pr + apply-review + address-review	Nothing — all capabilities are used across the plan lifecycle

Parity guarantee (Flow B). The upstream skill's prompt.md is byte-identical to the Action's shipped prompts/default.md at the same release tag (enforced by the upstream Skills — prompt-sync invariant CI job). Pinning the same version on both surfaces aligns the review methodology, not identical findings; model behavior and CI iteration deduplication can differ. When setup wires prompt-extension-file: .review/extension.md, the CI Action reads the same file your local agent uses → same base prompt + same extension = the same methodology and severity model, locally and in CI.

Read these first (all relative inside the skill)

• SPEC.md — the normative (RFC-2119) contract: two flows, what is installed (local review required since 2.3.0; CI surface opt-in), how auth is deferred, how the security-pass augmentation is wired, the optional apply-review companion, the never-block rule, and the vendor-neutral guardrail.
• templates/INTEGRATION.md — reasoning guidance (NOT copy-paste): detect-if-already-installed, how to ask for the flow, how to wire the security-pass augmentation, and the consent / never-block rules.
• ../README.md — the addon mechanism (opt-in, reconcile-don't-clobber, contract).

When this runs

• From onboard Phase 7a — after the core AI-first scaffolding and before the optional addons of Phase 7b, onboard reads this SKILL and runs the flow below as a required step (the four optional addons — devcontainer / dailybot / dependency-upgrade / design-system — are offered afterwards).
• From the targeted harness upgrade (onboard Phase 0) — when a previously onboarded repository lacks the vendored skill or the extension file, the upgrade reconciles the missing piece.
• From execute — the Final Review's security pass runs the local review when installed, or records a missing-reviewer finding; it never installs.
• Directly — /deepworkplan-addon-ai-diff-reviewer on an already-onboarded repo to add the review integration.

Trust boundary (write scope)

allowed-tools includes write-capable Edit and Write. Exactly what this addon may write — and what it MUST NOT — is enumerated below. Skills.sh / Gen Agent Trust Hub treat allowed-tools as a trust boundary; this section is the human-readable contract for that field. Anything not listed here does not happen.

Reads (always allowed, no consent needed):

• Local files under the current git checkout via Read / Grep / Glob / Bash (detection only: existence of .agents/skills/ai-diff-reviewer/, extension-file paths, pr-review.yml, .review/.skip-bootstrap).
• Upstream sub-skill docs under .agents/skills/ai-diff-reviewer/** once installed (to hand off correctly).

Writes (only after explicit developer acceptance of the relevant step):

• Vendored skill install — via npx --yes skills add <repo>@<tag> … -y / npx --yes skills update … -y into .agents/skills/ai-diff-reviewer/ + skills-lock.json. Installs are tag-pinned (Step 1); never run without Step 1 consent.
• Extension file — hand off to upstream generate-extension (writes .review/extension.md or a consumer-chosen path). This addon itself does NOT invent severity rules; it only triggers the upstream sub-skill after the developer accepts the bootstrap offer.
• CI workflow (Flow B only) — hand off to upstream setup (writes .github/workflows/pr-review.yml and related labels). This addon itself does NOT hand-roll the workflow or invent provider secrets.
• AGENTS.md / docs notes (optional) — a short pointer that the addon is installed and which flow was chosen, only when the developer accepts a docs-update prompt. Reconcile; never clobber existing sections.
• Plan-time security-pass append — during execute, append the local review output under ## AI Diff Reviewer local review in analysis_results/SECURITY_REVIEW.md (plan working state, typically gitignored). Never rewrite the rest of that file.

It MUST NOT:

• Store, echo, or commit provider secrets (CURSOR_API_KEY, API tokens).
• Pipe a remote installer into a shell (any single-line fetch-and-execute variant).
• Install the CI workflow (Flow B) unrequested, or default to Flow B when the flow question is unanswered.
• Clobber an existing .review/extension.md, pr-review.yml, or vendored skill — reconcile gaps only.
• git commit / git push as part of the addon flow (those belong to the surrounding DWP execute / maintainer workflow).
• Edit source files under the consumer's application tree — review findings are applied (if at all) by the upstream apply-review / address-review sub-skills under their own consent contracts, not by this addon.

Supply-chain trust (what a "yes" actually installs)

This addon delegates to third-party artifacts, so the trust chain is stated explicitly rather than implied:

Artifact	Source	How it is verified
Vendored skill (six sub-skills)	DailybotHQ/ai-diff-reviewer at a published tag (documented pin v3.2.2)	skills CLI records source + content hash in the repo's skills-lock.json; a restore re-verifies the hash. Installs are consent-gated (Step 1) and always tag-pinned — never a moving branch.
CI Action (Flow B only)	DailybotHQ/ai-diff-reviewer GitHub Action, referenced by an explicitly chosen exact tag or its moving @v3 major line	Each Action release in the @v3 line ships a prompt.md byte-identical to the skill's at the matching skill tag — an upstream CI invariant. The skill side is pinned to an exact tag; the Action follows its major line, so reviews stay compatible while picking up patch fixes.
Extension file	Generated locally by generate-extension from the repo's own diff	Never downloaded; reviewed by the developer like any other tracked file.
Provider secret (Flow B only)	The maintainer's selected provider credential, configured through upstream setup	This addon never reads, stores, echoes, or commits provider secrets.

Nothing else is fetched. There is no telemetry, no post-install script, and no runtime download by this addon itself; the only network action it can prompt for is the consent-gated, tag-pinned skills add/skills update above.

The flow

Step 0 — Consent + choose the flow

1. Confirm consent. During onboard and the targeted upgrade, the Phase 0 consent covers this install: in trust mode proceed; in guided mode state what will be installed (the pinned skill tag and the extension file) and proceed unless the developer declines. A decline is recorded as a declared exception in AGENTS.md and in the onboarding report; it does not make the repository conformant — verify reports the gap until the reviewer is installed. Never install unpinned.

2. Local-only is automatic under onboarding authorization. Continue with the pinned local skill and extension without asking the developer to choose Flow A. Offer the optional CI surface separately; run upstream setup only after an explicit request or acceptance. An unanswered offer means Flow A, not a blocker. Existing CI configuration is preserved, not installed again.

3. Detect existing setup (reconcile-don't-clobber). Before installing anything, check what is already present (see templates/INTEGRATION.md):

   • Vendored skill already installed at .agents/skills/ai-diff-reviewer/?
   • Extension file at one of the three recognized paths (in precedence order): .review/extension.md > .github/ai-diff-reviewer/extension.md

     .github/ai-pr-reviewer/extension.md (pre-v1.5 back-compat)?

   • .review/.skip-bootstrap marker present (developer opted out of the bootstrap offer previously — respect it)?
   • .github/workflows/pr-review.yml or any workflow with uses: DailybotHQ/ai-diff-reviewer (or the pre-rename DailybotHQ/ai-pr-reviewer — the 301 redirect keeps old pins working)?
   • Provider secret documented anywhere (typical: CURSOR_API_KEY)?

   If a piece already exists, do not redo it — record it and only fill gaps.

Step 1 — Install the vendored skill (REQUIRED — covered by the onboarding consent)

Run the pinned install unless the developer explicitly declined in Step 0 (declared exception). Never run an unpinned installer.

• Vendored coding-agent skill (recommended — brings the six-sub-skill router and the byte-identical prompt parity guarantee; pinned v3.2.2; the moving @v3 is the documented default pin for CI workflows):
  • npx --yes skills add DailybotHQ/ai-diff-reviewer@v3.2.2 --skill ai-diff-reviewer -y (pinned to a published tag; vendors into .agents/skills/ai-diff-reviewer/ and records source + content hash in skills-lock.json; both --yes and -y are required — --yes covers npm's own prompt, 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 in v1.7.0).
  • Bump to the latest published tag with npx --yes skills update ai-diff-reviewer -y.

Do not reimplement the install, and never pipe a remote installer to a shell. The npx skills command is the supported, checksummed install path — it records the content hash in skills-lock.json for reproducible restores.

Step 1b — Bootstrap the extension file (REQUIRED for both flows)

Security-pass detection (SPEC §6.1 / create / execute) requires skill + an extension file at one of the three recognized paths. Do not finish addon onboarding without one — otherwise every later Final Review security pass records a local reviewer not installed finding instead of a review.

1. If an extension already exists at a recognized path → record it; do not clobber (and do not migrate fallback/back-compat paths silently — ask).
2. If .review/.skip-bootstrap is present → the developer previously opted out. Respect it: document that the local SR augmentation will not fire until they remove the marker and create an extension; do not surprise- bootstrap later during execute.
3. Otherwise → hand off to upstream generate-extension (or let the developer hand-write .review/extension.md) before proceeding to Step 2 / Step 3. Preferred handoff: "generate a .review/extension.md for this repo".

Mid-plan execute MUST NOT surprise-bootstrap an extension — that is an onboarding concern, not a side effect of the Final Review.

Step 2 — CI workflow install — DEFER to the upstream setup sub-skill (Flow B only)

Do not hand-roll .github/workflows/pr-review.yml, do not prompt for API keys, and do not store any credential. When the developer chose Flow B, hand off to the upstream setup sub-skill — its 6-question wizard produces a workflow tuned to the consumer's choices (runner and backend / strictness / trigger mode / external-contributor policy / PR-description mode / complexity labels), and setup/reference.md doubles as the reference manual for every action.yml input.

• Point at the vendored skill: .agents/skills/ai-diff-reviewer/setup/SKILL.md.
• Handoff phrase: "Set up AI Diff Reviewer for this repo" (or /ai-diff-reviewer-setup) — workflow + label bootstrap only. Step 1b already required the extension file for both flows; do not re-enter generate-extension here unless Step 1b was skipped (e.g. explicit .review/.skip-bootstrap opt-out and the developer later reversed it).
• Provider secret: the wizard tells the maintainer which secret to configure (typical: CURSOR_API_KEY for the Cursor provider). Maintainer sets it at Settings > Secrets and variables > Actions.

The addon MUST NOT reimplement the wizard. If the developer wants to skip the wizard, templates/INTEGRATION.md provides a fallback shape and points at the reference manual — but the wizard is the primary path.

Step 3 — Wire the security-pass augmentation into DWP execution

This is the integration value. Reasoning guidance is in templates/INTEGRATION.md — adapt it to the repo; do not copy verbatim.

• Add a short note to the repo's DWP execution docs (the generated AGENTS.md reporting section and/or docs/AI_AGENT_COLLAB.md) describing that the mandatory {N}.task_final_review.md template runs, as a required post-existing-checks step in its security pass:

  1. Local review augmentation (both flows) — invoke the upstream parent default flow ("Review my current branch"). Capture verdict + findings table + per-finding body + notes + recommendation. Append to analysis_results/SECURITY_REVIEW.md under a dedicated ## AI Diff Reviewer local review heading. Since v3 (BC-07) a critical finding means a verified critical — the verifier (default on) confirmed it with a second, 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 unless strict-unverified-criticals: true. A review with status: incomplete or timeout is not a clean pass under blocking strictness (BC-04). warning / info findings are appended and reported but do not block.

  2. Optional post-CI walkthrough companion (Flow B only) — after the plan's PR has been pushed and CI has reviewed it, the developer MAY invoke the upstream apply-review sub-skill from within the same execute session to walk through CI findings per-finding (apply / defer / skip) with explicit consent. apply-review is read-only by default; source-file edits require an explicit yes per finding; it never commits and never pushes. The address-review sub-skill (new in v3.1.1) is the one-invocation alternative: find the branch's open PR(s), check the review is fresh for the current head, present the findings, then on one yes apply, commit, push, and re-arm the reviewer (label-gated → toggle the label; push-triggered → confirm the new run; no workflow → offer the local review) — unlike apply-review it commits and pushes, and the never-block rule plus the no-plan-task boundary apply identically. When wiring automation, prefer the structured output (review-output/3.0; outputs structured-output-path / -sha256) over scraping review bodies. A body that says Recommendation: approve is not evidence the check passed — read the tracking marker's Highest severity / Strictness gate / Check status block first. These are surfaced as available options, not new plan task files — the addon MUST NOT insert an apply-review or address-review task into any plan.

• The local review is required, with honest degradation: it runs whenever the vendored skill is present and an extension file is detected. When either is missing, the security pass records a local reviewer not installed finding in SECURITY_REVIEW.md and carries it into the completion report. Installation is an onboarding action, not a Final Review side effect; mid-plan execute MUST NOT bootstrap the missing piece. It MUST NOT hard-stop create or execute; an invocation error of a review that could start is warn-once-record-and-continue (see SPEC §6.1 and §7). Do not skip the local pass because a CI provider secret is unset; that secret is Flow B CI / gate messaging only.

• The reviewer's .review/extension.md (repo-tailored via the upstream generate-extension sub-skill, either through the bootstrap offer or invoked explicitly) shapes what maps to which severity. This is the primary customization surface; consumers who want repo-specific review rules author them here.

• v6 plans — recording review states (no rubric fork). For a plan on the v6 records, the review's state is recorded as one asserted journal observation through shared/outcomes.py review with the closed grammar REVIEW: <state>[: <finding>] (state one of clean / critical / missing / error / incomplete). The failure semantics are the upstream skill's, preserved verbatim: critical blocks plan completion; missing / error / incomplete are never a clean pass. A review state never satisfies an acceptance criterion — reviewer cleanliness is not behavioral acceptance — and v6 adds no severity of its own; the upstream rubric and the extension file stay the only review customization surfaces.

Step 4 — Validate (SPEC §9 Validation)

Run the validation checklist and report: whether the vendored skill is present with the correct version, whether an extension file is present at one of the three recognized paths, whether (Flow B) the workflow file is present with the upstream Action pinned to @v3, whether the provider secret is documented in AGENTS.md, whether the stable-named gate job (if Flow B) is AI review gate for branch protection, and any deferred items. If nothing could be installed here (sandbox/CI), say why — do not silently skip, and do not fail the onboarding.

Failure-mode guardrails

• Required locally; invocation never blocking. A missing vendored skill or extension file is a recorded finding, never a silent skip and never a hard stop of the plan; installation is handled only by onboarding or an explicit addon invocation. A declined install is a recorded declared exception that verify keeps reporting. A local review invocation error is warn-once-record-and-continue. Once a local review ran, verified critical findings still block Final Review completion until fixed or explicitly accepted (BC-07; unverified critical claims arrive as annotated warnings), and an incomplete/timeout review is never a clean pass (BC-04) (SPEC §6.1 / §7). An unset CI provider secret does not skip the local security pass (Flow B CI/gate only).
• Defer to upstream. No wizard reimplementation, no review-methodology reimplementation, no apply-review/address-review reimplementation. Point at the vendored sub-skills.
• Verified install only. Never recommend piping a remote installer to a shell. Use npx --yes skills add <repo>@<tag> … -y — the tag pin plus skills-lock.json content-hash verification is what makes the install reproducible and auditable.
• Reconcile, don't clobber. An existing extension file, workflow, or vendored skill is preserved; only fill gaps. Never migrate a file at .github/ai-diff-reviewer/extension.md (or the back-compat .github/ai-pr-reviewer/extension.md) to .review/extension.md silently — ask.
• Vendor-neutral. The reviewer is an MIT, tag-pinned skill run by the developer's own agent; DWP never requires a commercial service, CI provider or secret. The optional CI surface is the only piece that touches a provider.
• Both flows are first-class. Flow A (local-only) is the baseline, not a degraded mode. Flow B is offered; the addon MUST NOT install it unrequested or default to it.