@drawbridge/drawbridge-agents 0.0.2

package/.claude-template/agents/README.md

@@ -0,0 +1,5 @@
+# Managed by @drawbridge/drawbridge-agents
+
+Subagent definitions placed here are mirrored into every consumer repo's `.claude/agents/` on `npm run sync`. To add a shared subagent: drop the markdown definition in this directory in `drawbridge-agents`, bump the package version, publish, then `npm run sync` in each consumer.
+
+Consumer-local subagents should be added directly to the consumer's `.claude/agents/` with a different filename — the sync mirror only overwrites paths that exist in this template.

package/.claude-template/commands/README.md

@@ -0,0 +1,5 @@
+# Managed by @drawbridge/drawbridge-agents
+
+Slash command markdown files placed here are mirrored into every consumer repo's `.claude/commands/` on `npm run sync`. To add a shared command: drop it in this directory in `drawbridge-agents`, bump the package version, publish, then `npm run sync` in each consumer.
+
+Consumer-local commands should be added directly to the consumer's `.claude/commands/` with a different filename — the sync mirror only overwrites paths that exist in this template.

package/.claude-template/hooks/README.md

@@ -0,0 +1,5 @@
+# Managed by @drawbridge/drawbridge-agents
+
+Hook scripts placed here are mirrored into every consumer repo's `.claude/hooks/` on `npm run sync`. To add a shared hook: drop it in this directory in `drawbridge-agents`, bump the package version, publish, then `npm run sync` in each consumer.
+
+Consumer-local hooks should be added directly to the consumer's `.claude/hooks/` with a different filename — the sync mirror only overwrites paths that exist in this template.

package/.claude-template/settings.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash",
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "Glob",
+      "Grep",
+      "LS",
+      "WebFetch",
+      "WebSearch",
+      "mcp__*",
+      "mcp__sentry__find_projects"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,81 @@
+# @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/
+
+bin/
+  sync-claude.js            ← drawbridge-agents-sync — mirrors .claude-template/ → consumer's .claude/
+```
+
+## Consuming from a drawbridge-* repo
+
+1. Install:
+   ```bash
+   npm install --save-exact @drawbridge/drawbridge-agents
+   ```
+
+2. Replace the repo's `CLAUDE.md` with a thin import file:
+   ```markdown
+   @./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:
+   ```markdown
+   @./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:
+   ```json
+   "sync": ". \"$HOME/.nvm/nvm.sh\" && nvm use && npm prune && npm install && npx drawbridge-agents-sync"
+   ```
+
+   On every `npm run sync`, the contents of this package's `.claude-template/` are copied into the consumer's `.claude/`. Paths that exist in the template are **managed** (overwritten on each sync). Anything else in `.claude/` — 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` |

package/bin/sync-claude.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+const fs = require('fs')
+const path = require('path')
+
+const consumerRoot = process.env.INIT_CWD || process.cwd()
+const templateRoot = path.resolve(__dirname, '..', '.claude-template')
+const destRoot = path.join(consumerRoot, '.claude')
+
+if (!fs.existsSync(templateRoot)) {
+  console.error(`drawbridge-agents-sync: template not found at ${templateRoot}`)
+  process.exit(1)
+}
+
+const copied = []
+
+const mirror = (src, dst) => {
+  fs.mkdirSync(dst, { recursive: true })
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name)
+    const d = path.join(dst, entry.name)
+    if (entry.isDirectory()) {
+      mirror(s, d)
+    } else {
+      fs.copyFileSync(s, d)
+      copied.push(path.relative(consumerRoot, d))
+    }
+  }
+}
+
+mirror(templateRoot, destRoot)
+
+console.log(`drawbridge-agents-sync: ${copied.length} file(s) mirrored to ${path.relative(consumerRoot, destRoot) || '.claude'}`)
+for (const p of copied) console.log(`  ${p}`)

package/claude/CLAUDE.md

@@ -0,0 +1,6 @@
+@../conventions/rules.md
+@../conventions/javascript-formatting.md
+@../conventions/nested-objects.md
+@../conventions/jsx-fragments.md
+@../conventions/transactions.md
+@../conventions/property-shorthand.md

package/conventions/javascript-formatting.md

@@ -0,0 +1,55 @@
+# JavaScript Formatting
+
+## Spaces inside parentheses
+```js
+require( 'module' )
+client.db( 'database' )
+for( const item of array )
+```
+
+## Spaces around colons in object literals
+```js
+{
+	collection : 'organization',
+	data : { ... },
+	options
+}
+```
+
+## Spaces inside computed property brackets
+```js
+array?.[ 0 ]
+object?.[ key ]
+```
+
+## No trailing commas on last items in objects
+```js
+{
+	first : 'value',
+	second : 'value'
+}
+```
+
+## Semicolons after objects and functions
+```js
+if( condition ){
+
+	// ...
+
+};
+
+const run = async () => {
+
+	// ...
+
+};
+```
+
+## Indentation
+- Tabs, size 4
+- Blank line after opening brace of functions and control structures
+- LF line endings
+- Trailing newline at end of file
+- Single quotes for strings
+
+When adding or removing a wrapper block (e.g. a transaction callback, an `if` block), re-indent all enclosed lines to match the new nesting level. If the indentation shift is large or the block is long, prefer rewriting the whole function with the Write tool rather than using multiple Edit calls.

