worktree-done git:20260910.b2bdfe6A

Immutable. This exact content never changes and is served at /api/v1/blob/5c561a79c95778a4.

---
name: worktree-done
description: Review, integrate, or finish a Toastty worktree task or PR from a session outside the task. When no target is named, discover open PRs and local worktrees with open Toastty workspaces in the current repository. Assess each task, then perform authorized integration and local task cleanup.
---

# Worktree Done

This example personal skill assesses and, when authorized, lands a task using
its repository's integration and verification rules. The finishing session can
be the original parent or another session; the original parent need not stay
active. The user can name the task or PR without supplying a commit SHA, or omit
the target to process the discovered tasks in the current repository.

## Resolve the task and authority

- Require `TOASTTY_CLI_PATH` and `TOASTTY_SESSION_ID`. If absent, stop with
  `error: worktree-done must run inside a Toastty-managed agent session`.
  Use `toastty-capabilities` to discover the running CLI's supported queries
  and actions before controlling sessions or workspaces.
- Resolve the task using the durable local launch record,
  `git worktree list --porcelain`, `WORKTREE_HANDOFF.md`, and live
  workspace/session metadata.
  Match branch and canonical checkout path, then workspace and session IDs;
  titles alone are insufficient. Ask only when the target remains ambiguous.
  Before controlling local resources, verify the finishing session's workspace
  scope. Add only workspaces assigned by the user or this authorized workflow;
  a launch record establishes identity, not authority. Respect `scope_denied`.
- For remote-only PRs, review and integrate through the repository workflow
  without requiring a local task workspace. Local cleanup is inapplicable when
  no task-owned resources exist; do not guess resources from a PR title.
- Resolve the landing branch and its checkout from the user's instruction,
  the handoff, and repository rules. Use upstream/default-branch information
  as evidence when needed; do not hardcode `main` or assume the task's base
  branch is the destination. Honor required PR, CI, review, and merge gates.
- Run integration from a clean landing checkout (or isolated integration
  checkout when needed) and cleanup from a finishing session
  outside both the target checkout and target workspace. Canonicalize paths
  through symlinks and compare directory boundaries, not string prefixes. If
  invoked from the child, prepare the readiness handoff and direct the user
  to run this skill from another session; do not delete the active session
  or expand its workspace scope.
- A request to merge and clean up authorizes both actions; do not ask again
  at each step. A merge-only request does not authorize termination or deletion.
  A readiness report, finished goal, or passing test does not authorize a merge.
- A review-only request authorizes assessment and a report, not changes to the
  task branch, PR state, or child workspace. Do not advance into landing,
  evidence archiving for cleanup, process termination, or deletion without the
  corresponding authorization. Keep feedback in the finishing report or
  task record;
  posting PR comments or requesting changes from the child needs authorization
  for that action, which may already be part of the task.

## Discover tasks when no target is named

- Honor an explicit task, PR, or repository scope. Otherwise infer the repository
  from the current checkout and Toastty session metadata; ask only if those
  cannot identify one repository. Do not search all of the user's repositories.
- Discover all open PRs in that repository, including additional result pages,
  and local Git worktrees matched to currently open Toastty workspaces. Use
  canonical checkout paths and branch/repository identity, not workspace titles.
  Include local tasks without PRs; an open workspace is discovery evidence, not
  proof that its task is ready. Exclude the landing checkout from local task
  candidates. If PR access is unavailable, continue with local discovery and
  report the access limit rather than treating it as zero open PRs.
- Combine both sources into one task list, deduplicating a PR and its matching
  local worktree. Preserve repository identity for fork PRs; a matching branch
  name alone does not establish a local resource association. Report uncertain
  matches without guessing which resources belong to the PR.
- Briefly state the discovered scope, then assess every candidate through the
  workflow below without asking the user to choose one. Discovery does not
  grant merge, push, session-control, or cleanup authority; apply the user's
  existing authorization to each task and prepare any remaining approval as
  one concrete batch. Respect workspace scope and the finishing-session rule;
  retain a task containing the current session and report its handoff separately.
