@caddis/cli 0.2.2 → 0.2.3

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.41",
+  "version": "1.3.47",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/skills/_registry.md

@@ -16,6 +16,7 @@
 | Code Review | `code-review/` | Automated code review for pull requests using specialized review patterns. Analyzes code for quality, security, performance, and best practices. Use when reviewing code changes, PRs, or doing code audits. |
 | Codebase Audit | `codebase-audit/` | Systematic codebase audit methodology for unfamiliar codebases before architecture or implementation work. Use for new codebase, unfamiliar codebase, pre-implementation audit, codebase review, technical due diligence, or onboarding to an existing project. Produces AUDIT-FINDINGS.md and QUESTIONS.md. Routes to Architect, Planner, or Code Reviewer agents. |
 | Cross Review | `cross-review/` | Cross-vendor code review of the current diff — a second-vendor model (DeepSeek/GLM/any OpenAI-compatible endpoint) reviews your changes to catch bugs a same-vendor reviewer misses |
+| Dashboard Perf Sweep | `dashboard-perf-sweep/` | Re-measure an app's dashboard/API endpoints for load-time regressions and decide, with a documented checklist (not a black-box verdict), whether a slow one is a candidate for the rs-kit summary-table refresher pattern — or needs an index, keyset paging, gzip, or nothing at all. Use when the user says "sweep dashboard performance", "check if this app needs rs-kit", "re-measure the perf tracker", "is this endpoint a refresher candidate", or when a dashboard-performance-tracker.md is stale and needs re-validating. Read-only by default (dev servers only; prod requires an explicit opt-in and human confirmation) and human-invoked, never scheduled -- it surfaces candidates, it does not enroll them. |
 | Error Handling | `error-handling/` | Error handling patterns for Python and TypeScript applications. Use when designing error hierarchies, implementing retry logic, building error boundaries, or establishing logging strategies. Covers custom exceptions, result types, circuit breakers, and user-facing error messages. |
 | Fastapi Dev | `fastapi-dev/` | Build FastAPI backends with standard patterns, error handling, and testing |
 | Javascript Typescript | `javascript-typescript/` | JavaScript and TypeScript development with ES6+, Node.js, React, and modern web frameworks. Use for frontend, backend, or full-stack JavaScript/TypeScript projects. |
@@ -46,6 +47,7 @@
 | Skill | Path | When to Use |
 |-------|------|-------------|
 | Code Documentation | `code-documentation/` | Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides. |
+| Explainer Doc | `explainer-doc/` | Write a document that hands off work to a team who did NOT do the investigation — an external vendor, another team, a contractor — and who must be able to act on it alone. Use when the user says "write a spec for the X team", "document this for someone outside the team", "explainer doc", "implementation spec for a vendor", "hand this off to Y", or is about to write a design doc whose primary reader did not live through the debugging/design process. NOT for internal specs where the reader already has full context (use technical-writing or writing-plans instead) — this is specifically for the "stranger must follow it alone" case. |
 | Technical Writing | `technical-writing/` | Technical documentation best practices for READMEs, API docs, architecture docs, runbooks, and developer guides. Use when writing or reviewing documentation, creating onboarding guides, or establishing documentation standards. |
 | Writing Plans | `writing-plans/` | Use when you have a spec or requirements for a multi-step task, before touching code |
 

package/bundles/antigravity-plugin/skills/cross-review/SKILL.md

@@ -17,11 +17,14 @@ overridable via `CADDIS_KEYS_FILE`). If your keys file is populated, no env setu
 Details: the `coding/cross-review` skill and the **Providers & keys** guide.
 
 ## Run it
-The tool ships at `.github/tools/oss_review.py` (stdlib-only, no install):
+Locate the tool (stdlib-only, no install), in order:
+- `.github/tools/oss_review.py` — this project vendors its own copy.
+- `${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py` — the plugin-bundled copy (every install has this;
+  use it whenever the project has no local copy).
 ```
-python .github/tools/oss_review.py                     # DeepSeek eyes (default)
-python .github/tools/oss_review.py --provider glm      # GLM eyes
-python .github/tools/oss_review.py --range $ARGUMENTS  # review a git range, e.g. origin/main..HEAD
+python <resolved-path>/oss_review.py                     # DeepSeek eyes (default)
+python <resolved-path>/oss_review.py --provider glm      # GLM eyes
+python <resolved-path>/oss_review.py --range $ARGUMENTS  # review a git range, e.g. origin/main..HEAD
 ```
 Optional: `--base-url <url>`, `--model <id>` (env always overrides the preset).
 **Alternate the provider between reviews** (DeepSeek one diff, GLM the next) — different model

