add-dep command

Command

Vet a new or changed third-party dependency for license, provenance, and supply-chain risk before any install runs.

Invoke it

Claude Code/ca:add-dep

Codex$ca-add-dep

Pi/ca-add-dep

Availability is read from each shipped host catalog. Preview-only commands are marked on the page.

What it does

Reviews a new or changed third-party dependency before adoption. The read-only dependency-reviewer uses the target repository’s .codearbiter/security-controls.md and .codearbiter/tech-stack.md for license, source, maintenance, audit and stack requirements. It produces findings without running installs or editing files.

For adoption, clearance is followed by confirmation of the exact install command. The installed version must match the review; manifest and lockfile changes are delivered together. Unknown or denied licenses, unapproved sources and unresolved supply-chain concerns must not be presented as clearance. Follow the project’s declared advisory thresholds and documented justifications.

The gate is orchestrator-enforced, not hook-enforced. There is no pre-bash rule blocking every package-manager install outside this route; H-07 is a manifest-change advisory.

Usage

/ca:add-dep <package[@version]>

Omitting the version evaluates the latest available. Confirm the resolved exact version before execution. Codex uses $ca-add-dep; Pi uses /ca-add-dep.

One-time inspection

The command has a bounded ephemeral-tool exception, not a separate public command. It applies only when the operator names that specific tool in the current session, it runs once for inspection or analysis, and no manifest, lockfile or committed artifact changes. Adopting the tool in scripts, hooks, CI or a base image does not qualify. Unclear scope takes full review.

Pin the exact version, use the approved registry, and confirm the exact command before running. The current npm one-time path specifies https://registry.npmjs.org, excluding git+, file: and non-TLS sources. Prefer a system temporary directory for cache and reports. This is not a sandbox, a network restriction, or a guarantee about third-party code.

Verify manifest and lockfile state before and after, account for other artifact changes, and report the command and output location. A manifest or lockfile write stops this path and routes to adoption review. Existing dirty files need content comparisons, not only status-code checks. An inspection approval does not authorize recurring execution or future adoption.

Example

This is an illustrative request, not a captured run or a current package assessment:

Use jscpd once for this duplicate-code investigation without adopting it.
Propose a pinned command, registry and temporary output location.
Wait for my confirmation. Preserve project artifacts and verify the result.

No version or safety verdict is supplied by this example. The exact command still needs to be resolved and confirmed. Follow Add a dependency safely for the adoption-versus-inspection decision and before/after verification.

When to reach for it

Use it for dependency adoption or the bounded one-time exception. Removing a dependency or updating one as part of a code change belongs in fix or feature; dependency changes receive review in the PR lane. Ask package questions directly when no execution is intended. The legacy btw reference in the embedded source is not a prerequisite for a read-only question.

For the complete source-traced sequence and its actual endpoint, use the operator guide and Compare workflow routes.

Gates

Gate	When	Effect
dependency review	before dependency adoption through this command	the dependency-reviewer must clear the package before the separately confirmed install; a bounded one-time inspection follows the explicit exception below

Route context

Find this entry in the workflow atlas. Compare its related teaching maps, host spelling and context inputs. The exact procedure below remains the owner.

Source

Source — plugins/ca/commands/add-dep.md (v3.7.0)

---
description: Vet a new or changed third-party dependency for license, provenance, and supply-chain risk before any install runs.
argument-hint: "<package[@version]>"
---

# /ca:add-dep — dependency review

For every security policy reference below, follow `${CLAUDE_PLUGIN_ROOT}/includes/knowledge.md`
("Read security policy before a security decision"): select the repository's
context format, read the complete policy from exact `CTX-SECURITY-CONTROLS`
records in HTML mode or the full Markdown controls in Markdown mode, and read
operative scope blocks when applicable. Required policy that is missing or
unreadable blocks a security decision; scope blocks alone are not full policy.

