@workerstack/repo 0.0.0-stage → 0.1.0

package/agents/skills/commit-push/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: commit-push
+description: >
+  Commit with a Conventional Commits subject, then push. Use for /commit-push,
+  "commit and push", "commit this and push". Must push. Never force-push.
+---
+Inspect `git status` + `git diff` (staged and unstaged) before the message.
+
+Diff pass on the hunks you will stage: delete narrating comments, unused defensive guards or try/catch on trusted paths, `any` casts that only silence types, dead compatibility, and unrelated hunks. Keep a comment only when it states a constraint the code cannot encode. Keep behavior otherwise. Do not spawn a reviewer.
+
+Stage only user intent. Never blind `git add -A` / `git add .`. Split unrelated concerns into multiple commits.
+
+If a unique in-progress file exists under `.tmp/repo/implementations/`, its `## Files` is the default stage set. Still inspect `git status`.
+
+Message = Conventional Commits **subject only**: `type(scope): subject` (scope optional).
+
+Types: feat fix docs style refactor perf test build ci chore revert.
+
+Subject: imperative lowercase no trailing period.
+
+NO body. NO footer. NO `Co-Authored-By`. NO `Generated with`. NO 🤖. NO trailers. No AI attribution. Work belongs to the human.
+
+Must `git push`. Do not load /commit. Ignore never-push.
+
+## Where
+
+Run `git rev-parse --show-toplevel` and `git branch --show-current` first.
+
+- Managed worktree (`<root>/.worktrees/<name>` on `wt/<name>`): commit there, run `cd <root> && bun repo worktree finish <name>` (from the root, not inside the worktree), then push the default branch from the root and skip the Recent rows below. `wt/*` never counts as Recent and is never pushed. If `finish` fails, resolve it as `/commit` says and push nothing.
+- Main checkout: the gate denies a commit there unless the user's message names commit, and this command does. Commit only changes the user made there. Your own changes go through `bun repo worktree add <name>`.
+- Any other linked worktree (T3 Code, Claude Desktop): `finish` cannot land it. Commit and push its branch per Branch.
+
+## Branch
+
+Current: `git rev-parse --abbrev-ref HEAD`
+
+Default: `git symbolic-ref --quiet --short refs/remotes/origin/HEAD` (strip `origin/`). If that fails: ask. Never invent default.
+
+Recent (frozen flags; do not change):
+
+```
+git reflog -n 30
+git for-each-ref --count=8 --sort=-committerdate --format='%(refname:short) %(committerdate:unix)' refs/heads
+```
+
+Recent = unique existing non-default, non-`wt/*` names from those two outputs whose `committerdate` unix is ≤7d (`now - 604800`). Never invent branch names. Unknown/ambiguous names → drop them, do not guess.
+
+| state | action |
+| current is `wt/*` | do not push; follow Where (`finish`, then push the default branch from the root) |
+| current ≠ default AND not `wt/*` | push current |
+| default AND 0 recent | push default |
+| default AND exactly 1 recent exists | push that name (`git push origin <name>`, no checkout: the gate denies `git checkout` in the main checkout) |
+| else | ask; do not push yet |
+
+No upstream (`git rev-parse --abbrev-ref @{upstream}` fails): `git push -u origin <branch>`. Else `git push`.
+
+Never force-push. Never `--force`, `-f`, `--force-with-lease`, `+<branch>`.
+
+Protocol: `node_modules/@workerstack/repo/references/cascade.md`. Do not paste cascade.

package/agents/skills/commit-push-deploy/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: commit-push-deploy
+description: >
+  Commit, push, then deploy only if allowlisted infra already exists. Use for
+  /commit-push-deploy, "commit push deploy", "deploy this". Must push. Never
+  force-push. Never invent infra.
+---
+Inspect `git status` + `git diff` (staged and unstaged) before the message.
+
+Diff pass on the hunks you will stage: delete narrating comments, unused defensive guards or try/catch on trusted paths, `any` casts that only silence types, dead compatibility, and unrelated hunks. Keep a comment only when it states a constraint the code cannot encode. Keep behavior otherwise. Do not spawn a reviewer.
+
+Stage only user intent. Never blind `git add -A` / `git add .`. Split unrelated concerns into multiple commits.
+
+If a unique in-progress file exists under `.tmp/repo/implementations/`, its `## Files` is the default stage set. Still inspect `git status`.
+
+Message = Conventional Commits **subject only**: `type(scope): subject` (scope optional).
+
+Types: feat fix docs style refactor perf test build ci chore revert.
+
+Subject: imperative lowercase no trailing period.
+
+NO body. NO footer. NO `Co-Authored-By`. NO `Generated with`. NO 🤖. NO trailers. No AI attribution. Work belongs to the human.
+
+Must `git push`. Do not load /commit. Ignore never-push.
+
+## Where
+
+Run `git rev-parse --show-toplevel` and `git branch --show-current` first.
+
+- Managed worktree (`<root>/.worktrees/<name>` on `wt/<name>`): commit there, run `cd <root> && bun repo worktree finish <name>` (from the root, not inside the worktree), then push the default branch from the root and skip the Recent rows below. `wt/*` never counts as Recent and is never pushed. If `finish` fails, resolve it as `/commit` says and push nothing.
+- Main checkout: the gate denies a commit there unless the user's message names commit, and this command does. Commit only changes the user made there. Your own changes go through `bun repo worktree add <name>`.
+- Any other linked worktree (T3 Code, Claude Desktop): `finish` cannot land it. Commit and push its branch per Branch.
+
+## Branch
+
+Current: `git rev-parse --abbrev-ref HEAD`
+
+Default: `git symbolic-ref --quiet --short refs/remotes/origin/HEAD` (strip `origin/`). If that fails: ask. Never invent default.
+
+Recent (frozen flags; do not change):
+
+```
+git reflog -n 30
+git for-each-ref --count=8 --sort=-committerdate --format='%(refname:short) %(committerdate:unix)' refs/heads
+```
+
+Recent = unique existing non-default, non-`wt/*` names from those two outputs whose `committerdate` unix is ≤7d (`now - 604800`). Never invent branch names. Unknown/ambiguous names → drop them, do not guess.
+
+| state | action |
+| current is `wt/*` | do not push; follow Where (`finish`, then push the default branch from the root) |
+| current ≠ default AND not `wt/*` | push current |
+| default AND 0 recent | push default |
+| default AND exactly 1 recent exists | push that name (`git push origin <name>`, no checkout: the gate denies `git checkout` in the main checkout) |
+| else | ask; do not push yet |
+
+No upstream (`git rev-parse --abbrev-ref @{upstream}` fails): `git push -u origin <branch>`. Else `git push`.
+
+Never force-push. Never `--force`, `-f`, `--force-with-lease`, `+<branch>`.
+
+## Deploy
+
+After push. Detect **existing** repo-root (or listed) paths only — never create them:
+
+`fly.toml` `vercel.json` `netlify.toml` `wrangler.toml` `wrangler.jsonc` `cloudflare.config.ts` `railway.toml` `railway.json` `render.yaml` `render.yml` `app.yaml` `Dockerfile` `docker-compose.yml` `docker-compose.yaml` `samconfig.toml` `serverless.yml` `serverless.yaml` `Pulumi.yaml` `terraform/` `.do/app.yaml`
+
+This repo (`package.json` `name` `@workerstack/repo`): skip deploy. Stop after push.
+
+No allowlist hit: skip. Never invent infra, hosts, workflows, or config.
+
+Hit: run only a deploy command already documented in-repo (scripts/CI/README). Do not guess a provider. Do not add files.
+
+Cloudflare hit (`wrangler.toml`, `wrangler.jsonc`, `cloudflare.config.ts`) with no in-repo deploy command: run `cf deploy`. Read `node_modules/@workerstack/repo/references/cloudflare.md` first.
+
+Protocol: `node_modules/@workerstack/repo/references/cascade.md`. Do not paste cascade.

package/agents/skills/commit-push-release/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: commit-push-release
+description: >
+  Commit, push, and for "release" run `bun repo release` from the main checkout
+  (it bumps, stamps CHANGELOG.md, pushes, waits on CI, tags), then
+  `bun repo release wait <tag>`. Use for /commit-push-release, "commit push
+  release", "release". Must push. Never force-push. No bun/npm/gh publish.
+---
+Inspect `git status` + `git diff` (staged and unstaged) before the message.
+
+Diff pass on the hunks you will stage: delete narrating comments, unused defensive guards or try/catch on trusted paths, `any` casts that only silence types, dead compatibility, and unrelated hunks. Keep a comment only when it states a constraint the code cannot encode. Keep behavior otherwise. Do not spawn a reviewer.
+
+Stage only user intent. Never blind `git add -A` / `git add .`. Split unrelated concerns into multiple commits.
+
+If a unique in-progress file exists under `.tmp/repo/implementations/`, its `## Files` is the default stage set. Still inspect `git status`.
+
+Message = Conventional Commits **subject only**: `type(scope): subject` (scope optional).
+
+Types: feat fix docs style refactor perf test build ci chore revert.
+
+Subject: imperative lowercase no trailing period.
+
+NO body. NO footer. NO `Co-Authored-By`. NO `Generated with`. NO 🤖. NO trailers. No AI attribution. Work belongs to the human.
+
+Must `git push`. Do not load /commit. Ignore never-push.
+
+## Where
+
+Run `git rev-parse --show-toplevel` and `git branch --show-current` first.
+
+- Managed worktree (`<root>/.worktrees/<name>` on `wt/<name>`): commit there, run `cd <root> && bun repo worktree finish <name>` (from the root, not inside the worktree), then push the default branch from the root and skip the Recent rows below. `wt/*` never counts as Recent and is never pushed. If `finish` fails, resolve it as `/commit` says and push nothing.
+- Main checkout: the gate denies a commit there unless the user's message names commit, and this command does. Commit only changes the user made there. Your own changes go through `bun repo worktree add <name>`.
+- Any other linked worktree (T3 Code, Claude Desktop): `finish` cannot land it. Commit and push its branch per Branch.
+
+## Branch
+
+Current: `git rev-parse --abbrev-ref HEAD`
+
+Default: `git symbolic-ref --quiet --short refs/remotes/origin/HEAD` (strip `origin/`). If that fails: ask. Never invent default.
+
+Recent (frozen flags; do not change):
+
+```
+git reflog -n 30
+git for-each-ref --count=8 --sort=-committerdate --format='%(refname:short) %(committerdate:unix)' refs/heads
+```
+
+Recent = unique existing non-default, non-`wt/*` names from those two outputs whose `committerdate` unix is ≤7d (`now - 604800`). Never invent branch names. Unknown/ambiguous names → drop them, do not guess.
+
+| state | action |
+| current is `wt/*` | do not push; follow Where (`finish`, then push the default branch from the root) |
+| current ≠ default AND not `wt/*` | push current |
+| default AND 0 recent | push default |
+| default AND exactly 1 recent exists | push that name (`git push origin <name>`, no checkout: the gate denies `git checkout` in the main checkout) |
+| else | ask; do not push yet |
+
+No upstream (`git rev-parse --abbrev-ref @{upstream}` fails): `git push -u origin <branch>`. Else `git push`.
+
+Never force-push. Never `--force`, `-f`, `--force-with-lease`, `+<branch>`.
+
+## Release
+
+Run `bun repo release` from the main checkout (not a worktree), on the default branch, clean and equal to origin, after the commits are pushed per **Branch**. Do not ask the user for a bump and do not edit `package.json`: the command reads the Conventional Commits since the last tag. Add `--stable` (0.x to 1.0.0) or `--pre <id>` only when the user named them. Every feat, fix, perf or breaking commit in a public package stages its `CHANGELOG.md` entry under `## [Unreleased]`; the hook refuses it otherwise, and the release refuses an empty Unreleased.
+
+1. `bun repo release` commits `chore: release <name>@<version>` (the version line and CHANGELOG.md only), pushes it, waits on CI for that commit, then tags `<name>@<version>` and pushes the tag. Its last line names the tag. A refusal prints one line that starts with repo release: and has written nothing; fix what it names and run it again.
+2. When CI failed, read the jobs it printed, fix the cause with a failing test first and a CHANGELOG.md entry, push, and run `bun repo release` again. A rerun finishes the same version and never bumps twice. A cancelled or missing CI result is the same: pull if told to, run it again.
+3. The tag push starts `release.yml` (generated by `bun repo sync`), which runs three jobs. **gate** checks that the tag equals the version in package.json at the tagged commit, that CHANGELOG.md has that version's section, that the commit is on the default branch and that its CI passed. **publish** packs, refuses a `catalog:` or `workspace:` version in the packed manifest, skips a version npm already serves and publishes through trusted publishing (no npm token), under `next` for a prerelease. **github** creates the GitHub release from the changelog section. Each job reruns safely: `gh workflow run release.yml -f tag=<name>@<version>` finishes a release that stopped halfway.
+4. After the tag, run `bun repo release wait <name>@<version>` from the main checkout. A pushed tag is not a release until it prints `published <version>`. It exits 1 after 15 minutes; report that and `gh run list --workflow release`. Do not watch runs by hand.
+5. A package that is not on npm yet cannot publish from CI: the publish job fails and prints the bootstrap steps. Tell the user to run `npm login` and `bun repo release publish <name>@<version>` at that tag on their machine, then add the trusted publisher the line names. Never do it yourself.
+
+Do not `bun publish` or `npm publish`. Do not `bun pm pack` as publish. Do not `gh release create`. CI publishes from the tag; the one exception is the first publish of a new package, which the user runs.
+
+Never tag by hand, never `git tag -f`, delete a tag or force-push one. A tag never moves; a bad release is fixed by the next version.
+
+Protocol: `node_modules/@workerstack/repo/references/cascade.md`. Do not paste cascade.

package/agents/skills/correct/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: correct
+description: >-
+  Find the mistakes agents keep repeating in this repo and make each one
+  impossible. Try architecture first, then types, then a lint whose error names
+  the fix, then a test, and write docs last. Prove each check fails on a real
+  past mistake. Repeat this each time the operator corrects you. Use for
+  /correct.
+---
+# Correct
+
+The operator keeps correcting agents in this repo for the same mistakes. Change the repo so the next agent can't make them.
+
+First read `principle-encode-lessons-in-structure` and follow it. Encode the lesson in the repo, not in another paragraph.
+
+Slash `/correct` only. Not a session flag.
+
+Assume every contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Design the repo so a change that looks right from one file is right for the whole repo.
+
+## Find the mistake classes
+
+First, read recent commits, reverts, review comments, agent instruction files, and comments that explain workarounds. Also read `.repo/lessons/INDEX.md`: every lesson with `hits` of 2 or more is a class with its evidence. Group the mistakes into classes. A class counts once it has happened twice.
+
+## Fix each class at the highest level that works
+
+1. **Eliminate it with architecture.** Give each piece of state one owner and each task one supported way. Hide internals so the wrong import fails. Replace hand-synced lists with one source of truth. Delete old ways and dead code an agent would copy.
+2. **Enforce it with types so the bad state can't be written.** If bad code still compiles, add a lint or CI check whose error names the file, type, or function to use instead. If the pattern is already common, fail only when a change adds more.
+3. **Test the behavior.** Fix or delete any test that still passes when the behavior it checks breaks, or that fails when only the internals change.
+4. **Write docs or agent rules last, only for judgment calls.** Nothing fails when an agent skips them.
+
+## Fix and prove
+
+Then fix the most frequent classes now, one worktree per class (`bun repo worktree add correct-{slug}`), each committed and finished (`/commit` runs `finish` from the root). When a fixed class came from a lesson, run `bun repo lessons rm <slug>` in that worktree, in the same commit: the check replaces the lesson. A correction you fix now but cannot encode yet goes in as a lesson (`bun repo lessons hit`, or write one) inside a worktree: the class's `correct-{slug}`, else `lesson-{slug}`. Prove each new check fails on a real past mistake. Run the same command locally and in CI. Exceptions go on the offending line with a reason, an expiry date, and a human's approval.
+
+## Keep the rule table
+
+Last, in a worktree, keep a table in `AGENTS.md` (SSOT: `agents/rules/overview.md` in this repo, a rule file under `.repo/rules/` in a consumer) that pairs each rule with what enforces it. When the operator corrects you, fix the mistake and add the rule. If the rule was already there and nothing enforces it, that's a repeat, so fix it at the highest level in the same change. Drop a rule once its mistake can't happen.
+
+**Reply:** each class with its evidence, the level you picked, and why a higher level didn't work.

package/agents/skills/do/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: do
+description: 'Do a small task now: no plan, no review. Worktree, nearest test and commit still apply.'
+---
+# do
+
+`/do <task>`. Skip the plan and its review. Never skip the worktree, the nearest test or the commit gate.
+
+1. `bun repo worktree add <name>`. Edit only there.
+2. Make the change.
+3. Run the nearest existing test. Fix until it passes.
+4. `/commit` in the worktree.
+5. From the root, `bun repo worktree finish <name>`.
+
+A change that needs a decision stops before the first edit. Reply exactly:
+
+```
+this needs a decision; write a plan with /write-plan
+```
+
+Empty task → ask for a task and stop.

package/agents/skills/explain/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: explain
+description: Longer human recap this reply only.
+---
+This reply only: explain for a human. Not a mode switch or session flag. After this reply, revert to output.md.
+
+Still concise. Complete sentences. Prioritize clarity over token compression. Do not dump, sprawl, or narrate process.
+Open with the verdict, failures included. The four buckets are the middle (completed / in-flight / remainder / blocker). Close on the same facts. Completed work = past tense. Omit empty. Natural language; no key tokens. Longer expansion this reply only — not the only grammar for complete sentences.
+
+en-US default. Keep need: JSON and plan grammar when those apply.
+
+Always-why advise recap ≠ `/explain`. `/explain` = longer expansion not the why path.
+Freeform how/why/explain is not this skill. Slash `/explain` only.

package/agents/skills/google-workspace/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: google-workspace
+description: >-
+  Google Sheets, Docs, Slides, Calendar, Gmail via bun repo google-workspace.
+---
+# google-workspace
+
+When the user wants a Google sheet, doc, slide, meeting, or mail, run `bun repo google-workspace`. Spec: `node_modules/@workerstack/repo/references/google-workspace.md`. If Calendar/Gmail/sheet set fail or login is missing, tell them to run `bun repo setup google-workspace` (TTY) for the handheld walk. Do not share creds. Do not invent OAuth JSON. Do not ask them to write Apps Script.
+
+`whoami` · `scopes` · `accounts` · `login` · `sheet create|set|get|append|clear` · `doc create|append` · `drive list` · `slide create` · `meeting create [--attendees a@b,c@d]` · `mail send|list`. `--account NAME` for a second Google user on this machine.
+
+Auth: `bun repo setup google-workspace` then `login` as needed. Two Google users on one machine: `--account NAME`. Creds stay in `~/.workerstack/` (or `~/.workerstack/workspace/NAME/`). Do not share OAuth JSON or tokens. Doctor: `bun repo doctor` reports google-workspace as optional (`oauth` `tokens` `adc` `clasprc`; no secrets). `clasprc` is Drive-only. Spec: `node_modules/@workerstack/repo/references/google-workspace.md` `node_modules/@workerstack/repo/references/setup.md`.

package/agents/skills/handoff/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: handoff
+description: Write a session handoff under .tmp/repo/handoffs/. Continue with /pickup.
+---
+# handoff
+
+One turn. Author from this session. Write once, report the absolute path, stop.
+
+## Invocation
+
+`/handoff [focus]`
+
+Focus narrows what the handoff carries. Empty → whole session.
+
+## When
+
+Context large + work unfinished → write handoff, then advise a new session. Also on host/tool churn, or before a long unrelated detour.
+
+Nothing done yet (no edits, no findings) → `nothing to hand off` and stop. Do not write an empty file.
+
+## Path
+
+`.tmp/repo/handoffs/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- serial: unpadded int ≥ 1, next after existing handoffs (own counter; not plan serials)
+- slug: lower, non `[a-z0-9]` → `-`, collapse, trim 50
+- stamp: `created` with `-` and `:` dropped (`20260827T143000Z`)
+
+## Format
+
+```yaml
+---
+serial: 1
+name: <slug>
+status: open        # open | resumed | done
+created: 2026-08-27T14:30:00Z   # UTC, seconds, no ms
+source: "<≤120 chars of the session task>"
+---
+```
+
+Headings, this order only: `# {slug}`, `## Goal`, `## State`, `## Context`, `## Next`, `## Watch-outs`.
+
+| Section | Amount |
+|---|---|
+| Goal | 1–3 sentences. What the session is trying to land. |
+| State | bullets. Past tense for landed work / changed / green-red, with absolute paths. |
+| Context | bullets. Abs paths, decisions, verdict facts the next session needs. |
+| Next | checkbox steps, `N [ ]` phase + `N.M [ ]` leaf, all `[ ]` fresh |
+| Watch-outs | bullets. Footguns. `(none)` allowed. |
+
+Boxes: `^{id} [ ] {text}$`, id `N` / `N.M` / `N.M.K`. Not `- [ ]`, not `1. [ ]`. Every phase has ≥1 leaf. Fresh handoff has zero `[x]`.
+
+Facts only. Absolute paths. No transcript paste, no dump, no secrets/tokens.
+
+## Write
+
+Line 1 of the body: `HANDOFF_NAME: <3-6 word name>`, then the body only.
+
+Write under `.tmp/repo/handoffs/` (any filename in that dir). Grok `orchestrate-parent.ts` runs `cli/scripts/persist-handoff.ts`: serial/slug from `HANDOFF_NAME:` / heading, injects frontmatter, rewrites path + content. Invalid handoff or a write outside that dir is denied — fix the body, do not retry elsewhere.
+
+Host without that hook: name the file per **Path** yourself, or pipe the body to `bun repo persist handoff --workspace {repo}` and use its `absPath`.
+
+## Report
+
+```
+[handoff]: serial={int} path={abs}/.tmp/repo/handoffs/{serial}-{slug}-{stamp}.md
+next: start a new session; `/pickup {serial}`
+```
+
+Do not dump the handoff body.
+
+## Picking one up
+
+`/pickup {serial}` owns pickup. Load the file, set `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
+
+## Rules
+
+- One write. `/handoff` is not a mode.
+- Handoff ≠ plan: no Steps/Verify phases, no `.tmp/repo/plans/` write. Handoff ≠ implementation journal.
+- Never rewrite or renumber an existing handoff; new session = new serial.
+- Protocol: `node_modules/@workerstack/repo/references/cascade.md`. Do not paste it here.

package/agents/skills/implement-plan/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: implement-plan
+description: 'Execute remaining leaves in a .tmp/repo/plans checklist. Skip [x].'
+---
+# implement-plan
+
+You execute the plan in this session. A plan with `reviews: 0` cannot start: the save denies the move to `in-progress`. Run `/review-plan {n}` in a fresh agent and settle it first. Start only on a plan the user approved, when the request said "plan and do it", or when `/implement-roadmap` is running a `locked` or `in-progress` roadmap. Skip `[x]`. Before the first open leaf, run `git log -3 --stat` and reconcile any newer commit that touches a file the plan lists, then read the plan's `## Previous mistakes` and do not repeat one. Start at the first open leaf. Flip only the box after each leaf. When a phase's children are `[x]`, mark the phase `[x]`. Frontmatter `in-progress` then `done`.
+
+strategy review-fast or review-deep: read node_modules/@workerstack/repo/references/review-loop.md first; a parallel group of phases runs at once, as it says. default: ignore this line.
+
+Arg `{n|path}` picks that file. Empty arg: unique in-progress, else unique ready, else list serials.
+
+Worktree: before the first open leaf, run `bun repo worktree add {serial}-{name}` (serial and name from the frontmatter; it prints `.worktrees/{serial}-{name}` and reuses one that exists). Every product edit, test run and commit happens there; the gate denies product writes and commits in the main checkout. The plan, the journal and `.tmp/repo/` stay in the root. A subagent starts in the root, so its prompt names the worktree path.
+
+Format: `node_modules/@workerstack/repo/references/plan-format.md`. Write-allowlist = paths listed in the plan, repo-relative to the worktree; an absolute path under the root names the same path there. Run Verify leaves. Do not skip a test leaf. Do not flip a behavior leaf `[x]` until its test ran.
+
+A leaf that names a principle skill is done by reading that skill and following it. Also follow the next paragraph, and read a principle an already-read principle cites. Do not open the rest of the catalog.
+
+When a Verify or a test fails after a fix, or `principle-attack-the-premise` fires, add a `- verify: …` or `- premise: …` entry to `## Previous mistakes` (Edit the plan; earlier entries stay). When it will happen again on other tasks, run `bun repo lessons match` on the files involved, then `hit` the matching lesson or write a new one inside the plan's worktree (`node_modules/@workerstack/repo/references/lessons.md`), so it lands with the plan's commit, and end the entry with `(lesson: {slug})`.
+
+Before Verify, read `principle-prove-it-works` and follow it. After two fixes that share a premise fail the same gate, read `principle-attack-the-premise` before a third try. Before you ask the user, read `principle-never-block-on-the-human`. Under `/away`, or frontmatter `mode: away`, do not ask: decide, add `- decision: {question} → {choice}, because {why}` to `## Previous mistakes`, and continue; stop only on a true blocker (a missing credential, a destructive action). Before a large dump or a fan-out, read `principle-guard-the-context-window`. Fat dumps go through `bun repo job`.
+
+On a failing-test leaf, run the test and see it fail for the missing behavior before the production edit. Then make it pass. Then run the nearest suite.
+
+After Verify, if frontmatter `commit:` is set, run `/commit` with that subject and the journal Files. One plan, one commit, including a failing-test leaf and the fix. If a git hook fails on a path inside the plan write-allowlist, fix that code and commit again until the hook passes. Stop when the hook cites a path outside the allowlist or a missing secret. Do not skip the hook. Do not push. A plan with no `commit:` key does not auto-commit and does not finish: leave the worktree and report its path.
+
+`/commit` in the worktree then runs `cd <root> && bun repo worktree finish {serial}-{name}` (from the root: run inside the removed worktree, the shell reports exit 1 after a successful finish, so do not rerun it), which rebases onto the default branch, fast-forwards it and removes the worktree. On a rebase conflict it aborts, keeps the worktree and names the files: resolve them there, rerun the Verify checks, run `finish` again. Mark the plan `blocked` only when you cannot land it.
+
+On start: if this plan has no journal, Write one under `.tmp/repo/implementations/` (`IMPL_NAME:`, `IMPL_PLAN: {n}`). Format: `node_modules/@workerstack/repo/references/implementation-format.md`. After each leaf: append `N.M [x] …` to Log, update Files (repo-relative product paths) and Done. Blocked → `status: blocked` and Blockers, e.g. `- finish could not land wt/{serial}-{name}: rebase conflict in src/x.ts left unresolved in {root}/.worktrees/{serial}-{name}`. Verify done → `status: done`. Straight shots do not write a journal.

