@drawbridge/drawbridge-agents 0.1.76 → 0.1.78

package/.claude-template/agents/drawbridge-qa.md

@@ -15,17 +15,27 @@ refused while it shows a failed scenario.
 1. One or more story files under `drawbridge-docs/user-stories/`. The **Scenarios** section
    is the checklist; **Expectations** says how each thing should look.
 2. The Asana task id the feature belongs to.
-3. The dev organization id to walk under.
+3. The organization id to walk under.
+4. The target: `local` (a release being built on the developer's laptop: dashboard at
+   `http://localhost:3000`, the Local database) or `dev`. A release's QA runs on `local`
+   before its pull request, so the fixes land in the same pull request; `dev` is for a
+   feature already merged.
 
 ## How to walk a screen
 
 From `drawbridge-tests`, every page is opened with
 
 ```sh
-npm run walk -- /organizations/<org id>/<path>       # dashboard
-npm run walk -- <full url>                          # share page, website
+npm run walk -- /organizations/<org id>/<path>            # dashboard on dev
+npm run walk -- --local /organizations/<org id>/<path>    # dashboard on the laptop
+npm run walk -- <full url>                                # share page, website
 ```
 
+On `local`, every script you write runs the same way, under the api's Local Environment:
+`node lib/target.js local -- node <your script>` from `drawbridge-tests`. The seeding helper
+and the saved session then point at the laptop too (`e2e/.auth/user.local.json`). A local
+walk needs the api, sync and the dashboard running (`npm run local` in each).
+
 It signs in, saves a screenshot and prints the headings, buttons, links, inputs and table
 headers on the page. **Read the screenshot file with the Read tool every time.** What you
 report as seen is what is on that image and in that printed list, nothing else. Setup and

