@drawbridge/drawbridge-agents

Shared agent-instruction content for the drawbridge-* monorepo. One canonical source of conventions (rules, code style, patterns) consumed by every drawbridge-* repo's CLAUDE.md (and, in future, other agent config files).

Why this exists

Before this package, every drawbridge-* repo carried a byte-identical copy of the same 164-line CLAUDE.md. Updating a rule meant editing 13 places and drift was inevitable. Now the canonical content lives here; each repo's CLAUDE.md is a thin file of @ imports.

Layout

conventions/                ← canonical, agent-neutral content (@-imported into CLAUDE.md)
  rules.md, javascript-formatting.md, ...
  ecosystem.md              ← always-loaded architecture map of the 16 repos
  cross-repo-contracts.md   ← load-bearing invariants that break across repos
  docs-linkage.md           ← consult the spec + @story/@doc code anchors
  graphify.md               ← query the family knowledge graph before grepping

claude/
  CLAUDE.md                 ← aggregator — @-imports every conventions/*.md

.claude-template/           ← the complete shared .claude/, mirrored into each consumer repo
  settings.json             ← permissions, additionalDirectories, drift-check Stop hook,
                              family-wide plugin marketplaces + enabledPlugins
  skills/                   ← shared skills (drawbridge-ship-feature, -asana-ship-handoff, ...)
  hooks/  agents/  commands/

.root-template/             ← mirrored to each consumer repo's root; files are stored DOTLESS
                              and the mirror restores the leading dot (one rule; also required
                              for npmrc since npm strips a literal .npmrc from tarballs)
  mcp.json                  → .mcp.json    project-level MCP servers (Sentry, Asana)
  editorconfig              → .editorconfig family-wide editor defaults (tabs, lf, utf-8)
  npmrc                     → .npmrc        save-exact=true (exact-pin convention)
  nvmrc                     → .nvmrc        family-standard node version (v22.23.1)

bin/
  sync-claude.js            ← drawbridge-agents-sync — mirrors templates + graphify preflight
  graph.js                  ← drawbridge-agents-graph — builds the merged family knowledge graph
  preflight-graphify.js     ← ensures the graphify runtime is installed (called by sync)

scripts/
  check-doc-links.js        ← drawbridge-agents-check-docs — validates @story/@doc tags resolve

hooks/
  drift-check.js            ← Stop hook (wired via .claude-template/settings.json)
  consult-docs-record.js    ← PostToolUse hook: remembers a docs page read / graph query per session
  consult-docs-gate.js      ← PreToolUse hook: refuses the first source edit until both happened
  qa-gate.js                ← PreToolUse hook on the Asana comment tool: every "quoted label" must have been walked or exist in source; a session that changed code needs a clean QA report
  guard-superpowers-docs.js ← PreToolUse hook: plans/specs go to drawbridge-docs

Consuming from a drawbridge-* repo

1. Install as a devDependency (this package is agent-tooling only — no app-runtime imports — so it must not ship to production / DigitalOcean):

   npm install --save-exact --save-dev @drawbridge/drawbridge-agents

   Ensure the app's deploy install step omits devDependencies (npm ci --omit=dev).

2. Replace the repo's CLAUDE.md with a thin import file:

   @./node_modules/@drawbridge/drawbridge-agents/claude/CLAUDE.md

   Add any repo-specific rules above that import line.

3. (Optional) Import additional narrow conventions as they're added to this package:

   @./node_modules/@drawbridge/drawbridge-agents/claude/CLAUDE.md
   @./node_modules/@drawbridge/drawbridge-agents/conventions/sync-side-effects.md

4. Extend the consumer's npm run sync to mirror the shared .claude/ template:

   "sync": ". \"$HOME/.nvm/nvm.sh\" && nvm use && npm prune && npm install && npx drawbridge-agents-sync"

   On every npm run sync, this package mirrors the single source of truth into the consumer:

   • .claude-template/ → consumer's .claude/ — the complete shared setup: settings.json (permissions, additionalDirectories, the drift-check Stop hook), plus skills/, agents/, commands/, hooks/.
   • .root-template/ → consumer's repo root (.mcp.json, .editorconfig)

   Paths that exist in the templates are managed (overwritten on each sync) — every repo ends up with an identical .claude/. Only settings.local.json (each dev's personal overrides) and any consumer-only files are left untouched.

Claude Code's @ imports cascade — one import line resolves the whole tree under claude/CLAUDE.md.

Ecosystem knowledge, graph, and drift checks

Beyond the conventions, this package gives agents cross-repo visibility and keeps code, docs, and the knowledge graph from drifting. This package is the single source; each repo gets an identical copy via the sync mirror (see "Delivery model").

• Family knowledge graph (Graphify). npx drawbridge-agents-graph runs code-only AST extraction over every drawbridge-* repo and writes the merged graph to the committed, shared location drawbridge-docs/knowledge/graphs/global.json. Agents query it with the graphify CLI (e.g. graphify query "…" --graph ../drawbridge-docs/knowledge/graphs/global.json) instead of grepping; refreshing is rebuild + commit in docs + git pull (no npm/publish cycle). The runtime is a per-machine Python tool — npm run sync installs it (bin/preflight-graphify.js); set DRAWBRIDGE_SKIP_GRAPHIFY=1 to skip in CI/headless. We deliberately do not run graphify install (it would rewrite CLAUDE.md); the optional graphify-mcp server is available if you prefer MCP.
• Docs linkage + validator. Feature code carries @story <domain>/<slug> / @doc reference/<file>#<anchor> anchors (see conventions/docs-linkage.md). npx drawbridge-agents-check-docs scans every repo and fails if any anchor no longer resolves against drawbridge-docs.
• Drift-check Stop hook. hooks/drift-check.js runs at each task-turn end, wired via the drift-check Stop hook in the mirrored .claude/settings.json. It blocks on an unresolved doc anchor and on @story-anchored code changed without a drawbridge-docs change (once per turn; the second attempt passes so the agent must answer), and nudges (non-blocking) when the graph looks stale. It skips plan-mode and turns with no source changes.
• Read-before-write hooks. hooks/consult-docs-record.js (PostToolUse on Read/Bash) remembers that a drawbridge-docs page was read and a graph query ran in this session; hooks/consult-docs-gate.js (PreToolUse on Write/Edit) refuses the first source edit until both happened. See conventions/docs-linkage.md, "Enforced, not just asked".
• Shared skills. Mirrored into every repo's .claude/skills/ (from .claude-template/skills/): drawbridge-ship-feature (verify → docs → graph → handoff), drawbridge-asana-ship-handoff, drawbridge-explore-ecosystem, drawbridge-record-contract.

Delivery model

Every repo has an identical, normalized agent setup, all sourced from this one package:

• CLAUDE.md → one-line @import (live from node_modules).
• .claude/ (settings.json + permissions + hook, skills, agents/commands/hooks) → mirrored from .claude-template/ and committed per repo.
• .mcp.json, .editorconfig → mirrored from .root-template/ and committed per repo.
• Config files (.claude/, .mcp.json) are copied rather than imported because only markdown (CLAUDE.md) supports @import; the mirror keeps the copies identical from one source.
• The package is a devDependency → never installed in production / on DigitalOcean.
• The knowledge graph is committed once in drawbridge-docs/knowledge/graphs/; the graphify runtime + build cache are per-machine under ~/.graphify/ (gitignored). graphify install (which edits CLAUDE.md) is never run.

Updating a rule or shared .claude/ file

1. Edit the relevant conventions/<file>.md or .claude-template/<path>.
2. Bump version in package.json (semver: patch for clarification, minor for added rule/file, major for breaking change).
3. npm audit (per drawbridge-* publishing convention).
4. npm run build (runs npm publish).
5. Bump the exact-pin in each consuming repo's package.json and npm run sync.

Content map (origin → destination)

This package was lifted from the original CLAUDE.md that previously lived in every drawbridge-* repo. The mapping:

| Original section | File | |---|---| | # Rules (8 numbered rules) | conventions/rules.md | | # JavaScript Formatting (spaces, colons, brackets, commas, semicolons, indentation) | conventions/javascript-formatting.md | | ## Nested objects must always be expanded across multiple lines | conventions/nested-objects.md | | ## JSX Fragments | conventions/jsx-fragments.md | | ## Database Transactions | conventions/transactions.md | | ## Property shorthand | conventions/property-shorthand.md |