package/agents/skills/implement-roadmap/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: implement-roadmap
+description: >-
+  Run a locked roadmap in order. Use for /implement-roadmap. Writes each missing
+  plan, then /implement-plan. Refuses a draft.
+---
+# implement-roadmap
+
+You run the roadmap in this session. Format: `node_modules/@workerstack/repo/references/roadmap-format.md`.
+
+Refuse `status: draft`. Say it is not locked and stop. Do not write a plan.
+
+Accept `locked` or `in-progress`. Set `in-progress` when you start. Same session. Do not spawn a subagent per slice.
+
+For each open slice, in order:
+
+1. If `Location` is absent, run `/write-plan` from that slice's line: its title and sentence on a pointer roadmap, its Title, Goal and Why on an old-shape one. Research the slice's decisions and Usage there; they go into the plan, not the roadmap. Read the roadmap's `## Previous mistakes` first and put each entry that touches this slice in the plan's Watch-outs. The lock is the approval: do not stop for plan approval. `/write-plan` picks the type and the `commit:` subject. The plan copies the roadmap's `strategy:` unless the slice's scope argues for another (heuristic in `/write-plan`). If it hits a plan-shaping question, stop and leave the roadmap `locked` or `in-progress`.
+2. Set `Location` to the absolute plan path `/write-plan` reported. Do not write a second plan when Location is already set.
+3. Run `/implement-plan` on that plan. It works in the plan's worktree `{serial}-{name}` and finishes it. Do not stop between slices.
+4. Mark the slice `[x]` only after that plan's Verify is done.
+5. Read that plan's `## Previous mistakes`. For each entry that changes the Order or a later slice (its sentence, or on an old-shape roadmap its Goal or Why, or a Decision), add `- slice: {what plan N found} → {what changed in the roadmap}` to the roadmap and make that change in the same save. Earlier entries stay.
+
+A failed program Verify adds `- verify: …` to the roadmap. Stop on a blocker, a failed Verify, or a plan-shaping question.
+
+When every slice and Verify are `[x]`, promote before `done`: the roadmap lives in `.tmp/` and is lost with it. For each roadmap entry that will happen again after this program, run `bun repo lessons match` on the files involved, then `hit` the matching lesson with `--evidence "roadmap {n}"` or write a new one (`node_modules/@workerstack/repo/references/lessons.md`). Write or hit it inside a worktree (`bun repo worktree add lesson-{slug}`), commit there, and run `cd <root> && bun repo worktree finish lesson-{slug}`. Then set `status: done`.
+
+On a pointer roadmap the slice's why goes into the child plan's Context. On an old-shape roadmap the Why stays on the roadmap. Never add a Why heading to the child plan.