package/conventions/jsx-fragments.md

@@ -0,0 +1,29 @@
+# JSX Fragments
+
+Never use the `<></>` shorthand. Always use explicit `<Fragment></Fragment>` with a named import from `react`.
+
+```js
+// Wrong
+import { useState } from 'react';
+
+return (
+	<>
+		<Foo />
+		<Bar />
+	</>
+);
+
+// Correct
+import { Fragment, useState } from 'react';
+
+return (
+	<Fragment>
+		<Foo />
+		<Bar />
+	</Fragment>
+);
+```
+
+- Add `Fragment` to the existing named `react` import in alphabetical position (capital `F` sorts before lowercase hooks like `use*`).
+- Do not import `React` as a default just to write `<React.Fragment>` — use the named `Fragment` import.
+- Applies to every Next.js app in the drawbridge-* monorepo.

package/conventions/nested-objects.md

@@ -0,0 +1,15 @@
+# Nested objects must always be expanded across multiple lines
+Never write inline nested objects — always expand across multiple lines:
+```js
+// Wrong
+{ $slice : [ '$frames', i ] }
+{ $add : [ i, 1 ] }
+
+// Correct
+{
+	$slice : [ '$frames', i ]
+}
+{
+	$add : [ i, 1 ]
+}
+```

package/conventions/property-shorthand.md

@@ -0,0 +1,18 @@
+# Property shorthand
+
+Use ES6 property shorthand whenever the source variable name matches the target property key. If you'd write `foo : foo`, drop to `foo`.
+
+For JSX, when a prop is computed (helper call, ternary, lookup), hoist it to a local `const` named after the prop above the `return`, then reference it via shorthand inside the prop-spread. Gate the conditional render on that same `const`, not on a re-derived expression.
+
+```js
+const src = cdnSrc( image, '100x100', updatedAt );
+
+return src ?
+<Image { ...{ alt, src, fill : true, sizes : '40px' } } />
+:
+<Placeholder />;
+```
+
+Not `src : cdnSrc( ... )` inline; not `src : src` once the variable exists; not gating on `image?.sizes?.[ '100x100' ]` when `src` already encodes the same truthiness.
+
+CDN image URLs use `cdnSrc( asset, size, timestamp )` from `@drawbridge/drawbridge-utils/cdn`. All three arguments are required — without `timestamp` the URL would never change across uploads and the CDN/browser would serve a stale asset. Pass the asset's own `updatedAt` when it has one, or the parent document's `updatedAt` for embedded assets (e.g. `user.image`). Returns `undefined` if `asset.sizes[ size ]` or `timestamp` is missing.

package/conventions/rules.md

@@ -0,0 +1,8 @@
+# Rules
+1. Ask, don't assume. If something is unclear, ask before writing a single line. Never make silent assumptions about intent, architecture, or requirements.
+
+2. Simplest solution first. Always implement the simplest thing that could work. Do not add abstractions or flexibility that weren't explicitly requested.
+
+3. Don't touch unrelated code. If a file or function is not directly part of the current task, do not modify it, even if you think it could be improved.
+
+4. Flag uncertainty explicitly. If you are not confident about an approach or technical detail, say so before proceeding. Confidence without certainty causes more damage than admitting a gap.

package/conventions/transactions.md

@@ -0,0 +1,34 @@
+# Database Transactions
+
+Wrap multiple sequential `controller.update`, `controller.create`, or `controller.delete` calls in `controller.transaction` for atomicity. A single write does not need a transaction.
+
+```js
+await controller.transaction( async ( session ) => {
+
+	const options = { session };
+
+	await controller.update({
+		collection : 'foo',
+		data : { ... },
+		options,
+		query : { id }
+	});
+
+	await controller.create({
+		collection : 'bar',
+		data : { ... },
+		options
+	});
+
+} );
+```
+
+Rules:
+- Pass `session` to every operation inside the transaction via `options : { session }`
+- When results are needed outside the transaction, `return` them from the callback — do not fold subsequent operations inside just to avoid returning
+- When other options exist (e.g. `bypassDocumentValidation`), spread them: `{ ...options, session }`
+- **Do NOT include `controller.get` or `controller.aggregate` inside a transaction** — reads do not benefit from transaction protection; fetch them before or after
+- **Do NOT include operations on time-series collections inside a transaction** — MongoDB does not support this (`analytic`, `message` are time-series); perform these writes outside the transaction
+- Socket `io.emit` calls must be outside the transaction — extract return values from the callback
+- External side effects (S3, Stripe API, BullMQ) cannot participate in MongoDB transactions — keep them outside
+- Do not wrap large bulk-delete loops in a single transaction — MongoDB has a 60-second timeout

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@drawbridge/drawbridge-agents",
+  "version": "0.0.2",
+  "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "sync": ". \"$HOME/.nvm/nvm.sh\" && nvm use && npm prune && npm install",
+    "build": "npm publish"
+  },
+  "bin": {
+    "drawbridge-agents-sync": "bin/sync-claude.js"
+  },
+  "files": [
+    "claude",
+    "conventions",
+    ".claude-template",
+    "bin",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trydrawbridge/drawbridge-agents.git"
+  }
+}