- Use dependencies and overlapping changes to choose an order. Recheck the
  destination and affected assessments after each integration. Keep blocked,
  draft, or still-active tasks pending and continue with independent candidates;
  do not land dependent work past a blocker. End with a result or blocker for
  every candidate, or state that no candidates were found with any discovery
  limits. This is one discovery pass, not an ongoing monitor.

## Establish readiness

- Read repository instructions first (`AGENTS.md`/`CLAUDE.md`), then the local
  verify skill they name, then relevant build/test docs and CI configuration.
  Use those to select and report the required review and checks for this diff.
  If no verification guidance exists, choose the smallest meaningful checks
  supported by the project and state what remains unverified.
- Read the PR handoff and its review/test evidence, or the durable local task
  note when there is no PR. An optional Scratchpad can add visual context but
  is not required. Match `ValidatedCommit: <full SHA>` to the source tip. If
  evidence is missing or stale, establish the assessed head and complete the
  required verification before integration; do not equate “done” with verified.
- For a PR, verify its repository, base branch, head branch, and live head SHA
  against the task identity. Integration requires the PR head, any assigned
  local task branch tip, and `ValidatedCommit` to agree, with required review
  and CI covering that head.
  Do not silently choose the newer of conflicting tips. For review-only work,
  assess an explicitly identified current commit and label missing or stale
  readiness evidence; it need not prevent useful read-only feedback.
- Before integration, coordinate the task owner and recheck the source head.
  For an assigned local child, confirm it is idle and will not continue writing.
  For local resources, capture the branch tip and worktree status, including
  untracked files and content fingerprints for artifacts that will be removed. Status paths alone
  cannot detect later edits to an already-untracked handoff.
  Preserve uncommitted or unpublished work; never stash, reset, or force it
  away. Treat the handoff as an artifact to preserve, not a product change.
- Before integration, check the landing checkout can accept it without mixing
  unrelated local changes. Preserve those changes; do not clear them to make room.
  Refresh the destination only as the repository requires, without discarding
  local commits or bypassing its integration policy.

## Project assessment

Integration requires a completed project assessment of the exact task commit.
Run this pass before merging if no current assessment exists, even when
integration is authorized without a separate review request. It also supports
review-only requests and complements
repository-required independent review and CI; human testing follows deployment.

- Review the task diff in the context of existing code: design and ownership
  boundaries, established abstractions and naming, duplicate capability,
  maintenance cost, API and data contracts, failure handling, security and data
  preservation, and missing tests or documentation. Keep mechanical style
  checks with existing formatters/linters; explain concrete consequences for
  design findings.
- Inspect the intended target branch and relevant open PRs and active worktrees
  in the same repository. Use their identified commit heads, prioritizing shared
  files, interfaces, data models, configuration, and overlapping product scope.
  Record which work was examined and any access or discovery limits; do not
  claim compatibility with work you could not inspect.
- Distinguish Git conflicts from semantic incompatibility: changes can merge
  cleanly while disagreeing about a contract or expected behavior. Start with
  read-only inspection. When a specific interaction cannot be resolved that
  way, use a disposable integration worktree for the candidate and the relevant
  changes expected to land first, then run focused checks. Record the tested
  commits, order, commands, and results. Keep this worktree outside child
  workspaces and use detached commits; never stash or change task/landing
  checkouts for the experiment. Remove only this disposable worktree when the
  checks finish, preserving useful results in the report; report any teardown
  failure. This review-owned teardown does not authorize task cleanup. Do not
  rebase the children's branches, test every possible combination, or require
  a speculative build for every review.
- Report the assessed task/PR head, target SHA, relevant peer SHAs, coverage
  limits, blocking findings, optional suggestions, and any recommended merge
  order. Unresolved material conflicts or correctness risks block integration;
  cosmetic preferences do not become new gates. Keep the report in the durable
  task record; a Scratchpad can present it. Publish findings on the
  PR only when authorized.