package/agents/skills/jev/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: jev
+description: >-
+  Yes/no or named-option decision on text already saved. Run bun repo jev --available first. On yes, one decision call. On no, decide
+  yourself and do not mention Jev.
+---
+# jev
+
+Use this when the source text is already saved and the leftover question is a yes/no or a choice among options the research already named. Spec: `node_modules/@workerstack/repo/references/jev.md`.
+
+Run `bun repo jev --available`. It prints `yes` or `no` and exits 0.
+
+`no`: answer the question yourself. Do not run a decision call. Do not mention Jev, a missing key, or setup.
+
+`yes`: read `node_modules/@workerstack/repo/references/jev.md`. Write the passage and one questions file under `.tmp/repo/jev/`. Run `bun repo jev --state <state> --questions <questions>` once. Use the printed label and confidence. A low confidence is the result. Do not call again.
+
+Open research, code, and job stay with the session. If the decision call exits non-zero, answer from the sources. Do not invent a label.

package/agents/skills/listen/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: listen
+description: >-
+  Speech-to-text via bun repo listen (ffmpeg mic + local
+  whisper.cpp, OpenAI fallback). Input only.
+---
+# listen
+
+When the user wants to dictate, transcribe a recording, or toggle a mic, run `bun repo listen`. Spec: `node_modules/@workerstack/repo/references/listen.md`. Input only (audio → text). Do not speak. Do not use `/speak`.
+
+`whoami` · `devices` · `rec [--seconds N]` · `start` · `stop` · `toggle` · `status` · `file --path P` · `latest`. `--clip` copies the transcript. `--cwd DIR` when the process is not already in the repo (hotkeys). `rec` prints the transcript and `transcript=.tmp/repo/listen/latest.txt`.
+
+STT: local `whisper-cli` first (mac: `brew install whisper-cpp`); first listen downloads the ggml model to `~/.workerstack/whisper/`. Else `OPENAI_API_KEY`. Mic verbs need ffmpeg. Do not tell them to pip-install openai-whisper or curl the model by hand.
+
+If the CLI exits non-zero, print its message. Lines with `setup:` are for the user — show that command. Tell them to run `bun repo setup listen` (or `bun repo setup`) in their terminal. Do not dump JSON. Do not invent a key. Spec: `node_modules/@workerstack/repo/references/listen.md` `node_modules/@workerstack/repo/references/setup.md`.

package/agents/skills/pickup/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: pickup
+description: Continue a handoff under .tmp/repo/handoffs/.
+---
+# pickup
+
+Voice: `node_modules/@workerstack/repo/references/output.md`.
+
+Load a handoff and continue in this session. Not a mode. Not `/handoff`. Inverse of `/handoff`.
+
+## Invocation
+
+- `/pickup`
+- `/pickup latest` (also `newest`/`last`)
+- `/pickup {serial}`
+- `/pickup {abs|rel|drag-drop path}`
+- `/pickup {title substring}`
+
+## Resolve
+
+Read `.tmp/repo/handoffs/`. Use `bun repo job --job search|exec` when the listing is fat.
+
+Order:
+
+1. path-like → file if exists + FILENAME_RE `^[0-9]+-[a-z0-9]+(-[a-z0-9]+)*-\d{8}T\d{6}Z\.md$`
+2. integer → FM serial or filename prefix
+3. latest|newest|last → newest by FM `created`
+4. else case-insensitive substring on name/source/H1
+5. empty arg: 0→none; 1→auto; N→list+ask (**not** auto-newest)
+
+List lines: serial status name created path. Prefer open|resumed first; still include done.
+
+Matches: 0→recap missing; 1→proceed; N→list+ask never guess.
+
+Empty/missing dir: recap no handoffs; stop.
+
+Drag outside handoffs dir or non-FILENAME_RE: reject; list valid.
+
+Corrupt FM: recap; do not continue on garbage.
+
+status done + explicit serial/path: warn; still load if the user named it.
+
+## After unique path
+
+Read the file. Set `status: resumed`. Work in a worktree: the one the handoff names, else `bun repo worktree add <handoff slug>`; the gate denies product writes in the main checkout. Work Next leaves in order; flip only that box; all `[x]` → `status: done`; do not re-plan; stale → `/write-plan`. Edit in place. Never persist-handoff.ts on pickup.
+
+## Recap
+
+```
+serial={int} path={abs}
+```
+
+Do not invent a new role tag.
+
+## Rules
+
+- `/handoff` stays one-turn write. This skill owns pickup.
+- Protocol: `node_modules/@workerstack/repo/references/cascade.md`. Do not paste.

