@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
  rules.md
  javascript-formatting.md
  nested-objects.md
  jsx-fragments.md
  transactions.md
  property-shorthand.md

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

.claude-template/           ← mirrored into each consumer repo's .claude/
  settings.json             ← shared permissions/env
  hooks/
  agents/
  commands/

.root-template/             ← mirrored into each consumer repo's root
  .mcp.json                 ← project-level MCP servers (e.g. Sentry)

bin/
  sync-claude.js            ← drawbridge-agents-sync — mirrors templates into consumer repo

Consuming from a drawbridge-* repo

1. Install:

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

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:

   • .claude-template/ → consumer's .claude/
   • .root-template/ → consumer's repo root (currently just .mcp.json)

   Paths that exist in the templates are managed (overwritten on each sync). Anything else in .claude/ or at the repo root — including settings.local.json and any consumer-only hooks/agents/commands — is left untouched.

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

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 (4 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 |