package/bundles/antigravity-plugin/skills/dashboard-perf-sweep/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: dashboard-perf-sweep
+context: fork
+description: Re-measure an app's dashboard/API endpoints for load-time regressions and decide, with a documented checklist (not a black-box verdict), whether a slow one is a candidate for the rs-kit summary-table refresher pattern — or needs an index, keyset paging, gzip, or nothing at all. Use when the user says "sweep dashboard performance", "check if this app needs rs-kit", "re-measure the perf tracker", "is this endpoint a refresher candidate", or when a dashboard-performance-tracker.md is stale and needs re-validating. Read-only by default (dev servers only; prod requires an explicit opt-in and human confirmation) and human-invoked, never scheduled -- it surfaces candidates, it does not enroll them.
+---
+
+# dashboard-perf-sweep — re-measure, then judge the shape, not just the time
+
+Today an app "earns" the rs-kit refresher pattern only when someone happens to be doing unrelated
+work on it, hits a slow page, and measures it properly. That worked for rev-sight and serve-sight,
+but a snapshot measurement goes stale — a page added last month, or a table that crossed a growth
+threshold since, has no mechanism to surface itself. This skill re-measures on demand.
+
+**What already exists and must NOT be rebuilt:** every app in the fleet has its own
+`.caddis/kb/dashboard-performance-tracker.md` with real baseline measurements. The gap this closes
+is **re-measurement and re-judgment**, not first-time discovery.
+
+## Explicit scope guardrails — do not relax without a new conversation
+
+- **Read-only except the final tracker update.** No code changes, no schema changes, ever. The only
+  write this skill makes is a diffable update to the target app's own `dashboard-performance-tracker.md`.
+- **Dev by default.** Measuring against prod requires an explicit opt-in flag from the user AND, per
+  this project's convention for risky/hard-to-reverse actions, confirmation before hitting a live
+  service.
+- **Human-invoked, not scheduled.** Run this when a person chooses to — never wire it into a cron job
+  or background automation. It surfaces candidates; it does not enroll them.
+- **rs-kit is one of several possible recommendations, never the only output.** The checklist below
+  must be able to conclude "needs an index," "needs keyset paging," "needs gzip/trimmed fields,"
+  "not currently a candidate" — recommending rs-kit only for the specific aggregation shape.
+
+## The decision model — two gates, not one number
+
+**Gate 1 — time (mechanical).** `DASHBOARD-PERFORMANCE-STANDARD.md` Rule 6: the first, uncached load
+of any dashboard endpoint must finish in **under ~1 second**. The harness script below applies this
+gate automatically per endpoint. Passing gate 1 does **not** mean rs-kit — it just means "look closer."
+
+**Gate 2 — shape (judgment, applied by you the agent, never automated).** rs-kit fixes exactly one
+shape: a query that recomputes `O(all rows ever stored)` per request, against data that keeps
+growing. Time alone is not sufficient evidence — the fleet's own history proves it:
+
+| App | Cold time | Root cause | rs-kit? |
+|---|---|---|---|
+| serve-sight | worst >60s, 5 real breaches | recurring full-table aggregation | **YES** |
+| rev-sight (pre-fix) | 14s–60s+ across several endpoints | recurring full-table aggregation | **YES** |
+| appointment-assist | 10.3s | a single ~158MB LOB payload on 9.1k rows, not aggregation | **NO** — SQL aggregate + gzip |
+| nps-lens | 1.9s | cold JSON parse, no DB at all in prod | **NO** — warm the provider |
+| app-sight | 202ms | n/a — never crossed gate 1 | **NO** |
+
+A naive "slow ⇒ recommend rs-kit" tool would have wrongly flagged appointment-assist and nps-lens.
+That already happened once before the shape distinction was made explicit — don't repeat it.
+
+## Step 1 — build the endpoint list for this app
+
+The tracker files are semi-structured (page names + backtick route fragments in a markdown table),
+not a clean machine-parseable list — extract the list yourself, per app, each run:
+
+1. Read the target app's `.caddis/kb/dashboard-performance-tracker.md` — pull every "Page / endpoint"
+   entry, in particular anything marked ⏳ pending or not re-measured recently.
+2. If the app has a `UI_PAGE_GUIDE.md` (check root and `docs/reference/`), cross-check it for pages
+   **not yet in the tracker** — this is what catches drift, not just re-running the same old list. Not
+   every app has one; if it's missing, say so explicitly rather than silently only using the tracker.
+3. Write the result as a JSON file matching the harness's input shape:
+   ```json
+   [
+     {"name": "Historical Trends chart", "method": "GET", "path": "/api/trends/daily"},
+     {"name": "IW grid", "method": "POST", "path": "/raworkbench/investigation/query", "json": {}}
+   ]
+   ```
+4. Confirm with the user (or the app's own `run`/`webapp-testing` conventions) how to reach the dev
+   instance safely, and what auth the endpoints need (open / token / session cookie) — pass it via
+   `--header`.
+
+## Step 2 — start the dev server, then run the harness
+
+Use the app's own `run` skill/convention to start it — this skill does not start dev servers itself,
+only measures an already-reachable URL.
+
+**Use `127.0.0.1`, never the hostname `localhost`, in `--base-url`.** On Windows, Python's `urllib`
+resolves `localhost` dual-stack (tries IPv6 `::1` first) and can add a **spurious, rock-steady
+~1000ms** to every single request — cold *and* warm, on every endpoint including the framework's own
+static docs page. It looks exactly like a real, uniform perf problem (equal cold/warm, present on
+trivial routes too) and is not one. This cost real time during this skill's own validation (§
+Validating below) before `127.0.0.1` was substituted and the true numbers — sub-15ms — appeared. If a
+sweep ever comes back with a suspiciously uniform floor across unrelated endpoints, first time a
+`/docs` or `/openapi.json` route on the same base URL before trusting the data.
+
+```bash
+python <skill-dir>/scripts/perf_sweep.py --base-url http://127.0.0.1:<port> --endpoints endpoints.json
+python <skill-dir>/scripts/perf_sweep.py --base-url http://127.0.0.1:<port> --endpoints endpoints.json \
+  --header "Cookie: session=..." --output report.json
+```
+
+Cold = first request after the dev server's fresh start (or right after a cache-bust if it can't be
+restarted cheaply); warm = the immediate second request. The report flags gate-1 breaches and prints
+the cold/warm ratio — a big ratio with no cache in between already points at a query-shape problem,
+not a cache-TTL one. **A page that errors or times out is a finding, not a script failure** — it's
+printed as `[ERROR]`, never silently dropped.
+
+## Step 3 — apply the gate-2 checklist to every gate-1 breach
+
+Force these questions, in order, for each slow endpoint — don't skip to a verdict:
+
+1. **Does response size explain most of the time** (large payload, not a slow query)? → not rs-kit;
+   recommend trimming fields / gzip / virtualization.
+2. **Is the slow part parsing/serialization, not the DB round-trip?** → not rs-kit; recommend
+   caching/warming the parsed form (nps-lens precedent).
+3. **Does the query scale with total stored rows rather than the response size** — read the actual
+   SQL/query plan, not just the timing — **and is the same aggregation recomputed per request on data
+   that keeps growing?** → candidate for rs-kit.
+4. **Is it slow only at deep pagination (OFFSET)?** → not rs-kit; recommend keyset paging
+   (`exception_id`-style cursor, rev-sight R6/P3 precedent).
+5. **Is a specific WHERE clause unseekable** (function-wrapped column, NVARCHAR/VARCHAR param
+   mismatch)? → not rs-kit; recommend an index or a param-type fix.
+
+Link findings to real fleet precedent (the table above, the `nvarchar-param-varchar-column-scan`
+pattern, the keyset-paging work) rather than describing fixes in the abstract — every category here
+has already been solved once in this fleet.
+
+## Step 4 — update the tracker, diffably
+
+Update the target app's own `dashboard-performance-tracker.md` in place with the new measurements and
+verdicts, so drift becomes visible over time in the diff. Never silently overwrite it without the user
+being able to see a before/after. Print a summary alongside the file edit.
+
+## Validating this skill against known ground truth
+
+Before trusting a new app's output, or after changing the checklist, run the sweep against an
+already-known app and confirm it reproduces the **already-established, human-verified** conclusion:
+**app-sight** (202ms, should conclude "not a candidate") and **serve-sight** (known breach, should
+conclude "aggregation-shaped, rs-kit candidate" for the pages already identified). If the output
+disagrees with the known-good conclusion for either, that's a checklist bug — fix the checklist, don't
+rationalize the disagreement away.

