@drawbridge/drawbridge-agents 0.1.77 → 0.1.79

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**: their GitHub username (for the pull requests) and their Asana name (for the task). 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. A release that publishes a package stops once more, at the publish (line 4 step 2); everything else between lines 3 and 5 runs without anyone present.
+
+## Line 3: Building
+
+1. **One release at a time.** List the project's tasks (`GET /projects/1219601041167594/tasks?opt_fields=name,memberships.section.name`). If any other release sits in Building, Review, QA or Approved, stop and say which one; only one release is being built or tested at a time (Darren, 2026-10-22). Then move this task to Building (`POST /sections/1219601033297172/addTask { task }`).
+2. `release/<id>` in every repo a subtask touches, off `develop` (components and utils off `main`), each in a worktree under `/Users/darrenshea/Projects/.worktrees/<repo>-release-<id>` so no main checkout changes branch. **drawbridge-docs is the exception**: its `release/<id>` branch is made in the main docs checkout (docs is `main`-only and single-writer), because `npx drawbridge-agents-check-stories` reads nothing from a worktree path (Asana 1218852240225835). "Repo a subtask touches" includes docs, components and utils, not only the six apps.
+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. If `drawbridge-api/release.json` does not already carry this task's link, write it, 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. When the link is already there, say so and move on.
+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. Anything a person must do around the run (export a collection and read it back before a drop, take a snapshot) is written into the release doc's Migrations section as the developer's steps, not into the file. 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: `APP_TEST_ORG_ID` in `drawbridge-tests/.env`, the e2e organization `fixtures/e2e-org.md` describes, present on Local because Local is a copy of dev). A subtask spanning many stories gets one report listing them all. 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, write to the production or dev database (the refresh READS dev to copy it into Local, and that is all), publish a package, merge a pull request, assign the QA person or move the task to QA or Approved. Those are a developer's or a tester's lines.
+- Name a reviewer or a release scope that nobody told it; both are asked in line 2. The tester is the developer's choice at line 6 and the window is the developer's at line 9; the skill asks for neither.
+- 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
+
+Releases project `1219601041167594` (workspace `15457086713130`): Planned `1219601041167595`, Building `1219601033297172`, Review `1219762451512990`, QA `1219601033155111`, Approved `1219601033299066`, Released `1219601137919036`. Application project, where the subtasks live: Complete `1213887707425532`.

package/conventions/migrations.md

@@ -1,6 +1,6 @@
 # Migrations live in the api
 
-Every one-off migration and backfill goes in `drawbridge-api/scripts.js`.
+Every one-off migration and backfill is one file in `drawbridge-api/scripts/`, `migration-<release asana id>.js`, run through `drawbridge-api/migrate.js` and nothing else.
 
 **The only exception is media processing** — work that needs ffmpeg or sharp to
 open an image or a video. Those dependencies exist in `drawbridge-sync` and
@@ -46,33 +46,36 @@ quietly that dev served stale code the whole time.
   return (`{ found, updated }` or whatever the counts are). The first run of a
   migration is a read.
 - Run it only through the runner. On a laptop, from the api checkout:
-  `npm run migrate -- <asana id> --dry --env dev`, then
-  `--organization <id> --env dev --release <slug>`, then `--env dev --release <slug>`.
+  `npm run migrate -- <release asana id> --dry --env dev`, then
+  `--organization <org id> --env dev`, then `--env dev`. There is no `--release`
+  flag: the migration id IS the release id.
   No env file holds a value: the runner re-runs itself through `scripts/op.sh`
   with the file `--env` names (`.env.local` / `.env.development`, two lines naming
   a 1Password Environment), so the Environment is injected the way the servers
   get it. It refuses the wrong cluster, hands a dry run a controller that throws
   on any write, and writes the result to `runs/<env>-<fn>-<time>.json` (read the
   file, never the console: `op run` conceals anything that looks like a secret).
-- **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`
-  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.
+- **Production is run by a developer, by hand, from their api checkout** on
+  `main` at the promoted commit with a clean tree, with the api's two-line
+  `.env.production` beside `migrate.js` (Darren, 2026-10-22: "the api is the
+  only place that needs this, and locally it's there"):
+  `npm run migrate -- <release asana id> --env prod --dry --sha <promoted commit>`,
+  then the same without `--dry`. The runner refuses production off `main`, at
+  the wrong commit, or with `scripts/`, `lib/` or `migrate.js` modified. The
+  deployed api container can run it too (`doctl apps console <prod api app id>
+  drawbridge-api`, then the `op run --environment "$OP_ENVIRONMENT_ID" -- node
+  migrate.js …` form; the image carries `migrate.js` and `scripts/`, there is no
+  git, so `--sha` is proven against `APP_COMMIT_HASH`). An agent never runs it:
+  it hands the developer the command and verifies by reading afterwards.
+- **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.77",
+  "version": "0.1.79",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {