Add cargo xtask create-worktree

.cargo/config.toml

@@ -5,3 +5,4 @@
 # See crates/xtask/src/main.rs for available commands
 xtask = "run --package xtask --"
 dev-setup = "xtask dev-setup"
+create-worktree = "xtask create-worktree"

.claude/rules/worktrees.md

@@ -13,15 +13,22 @@ The directory mirrors the leaf of the branch name. The conventions are stable so
 
 ## Fresh worktree bootstrap
 
-A fresh worktree has no `node_modules/`. `cargo xtask verify` runs the hub-client TypeScript build, which fails on missing npm deps. Bootstrap with `npm install` from the worktree root before re-running verify:
+Use `cargo xtask create-worktree <bd-id>` (or `--issue N` / `--upgrade`) for new worktrees —
+it handles `git worktree add`, `.beads/redirect`, and the CLAUDE.local.md context stub in
+one shot. After it finishes, run `npm install` from the new worktree if hub-client is in scope:
 
 ```bash
-cd .worktrees/<name>
-npm install
-cargo xtask verify --skip-hub-build  # or full verify if hub-client is in scope
+cargo xtask create-worktree bd-XXXX
+cd .worktrees/<id>-<slug>
+npm install                              # only if hub-client work is in scope
+cargo xtask verify --skip-hub-build      # confirm green at branch HEAD
 ```
 
-`cargo xtask dev-setup` exists for Rust dev tools (cargo-nextest, wasm-bindgen-cli) but does not currently run `npm install`. bd-7giz tracks extending it; once that lands, the bootstrap step above becomes a single `cargo xtask dev-setup`.
+If the xtask is not yet built (fresh clone, or a branch where `cargo build -p xtask` has
+not run), see § Manual bootstrap below.
+
+`cargo xtask dev-setup` exists for Rust dev tools (cargo-nextest, wasm-bindgen-cli) but
+does not currently run `npm install`. bd-7giz tracks extending it.
 
 ## Beads Redirect
 
@@ -35,6 +42,30 @@ echo "../../../.beads" > .worktrees/<name>/.beads/redirect
 
 The `redirect` file is already in `.beads/.gitignore`, so it won't show as a git change. Verify with `br where` from inside the worktree.
 
+## CLAUDE.local.md
+
+`cargo xtask create-worktree` prepends a worktree context section to `CLAUDE.local.md`.
+Claude Code loads it automatically — no need to run `br show` to orient at session start.
+
+The section contains: worktree declaration, main repo path (`../..`), beads ID
+(or `**GitHub issue:** #N` in `--issue` mode), GitHub URL when available, an
+italic-prose placeholder for the plan file path, and a `**Skill:**` line
+naming the slash-command that continues the work (`/investigate-beads`,
+`/triage`, or `/upgrade-cargo-deps`). Placeholders are self-documenting —
+they say exactly what to replace them with.
+
+Status lives in beads, not in this file. Run `br show <id>` for current status + notes.
+
+The section is delimited by `<!-- BEGIN/END WORKTREE CONTEXT -->` markers so it can be
+refreshed in place (e.g. when a worktree is recreated, or by hand-editing the file).
+The `update_claude_local_md` rewrite is idempotent at the file level: re-running it on
+a file that already has a managed section replaces that section without duplicating it
+and preserves any user content below.
+
+`cargo xtask create-worktree` itself is **not** idempotent end-to-end — `git worktree add`
+fails fast if the directory already exists. To refresh a worktree's CLAUDE.local.md,
+either edit it by hand (the markers make this safe) or remove the worktree and recreate.
+
 ## Committing beads changes
 
 With a redirect active, all beads data lives physically in the main repo's `.beads/`. JSONL changes from worktree work are only visible in `git status` from the main repo. All beads git commits must happen from the main repo, not from a worktree branch.
@@ -52,3 +83,19 @@ git push -u origin beads/<id>-<slug>:feature/<id>-<slug>
 ```
 
 This keeps local branches short and consistent while remote refs are self-describing in PR lists.
+
+## Manual bootstrap
+
+If `cargo xtask create-worktree` is unavailable (fresh clone before first build, or
+the xtask binary is broken on the current branch), fall back to manual setup:
+
+```bash
+git worktree add -b beads/<id>-<slug> .worktrees/<id>-<slug> main
+echo "../../../.beads" > .worktrees/<id>-<slug>/.beads/redirect
+```
+
+Verify with `br where` from inside the worktree. CLAUDE.local.md is not part
+of the manual bootstrap — once the xtask binary is built, re-running
+`cargo xtask create-worktree` is not safe on the existing worktree (see
+above), but the template lives in `crates/xtask/src/create_worktree.rs`
+(`build_section`) for hand-copying if needed.

.claude/rules/xtask.md

@@ -21,6 +21,7 @@ paths:
 |---------|-------|---------|
 | `cargo xtask dev-setup` | `cargo dev-setup` | Install required dev tools (cargo-nextest, wasm-bindgen-cli) |
 | `cargo xtask lint` | — | Run custom lint checks |
+| `cargo xtask create-worktree` | `cargo create-worktree` | Create git worktree + `.beads/redirect` + CLAUDE.local.md context stub |
 | `cargo xtask verify` | — | Full project verification (build + tests for Rust and hub-client) |
 
 ## Dev tool version pinning

.claude/skills/investigate-beads/SKILL.md

@@ -70,15 +70,22 @@ If the description references a plan file (`claude-notes/plans/...`), read it. I
 
 Spot-check the area: does the code the issue points at still exist with the same shape? Beads issues age — a six-month-old issue may have been overtaken by a refactor.
 
-### 5. Create the worktree
+### 5. Create the worktree (skip if already inside it)
 
-Branch + directory naming follows `.claude/rules/worktrees.md` § Branch naming (`beads/<id>-<slug>` where `<slug>` is a short kebab-case form of the issue title, 3–5 words). Beads redirect setup follows § Beads Redirect.
+**First, check if you're already in the right worktree.** A `CLAUDE.local.md` whose `**Beads:**` line matches `<id>` means the worktree exists and you're in it — skip to step 6. This skill is often re-invoked from inside an existing worktree to reload context; re-running `cargo xtask create-worktree` from there would fail noisily (`git worktree add` errors on existing directories).
+
+If you're in the main checkout or a different worktree, create it now:
 
 ```bash
