Wt

---
name: wt
description: "Use when 使用者要開 worktree（隔離環境跑 task 不影響主 working tree），或並行做多條 task（/wt A: ... B: ...）。NOT for 發布散播（走 clade-publish）、提交已完成工作（走 commit），NOT for 只是要切 branch。"
license: MIT
metadata:
  author: clade
  version: "4.0"
  clade:
    permission_tier: action
---


# /wt — orchestrate worktree task lifecycle

`/wt` builds an isolated implementation worktree and routes execution per Step 1.8. The worker validates behavior and saves scoped checkpoints. The coordinator verifies the result, registers readiness and evaluates the shared batch queue. Read commit skill `batch.md` before readiness registration or landing. The batch runs one full `/commit` in an isolated integration worktree, lands the reviewed result, then safely removes its sources.

Ready sources remain recoverable while a batch waits or fails review. Main receives formally reviewed commits; worker checkpoint creation is not formal review.

The user's only follow-up action is the actual 人工檢查 decision（GUI 的 OK / Issue / Skip）。After that decision, the coordinator marks the work done and invokes `/commit` itself. If either workflow step requires a separate clean session, use [[session-tasks.operations]] § Herdr session transport and return the dispatch receipt; **NEVER** ask the user to open main or type either invocation.

## When to invoke

Whenever a coding task (write, edit, refactor, migration prep) or investigation task (analysis, debugging, auditing) is about to start from the main worktree. `/wt` makes per-task worktree isolation cheap; the previous "type a slug, copy a oneliner, open a new session" choreography is gone.

Step 1.8 selects the executor from the shared routing table and uses that model’s supported transport. Nuxt UI／Content, Nuxt core and other UI views have separate implementation rows.

**Do not invoke `/wt`** in these cases:

