wt

name	wt
description	Orchestrate a task inside a fresh git worktree end-to-end. /wt TASK builds a worktree, auto-routes the executor (Claude subagent for UI work, Codex for non-UI coding/analysis/debug), and reports back. Override with --claude or --codex. Supports parallel multi-task via /wt A: ... B: .... Use when 使用者說「worktree」「開 wt」「並行做」，或需要在隔離環境跑 task 不影響主 working tree。
license	MIT
metadata	{"author":"clade","version":"4.0"}

/wt — orchestrate worktree task lifecycle

/wt is the single entry point for "do work in a worktree". It builds the worktree, auto-routes the executor (Claude subagent for UI work, Codex for non-UI coding/analysis/debug — see Step 1.8), and reports — without squashing or cleaning up. The worktree branch holds the committed work until the corresponding spectra change is archived; /spectra-archive Step 0 (per [[worktree-default]] §5.5) runs wt-helper merge-back to atomically absorb the worktree into main, then /commit lands the result.

This deferred-landing model guarantees main never carries half-done features between sessions: only fully-reviewed-and-archived changes touch main. The previous v2.0 behavior — /wt return time squash + cleanup — accumulated cross-session WIP in main and made /commit impossible whenever the 人工檢查 Gate triggered.

The user's two follow-up actions are:

1. Complete 人工檢查 + run /spectra-archive <change> — this absorbs the worktree.
2. Run /commit on main — this ceremonies the accumulated diff.

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.

Non-UI tasks are automatically routed to Codex (cheaper, doesn't consume Claude context); UI tasks stay with Claude subagent. Use --claude or --codex to override.

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 skill being run is main-bound by design (/spectra-archive).
• 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 + subagent. Subagents run concurrently and commit inside their worktrees. There is no squash or cleanup at return — completed worktrees stay parked until archive-time merge-back (see Step 4). A failure in one task does not block the others.

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: /spectra-apply fix-auth
/wt evlog-dpattern: /spectra-ingest evlog-dpattern

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.mjs 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). There is no squash or cleanup at /wt return — those happen at archive time via wt-helper merge-back (per [[worktree-default]] §5.5).

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)

/wt ad-hoc invocation 沒有 spectra change context，所以不能做 scope-aware baseline commit（會撞 cross-session WIP）。預設走 stash-apply 策略 — 把 main 的 dirty（modified + untracked）一律 stash 起來、fork 後在新 worktree 內 git stash apply 把全部 baseline 帶過去，再 drop stash。Subagent 進 worktree 看 baseline 但收到 Step 2 的 warn 段落知道哪些檔不該動（[[worktree-default]] §1 Pre-fork baseline guard）。

node scripts/wt-helper.mjs add <slug> \
  --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 非空 → git stash push -u -m wt-baseline/<slug>/<ISO> on main.
• 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.
• （stash strategy + has stashed）cd 進 worktree 跑 git stash apply stash@{0} + git stash drop stash@{0} → worktree 看到 baseline dirty、main 的 stash list 清掉。
• Stash apply 失敗 → warn user，保留 stash entry 供手動恢復（極罕見：worktree 起步是 main HEAD 副本，理論不該衝突）。

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:

---
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 task to choose the executor. The default routing is automatic; users can override with --claude or --codex.

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

• /wt --claude <task> → force Claude subagent (Step 2)
• /wt --codex <task> → force Codex (Step 2-codex)
• No flag → auto-classify below

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

1. UI work → Claude subagent (Step 2)

   • Task description contains UI keywords: vue, css, scss, component, page, layout, styling, design, template, responsive, animation, UI, UX, 視覺, 畫面, 樣式, 介面
   • OR thin brief lists files matching: *.vue, *.tsx, *.jsx, *.css, *.scss, pages/, components/, layouts/, views/
   • Rationale: UI work requires Claude's visual reasoning + nuxt-ui-mcp / modern-web-guidance skill access. Codex has a hard view-layer guard.

