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", current v2.0.0) so DWP work — the mandatory Security Review final task — is augmented with a structured local review (verdict + findings table + severity), and (in Flow B, optionally) every pull request to the target repo is gated by a CI-side review Action pinned to the same tag for byte-identical parity. This is an opt-in addon; it is never required for a repo to be AI-first. Missing skill/extension or invocation errors never block the work; critical findings from a completed local review still follow the existing Security Review contract (block until fixed or explicitly accepted).
The rule that overrides everything: this addon DEFERS, it does not reinvent
The upstream DailybotHQ/ai-diff-reviewer skill (currently v2.0.0)
already owns install, review methodology, the CI-workflow wizard, the
extension-file authoring flow, the PR-body drafting flow, and the post-CI
apply-review walkthrough — as five coordinated sub-skills (parent default
flow, generate-extension, setup, open-pr, apply-review). This
addon's job is narrow: (1) offer to install the vendored skill through
its own consent flow, (2) ask whether the consumer wants Flow A
(local-only) or Flow B (dual-surface) — never guess, matching the upstream
skill's own ambiguity tie-break policy, (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 mandatory Security Review is
augmented with a local review pass, plus (Flow B only) surface apply-review
as an available companion 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 core DeepWorkPlan methodology has ZERO AI Diff Reviewer dependency. It
is vendor-neutral, MIT, and agent-agnostic. A repo with zero addons —
including this one — is fully conformant. This addon adds structured
code-review quality to DWP work for developers who want it; declining leaves
a fully AI-first repo. Never present the AI Diff Reviewer as a precondition
for DWP, and never auto-install it for everyone.
Two officially-supported adoption flows
The upstream skill (v2.0.0+) defines two flows and requires consumers to
pick explicitly. This addon MUST offer both at consent time and MUST NOT
default to either.
| 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 Review augmentation) + generate-extension (required for SR detection) + optionally open-pr |
setup (would install the workflow), apply-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 five: parent + generate-extension + setup + open-pr + apply-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 guarantees identical reviews.
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 = same review, locally and in CI.
Read these first (all relative inside the skill)
SPEC.md — the normative (RFC-2119) contract: two flows, what is
installed (all opt-in), how auth is deferred, how the Security Review
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 Review 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 7b — after the core AI-first scaffolding, onboard
offers this addon alongside devcontainer / dailybot / dependency-upgrade /
design-system; if accepted it reads this SKILL and runs the flow below.
- 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 Review 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).
- Auto-install for everyone 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 sub-skill under its
own per-finding consent contract, 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 (five sub-skills) |
DailybotHQ/ai-diff-reviewer at a published tag (current v2.0.0) |
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 its @v2 major line (exact-tag pinning is not how the Actions marketplace references actions) |
Each Action release in the @v2 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 own CURSOR_API_KEY, set in GitHub Settings |
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 + recommend-only-if-relevant + choose the flow
Confirm relevance. Offer this addon only when it makes sense: the
developer or team wants structured code-review quality on DWP work, or
explicitly asks for local pre-push review or PR merge-gating. In trust/auto
mode you MAY recommend it only on that signal — do not auto-install
for everyone. If the developer declines, stop cleanly; the repo stays
baseline-conformant.
Ask the flow question — do NOT guess. This matches upstream v2.0.0's
own ambiguity tie-break policy. Present both flows plainly:
This addon supports two adoption modes:
Flow A — local-only. Vendored skill + a repo-tailored extension
file (via generate-extension); no GitHub Actions changes. Best for
personal or experimental repos, or teams not (yet) ready for automated
PR review. Once both are present, the DWP Security Review is augmented
with a local review pass — skill alone is not enough.
Flow B — dual-surface. Skill + CI Action, both reading the same
.review/extension.md for byte-identical parity. Every PR to main
gets an AI review in CI, gated on a label of your choice (typical:
ready). Recommended for team repos.
Which flow?
If the signal is unclear, ask; never default to Flow B (installing the
workflow unrequested is a much bigger footprint than declining Flow B and
only using the local review).
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 — Offer the vendored skill install (OPT-IN, defer consent)
Present the install path and let the developer choose; never run an
installer without their explicit acceptance.
- Vendored coding-agent skill (recommended — brings the five-sub-skill
router and the byte-identical prompt parity guarantee; current v2.0.0):
npx --yes skills add DailybotHQ/ai-diff-reviewer@v2.0.0 --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 Review 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
Security Review will warn "install incomplete" and skip the local pass.
- If an extension already exists at a recognized path → record it; do not
clobber (and do not migrate fallback/back-compat paths silently — ask).
- 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.
- 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 Security Review side effect.
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 (provider / 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 Review 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, clearly-optional note to the repo's DWP execution docs (the
generated AGENTS.md reporting section and/or docs/AI_AGENT_COLLAB.md)
describing that when this addon is installed, the mandatory
{N-2}.task_security_review.md template gains an additional post-existing-checks step:
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. A critical finding
follows the existing SR contract — blocks completion until fixed or
explicitly accepted. warning / info findings are appended and
reported but do not block.
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. This is surfaced as an available
option, not a new plan task file — the addon MUST NOT insert an
apply-review task into any plan.
Every hook MUST be best-effort and conditional: the local Security
Review pass fires only when the vendored skill is present and an
extension file is detected, and it MUST NOT block create or
execute if the skill is absent, detection fails, or the local review
invocation errors — warn once and continue (see SPEC §7 Never-block).
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.
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 @v2, 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
- Never required; invocation never blocking. If declined — or if the
vendored skill is missing, detection fails, or the local review
invocation errors — stop/continue cleanly. The repo stays
baseline-conformant. Once a local review ran, open
critical
findings still block Security Review completion until fixed or
explicitly accepted (SPEC §6.1 / §7). An unset CI provider secret does
not skip the local Security Review pass (Flow B CI/gate only).
- Defer to upstream. No wizard reimplementation, no review-methodology
reimplementation, no apply-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. Never imply DWP needs the AI Diff Reviewer. This addon
is purely additive review quality.
- Both flows are first-class. Flow A (local-only) is a supported use
case, not a degraded mode. The addon MUST ask; MUST NOT default to Flow B.
1---2name: deepworkplan-addon-ai-diff-reviewer-43description: "Optional DeepWorkPlan addon that connects an AI-first repo to the AI Diff Reviewer (DailybotHQ/ai-diff-reviewer on GitHub, \"AI Diff Reviewer\" on the Marketplace, current v2.0.0) — installing (with consent) the vendored coding-agent skill (DailybotHQ/ai-diff-reviewer, five sub-skills — parent default flow, generate-extension, setup, open-pr, apply-review) and, if the developer picks Flow B (dual-surface), letting the upstream setup sub-skill write .github/workflows/pr-review.yml so every pull request to the target repo is reviewed in CI with byte-identical parity to the local review. Wires the mandatory DWP Security Review task to run the parent default flow (\"Review my current branch\") as an additive step producing verdict + findings table + severity, appended under a dedicated heading in analysis_results/SECURITY_REVIEW.md. In Flow B, also surfaces the upstream apply-review sub-skill as an OPTIONAL developer-invoked companion during execute for walking through CI-posted findings per-finding (apply / defer / skip) with explicit consent. Opt-in, never required, never blocks on missing skill/extension/invocation errors (completed-review critical findings still follow the Security Review contract), reconciles existing setups instead of clobbering them, defers all install/auth/wizard details to the upstream skill's own consent flows, and lets consumers pick Flow A (local-only) or Flow B (dual-surface) — never guesses, always asks. Use when the developer or team wants structured local review + optional CI merge gate on DWP work."4version: "2.17.0"5documentation_url: https://deepworkplan.com6user-invocable: true7allowed-tools: Bash, Read, Grep, Glob, Edit, Write8metadata:9 source: https://skillmd.com/skills/dailybothq/deepworkplan-addon-ai-diff-reviewer-410 openclaw:11 emoji: 🔍12 homepage: https://deepworkplan.com13 requires:14 anyBins:15 - git16 - gh17---1819# DeepWorkPlan — AI Diff Reviewer Addon2021Connect the target repo to the **[AI Diff Reviewer](https://github.com/DailybotHQ/ai-diff-reviewer)** (GitHub repo `DailybotHQ/ai-diff-reviewer`, marketplace listing **"AI Diff Reviewer"**, current **v2.0.0**) so DWP work — the mandatory **Security Review** final task — is augmented with a structured local review (verdict + findings table + severity), and (in Flow B, optionally) every pull request to the target repo is gated by a CI-side review Action pinned to the same tag for byte-identical parity. This is an **opt-in addon**; it is **never** required for a repo to be AI-first. Missing skill/extension or invocation errors **never block** the work; `critical` findings from a **completed** local review still follow the existing Security Review contract (block until fixed or explicitly accepted).2223> ## The rule that overrides everything: this addon DEFERS, it does not reinvent24>25> The upstream **`DailybotHQ/ai-diff-reviewer`** skill (currently **v2.0.0**)26> already owns install, review methodology, the CI-workflow wizard, the27> extension-file authoring flow, the PR-body drafting flow, and the post-CI28> apply-review walkthrough — as five coordinated sub-skills (parent default29> flow, `generate-extension`, `setup`, `open-pr`, `apply-review`). **This30> addon's job is narrow**: (1) **offer** to install the vendored skill through31> its own consent flow, (2) **ask** whether the consumer wants Flow A32> (local-only) or Flow B (dual-surface) — never guess, matching the upstream33> skill's own ambiguity tie-break policy, (3) if Flow B, defer to the34> upstream `setup` sub-skill for the CI workflow, and (4) **wire** the parent35> default flow into DWP `create`/`execute` so the mandatory Security Review is36> augmented with a local review pass, plus (Flow B only) surface `apply-review`37> as an available companion for post-CI walkthrough. It MUST NOT duplicate,38> bypass, or weaken any upstream consent, auth, wizard, or review flow — it39> points at them. (Normative source: [`SPEC.md`](SPEC.md).)4041## Positioning guardrail (read before anything)4243The **core DeepWorkPlan methodology has ZERO AI Diff Reviewer dependency.** It44is vendor-neutral, MIT, and agent-agnostic. A repo with **zero addons** —45including this one — is fully conformant. This addon adds *structured46code-review quality* to DWP work for developers who want it; declining leaves47a fully AI-first repo. Never present the AI Diff Reviewer as a precondition48for DWP, and never auto-install it for everyone.4950## Two officially-supported adoption flows5152The upstream skill (v2.0.0+) defines **two flows** and requires consumers to53pick explicitly. This addon MUST offer both at consent time and MUST NOT54default to either.5556| Flow | Use when | Sub-skills used | Sub-skills skipped |57|------|----------|-----------------|--------------------|58| **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 Review augmentation) + **`generate-extension` (required for SR detection)** + optionally `open-pr` | `setup` (would install the workflow), `apply-review` (nothing to apply back — no CI review posts) |59| **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 five: parent + `generate-extension` + `setup` + `open-pr` + `apply-review` | Nothing — all capabilities are used across the plan lifecycle |6061**Parity guarantee (Flow B).** The upstream skill's `prompt.md` is62**byte-identical** to the Action's shipped `prompts/default.md` at the same63release tag (enforced by the upstream `Skills — prompt-sync invariant` CI64job). Pinning the same version on both surfaces guarantees identical reviews.65When `setup` wires `prompt-extension-file: .review/extension.md`, the CI66Action reads the same file your local agent uses → same base prompt + same67extension = same review, locally and in CI.6869## Read these first (all relative inside the skill)7071- [`SPEC.md`](SPEC.md) — the normative (RFC-2119) contract: two flows, what is72 installed (all opt-in), how auth is deferred, how the Security Review73 augmentation is wired, the optional `apply-review` companion, the74 never-block rule, and the vendor-neutral guardrail.75- [`templates/INTEGRATION.md`](templates/INTEGRATION.md) — reasoning guidance76 (NOT copy-paste): detect-if-already-installed, how to ask for the flow, how77 to wire the Security Review augmentation, and the consent / never-block78 rules.79- `../README.md` — the addon mechanism (opt-in, reconcile-don't-clobber, contract).8081## When this runs8283- From **`onboard` Phase 7b** — after the core AI-first scaffolding, `onboard`84 offers this addon alongside devcontainer / dailybot / dependency-upgrade /85 design-system; if accepted it reads this SKILL and runs the flow below.86- **Directly** — `/deepworkplan-addon-ai-diff-reviewer` on an already-onboarded87 repo to add the review integration.8889## Trust boundary (write scope)9091`allowed-tools` includes write-capable `Edit` and `Write`. Exactly what this92addon may write — and what it MUST NOT — is enumerated below. Skills.sh / Gen93Agent Trust Hub treat `allowed-tools` as a trust boundary; this section is the94human-readable contract for that field. Anything not listed here does not95happen.9697**Reads (always allowed, no consent needed):**9899- Local files under the current git checkout via `Read` / `Grep` / `Glob` /100 `Bash` (detection only: existence of `.agents/skills/ai-diff-reviewer/`,101 extension-file paths, `pr-review.yml`, `.review/.skip-bootstrap`).102- Upstream sub-skill docs under `.agents/skills/ai-diff-reviewer/**` once103 installed (to hand off correctly).104105**Writes (only after explicit developer acceptance of the relevant step):**106107- **Vendored skill install** — via `npx --yes skills add <repo>@<tag> … -y` /108 `npx --yes skills update … -y` into `.agents/skills/ai-diff-reviewer/` +109 `skills-lock.json`. Installs are tag-pinned (Step 1); never run without110 Step 1 consent.111- **Extension file** — hand off to upstream `generate-extension` (writes112 `.review/extension.md` or a consumer-chosen path). This addon itself does113 NOT invent severity rules; it only triggers the upstream sub-skill after114 the developer accepts the bootstrap offer.115- **CI workflow (Flow B only)** — hand off to upstream `setup` (writes116 `.github/workflows/pr-review.yml` and related labels). This addon itself117 does NOT hand-roll the workflow or invent provider secrets.118- **AGENTS.md / docs notes (optional)** — a short pointer that the addon is119 installed and which flow was chosen, only when the developer accepts a120 docs-update prompt. Reconcile; never clobber existing sections.121- **Plan-time Security Review append** — during `execute`, append the local122 review output under `## AI Diff Reviewer local review` in123 `analysis_results/SECURITY_REVIEW.md` (plan working state, typically124 gitignored). Never rewrite the rest of that file.125126**It MUST NOT:**127128- Store, echo, or commit provider secrets (`CURSOR_API_KEY`, API tokens).129- Pipe a remote installer into a shell (any single-line fetch-and-execute130 variant).131- Auto-install for everyone or default to Flow B when the flow question is132 unanswered.133- Clobber an existing `.review/extension.md`, `pr-review.yml`, or vendored134 skill — reconcile gaps only.135- `git commit` / `git push` as part of the addon flow (those belong to the136 surrounding DWP `execute` / maintainer workflow).137- Edit source files under the consumer's application tree — review findings138 are applied (if at all) by the upstream `apply-review` sub-skill under its139 own per-finding consent contract, not by this addon.140141### Supply-chain trust (what a "yes" actually installs)142143This addon delegates to third-party artifacts, so the trust chain is stated144explicitly rather than implied:145146| Artifact | Source | How it is verified |147|----------|--------|--------------------|148| Vendored skill (five sub-skills) | `DailybotHQ/ai-diff-reviewer` at a **published tag** (current `v2.0.0`) | `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. |149| CI Action (Flow B only) | `DailybotHQ/ai-diff-reviewer` GitHub Action, referenced by its `@v2` major line (exact-tag pinning is not how the Actions marketplace references actions) | Each Action release in the `@v2` 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. |150| Extension file | Generated **locally** by `generate-extension` from the repo's own diff | Never downloaded; reviewed by the developer like any other tracked file. |151| Provider secret (Flow B only) | The maintainer's own `CURSOR_API_KEY`, set in GitHub Settings | This addon never reads, stores, echoes, or commits provider secrets. |152153Nothing else is fetched. There is no telemetry, no post-install script, and no154runtime download by this addon itself; the only network action it can prompt155for is the consent-gated, tag-pinned `skills add`/`skills update` above.156157## The flow158159### Step 0 — Consent + recommend-only-if-relevant + choose the flow1601611. **Confirm relevance.** Offer this addon only when it makes sense: the162 developer or team wants structured code-review quality on DWP work, or163 explicitly asks for local pre-push review or PR merge-gating. In trust/auto164 mode you MAY recommend it **only** on that signal — do **not** auto-install165 for everyone. If the developer declines, stop cleanly; the repo stays166 baseline-conformant.1671682. **Ask the flow question — do NOT guess.** This matches upstream v2.0.0's169 own ambiguity tie-break policy. Present both flows plainly:170171 > This addon supports two adoption modes:172 >173 > **Flow A — local-only.** Vendored skill + a repo-tailored extension174 > file (via `generate-extension`); no GitHub Actions changes. Best for175 > personal or experimental repos, or teams not (yet) ready for automated176 > PR review. Once both are present, the DWP Security Review is augmented177 > with a local review pass — skill alone is not enough.178 >179 > **Flow B — dual-surface.** Skill + CI Action, both reading the same180 > `.review/extension.md` for byte-identical parity. Every PR to `main`181 > gets an AI review in CI, gated on a label of your choice (typical:182 > `ready`). Recommended for team repos.183 >184 > Which flow?185186 If the signal is unclear, ask; never default to Flow B (installing the187 workflow unrequested is a much bigger footprint than declining Flow B and188 only using the local review).1891903. **Detect existing setup (reconcile-don't-clobber).** Before installing191 anything, check what is already present (see `templates/INTEGRATION.md`):192 - Vendored skill already installed at `.agents/skills/ai-diff-reviewer/`?193 - Extension file at one of the three recognized paths (in precedence194 order): `.review/extension.md` > `.github/ai-diff-reviewer/extension.md`195 > `.github/ai-pr-reviewer/extension.md` (pre-v1.5 back-compat)?196 - `.review/.skip-bootstrap` marker present (developer opted out of the197 bootstrap offer previously — respect it)?198 - `.github/workflows/pr-review.yml` or any workflow with199 `uses: DailybotHQ/ai-diff-reviewer` (or the pre-rename200 `DailybotHQ/ai-pr-reviewer` — the 301 redirect keeps old pins working)?201 - Provider secret documented anywhere (typical: `CURSOR_API_KEY`)?202203 If a piece already exists, **do not redo it** — record it and only fill204 gaps.205206### Step 1 — Offer the vendored skill install (OPT-IN, defer consent)207208Present the install path and let the developer choose; **never run an209installer without their explicit acceptance**.210211- **Vendored coding-agent skill** (recommended — brings the five-sub-skill212 router and the byte-identical prompt parity guarantee; current **v2.0.0**):213 - `npx --yes skills add DailybotHQ/ai-diff-reviewer@v2.0.0 --skill ai-diff-reviewer -y`214 (**pinned to a published tag**; vendors into215 `.agents/skills/ai-diff-reviewer/` and records source + content hash in216 `skills-lock.json`; both `--yes` and `-y` are required — `--yes` covers217 npm's own prompt, subcommand `-y` covers the `skills` CLI's own218 "Which agents do you want to install to?" picker, which hangs in non-TTY219 without it — upstream fixed this in v1.7.0).220 - Bump to the latest published tag with `npx --yes skills update ai-diff-reviewer -y`.221222> **Do not reimplement the install, and never pipe a remote installer to a223> shell.** The `npx skills` command is the supported, checksummed install224> path — it records the content hash in `skills-lock.json` for reproducible225> restores.226227### Step 1b — Bootstrap the extension file (REQUIRED for both flows)228229Security Review detection (SPEC §6.1 / `create` / `execute`) requires230**skill + an extension file** at one of the three recognized paths. Do231**not** finish addon onboarding without one — otherwise every later232Security Review will warn "install incomplete" and skip the local pass.2332341. If an extension already exists at a recognized path → record it; do not235 clobber (and do not migrate fallback/back-compat paths silently — ask).2362. If `.review/.skip-bootstrap` is present → the developer previously opted237 out. Respect it: document that the local SR augmentation will not fire238 until they remove the marker and create an extension; do not surprise-239 bootstrap later during `execute`.2403. Otherwise → hand off to upstream `generate-extension` (or let the241 developer hand-write `.review/extension.md`) **before** proceeding to242 Step 2 / Step 3. Preferred handoff: *"generate a `.review/extension.md`243 for this repo"*.244245Mid-plan `execute` **MUST NOT** surprise-bootstrap an extension — that is246an onboarding concern, not a Security Review side effect.247248### Step 2 — CI workflow install — DEFER to the upstream `setup` sub-skill (Flow B only)249250Do **not** hand-roll `.github/workflows/pr-review.yml`, do **not** prompt for251API keys, and do **not** store any credential. When the developer chose252Flow B, hand off to the upstream `setup` sub-skill — its 6-question wizard253produces a workflow tuned to the consumer's choices (provider / strictness /254trigger mode / external-contributor policy / PR-description mode /255complexity labels), and [`setup/reference.md`](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/skills/ai-diff-reviewer/setup/reference.md)256doubles as the reference manual for every `action.yml` input.257258- Point at the vendored skill: `.agents/skills/ai-diff-reviewer/setup/SKILL.md`.259- Handoff phrase: *"Set up AI Diff Reviewer for this repo"* (or260 `/ai-diff-reviewer-setup`) — workflow + label bootstrap only. Step 1b already261 required the extension file for both flows; do **not** re-enter262 `generate-extension` here unless Step 1b was skipped (e.g. explicit263 `.review/.skip-bootstrap` opt-out and the developer later reversed it).264- Provider secret: the wizard tells the maintainer which secret to configure265 (typical: `CURSOR_API_KEY` for the Cursor provider). Maintainer sets it at266 Settings > Secrets and variables > Actions.267268The addon **MUST NOT** reimplement the wizard. If the developer wants to skip269the wizard, `templates/INTEGRATION.md` provides a fallback shape and points270at the reference manual — but the wizard is the primary path.271272### Step 3 — Wire the Security Review augmentation into DWP execution273274This is the integration value. Reasoning guidance is in275`templates/INTEGRATION.md` — adapt it to the repo; do not copy verbatim.276277- Add a short, clearly-optional note to the repo's DWP execution docs (the278 generated `AGENTS.md` reporting section and/or `docs/AI_AGENT_COLLAB.md`)279 describing that **when this addon is installed**, the mandatory280 `{N-2}.task_security_review.md` template gains an additional post-existing-checks step:281282 1. **Local review augmentation (both flows)** — invoke the upstream283 parent default flow ("Review my current branch"). Capture verdict +284 findings table + per-finding body + notes + recommendation. Append to285 `analysis_results/SECURITY_REVIEW.md` under a dedicated286 `## AI Diff Reviewer local review` heading. A `critical` finding287 follows the existing SR contract — blocks completion until fixed or288 explicitly accepted. `warning` / `info` findings are appended and289 reported but do not block.290291 2. **Optional post-CI walkthrough companion (Flow B only)** — after the292 plan's PR has been pushed and CI has reviewed it, the developer MAY293 invoke the upstream `apply-review` sub-skill from within the same294 `execute` session to walk through CI findings per-finding (apply /295 defer / skip) with explicit consent. `apply-review` is **read-only by296 default**; source-file edits require an explicit yes per finding; it297 **never commits and never pushes**. This is surfaced as an *available298 option*, not a new plan task file — the addon **MUST NOT** insert an299 `apply-review` task into any plan.300301- Every hook MUST be **best-effort and conditional**: the local Security302 Review pass fires only when the vendored skill is present **and** an303 extension file is detected, and it **MUST NOT block** `create` or304 `execute` if the skill is absent, detection fails, or the local review305 invocation errors — warn once and continue (see SPEC §7 Never-block).306 Do **not** skip the local pass because a CI provider secret is unset;307 that secret is Flow B CI / gate messaging only.308309- The reviewer's `.review/extension.md` (repo-tailored via the upstream310 `generate-extension` sub-skill, either through the bootstrap offer or311 invoked explicitly) shapes what maps to which severity. This is the312 primary customization surface; consumers who want repo-specific review313 rules author them here.314315### Step 4 — Validate (SPEC §9 Validation)316317Run the validation checklist and report: whether the vendored skill is318present with the correct version, whether an extension file is present at319one of the three recognized paths, whether (Flow B) the workflow file is320present with the upstream Action pinned to `@v2`, whether the provider321secret is documented in AGENTS.md, whether the stable-named gate job (if322Flow B) is `AI review gate` for branch protection, and any deferred items.323If nothing could be installed here (sandbox/CI), say why — do not silently324skip, and do not fail the onboarding.325326## Failure-mode guardrails327328- **Never required; invocation never blocking.** If declined — or if the329 vendored skill is missing, detection fails, or the local review330 invocation errors — stop/continue cleanly. The repo stays331 baseline-conformant. Once a local review **ran**, open `critical`332 findings still block Security Review completion until fixed or333 explicitly accepted (SPEC §6.1 / §7). An unset CI provider secret does334 not skip the local Security Review pass (Flow B CI/gate only).335- **Defer to upstream.** No wizard reimplementation, no review-methodology336 reimplementation, no apply-review reimplementation. Point at the vendored337 sub-skills.338- **Verified install only.** Never recommend piping a remote installer to a339 shell. Use `npx --yes skills add <repo>@<tag> … -y` — the tag pin plus340 `skills-lock.json` content-hash verification is what makes the install341 reproducible and auditable.342- **Reconcile, don't clobber.** An existing extension file, workflow, or343 vendored skill is preserved; only fill gaps. Never migrate a file at344 `.github/ai-diff-reviewer/extension.md` (or the back-compat345 `.github/ai-pr-reviewer/extension.md`) to `.review/extension.md` silently346 — ask.347- **Vendor-neutral.** Never imply DWP needs the AI Diff Reviewer. This addon348 is purely additive review quality.349- **Both flows are first-class.** Flow A (local-only) is a supported use350 case, not a degraded mode. The addon MUST ask; MUST NOT default to Flow B.