# New Thread > Launch and control an implementation agent in its own wt worktree and Fut workspace. Use when the user asks to start a new thread, delegate isolated work, or run a task in a separate workspace. - Skill: `mikker/new-thread` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add mikker/new-thread` - Raw SKILL.md: https://api.skillmd.com/api/skills/mikker/new-thread/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: mikker (https://skillmd.com/u/mikker) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mikker/new-thread --- # New Thread Run a free-form task in a dedicated Git worktree, Fut workspace, and integrated Pi agent. The worktree path is the workspace root; do not put the agent in a new pane or tab of the caller's workspace. ## Launch 1. Read the installed `wt` and `fut` help needed for the commands below. Treat those CLIs as authoritative. 2. Derive two concise, distinctive names without asking when the request makes them clear: - **Worktree name:** a short branch-compatible identifier. If the request names a ticket, inspect it first and prefer its ID or a compact title slug. - **Workspace title:** a very short human-readable label, ideally one to three words, that is easy to distinguish in Fut's navigator. It may be shorter and friendlier than the worktree name. 3. Build a complete child prompt in a literal heredoc and launch the thread with the companion script: ```sh /scripts/launch-thread --workspace-name <<'PROMPT' PROMPT ``` The script requires `git`, `wt`, `fut`, `jq`, and `pi`. It creates the worktree, creates a new Fut workspace, polls for Pi integration, verifies the exact workspace root, submits the prompt through `fut agent prompt --stdin`, and prints a JSON manifest. It also stores that manifest under `/new-thread/.json`, outside the disposable worktree, so the final report survives teardown. Record its manifest path, worktree, workspace, pane, and terminal IDs. For an existing prompt file, pass `--prompt-file ` instead of stdin. Create multiple threads one after another rather than running launchers in parallel, because concurrent `wt create` calls can contend on Git locks. 4. Require the manifest's prompt result to report `submitted: true`. The helper has already required a fresh `workspace_created` or `session_created` disposition, `available: true`, and an exact root match. `session_created` is the normal fresh result when the repository had no existing Fut session. The helper still rejects `existing`, reuse results, and every unknown disposition. If it fails after worktree creation, follow the printed resource IDs and path; do not launch another agent blindly or remove the retained worktree without checking it. 5. Run every later Git, ticket, build, and cleanup command with an explicit `cd` to either the recorded worktree or main checkout. Ticket changes made inside the worktree are branch-local until merged, including `tk start`. The child prompt must preserve the user's request verbatim. Also tell the child to read the repository instructions, inspect relevant ticket details, make a complete implementation, add focused tests and user-facing docs/changelog where required, run the project's required build, preserve existing changes, avoid committing unless requested, and report changed files plus exact validation results. State explicitly that the parent thread owns completion: the child must not run `wt done`, `wt rm`, close or retire its Fut workspace, or delete its active worktree. ### Manual fallback If the helper is unavailable or incompatible with the installed CLIs, perform the same steps manually from the main checkout: ```sh wt create fut --json open --background --name -- pi --name fut --json agent get fut --json get prompt_text=$(cat ) fut --json agent prompt -- "$prompt_text" ``` Require `disposition: workspace_created` or `session_created`; never accept `existing`, a reuse result, or an unknown disposition. Poll `agent get` with a bounded timeout rather than sleeping once. Confirm the exact workspace root and `available: true` before prompting. Store the resource IDs and lifecycle state under the common Git directory rather than inside the disposable worktree. Do not wait for completion by default. Report the workspace name, worktree path, and launched task so the user can switch to it immediately. ## Control Always target the recorded terminal ID; never rely on whichever workspace or pane currently has focus. ```sh fut --json agent get fut --json agent read --source recent-unwrapped --lines 200 fut --json agent wait --timeout 10m follow_up=$(cat ) fut --json agent prompt --wait --timeout 10m -- "$follow_up" ``` - Use `agent wait` for work already underway. - Use `agent prompt --wait` for a fresh follow-up and inspect the returned lifecycle state. A `blocked` state is a result to surface, not a reason to retry blindly. - Read the agent's output and inspect the worktree diff before accepting the result. Send review fixes back through `agent prompt` when appropriate. - Keep the workspace open until the user asks to finish or abandon it. ## Finish Completion belongs to the parent thread or another controller outside the owned worktree and Fut workspace. A child must never delete the directory that is its active cwd or terminate the workspace carrying its own final report. Before cleanup, inspect status from the recorded worktree path, then run the companion completion script from the parent thread: ```sh /scripts/finish-thread --done /scripts/finish-thread --abandon ``` The script refuses to run from inside the owned worktree or from the owned Fut workspace/terminal. It captures `agent get` and up to 2,000 unwrapped output lines into the durable manifest, atomically records `report_persisted`, closes the owned workspace by explicit ID, and only then runs `wt done` or confirmed `wt rm --force`. If capture or close fails, it records the failure and leaves the worktree in place. If teardown fails after close, the durable report and failure state remain available for recovery. When the user asks to commit and merge: 1. Ensure validation passed and commit all intended work in the worktree. 2. From outside the worktree, run `finish-thread --done`. Never push unless requested. 3. Verify the main checkout, the durable manifest, and `wt ls`. When the user asks to abandon the thread, run `finish-thread --abandon` from outside the worktree. The helper provides the explicit confirmation still required by some `wt rm --force` versions. Never close or remove resources that were not created for this thread. ## Failure Safety - If worktree creation succeeds but workspace creation fails, report the worktree and offer to retry or remove it. - If agent integration does not appear, inspect the terminal before closing it; do not launch a second agent blindly. - Do not clean up if final state or output capture fails. The completion helper persists a typed failure in the manifest and deliberately leaves resources available for inspection. - Treat installed `fut agent prompt --help` as authoritative. Use `--stdin` when that version supports it; otherwise read the file into a quoted shell variable and pass it as positional `TEXT` after `--`. Use quoted heredoc delimiters so backticks, dollar signs, and command substitutions remain literal. - Preserve surprising changes in both the main checkout and worktree.