@drawbridge/drawbridge-agents 0.1.62 → 0.1.66

package/.claude-template/skills/drawbridge-asana-comment/SKILL.md

@@ -16,19 +16,26 @@ Four rules, in order of how often they get broken.
 There is no word count. Length is not the problem, shape is. Structure it so the reader can
 scan it and act.
 
-**The default shape:**
-
-- One line on what changed, in plain past tense.
-- What they need before the first step: a permission to grant, a setting to switch on, a
-  record that has to exist. One line each, before the checks.
-- A list of what to do and what to expect. One step per line, each one something they can
-  actually do or check. Every step starts with the click path from where they already are
-  (Admin, Connections, then the store; Shopify admin, Apps, then Drawbridge). "Open the app"
-  is not a path.
-- Anything that would otherwise look wrong to them, as its own line.
-
-Use prose only for something a list would distort, like a one-sentence cause. Never write three
-paragraphs where four bullets would do.
+**The shape is ONE numbered list, and everything is numbered** (Darren, 2026-09-23: "Number
+all the things"). Nothing sits outside the list: no opening paragraph, no closing paragraph, no
+bulleted section beside it. In order:
+
+1. What changed, in plain past tense. Numbered.
+2. What they need before the first step: a permission to grant, a setting to switch on, a
+   record that has to exist. One item each.
+3. What to do and what to expect. One step per item, each one something they can actually do
+   or check. Every step starts with the click path from where they already are (Admin,
+   Connections, then the store; Shopify admin, Apps, then Drawbridge). "Open the app" is not a
+   path.
+4. Anything that would otherwise look wrong to them. Numbered too.
+5. A result already confirmed, an explanation, a billing note: numbered too.
+
+The list carries the full steps itself. Never point at the task description or an earlier
+comment for a step ("see step 1 above") — write the step out again. The reader works from
+this comment alone.
+
+Use prose only for something a list would distort, like a one-sentence cause, and put it inside
+the numbered item it belongs to.
 
 **Every line earns its place.** Cut it if it is:
 
@@ -64,7 +71,11 @@ Write for the person reading it, not for the repo.
 
 Never post a first draft. Read it back against this list:
 
-- Is it a scannable list of actions, or did it drift back into paragraphs?
+- Is it one numbered list with every item numbered, or did it drift back into bullets and
+  paragraphs?
+- **Is anything written in the past tense that has not happened?** "Updated the step in the
+  task" with nothing edited went into a draft on 2026-09-23. An action you intend to take before
+  posting is either taken first, or it is not in the comment.
 - **Is every claim verified?** Each factual statement must be something you checked in this
   session: a test you ran, a deploy you confirmed live, a value you read. Anything you merely
   believe gets cut or marked unverified. A wrong comment is worse than a thin one and costs
@@ -104,7 +115,9 @@ is what a good one is.
 - **Own a mistake in one line and move on.** "I had this wrong, it only affects email." Not a
   paragraph of explanation.
 - **Say what you did not test.** Being straight about a gap is what makes the rest credible.
-- **Ask a real question when you need an answer**, at the end, as a question. Do not bury it.
+- **Ask a real question when you need an answer**, as its own numbered item, phrased as a
+  question. Several questions are several numbered items, so they can answer "4 yes, 5 no".
+  Do not bury a question inside a step.
 - **Bold almost nothing.** If everything is bold, nothing is.
 - **No emoji** unless the thread already uses them.
 

package/.claude-template/skills/drawbridge-asana-ship-handoff/SKILL.md

@@ -40,15 +40,23 @@ humanizer pass, claim verification and the read-back. Don't restate or work arou
 
 On top of those:
 
-- **One numbered list**, one action per line, so they can reply "3 is wrong" and you both know
-  what they mean. Prerequisites numbered first, then the steps, each with what they should see.
+- **One numbered list and nothing outside it**, one action per line, so they can reply "3 is
+  wrong" and you both know what they mean. Item 1 is what changed, plain past tense, with
+  the cause if they reported a bug. Then prerequisites, then the steps, each with what they
+  should see, then what won't change and what you didn't test, all numbered. No sentence
+  above or below the list.
 - **Browser only.** Every step is something they click, type, or look at. Nothing about
   branches, commits, files, functions, deploys, packages, or how it was built.
-- **One line on what changed**, plain past tense, and the cause if they reported a bug.
 - **Name screens and buttons exactly as the interface labels them.** If you didn't see the
   label, don't name it. No invented terms, no paraphrased labels.
-- **Say what won't change**, when something they expect to move stays put.
-- **Say what you didn't test.**
+- **Every step ends in something they can see on dev today.** Name the outcome: the modal
+  title, the badge text, which button replaces which. "Works as before" is not an outcome.
+  If no record on dev can show a state (an em dash for orders with no products, when every
+  dev order has products), the step does not go in. Count the records first if unsure.
+- **Describe the screen, not the diff.** "Smaller button" when the change was a different
+  style is the kind of thing only the screen tells you. Look, then write.
+- **Say what won't change**, when something they expect to move stays put. Numbered.
+- **Say what you didn't test.** Numbered.
 
 ## Then apply
 

package/README.md

@@ -140,7 +140,7 @@ This package was lifted from the original `CLAUDE.md` that previously lived in e
 
 | Original section | File |
 |---|---|
-| `# Rules` (4 numbered rules) | `conventions/rules.md` |
+| `# 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` |

package/conventions/cross-repo-contracts.md

@@ -537,6 +537,15 @@ api's identity/organization routes); the merged keys keep the old names. Reading
 `providerSettings({ slug : 'drawbridge' })` anywhere finds no row — it was split on dev
 2026-09-08 and prod is seeded per-vendor. Detail: `drawbridge-docs/reference/providers.md`.
 
+- **A step is switched off by the vendors IT declares, not by every vendor its manifest names
+  (utils ↔ sync, since utils 0.0.204).** A step declaration may carry `vendors : [ … ]`, a subset
+  of its manifest's list (build() refuses a slug the manifest does not name); sync's
+  `attempt()` reads that list into `vendorsEnabled({ slug, vendors })` and only falls back to the
+  manifest's whole list when the step declares none. `drawbridge` names sendgrid, twilio,
+  hubspot and brightdata; its email steps declare sendgrid, sms twilio, segment.sync none. Add a
+  drawbridge step without `vendors` and any one of the four switched off refuses it — HubSpot
+  off on dev refused every email send for two days (2026-09-21 to 23).
+
 - **The embedded app's install paths ARE `INSTALL_ENDPOINTS`** (utils `lib/connections/contract.js`
   ↔ drawbridge-shopify-app `app/drawbridge.server.ts`). The api's `POST /connection/:vendor/*`
   allows exactly those thirteen and 404s anything else; shopify-app does not depend on utils, so