package/.claude-template/skills/drawbridge-release/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: drawbridge-release
+description: Use when someone gives you a release task from the Asana project "Drawbridge - Releases" and says to run, open, build or promote it — the only way a release moves from Planned to Released. Also use when asked what state a release is in or what its next step is.
+---
+
+# Run a release
+
+One Asana release task is the unit. Its id names everything: the `release/<id>` branch in every app the release touches, `drawbridge-api/scripts/migration-<id>.js` when it moves data, `drawbridge-docs/releases/<id>.md`, and the band on the dev dashboard. The task moves Planned → Building → Review → QA → Approved → Released; every state change is a section move in that project and nothing else records state.
+
+The ten lines below are the release, as Darren confirmed them on 2026-10-22. The skill owns lines 1 to 5 and 10 and runs them without anyone present once line 2 has its yes. A developer owns 6 and 9. A QA person owns 7 and 8. The skill never does a developer's or a tester's line for them.
+
+1. A person gives the skill the release task link. The skill checks `gh auth status`.
+2. The skill reads the task and subtasks, writes the stories, sends ONE numbered list and waits for the yes.
+3. Task → Building: branches, the release document, the band.
+4. The skill builds on the release branches against the Local database, with the QA agent run locally.
+5. One pull request per repo, assigned to the developer named in line 2. Task → Review.
+6. The developer reviews, runs the branch locally, merges; runs any migration on dev; moves the task → QA and assigns the QA person.
+7. The QA person tests on dev.
+8. The QA person moves the task → Approved.
+9. The developer promotes by hand, with the skill as checklist.
+10. The skill writes "What's new", completes the subtasks, moves the task → Released, cleans up.
+
+## Line 1: start
+
+Read the release task and every subtask through `drawbridge-tests/lib/asana.js` (`api( 'GET', '/tasks/<id>?opt_fields=name,notes,memberships.section.name' )`, then `/tasks/<id>/subtasks`). Subtasks live in "DrawBridge - Application" and stay there. `gh auth status` must pass; if it does not, stop and tell the person `brew install gh && gh auth login`. Other developers start releases from their own machines, so this is never assumed.
+
+## Line 2: the one list
+
+For every subtask, find or write the story (`drawbridge-feature` step 1). Then ONE numbered list to the person who started the release, each item three plain sentences (`conventions/rules.md` rule 7), holding:
+
+- every unknown from every story;
+- **who on the development team takes the pull requests** (a GitHub username). Asked now so nobody needs to be present between lines 3 and 5. Never guess a reviewer;
+- **a package publish, if any subtask names `@drawbridge/components` or `@drawbridge/drawbridge-utils`**, in these words: this release publishes a package; the package is built, reviewed and merged to the package's `main` first; the person publishes it when asked (the skill cannot), the publish needs the one-time password until the automation token (queue task 1218041740718540) exists; the apps' pull requests cannot merge until their pin bumps resolve.
+
+Wait for the yes. Nothing below runs before it.
+
+## Line 3: Building
+
+1. Move the task to Building (`POST /sections/1219601033297172/addTask { task }`).
+2. `release/<id>` in every repo a subtask touches, off `develop` (components and utils off `main`; docs off `main`), each in a worktree under `/Users/darrenshea/Projects/.worktrees/<repo>-release-<id>` so no main checkout changes branch.
+3. Copy `drawbridge-docs/templates/release.md` to `releases/<id>.md`, fill Scope and Branches (reviewer from line 2), commit on the docs branch. The markdown is the one record; there is no json.
+4. Write the task link into `drawbridge-api/release.json`, commit on the api's `develop` directly ("release <id>: band"), push. Dev shows the yellow band above the account once the api redeploys. This is the only develop commit before the pull requests merge.
+5. If the release task has no subtask named "Marketing: What's new", create one.
+
+## Line 4: build, on Local
+
+All work on the release branches against the **Local** database. Develop and its schema are never touched while a release is being built, and one release at a time is promoted to develop.
+
+1. **Local up.** `npm run migrate -- refresh` in the api (copies dev into Local; `--dry` first), then `npm run local` in every app the release touches: dashboard 3000, share 3001, website 3002, api 4000, sync 4001, webhooks 4002. The scripts force the ports; nothing sets them.
+2. **Package first.** A package subtask is built, reviewed and merged to the package's `main` before any app subtask that depends on it; when it is merged, ask the person to publish, then bump the pin on the apps' release branches.
+3. **Per subtask**, on the release branch: read the story and the reference page, one graph query, failing test first where a suite exists, the change, `npm test` in that repo. One commit per subtask, its message starting with the subtask id.
+4. **Migration.** If any subtask moves data, ONE file, `drawbridge-api/scripts/migration-<id>.js`, exporting `({ controller }) => async ({ dryRun, organization, ...args }) => counts`, holding every data step. It uses the controller only; a dry run refuses controller writes but cannot refuse a native `collection.drop()` or `dropIndex()`, so a step that drops anything branches on `dryRun` itself and reports what it would drop. Prove it on Local: `npm run migrate -- <id> --dry --env local`, then `--env local`. The runner prints the counts and writes `runs/<env>-<id>-<time>.json`; nothing copies them anywhere.
+5. **Walk every touched app on Local**: `npm run walk -- --local <path or url>` from drawbridge-tests (dashboard at `localhost:3000`; sync must be running for anything live). Record what was seen; a label quoted later comes from this walk.
+6. **QA agent on Local.** Dispatch `drawbridge-qa` with `target : local`, once per subtask that has a story (story paths, the SUBTASK id, the organization id from `drawbridge-tests/fixtures/e2e-org.md`, present on Local because Local is a copy of dev). Fix every fail on the release branch, redispatch, until every `drawbridge-tests/results/qa/<subtask id>.json` reads `fails : 0`. The fixes are commits in the same pull request; that is why the agent runs here and not on dev (Darren: "all agent work is done locally so the work and fixes get committed as part of the PR").
+   **Inbound webhooks are the exception.** Every Local Environment points `APP_CLIENT_WEBHOOKS_URI` at `http://localhost:4002`, which Shopify, Stripe and Twilio cannot reach, so a change to how a webhook is received or handled is marked in the Scope table as "webhooks: tested on dev" and the QA person checks it on dev in line 7.
+7. **Review.** `superpowers:code-reviewer` against the stories, then `ponytail-review`, on each repo's diff.
+8. Push the release branches.
+
+## Line 5: Review
+
+1. One pull request per repo: `gh pr create --base develop --head release/<id> --title "Release <id>: <task name>" --assignee <developer> --reviewer <developer> --body <the Scope table, the per-subtask commits, the QA reports' paths, and the migration's dev command if there is one>`. Components and utils target `main`.
+2. Fill the Branches table in `releases/<id>.md` with the PR links; commit.
+3. Put the PR links on the release task as ONE numbered list (`drawbridge-asana-comment`), assign the task to the developer, move it to Review (`POST /sections/1219762451512990/addTask`).
+4. Stop. Report the PR links.
+
+## Lines 6 to 8: the developer and the QA person
+
+The skill does none of this. For the record, so the skill can answer "what is the next step":
+
+- Line 6, the developer: reviews the diff, runs the branch locally, approves and merges. Dev deploys itself. If there is a migration: `npm run migrate -- <id> --dry --env dev` from the api checkout on `develop`, read the printed result, then without `--dry`. Then moves the task to QA and assigns the QA person in Asana.
+- Line 7, the QA person: tests on dev. The band already names the release.
+- Line 8, the QA person: moves the task to Approved.
+
+## Line 9: promote, as the developer's checklist
+
+**Production is done by a developer, by hand: every push to `main`, every deploy, the migration** (Darren: "All production deployment and migrations will be done manually, you are only to aid a developer deploying to production"). The skill hands over one step at a time, waits for "done", verifies by reading, records, then hands over the next.
+
+1. Confirm the task sits in Approved; refuse otherwise.
+2. Hand over the preparation: the window (avoid 00:00 and 02:00 UTC, sync's scheduled jobs) and the Atlas snapshot. Wait.
+3. Per app, in this order unless the release doc says otherwise (dashboard, api, sync, share, webhooks, website): hand over the fast-forward of `main` to the exact tested `develop` commit (`git push origin <sha>:refs/heads/main`), then the Deploy click in DigitalOcean (prod apps deploy from `main` with deploy-on-push off). Verify by reading: the deployment ACTIVE, `/health` reporting the commit. Note the commit in the release doc's Promote section.
+4. Migration, after the api is ACTIVE and before sync: from the developer's api checkout on `main` at the promoted commit, with the api's two-line `.env.production` beside `migrate.js`: `npm run migrate -- <id> --env prod --dry --sha <promoted api commit>`, read the result, then without `--dry`. (The deployed api container can run it too, through `doctl apps console`.) Then `git rm drawbridge-api/scripts/migration-<id>.js`, committed on develop, and `main` fast-forwarded once more.
+5. Hand over the verification list from the release doc's Promote section; the developer reports what they saw; the skill fills it in.
+
+## Line 10: Released
+
+1. **What's new.** Write the marketing breakdown into the "Marketing: What's new" subtask, in the customer's words, one item per subtask a merchant would notice (`drawbridge-asana-comment` for the shape, `humanizer` for the words).
+2. Complete every subtask (Application → Complete). Move the release task to Released (`POST /sections/1219601137919036/addTask`).
+3. Remove the worktrees; refresh the knowledge graph (`drawbridge-ship-feature` step 5). Report the promoted commits.
+
+## What the skill never does
+
+- Push `main`, deploy production, run anything against the production or dev database, publish a package, merge a pull request, assign the QA person or move the task to QA, Approved. Those are a developer's or a tester's lines.
+- Name a reviewer, a tester, a window or a release scope that nobody told it. Each is one numbered question in line 2.
+- Write a release document, branch or migration under any name but the Asana id.
+- Build or run the QA agent against dev or develop before the pull requests merge. Local only.
+
+## Section ids
+
+Planned `1219601041167595`, Building `1219601033297172`, Review `1219762451512990`, QA `1219601033155111`, Approved `1219601033299066`, Released `1219601137919036`; project `1219601041167594`, workspace `15457086713130`.

package/conventions/migrations.md

@@ -57,22 +57,21 @@ quietly that dev served stale code the whole time.
 - **Production runs inside the deployed api container**, never from a laptop,
   so no laptop ever holds a production file: `doctl apps console <prod api app
   id> drawbridge-api`, then `op run --environment "$OP_ENVIRONMENT_ID" -- node
-  migrate.js <asana id> --env prod --dry --sha <promoted commit>`, then the same
-  without `--dry` and with `--release <slug>`. The image carries `migrate.js`
-  and `scripts/`. There is no git there, so the runner proves `--sha`
+  migrate.js <release asana id> --env prod --dry --sha <promoted commit>`, then the
+  same without `--dry`. The image carries `migrate.js` and `scripts/`. There is no git there, so the runner proves `--sha`
   against `APP_COMMIT_HASH` (the deployed commit, injected by the app spec); in
   a checkout it still refuses production off `main`, at the wrong commit, or with
   `scripts/`, `lib/` or `migrate.js` modified. `cat` the counts file from the
   console shell afterwards, outside `op run`, to read it unconcealed.
-- A real fleet run records itself when drawbridge-docs sits beside the api:
-  `drawbridge-docs/releases/<slug>.json` gets
-  `migrations.<asana id>.<development|production> = true`, and the release
-  document `releases/<slug>.md` gets a row in its Migrations table. That is how
-  "has it run on prod?" is answered. In the container there is no docs checkout:
-  the runner prints exactly which flag and row to write, and you commit them
-  from a laptop from the counts file. After a production run the promote step
-  deletes `scripts/migration-<asana id>.js`, so the folder only ever holds what
-  has not run.
+- **The runner records nothing but its counts file**, and nothing else records
+  a run either: a developer runs the migration on dev after the pull request
+  merges and reads the printed result, and runs it on production from their
+  laptop (the api's two-line `.env.production`) during the promote (Darren,
+  2026-10-22: the runner "shouldn't be writing to a row either"; "a development
+  migration just returns the result"). There is no release json. "Has it run
+  on prod?" is answered by `scripts/migration-<id>.js` still existing: after
+  the production run the developer `git rm`s it, so the folder only ever holds
+  what has not run.
 - Add it to the release document in `drawbridge-docs/releases/` for the launch it
   belongs to, with the ordering constraint stated: what has to be deployed before
   it can run, and what breaks if it runs early.

package/conventions/walk-the-app.md

@@ -56,8 +56,16 @@ every later walk until it expires (`e2e/auth.setup.js`, `lib/otc.js`).
 npm run walk -- /organizations/<org id>/suppressions          # a dashboard path
 npm run walk -- https://<slug>.dev.drwbrdg.com/<campaign>      # any full URL (share, website)
 npm run walk -- /organizations/<org id>/campaigns --out shot.png
+npm run walk -- --local /organizations/<org id>/campaigns      # the laptop: localhost:3000, the Local database
+npm run walk -- --production https://trydrawbridge.com/pricing  # public pages only; no signed-in production walk
 ```
 
+`--local` re-runs the walk under the api's Local Environment through the api's `scripts/op.sh`
+(`lib/target.js`), so this repo keeps its single dev-pointing `.env`; the api, sync and the
+dashboard must be running (`npm run local` in each). Each target keeps its own saved session
+(`e2e/.auth/user.local.json` for the laptop). Any script of your own runs the same way:
+`node lib/target.js local -- node <script>`.
+
 It signs in if the saved session is missing or stale, opens the page, saves a screenshot
 (default `results/walk/<timestamp>.png`) and prints the headings, buttons, links and table
 headers a person would see. **Read the screenshot** (the Read tool renders images), then

package/package.json

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

package/scripts/check-doc-links.js

@@ -78,8 +78,9 @@ const unresolved = []
 for (const name of fs.readdirSync(familyRoot, { withFileTypes: true })) {
   if (!name.isDirectory() || !name.name.startsWith('drawbridge-')) continue
   // drawbridge-agents is the meta-tooling repo (this script, the hook, the convention docs all
-  // contain the literal tag strings) — tags live in the app repos, so skip it.
-  if (name.name === 'drawbridge-agents') continue
+  // contain the literal tag strings) — tags live in the app repos, so skip it, and skip its
+  // worktrees too (drawbridge-agents-<branch>), which carry the same strings.
+  if (name.name.startsWith('drawbridge-agents')) continue
   const repoRoot = path.join(familyRoot, name.name)
   walk(repoRoot, (file) => {
     if (!SOURCE_EXTENSIONS.has(path.extname(file))) return