baton

Review git worktrees in the active context and clean up the finished ones. Scoped to the active context by default; pass --context <name> or --all-contexts to widen it. Runs its scan in a background agent by default, so the calling session sees only a per-worktree question (when one needs an explicit yes) and the final report; pass --inline to run the scan in the foreground. A worktree is a confirmed candidate when its leaf bead carries the `ready-for-worktree-delete` label (applied by `baton:finish` once merged) AND the merged/clean signals agree, AND either the bead is closed or it carries `keep-task-open` (an explicit "left open on purpose" signal) — those are auto-removed with no prompt. A task that deliberately produced nothing to merge carries `no-pr-needed`, which stands in for the merge signal when git agrees nothing is outstanding. Everything else still requires explicit per-worktree confirmation.

Create or edit a baton context — a small workspace repo holding a context.yaml (task tracker, member repos, GitHub owner, work mode, startup tasks, hooks) plus a guidance.md. Registers it so its <name>-start command appears. Re-run anytime to adjust tasks, tools, hooks, or the retrospective.

Verify this machine has every tool baton needs — its baseline (git, gh, yq, jq), the tools the context's task tracker backend declares, plus tmux and any custom handoff.launcher when the context uses the worktree-new-session work mode, plus the active context's required_tools — and validate the active context.yaml against baton's config schema, catching typo'd keys that would otherwise silently fall back to defaults. Offers to install or fix anything missing. Runs at setup and, by default, on every session start so environment drift is caught over time.

Finish a task — run pre-finish hooks, verify acceptance criteria, run a documentation pass, close the leaf bead, run post-finish hooks, and (if enabled) run a retrospective whose feedback is folded back into this context's guidance/hooks. If the PR isn't merged yet, always checks its check-run status and flags failing/pending checks before offering to fix them or proceed anyway — unless the leaf is labeled `autonomous-safe`, in which case it waits for checks and merges automatically once they're green (never over red checks). Never deletes the directory it runs in; once the branch is merged it labels the leaf bead `ready-for-worktree-delete` (plus `keep-task-open` if the bead is being left open on purpose for follow-up work) so a later session's `baton:cleanup-worktrees` can clean it up explicitly. A task that deliberately produced nothing to merge — work done against a live system rather than in the repo — is labeled `no-pr-needed` instead of waiting forever for a merge that will never come.

Create a new repository for the active context — proposes a name using the context's new_repo_prefix, requires your signoff, creates it under the context's GitHub owner, and registers it as a member repo so context auto-detection picks it up.

Get oriented on how baton works — a plain-language briefing covering contexts, the task model and its pluggable tracker, the worktree handoff, and the full baton skill catalog. Reports your registered contexts and which one is active. Run this on your first session.

Open (or report) the PR for the current task — runs any context-specific hooks.worker.pre_pr hook, a documentation pass, then creates the PR via gh pr create. The customizable pre-PR extension point. Never merges here (even for autonomous-safe leaves) — that's baton:finish's job.

Save a decision, preference, or convention into the active context's guidance.md so future baton runs honor it — without editing the plugin. This is the write path the retrospective uses; call it anytime you want the workflow to remember something for this context.

Run the active context's startup_tasks, in order, every time — the routine that <name>-start and the home session invoke. Defaults are align (pull + plugin update + tracker sync), doctor (tool check), cleanup (worktree review), and status. Custom tasks run too. From a generic home session it can iterate all contexts.

One-time machine bootstrap for baton — wires the shell integration (so <name>-start commands and BEADS_DIR auto-switching work), ensures the config dir exists, checks required tools, and optionally wires your tmux launcher for the new-session handoff. Run once per machine, then baton:configure to create your first context.

Decompose a bead into child leaves mid-work — turn a task into a parent by creating children (labels inherited), optionally gate the parent on all children, and offer to start a child in its own worktree. Never re-homes the current worktree onto a different id.

Start work on a task in the active context — resolve a single leaf bead (pick a child of a parent, use a leaf directly, or create one), create its git worktree and branch, and hand off per the context's work mode (new tmux session by default). One worktree ⇔ one leaf bead.

(Worker session) Report where THIS worktree's task stands — the bead and its acceptance criteria, blockers, PR and check state, and exactly one overall state from a fixed vocabulary (unstarted, blocked, in progress, waiting on CI, waiting on the human, merged but not finished, done and awaiting worktree delete, done with follow-ups elsewhere). Strictly read-only — it fires no hooks, claims nothing, closes nothing, and starts no work — so it is safe to run purely to look around. No-ops cleanly outside a baton worktree.

Quick-capture a task into the active context's tracker. Optionally make it a child of a parent (to pre-decompose a ticket into per-worktree subtasks), add labels, or mark it autonomous-safe. Thin wrapper over the tracker seam, context-resolved so it hits the right backend and database.

List tasks in the active context's tracker — ready work, in-progress, or a full tree — with optional filtering. Thin wrapper over the tracker seam, context-resolved so it reads the right backend and database.

Report which baton context is active for the current directory, and the paths it resolves to (tracker, code root, worktree base). A quick debugging aid for context auto-detection.