`references/adoption-rubric.md`

75 lines
# Adoption rubric — should Steve actually add this?

Guri Singh's feed is a firehose of "someone open-sourced X". Most picks are
noise for *this* stack. The job isn't to relay hype — it's to answer, per
candidate: **adopt, watch, or skip**, with a reason. Score each candidate on the
six dimensions below (0–3 each, 18 max).

## Dimensions

1. **Stack fit (0–3)** — does it serve something Steve actually runs? High:
   Claude Code skills/subagents/hooks, MCP servers, catalog/scraper/pricing
   tooling, cost/observability for Claude, marketing/social automation, DW
   commerce, directory builders. Low: generic web-dev boilerplate, crypto,
   things with no path into his workflow.
2. **Novelty vs. what he already has (0–3)** — 3 = fills a real gap; 0 = he
   already has an equal-or-better skill/agent. **Always run the dedupe check
   below before scoring this.**
3. **Leverage (0–3)** — does it save real hours or unlock revenue, or is it a
   toy? Favor "measurable time back" over "feels productive" (Steve's own
   theater-vs-real test).
4. **Install/run cost (0–3, higher = cheaper)** — 3 = one paste / `npx`, local,
   no new paid API; 0 = heavy infra, new metered API, or a rewrite to fit.
   Note any per-call cost explicitly (always-show-costs rule).
5. **Trust & license (0–3)** — stars/traction, **license present** (MIT/Apache
   good; `NONE`/`NOASSERTION` is a flag), recently maintained (`days_since_push`
   low, not archived), no obvious security smell. Unlicensed + unmaintained caps
   this at 1.
6. **Safety/gating exposure (0–3, higher = safer)** — 3 = read-only/local, no
   secrets, no outbound writes; 0 = wants prod creds, sends email, touches DNS,
   writes to customer-facing systems, or auto-executes on a schedule. Low scores
   here don't kill a pick — they route it to pending-approval (see Gating).

**Verdict bands:** ≥14 → **ADOPT** (draft the install memo). 9–13 → **WATCH**
(log it, revisit if it gains traction). ≤8 → **SKIP** (one-line why).

## Dedupe against Steve's existing kit (do this before scoring novelty)

Steve already has 200+ skills and dozens of agents. Before recommending
anything, check for an existing equivalent:

```bash
ls ~/.claude/skills/ | grep -i "<keyword>"
grep -ril "<capability keyword>" ~/.claude/skills/*/SKILL.md 2>/dev/null
```

Also sanity-check the cabinet/agents and CNCP. Examples of "he already has it":
cost tracking → `cost-tracker`; token-spend analysis → overlaps `token-use`;
multi-agent orchestration → the cabinet + `Workflow`; research → `last30`,
`deep-research`, `web-extract`; code review → `claude-codex`, `code-review`.
If an equivalent exists, the useful output is a **diff** ("codeburn breaks spend
down by tool+MCP, which `cost-tracker` doesn't"), not a redundant recommend.

## Gating — what the scout may and may NOT do

**Discovery, retrieval, enrichment, scoring, and writing the shortlist are
reversible and run freely.** Everything that changes Steve's machine or spends is
gated — draft it to `~/.claude/yolo-queue/pending-approval/` with an
APPROVE/REVISE/BLOCK block; never auto-run:

- Installing a skill/plugin (`git clone`, `/plugin install`, paste-into-`.claude`).
- `npx`/running an unfamiliar tool that executes code or reads `~/.claude`.
- Anything needing a new paid API key or that spends.
- Anything the tool itself does that is customer-facing / destructive / outbound.

The scout's deliverable is a **decision-ready shortlist**, not an installed tool.
Adoption is Steve's call.

## Output shape (per run)

Produce a ranked table: `Tool | Repo (stars, license, last-push) | What it does |
Category | Dedupe (have/gap) | Score | Verdict | 1-line reason`. Then, for each
ADOPT, a short pending-approval memo: what it is, why it fits, exact install
steps, cost, risks, and the APPROVE/REVISE/BLOCK line. Log genuine wins (a pick
that gets adopted) — not the scan itself.