package/bundles/antigravity-plugin/skills/dashboard-perf-sweep/scripts/perf_sweep.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Cold/warm HTTP timing harness for the dashboard-perf-sweep skill.
+
+Given a base URL and a list of endpoints, measures a COLD request (first hit) and a WARM
+request (immediately after) per endpoint, safely: a timeout or connection error on one endpoint
+is recorded as a finding, never a crash of the whole sweep (DASHBOARD-PERFORMANCE-STANDARD.md
+Rule 6 gate-1 mechanics; the huge cold/warm gap without a cache in between is itself diagnostic
+of a query-shape problem, not a cache-TTL one).
+
+This harness does NOT start dev servers or know anything about a specific app -- that's the
+`run` skill's job. It only measures a URL that is already reachable. stdlib-only (urllib), no
+install, matching the other caddis tool scripts (oss_review.py etc.).
+
+CLI:
+  python perf_sweep.py --base-url http://localhost:8000 --endpoints endpoints.json
+  python perf_sweep.py --base-url http://localhost:8000 --endpoints endpoints.json --output report.json
+  python perf_sweep.py --base-url http://localhost:8000 --endpoints endpoints.json --gate1-seconds 1.0
+
+endpoints.json shape (a JSON list):
+  [
+    {"name": "Historical Trends chart", "method": "GET", "path": "/api/trends/daily"},
+    {"name": "IW grid", "method": "POST", "path": "/raworkbench/investigation/query",
+     "json": {"filters": {}}, "headers": {"Authorization": "Bearer ..."}}
+  ]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_GATE1_SECONDS = 1.0  # DASHBOARD-PERFORMANCE-STANDARD.md Rule 6
+
+
+@dataclass
+class RequestResult:
+    ok: bool
+    status: int | None = None
+    elapsed_ms: float | None = None
+    error: str | None = None
+
+
+@dataclass
+class EndpointResult:
+    name: str
+    method: str
+    path: str
+    cold: RequestResult
+    warm: RequestResult | None = None
+    gate1_breach: bool = False
+
+
+@dataclass
+class SweepReport:
+    base_url: str
+    gate1_seconds: float
+    endpoints: list[EndpointResult] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "base_url": self.base_url,
+            "gate1_seconds": self.gate1_seconds,
+            "endpoints": [
+                {
+                    "name": e.name,
+                    "method": e.method,
+                    "path": e.path,
+                    "cold": asdict(e.cold),
+                    "warm": asdict(e.warm) if e.warm else None,
+                    "gate1_breach": e.gate1_breach,
+                }
+                for e in self.endpoints
+            ],
+        }
+
+
+def _do_request(
+    url: str,
+    method: str,
+    *,
+    json_body: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> RequestResult:
+    """One timed HTTP request. Never raises -- a timeout/connection/HTTP error becomes a
+    RequestResult with ok=False and a human-readable error, which is itself a sweep finding."""
+    data = None
+    req_headers = dict(headers or {})
+    if json_body is not None:
+        data = json.dumps(json_body).encode("utf-8")
+        req_headers.setdefault("Content-Type", "application/json")
+
+    req = urllib.request.Request(url, data=data, headers=req_headers, method=method)
+    start = time.perf_counter()
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            resp.read()
+            elapsed_ms = (time.perf_counter() - start) * 1000.0
+            return RequestResult(ok=True, status=resp.status, elapsed_ms=elapsed_ms)
+    except urllib.error.HTTPError as exc:
+        # An HTTP error status still completed a round trip -- timing is a real finding.
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        return RequestResult(ok=False, status=exc.code, elapsed_ms=elapsed_ms, error=f"HTTP {exc.code}")
+    except urllib.error.URLError as exc:
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        return RequestResult(ok=False, elapsed_ms=elapsed_ms, error=f"connection error: {exc.reason}")
+    except TimeoutError:
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        return RequestResult(ok=False, elapsed_ms=elapsed_ms, error=f"timeout after {timeout}s")
+
+
+def sweep_endpoint(
+    base_url: str,
+    endpoint: dict[str, Any],
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    gate1_seconds: float = DEFAULT_GATE1_SECONDS,
+    warm: bool = True,
+    extra_headers: dict[str, str] | None = None,
+) -> EndpointResult:
+    method = endpoint.get("method", "GET").upper()
+    path = endpoint["path"]
+    url = base_url.rstrip("/") + path
+    headers = dict(extra_headers or {})
+    headers.update(endpoint.get("headers", {}))
+    json_body = endpoint.get("json")
+
+    cold = _do_request(url, method, json_body=json_body, headers=headers, timeout=timeout)
+    warm_result = None
+    if warm:
+        warm_result = _do_request(url, method, json_body=json_body, headers=headers, timeout=timeout)
+
+    gate1_breach = bool(cold.ok and cold.elapsed_ms is not None and cold.elapsed_ms / 1000.0 > gate1_seconds)
+    return EndpointResult(
+        name=endpoint.get("name", path),
+        method=method,
+        path=path,
+        cold=cold,
+        warm=warm_result,
+        gate1_breach=gate1_breach,
+    )
+
+
+def sweep(
+    base_url: str,
+    endpoints: list[dict[str, Any]],
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    gate1_seconds: float = DEFAULT_GATE1_SECONDS,
+    warm: bool = True,
+    extra_headers: dict[str, str] | None = None,
+) -> SweepReport:
+    report = SweepReport(base_url=base_url, gate1_seconds=gate1_seconds)
+    for endpoint in endpoints:
+        report.endpoints.append(
+            sweep_endpoint(
+                base_url,
+                endpoint,
+                timeout=timeout,
+                gate1_seconds=gate1_seconds,
+                warm=warm,
+                extra_headers=extra_headers,
+            )
+        )
+    return report
+
+
+def format_report(report: SweepReport) -> str:
+    lines = [f"Sweep: {report.base_url}  (gate 1 = {report.gate1_seconds}s cold, uncached)", ""]
+    for e in report.endpoints:
+        if not e.cold.ok:
+            lines.append(f"  [ERROR]  {e.method:5s} {e.path:45s}  {e.cold.error}")
+            continue
+        flag = "SLOW " if e.gate1_breach else "     "
+        cold_s = f"{e.cold.elapsed_ms:8.1f}ms"
+        warm_s = f"{e.warm.elapsed_ms:8.1f}ms" if e.warm and e.warm.ok else "n/a"
+        gap = ""
+        if e.warm and e.warm.ok and e.cold.elapsed_ms and e.warm.elapsed_ms:
+            ratio = e.cold.elapsed_ms / max(e.warm.elapsed_ms, 0.01)
+            if ratio > 3:
+                gap = f"  (cold/warm {ratio:.1f}x -- likely query-shape, not cache-TTL)"
+        lines.append(f"  {flag}{e.method:5s} {e.path:45s}  cold={cold_s}  warm={warm_s}{gap}")
+    breaches = [e for e in report.endpoints if e.gate1_breach]
+    errors = [e for e in report.endpoints if not e.cold.ok]
+    problems = breaches + errors
+    lines.append("")
+    lines.append(
+        f"{len(problems)}/{len(report.endpoints)} endpoint(s) have a problem "
+        f"({len(breaches)} slow, {len(errors)} errored/timed out -- a timeout is a WORSE "
+        f"signal than a gate-1 breach, not a lesser one)."
+    )
+    if problems:
+        lines.append("Not itself a rs-kit verdict -- apply the shape checklist (SKILL.md) next.")
+    return "\n".join(lines)
+
+
+def _parse_header(value: str) -> tuple[str, str]:
+    if ":" not in value:
+        raise argparse.ArgumentTypeError(f"--header must be 'Key: Value', got {value!r}")
+    key, _, val = value.partition(":")
+    return key.strip(), val.strip()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--base-url", required=True, help="e.g. http://localhost:8703")
+    parser.add_argument("--endpoints", required=True, help="path to a JSON file (see module docstring)")
+    parser.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT_SECONDS)
+    parser.add_argument("--gate1-seconds", type=float, default=DEFAULT_GATE1_SECONDS)
+    parser.add_argument("--no-warm", action="store_true", help="skip the warm (second) request")
+    parser.add_argument("--header", action="append", default=[], type=_parse_header,
+                         help="extra header applied to every request, repeatable: --header 'Cookie: session=...'")
+    parser.add_argument("--output", help="also write the JSON report to this path")
+    args = parser.parse_args(argv)
+
+    with open(args.endpoints, encoding="utf-8") as f:
+        endpoints = json.load(f)
+    if not isinstance(endpoints, list):
+        print(f"[FAIL] {args.endpoints} must contain a JSON list of endpoint objects", file=sys.stderr)
+        return 2
+
+    report = sweep(
+        args.base_url,
+        endpoints,
+        timeout=args.timeout,
+        gate1_seconds=args.gate1_seconds,
+        warm=not args.no_warm,
+        extra_headers=dict(args.header),
+    )
+
+    print(format_report(report))
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            json.dump(report.to_dict(), f, indent=2)
+        print(f"\nWrote {args.output}")
+
+    breaches = [e for e in report.endpoints if e.gate1_breach]
+    errors = [e for e in report.endpoints if not e.cold.ok]
+    return 1 if (breaches or errors) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/antigravity-plugin/skills/explainer-doc/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: explainer-doc
+context: fork
+description: Write a document that hands off work to a team who did NOT do the investigation — an external vendor, another team, a contractor — and who must be able to act on it alone. Use when the user says "write a spec for the X team", "document this for someone outside the team", "explainer doc", "implementation spec for a vendor", "hand this off to Y", or is about to write a design doc whose primary reader did not live through the debugging/design process. NOT for internal specs where the reader already has full context (use technical-writing or writing-plans instead) — this is specifically for the "stranger must follow it alone" case.
+---
+
+# explainer-doc — write for the reader who has no other context
+
+A spec written by the people who did the investigation is unreadable by the team who must implement
+it. The authors compress away the reasoning, so every design choice looks arbitrary, and the reader
+either follows it blindly or argues with it. **The fix is not "add more detail" — it is to lead with
+*why*, and to make the document survive being read alone.**
+
+Proven in anger on a Genesys→ETL cutover spec handed to an external vendor team. The user's verdict:
+*"nailed it — the document was perfect, simple, this should be the standard for explainer documents."*
+Reference implementation to study: `serve-sight/docs/genesys-cutover/etl-implementation-spec.md` (full
+spec) and `pega-cticallid-change-request.md` (the same pattern compressed to one page for a single ask).
+
+## When this is NOT the right skill
+
+If the reader already lived through the investigation (a teammate, your future self, an internal
+handoff with shared context), use `technical-writing` or `writing-plans` instead — those are lighter
+and don't need the "assume zero shared context" discipline below. Reach for `explainer-doc` specifically
+when the reader is a **stranger to the problem**: an external vendor, a different team, a contractor,
+anyone who will act on the document with no one in the room to ask.
+
+## The shape — in order. The order IS the pattern
+
+Do not reorder these. Each section's position is load-bearing: later sections lean on earlier ones for
+their justification, and a reader working top-to-bottom needs the "why" before the "what."
+
+| § | Section | Why it must come here |
+|---|---|---|
+| 1 | **Why this exists** — what broke, in a diagram | Every later decision is justified by this. Lead with the failure, not the solution. |
+| 2 | **What we're asking for, in one picture** + a size table | The reader decides here whether the ask is reasonable. Include what you are explicitly **not** asking for. |
+| 3 | **Understanding the source data** — the 3-5 things that catch people out | Each one should have already caused a real bug. Not a data dictionary. |
+| 4 | **The one thing that matters most** | Usually not the new build. Say so plainly, with the number that proves it. |
+| 5 | **Where it runs** + access needed | The blocker nobody writes down until the first deploy fails. |
+| 6 | **What to build**, with the reasoning *beside* each choice | Not in an appendix. Next to the DDL / the query / the config. |
+| 6b | **Changes to what already exists** | Always under-specified. Ask "what did I only half-mention?" — this is where the gaps hide. |
+| 7-8 | The actual implementation (extract/build queries, load procedure, etc.) | |
+| 9 | Schedule / retention / first load | The one-off backfill is always forgotten. |
+| 10 | **Validation, with EXPECTED VALUES** | "Run this, expect ~64%" beats "verify the data." |
+| 11 | Priority · acceptance (who signs off) · **what we excluded** | The exclusion list stops speculative building. |
+| 12 | **Glossary** | Every acronym, inline. Not a link. |
+
+Adapt section names to the domain (this table is ETL-flavored from its origin; a UI handoff, an API
+contract, or an infra runbook will rename §6-9) — but keep the **order and the intent of each slot**.
+
+## The ten rules
+
+1. **Self-contained.** If the reader needs another document to follow this one, the document has
+   failed. Companions are optional background, stated as such — never load-bearing.
+2. **Lead with the failure mode, not the solution.** State what actually went wrong, concretely, before
+   proposing anything. Everything cautious later inherits its justification from that paragraph.
+3. **Reasoning beside the artefact, not in an appendix.** "Cluster on the date not the GUID" with the
+   3-row comparison table right there. An appendix is never read.
+4. **Every number carries its measurement date and a way to reproduce it.** "1.4% of reality (measured
+   2026-07-14, `SELECT ...`)" — not "a small fraction."
+5. **Say what you are NOT asking for.** Prevents speculative work and pre-answers "why not X?" before
+   it's asked.
+6. **Name what is not the reader's fault.** If a gap traces to a third system or a decision made
+   elsewhere, say so explicitly. Saves the reader a week of misdirected chasing and buys credibility for
+   the rest of the document.
+7. **Diagrams for the shape, tables for the detail, prose only for judgement.** No diagram should repeat
+   what a table already says better.
+8. **Validation states expected values.** "It ran" and "it is right" must be two different checks — give
+   the reader the number to compare against.
+9. **Route by owner.** If an item belongs to a third team, mark it as theirs, explicitly, in the document
+   — don't let it read as part of the reader's scope.
+10. **Glossary inline.** The reader will not follow a link mid-implementation; every acronym gets defined
+    where it's used, plus a glossary section as the fallback lookup.
+
+## Process
+
+1. **Confirm the reader.** Ask (or infer from context) who this is actually for and how much they
+   already know. If they have real shared context, stop and suggest `technical-writing`/`writing-plans`
+   instead — this skill's discipline is overhead they don't need.
+2. **Draft §1 first, alone, and get it right before writing anything else.** Every other section's
+   justification traces back to it. If you can't state the failure mode plainly and concretely, the
+   rest of the document will inherit that vagueness.
+3. **Write the shape table above as your outline**, adapting section names to the domain, then fill it
+   in top to bottom. Keep reasoning next to the artefact it justifies (rule 3), not in a separate
+   "design decisions" section.
+4. **Before sending, ask the two questions below** — they are an exit gate, not a suggestion.
+
+## The two-question exit gate
+
+Ask both, honestly, before the document ships:
+
+- **"Could someone who has read nothing else follow this end to end?"** If the answer requires "well,
+  they'd also need to know X" — X is either missing or should be a stated, explicit companion doc.
+- **"What did I mention once and never specify?"** This is the question that surfaces the gaps — in the
+  origin case it found an entire missing section (§6b, changes to existing infrastructure) that had been
+  gestured at once and never actually written.
+
+If either question fails, fix the document — don't ship it and hope the reader asks.

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.14",
+  "version": "1.3.20",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/cross-review/SKILL.md

@@ -28,10 +28,13 @@ churn — the preset table in `oss_review.py` is the one place to edit a rename,
 `REVIEW_BASE_URL` always win, so you can point at any new id without touching code.
 
 ## How to run
-From the repo root (the tool ships at `.github/tools/oss_review.py`):
+From the repo root. Locate the tool, in order:
+- `.github/tools/oss_review.py` — this project vendors its own copy.
+- `${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py` — the plugin-bundled copy (every Claude Code
+  install has this; use it whenever the project has no local copy).
 ```
-python .github/tools/oss_review.py                       # review the working tree (staged+unstaged)
-python .github/tools/oss_review.py --range origin/main..HEAD   # review a branch's commits
+python <resolved-path>/oss_review.py                       # review the working tree (staged+unstaged)
+python <resolved-path>/oss_review.py --range origin/main..HEAD   # review a branch's commits
 ```
 Optional flags: `--cwd <repo>`, `--base-url <url>`, `--model <id>` (override the env).
 

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.41",
+  "poolVersion": "1.3.47",
   "bundles": {
-    "antigravity-plugin": "1.3.41",
-    "antigravity-plugin-extras": "1.3.14"
+    "antigravity-plugin": "1.3.47",
+    "antigravity-plugin-extras": "1.3.20"
   }
 }

