| name | onboard-dependency |
| description | Onboard any new external dependency before using it — research the official docs, vendor them as the single source of truth, then generate a blocking guard. Use when adding or first using any library, framework, SDK, API, or CLI tool; when editing package.json / requirements.txt / pyproject.toml / go.mod / Cargo.toml; or when the user mentions adopting a new tool. This is a rail, not advice — the trigger is unconditional, never "when uncertain". |
Onboard a dependency
The rail
Trigger is deterministic, not subjective. The moment a new dependency enters the project — any library, framework, SDK, API, or CLI — you run this pipeline before writing code against it. There is no "I already know this one." Memory lies; APIs move.
[1 RESEARCH] official docs / changelog / latest version (search the live web — never from memory)
↓
[2 VENDOR] save the official pages into docs/official/<dep>/ (copy, do NOT symlink)
↓
[3 RULES] extract 5–10 "official correct usage" rules + anti-patterns
↓
[4 GUARD] add/extend a PreToolUse hook that blocks edits violating those rules
Steps
- Research (live). Find the current version, the official docs, and the recommended usage — not the first StackOverflow answer. Note version + retrieval date. If a sibling
/grill is running, feed it: "latest is X, the options are A/B/C, recommend A — which?"
- Vendor. Write the official reference into
docs/official/<dep>/ with a header line: > source: <url> · version: <v> · retrieved: <date>. Vendoring (not symlinking) survives clean clones and CI. Record it in docs/official/INDEX.md.
- Extract rules. From the vendored docs, list the deterministic "always do X / never do Y" facts you can grep for (banned imports, required call shapes, deprecated APIs). Judgment calls go to human review, not the hook.
- Guard. Don't hand-write a guard script — append rules to
.claude/usage-rules.tsv (the
generic usage-guard hook reads it; the hook code never changes). One TAB-separated line per
rule, grounded in the actually-installed source (venv site-packages / node_modules .d.ts),
not just docs:
exts<TAB>severity<TAB>regex<TAB>message<TAB>unless(optional)
exts = comma-separated extensions (py or ts,tsx,js,jsx); severity = block (unambiguous
bug) or warn (fuzzy); regex = an ERE grep can match in changed content; unless = an optional
ERE exemption. Prefer block only for high-confidence patterns (deprecated/removed APIs, injection,
wrong-field bugs); everything fuzzy is warn. See rules/starter-usage-rules.tsv for examples.
Frameworks need a CONSIDERATIONS doc
A framework (Next.js, FastAPI, a major SDK) is not just "a dependency" — adopting it commits
architecture. So beyond vendoring its docs, write docs/official/<framework>/CONSIDERATIONS.md
covering the footguns people miss: runtime (Node vs Edge), rendering/caching model, auth
integration, secret exposure, streaming, deploy target, i18n/SEO, version migration. Derive it
from the latest official docs, not memory — frameworks move fast.
Resist the reflex to call thoroughness "overkill": at a production target, this research is
required, not optional. And design to the target level — leave seams for what's coming
(global auth, billing) even if the current level doesn't implement them yet.
Feature survey — choose deliberately, don't default to the basics
LLMs wire the two features they remember and ignore the rest. Before building on a dependency,
enumerate its FULL feature surface (from the official docs at the pinned version) and tag each
USE / SKIP / MAYBE with a one-line reason for this project. Put the survey in
CONSIDERATIONS.md and end it with a "minimum viable feature set we actually wire". You can't
choose what you never listed.
CONSIDERATIONS.md must carry a Decisions ledger
The most dangerous gap is the decision the agent never surfaced — a load-bearing choice the
SDK has an official pattern for, silently skipped. Kill it with a visible ledger. Every
framework/SDK CONSIDERATIONS.md ends with a ## Decisions (official SDK patterns) table:
| concern | official pattern / options | our decision | status |
|---|
Enumerate the load-bearing concerns the SDK forces you to choose on — typically memory /
conversation history, state injection, tool registration, error/retry, streaming, usage &
cost limits, auth, caching, deployment (tailor per SDK). An undecided row is TBD (visible),
never absent. No silent skips. Proactively raise these before building — the user shouldn't
have to notice they were missing.
Deployment-level calibration
Read docs/agents/deployment-level.md: current scales the guard (block/warn/off), target
scales the considerations + architectural seams. Build for target, run at current.
| L0 local / prototype | L1 staging / internal | L2 production |
|---|
| Research | official quickstart only | full | full + changelog/migration review |
| Vendor | skip (link in INDEX) | vendor key pages | vendor + version-pin |
| Guard | off | warn | block (exit 2) |
If deployment-level.md is missing, stop and ask the level — never assume.
Checklist