-git worktree add -b beads/<id>-<slug> .worktrees/<id>-<slug> main
-echo "../../../.beads" > .worktrees/<id>-<slug>/.beads/redirect
+cargo xtask create-worktree <id>
+# Creates the worktree, .beads/redirect, and CLAUDE.local.md context stub.
+# Slug is auto-derived from the beads title; pass `--slug X` to override.
+# Fallback for fresh clones where the xtask is not yet built:
+# see .claude/rules/worktrees.md § Manual bootstrap.
 ```
 
+Branch + directory naming follows `.claude/rules/worktrees.md` § Branch naming (`beads/<id>-<slug>` where `<slug>` is a short kebab-case form of the issue title, 3–5 words). Beads redirect setup follows § Beads Redirect.
+
 Verify with `br where` from inside the worktree.
 
 ### 6. Bootstrap the worktree

.claude/skills/triage/SKILL.md

@@ -44,15 +44,28 @@ gh issue view <N> --repo quarto-dev/q2 --json title,body,author,createdAt,labels
 
 Read the body and every comment. If the issue contains multiple distinct reports (a list of unrelated bugs in one issue is common), confirm with the user which one(s) you're triaging. Capture that scope decision in the triage doc.
 
-### 3. Create the worktree
+### 3. Create the worktree (skip if already inside it)
 
-Branch + directory naming follows `.claude/rules/worktrees.md` § Branch naming (`issue-<N>` for triage). Beads redirect setup follows § Beads Redirect.
+**First, check if you're already in the right worktree.** A `CLAUDE.local.md` whose `**GitHub issue:**` line matches `#<N>` means the worktree exists and you're in it — skip to step 4. Re-running `cargo xtask create-worktree --issue <N>` from there would fail (`git worktree add` errors on existing directories).
+
+If you're in the main checkout or a different worktree, create it now:
 
 ```bash
-git worktree add -b issue-<N> .worktrees/issue-<N> main
-echo "../../../.beads" > .worktrees/issue-<N>/.beads/redirect
+cargo xtask create-worktree --issue <N>
+# Creates the worktree, .beads/redirect, and CLAUDE.local.md context stub.
+# This step runs BEFORE the beads issue is created (step 6). The `--issue`
+# template's `**Beads:**` line is a self-documenting placeholder pointing
+# at `br search <N>` / `br create`. After step 6 creates the bd-XXXX,
+# edit that line in CLAUDE.local.md manually to point at the new ID.
+# Do NOT re-run the xtask with `<bd-id>` to "refresh" — that creates a
+# separate beads worktree at `.worktrees/<bd-id>-<slug>` rather than
+# updating this one.
+# Fallback for fresh clones where the xtask is not yet built:
+# see .claude/rules/worktrees.md § Manual bootstrap.
 ```
 
+Branch + directory naming follows `.claude/rules/worktrees.md` § Branch naming (`issue-<N>` for triage). Beads redirect setup follows § Beads Redirect.
+
 Verify with `br where` from inside the worktree.
 
 ### 4. Bootstrap the worktree

.claude/skills/upgrade-cargo-deps/SKILL.md

@@ -113,17 +113,17 @@ Don't propose changes for these — they're either upstream vendored, workspace-
 
 If a major-upgrade candidate's only consumer is one of the vendored/pinned crates, list it under "Skipped" with the reason; don't file a beads issue.
 
-### 5. Create the worktree
+### 5. Create the worktree (skip if already inside it)
 
-```bash
-DATE=$(date +%Y-%m-%d)
-git worktree add -b cargo-upgrade-$DATE .worktrees/cargo-upgrade-$DATE main
-```
+**First, check if you're already in the right worktree.** A `CLAUDE.local.md` whose `**Task:**` line says `Cargo dependency upgrade — YYYY-MM-DD` for today's date means the worktree exists and you're in it — skip to step 6. Re-running `cargo xtask create-worktree --upgrade` from there would fail (`git worktree add` errors on existing directories).
 
-Add the beads redirect (the `.beads/` directory already exists from git — do not delete or overwrite it):
+If you're in the main checkout or a different worktree, create it now:
 
 ```bash
-echo "../../../.beads" > .worktrees/cargo-upgrade-$DATE/.beads/redirect
+cargo xtask create-worktree --upgrade
+# Creates a cargo-upgrade-YYYY-MM-DD worktree with .beads/redirect and CLAUDE.local.md.
+# Fallback for fresh clones where the xtask is not yet built:
+# see .claude/rules/worktrees.md § Manual bootstrap.
 ```
 
 Verify with `br where` from inside the worktree.

.gitignore

@@ -33,4 +33,7 @@ crates/wasm-quarto-hub-client/pkg/
 
 /.luarc.json
 
-.claude/scheduled_tasks.lock
+.claude/scheduled_tasks.lock
+
+# Per-session local context (managed by `cargo xtask create-worktree` for worktrees)
+CLAUDE.local.md