@drawbridge/drawbridge-agents 0.0.8 → 0.0.10

package/claude/CLAUDE.md

@@ -1,8 +1,11 @@
+@../conventions/karpathy-guidelines.md
 @../conventions/rules.md
 @../conventions/javascript-formatting.md
 @../conventions/nested-objects.md
 @../conventions/jsx-fragments.md
 @../conventions/transactions.md
+@../conventions/cascade-cleanup.md
+@../conventions/dry.md
 @../conventions/property-shorthand.md
 @../conventions/drawbridge-packages.md
 @../conventions/sentry-sdk.md

package/conventions/cascade-cleanup.md

@@ -0,0 +1,25 @@
+# Cascade cleanup belongs in drawbridge-sync
+
+When a Drawbridge document delete should trigger cleanup of dependent rows in another collection — steps tied to a workflow, workflows tied to a connection, exports tied to a user, anything where deleting X requires also deleting Y — the cleanup belongs in a change-stream listener in `drawbridge-sync`, **not** inline in the API route handler that triggered the original delete.
+
+## Why
+
+- API routes stay focused on the user's request. Cascade work shouldn't block the HTTP response or balloon the request's transaction scope.
+- A sync-side listener fires on **every** delete path: the direct route, a cascade from a different route, an admin tool, a manual Mongo write. An inline cascade only runs on the one route that has it.
+- Change streams are configured with `fullDocumentBeforeChange: 'required'`, so the listener receives the full prior document and has everything it needs to reason about the dependents.
+
+## How to apply
+
+- In an API route delete handler, do **not** add `controllers.base.delete` (or `bulk` with `deleteMany`) for child collections. Just delete the parent. The sync listener cleans up.
+- Add the cleanup handler in `drawbridge-sync/queue/<collection>.js`, in the `handlers.delete` slot, signature `async ({ fullDocumentBeforeChange : doc }) => { ... }`. Copy the shape from `queue/user.js` or `queue/organization.js`.
+- For the listener to fire at all, the collection must be in both:
+  - `drawbridge-sync/stream.js` `collections` array
+  - `drawbridge-sync/lib/queue.js` queue map
+  - **And** registered in `drawbridge-sync/queue/index.js`'s workers array.
+  - If any of these are missing, change-stream events get enqueued and silently dropped, or never enqueued at all. Audit all four sites when adding a new collection.
+- For deep cascades (parent → child → grandchild), let the chain ride the change streams: the child's own listener handles its own dependents. Don't reach down two levels from the parent's listener.
+
+## Counter-examples (these stay inline in the API)
+
+- Decrementing `organization.totals.<resource>` and `usage.totals.<resource>` on delete. These are counter mutations against the *same* request, not cleanup of dependent rows. Done inline in the API route handler.
+- The deleted document itself. The route deletes it; the listener reacts to the deletion.

package/conventions/dry.md

@@ -0,0 +1,34 @@
+# Don't Repeat Yourself (DRY)
+
+Before writing a new function or handler that *does work* (external API call, doc creation, counter increment, cascade pattern, dispatch), check whether existing code already does that work. If so, **reuse it**. If the same work happens in 2+ places, **extract a helper** before adding a third copy.
+
+## Why
+
+Repeated implementations drift. Two paths that did the same thing yesterday do *almost* the same thing tomorrow — and the divergence is the bug. Examples from this codebase:
+
+- `step.sendgrid.email.send` was implemented as a separate handler that called `sendgrid.send()` directly, while `queue/notification.js`'s `send()` already did exactly that with the right provider selection from org connections. Two paths, same external service, slightly different code — a future SendGrid auth change would have to be made in both.
+- `usage.totals.actions` increments are hand-rolled in `stream/otc.js`, `queue/segment.js`, `queue/contact.js`, and historically `queue/workflow.js` — billing logic spread across 4+ files, each independent.
+- Connection-fetch + `decrypt(connection.settings)` appears 7+ times across `stream/` and `queue/`. The `status: 'active'` guard is implicit in some callers and missing in others — a latent security gap.
+
+Each pattern is small individually. Together they make debugging issues like "why is the action count wrong?" require grepping every counter increment to find the right one.
+
+## How to apply
+
+1. **Name the existing function you're calling before writing the new function.** "I'll call `send()` from `queue/notification.js`" — not "I'll call `sendgrid.send()` directly". If the function you'd call doesn't exist yet, you might still need to write it — but first verify it's not just one grep away.
+2. **Grep the work, not the name.** Before adding a `controller.update({ $inc: { 'totals.X': … }})`, grep for `totals.X` to find every other site doing the same. Same for SDK calls (`sendgrid.send`, `stripe.customers.update`, etc.).
+3. **At 2 copies, extract.** If you find the same shape in two places, factor before adding a third. Don't wait for the 5th.
+4. **Centralize step handlers, queue workers, and lifecycle emitters in one file each.** drawbridge-sync's pattern: all `step.*` bodies live in `queue/step.js`; all messaging delivery routes through `queue/notification.js`'s `send()`; per-collection cleanup lives in `stream/<collection>.js`. Don't sprinkle related logic across multiple files for no reason.
+
+## Watch list
+
+Patterns that have been duplicated in this family before — confirm before adding new instances:
+
+- External SDK calls (SendGrid / Mailchimp / Twilio / Stripe / Shopify Admin / Shopify Storefront)
+- `controller.update({ $inc: { 'totals.X': … }})` counter increments on the `usage`, `organization`, `campaign`, `page`, `range`, `lead` collections
+- `controller.get({ collection: 'connection', … })` followed by `decrypt(connection.settings)`
+- Notification doc creation (`controller.create({ collection: 'notification', … })`) when you actually want to send an email/SMS — use `send()` directly
+- Cache invalidation chains where multiple `cache.delete([…])` calls fire as a pair
+- `logger.emit('<entity>.<verb>', …)` lifecycle telemetry wrappers
+- Cascade-delete patterns (delete X → also cleanup Y, Z) — these belong as stream listeners in `drawbridge-sync`, see `cascade-cleanup.md`
+
+If you find a duplicate while implementing something new, surface it: either factor it as part of the same change, or document it and propose a follow-up cleanup PR.

package/conventions/karpathy-guidelines.md

@@ -0,0 +1,63 @@
+# Karpathy coding guidelines
+
+Adapted from Andrej Karpathy's observations on common LLM coding mistakes — see https://github.com/multica-ai/andrej-karpathy-skills. These are general behavioral guidelines that bias toward caution over speed; use judgment for trivial tasks.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {