@drawbridge/drawbridge-agents 0.1.39 → 0.1.43

package/.claude-template/skills/drawbridge-add-connection/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: drawbridge-add-connection
+description: Use when adding a new vendor connection (a new manifest in drawbridge-utils) — runs the auth-type assessment FIRST so the integration is built the way the vendor's own docs recommend, then walks the build against the documented checklist and its guards.
+---
+
+# Add a connection
+
+A connection is one manifest file in `drawbridge-utils/lib/connections/`, and the
+build half is documented — `drawbridge-docs/reference/connection-hooks.md`,
+"Adding a connection". This skill exists for what comes BEFORE the file: deciding
+what kind of connection to build, from the vendor's documentation rather than
+from whichever auth mechanism is easiest to wire.
+
+The failure it prevents is real: Attentive was first built as pasted API keys
+because keys worked, and their docs turned out to frame private-app keys as
+"integrate your own account" — the public OAuth app was the documented path for
+platforms like Drawbridge. The rebuild cost an afternoon; the assessment costs
+ten minutes.
+
+## When to use
+
+Any new vendor manifest, and any auth-type change to an existing one (keys →
+OAuth is a rebuild of the auth surface, not a tweak).
+
+## Steps
+
+1. **Fetch the vendor's developer docs and answer these in writing, with the
+   URL of the page that answers each.** Never from memory — the Klaviyo consent
+   url was once written from memory, pointed at their API host, and stalled
+   every merchant on a blank page.
+
+   - What auth mechanisms exist, and **who does the vendor say each is for**?
+     The distinction that matters is *your own account* versus *accounts outside
+     your organization*. Drawbridge is always the second: merchants connect
+     THEIR account to OUR platform.
+   - Is there a partner / public-app / marketplace program? What does
+     registration take, and what credentials does it issue?
+   - For OAuth: authorize url, token url, how client credentials are sent
+     (form fields vs Basic header), whether PKCE is required, token lifetime,
+     whether refresh tokens exist, scope names.
+
+2. **Pick the `auth.type` from the answers, not from convenience:**
+
+   | vendor's shape | type |
+   |---|---|
+   | installed from the vendor's app store, never redirects back | `install` |
+   | registered app, merchant consents on the vendor's screen | `oauth` |
+   | the vendor offers ONLY per-account credentials | `keys` |
+   | no third party behind it at all | `generated` |
+
+   `keys` when OAuth exists is a decision someone must make out loud — usually
+   as an explicitly-flagged interim while a partner registration is pending, and
+   the manifest header says so.
+
+3. **If the app is not yet registered, build it dormant.** `requires` names the
+   client env vars that will exist after registration; until they land on a
+   deployment, the connection is offered nowhere. Shipping the manifest complete
+   and inert beats waiting — adding the env vars becomes the launch.
+
+4. **Record the assessment in the manifest header**: every cited fact, every
+   contradiction between the vendor's own pages (cite both and say which one the
+   code models), and — for OAuth — the questions only a live registration
+   answers: does consent echo `state` back, what is the real token lifetime,
+   does one app accept both environments' redirect urls.
+
+5. **Build against the checklist** in
+   `drawbridge-docs/reference/connection-hooks.md` → "Adding a connection". Its
+   guards are the enforcement: the directory-registration test, the
+   feature-grant test, `build()` itself. Trust the named failures over your
+   memory of the steps.
+
+## Notes
+
+- The manifest is the only place vendor facts live. If the assessment finds a
+  fact that must hold across repos, record it with `drawbridge-record-contract`.
+- The picker/search question is part of the assessment: if the vendor's list
+  endpoint filters by name server-side, the field must NOT declare
+  `search : false` — Attentive was the first vendor that could, and a test pins
+  that it stays searchable.

package/conventions/cross-repo-contracts.md

@@ -137,6 +137,19 @@ skill) so it stops living only in tribal memory.
 - **A subscription must open with the plan item.** It used to open with the metered actions price
   and attach the plan afterwards with `always_invoice`. With no metered item, Stripe rejects an
   itemless subscription, so the plan goes in at creation — changing the first invoice's shape.
+- **Ending a subscription is written twice, from ONE implementation** (stripe ↔ api ↔ sync).
+  `subscription.markTerminal` in **drawbridge-stripe** (`lib/subscription.js`, takes the caller's
+  db controller + session like `reconcile`) clears the org's `subscription` pointer, demotes to
+  `unsubscribed` under `status : { $nin : [ 'suspended', 'unsubscribed' ] }`, `$pull`s the org's
+  `type : 'method'` errors and flips the sub doc to `canceled`. Both callers run it: sync's
+  `markSubscriptionTerminal` (`lib/buffer.js`, on `customer.subscription.deleted` and terminal
+  `subscription.updated`) and drawbridge-api's admin cancel
+  (`route/organization-subscription.js` `handlers.delete.cancel`), which mirrors it inline so the
+  page isn't stale for a webhook it just caused. **The mirror runs FIRST and consumes the status
+  guard**, so the webhook's pass then matches nothing — anything one caller does outside
+  `markTerminal` therefore never happens on the admin path. Never re-inline these writes: the
+  hand-copied version drifted, and a stale card decline outlived its subscription and permanently
+  blocked the org from resubscribing (Asana 1217947409527192).
 - **Invoice line descriptions must keep the word "actions":** `isActionsLine` matches `/actions/i`
   to count billed quantity for the billed-vs-ledger reconcile. A copy edit that drops it silently
   breaks the audit. Detail: drawbridge-docs `reference/billing.md`.

package/conventions/superpowers-docs.md

@@ -8,7 +8,12 @@ drawbridge-docs/superpowers/plans/YYYY-MM-DD-<slug>.md
 drawbridge-docs/superpowers/specs/YYYY-MM-DD-<slug>.md
 ```
 
-This is the **only** allowed home for these working docs. Rules:
+**THE ONE EXCEPTION IS drawbridge-growth** (Darren, repeatedly, most recently 2026-09-01:
+"Don't add growth docs to docs"): growth is its own system — its plans and specs live in
+`drawbridge-growth/docs/superpowers/{plans,specs}/` and must **never** be written to
+drawbridge-docs. The guard hook exempts any `drawbridge-growth*` path for this reason.
+
+For every other repo, this is the **only** allowed home for these working docs. Rules:
 
 - Do **not** create or keep superpowers plans/specs (or `docs/superpowers/`, `docs/plans/`)
   inside any other repo. When you finalize a plan or spec, write it under

package/hooks/guard-superpowers-docs.js

@@ -47,6 +47,11 @@ const run = () => {
   // drawbridge-docs is the canonical home — anything there is fine.
   if (resolved.split('/').includes('drawbridge-docs')) process.exit(0)
 
+  // GROWTH IS THE EXCEPTION (Darren, repeatedly, most recently 2026-09-01):
+  // growth is its own system and its docs stay in drawbridge-growth — never
+  // in drawbridge-docs. Any growth checkout or worktree passes.
+  if (/\/drawbridge-growth[^/]*\//.test(resolved + '/')) process.exit(0)
+
   const hit = FORBIDDEN.find((seg) => resolved.includes('/' + seg + '/') || resolved.endsWith('/' + seg))
   if (!hit) process.exit(0)
 

package/package.json

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