From e3d1f958aa5fdd74169d299c27b2d22767a303eb Mon Sep 17 00:00:00 2001 From: Sergio Alexander Florez Galeano Date: Wed, 15 Jul 2026 18:53:32 +0000 Subject: [PATCH 01/18] feat(dwp): add ai-diff-reviewer addon (opt-in, two-flow, defers to upstream v1.7.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Author the fifth DWP addon that connects an AI-first repo to the AI Diff Reviewer (DailybotHQ/ai-diff-reviewer, marketplace "AI Diff Reviewer", v1.7.0 upstream). Mirrors the dailybot addon shape: opt-in, never required, never blocks, reconcile-don't-clobber, vendor-neutral. Defers install, review methodology, workflow wizard, PR-body drafting, and post-CI walkthrough to the upstream skill's five coordinated sub-skills (parent default flow + generate-extension + setup + open-pr + apply-review). Ships the four mandatory addon components: - SKILL.md — the onboarding hook (Step 0 asks Flow A vs Flow B — never guesses, matching upstream v1.7.0's own ambiguity tie-break policy; Step 1 offers the vendored skill install with both `--yes` and `-y` flags; Step 2 defers CI-workflow authoring to the upstream `setup` wizard; Step 3 wires the mandatory DWP Security Review task to run the upstream parent default flow as an additive local review pass and, in Flow B, surfaces `apply-review` as an optional developer-invoked companion during `execute`). - SPEC.md — RFC-2119, 10 sections, formally defines both flows (§3), what the addon installs (§4), deferred auth + wizard handoff (§5), Security Review augmentation + optional apply-review companion (§6), never-block rule (§7), reconcile-don't-clobber with the 3-path extension-file precedence order (§8), 8-item conformance validation checklist (§9), archetype compatibility notes (§10). - templates/INTEGRATION.md — reasoning guidance for detecting existing setup, asking the flow question, installing the vendored skill, bootstrapping the extension via `generate-extension`, wiring the CI workflow via `setup` (with a minimal fallback shape when the developer skips the wizard), and never-block rules. - addons/README.md — new row + trailing-paragraph mention. The core DWP methodology has ZERO dependency on the AI Diff Reviewer; a repo with zero addons remains fully baseline-conformant. Task 2 wires this addon's Security Review augmentation into DWP `create`/`execute`. Co-authored-by: Cursor --- skills/deepworkplan/addons/README.md | 7 +- .../addons/ai-diff-reviewer/SKILL.md | 243 +++++++++++ .../addons/ai-diff-reviewer/SPEC.md | 389 ++++++++++++++++++ .../ai-diff-reviewer/templates/INTEGRATION.md | 302 ++++++++++++++ 4 files changed, 940 insertions(+), 1 deletion(-) create mode 100644 skills/deepworkplan/addons/ai-diff-reviewer/SKILL.md create mode 100644 skills/deepworkplan/addons/ai-diff-reviewer/SPEC.md create mode 100644 skills/deepworkplan/addons/ai-diff-reviewer/templates/INTEGRATION.md diff --git a/skills/deepworkplan/addons/README.md b/skills/deepworkplan/addons/README.md index 2a936e5..9ca191b 100644 --- a/skills/deepworkplan/addons/README.md +++ b/skills/deepworkplan/addons/README.md @@ -64,6 +64,7 @@ An addon MAY additionally ship per-stack presets, examples, or migration notes. | Dailybot integration | [`addons/dailybot/`](dailybot/SKILL.md) | **Authored** — opt-in install of the Dailybot agent skill (**3.10.3**) / CLI (**>= 3.7.0**), auth **deferred** to the Dailybot skill's own consent flow, **four lifecycle events** (kickoff, significant task, blocked, completion) wired as optional best-effort reports via the `report` sub-skill, optional deterministic hook enforcement, and access to the full 14-capability Dailybot skill when invoked directly. The core methodology has **zero** Dailybot dependency. | | Dependency upgrade | [`addons/dependency-upgrade/`](dependency-upgrade/SKILL.md) | **Authored** — opt-in, **package-manager-agnostic** dependency upgrades: detect the repo's real manager (npm/pnpm/yarn + ncu, pip/poetry/uv, cargo, go mod, bundler, composer…), classify by semver, upgrade in safe batches, run the repo's **real** validation gate after each batch, revert a failing batch, summarize. Installs a `/lib-upgrade` delegator into the repo's `.agents/commands/` only when accepted. | | Design system | [`addons/design-system/`](design-system/SKILL.md) | **Authored** — opt-in, **interface-surface-scoped** `DESIGN.md` at `docs/DESIGN.md` (indexed from `AGENTS.md`; root only if no `docs/` tree), covering three profiles in one file: **visual-ui** (design tokens from CSS vars / Tailwind config / token files / component styles; WCAG AA contrast), **cli-output** (semantic terminal styles, output components, TTY/`NO_COLOR` degradation), and **conversational** (voice & register, message anatomy, per-platform rendering with plain-text fallbacks). Reason about the repo's **real** design source — never a brand file — and reconcile an existing `DESIGN.md` instead of clobbering it. Offered by `onboard` **only when an interface surface is detected**: visual-ui is default-on when detected; cli-output and conversational are recommended when detected, always asked, never auto-applied. | +| AI Diff Reviewer | [`addons/ai-diff-reviewer/`](ai-diff-reviewer/SKILL.md) | **Authored** — opt-in install of the vendored `DailybotHQ/ai-diff-reviewer` skill (currently **v1.7.0**, marketplace listing "AI Diff Reviewer") which is a **router with five coordinated sub-skills** — parent default flow (local review), `generate-extension`, `setup`, `open-pr`, and `apply-review` (new in v1.7.0). Two officially-supported adoption flows: **Flow A — local-only** (vendored skill only; augments the mandatory DWP Security Review with a structured local review) and **Flow B — dual-surface** (Flow A + `setup` writes `.github/workflows/pr-review.yml` for byte-identical CI-side parity via the workflow's `prompt-extension-file: .review/extension.md`; adds `apply-review` as an OPTIONAL developer-invoked companion during `execute` for walking through CI-posted findings per-finding with explicit consent). The addon MUST ask which flow at consent time — MUST NOT default to Flow B. Install/auth/wizard details all deferred to the upstream skill. The core methodology has **zero** AI Diff Reviewer dependency. | > This README is the mechanism doc. The first addon, `addons/devcontainer/`, is > the methodology's proof that the mechanism works; the second, @@ -73,4 +74,8 @@ An addon MAY additionally ship per-stack presets, examples, or migration notes. > workflow that reasons about each repo's actual stack; the fourth, > `addons/design-system/`, shows an addon can capture durable, repo-native > interface design context — visual UI, CLI output, or conversational — for any -> repo with a user-facing surface (a repo is conformant with zero addons). +> repo with a user-facing surface; the fifth, `addons/ai-diff-reviewer/`, shows +> an addon can potentiate a mandatory final DWP task (Security Review) with a +> structured local review flow AND, in dual-surface mode, add a CI-side merge +> gate with byte-identical parity — while still leaving every repo baseline- +> conformant with zero addons installed. diff --git a/skills/deepworkplan/addons/ai-diff-reviewer/SKILL.md b/skills/deepworkplan/addons/ai-diff-reviewer/SKILL.md new file mode 100644 index 0000000..58de6ee --- /dev/null +++ b/skills/deepworkplan/addons/ai-diff-reviewer/SKILL.md @@ -0,0 +1,243 @@ +--- +name: deepworkplan-addon-ai-diff-reviewer +description: 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 v1.7.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 the work, 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. +version: "2.16.3" +documentation_url: https://deepworkplan.com +user-invocable: true +allowed-tools: Bash, Read, Grep, Glob, Edit, Write +metadata: {"openclaw":{"emoji":"🔍","homepage":"https://deepworkplan.com","requires":{"anyBins":["git","gh"]}}} +--- + +# DeepWorkPlan — AI Diff Reviewer Addon + +Connect 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 **v1.7.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, and it **never blocks** the actual work. + +> ## The rule that overrides everything: this addon DEFERS, it does not reinvent +> +> The upstream **`DailybotHQ/ai-diff-reviewer`** skill (currently **v1.7.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`](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 (v1.7.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) + optionally `generate-extension` + 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`](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`](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. + +## The flow + +### Step 0 — Consent + recommend-only-if-relevant + choose the flow + +1. **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. + +2. **Ask the flow question — do NOT guess.** This matches upstream v1.7.0's + own ambiguity tie-break policy. Present both flows plainly: + + > This addon supports two adoption modes: + > + > **Flow A — local-only.** Vendored skill only; no GitHub Actions changes. + > Best for personal or experimental repos, or teams not (yet) ready for + > automated PR review. The DWP Security Review still gets augmented with a + > local review pass. + > + > **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). + +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 — 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 **v1.7.0**): + - `npx --yes skills add DailybotHQ/ai-diff-reviewer --skill ai-diff-reviewer -y` + (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). + - Or pin to a specific tag: `... DailybotHQ/ai-diff-reviewer@v1.7.0 ...`. + - Bump to the latest 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 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`](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/skills/ai-diff-reviewer/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: *"Full ai-diff-reviewer setup — install the Action workflow + AND generate the extension file."* (Signals Flow B to any agent picking + the skill up on subsequent runs.) +- 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: + + 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. 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. + + 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**. 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**: it fires only if the + vendored skill is present, and it **MUST NOT block** `create` or `execute` + if the skill or its provider secret is absent — warn once and continue + (see SPEC §7 Never-block). + +- 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 `@v1`, 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, never blocking.** If declined — or if the vendored skill + is missing or its provider secret is unset — stop/continue cleanly. The + repo stays baseline-conformant and `execute` is never blocked by review + augmentation. +- **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 … -y` — pinned via `skills-lock.json` + with content-hash verification. +- **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. diff --git a/skills/deepworkplan/addons/ai-diff-reviewer/SPEC.md b/skills/deepworkplan/addons/ai-diff-reviewer/SPEC.md new file mode 100644 index 0000000..87b6e24 --- /dev/null +++ b/skills/deepworkplan/addons/ai-diff-reviewer/SPEC.md @@ -0,0 +1,389 @@ +# SPEC.md — AI Diff Reviewer Addon (Normative) + +## Abstract + +This document is the **normative specification** of the DeepWorkPlan **AI Diff +Reviewer addon**: an opt-in capability that connects an AI-first repository to +the **AI Diff Reviewer** (`DailybotHQ/ai-diff-reviewer`, marketplace listing +"AI Diff Reviewer", current **v1.7.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 — dual-surface**, +optionally) every pull request to the target repo is gated by a CI-side +review Action with byte-identical parity to the local review. It defines the +**two officially-supported adoption flows** (§3), **what the addon +installs/configures** (all opt-in, §4), how it **defers authentication and +wizard orchestration** to the upstream skill's own consent flows (§5), how +the **Security Review augmentation** and the optional **`apply-review` +post-CI companion** 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 +[`methodology-spec/ADDONS.md`](../../spec/ADDONS.md): it is **never** required +for baseline AI-first conformance. + +## Status of This Document + +| Field | Value | +|-------|-------| +| **Version** | 2.16.3 | +| **Status** | Stable | +| **Companions** | `SKILL.md`, `templates/INTEGRATION.md`, `../README.md`, `methodology-spec/ADDONS.md`, `../../create/SKILL.md`, `../../guide/GUIDE.md` §5.4 | +| **License** | MIT | +| **Upstream reference** | `DailybotHQ/ai-diff-reviewer` v1.7.0 (marketplace: "AI Diff Reviewer") | + +## 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 five 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`** (new in 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. + +The **CI Action** is the GitHub Marketplace listing "AI Diff Reviewer" +([`DailybotHQ/ai-diff-reviewer@v1`](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 **core DeepWorkPlan methodology MUST have zero dependency on the AI + Diff Reviewer.** It is vendor-neutral, MIT, and agent-agnostic. A + repository **MUST** be fully conformant to the AI-first baseline + (`DOCUMENTATION_STANDARD.md` §§2–7) and to the DWP specification with + **zero** addons — including this one. +- This addon **MUST NOT** be presented as a precondition for using DWP, and + the `onboard` flow **MUST NOT** auto-install it for everyone. It is + offered, and applied only on explicit acceptance. +- Declining this addon **MUST** still produce a baseline-conformant repo. +- The addon's value is **purely additive review quality** for + developers/teams who want structured code-review output on DWP work. + +--- + +## 3. Two Supported Adoption Flows + +The upstream skill v1.7.0 defines two flows explicitly and requires consumers +to pick between them at consent time (matching its own ambiguity tie-break +policy — ask, don't guess). This addon **MUST** offer both. + +### 3.1 Flow A — local-only + +- Vendored skill installed; the CI Action is **NOT** installed. +- Sub-skills used: **parent default flow** (Security Review augmentation) + + optionally `generate-extension` + optionally `open-pr`. +- Sub-skills skipped: `setup` (would install the workflow, opting the repo + into Flow B against the developer's intent), `apply-review` (no CI review + posts back to any PR without the Action installed). +- 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 five** — parent + `generate-extension` + `setup` + + `open-pr` + `apply-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** offer both flows at consent time. It **MUST NOT** default + to Flow B or install the CI workflow unrequested. +- When the developer's signal is ambiguous, the addon **MUST** ask. The + ambiguity resolution mirrors upstream v1.7.0'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 (all OPT-IN) + +When accepted, the addon **MAY** install or configure the following — each +only with explicit acceptance, and each reconciled if already present (§8): + +### 4.1 The upstream skill (both flows) + +- The addon **SHOULD** offer the vendored skill as the primary install path. + Supported install method: + - `npx --yes skills add DailybotHQ/ai-diff-reviewer --skill ai-diff-reviewer -y` + (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). + - Or pin to a specific tag: `... DailybotHQ/ai-diff-reviewer@v1.7.0 ...`. + - Bump: `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 **SHOULD** offer to bootstrap a repo-tailored extension file + via 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. +- 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 Step 2.5 bootstrap offer). + +### 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 (provider / strictness / trigger mode / + external-contributor policy / PR-description mode / complexity labels). +- The workflow **MUST** pin the upstream Action to a major-line tag (default + `DailybotHQ/ai-diff-reviewer@v1`) so patch-level fixes flow automatically. + Pinning to a specific tag is also acceptable — parity with the vendored + skill's version is what makes local ≡ CI worth it. +- 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 Security Review augmentation (both flows). + - (Flow B) the `pr-review.yml` behavior, the provider-secret requirement, + the label workflow, 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 mandatory **Security Review** task +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 Security Review (both flows — SHOULD) + +The addon **MUST** wire an additive step into the DWP `create` sub-skill's +`{N-2}.task_security_review.md` template. 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 SR task template 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: `critical` findings follow the existing SR contract + and block completion until fixed or explicitly accepted. `warning` and + `info` findings are appended and reported but do not block. + +- The step is **SHOULD**, not MUST — the addon MUST NOT fail-close the plan + if the upstream skill or its provider are unavailable at execution time. +- The augmentation is **additive**. The existing manual Security Review + reasoning is preserved. On repos without the addon, the SR template body + is unchanged. + +### 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. + +### 6.3 Post-CI apply-review companion (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. +- Multi-provider awareness: if consumers change the workflow to a matrix + (e.g. `self-reviewed:anthropic`, `-cursor`, `-codex`, `-claude-code`), + `apply-review` attributes each finding to its leg and surfaces cross-leg + consensus automatically. +- The addon **MUST** describe `apply-review` in the target repo's docs as + an *available option* during `execute` — never as a mandatory extra task. + The addon **MUST NOT** materialize `apply-review` as a plan task file — + doing so would violate the mandatory-final-task-order rule (Security + Review → Skills & Agents Discovery → Executive Report) and turn a + developer-invoked convenience into a scheduled plan step. + +--- + +## 7. Never-Block Rule (mandatory) + +- The Security Review augmentation **MUST NOT** block the developer's + primary work or DWP `execute`. +- If the vendored skill is **absent**, the provider secret is **unset**, the + network is **down**, or any upstream skill invocation **errors**, the + addon's wired step **MUST**: warn briefly once, continue the primary task, + **not** retry automatically, and **not** enter a diagnostic loop. This + mirrors the upstream skill's own trust-boundary guarantees. +- Plan execution **MUST** succeed regardless of whether the local review + was run. +- 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) without + failing onboarding. +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 **optional, conditional, + non-blocking** Security Review augmentation. +5. (Flow B only) `.github/workflows/pr-review.yml` exists with the upstream + Action pinned to `@v1` (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: nothing in the repo implies DWP + **requires** the AI Diff Reviewer; the repo is still baseline-conformant. +8. No `curl … | sh` install path was recommended anywhere in the addon + flow. + +--- + +## 10. Compatibility + +### 10.1 Individual repo archetype + +- Standard use case. Both flows apply directly. The Security Review + 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. + +--- + +## 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` (currently **v1.7.0**), 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`. +- Marketplace listing: ["AI Diff Reviewer"](https://github.com/marketplace/actions/ai-diff-reviewer). +- [`../../create/SKILL.md`](../../create/SKILL.md) §"Three mandatory final tasks" — where the SR augmentation callout is wired. +- [`../../guide/GUIDE.md`](../../guide/GUIDE.md) §5.4 — the canonical Security Review template body. + +--- + +*Part of the DeepWorkPlan methodology, MIT License, by [Dailybot](https://dailybot.com) / dailybotops.* diff --git a/skills/deepworkplan/addons/ai-diff-reviewer/templates/INTEGRATION.md b/skills/deepworkplan/addons/ai-diff-reviewer/templates/INTEGRATION.md new file mode 100644 index 0000000..c3bd758 --- /dev/null +++ b/skills/deepworkplan/addons/ai-diff-reviewer/templates/INTEGRATION.md @@ -0,0 +1,302 @@ +# Template — AI Diff Reviewer Integration (reason, don't copy-paste) + +Reasoning guidance for wiring the AI Diff Reviewer addon into a target repo. +This is **not** a file to drop in verbatim — the commands, workflow shape, +and doc wording are **reasoned against the target repo** (its stack, its +actual DWP execution docs, whether it is public/private, whether it wants +Flow A or Flow B, whether it already has any review workflow). Keep the +SPEC contract intact: **opt-in, defer to upstream, never block, +reconcile-don't-clobber, vendor-neutral, both flows are first-class.** + +Read [`../SKILL.md`](../SKILL.md) and [`../SPEC.md`](../SPEC.md) first. + +--- + +## 1. Detect if the AI Diff Reviewer is already installed (reconcile-don't-clobber) + +Run these **before** offering to install anything. Where a piece exists, do +not redo it — record it and only fill gaps. + +```bash +# Is the vendored skill already installed? +ls -d .agents/skills/ai-diff-reviewer/ 2>/dev/null && \ + sed -nE 's/^version:[[:space:]]*"([^"]+)".*/\1/p' \ + .agents/skills/ai-diff-reviewer/SKILL.md 2>/dev/null | head -1 + +# Is skills-lock.json tracking it? +grep -l '"skillPath":[[:space:]]*"skills/ai-diff-reviewer/' skills-lock.json 2>/dev/null + +# Is an extension file already present? Check all three recognized paths +# in precedence order (first match wins per upstream skill's Step 2). +ls .review/extension.md 2>/dev/null # 1. recommended +ls .github/ai-diff-reviewer/extension.md 2>/dev/null # 2. fallback +ls .github/ai-pr-reviewer/extension.md 2>/dev/null # 3. back-compat + +# Is the opt-out marker present? (developer previously answered "never" to +# upstream's Step 2.5 bootstrap offer — respect it) +ls .review/.skip-bootstrap 2>/dev/null + +# Is a review workflow already wired? +grep -l 'DailybotHQ/ai-diff-reviewer\|DailybotHQ/ai-pr-reviewer' \ + .github/workflows/*.y*ml 2>/dev/null + +# Is a provider secret documented? +grep -l 'CURSOR_API_KEY\|ANTHROPIC_API_KEY\|OPENAI_API_KEY' \ + AGENTS.md docs/*.md .github/README.md 2>/dev/null +``` + +Decision notes: + +- **Vendored skill present** → do not reinstall. Verify the version invariant + against `skills-lock.json`. If lagging, offer `npx --yes skills update ai-diff-reviewer -y`. +- **Extension file present at any path** → keep it. Never migrate silently + from `.github/ai-diff-reviewer/extension.md` (or the back-compat + `.github/ai-pr-reviewer/extension.md`) to `.review/extension.md` — ask. +- **`.review/.skip-bootstrap` present** → the developer opted out of the + bootstrap offer. The addon MUST NOT re-offer it and MUST NOT delete the + marker. To re-enable, the developer deletes the marker themselves. +- **Workflow present** → do not overwrite. If the maintainer wants to switch + providers or change the label gate, hand off to the upstream `setup` + sub-skill to regenerate (it's idempotent and reconciles). +- **Provider secret documentation present** → keep it; only extend to + mention the label workflow if missing. + +--- + +## 2. Ask the flow question — do NOT guess + +Matching upstream v1.7.0's own ambiguity tie-break policy: when the signal is +unclear, **ask**. Never default to Flow B (installing the workflow +unrequested is a much bigger footprint than declining Flow B). + +Present both flows plainly: + +> This addon supports two adoption modes: +> +> **Flow A — local-only.** Vendored skill only; no GitHub Actions changes. +> Best for personal or experimental repos, or teams not (yet) ready for +> automated PR review. Your DWP plans' Security Review task still gets +> augmented with a structured local review. +> +> **Flow B — dual-surface.** Skill + CI Action, both reading the same +> `.review/extension.md` for byte-identical parity. Every PR to your default +> branch gets an AI review in CI, gated on a label of your choice (typical: +> `ready`). Recommended for team repos. Adds an optional `apply-review` +> companion for walking through CI findings after push. +> +> Which flow? + +Signals that clarify the answer without asking: + +- Explicit "local-only", "no CI Action", "just want the skill" → Flow A. +- Explicit "full setup", "install the workflow", "gate my PRs" → Flow B. +- Personal repo, experimental repo, or maintainer says "not ready to + automate" → default suggestion Flow A (still ask). +- Team repo with existing review culture, `.github/CODEOWNERS`, and other + automated PR quality checks → default suggestion Flow B (still ask). +- **Ambiguous → ASK.** Do NOT interpret the presence of unrelated workflows + (CI tests, deploy pipelines, dependency bots) as evidence of Flow B — + only an existing ai-diff-reviewer workflow is. + +Record the chosen flow in `AGENTS.md` (or equivalent docs) so future +maintainers and future agent runs see it — mirrors upstream's own recommended +signalling ("Flow A / Flow B" phrases every subsequent request). + +--- + +## 3. Install the vendored skill (OPT-IN — never run without acceptance) + +```bash +npx --yes skills add DailybotHQ/ai-diff-reviewer --skill ai-diff-reviewer -y + +# Verify the vendored version matches the requested tag / latest +VENDORED=$(sed -nE 's/^version:[[:space:]]*"([^"]+)".*/\1/p' \ + .agents/skills/ai-diff-reviewer/SKILL.md | head -1) +echo "Vendored: $VENDORED" + +# Pin to a specific tag for reproducibility (optional) +# npx --yes skills add DailybotHQ/ai-diff-reviewer@v1.7.0 --skill ai-diff-reviewer -y + +# Bump later +# npx --yes skills update ai-diff-reviewer -y +``` + +**Critical: both `--yes` and `-y` are required.** `npx --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 (interactive in +non-TTY hangs indefinitely). Upstream `ai-diff-reviewer` fixed exactly this +bug in v1.7.0 after their own auto-release ran without the subcommand `-y` +and left a partially-published release. Do NOT drop either flag. + +The install vendors the skill into `.agents/skills/ai-diff-reviewer/` and +records source + content hash in `skills-lock.json` so teammates can restore +identical bytes with `npx skills experimental_install`. + +--- + +## 4. Bootstrap the extension file (both flows) + +Where possible, hand off to the upstream `generate-extension` sub-skill — +its ≥12 tool-call Discovery produces a repo-specific file grounded in the +actual codebase, not templated boilerplate. + +- **First-time in a repo with no extension** — the parent default flow's + Step 2.5 will offer to bootstrap automatically. Say "yes" and let it + route to `generate-extension`. +- **Explicit invocation** — say "generate a `.review/extension.md` for this + repo" (one of the `generate-extension` sub-skill's activation triggers). + Same result, skips the bootstrap prompt. +- **Hand-written** — the developer writes the file directly using the + upstream skill's Step 5 examples. Best when the overrides are already + known. + +Extension file location — use `.review/extension.md` when writing a new one. +Reason: runtime-agnostic, works even for teams that don't use GitHub +Actions. The `.github/ai-diff-reviewer/extension.md` fallback is fine for +teams that prefer keeping the file next to workflows; both are recognized +by the upstream skill. + +--- + +## 5. Install the CI workflow (Flow B only) — DEFER to `setup` + +Do **not** hand-roll `.github/workflows/pr-review.yml`. Hand off to the +upstream `setup` sub-skill's 6-question wizard: + +``` +Invoke: "Set up AI Diff Reviewer for this repo" (or /ai-diff-reviewer-setup) +``` + +The wizard asks: + +1. **Provider** (anthropic / claude-code / cursor / codex — pick one, or a + matrix). +2. **Strictness** (block-on-critical / block-on-warning / advisory). +3. **Trigger mode** (label-gated / on-open / on-synchronize). +4. **External-contributor policy** (author-association whitelist). +5. **PR-description mode** (require / skip). +6. **Complexity labels** (auto-apply / skip). + +It writes `.github/workflows/pr-review.yml` adapted to the answers, sets up +the label-bootstrap step, and generates the stable-named gate job for +branch protection. Point at [`setup/reference.md`](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/skills/ai-diff-reviewer/setup/reference.md) +as the reference manual for every `action.yml` input. + +**Fallback (developer wants to skip the wizard).** The minimum viable +workflow shape is: + +```yaml +name: PR review +on: + pull_request: + branches: [] + types: [opened, labeled] +permissions: + contents: read + pull-requests: write +jobs: + review: + if: contains(github.event.pull_request.labels.*.name, '') \ + && contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), \ + github.event.pull_request.author_association) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: { persist-credentials: false } + - uses: DailybotHQ/ai-diff-reviewer@v1 + with: + provider: + api-key: ${{ secrets._API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} + prompt-extension-file: .review/extension.md + strictness: block-on-critical + gate: + name: AI review gate + needs: [review] + if: always() + runs-on: ubuntu-latest + steps: + - run: | + [ "${{ needs.review.result }}" = "success" ] || \ + [ "${{ needs.review.result }}" = "skipped" ] || exit 1 +``` + +Reasoning notes: + +- **`persist-credentials: false`** on `actions/checkout` is REQUIRED — the + reviewer runs with broad local access; no credential should persist. +- **`AI review gate`** is stable-named so branch protection can be + configured against it once and continue to work when the review-job name + changes across provider matrices. +- **Skipped ≠ Failed.** The gate returns success on skipped so a PR + without the label is still mergeable per branch-protection rules. +- The wizard version is preferred because it handles multi-provider + matrices, complexity-label integration, external-contributor policy edge + cases, and label-bootstrap. Only hand-roll when the developer explicitly + asks to skip the wizard. + +--- + +## 6. Wire the Security Review augmentation into DWP execution + +Once the addon is installed, the DWP `create` sub-skill's +`{N-2}.task_security_review.md` template already carries the augmentation +callout (added by `../../create/SKILL.md` — search for +`ai-diff-reviewer`). Every plan materialized in this repo from now on will +carry the addon-augmented SR body. + +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`). +The shape to convey: + +> **Optional — AI Diff Reviewer review augmentation (best-effort, never +> blocks):** when the AI Diff Reviewer addon is installed (detected via +> `.agents/skills/ai-diff-reviewer/` + an extension file), the mandatory +> Security Review task gains an additional local review pass. Invokes the +> upstream skill's parent default flow ("Review my current branch"), +> captures verdict + findings table + severity, and appends them to +> `analysis_results/SECURITY_REVIEW.md` under `## AI Diff Reviewer local +> review`. A `critical` finding blocks completion until fixed or explicitly +> accepted; `warning` / `info` findings are appended and reported but do +> not block. In Flow B, an OPTIONAL post-PR companion is available — the +> `apply-review` sub-skill walks through CI-posted findings per-finding +> (apply / defer / skip) with explicit consent, read-only by default, never +> commits or pushes. + +Decision notes: + +- **Both flows benefit from the SR augmentation.** The local review runs + the same base prompt + extension file regardless of whether the CI Action + is wired. The parity guarantee (`prompt.md` byte-identical between skill + and Action) is only material in Flow B; in Flow A the local review IS + the whole reviewer. +- **`apply-review` is a companion, not a task.** The addon MUST NOT insert + an `apply-review` task file into any plan — it's a developer-invoked + convenience during `execute`, surfaced when the addon is installed AND + Flow B is active AND a PR exists for the plan's branch. +- **Reconcile:** if the repo's DWP docs already mention a review step, + correct or keep it; do not duplicate. + +--- + +## 7. Consent + never-block rules (do not violate) + +- **Opt-in:** install nothing, write no extension file, commit no workflow, + and add no docs without explicit acceptance. Ask about the flow — never + default to Flow B. +- **Defer to upstream:** never reimplement the `setup` wizard, the + `generate-extension` Discovery, the `open-pr` inference, the + `apply-review` walkthrough, or the review methodology. Point at the + vendored sub-skills. +- **Verified install only:** never recommend piping a remote installer to + a shell. Use `npx --yes skills add … -y` — pinned via `skills-lock.json` + with content-hash verification. +- **Never block:** the wired review step is best-effort; absence of the + skill, missing provider secret, network errors — all mean skip-and- + continue — warn once, no retries, no diagnostic loop. `execute` always + succeeds regardless. +- **Vendor-neutral:** never imply DWP requires the AI Diff Reviewer. A + repo with zero addons is fully conformant. +- **Both flows are first-class:** Flow A (local-only) is a supported use + case, not a degraded mode. Whichever the consumer picks, run the flow's + sub-skill set and stop. From f9d5c0f02ea935c696a44566d218e39d2426ad96 Mon Sep 17 00:00:00 2001 From: Sergio Alexander Florez Galeano Date: Wed, 15 Jul 2026 18:56:14 +0000 Subject: [PATCH 02/18] feat(dwp): augment Security Review with ai-diff-reviewer local pass when addon installed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wire the ai-diff-reviewer addon (authored in the previous commit) into the DWP methodology's `create`, `execute`, and `guide` sub-skills. When a target repo installs the addon, the mandatory Security Review task template gains an additive local-review pass — verdict + findings table + severity — appended under a dedicated heading in `analysis_results/SECURITY_REVIEW.md`. The augmentation is conditional on `.agents/skills/ai-diff-reviewer/` being present + an extension file at one of the three recognized paths (in precedence order): `.review/extension.md`, `.github/ai-diff-reviewer/extension.md`, or the back-compat `.github/ai-pr-reviewer/extension.md`. On repos without the addon, the SR template body is unchanged (baseline conformance preserved). Changes: - `create/SKILL.md` "Three mandatory final tasks": adds an addon-augmentation callout under the Security Review bullet. Names all three extension-file paths, cites the upstream skill's five-sub-skill router (parent default flow, `generate-extension`, `setup`, `open-pr`, `apply-review`), points at the byte-identical `prompt.md` parity guarantee between skill and CI Action, and describes the `apply-review` sub-skill as an OPTIONAL Flow B companion during `execute` — never a plan task file. The mandatory-final- task ORDER stays untouched (Security Review → Skills & Agents Discovery → Executive Report). - `guide/GUIDE.md` §5.4: adds a subsection "AI Diff Reviewer local pass (optional — addon-augmented)" describing detection, invocation, output shape, integration into SECURITY_REVIEW.md, severity handling, and the Flow B apply-review companion. - `execute/SKILL.md` Step 5: adds a short callout about addon augmentation of mandatory final tasks — currently only ai-diff-reviewer augments Security Review; the note is generalized so future addons can plug in without further edits to execute. Every mention is conditional ("when installed", "opt-in", "optional"), matching the addon SPEC's never-block rule. No new plan-task file for `apply-review` (would violate the mandatory-final-task-order rule). Co-authored-by: Cursor --- skills/deepworkplan/create/SKILL.md | 27 ++++++++++++++++++++ skills/deepworkplan/execute/SKILL.md | 11 ++++++++ skills/deepworkplan/guide/GUIDE.md | 38 ++++++++++++++++++++++++++++ 3 files changed, 76 insertions(+) diff --git a/skills/deepworkplan/create/SKILL.md b/skills/deepworkplan/create/SKILL.md index 8fe3471..2c204e9 100644 --- a/skills/deepworkplan/create/SKILL.md +++ b/skills/deepworkplan/create/SKILL.md @@ -265,6 +265,33 @@ it. Declare the chosen tier (`standard` or `deep`) and why in the refined draft. `analysis_results/SECURITY_REVIEW.md` even when clean. A critical finding blocks completion until fixed or explicitly accepted by the user (`../spec/DWP_SPECIFICATION.md` §6.1). + + **Addon augmentation — `ai-diff-reviewer` (opt-in, only when installed).** + When the target repo has installed the [`ai-diff-reviewer` addon](../addons/ai-diff-reviewer/SKILL.md) — detected via + `.agents/skills/ai-diff-reviewer/` present + an extension file at one of the + three recognized paths (in precedence order): `.review/extension.md`, + `.github/ai-diff-reviewer/extension.md`, or the back-compat + `.github/ai-pr-reviewer/extension.md` — the Security Review task template gains + an ADDITIONAL post-existing-checks step: invoke the upstream skill's parent + default flow ("Review my current branch" / `/ai-diff-reviewer`), capture the + verdict, findings table, per-finding bodies, notes, and recommendation, and + append them to `analysis_results/SECURITY_REVIEW.md` under a dedicated + `## AI Diff Reviewer local review` heading. The upstream skill's `prompt.md` + is byte-identical to the CI Action's `prompts/default.md` at the same tag, so + when the same repo also runs the CI Action (Flow B), the local review predicts + the CI review exactly. 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. The augmentation is + best-effort and conditional per the addon SPEC §7 (never-block rule): the + upstream skill or its provider secret being absent MUST cause a warning + + skip, NEVER a failed task. **Flow B optional companion (not a plan task):** + when the 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 + `execute` session to walk through CI findings per-finding (apply / defer / + skip) with explicit consent — read-only by default, edits require per-finding + yes, never commits or pushes. This is surfaced as an available option during + `execute`; the addon MUST NOT insert an `apply-review` task file into any + plan (would violate the mandatory-final-task-order rule). - **Skills & Agents Discovery** (MANDATORY, **second-to-last**, task `N-1`, `{N-1}.task_skills_agents_discovery.md`): reviews completed tasks for new patterns, checks the catalog, creates/updates skills/agents if warranted, diff --git a/skills/deepworkplan/execute/SKILL.md b/skills/deepworkplan/execute/SKILL.md index fcc0cbf..d078003 100644 --- a/skills/deepworkplan/execute/SKILL.md +++ b/skills/deepworkplan/execute/SKILL.md @@ -80,6 +80,17 @@ Rules (strict): reorder. 2. **For each task** — open `N.task_{title}.md`, read it fully, follow its instructions and Execution Checklist. + + **Addon augmentation of mandatory final tasks.** If the current task is a + mandatory final task (`{N-2}.task_security_review.md`, etc.) AND an + opt-in addon that augments it is installed in this repo, execute BOTH the + base instruction body AND the addon augmentation. Currently the only such + augmentation is [`../addons/ai-diff-reviewer/`](../addons/ai-diff-reviewer/SKILL.md) + augmenting Security Review (detection: `.agents/skills/ai-diff-reviewer/` + present; augmentation is defined in `../create/SKILL.md` "Three mandatory + final tasks" and detailed in `../guide/GUIDE.md` §5.4 "AI Diff Reviewer + local pass"). The augmentation is best-effort and conditional — never + fails the task; on any upstream error, warn once and continue. 3. **Run validations** — execute ALL validation commands. If any fail: STOP, log the issue in the task's Completion & Log, do NOT mark `[x]`, report and wait for guidance. **Test discipline (`../guide/GUIDE.md` §5.3):** if the task added diff --git a/skills/deepworkplan/guide/GUIDE.md b/skills/deepworkplan/guide/GUIDE.md index 4b7dcf0..9ed85d8 100644 --- a/skills/deepworkplan/guide/GUIDE.md +++ b/skills/deepworkplan/guide/GUIDE.md @@ -467,6 +467,44 @@ plan at the end (`spec/DWP_SPECIFICATION.md` §6.1): Security Review final task — that gate audits the full accumulated diff, including what the tests and docs tasks themselves changed. +#### AI Diff Reviewer local pass (optional — addon-augmented) + +When the [`ai-diff-reviewer` addon](../addons/ai-diff-reviewer/SKILL.md) is +installed, the Security Review task gains an additional local-review pass. The +augmentation is best-effort and conditional — the addon's SPEC §7 (never-block +rule) means an absent upstream skill or missing provider secret produces a +warning + skip, never a failed task. + +- **Detection.** `.agents/skills/ai-diff-reviewer/` present + an 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). +- **Invocation.** Route to the upstream skill's parent default flow ("Review + my current branch" / `/ai-diff-reviewer`) — the local review is capability + #1 of the upstream skill's five-sub-skill router (parent + `generate-extension` + + `setup` + `open-pr` + `apply-review`). +- **Output shape.** Verdict + findings table (columns: `#` / Severity / File / + Summary) + per-finding body + notes + recommendation. This is the same shape + the CI leg would post on a PR — parity is a design property of the upstream + skill (its `prompt.md` is byte-identical to the CI Action's shipped + `prompts/default.md` at the same tag, enforced by upstream CI). +- **Integration.** Append the output to `analysis_results/SECURITY_REVIEW.md` + under a dedicated `## AI Diff Reviewer local review` heading — so a reader + sees the manual SR findings and the AI-augmented findings side by side. +- **Severity handling.** `critical` blocks completion until fixed or explicitly + accepted (existing SR contract); `warning` and `info` are documented but + non-blocking. The reviewer's `.review/extension.md` (repo-tailored) shapes + what maps to which severity — this is the primary customization surface. +- **Optional Flow B post-CI companion.** When the repo runs the CI Action + (Flow B) AND the 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 `execute` session to walk through CI-posted findings per-finding + (apply / defer / skip) with explicit consent. `apply-review` is read-only + by default; edits require per-finding yes; never commits or pushes. This + is an *available option* during `execute`, never a plan task file — the + addon MUST NOT insert an `apply-review` task (would violate the + mandatory-final-task-order rule). + --- ## 6. Agent Execution Rules (Critical Behavior) From 0f259fafd789074e038408e57ef94a14115c92b5 Mon Sep 17 00:00:00 2001 From: Sergio Alexander Florez Galeano Date: Wed, 15 Jul 2026 18:59:03 +0000 Subject: [PATCH 03/18] chore(review): install dailybot v3.10.3 and ai-diff-reviewer v1.7.0 vendored MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Vendor both upstream skills into .agents/skills/ so the deepworkplan-skill repo can dogfood the two DWP addons it maintains: - .agents/skills/dailybot/ (from DailybotHQ/agent-skill@v3.10.3) - .agents/skills/ai-diff-reviewer/ (from DailybotHQ/ai-diff-reviewer@v1.7.0) Both installs used npx --yes skills add ... --force -y (both flags required — npx's --yes for npm's proceed prompt, and the CLI's -y for its own agent-picker prompt; missing either hangs in CI). skills-lock.json now carries three pinned entries: deepworkplan, dailybot, ai-diff-reviewer. Downstream tasks (4, 5, 6, 11) will now write the extension file, add the pr-review.yml workflow, extend auto-release.yml to update these vendored skills alongside deepworkplan, and document the new .agents/ layout. Co-authored-by: Cursor --- .agents/skills/ai-diff-reviewer/SKILL.md | 536 +++++++ .../ai-diff-reviewer/apply-review/SKILL.md | 1336 ++++++++++++++++ .../generate-extension/SKILL.md | 349 +++++ .../generate-extension/examples.md | 185 +++ .../skills/ai-diff-reviewer/open-pr/SKILL.md | 923 +++++++++++ .agents/skills/ai-diff-reviewer/prompt.md | 120 ++ .../skills/ai-diff-reviewer/setup/SKILL.md | 450 ++++++ .../ai-diff-reviewer/setup/reference.md | 397 +++++ .agents/skills/dailybot/SKILL.md | 354 +++++ .agents/skills/dailybot/TRUST.md | 118 ++ .agents/skills/dailybot/ask/SKILL.md | 145 ++ .agents/skills/dailybot/channels/SKILL.md | 75 + .agents/skills/dailybot/chat/SKILL.md | 533 +++++++ .agents/skills/dailybot/checkin/SKILL.md | 871 +++++++++++ .agents/skills/dailybot/conversation/SKILL.md | 243 +++ .agents/skills/dailybot/email/SKILL.md | 270 ++++ .agents/skills/dailybot/forms/SKILL.md | 1350 +++++++++++++++++ .../dailybot/forms/_custom-template/SKILL.md | 129 ++ .agents/skills/dailybot/health/SKILL.md | 215 +++ .agents/skills/dailybot/kudos/SKILL.md | 505 ++++++ .agents/skills/dailybot/messages/SKILL.md | 180 +++ .agents/skills/dailybot/report/SKILL.md | 535 +++++++ .agents/skills/dailybot/report/examples.md | 237 +++ .agents/skills/dailybot/report/hooks.md | 189 +++ .../skills/dailybot/report/significance.md | 61 + .agents/skills/dailybot/report/triggers.md | 269 ++++ .../skills/dailybot/report/writing-guide.md | 192 +++ .agents/skills/dailybot/shared/auth.md | 471 ++++++ .agents/skills/dailybot/shared/context.sh | 151 ++ .../skills/dailybot/shared/dashboard-urls.md | 129 ++ .agents/skills/dailybot/shared/env-json.md | 453 ++++++ .../skills/dailybot/shared/http-fallback.md | 175 +++ .../dailybot/shared/list-query-and-errors.md | 212 +++ .../skills/dailybot/shared/repo-profile.md | 170 +++ .agents/skills/dailybot/teams/SKILL.md | 272 ++++ .agents/skills/dailybot/workflow/SKILL.md | 186 +++ skills-lock.json | 12 + 37 files changed, 12998 insertions(+) create mode 100644 .agents/skills/ai-diff-reviewer/SKILL.md create mode 100644 .agents/skills/ai-diff-reviewer/apply-review/SKILL.md create mode 100644 .agents/skills/ai-diff-reviewer/generate-extension/SKILL.md create mode 100644 .agents/skills/ai-diff-reviewer/generate-extension/examples.md create mode 100644 .agents/skills/ai-diff-reviewer/open-pr/SKILL.md create mode 100644 .agents/skills/ai-diff-reviewer/prompt.md create mode 100644 .agents/skills/ai-diff-reviewer/setup/SKILL.md create mode 100644 .agents/skills/ai-diff-reviewer/setup/reference.md create mode 100644 .agents/skills/dailybot/SKILL.md create mode 100644 .agents/skills/dailybot/TRUST.md create mode 100644 .agents/skills/dailybot/ask/SKILL.md create mode 100644 .agents/skills/dailybot/channels/SKILL.md create mode 100644 .agents/skills/dailybot/chat/SKILL.md create mode 100644 .agents/skills/dailybot/checkin/SKILL.md create mode 100644 .agents/skills/dailybot/conversation/SKILL.md create mode 100644 .agents/skills/dailybot/email/SKILL.md create mode 100644 .agents/skills/dailybot/forms/SKILL.md create mode 100644 .agents/skills/dailybot/forms/_custom-template/SKILL.md create mode 100644 .agents/skills/dailybot/health/SKILL.md create mode 100644 .agents/skills/dailybot/kudos/SKILL.md create mode 100644 .agents/skills/dailybot/messages/SKILL.md create mode 100644 .agents/skills/dailybot/report/SKILL.md create mode 100644 .agents/skills/dailybot/report/examples.md create mode 100644 .agents/skills/dailybot/report/hooks.md create mode 100644 .agents/skills/dailybot/report/significance.md create mode 100644 .agents/skills/dailybot/report/triggers.md create mode 100644 .agents/skills/dailybot/report/writing-guide.md create mode 100644 .agents/skills/dailybot/shared/auth.md create mode 100755 .agents/skills/dailybot/shared/context.sh create mode 100644 .agents/skills/dailybot/shared/dashboard-urls.md create mode 100644 .agents/skills/dailybot/shared/env-json.md create mode 100644 .agents/skills/dailybot/shared/http-fallback.md create mode 100644 .agents/skills/dailybot/shared/list-query-and-errors.md create mode 100644 .agents/skills/dailybot/shared/repo-profile.md create mode 100644 .agents/skills/dailybot/teams/SKILL.md create mode 100644 .agents/skills/dailybot/workflow/SKILL.md diff --git a/.agents/skills/ai-diff-reviewer/SKILL.md b/.agents/skills/ai-diff-reviewer/SKILL.md new file mode 100644 index 0000000..9a6e0cd --- /dev/null +++ b/.agents/skills/ai-diff-reviewer/SKILL.md @@ -0,0 +1,536 @@ +--- +name: ai-diff-reviewer +description: Local & CI companion to the AI Diff Reviewer GitHub Action (DailybotHQ/ai-diff-reviewer on GitHub, "AI Diff Reviewer" on the Marketplace). Router for five capabilities — (1) run a local review of the current branch's diff using the SAME methodology as the CI action, (2) generate a repo-tailored `.review/extension.md` via the `generate-extension` sub-skill, (3) install and configure the GitHub Action itself in a repo that doesn't have it yet via the `setup` sub-skill (also doubles as the reference manual for every `action.yml` input), (4) author a well-documented pull request from the current branch's diff (Conventional-Commits title inference, structured body, PR-template merge, `gh pr create`/`edit`) via the `open-pr` sub-skill, (5) read the AI review the CI Action posted back on the current branch's open PR, present findings in the same format as the local review, and optionally walk the developer through each finding to apply/defer/skip (multi-leg-aware, per-finding consent, no commits/pushes) via the `apply-review` sub-skill. Auto-detects `.review/extension.md` (or `.github/ai-diff-reviewer/extension.md` as fallback) and layers it on top of the shipped default prompt for full local↔CI parity. Use when the developer wants a local pre-flight review before pushing, asks "run a code review on my current changes", wants to customize the reviewer to this repo, asks "how do I set up ai diff reviewer?", asks a reference-style question about any of the action's inputs, asks to "open a PR", "create the pull request", or "write the PR body" for the current branch, or asks "what did the CI review say?", "apply the AI review's fixes", or "walk me through the review findings". +version: "1.7.0" +documentation_url: https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/skills/ai-diff-reviewer/SKILL.md +user-invocable: true +metadata: {"openclaw":{"emoji":"🔍","homepage":"https://github.com/DailybotHQ/ai-diff-reviewer","requires":{"anyBins":["git"]}}} +allowed-tools: Bash, Read, Grep, Glob +--- + +# AI Diff Reviewer — Local & CI Companion Skill + +The [**AI Diff Reviewer**](https://github.com/marketplace/actions/ai-diff-reviewer) +is a GitHub Action that runs an LLM review on every pull request in +CI. **This skill is its local counterpart** — the same reviewer, +driven by your coding agent (Cursor, Claude Code, Codex, Gemini, +Copilot, Cline, Windsurf), on the branch you're editing right now. It +also installs and configures the CI Action itself when your repo +doesn't have it yet. + +**Two audiences, same skill.** + +- If your repo **already runs the Action in CI** → use the skill + locally to catch what CI would catch, seconds before pushing. When + CI is wired to the same extension file + (`prompt-extension-file: .review/extension.md`), local and CI + reviews match — same base prompt, same overrides. See the "Parity + guarantee (Flow B)" section below for the wiring details. +- If your repo **doesn't have the Action yet** (or you don't want it) + → the skill still gives you the full review locally, AND — when + you're ready — helps you install the Action in CI with sensible + defaults for strictness, triggers, and external-contributor policy. + +**Five coordinated capabilities**, routed by intent: + +| # | Capability | Sub-skill | Surface | +|---|---|---|---| +| 1 | Run the review on the current branch | *(default flow — this file)* | 🖥️ Local | +| 2 | Author repo-specific overrides (`.review/extension.md`) | [`generate-extension`](generate-extension/SKILL.md) | 🖥️ Local **+** ☁️ CI (shared file) | +| 3 | Install the GitHub Action + write `pr-review.yml` | [`setup`](setup/SKILL.md) | ☁️ CI | +| 4 | Draft the PR title + body from the diff | [`open-pr`](open-pr/SKILL.md) | 🖥️ Local → GitHub | +| 5 | Read the CI review on the PR + walk through findings to apply/defer/skip | [`apply-review`](apply-review/SKILL.md) | ☁️ CI → 🖥️ Local | + +Sub-skill 3 (`setup`) also doubles as the **reference manual** for +every `action.yml` input via [`setup/reference.md`](setup/reference.md) +— any agent can answer *"what does `strictness` do?"* without opening +the action source. + +**Version parity.** The [`prompt.md`](prompt.md) in this skill is +byte-identical to the one the Action ships in the same tagged release +(enforced by CI's `Skills — prompt-sync invariant` job). Pinning +`@v1.4.2` on both surfaces guarantees identical reviews. + +Source: · License: MIT + +--- + +## Two supported flows: local-only or dual-surface + +The five sub-skills are **independent**. There is no ordering +requirement, and installing the CI GitHub Action is **NOT** a +prerequisite for using this skill locally. Every consumer repo falls +into one of two flows — pick the one that matches the repo's use case: + +| Flow | Use when | Sub-skills to run | Sub-skills to skip | +|---|---|---|---| +| **A. Local-only** | You want your coding agent to run the same review methodology on the branch you're working on right now, but you do NOT want the review to fire in CI on every PR. Common for personal repos, experimental repos, repos where the team hasn't opted into automated PR review yet. | **Optional but recommended:** `generate-extension` (once, to tailor `.review/extension.md`). Then the parent `run a local review` flow on every branch — works with or without an extension file (falls back to the shipped base prompt if Step 2.5 is declined). Optionally `open-pr` at the end. | `setup` — do NOT run it. It writes `.github/workflows/pr-review.yml`, which activates the CI Action. `apply-review` — nothing to apply (no CI review posts back to the PR without the Action installed). | +| **B. Dual-surface** | You want both: pre-flight local review before pushing AND a full CI review on every PR, with identical rules on both surfaces. Recommended for team repos and anything production-facing. | `setup` (once, installs the CI Action + accepts the Step 5 handoff to `generate-extension`), then the parent `run a local review` flow on every branch. `open-pr` when the PR is ready. After push, once CI has posted its review, `apply-review` closes the loop (read the CI findings, walk through them, apply fixes). | Nothing — all five capabilities are used across the lifecycle. | + +**Parity guarantee (Flow B).** When `setup` writes the workflow with +`prompt-extension-file: .review/extension.md` wired in (default when +you accept the Step 5 handoff to `generate-extension`), the CI Action +reads the same file your local agent uses. Same base prompt + same +extension file = same review, locally and in CI. If the Step 5 handoff +is declined, `setup` omits `prompt-extension-file` and you get +base-prompt parity only — you can add the input manually later, or +re-run `setup` and accept the handoff. + +**Signalling the flow to your agent.** If the ambiguous request "set +up the reviewer" could mean either flow, the agent will ask. To skip +that question, be explicit the first time in each repo: + +- Flow A: *"Set up ai-diff-reviewer for local-only use — do NOT install the GitHub Action."* +- Flow B: *"Full ai-diff-reviewer setup — install the Action workflow AND generate the extension file."* + +Every subsequent request in the repo (`"review my branch"`, +`"open the PR"`, etc.) works identically across both flows — the flow +distinction only matters at first-time setup. + +--- + +## Install + +```bash +# Latest v1.x +npx skills add DailybotHQ/ai-diff-reviewer --skill ai-diff-reviewer + +# Or pin to a specific tag for reproducibility +npx skills add DailybotHQ/ai-diff-reviewer@v1.4.2 --skill ai-diff-reviewer +``` + +This vendors the skill into `.agents/skills/ai-diff-reviewer/` in the +consumer repo and records source + content hash in `skills-lock.json` so +any teammate can restore identical bytes with `npx skills experimental_install`. +Bump to the latest with `npx skills update ai-diff-reviewer`. + +> **Note on the git repo slug.** The repo path stays at +> `DailybotHQ/ai-diff-reviewer` (historical — published tags v1.0.0–v1.4.2 +> anchor the URL space). The `--skill ai-diff-reviewer` flag matches the +> Marketplace listing name; both refer to the same product. + +--- + +## Activation + +**Default flow (run a review) — triggers:** + +- "Review my current branch" +- "Run a code review on my changes" +- "Do a pre-flight review before I push" +- "Code review the diff against `main`" +- "What would CI say about my current commits?" + +**Generate-extension flow — triggers:** + +- "Generate a `.review/extension.md` for this repo" +- "Customize the code review for our project" +- "Help me write repo-specific review rules" +- "Tailor the reviewer to our stack" + +**Setup flow (install the GitHub Action) — triggers:** + +- "Set up AI Diff Reviewer for this repo" +- "Configure the reviewer action" +- "Install the AI Diff Reviewer GitHub Action" +- "Help me create the pr-review workflow" +- "How do I add AI Diff Reviewer to this project?" +- Also fires as the answer to reference-style questions about the + action — *"what does `strictness` do?"*, *"how do I use + `label-gate`?"* — via [`setup/reference.md`](setup/reference.md). + +**Open-PR flow (author the pull request) — triggers:** + +- "Open the PR", "create a pull request for this branch" +- "Draft the PR title and description" +- "Write the PR body" +- "Update the PR description", "rewrite the PR body in the proper format" +- "Make a draft PR" (adds `--draft`) + +**Apply-review flow (read + apply the CI review on the PR) — triggers:** + +- "What did the CI review say?" +- "Read the review on this PR", "show me the review findings" +- "Apply the AI review's fixes", "walk me through the findings" +- "Help me address the critical findings", "critical only" +- "Which findings blocked the merge?" +- "The bot posted a review — help me address it" + +If the trigger is ambiguous (e.g. developer says "help me with the +review" on a repo that has no `.review/extension.md` yet, or says +"handle the PR" on a repo where a PR both needs a review AND has a +one-line body), ask ONE clarifying question before routing. Heuristics +that help disambiguate: + +- Repo already has `.github/workflows/pr-review.yml` (or similar) → + probably NOT the setup flow. +- Repo has no `.github/workflows/pr-review.yml` (or similarly-named + AI Diff Reviewer workflow — grep the `.github/workflows/` tree for + `DailybotHQ/ai-diff-reviewer` or `ai-diff-reviewer` action refs) + AND no `.review/extension.md`, and the developer just installed the + skill → **ask** which of the two flows they want ("Flow A + local-only" vs "Flow B dual-surface"; see the "Two supported flows" + section above). Do NOT default to `setup` — Flow A (local-only) is + a first-class use case, and running `setup` unrequested would + write `.github/workflows/pr-review.yml` and force the CI Action + into a repo where the developer may not want it. The presence of + unrelated workflows (CI tests, deploy pipelines, dependency bots) + is NOT evidence of Flow B; only an ai-diff-reviewer workflow is. +- Developer just finished a session of code changes and hasn't asked for + a review yet → default review flow (local). +- The word *"review"* is ambiguous when a PR already exists for the + current branch AND has live `` comments + from a recent CI run. In that case, *"read the review"* usually means + the CI review on the PR (apply-review flow), not a fresh local one. + Ask once: *"Read the CI review that just landed on PR #N, or run a + new local review on your working tree?"* +- Developer just accepted a local review's findings and applied fixes + → probably the open-pr flow (natural next step, first PR of the + session). +- Developer just applied fixes from the CI review → probably `open-pr` + in edit mode (to refresh the PR body if the scope changed), then + `git commit + git push` (they'll do it themselves). + +Some harnesses (Claude Code, Cursor) also expose these as slash +commands (`/ai-diff-reviewer`, `/ai-diff-reviewer-generate-extension`, +`/ai-diff-reviewer-setup`, `/ai-diff-reviewer-open-pr`, +`/ai-diff-reviewer-apply-review`); check the harness's +skill-invocation docs. + +--- + +## Default flow: how the local review works + +Everything below (Steps 0 through 5) describes **only capability #1** +from the table above — running the review on the current branch. The +four sibling sub-skills have their own procedures in their respective +`SKILL.md` files: + +- [`generate-extension/SKILL.md`](generate-extension/SKILL.md) — author `.review/extension.md` +- [`setup/SKILL.md`](setup/SKILL.md) — install the GitHub Action +- [`open-pr/SKILL.md`](open-pr/SKILL.md) — author the PR title + body +- [`apply-review/SKILL.md`](apply-review/SKILL.md) — read + apply the CI review posted on the PR + +--- + +## Step 0 — Trust boundary + +This skill is **near read-only** on the working tree and does **not** +call any remote API. It: + +- Reads files from the current git checkout (`Read`, `Grep`, `Glob`). +- Runs `git diff` and `git log` locally (no push, no fetch). +- Composes the review prompt in the agent's context and produces the + review as terminal output. + +The **only** writes it may perform, and only with explicit developer +consent in Step 2.5: + +- Create `.review/` and write `.review/extension.md` — if the developer + answers **yes** to the bootstrap offer (invokes the + `generate-extension` sub-skill). +- Create `.review/` and touch `.review/.skip-bootstrap` (0 bytes) — if + the developer answers **never** to the bootstrap offer. + +It does **not**: + +- Post inline comments to GitHub (that's the CI action's job). +- Modify any source file, workflow, or config file in the working tree. +- Call the LLM provider directly — it uses the coding agent that's + already running you. +- Send any data off your machine. + +If the coding agent has broader powers (e.g. can write files or run +arbitrary bash), those come from the harness, not this skill. + +--- + +## Step 1 — Detect context + +Run these to establish the review's inputs. Emit the JSON to your working +context; do not print it to the user unless they ask. + +```bash +# Base branch: prefer the tracked upstream's short name, fall back to `main`. +BASE=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null | sed 's|.*/||') +BASE="${BASE:-main}" + +# Current branch + head SHA +HEAD_BRANCH=$(git branch --show-current) +HEAD_SHA=$(git rev-parse --short HEAD) + +# The three artifacts the review needs +git diff --stat "origin/${BASE}...HEAD" # summary of what changed +git diff "origin/${BASE}...HEAD" # the actual diff +git log "origin/${BASE}..HEAD" --oneline # the commit trail +``` + +If the diff is empty, tell the developer "no changes vs `` — nothing +to review" and stop. If `origin/${BASE}` doesn't exist (fresh clone, +missing remote), fall back to `git merge-base main HEAD` and diff against +that; note the fallback in the summary. + +--- + +## Step 2 — Compose the prompt (base + extension) + +The review methodology lives in [`prompt.md`](prompt.md) — the exact same +prompt the CI action ships. Read it into your context as the base. + +Then check for a **repo-specific extension** in this order of precedence +(first match wins; the rest are ignored): + +1. `.review/extension.md` (recommended convention — runtime-agnostic) +2. `.github/ai-diff-reviewer/extension.md` (fallback for teams that + prefer `.github/` sibling to workflow files; + `.github/ai-pr-reviewer/extension.md` also accepted for back-compat + with the pre-v1.5 skill name) + +**If a match is found** — read it, append its content to the base prompt +verbatim, and skip to Step 3. + +**If no match is found**: + +- If `.review/.skip-bootstrap` exists → the developer opted out of the + bootstrap offer previously. Use the base prompt alone (no announcement), + skip to Step 3. +- Otherwise → go to **Step 2.5** (first-time bootstrap offer). + +Announce the composed configuration in one line, e.g. +`Reviewing feat/foo (a1b2c3d) against main. Base prompt + .review/extension.md.` + +The final composed prompt is what governs the review — the severity +definitions, the "what NOT to comment on" rules, the output shape. + +--- + +## Step 2.5 — Offer to bootstrap the extension (first-time only) + +This step fires only when Step 2 found no extension file **and** no +`.review/.skip-bootstrap` marker exists. It's the one moment the skill +educates the developer about the extension convention. After the answer +is recorded (either as generated content or an opt-out marker), the +skill never asks again in this repo unless the developer removes the +marker. + +Ask the developer ONE question: + +> **No `.review/extension.md` found for this repo.** +> +> I can run the review right now with the shipped default prompt — that +> catches ~90% of general-purpose issues (SQL injection, unhandled +> promises, missing input validation, obvious perf regressions, etc.). +> +> But it will miss the **repo-specific** stuff: your money-handling +> conventions, the modules where `console.log` is banned, the RFC-014 +> pattern, the always-critical SQL patterns tied to YOUR schema. That's +> what a `.review/extension.md` gives you — file-anchored severity +> overrides written against THIS codebase. +> +> Want to bootstrap one now? (~30 seconds of Discovery + a ~100-line +> file of concrete overrides.) +> +> - **yes** — I'll route to the `generate-extension` sub-skill, then +> come back and run the review with the fresh extension layered on. +> - **no** — run the review this once with the base prompt only. I'll +> ask again the next time the skill activates. +> - **never** — never ask again in this repo. I'll create +> `.review/.skip-bootstrap` (a tracked 0-byte marker). Commit it so +> your whole team inherits the same preference. To re-enable the +> offer later, delete the marker. + +Handle the response: + +- **yes** → invoke the `generate-extension` sub-skill in extension mode + (see [`generate-extension/SKILL.md`](generate-extension/SKILL.md)). + When the sub-skill finishes writing `.review/extension.md`, re-enter + Step 2 from the top — the freshly-written file will be picked up and + layered onto the base prompt. Do NOT skip the sub-skill's Discovery + phase (12+ tool calls); that's where the value is. +- **no** → skip to Step 3 with the base prompt alone. Do NOT persist + anything. The offer fires again next time. +- **never** → run: + ```bash + mkdir -p .review + touch .review/.skip-bootstrap + ``` + Then skip to Step 3 with the base prompt alone. Suggest the developer + commit the marker: `git add .review/.skip-bootstrap && git commit -m + "chore(review): opt out of AI Diff Reviewer bootstrap offer"`. + +If the developer's response is ambiguous, default to **no** (the +minimally-disruptive choice) — do not silently opt them out. + +--- + +## Step 3 — Execute the review + +Apply the composed prompt to the diff **using the coding agent's own +tools** (Read, Grep, Glob): + +- The prompt tells you to `read_file` / `grep` / `glob` — translate those + to whatever primitives the harness gives you. Read the changed files in + full; the diff alone is rarely enough context. +- The prompt tells you to `post_inline_comment(path, line, body, severity)` + — since you are running locally without GitHub write access, instead + **collect** each finding into an internal list of + `{path, line, severity, body}` records and print them as a table in + Step 4. +- The prompt tells you to `submit_review(summary)` **exactly once** — this + is your cue that the review is complete. When you reach this point, + print the final summary and stop. + +**Cost discipline:** cap yourself at the same number of turns the CI +action does (~25) and the same inline-comment cap (default 20). Don't +grep the whole world; grep the files you're commenting on plus their +imports. + +--- + +## Step 4 — Print the review + +Emit the review to the terminal in the **same format** the CI bot would +post on a PR — this is the parity contract: + +```markdown +## Verdict + + +## Findings + +| # | Severity | File | Summary | +|---|----------|------|---------| +| 1 | 🚨 critical | `src/auth.ts:55` | SQL injection in raw-string login query | +| 2 | ⚠️ warning | `src/cache.ts:120` | Unbounded cache key cardinality | +| 3 | ℹ️ info | `tests/utils.ts:12` | Helper could be reused from existing fixture | + +### 1. `src/auth.ts:55` — 🚨 critical + + +### 2. `src/cache.ts:120` — ⚠️ warning +<...> + +### 3. `tests/utils.ts:12` — ℹ️ info +<...> + +## Notes (no inline anchor) +- + +**Recommendation:** approve / request-changes / comment-only +``` + +Reproducing this exact shape (verdict → findings table → per-finding +body → notes → recommendation) is what lets a developer trust "the +local review says X, so CI will say X too." + +**Optional next-step hint.** When the review is clean (no 🚨 critical or +⚠️ warning findings) OR when the developer explicitly signals they're +ready to push, close the output with a one-line pointer to the sibling +sub-skill: + +```text +Next step: want me to open the PR? — I can draft the title + body from +this same diff (see the `open-pr` sub-skill). Or run `gh pr create` +yourself. +``` + +Do not print this hint when the review found blocking issues — fix +first, ship second. + +--- + +## Step 5 — Extension file convention (for consumers) + +Three ways to end up with an extension file, all valid: + +1. **Automated bootstrap** — say "review my branch" on a fresh repo, + answer **yes** at the Step 2.5 prompt. The `generate-extension` + sub-skill runs its 12+ tool-call Discovery and writes + `.review/extension.md` for you. Simplest path — recommended for the + first setup. +2. **Explicit sub-skill invocation** — say "generate a + `.review/extension.md` for this repo" (or one of the other triggers + listed in Activation). Same result as (1) but skips the bootstrap + prompt. Use this to regenerate or refine an existing file. +3. **Hand-written** — create the file yourself, using the schema and + examples below. Best when you know exactly what overrides you want + and don't need the Discovery walkthrough. + +Whichever path you take, the layout options are the same: + +**Option A — `.review/extension.md`** (recommended): + +``` +my-repo/ +├── .review/ +│ └── extension.md ← auto-detected by this skill +└── .github/ + └── workflows/ + └── pr-review.yml ← CI workflow uses the same file +``` + +**Option B — `.github/ai-diff-reviewer/extension.md`** (fallback if you +prefer keeping the file next to your workflows). The pre-v1.5 path +`.github/ai-pr-reviewer/extension.md` is still recognised for +back-compat. + +The **same file** should be referenced from your CI workflow's +`prompt-extension-file:` input so local and CI stay in perfect sync: + +```yaml +# .github/workflows/pr-review.yml +- uses: DailybotHQ/ai-diff-reviewer@v1 + with: + api-key: ${{ secrets.ANTHROPIC_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} + prompt-extension-file: .review/extension.md # same file the skill auto-detects +``` + +Example `.review/extension.md`: + +```markdown +## Severity overrides for our codebase + +- Any `SELECT * FROM users` in a request path is **critical** (PII exposure). +- Missing `AbortController` on a `fetch()` in `apps/frontend/` is **warning** + (React 18 pattern we standardized on in RFC-014). + +## Don't comment on + +- Formatting in `apps/legacy/*` — that module is scheduled for a rewrite. +- Missing tests in `experiments/` — that folder is intentionally exploratory. +``` + +Full authoring guide (structure, tips, worked examples): +[`docs/PROMPTS.md`](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/docs/PROMPTS.md). + +--- + +## Notes + +- **The skill runs your local agent — it doesn't invoke a separate + LLM.** If your harness is Cursor and you're on `auto`, the review costs + are billed to your Cursor Pro subscription. If your harness is Claude + Code with an API key, it's Anthropic tokens. Either way the local + review is a "free bonus" if you were going to use the agent anyway. +- **When paired with the CI Action (Flow B), this skill does not + replace it.** The CI Action still runs on every PR and posts the + authoritative review (inline comments, severity gating, + merge-blocking); the skill is for the "before pushing" moment. In + Flow A (local-only), the local skill IS the entire reviewer — no CI + leg, no post-push authority; findings live only in your terminal + and you decide what to act on before opening the PR. +- **Extension parity is guaranteed on your side, not enforced by + tooling.** If your `.review/extension.md` says something different + from what your CI workflow's `prompt-extension-file:` points at, you + get drift. Keep them at the same path. +- **Opt-out marker (`.review/.skip-bootstrap`).** A 0-byte tracked + marker file that tells the skill "don't offer to bootstrap the + extension anymore in this repo — the team knows the option exists + and chose to stick with the base prompt." Created by answering + **never** at the Step 2.5 prompt. Delete the file to re-enable the + offer. Committing it is the intended behaviour so the whole team + inherits the same UX. +- **Bugs, feature requests, and extension patterns to add to the + starter templates:** + [`github.com/DailybotHQ/ai-diff-reviewer/issues`](https://github.com/DailybotHQ/ai-diff-reviewer/issues). diff --git a/.agents/skills/ai-diff-reviewer/apply-review/SKILL.md b/.agents/skills/ai-diff-reviewer/apply-review/SKILL.md new file mode 100644 index 0000000..b92262e --- /dev/null +++ b/.agents/skills/ai-diff-reviewer/apply-review/SKILL.md @@ -0,0 +1,1336 @@ +--- +name: ai-diff-reviewer-apply-review +description: Read the most recent AI Diff Reviewer review from the current branch's open PR, present the findings in the same format as the parent skill's local review flow (verdict → findings table → per-finding body → recommendation), and — with explicit consent — walk the developer through each finding to apply, defer, or skip. Multi-provider aware — when the repo runs a matrix of legs (anthropic, cursor, codex, claude-code), attributes each finding to its self-reviewed provider label and surfaces cross-leg consensus. Anchors on the latest ai-pr-reviewer-marker tracking comment and filters minimized (collapsed / outdated) comments per the repo's documented PR-review workflow. Read-only by default; edits to source files require an explicit yes per finding, never commits, never pushes. Use when the developer says "what did the CI review say?", "read the review on this PR", "apply the AI review's fixes", "walk me through the findings", "which findings blocked the merge?", "show me only the critical findings", or "the bot posted a review — help me address it". +version: "1.7.0" +documentation_url: https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/skills/ai-diff-reviewer/apply-review/SKILL.md +user-invocable: true +metadata: {"openclaw":{"emoji":"🔎","homepage":"https://github.com/DailybotHQ/ai-diff-reviewer","requires":{"anyBins":["git","gh"]}}} +allowed-tools: Bash, Read, Grep, Glob, Edit +--- + +# AI Diff Reviewer — Apply Review (sub-skill) + +Companion to the [`ai-diff-reviewer`](../SKILL.md) skill. Where the +parent **runs** the review locally and [`open-pr`](../open-pr/SKILL.md) +**writes** the pull request, this sub-skill closes the loop: it +**reads** the review the CI Action posted back on the PR, presents +the findings in the same format the local review uses, and — with +explicit consent — walks the developer through each finding to +apply, defer, or skip. + +The design philosophy mirrors the family's: + +- **Parity of shape.** The output uses the same + `verdict → findings table → per-finding body → notes → recommendation` + structure the parent skill emits. A developer who has seen one of + the two knows how to read the other. When the CI leg found *"SQL + injection in `src/auth.ts:55`"*, the summary looks identical whether + it was your local agent or CI that surfaced it. +- **Read-only by default.** Fetching + presenting the review never + writes anything. Only when the developer explicitly asks to *"walk + through"* or *"apply the fixes"* does the sub-skill open source + files, and each individual apply still requires a yes. +- **Multi-provider aware.** This repo (and any consumer that opts + into the 4-leg matrix) posts up to four independent reviews per PR, + distinguished by `self-reviewed:` labels. The sub-skill + reads all live legs, attributes each finding to its leg, and + surfaces cross-leg consensus (*"agreed by 3/3 legs → strong signal; + called by 1/3 → could be leg-specific"*). +- **Never commits, never pushes.** Applied fixes stay unstaged in the + working tree. Commit + push is the developer's judgment call, + matching [`open-pr`](../open-pr/SKILL.md)'s trust boundary. + +The single source of truth for the workflow this sub-skill implements +is [`docs/PR_REVIEW_WORKFLOW.md`](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/docs/PR_REVIEW_WORKFLOW.md). +This sub-skill is that doc, executable. + +--- + +## When it fires + +**Read + present the review (default flow) — triggers:** + +- "What did the CI review say?" +- "Read the review on this PR" +- "Show me the review findings" +- "Did the bot approve or request changes?" +- "Which findings blocked the merge?" +- "The AI review just landed — summarize it" + +**Walkthrough mode (apply/defer/skip per finding) — triggers:** + +- "Apply the AI review's fixes" +- "Walk me through the findings" +- "Go through the review one finding at a time" +- "Help me address the critical findings" +- "Fix the review comments the bot left" + +**Scope filters — triggers:** + +- "Critical only" / "show me only the critical findings" +- "Warnings only" / "info-level only" +- "Just the ones from the `cursor` leg" (multi-leg attribution) +- "The findings we all three legs agreed on" + +**Fall through** to a sibling skill when the developer: + +- Wants a **local review** on uncommitted changes → parent + [`ai-diff-reviewer`](../SKILL.md) skill (default review flow). This + sub-skill reads reviews that already exist on the PR; the parent + produces a new one locally. +- Wants to **install the CI action** → [`setup`](../setup/SKILL.md). +- Wants to **customize the reviewer** → [`generate-extension`](../generate-extension/SKILL.md). +- Wants to **author or refresh the PR body** → [`open-pr`](../open-pr/SKILL.md). +- Wants to read **human** reviewer comments (not the bot's) → defer; + this skill filters to bot artefacts by design. `gh pr view --comments` + covers human threads. + +If the intent is ambiguous ("show me the review" on a repo where the +Action posted 4 legs, or on a PR with both bot findings and human +comments), ask ONE clarifying question before acting. + +--- + +## Step 0 — Trust boundary + +This sub-skill's reads and writes are enumerated below. **Nothing else +happens.** + +**Reads (always allowed, no consent needed):** + +- `git`: `git branch --show-current`, `git rev-parse HEAD`, + `git status`, and `git show :` — the latter is + Step 6b's **primary** pre-image source (used on every `apply`, not + just the empty-`diffHunk` case) and is safe by construction: + write-free, streamed to stdout, never touches the working tree, + never creates or modifies a ref. Use it whenever the sub-skill + needs SHA-pinned file content. +- `gh`: `gh pr view` for PR metadata, `gh api graphql` for reviews + + comments. **Not** `gh pr diff` — it always emits current tip vs + base with no way to pin a historical SHA, so it can't be used for + pre-image or freshness checks (Step 6b covers this in detail); if + the sub-skill needs SHA-pinned file content, use `git show` + instead. +- Local files under the current git checkout, via `Read` / `Grep` / + `Glob` — only for files a finding references. + +**Writes (only under the per-finding consent contract in Step 6):** + +- **Edit source files** — when the developer answers *"apply"* on a + finding that has a `\`\`\`suggestion` block, the sub-skill reads the + target file, replaces the exact lines the suggestion covers, and + writes the file back. Never touches lines outside the suggestion's + range. +- **Create `.review/deferred.md`** (0-byte if empty, otherwise a + single-line-per-deferral list) — only when the developer answers + *"defer"* on any finding AND is prompted-and-agrees to persist. If + the developer prefers ephemeral deferrals, the file is not created. +- **Append `.review/deferred.md` to `.gitignore`** — only as a + one-time follow-up the very first time `.review/deferred.md` is + created in this repo, AND only when the developer accepts the + separate consent prompt in Step 6c. Never modifies existing + `.gitignore` rules; only appends one line (plus a labeled comment + identifying this sub-skill as the source) after the existing + content. + +**It does not:** + +- `git add`, `git commit`, `git push`, `git checkout`, or any + history-rewriting operation. +- Post replies, resolve conversations, dismiss reviews, approve, or + request changes on the PR — the sub-skill is read-only against + the GitHub PR-review surface. Replies to individual threads are a + separate concern (a future `respond-to-review` sub-skill). +- Call the LLM provider directly — it uses the coding agent that's + already running you. +- Fabricate suggestions, expand suggestion blocks beyond what the bot + wrote, or reason about "what the bot probably meant" when a + suggestion is absent. If a finding has no suggestion, *"apply"* is + not offered; the developer implements the fix themselves. +- Change any file outside the finding's `path:line` scope on + *"apply"*. If a suggestion is malformed (e.g. the file no longer + matches the expected context), the sub-skill refuses and surfaces + the finding for manual application. + +If the coding agent has broader powers (e.g. can run arbitrary bash), +those come from the harness, not this sub-skill. + +--- + +## Step 1 — Detect context + +Establish the mode (present vs. walkthrough vs. refuse) before +fetching anything from GitHub. + +```bash +# Current branch + head SHA +HEAD_BRANCH="$(git branch --show-current)" +HEAD_SHA="$(git rev-parse HEAD)" +HEAD_SHORT="$(git rev-parse --short HEAD)" + +# Repo slug (owner/repo) +REPO="$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null || echo '')" + +# PR for the current branch (if any) +PR_JSON="$(gh pr view --json number,url,state,headRefOid,labels,isDraft 2>/dev/null || true)" +PR_NUMBER="$(gh pr view --json number --jq '.number // empty' 2>/dev/null || true)" +``` + +`PR_NUMBER` is consumed by every subsequent `gh` / `gh api graphql` +invocation (Steps 2b, 3, 7). Extracted via `gh pr view --json … +--jq …` (not standalone `jq`) so the sub-skill's dependency set +stays `git` + `gh` — the two bins already declared in +`metadata.requires.anyBins`, matching sibling sub-skills. If the +`gh pr view` call fails (no open PR on this branch), `PR_NUMBER` is +empty and the mode table below routes to `refuse-soft`. + +Decide the mode from the state: + +| State | Mode | Skill behavior | +|---|---|---| +| On `main` / `master` / `develop` / `trunk` with no PR | **refuse** | Ask the developer to switch to a feature branch that has an open PR. | +| Detached HEAD | **refuse** | Ask the developer to check out a branch first. | +| `PR_JSON` empty (no PR for this branch) | **refuse-soft** | Point at [`open-pr`](../open-pr/SKILL.md): *"No open PR for ``. Open one first with the `open-pr` sub-skill, wait for CI to review, then re-run me."* | +| `PR_JSON` state is CLOSED or MERGED | **warn** | The review artefacts still exist and are readable — offer to read anyway ("this PR is closed / merged; want the historical review or should I stop?"). Do not proceed silently. | +| `PR_JSON` state is OPEN | **read** | Go to Step 2. | + +**On `gh` missing or unauthenticated:** surface the exact remediation +(`brew install gh` or `gh auth login`) and stop. Do not attempt to +scrape the PR page via a browser — the sub-skill is designed for +`gh` + GraphQL and there is no fallback path. + +--- + +## Step 2 — Fetch the review + +This is the mechanical heart of the sub-skill. The GraphQL query below +is **adapted from** [`docs/PR_REVIEW_WORKFLOW.md`](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/docs/PR_REVIEW_WORKFLOW.md#ready-to-copy-graphql-query) +— the selection set is extended (`createdAt`, `submittedAt`, +`startLine` for multi-line-suggestion apply) but the **filter rules +are the shared contract**: if the doc says *"skip `isMinimized == +true`"*, this sub-skill does. If it says *"anchor on the most recent +marker"*, this sub-skill does. Divergence in the selection set is +allowed and expected as this sub-skill's needs evolve; divergence in +the filter rules is a bug — fix the doc, then re-sync here. + +### 2a. Identify the bot login + +The Action collapses prior artefacts belonging to the user its +`github-token` authenticates as. For consumers using +`secrets.GITHUB_TOKEN` (default), that's `github-actions[bot]`; for +consumers using a PAT / automation account, it's the PAT owner's +login. Hardcoding `github-actions[bot]` silently mis-filters every +PAT consumer — Step 2c drops the real review author and Step 2d +then fires the *"Missing (no marker found)"* branch even though a +live review exists on the PR. + +Resolve the login in this order (first non-empty wins): + +1. **`AIPRR_BOT_LOGIN` env var** — explicit override; always respected. +2. **The most recent non-minimized `` + comment's `author.login`** — authoritative and self-configuring + across `github-actions[bot]`, PATs, and automation accounts. Read + it from the `comments` collection you already fetch in Step 2b; + pick the newest comment whose body starts with + ``. +3. **`gh api user --jq .login`** — a last-resort fallback only when + no marker exists on the PR (a first-run install where CI hasn't + posted anything yet). +4. **The literal string `github-actions[bot]`** — final default when + even step 3 fails; a warning should be surfaced to the developer + since this is almost always wrong for PAT consumers. + +The Step 2b query already returns the top-level `comments` nodes +with `author.login`. To keep the sub-skill's runtime deps aligned +with `metadata.requires.anyBins` (`git` + `gh` only — **no** +standalone `jq`), issue a small dedicated `gh api graphql` call for +the marker-author read, using `gh`'s built-in `--jq` filter to +extract the login without shelling out to `jq`: + +```bash +BOT_LOGIN="${AIPRR_BOT_LOGIN:-}" + +if [ -z "$BOT_LOGIN" ]; then + # Preferred: derive from the most recent non-minimized marker comment. + # Uses gh's built-in --jq (no standalone jq dependency). + BOT_LOGIN="$(gh api graphql \ + -F owner="${REPO%%/*}" -F repo="${REPO##*/}" -F number="$PR_NUMBER" \ + -f query=' + query($owner: String!, $repo: String!, $number: Int!) { + repository(owner: $owner, name: $repo) { + pullRequest(number: $number) { + comments(first: 100) { + nodes { body isMinimized createdAt author { login } } + } + } + } + }' \ + --jq '[.data.repository.pullRequest.comments.nodes[] + | select((.isMinimized | not) + and (.body | startswith("")))] + | sort_by(.createdAt) | reverse | .[0].author.login // empty' \ + 2>/dev/null)" +fi + +if [ -z "$BOT_LOGIN" ]; then + # Fallback: current authenticated user (only accurate on first-run repos + # where no marker exists yet). Warn the developer that this is a guess. + BOT_LOGIN="$(gh api user --jq .login 2>/dev/null || echo 'github-actions[bot]')" +fi +``` + +`gh api graphql --jq` runs the filter inside `gh` itself — it does +not shell out to standalone `jq`, so this snippet stays inside the +`git` + `gh`-only dep constraint declared in `metadata.requires`. +Do NOT reintroduce a standalone `jq | ...` pipe here — the moment +you do, the primary marker-author path breaks on vanilla macOS / +minimal agents and the fallback (`gh api user`) mis-filters live +reviews for every PAT / automation-account consumer. + +### 2b. Run the GraphQL query + +```bash +gh api graphql -F owner="${REPO%%/*}" -F repo="${REPO##*/}" \ + -F number="$PR_NUMBER" -f query=' +query($owner: String!, $repo: String!, $number: Int!) { + repository(owner: $owner, name: $repo) { + pullRequest(number: $number) { + comments(first: 100) { + nodes { + id + body + isMinimized + createdAt + author { login } + } + } + reviews(first: 100) { + nodes { + id + body + state + isMinimized + submittedAt + author { login } + commit { oid } + comments(first: 100) { + nodes { + id + body + path + line + startLine + diffHunk + isMinimized + } + } + } + } + } + } +}' +``` + +`startLine` is `null` for single-line inline comments and non-null for +multi-line ones (e.g. a `\`\`\`suggestion\`\`\` block covering several +lines). When you later need the apply range for Step 6b, derive it as +`start = startLine or line`, `end = line` — the reviewer's `line` +field is the range end for multi-line comments and the anchor for +single-line ones. `originalLine` is the outdated-position field +(diff-relative for reviews that no longer point at the current file +state) and is **not** the multi-line-range start — do not use it here. + +**`line: null` is a distinct case.** GitHub returns `line: null` (and +`startLine: null`) when the comment is anchored on a hunk that is no +longer present in the diff — the review was posted, the developer +force-pushed or rebased, and the anchor became orphaned. This shows +up precisely on the stale-review paths Step 2d allows after +acknowledgement. Because `[startLine or line, line]` would collapse +to `[null, null]` and every downstream comparison would either crash +or produce a bogus apply range, treat `line: null` as a **read-only** +finding: + +- Include the finding in Step 4's presentation with a marker like + `[⚠️ outdated anchor — apply disabled]`. +- In Step 6a's walkthrough, present the body normally. +- In Step 6's menu, **never offer `apply`** — only `defer`, `skip`, + `discuss`, `stop`. Do not attempt to reconstruct a range from + `originalLine` (it's diff-relative to a hunk that no longer + exists; the numbers won't map cleanly onto today's file). +- In Step 3a's consensus scoring, group `line: null` findings only + with other `line: null` findings on the same `path` — the range- + overlap predicate is undefined for null ranges. + +The `diffHunk` field carries the raw diff hunk the comment was +anchored on (the `-`, `+`, and context lines around the anchor). It +is used to render the surrounding patch when the developer needs +context — that display belongs in **Step 4's presentation table** +(next to the file/line) and/or **Step 6a's walkthrough banner** for +the current finding, NOT in Step 5 (which is only the top-level +routing menu: `done` / `walk through` / `critical only` / `warnings +and up` / `filter by leg` / `cancel`). `diffHunk` also serves as an +optional +consistency check inside Step 6b — but it is **not** the primary +source of the expected pre-image; that role belongs to +`git show :` (see Step 6b for the full +derivation). Note the GraphQL schema does **not** expose a `side` +field on `PullRequestReviewComment` — side-of-diff lives on +`PullRequestReviewThread.diffSide`. Step 6b sidesteps this by +reading the reviewed-commit file content directly, which is +independent of hunk sides. In practice this is safe because +`findings_to_gh_inline_comments()` in `scripts/reviewer.py` posts +anchors with `side: RIGHT` by default (the `"side": f.side or +"RIGHT"` line inside that function is the authoritative reference — +cite the function name, not a raw line number that will drift on +the next edit), so `line` / `startLine` refer to post-image file +positions that resolve cleanly +via `git show`. A rare `side: LEFT` anchor (removed-line comment) +will fail the `git show`-slice consistency check in Step 6b and +route to `skip / discuss`. + +`BOT_LOGIN` is **not** a GraphQL variable — it's applied client-side +in Step 2c's filter. GitHub's GraphQL API rejects unused declared +variables (`variableNotUsed`), so declaring `$bot: String!` while only +using it in a follow-up `jq` filter fails the query outright. Keep +the login filter in Step 2c and the GraphQL selection set variable-free. + +### 2c. Filter to live bot artefacts + +Two collections come back — `comments` (top-level, includes tracking +markers) and `reviews` (with nested inline `comments`). Apply the +mandatory rules from [`docs/PR_REVIEW_WORKFLOW.md` § Mandatory rules](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/docs/PR_REVIEW_WORKFLOW.md#mandatory-rules): + +1. **Filter out `isMinimized == true`** at every level (top-level + comments, review bodies, inline review comments). +2. **Filter authors** to `$BOT_LOGIN` only. +3. **Anchor on the latest `` comments** — + plural when multiple legs ran. Each marker's body starts with the + marker string; each carries the SHA its leg reviewed. + +Emit the filtered set to your working context as a list of +`{leg_label, sha, review_body, inline_comments[]}` records. + +### 2d. Anchor + freshness check + +Tracking markers are top-level **issue comments** — they have no +`commit.oid`. The SHA source depends on the marker state (the H3 tells +you which one: `_Working…_` vs. `✅ done` / `🚫 done` vs. `❌ failed`): + +- **Working markers** (`render_tracking_body_working()` in + `scripts/reviewer.py`) — include a `Full SHA: \`\`` line in + the body. Parse it. This is the in-flight case; a Working marker + means the review is still running or its terminal transition + failed. +- **Done and failed markers** (`render_tracking_body_done()` / + `render_tracking_body_failed()`) — do NOT render `Full SHA:`; they + only carry the 7-char short SHA in the H3 (`AI review for + \`<7chars>\``). Resolve the full SHA by joining the marker to its + matching non-minimized review via the provider marker (both carry + ``), then read the joined + review's `commit.oid` — that is the **primary** SHA source for + completed reviews (which is the common case). The 7-char prefix in + the H3 is a useful cross-check but is ambiguous by itself. + +If the joined review is missing when the marker says `done` or +`failed` (rare — the mid-flight transition raced), fall back to the +7-char H3 prefix and warn the developer that the review body could +not be paired. + +Compare the resolved SHA against `HEAD_SHA`: + +| Marker SHA | HEAD SHA | Interpretation | +|---|---|---| +| Matches HEAD | Matches | Review is for the current commit — proceed normally. | +| Matches HEAD's parent (marker == `HEAD~1`) | Matches | The developer has made **one commit locally** since the review; HEAD itself is a commit CI never saw. Warn: *"The review is for ``, but you've committed `` since then. Findings may already be resolved by your local commit; CI will re-review once you push. Continue anyway?"* — proceed only after ack. Pre-image checks in Step 6b will still refuse silently-clobbering an already-edited line. | +| Older than HEAD's parent | New commits landed since the review | Warn: *"The review is for ``, but HEAD is ``. Reading anyway, but the findings may be stale — CI will likely re-review. Continue?"* | +| Newer than HEAD | Local branch is behind origin | Warn: *"Origin has ``, your local HEAD is ``. Consider `git pull` before applying."* — proceed only after ack. | +| Missing (no marker found) | — | CI hasn't run yet OR the label-gate is missing OR all matrix legs' secrets are unset. See [`docs/PR_REVIEW_WORKFLOW.md` § "I don't see any live review"](https://github.com/DailybotHQ/ai-diff-reviewer/blob/main/docs/PR_REVIEW_WORKFLOW.md#i-dont-see-any-live-review) for the diagnosis table. Stop; do not proceed with an empty review. | + +Only exact-HEAD is fully authoritative; every other row above +(including `marker == HEAD~1`) requires an explicit developer +acknowledgement before Step 4 presents findings or Step 6b applies +anything. This closes the "silent green light" case where a single +uncommitted-since-CI commit would otherwise be treated as +authoritative. + +Never fabricate findings when the review is missing or stale. + +### 2e. Extract per-finding severity + +GitHub inline review comments carry `body` only — +`findings_to_gh_inline_comments()` in `scripts/reviewer.py` does +**not** prefix severity into the comment body, so severity is **not** +recoverable from the inline comment itself. The authoritative +per-finding severity lives in the **review summary body's findings +table**: + +```markdown +### 2. Findings table + +| # | Severity | File | Summary | +|---|------------|---------------------|----------------| +| 1 | 🚨 critical | `src/auth.ts:55` | SQL injection… | +| 2 | ⚠️ warning | `src/cache.ts:120` | Unbounded key… | +``` + +For each inline comment produced by the leg, join to the summary +table by matching on `path:line`: + +1. **Locate the findings table heading-agnostically.** Scan + `review_body` for a Markdown table whose header row contains all + of `Severity`, `File`, and `Summary` (case-insensitive, in any + column order). The heading right above the table varies — + `prompts/default.md` instructs models to emit it under + `### 2. Findings table`, while the local review flow uses + `## Findings`, and consumers with custom prompts may use anything — + so anchoring on the header row (not the heading text) is the only + reliable strategy. +2. Parse each row into `{severity, path, line, summary}`. The severity + cell is `