package/agents/skills/principle-attack-the-premise/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: principle-attack-the-premise
+description: >-
+  Apply when two or more fixes that share one premise have failed the same gate.
+  Write the premise down and test it directly before you write another fix that
+  assumes it. Use for /principle-attack-the-premise.
+---
+# Attack the Premise
+
+When two or more fixes that share one premise have failed the same gate, suspect the premise, not the fixes.
+
+Slash `/principle-attack-the-premise` only. Not a session flag.
+
+**Why:** Each failed fix is evidence against the belief it assumed. A third fix on the same premise spends effort where the evidence already says the cause is not.
+
+**Pattern:**
+- **Write the premise down.** The premise is the one sentence that every failed fix assumed.
+- **Test the premise before the next fix.** Find an observation that would come out differently if the premise were false, and make it. Look at how the failures are distributed, not only at how large they are. Make the check rerunnable per `/principle-build-the-lever`.
+- **Follow the evidence.** If it contradicts the premise, the cause is elsewhere. Look for what the failures have in common that the premise did not predict. If it confirms the premise, ask the next "why" per `/principle-fix-root-causes`. The earlier fixes may have treated a consequence instead of the cause.
+- **Remove the condition instead of compensating for it**, per the `/principle-laziness-protocol`. If the evidence shows that one part always lands on the losing side, change what puts it there. A mechanism that cleans up after it leaves the cause in place and adds work on every run.
+
+**Stop:** Do not start the next fix before the premise is written down and tested.
+
+This principle is distinct from `/principle-redesign-from-first-principles`, which rebuilds a design around a new requirement. It questions a fact the current design assumes.

package/agents/skills/principle-boundary-discipline/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: principle-boundary-discipline
+description: >-
+  Apply when wiring validation, error handling, or framework adapters.
+  Concentrate guards at system boundaries (CLI, config, network, external APIs);
+  trust internal types and keep business logic in pure functions. Use for
+  /principle-boundary-discipline.
+---
+# Boundary Discipline
+
+Place validation, type narrowing, and error handling at system boundaries. Trust internal code unconditionally. Business logic lives in pure functions. The shell is thin and mechanical.
+
+Slash `/principle-boundary-discipline` only. Not a session flag.
+
+**Why:** Scattered validation is noisy, redundant, and gives a false sense of safety. Keep logic out of framework wiring so it can be tested without the framework.
+
+**The pattern:**
+- **At boundaries** (CLI args, config files, external APIs, network protocols): validate, return errors, handle defensively.
+- **Inside the system:** typed data, error propagation, no re-validation. Trust the types.
+- **Across the boundary.** Expose domain concepts, not the boundary's private representation. Keep general-purpose mechanism inside and special-purpose policy at the edge.
+
+**Applications:**
+
+Validation and error handling:
+- Validate config at parse time (the boundary), not inside business logic
+- Parse raw data into domain types at the boundary
+- Do not re-export transport, storage, framework, or wire types through the public surface
+- No redundant nil checks deep in call chains if the boundary already validated
+
+Code organization:
+- Business logic in pure functions with no framework dependencies
+- Parse functions: pure transforms from raw bytes to typed state
+- Prompt construction: structured state in, string out
+- Scoring and assessment: pure transforms from state to results
+
+**The tests:**
+- "Is this data crossing a system boundary right now?" If not, validation is redundant.
+- "Can this be a pure function that the shell just calls?" If yes, extract it.

package/agents/skills/principle-build-the-lever/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: principle-build-the-lever
+description: >-
+  Apply to any non-trivial work, not just bulk work: edits, migrations,
+  analyses, checks. Build the tool that does it or proves it (codemod, script,
+  generator, or a skill later turns follow) instead of working by hand. The tool
+  is the artifact a reviewer can rerun. Use for /principle-build-the-lever.
+---
+# Build the Lever
+
+When the work isn't trivial, build the tool that does it instead of doing it by hand.
+
+Slash `/principle-build-the-lever` only. Not a session flag.
+
+A codemod, generator, or script does the work the same way every time and reruns for free. The tool is one artifact a reviewer can read and rerun to check the work. Hand-done changes can only be re-verified by redoing them. A deterministic script turns "trust me" into "run this".
+
+Default to building the lever. Skip it only when the task is trivial, a couple of obvious edits you can see at a glance.
+
+- Do the first unit by hand to learn the recipe, then build the tool. Prove it by rerunning it on that unit and diffing against your hand-done version. Make the lever safe to rerun.
+- Codemod or script for edits, generator for repetitive files, a dump-to-sqlite query for analysis, a rerunnable check for verification.
+- A deterministic lever beats fan-out. If the tool can process every unit in one pass, run it yourself. Don't fan out delegates to hand-apply what a script can do.
+- When you split work across later turns or child runs, write the lever as a skill they all read: the recipe, the verification contract, and the do-not-touch fences in one artifact. Keep it outside the delegates' write scope so they can't quietly edit the contract.
+- Applying this principle produces a file. If you cited it and there is no codemod, script, generator, or delegate skill in the diff, you didn't apply it.
+- Commit the lever when the work outlives the session.
+
+The bar is triviality, not repetition. A one-off still earns a lever when the lever is what makes the work checkable. Per the `/principle-laziness-protocol`, build the smallest script that does or proves the job, never a framework.
+
+Distinct from `/principle-encode-lessons-in-structure`, which makes a recurring instruction a durable guardrail. This is throughput and reviewability on the work in front of you. For scripting the verification itself, see `/principle-prove-it-works`.