2. Analysis/debug work → Codex via codex-dispatch.mjs (Step 2-codex-investigate)

   • Task description contains investigation keywords: analyze, analysis, debug, investigate, audit, scan, trace, why, root cause, 分析, 除錯, 調查, 掃描, 追蹤, 為什麼
   • Rationale: analysis/debug tasks benefit from Codex's structured evidence collection (codex-offload templates). These tasks typically don't need worktree commits — they produce JSON reports.

3. Non-UI coding work → Codex via codex exec (Step 2-codex)

   • Everything else: refactoring, adding tests, implementing features, fixing bugs, migrations, config changes, etc.
   • Rationale: non-UI coding is the sweet spot for Codex — cheaper, doesn't consume Claude context, follows the same codex-watch-protocol already proven in /commit and /spectra-apply.

Form-specific overrides:

• Form 3 (/wt <slug>: /<next-skill>): always Claude subagent — the subagent needs Skill tool access to invoke the next skill
• Form 4 (/wt resume <slug>): always Claude subagent — resume requires judgment to pick up from WORKTREE-BRIEF.md
• 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> → [codex|claude|codex:analyze|codex:debug] (<reason>)

Step 2 — Dispatch a Claude subagent into the worktree

Use the spawn_agent 工具 with:

• name: wt-<slug> (so a continuation pattern can SendMessage({to: name}) later).
• isolation: omit (the worktree itself is the isolation; the spawn_agent 工具's built-in worktree isolation is for the parent's repo, which we don't want).
• prompt: see the subagent prompt template below.

The subagent's cwd is set via the prompt — explicit instruction your working directory is <worktree-path>; all writes happen there. The parent's cwd remains on the main worktree.

Subagent prompt template

Your working directory is <worktree-absolute-path>. All file reads, writes,
and shell commands MUST run there. Do NOT cd out of this directory.

⚠️ **Baseline notice**: This worktree may have inherited untracked + modified
files from main's working tree via pre-fork stash-apply (Step 1 baseline guard,
see worktree-default.md §1). Run `git status` on start — any file NOT
mentioned in your task description below is main's starting state, **NOT
yours to deal with**. They came from main and will be handled by main's own
commit flow. Touching them in this worktree mixes scopes and bleeds them
into your session branch's commits.

WORKTREE-BRIEF.md exists at the worktree root with the full task context,
acceptance criteria, and a Progress checklist. As you work:
- Check off completed Progress items: change `- [ ]` to `- [x]`
- Add new items if you discover additional steps needed
- On completion: update frontmatter `status: done` and `last_updated` to now
- On being blocked: update `status: blocked` and add a note explaining why
- On failure: update `status: failed` and explain in the Progress section

Task:
<task description verbatim, or the next-skill invocation in form 3>

Contract:
1. Perform the task. Make commits inside the worktree as needed:
     git add -- <files-you-actually-changed>     # selective, NOT `git add -A`
     git commit -m "wt: <slug> — <short description>"
   Multiple commits are fine; only the squash-merged result lands on main.
   **MUST** selective stage — `git add -A` / `git add .` would catch any
   baseline inherited from main and bleed it into your session branch.
2. Do NOT run `git push` from the worktree. The session branch is short-lived.
3. Do NOT run `/commit` or `/spectra-commit` inside the worktree. Commit ceremony
   on main is the user's responsibility once changes accumulate.
4. When done, report back with:
   - Success: "done — commits: <SHA-list>, files: <count>". Optionally a one-line
     summary of what changed.
   - Failure: "fail — <reason>". If you abort before committing, the worktree
     branch will be preserved for the user to inspect.

Context for the task: <thin brief extracted from main session — see Parallel
Subagent Fan-out guidance in user AGENTS.md>.

The thin brief MUST be prepared by the parent before dispatching: file paths to touch, rules to follow, acceptance criteria. Do NOT spawn a subagent with only a task name and let it grep the repo cold — that violates the user's "Parallel Subagent Fan-out" rule and burns context.

