@orchestrator-claude/definitions

Built-in definitions (agents, skills, hooks, workflows, KB seeds) for the Orchestrator ecosystem, distributed as an npm package and installed into ~/.claude/* via orch-defs install.

CLI

npx orch-defs <command>

| Command | Purpose | |---|---| | install | Materialize agents/skills/hooks/personas/kb into ~/.claude/*, wire hooks into ~/.claude/settings.json, and register MCP servers via claude mcp add --scope user (RFC-040 ④) | | seed | Seed a project's definitions into the orchestrator API (Postgres) | | diff | Compare the local package's definitions against a target | | verify | Verify manifest checksums | | info | Show manifest metadata |

Run npx orch-defs install --help for the full flag reference and the in-context risk notes summarized below.

install: two configuration owners (RF-006)

orch-defs install writes to two physically distinct configuration surfaces, each owned by a different Claude Code subsystem, and never attempts to unify them:

| Surface | Owner | How the installer writes it | |---|---|---| | ~/.claude.json (MCP server registry) | Internal Claude Code state — rewritten live by the running CLI, ~200KB, mostly telemetry | Never written directly. The installer only ever invokes claude mcp add --scope user <name> ... and checks claude mcp list first for idempotency. | | ~/.claude/settings.json (hooks block) | Documented contract surface (published precedence, stable schema) | Read-modify-write JSON merge — existing non-orchestrator keys survive. |

Why not unified? ~/.claude.json is Claude Code's own live-rewritten internal state file — editing it directly races with the running CLI and risks corruption/state loss (~/.claude/.mcp.json is a dead path that Claude Code never reads, confirmed both in official docs and empirically). By contrast, ~/.claude/settings.json is a documented, stable contract surface safe to edit directly. Collapsing both into one "installer config" write path would hide this differing discipline and reintroduce the exact corruption risk the split is designed to avoid (spec RF-006 / RF-004).

The codebase enforces this split structurally: MCP registration (McpRegistrar) and hooks wiring (HooksWirer) are two separate modules, not one generic "write config" function that treats both files as interchangeable.

install: MCP server registration — dual-mode (--monorepo-root vs bare)

The stdio MCP servers (orchestrator-tools, orchestrator-extended, perplexity) are declared in the bundled mcp-servers.json, whose stdio args carry a {{MONOREPO_ROOT}} placeholder. orch-defs install resolves that placeholder in one of two modes (RFC-040 §16, spec ADR-007 + ADR-P001):

| Mode | Trigger | Resolution | |---|---|---| | dev-checkout | --monorepo-root <path> given | In-place substitution of the placeholder with <path> — byte-for-byte the original ADR-007 behavior. Use when running against a monorepo checkout on disk. | | npm-user (self-contained) | --monorepo-root absent | Resolves the real installed location of @orchestrator-claude/mcp-server via createRequire(import.meta.url).resolve() and rewrites the whole placeholder-bearing arg to it. No monorepo on disk required. | | fallback | resolution fails (no hoisting, Yarn PnP, …) | Skips the servers that need the placeholder + emits a warning (Use --monorepo-root to register them); placeholder-free servers still register. |

Self-contained by construction. @orchestrator-claude/mcp-server is a real runtime dependency of this package (not a peer/dev dep), so a plain npm i -g @orchestrator-claude/definitions pulls the MCP backbone with it and the npm-user resolution above finds it on disk. mcp-server in turn depends on @orchestrator-claude/project-root-resolver — published to npm since v3.33.0 (S388) — so the whole chain resolves from the registry with no monorepo checkout.

The files[] allowlist ships the two runtime-required, non-dist assets the installer reads at runtime — mcp-servers.json and hooks-settings-template.json. Omitting them (the pre-S387 bug) made a real tarball install ENOENT while --dry-run masked it. --dry-run does not prove a tarball — only npm pack + an isolated install does.

ESM note: this package is "type": "module", so bare require.resolve is unavailable; createRequire(import.meta.url) synthesizes a CJS-style resolver. import.meta.resolve is deliberately not used (ADR-P001 — historically unstable across Node versions).

Dev-checkout mode (spec §5.2) — primary use case, not an edge case

orch-defs install detects two modes:

• Clean-install: cwd is a consumer project (e.g. orch-testproj-rfc040, trc, red-bull) or a fresh machine — nothing competes with the newly-materialized user-scope copy.
• Dev-checkout: cwd is inside the orchestrator monorepo itself, where .claude/agents/, .claude/skills/ are the authored, git-tracked, PR-reviewed source.

Dev-checkout is cmac's primary, everyday use case — not a rare edge case. The "launch-from-root" goal (RFC-040) is primarily about starting sessions outside the monorepo, but cmac continues developing the orchestrator itself from inside the monorepo checkout on a daily basis.

Precedence — MEASURED (AC-007/TASK-036, S385)

An earlier draft of this spec (§3.3) treated the precedence direction between project-scope and user-scope as asserted by Claude Code's official docs but not empirically measured. scripts/probes/ac007-precedence-probe.ts (TASK-035) has since run that probe for real (TASK-036): an isolated CLAUDE_CONFIG_DIR fixture, 3/3 deterministic runs per axis, with a hard isolation gate confirming the real ~/.claude and the real repo were never mutated by the probe itself.

Verdict: CONFIRMS the documented claim. Agents resolve by project scope (a local edit inside this repo takes effect on the next live session immediately); skills resolve by user scope (~/.claude/skills — editing a skill here has no effect on a live session until orch-defs install re-runs, unless the file happens to be an INTERIM per-file symlink, C6/TD-204). The precedence direction is not inverted.

The risk that remains is silent drift, not precedence direction. Because ~/.claude/agents|skills now resolves from the distributed package copy while <repo>/.claude/agents|skills remains the authored copy, the two can silently diverge over time — a project-scope skill edit has no effect on a live session until you re-run orch-defs install to refresh ~/.claude/skills. orch-defs install detects dev-checkout mode and requires an explicit --dev-checkout-ack before proceeding, precisely because this drift risk is real and ongoing, not a one-time inverted- precedence hazard.

Full convergence — open question, not closed by this backlog

Fully resolving requirement (a) for the dev-checkout case — converging <repo>/.claude/{agents,skills} into symlinks pointing at packages/definitions/ (the C6 model, in the reverse direction) — is bigger than this installer and is explicitly out of scope here (spec §3.2/§5.2). orch-defs install v1 detects-and-warns; full repo convergence is a separate design decision, not implemented in this version.

Development

npm run build           # tsc + bundle-hooks + generate-manifest
npm run test            # vitest run
npm run test:coverage   # vitest run --coverage

Hooks (hooks/*.ts) are bundled into self-contained hooks/*.mjs bundles at build time (npm run bundle-hooks, src/scripts/bundle-hooks.ts) — a fresh install target has no node_modules of its own, so hooks must not depend on runtime module resolution outside the bundle. tests/HooksBundleFreshness.test.ts guards against source/bundle drift (see below).