- The work is read-only AND trivial (quick grep, log inspection, code explanation that writes nothing and doesn't need structured evidence collection).
- The operation is main-bound by design (clade publish / propagate).
- The work item already owns an existing implementation checkout; resolve that source instead of creating a second implementation tree.
- cwd is already inside a session worktree (`git rev-parse --git-dir` contains `/worktrees/`). The current worktree is the workspace; do not nest.

## Invocation forms

### Form 1 — single ad-hoc task

```
/wt <task description>
```

Examples:

```
/wt refactor the cache layer to use LRU eviction
/wt add unit tests for src/parsers/csv.ts covering empty / unicode / quoted rows
/wt update Node version pin to 24 and rerun pnpm install
```

The skill derives a short slug from the task description (lowercased, kebab-case, trimmed to roughly 40 chars). If the user prefers an explicit slug, they MAY prefix the description with `<slug>:` — e.g., `/wt lru-cache: refactor the cache layer to use LRU eviction`.

### Form 2 — parallel multi-task

```
/wt
A: <task A description>
B: <task B description>
C: <task C description>
```

Or single line: `/wt A: task A B: task B`.

Each labeled task becomes its own worktree + executor, subject to routing. Workers run concurrently and checkpoint inside their worktrees. The coordinator harvests completed tasks into the batch queue; a failure in one task does not block other eligible members.

Labels are arbitrary identifiers (A/B/C/feat-x/test-y). The skill normalizes them into slugs.

### Form 3 — dispatch a named next-skill (internal, used by `/handoff` Mode B)

```
/wt <slug>: /<next-skill> <args>
```

Example:

```
/wt fix-auth: /implement 繼續 tasks/2026-09-07-fix-auth.md 的下一個未勾 phase
/wt evlog-dpattern: /implement 繼續 specs/plans/012-evlog-dpattern/tasks.md
```

This form is invoked by `/handoff` Mode B (per [[worktree-default]] §1 and [[handoff]] §2B.5) when the user has selected a worktree-requiring change from the outstanding-work list. The subagent inside the worktree runs `<next-skill>` as its first action.

Direct user invocation of this form is allowed but uncommon — usually the user just types `/wt <task>` and lets the subagent figure out the work.

### Form 4 — Resume interrupted worktree

```
/wt resume <slug>
```

Dispatches a new subagent into an existing worktree whose previous session was interrupted. The subagent reads `WORKTREE-BRIEF.md` at the worktree root for full task context (description, thin brief, progress checklist) and continues from the next unchecked Progress item.

If no worktree exists at the expected path for `<slug>`, error with guidance: "No worktree found for slug `<slug>`. Use `/wt <task>` to create a new one."

To discover available worktrees for resume, run `node scripts/wt-helper.ts list` — the output shows task summary and status for worktrees that have a brief.

## Per-task lifecycle

For each task in the invocation, `/wt` SHALL execute the following sequence. With parallel tasks, steps 2–4 run concurrently across tasks; step 1 runs sequentially (one `wt-helper add` at a time). Harvest checkpoints into the ready pool; batch review, landing and cleanup follow commit skill `batch.md`.

### Step 0 — Resume detection

Before creating a new worktree, check if one already exists at the expected path:

1. Derive the slug from the task description (or from the explicit `resume <slug>` form).
2. Compute the expected worktree path: `<consumer-parent>/<consumer-name>-wt/<slug>/`.
3. If the path exists AND contains `WORKTREE-BRIEF.md`:
   - Read the brief file.
   - Run `git -C <worktree-path> log main..HEAD --oneline` to see completed commits.
   - Run `git -C <worktree-path> status --short` to see uncommitted work.
   - **Skip Step 1 entirely** — do NOT call `wt-helper add`.
   - Proceed to Step 1.5 (update the brief's `last_updated` timestamp) and Step 2 (dispatch a resume subagent with the brief content + git status as context).
4. If the path exists but has no brief, the worktree was created before this feature. Fall through to the existing "already exists" error from `wt-helper add`.
5. If the path does not exist and the invocation is Form 4 (`/wt resume <slug>`), error: "No worktree found for slug `<slug>`."
6. If the path does not exist, proceed to Step 1 normally.

### Step 1 — Build the worktree (with pre-fork baseline guard)

**MUST Read [baseline-guard.md](baseline-guard.md) before running `wt-helper add`** — 含 unmerged / clean / dirty 三路策略分流、`--baseline-scope-paths` 的對齊要求、stash strategy 的隱性風險與 `rescue` 救援、`--include-unrelated-dirty` 的 bulk-capture 語意與還原三步驟。四條契約（預設不 capture / 帶 WIP 要顯式 flag / 傳了 flag 不准宣稱 main 沒被動到 / 不准手寫 pathspec stash）在 [[worktree-default]] §1。

`/wt` 預設從 committed baseline 開乾淨 worktree，main dirty 留在原處。確實需要既有 WIP 時，先依 baseline-guard.md 判定授權範圍，再顯式選擇 scoped capture；不把別 session WIP 當新任務 baseline。

```bash
node scripts/wt-helper.ts add <slug> \
  --task-summary "<一句話：這棵樹要做什麼>" \
  --precheck-baseline \
  --baseline-strategy stash
```

Run from the main worktree's cwd. The helper:

- Detects main dirty paths（modified / untracked / unmerged）via `git status --porcelain`：
  - **Unmerged 非空** → STOP，refuse to fork. User must resolve conflicts first.
  - **Clean** → fork directly（no stash needed）.
  - **Dirty 非空** → default leaves that WIP on main; capture requires explicit flags under baseline-guard.md.
- Normalizes the slug.
- Creates branch `session/<YYYY-MM-DD-HHMM>-<slug>` from `main`.
- Materializes the worktree at `<consumer-parent>/<consumer-name>-wt/<slug>/`.
- Merges `origin/main` if present.

Capture the worktree absolute path (the helper prints `cd <path>` and `Branch: <branch>` — parse them, or derive them from the consumer-root + slug convention).

### Step 1.5 — Write WORKTREE-BRIEF.md

After the worktree is created (Step 1) and before dispatching the subagent (Step 2), write `WORKTREE-BRIEF.md` at the worktree root using the Write tool. This persists the full task context so interrupted sessions can seamlessly resume.

The file is already excluded from git tracking via `wt-helper`'s per-worktree `$GIT_DIR/info/exclude` setup.

Template:

```markdown
---
slug: <slug>
branch: <session-branch-name>
consumer: <consumer-name>
created: <current ISO date>
base_sha: <output of git -C <worktree-path> rev-parse HEAD>
status: in-progress
last_updated: <current ISO date>
---

# Task

<original task description verbatim from the /wt invocation>

# Context

<thin brief prepared by the parent session: file paths to touch, rules to
follow, acceptance criteria. This is the same context that goes into the
subagent prompt — duplicated here for persistence across session boundaries.>

# Progress

- [ ] <planned step 1>
- [ ] <planned step 2>
...

# Recovery

If you are a new session resuming this worktree:
1. Run `git log main..HEAD --oneline` to see completed commits
2. Run `git status` to see uncommitted work
3. Continue from the next unchecked Progress item above
4. Follow the subagent contract: selective `git add -- <files>`, no `git add -A`, no `git push`
```

**Progress section**: Decompose the task into concrete steps if possible. If the task is too vague to decompose upfront, write a single item `- [ ] Complete task` — the subagent will refine the checklist as it works.

**For resume (Step 0 detected existing worktree)**: Do NOT overwrite the existing brief. Instead, update only the `last_updated` frontmatter field via Edit tool.

### Step 1.8 — Executor routing

Classify the work using the shared routing table, then select its supported transport. Explicit invocation flags select a carrier within that row’s model and capability requirements.

**Invocation override flags** (parsed from args before slug/task extraction):

- `/wt --claude <task>` → force Claude subagent (Step 2)
- `/wt --pi <task>` (or the older `--codex`) → force Pi (Step 2-pi)
- No flag → auto-classify below

**Auto-classification** (check in order, first match wins):

1. **UI or Nuxt implementation** → select the matching shared table row by the work being implemented:
   - Nuxt UI component assembly／Nuxt Content → `ui-implementation`: native Cursor Composer 2.5 from the current catalog.
   - Nuxt framework, modules and runtime logic → `nuxt-core-implementation`: GPT-5.6 Sol xhigh via the GPT transport for the current runtime.
   - Other UI views → `ui-view-implementation`: Claude Opus 5（effort: medium） via native Claude Code／Herdr.
   - A main line that meets the selected row’s model and tool requirements implements directly. Otherwise use the bounded phase transport in [[agent-routing]]; preserve the worktree and work identity.
   - Design review, UI planning and screenshot work use their own named rows. File extensions and UI keywords help locate the work but do not select its model.

2. **Analysis/debug work** → **Pi via pi-dispatch.ts** (Step 2-pi-investigate)
   - Task description contains investigation keywords: `analyze`, `analysis`, `debug`, `investigate`, `audit`, `scan`, `trace`, `why`, `root cause`, `分析`, `除錯`, `調查`, `掃描`, `追蹤`, `為什麼`
   - Rationale: analysis/debug tasks benefit from Pi's structured evidence collection (pi-offload templates). These tasks typically don't need worktree commits — they produce JSON reports.

3. **Non-UI coding work** → **Pi via the Pi dispatcher** (Step 2-pi)
   - Everything else: refactoring, adding tests, implementing features, fixing bugs, migrations, config changes, etc.
   - Rationale: non-UI coding is the sweet spot for Pi — cheaper, doesn't consume Claude context, follows the same pi-watch-protocol already proven in `/commit` and `/implement`.

**Form-specific overrides**:
- Form 3 (`/wt <slug>: /<next-skill>`): use a carrier that can invoke the next skill; each implementation phase still follows its named routing row.
- Form 4 (`/wt resume <slug>`): read WORKTREE-BRIEF.md and route the remaining work by its current role.
- Form 2 (parallel multi-task): each task independently classified; mixed executors in the same invocation is fine

After classification, report the routing decision to the user before dispatching:

```
Routing: <task> → <table-row> / <model> / <effort> / <transport> (<reason>)
```

### Step 2 — Dispatch a Claude subagent into the worktree

**MUST Read [dispatch-claude.md](dispatch-claude.md) before dispatching** — 含 Agent tool 參數、subagent prompt template（fresh + resume + form 3 variants）、baseline notice、contract。

摘要：`Agent(name: "wt-<slug>", prompt: <template>)` 派 subagent 進 worktree，cwd 透過 prompt 指定。Parent cwd 不動。Thin brief MUST 由 parent 預消化。

**Same message as the dispatch**: 記下 Agent name/id 與 deadline（deadline 取值依 [[agent-routing]] § deadline 怎麼取），排 [[agent-routing]] § Async keepalive prompt 的 canonical `ASYNC_KEEPALIVE_CONTROL task=none owner=<owner> deadline=<ISO>...`。這條路徑沒有可查 harness task id，**NEVER** 放原 `/wt` input、偽造 task id 或用 `TaskOutput` 推斷狀態。deadline 到達走 `TaskStop(owner)` intervention，terminal notification 前保留 ownership。

### Step 2-pi — Pi dispatch into worktree (non-UI coding)

**MUST Read [dispatch-pi.md](dispatch-pi.md) § Step 2-pi before dispatching** — 含 brief template（Task/Context/Plan-first/Git Baseline/Scope guard/View-layer guard/Commit Authorization）、`Pi dispatcher` 指令、effort 分級表、Watch Protocol。

摘要：寫 brief 到 `/tmp/wt-pi-<slug>-prompt.md` → `Pi dispatcher` background dispatch → Watch Protocol（1500s safety net）。

### Step 2-pi-investigate — Pi analysis/debug into worktree

**MUST Read [dispatch-pi.md](dispatch-pi.md) § Step 2-pi-investigate before dispatching** — 含 investigation 分類（debug/analysis）、`pi-dispatch.ts` 參數、template 選擇、JSON evidence 解析。

摘要：`pi-dispatch.ts --template <template>` 走 pi-offload，產出 structured JSON evidence → 寫入 WORKTREE-BRIEF.md `# Findings`。

### Step 3 — Wait for completion

**All paths — keepalive first**: worktree tasks routinely run past an hour (2026-08-08: 1h43m). Before ending the dispatch turn，follow [[agent-routing]] § 主線靜默上限：Claude subagent 用 `ASYNC_KEEPALIVE_CONTROL task=none owner=<agent-name-or-id> deadline=<ISO>`；pi background Bash 用既有 1500s `ASYNC_KEEPALIVE_CONTROL task=<task-id> owner=<owner> deadline=<ISO>`，不另加第二條。兩者都只承載控制面，**NEVER** 重播原任務；完成時停止。

**Claude subagent path** (Step 2): The Agent tool call returns when the subagent finishes — that describes how the result arrives, **not** what the mainline does meanwhile. Parse its report to determine success vs. failure.

**Pi coding path** (Step 2-pi): Wait for `<task-notification>`. On completion, read stdout and verify:

1. **Phase boundary**: `git -C <worktree-path> log --oneline main..HEAD` — should have commits with `🧹 chore: wt <slug>` format
2. **View-layer drift double-check**:
   ```bash
   git -C <worktree-path> diff main..HEAD --name-only \
     -- '*.vue' '*.tsx' '*.jsx' '*.css' '*.scss' \
        'app/pages/**' 'app/components/**' 'app/layouts/**' \
        'pages/**' 'components/**' 'layouts/**' 'views/**'
   ```
   Any hit → AskUserQuestion: [1] reset + redispatch / [2] accept + mainline fixes view parts / [3] abort
3. **Scope discipline**: `git -C <worktree-path> diff main..HEAD --name-only` vs. brief's scope declaration

**Pi investigation path** (Step 2-pi-investigate): Wait for `<task-notification>`. On completion, parse dispatcher's stdout JSON. Exit code 0 → read `result` field for structured evidence. Write findings into WORKTREE-BRIEF.md `# Findings` section.

For all paths, verify commits exist (if applicable):

```bash
git -C <worktree-path> log --oneline main..HEAD
```

### Step 4 — Report (no squash, no cleanup)

After all tasks in the invocation have either completed (subagent committed) or failed (worktree preserved with whatever WIP exists), emit one aggregated report:

```
✅ A (lru-cache) [pi]: committed — 5 files, 2 commits on branch session/<date>-lru-cache
   <one-line summary from pi stdout>
   pending: archive in source, then register batch readiness
✅ B (csv-tests) [claude]: subagent committed — 2 files added on branch session/<date>-csv-tests
✅ C (perf-audit) [pi:analyze]: JSON result — 8 findings, status: pass
   findings written to WORKTREE-BRIEF.md # Findings
❌ D (node-upgrade) [pi]: pi fail — pnpm install exited 1
   worktree preserved at ~/offline/<consumer>-wt/node-upgrade/
   branch: session/<date>-node-upgrade

Ready / blocked worktrees: <counts from batch status>; report each retained path and reason
```

The `[pi]` / `[claude]` / `[pi:analyze]` / `[pi:debug]` tag indicates which executor was used. This helps the user understand the execution path and cost profile.

**Batch handover**: after harvesting verified checkpoints, register readiness and run `wt-helper batch status --trigger auto`. At 4 distinct work ids, invoke one full `/commit` for the batch. User `/commit` or merge back has no minimum; dependency/drained/stop can flush early. Archive runs its gates and bookkeeping in the source tree before readiness. Cleanup belongs to the final commit workflow after verified landing.

Form 1 work uses the same queue; the coordinator handles authorized landing without asking the user to type commands.

## Failure handling

### Claude subagent task failure

Subagent reports failure or exits without commits. Preserve the worktree and branch; report the path. The user can inspect via `git -C <wt-path> log/diff/status` from the main session — no need to switch cwd.

When the user fixes the underlying issue, they can either:

- Re-run the subagent in the same worktree by passing the worktree path explicitly to a new Agent invocation, or
- `wt-helper cleanup <slug> --force --force-discard-unland` to discard the worktree and start fresh via `/wt`.

### Pi task failure

Pi exits with non-zero or `<task-notification status=failed>`. Preserve the worktree and branch; report the error tail from stdout/stderr.

Recovery options:

- **Retry with adjusted brief**: fix the issue in the brief (scope, paths, instructions), write a new prompt file, re-dispatch the `Pi dispatcher` into the same worktree (it already exists, no need for `wt-helper add`).
- **Switch to Claude**: re-dispatch as Claude subagent via `/wt --claude resume <slug>` (Claude picks up from WORKTREE-BRIEF.md).
- **Discard**: `wt-helper cleanup <slug> --force --force-discard-unland`.

For Pi investigation failures (Step 2-pi-investigate), exit code 2 (business fail) means the investigation ran but didn't meet acceptance criteria — read `result` JSON for details. Exit code 3 (mechanical failure) means Pi itself broke — check `/tmp/pi-<label>-stderr.log`. Exit code 4 (quota) means rate limited — wait or switch to Claude.

### Squash conflicts (no longer at `/wt` time)

Batch integration conflicts are resolved in the isolated integration worktree, then `wt-helper batch resume` continues. Sources remain intact; see commit skill `batch.md`.

## After `/wt` completes

Worktree(s) hold committed work on their session branches. Main's working tree is untouched.

The coordinator's next actions:

1. Complete the work item's acceptance gates and carrier bookkeeping in the source worktree, then checkpoint the result.
2. Verify scope, evidence and writer handover; register all authorized ready sources via `wt-helper batch ready`.
3. Evaluate the batch trigger and invoke `/commit` when due; preserve the queue across session handover.

`/wt` does NOT:

- Squash to main.
- Cleanup worktrees.
- Commit on main.
- Push anywhere.

These are owned by the batch commit coordinator after review and verified landing.

## Edge cases

### Degenerate form: `/wt <single-token>` with no description and no `:`

If the user types just `/wt fix-auth` (no description, no `:`-prefixed next-skill), prompt the user to clarify whether they want:

- An ad-hoc task in a new worktree (ask for the task description).
- A long-lived worktree session (deprecated via `/wt`; suggest `node scripts/wt-helper.ts add fix-auth --task-summary "<一句話>"` + opening a fresh session in the resulting path).

Do NOT silently build a worktree with no task — that's the deprecated v1 behavior and is gone.

### cwd already inside a session worktree

If `git rev-parse --git-dir` shows `/worktrees/`, refuse to invoke `/wt`. The current worktree IS the workspace. Tell the user: "Already inside worktree <name>; do the work here. Use `/wt` only from the main worktree."

### Subagent commits but you can't tell if the task fully succeeded

A completion report is a claim to verify. Inspect the checkpoint scope and acceptance evidence, confirm terminal outcome and writer release, then register readiness. Missing evidence or ambiguous ownership retains the source outside the ready pool.

## Related rules

- [[worktree-default]] — full rule baseline (§1 invariant, §5 mechanic, §6 tools).
- [[agent-routing.pi-watch-protocol]] — Pi dispatch standard, Watch Protocol, Plan-first / Git baseline / Commit Authorization hard rules.
- [[handoff]] — Mode B dispatch path that invokes `/wt <slug>: /<next-skill>`.
- [[session-tasks]] — shared `<YYYY-MM-DD-HHMM>-<slug>` naming convention.
- [[scope-discipline]] — when a `/wt` task drifts beyond its slug's scope, open a separate `/wt` task or return to `/specify` for an authorized scope revision.
- [[pi-offload]] — template registry for analysis/debug dispatch (`~/offline/clade/vendor/snippets/pi-offload/`).

## Maintenance commands

```bash
node scripts/wt-helper.ts list                              # list session worktrees
node scripts/wt-helper.ts merge-back <slug>                 # legacy compatibility; preserves source for review
node scripts/wt-helper.ts merge-back <slug> --dry-run       # preview blockers
node scripts/wt-helper.ts merge-back <slug> --auto-stash    # stash main blockers
node scripts/wt-helper.ts land-pending <slug>               # alias for grandfathered worktrees
node scripts/wt-helper.ts prune                             # remove merged ones interactively
node scripts/wt-helper.ts cleanup <slug> --force --force-discard-unland  # discard worktree + commits
node scripts/stash-reconcile.ts                             # plan recovery for wt-merge-block/* stashes
```

Use `node scripts/wt-helper.ts batch status --trigger manual` and commit skill `batch.md` for requested merge back. The coordinator runs the full batch commit and cleanup; archive prepares its source first.

`cleanup --force --force-discard-unland` is for discarding unwanted worktrees (subagent fail, abandoned exploration). It permanently loses the branch's commits; use `merge-back` first to preserve the work.

# Runtime adapter: Claude
Use Claude's qualified main line for UI implementation and visual judgement. Bind host question, Agent, completion notification, TaskStop and keepalive operations to the native Claude tools; these bindings do not authorize changing the shared worktree gates.

Claude bindings: dispatch uses the named `Agent` operation; completion arrives through native notification. Use `TaskStop` only after the deadline intervention and wait for terminal notification. Use `ScheduleWakeup` only for the inert control prompt, and stop it on terminal evidence. User choices use `AskUserQuestion`.