For form 3 (dispatch a next-skill), the "Task" section is replaced with:

Task:
Invoke the Skill tool with skill="<next-skill-name>" and args="<args>".
Run that skill to completion inside this worktree. Report back per the contract above.

For resume (Step 0 detected existing worktree), the prompt is:

Your working directory is <worktree-absolute-path>. All file reads, writes,
and shell commands MUST run there. Do NOT cd out of this directory.

You are RESUMING an interrupted task in this worktree. The previous session
was interrupted before completing.

Read WORKTREE-BRIEF.md at the worktree root — it contains the original task
description, context, and a Progress checklist showing what was done and what
remains.

Git state:
<output of git log main..HEAD --oneline>
<output of git status --short>

Continue from the next unchecked Progress item in WORKTREE-BRIEF.md. Do NOT
start over or re-read the entire codebase cold — the brief already contains
the digested context.

Update WORKTREE-BRIEF.md Progress as you work (check off items, add new ones).
On completion: set frontmatter `status: done`.

Contract: same as a fresh task — selective `git add`, no `git add -A`,
no `git push`, no `/commit`. Report back with done/fail per the standard
contract above.

Step 2-codex — Codex dispatch into worktree (non-UI coding)

When Step 1.8 routes to Codex for coding work, use Bash run_in_background=true to dispatch codex exec directly (following [[codex-watch-protocol]]). The worktree is Codex's working directory.

1. Prepare the brief: Write to /tmp/wt-codex-<slug>-prompt.md using the Write tool. The brief MUST contain all of the following sections:

   [DELEGATED-BY-CLAUDE-CODE]
   
   ## Task
   
   <task description verbatim>
   
   ## Context
   
   <thin brief: file paths to touch, rules to follow, acceptance criteria — prepared by parent>
   
   ## Plan-first（**MUST**）
   
   在動任何 Edit / Write / Bash 寫入動作之前，先在 stdout 最開頭輸出一段 `## Plan` section，包含：
   - **要動的具體檔案**（每條一行的相對路徑）
   - **每個檔案打算做什麼變動**（一句話描述）
   - **預期影響範圍**
   
   Plan 寫完後**立刻**繼續執行，**不要**停下來等確認。
   
   ## Git Baseline（**MUST** 讀完再開工）
   
   <output of `git -C <worktree-path> status --porcelain` — list all dirty paths inherited from main's stash-apply>
   
   以上 path 是 main working tree 透過 stash-apply 帶過來的 baseline，**不是你的工作範圍**，不要動它們。
   
   ## Scope guard（**MUST**）
   
   你**只准**動以下 path：
   <list of files/directories relevant to the task>
   
   ## View-layer guard（**MUST**）
   
   **NEVER** 修改：`.vue` / `.tsx` / `.jsx` / `.css` / `.scss`，以及 `pages/` / `components/` / `layouts/` 底下的檔案。
   
   ## Commit Authorization（**MUST**）
   
   - **允許** commit：`git add -- <files>` + `git commit -m "🧹 chore: wt <slug> — <short>"`
   - **MUST** selective stage — `git add -A` / `git add .` 會撈到 baseline
   - **NEVER** `git push` / `git stash` / `git commit --amend` / `--no-verify`
   - commit 前 self-check：view-layer drift + scope discipline
   
   ## WORKTREE-BRIEF.md（**MUST** 更新）
   
   Worktree root 有 WORKTREE-BRIEF.md。工作時：
   - 完成 Progress item 時 `- [ ]` 改 `- [x]`
   - 新增步驟時加 item
   - 完成時 `status: done`，被卡住時 `status: blocked`
   
   ## 驗收標準
   
   <acceptance criteria from thin brief>
   
   完成後跑 `<build/test command>` 確認綠燈。
   
   **NEVER** 為了讓 test 綠而 hard-code 回傳值、跳過邏輯分支、或改測試期望值遷就實作。
   