package/dist/cli.js

@@ -5167,7 +5167,7 @@ var claudeAdapter = {
 };
 
 // src/agents/agy.ts
-import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync2, existsSync as existsSync2, mkdtempSync, cpSync, rmSync } from "fs";
 import os from "os";
 import path2 from "path";
 init_pkg();
@@ -5239,6 +5239,25 @@ function shortenHome(target) {
   const home = os.homedir();
   return target.startsWith(home) ? path2.join("~", target.slice(home.length)) : target;
 }
+function stageForAgy(bundleDir) {
+  if (!bundleDir.includes("@")) {
+    return { installPath: bundleDir, cleanup: () => {
+    } };
+  }
+  const staged = mkdtempSync(path2.join(os.tmpdir(), "caddis-agy-"));
+  const dest = path2.join(staged, path2.basename(bundleDir));
+  cpSync(bundleDir, dest, { recursive: true });
+  return {
+    installPath: dest,
+    // Best-effort: a stray temp dir left behind is harmless clutter, not a failure.
+    cleanup: () => {
+      try {
+        rmSync(staged, { recursive: true, force: true });
+      } catch {
+      }
+    }
+  };
+}
 async function drive2(_action, options) {
   const detected = await detect2();
   if (!detected.present) {
@@ -5253,12 +5272,12 @@ async function drive2(_action, options) {
       message: `the ${BUNDLE} bundle is missing from this package \u2014 reinstall @caddis/cli`
     };
   }
-  const planned = [{ cmd: BIN2, args: ["plugin", "install", bundle] }];
+  const planned = [{ cmd: BIN2, args: ["plugin", "install", bundle], bundleDir: bundle }];
   const extrasInstalled = extrasStatusFromHome(os.homedir()).installed;
   if (options.extras === true || extrasInstalled) {
     const extrasBundle = bundlePath(EXTRAS_BUNDLE);
     if (extrasBundle) {
-      planned.push({ cmd: BIN2, args: ["plugin", "install", extrasBundle] });
+      planned.push({ cmd: BIN2, args: ["plugin", "install", extrasBundle], bundleDir: extrasBundle });
     } else if (options.extras === true) {
       return {
         ok: false,
@@ -5272,25 +5291,34 @@ async function drive2(_action, options) {
     return {
       ok: true,
       skipped: true,
+      // Show the logical bundle path, not a staged temp copy that was never created.
       steps: planned.map((s) => ({ command: formatCommand(s.cmd, s.args), ok: true, code: null })),
       message: "dry run \u2014 nothing executed"
     };
   }
-  const steps2 = [];
-  for (const step of planned) {
-    const command = formatCommand(step.cmd, step.args);
-    const result = await run(step.cmd, step.args);
-    steps2.push({
-      command,
-      ok: result.ok,
-      code: result.code,
-      output: result.ok ? void 0 : (result.stderr || result.stdout || result.failure || "").trim().split(/\r?\n/).slice(-3).join("\n")
-    });
-    if (!result.ok) {
-      return { ok: false, skipped: false, steps: steps2, message: `\`${command}\` failed` };
+  const cleanups = [];
+  try {
+    const steps2 = [];
+    for (const step of planned) {
+      const command = formatCommand(step.cmd, step.args);
+      const staged = stageForAgy(step.bundleDir);
+      cleanups.push(staged.cleanup);
+      const execArgs = [...step.args.slice(0, -1), staged.installPath];
+      const result = await run(step.cmd, execArgs);
+      steps2.push({
+        command,
+        ok: result.ok,
+        code: result.code,
+        output: result.ok ? void 0 : (result.stderr || result.stdout || result.failure || "").trim().split(/\r?\n/).slice(-3).join("\n")
+      });
+      if (!result.ok) {
+        return { ok: false, skipped: false, steps: steps2, message: `\`${command}\` failed` };
+      }
     }
+    return { ok: true, skipped: false, steps: steps2 };
+  } finally {
+    cleanups.forEach((fn) => fn());
   }
-  return { ok: true, skipped: false, steps: steps2 };
 }
 var agyAdapter = {
   id: "agy",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",