vignette-todo-run

Files (12)

• SKILL.md
• openai.yaml · agents/
• claude.md · launchers/
• bootstrap-prompt-2026-09-17.md · references/
• finish-run.sh · scripts/
• setup-run.sh · scripts/
• test-copy.sh · scripts/
• ARCHITECTURE.md · templates/
• BRIEF.md · templates/
• INTEGRATOR.md · templates/
• ITEM-example.md · templates/
• REVIEWER.md · templates/

SKILL.md (first lines)

# 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, which also removes the landed items from `docs/TODOS.md`,
and a run report in `~/Code/vignette-todo/reports/`.
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 (`main` unless said), the run tag,
the items in Pete's words, and whether Pete is at the Mac (the templates assume he may be). The
tag is `todoN`, one more than the highest in the base's commit subjects, since a finished run's
branches are pruned: `git log --format=%s <base> | grep -o 'todo[0-9]*' | sort -V | tail -1`.

## 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`, and
makes `~/Code/vignette-todo/<name>-scratch` with `shots/`, `captures/`, and a `settings.json`
seeded from `~/.config/vignette/settings.json` with jq. The seed points it at the shots folder and
turns `debug` on. It turns off Apple sync, launch at login, and copy and annotate on capture, hides
the menu bar icon, marks setup and the skill offer done, and sets a shortcut that is not Pete's,
`ctrl+option+cmd+9`. It also copies `scripts/test-copy.sh` to `~/Code/vignette-todo/`. Agent names
are lowercase letters, digits, and hyphens, since each becomes a bundle id and a URL scheme. 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's tag;
its reports are in `~/Code/vignette-todo/<tag>-archive/reports/`), `{{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_REPORTS}}` (the integration reports of the runs
since the baseline).
`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 writes the run report to
`reports/integration.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. Remove the landed items from `docs/TODOS.md` in one
commit on the integration branch, so they leave the list when Pete merges (the one place the
orchestrator commits). Then `scripts/finish-run.sh <run>`: it unregisters every worktree build
and test copy from LaunchServices, confirms Pete's build answers for `vignette://` and runs 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, the double tap, a
label's feel), incidents (settings mtime before and after, clipboard writes, input that went
astray), and the state of the Mac.

## Hazards the templates encode

Every worktree builds Pete's bundle id and `vignette://` scheme, and a second launch of a bundle id
quits the older instance. So agents run their builds through `test-copy.sh`, as copies with their
own bundle id, scheme, log, and Application Support folder, and without the bundled agent skill,
which a launch would copy over Pete's installed one. Pete's build is never launched, quit, or sent
a URL. A copy launched without `VIGNETTE_SETTINGS` runs on Pete's real settings file and
`Settings.bootstrap` rewrites it, so the script refuses a URL unless the running copy carries the
scratch path. The copy is not trusted for Accessibility: it takes the Dock to span the whole bottom
edge and cannot use the double tap. One driving round at a time behind
`~/Code/vignette-todo/launch.lock`, because the pointer, the keys, and the screen are shared.
Synthetic input reaches whatever is frontmost: `[state]` first, keys to the copy's pid, every press
checked against the window server, a level-1 catcher only over the rect of timed presses, and never
Escape or Cmd+Q. Done, Copy, Copy Drawing, and `stitch` write Pete's clipboard. The settings mtime
is recorded around every test run and round. `references/bootstrap-prompt-2026-09-17.md` is the
prompt this skill was written from.

From petekp/claude-code-setup, MIT.

More from petekp/claude-code-setup