2. Dispatch via background Bash:

   codex exec \
     --model gpt-5.6-sol \
     --dangerously-bypass-approvals-and-sandbox \
     --skip-git-repo-check \
     -c model_reasoning_effort=<effort> \
     --ephemeral \
     --disable memories \
     -C <worktree-absolute-path> \
     < /tmp/wt-codex-<slug>-prompt.md 2>&1
   

   effort 分級（-c model_reasoning_effort=<level>）：

   任務複雜度	effort	範例
   簡單機械修改（rename、config 調整）	low	更新 Node 版本 pin
   單一功能增改 / 加 test	medium	加 unit test 覆蓋特定函式
   跨檔 refactor / 功能實作	high	refactor cache layer 為 LRU eviction
   架構變動 / 複雜 migration	xhigh	資料庫 schema migration + handler 改寫
   極端複雜 / 需窮舉大量 edge case	max	從零實作一個完整子系統

   主線依任務描述的複雜度自行選 effort。判斷不了預設 high。

3. Report bash job ID to user immediately.

4. Start Watch Protocol (notification-only):

   • Immediately schedule one safety-net fallback: ScheduleWakeup(1500, "wt codex <slug> 安全網檢查")
   • On <task-notification status=completed>: read stdout → proceed to Step 3-codex
   • On <task-notification status=failed>: read stderr/stdout tail → report failure, preserve worktree
   • On safety-net wakeup with no notification: read BashOutput tail → healthy → re-schedule 1500s; stuck → request_user_input
   • After 30 min total: MUST request_user_input [continue / kill+redispatch / abort]

Step 2-codex-investigate — Codex analysis/debug into worktree

When Step 1.8 routes to analysis/debug, use codex-dispatch.mjs with the appropriate codex-offload template. These tasks produce structured JSON evidence — typically no commits needed.

1. Classify the investigation type:

   • Debug (error/bug/crash/failure/unexpected behavior/timeout/leak/exception/500) → debug-evidence.template.md, effort default high
   • Analysis (everything else: scan/audit/compare/survey/impact/coverage/why) → choose:
     • grep/command-collect/verify-matrix → fanout-collect.template.md, effort default medium
     • long-doc/cross-repo/release-notes/architecture → read-heavy-scan.template.md, effort default medium

2. Assemble --var parameters:

   • task: user's task description + mainline-added context (file paths, hypothesis list for debug)
   • acceptance: mainline-written acceptance criteria (NOT left to Codex to decide)
   • git_baseline: git -C <worktree-path> status --porcelain | head -20
   • allowed_paths: typically read-only; if the investigation needs writes (e.g., repro script), list specific /tmp/ paths

3. Dispatch via background Bash:

   node ~/offline/clade/vendor/scripts/codex-dispatch.mjs \
     --template ~/offline/clade/vendor/snippets/codex-offload/templates/<template>.template.md \
     --var "task=<task>" \
     --var "acceptance=<acceptance>" \
     --var "git_baseline=<baseline>" \
     --var "allowed_paths=<paths>" \
     --label wt-investigate-<slug> \
     --effort <effort> \
     --cwd <worktree-absolute-path>
   

   effort 分級：同 /codex-drive analyze / /codex-drive debug 各自的分級表。

4. Watch Protocol: same as Step 2-codex (notification-only + 1500s safety net).

5. On completion: parse the dispatcher's stdout JSON (exit code 0 → result field contains the template-specific JSON). Write key findings into WORKTREE-BRIEF.md under a # Findings section (so resume sessions can see the evidence without re-running).

Step 3 — Wait for completion

Claude subagent path (Step 2): The spawn_agent 工具 call returns when the subagent finishes. Parse its report to determine success vs. failure.

Codex coding path (Step 2-codex): 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:

   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 → request_user_input: [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

Codex investigation path (Step 2-codex-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):

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) [codex]: committed — 5 files, 2 commits on branch session/<date>-lru-cache
   <one-line summary from codex stdout>
   pending: /spectra-archive <change> will absorb via wt-helper merge-back
✅ B (csv-tests) [claude]: subagent committed — 2 files added on branch session/<date>-csv-tests
✅ C (perf-audit) [codex:analyze]: JSON result — 8 findings, status: pass
   findings written to WORKTREE-BRIEF.md # Findings
❌ D (node-upgrade) [codex]: codex fail — pnpm install exited 1
   worktree preserved at ~/offline/<consumer>-wt/node-upgrade/
   branch: session/<date>-node-upgrade

Pending worktrees: <N> (absorbed at /spectra-archive of matching change)

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

Key shift from v2.0: /wt no longer squashes or cleans up. Each worktree's branch carries committed work until its corresponding /spectra-archive run; archive Step 0 runs wt-helper merge-back --auto-stash --noop-if-missing <change-name> to atomically absorb + cleanup. This means main's working tree stays clean of in-progress work between sessions.

For non-spectra ad-hoc tasks (Form 1 with no corresponding change), the user runs wt-helper merge-back <slug> manually when ready to land.

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.

Codex task failure

Codex 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 codex exec 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 Codex investigation failures (Step 2-codex-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 Codex itself broke — check /tmp/codex-<label>-stderr.log. Exit code 4 (quota) means rate limited — wait or switch to Claude.

Squash conflicts (no longer at /wt time)

Squash happens at archive time (Step 0 of /spectra-archive, calling wt-helper merge-back). Conflict handling lives there — see [[worktree-default]] §5.5 and spectra-archive/SKILL.md Step 0. /wt does not encounter squash conflicts because it never squashes.

After /wt completes

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

The user's next moves:

1. (Spectra change worktree) When the change is ready to archive, run /spectra-archive <change-name>. Step 0 absorbs the worktree via wt-helper merge-back --auto-stash --noop-if-missing. Subsequent archive gates inspect the post-squash state.
2. (Ad-hoc Form-1 worktree) When ready to land, run node scripts/wt-helper.mjs merge-back <slug> --auto-stash. The diff lands on main's working tree; main commit ceremony via /commit.
3. Once one or more worktrees have been absorbed and main has accumulated diff, run /commit on main.

/wt does NOT:

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

These remain explicit later actions (archive + commit).

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.mjs add fix-auth + 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 ; do the work here. Use /wt only from the main worktree."

Token --dispatch-from-handoff appears in args

The flag from the previous /wt design is removed. If it appears in args, treat the token literally (it has no special meaning). Parent cwd never migrates regardless.

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

The subagent's reported status is the authority. If it says "done", proceed to squash. If the subagent's commits exist but it failed to report cleanly, treat as failure (preserve worktree, report ambiguity).

Related rules

• [[worktree-default]] — full rule baseline (§1 invariant, §5 mechanic, §6 tools).
• [[codex-watch-protocol]] — Codex 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 escalate to /spectra-propose.
• [[codex-offload]] — template registry for analysis/debug dispatch (~/offline/clade/vendor/snippets/codex-offload/).

Maintenance commands

node scripts/wt-helper.mjs list                              # list session worktrees
node scripts/wt-helper.mjs merge-back <slug>                 # atomically land worktree → main
node scripts/wt-helper.mjs merge-back <slug> --dry-run       # preview blockers
node scripts/wt-helper.mjs merge-back <slug> --auto-stash    # stash main blockers
node scripts/wt-helper.mjs land-pending <slug>               # alias for grandfathered worktrees
node scripts/wt-helper.mjs prune                             # remove merged ones interactively
node scripts/wt-helper.mjs cleanup <slug> --force --force-discard-unland  # discard worktree + commits
node scripts/stash-reconcile.mjs                             # plan recovery for wt-merge-block/* stashes

merge-back is the primary post-/wt action for ad-hoc Form-1 worktrees and for early-landing when needed. /spectra-archive calls it automatically as Step 0; users invoke it manually for non-spectra work.

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.