Gate a new or changed third-party dependency through review before it lands. When you route through
this command, the orchestrator runs no install until the `dependency-reviewer` agent clears the
package. Specify the exact version if you have one; without one, the reviewer evaluates the latest
available version.

## Routes to

The `dependency-reviewer` agent (`${CLAUDE_PLUGIN_ROOT}/agents/dependency-reviewer.md`). The agent
reads `${CLAUDE_PROJECT_DIR}/.codearbiter/security-controls.md` (allowed/denied licenses, provenance
and supply-chain policy) and the format-selected tech-stack document
(`${CLAUDE_PLUGIN_ROOT}/includes/knowledge.md`; stack fit, dependency
manager) to judge the package.

After the agent clears it, the orchestrator surfaces the install command for confirmation. The lock
file change is committed alongside the manifest change — never one without the other.

## When NOT to use

- Removing a dependency → `/ca:fix` or `/ca:feature` with the change described.
- Updating an existing dependency as part of a code change → `/ca:feature` / `/ca:fix`; manifest
  changes route to review at `/ca:pr`.
- Asking about a package without installing it → ask it directly; no command needed.

## Ephemeral tool run — one invocation, nothing adopted

A one-time developer tool is not a dependency, and reviewing it as one is what
issue #346 records going wrong: a duplicate-code investigation was interrupted
and pushed toward project-dependency review for `jscpd`, which the operator had
explicitly said must never be listed as a dependency. The redirect loop then
reached for `/ca:override`, a bypass invented to cover missing coverage. This
section is that coverage.

**The distinction is the dependency GRAPH, not the download.** Adopting or
changing anything that enters `package.json`, a lockfile, or a base image is the
review above, unchanged. Running a pinned tool once, against the repository,
adopting nothing, is this.

Route here when ALL of these hold. If any is unclear, it is a dependency and
takes the full review:

1. The operator asked for this specific tool, by name, in this session.
2. It runs ONCE, for inspection or analysis. It is not wired into a script, a
   hook, or CI.
3. Nothing it does may change a manifest, a lockfile, or a committed artifact.

Then:

- **Pin the exact version.** `npx jscpd@4.0.5 .`, never bare `npx jscpd` — an
  unpinned invocation resolves to whatever was published this morning, which is
  the supply-chain exposure the review exists for and the one part of it that
  still applies at full strength.
- **Use the approved registry.** `https://registry.npmjs.org` is the only one
  (`security-controls.md`); no `git+`, no `file:`, no non-TLS source.
- **Confirm before running**, naming the exact command. One approval, not a
  review — the operator has already made the adoption decision, which is "no".
- **Isolate what you can.** Prefer a cache directory under the system temp dir
  over the project tree, and write any report there too, so the run leaves no
  residue a later commit could pick up.
- **Report what ran** — the pinned command and where its output went.

**Hard gate: MUST NOT modify a manifest or a lockfile.** If the tool writes one,
that is adoption, and it stops here and routes to the review above. Verify
rather than trust: `git status --porcelain` over the manifest and lockfile paths
must be unchanged after the run. A tool that requires adoption to run at all is
a dependency, and saying so is the correct answer.

This is a bounded carve-out inside this command, not a command of its own
(ADR-0023). A new command would add a public surface — the catalog, the Pi
command catalog, the README counts, the site sidebar — to govern an action whose
whole definition is that it changes nothing.

## Hard gate

MUST NOT install before `dependency-reviewer` clears the package. BLOCK on a denied license or any
unresolved supply-chain or provenance concern.

This gate is **orchestrator-enforced, not hook-enforced**: unlike the crypto/secret gate
(`pre-bash.py` H-09b/H-10b), there is no pre-bash rule that blocks a bare `npm`/`pip`/`yarn`/`pnpm
install` typed outside this command. The discipline depends on routing installs through `/ca:add-dep`.
A hook-level install block (parallel to the security-gate marker) would be a stronger posture, but is a
deliberate behavior change — a possible future enhancement, not the current contract.

View in repo