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:

   <skill-dir>/scripts/launch-thread <worktree-name> --workspace-name <workspace-title> <<'PROMPT'
   <complete child 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 <common-git-dir>/new-thread/<workspace-id>.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 <path> 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:

wt create <worktree-name>
fut --json open --background --name <workspace-title> <worktree-path> -- pi --name <workspace-title>
fut --json agent get <terminal-id>
fut --json get <workspace-id>
prompt_text=$(cat <prompt-file>)
fut --json agent prompt <terminal-id> -- "$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.

fut --json agent get <terminal-id>
fut --json agent read <terminal-id> --source recent-unwrapped --lines 200
fut --json agent wait <terminal-id> --timeout 10m
follow_up=$(cat <follow-up-file>)
fut --json agent prompt --wait --timeout 10m <terminal-id> -- "$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:

<skill-dir>/scripts/finish-thread <manifest-path> --done
<skill-dir>/scripts/finish-thread <manifest-path> --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 <manifest-path> --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 <manifest-path> --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.