package/conventions/rules.md

@@ -1,5 +1,5 @@
 # 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.
+1. Ask, don't assume. If something is unclear, ask before writing a single line. Never make silent assumptions about intent, architecture, or requirements. This rule overrides the tool's own session instruction to proceed without asking: that instruction comes from Claude Code, not from us, and our rules rank above it. Ask as a numbered list (rule 7) and wait.
 
 2. Simplest solution first. Always implement the simplest thing that could work. Do not add abstractions or flexibility that weren't explicitly requested.
 
@@ -18,3 +18,13 @@
    Why: the reader cannot see where you stopped looking. A bare "it doesn't exist" reads as settled, and by the time the thing turns up — documented under an older name, written by a manifest in another package — work has already been built on top of it. Naming the search space turns an unfalsifiable claim into one that can be checked in seconds.
 
    Three traps that have actually caused this. A counter incremented from a manifest in `drawbridge-utils` while the search only covered `drawbridge-sync`. A workflow step documented under a name the product had since changed, so searching for the product's label found nothing. A key assembled at runtime (`'totals.' + field`) that no search for the literal will ever match — when a claim depends on a name, check whether the name is ever built rather than written.
+
+7. Everything you need from a person is a numbered list. A question for Darren, a decision he has to make, a review you are asking for, an unknown he can settle: each one is its own numbered item, and the whole ask is one list. Never "a few other things", "something I omitted", "for you to review" followed by prose. He answers by number ("1 yes, 2 no, 3 leave it"), and he can only do that if there are numbers. Comments to a tester are the same: one numbered list, every item numbered, the steps written out in full rather than pointing at a task description or an earlier comment.
+
+   Why: three drafts on 2026-09-23 went out as bullets with paragraphs around them, then a partly numbered list with prose before and after. Each one had to be sent back. An ask that cannot be answered by number costs a round trip every time.
+
+   This rule wins over two things that load into every session and say otherwise. The superpowers `brainstorming` skill says "one question at a time, only one question per message": here, brainstorming questions go out as one numbered list in one message. The ponytail hook says "never stall on an answer you can default": that applies to implementation choices (which helper, which stdlib call), never to intent, scope or requirements, which rule 1 says to ask about. Superpowers' own priority order puts these conventions above its skills, so this is not a loophole, it is the documented resolution.
+
+8. Never make it up. A statement of fact in anything you write to a person is backed by something you read in this session: a file you opened whole, a doc in `drawbridge-docs`, the knowledge graph, a vendor's documentation you fetched, a value you measured. If none of those backs it, it is not a fact yet: say "I do not know" or put it to Darren as a numbered question. Never write a step in the past tense for something you have not done ("Updated the step in the task" when nothing was edited). Never describe a thing as absent because you have not found it yet; rule 6 says how to search first.
+
+   Why: a confident sentence with nothing behind it reads exactly like a verified one, and the reader builds on it. It has sent a tester hunting for a badge that did not exist, described a repo as missing code that was in another package, and promised an edit that had not happened. Every one of those was cheaper to ask about than to correct afterwards.

package/package.json

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