- The task owner owns fixes. Return actionable findings to the user and, when
  authorized, resume the existing child for accepted corrections. If that agent
  is unavailable, arrange an authorized replacement using the PR and task record.
  Existing task
  authorization can cover routine fixes within scope; review-only requests do
  not add permission to initiate edits. Changed code
  invalidates readiness; require an updated PR/branch head, affected review and
  checks, and revised human-testing evidence where needed. Reassess the changed
  areas before landing. Do not silently take over the child's implementation
  or expand its task to satisfy an optional suggestion.
- For review-only requests, stop after the report. Before an authorized merge,
  recheck the live PR/task head, target branch, and relevant peer heads against
  this assessment. A changed task head needs fresh readiness evidence; changes
  to the target or related work need an updated conflict/interaction assessment
  and affected checks. Observe repository requirements for approval; human testing
  follows deployment unless the PR names a pre-merge manual check. No permanent monitoring service is part of this workflow.

## Preserve evidence, land, and verify

- Before local cleanup, preserve the task handoff and status note, source identity, PR/review
  links and verification evidence in a unique task directory outside the checkout
  being removed. Use the repository's ignored artifact location or a durable
  directory outside Git; never overwrite an earlier archive. Include canonical
  checkout/branch and workspace/session IDs for resources to be removed.
  Export any existing linked child Scratchpad while its session link remains.
  Absence of a Scratchpad is valid; inability to preserve required evidence is
  a reason to retain resources. Keep machine metadata out of public PRs.
- Integrate the validated source commit through the repository's established
  merge or PR workflow. Recheck that the source tip and any local task status
  have not changed before landing; stop if they have. Do not push or publish
  unless authorized.
  Resolve conflicts only within the agreed behavior; a material behavior
  decision still needs the user.
- Inspect the landed diff for accidental handoff files or other task artifacts.
  Validate the actual landed result with the repository's required checks,
  including generation/build and runtime checks when applicable. Record the
  landed SHA and the exact commands, targets, and results in the durable task
  record. Earlier child checks do not prove that integration works.
- If validation fails, keep the child workspace, worktree, and branch available
  while making authorized, scoped corrections. Do not claim completion merely
  because the merge succeeded.
- Preserve the PR-to-landed-commit correspondence in the task record.
  Integration does not prove deployment. Use the repository release workflow
  to establish delivery separately.

## Authorized cleanup

Proceed only after integration is verified and cleanup is authorized. If the
user requested only a merge, report its result and leave cleanup pending.

- Recheck the recorded source tip and worktree status before stopping the child.
  Any new edits or commits require reconciliation before cleanup. Inventory the
  target workspace for other sessions, terminals, unsaved documents, or work
  unrelated to this task; leave it open if closing it would discard that work.
- Stop only task-owned development servers or runtime instances using their
  recorded identities and repository cleanup instructions. Terminate the actual
  child agent process through supported Toastty terminal controls when authorized;
  marking a session stopped is bookkeeping, not proof that its process exited.
  Follow `toastty-capabilities` closing rules and never override an unsaved
  document block. Verify task writers have exited; if the available API only
  updates tracking, inspect processes tied to the checkout or retain it.
- Close the task workspace using supported controls once its owned processes
  are stopped and documents are saved or archived. Never close the finishing
  session's workspace. If the CLI cannot safely perform this step, report it as pending
  and retain the worktree rather than inventing a command or broad kill pattern.
- Immediately before filesystem removal, recheck the source SHA and worktree
  status and artifact contents against the captured values. Inspect ignored
  files too: preserve user data and configuration, and discard only confirmed
  disposable build output. Only remove task artifacts that were
  archived and unchanged; any other uncommitted or untracked content blocks
  deletion. Use `git worktree remove` without `--force`, then `git branch -d`
  for the fully merged local branch. Never use `git branch -D`.
- Ancestry proves ordinary merges; squash or rebase requires establishing that
  the validated source changes landed using the repository's integration
  evidence and diff inspection. If safe branch deletion refuses, leave the
  branch and report it. Do not force deletion to make cleanup appear complete.

Report the source and landed SHAs, verification, evidence archive, and which
processes, workspace, worktree, and branch were removed or retained. On partial
failure, report the completed step and remaining work. On a retry, inspect the
recorded landed result first so an already integrated task is not merged again.