Vignette TODO run

One run takes a base branch and a list of items from docs/TODOS.md, and ends with one integration branch Pete tests by hand, a run report under docs/, and the items marked landed. Read AGENTS.md in the Vignette checkout before planning: the loop, the rules for several builds on one Mac, and the measuring paragraphs are what the templates enforce.

Roles. The orchestrator (you) plans, briefs, orchestrates, and reviews, and writes no product code. Delegated agents do the code and the verification, one worktree each. One integrator, one adversarial reviewer, and, when asked, one architecture sweep. launchers/claude.md says how to spawn them in Claude Code; in Codex use its own delegation with the same prompts.

Inputs to settle before anything is spawned: the base branch (foundation unless said), the run tag (todoN, one more than the last todoN/* branch in git branch -a), the items in Pete's words, and whether Pete is at the Mac (the templates assume he may be).

1. Plan, and show it

Group the items by the files they touch so agents do not collide. Read the items, grep for the files each names, and check for a shared file between groups (Settings.swift and DebugPanel.swift are shared by any item that adds a tweak; AGENTS.md and README.md by every item). Inside a group, order items so a measurement comes before the change that would confound it. Show Pete the grouping (a table: agent, branch, items, files), the order inside each group, the shared files, and the merge order. Wait for a yes unless he said to proceed.

2. Set up

scripts/setup-run.sh <run> <base> <name>... creates, for each agent name, the worktree ~/Code/vignette-todo/<name> on <run>/<name> from <base>, copies scripts/signing.env, runs pnpm install in web/, and makes ~/Code/vignette-todo/<name>-scratch with shots/, captures/, and a settings.json seeded from ~/.config/vignette/settings.json with jq (screenshotsFolder = the shots folder, syncAppleSaveLocation false, debug true, launchAtLogin false, copyOnCapture false, annotateOnCapture false). It archives a previous run's briefs, reports, and scratch folders into ~/Code/vignette-todo/<previous run>-archive/ first. It prints the settings mtime; record it.

3. Brief

Fill the templates into ~/Code/vignette-todo/: BRIEF.md, one items/<name>.md per agent, INTEGRATOR.md, REVIEWER.md, and ARCHITECTURE.md when a sweep is wanted. Placeholders: {{RUN}}, {{BASE}}, {{BASE_SHA}}, {{DATE}}, {{PREVIOUS_RUN}} (the last run report's date suffix), {{SESSION_URL}} (this session's Claude-Session URL, or the equivalent), {{HOME}}, {{BRANCH_COUNT}}, {{MERGE_ORDER}}, {{SHARED_FILES}}, {{CROSS_BRANCH_PATHS}} (the smoke round: paths that cross branches, not what each agent proved), {{ITEM_SPECIFIC_CHECKS}} (what the reviewer should attack for these items), {{SWEEP_BASELINE}}, {{RUN_DOCS}}. templates/ITEM-example.md is a filled item file: Pete's words quoted verbatim under the item number, then notes (the files, the order, candidates named as candidates, what only Pete's hands can check). The rules in BRIEF.md are the run's contract; add rules only from an incident.

4. Run

Spawn every coding agent in one message. Each returns a report; save it to ~/Code/vignette-todo/reports/<name>.md (the agents write it there too). Append the loose ends from the reports to INTEGRATOR.md (an unverified path another branch can exercise, a comment an agent could not touch, a shared-file hazard), then spawn the integrator: it creates <run>/integration from the base, merges in order with build and tests after each, reads every file two branches touched by hand, runs the smoke round, and commits docs/run-<date>.md. Then spawn the reviewer over <base>..<run>/integration with the reports; and the architecture sweep, which can start as soon as the coding agents are done since it reads the base checkout read-only. Route the reviewer's confirmed findings and the sweep's safe cleanups (no behaviour change) back to the same integrator with a message: "Review fixes: …" commits and a Review section in the report. Refactors and design questions go to Pete, not to the integrator. Run ./scripts/build.sh --test yourself in the integration worktree at the end.

5. Hand over

Do not merge into the base unless asked. Mark the items landed in docs/TODOS.md on the base branch (the one place the orchestrator commits). Then scripts/finish-run.sh <run>: it unregisters every worktree's app from LaunchServices, confirms Pete's build answers for vignette://, checks his build is running on his real settings, and prints the worktrees and branches to prune once Pete has merged (it prunes only with --prune). Report: the branch and its tip, what landed per item, the open questions, exactly what only Pete's hands can check (a real pinch, smart zoom, the second display, a label's feel), incidents (settings mtime before and after, clipboard, drafts), and the state of the Mac.

Hazards the templates encode

Every worktree builds the same bundle id. A bare open -g vignette://… launches whichever copy LaunchServices registered last, on Pete's real settings, and Settings.bootstrap rewrites that file with the build's key set; so every URL goes through open -g -a <own app>, every launch carries VIGNETTE_SETTINGS=<scratch>, the running pid is checked by its own environment (ps -wwEp) before every action, one launch at a time behind ~/Code/vignette-todo/launch.lock, own pid killed before every launch (open --env is ignored while the bundle runs), and Pete's build is put back after every round. A unit test that reaches Settings.shared outside the scheme's env writes the real file; the settings mtime is recorded around every test run and round. Synthetic input reaches whatever is frontmost: [state] first, never Escape or Cmd+Q. references/bootstrap-prompt-2026-09-17.md is the prompt this skill was written from.