Worktree implementation executor. ALWAYS invoke this skill when instructed to implement a plan in a worktree with testing and merging. Do not read the plan or edit files directly — use this skill first to load the full implementation workflow.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Worktree implementation executor. ALWAYS invoke this skill when instructed to implement a plan in a worktree with testing and merging. Do not read the plan or edit files directly — use this skill first to load the full implementation workflow.
hooks
{"PreToolUse":[{"matcher":"*","hooks":[{"type":"command","command":"echo '🌳 [SKILL: implement-worktree] Setting up isolated worktree implementation...'","once":true}]}]}
Implement in Worktree Skill
Implement a provided plan in an isolated git worktree branched from the current branch.
When to Use
User says "implement in worktree", "worktree implement", "isolated implementation"
User provides a plan and wants it executed in a fresh worktree
Arguments
{plan_path} — Absolute path to the implementation plan file (required)
Critical Constraints
NEVER:
Implement without first exploring affected systems with subagents
Implement in the main working directory (always use the worktree)
Force push or perform destructive git operations
Consider implementation complete if ANY test fails
Blame test failures on "pre-existing issues" — ALL tests must pass
Re-run tests just to see failures — grep the saved output file instead
Run subagents in the background (run_in_background: true is prohibited)
ALWAYS:
Create a new worktree from the current branch
Use subagents to deeply understand affected systems BEFORE implementing
Use model: "sonnet" when spawning all subagents via the Task tool
Implement one phase at a time
Run the project's test suite after implementation
Rebase onto base branch before completion (ready for squash-and-merge)
Read before editing: Before issuing an Edit call on any file, ensure you have issued a Read on that file earlier in this session. Claude Code rejects Edit on unread files — the retry wastes a full API turn at current context size. If you are uncertain whether a file was read, issue a targeted Read (offset + limit to the region you plan to edit) rather than risk an error.
Context Limit Behavior
If this skill hits the Claude context limit mid-execution, the headless session
terminates with needs_retry=true in the tool response. The worktree remains
intact on disk with all commits made up to that point.
The orchestrator must not retry this skill when needs_retry=true. Retrying
creates a brand-new timestamped worktree, discarding all partial progress.
Correct orchestration on needs_retry=true:
Route immediately to /autoskillit:retry-worktree (via retry.on_exhausted)
Pass worktree_path from context.worktree_path (captured from this step's output)
Use max_attempts: 0 on this step's retry block to ensure immediate escalation
Workflow
Step 0: Validate Prerequisites
Extract and verify the plan path using path detection: scan the tokens
after the skill name for the first one that starts with /, ./, {{AUTOSKILLIT_TEMP}}/,
or .autoskillit/ — that token is the plan path. Ignore any non-path words
that appear before it. If no path-like token is found, treat the entire
argument string as pasted plan content. Verify the resolved file exists before
proceeding; if it does not, abort with:
"Plan file not found: {path}. Correct format: /autoskillit:implement-worktree <plan_path>"
Check for dry-walkthrough verification: Read the first line of the plan file. If it does not contain exactly Dry-walkthrough verified = TRUE:
Display warning: "⚠️ WARNING: This plan has NOT been validated with a dry-walkthrough. Implementation may encounter issues that could have been caught beforehand."
Use AskUserQuestion to prompt: "Do you want to continue without dry-walkthrough validation?"
If user declines, abort and suggest running /autoskillit:dry-walkthrough first
Check git status --porcelain — if dirty, warn user
Parse plan: phases, files per phase, verification commands
Multi-Part Plan Detection: Examine the plan filename. If it contains _part_ (e.g., _part_a, _part_b, _part_1):
Extract the part identifier (A, B, C… or number) from the suffix.
SCOPE FENCE — MANDATORY: Before any exploration or implementation begins, output the following constraint:
"🚧 SCOPE FENCE ACTIVE: I am implementing PART {X} ONLY. I MUST NOT open, read, or execute any other part files, regardless of what I encounter in {{AUTOSKILLIT_TEMP}}/ or any other directory. Sibling part files are out of scope for this entire session."
When launching subagents in Step 2, include this fence instruction explicitly in each subagent prompt so that the subagents do not open, read, or reference sibling part files.
Before implementing ANY code, launch parallel Explore subagents to understand affected systems:
Affected files — current implementation, dependencies, consumers
Test coverage — existing tests, patterns, fixtures for affected code
Integration points — entry/exit points, contracts that must be maintained
Data flow — state management, source of truth
Step 3: Set Up Worktree Environment
Set up the project's development environment in the worktree. Use the project's configured worktree_setup.command from .autoskillit/config.yaml if available. If not configured, check for a Taskfile with install-worktree task, or detect the project type and run appropriate setup.
cd"${WORKTREE_PATH}"# If worktree_setup.command is configured, run it. Otherwise:
task install-worktree # or equivalent for the project type
Why isolated env matters: Installing packages without isolation overwrites the global state. When the worktree is deleted, CLI commands break with import errors.
All commands in Steps 4–6 must run from ${WORKTREE_PATH}. Use absolute paths to avoid CWD drift across Bash tool calls.
Step 4: Implement Phase by Phase
NEVER pause for confirmation between phases. Once the plan is loaded, execute all
phases sequentially without asking the user whether to proceed to the next phase.
For each phase:
Announce phase objective and files to modify
Implement changes guided by understanding from Step 2
Run per-phase verification if plan specifies it
Commit per phase if possible
Report phase completion
Where practical, delegate test updates to subagents to keep main conversation context lean.
Step 4.5: Pre-Implementation Checklist
Before running the test suite, confirm the following to prevent avoidable test-fix cycles:
CLAUDE.md architecture section — if new modules, sub-packages, or files were added,
the ## Architecture section in CLAUDE.md reflects them
Recipe diagrams — if any recipe YAML file was added or modified, either regenerate
diagrams (task diagrams) or confirm new diagram files are listed in .gitignore
Project-specific registration checks — if the project maintains a registry of
components (e.g., a tool registry, a plugin manifest, a module index), verify any
newly added components are registered. This prevents cascading test failures caused
by missing registrations rather than implementation bugs.
Documentation consistency — if the project maintains architecture documentation
or a component count (e.g., in CLAUDE.md, README, or API docs), update it to reflect
new components added during this implementation.
Count-based test assertions — if tool, skill, or rule counts have changed, update any
assert len(...) == assertions in the test suite before running {test_command}
This checklist exists because these categories produce avoidable test-fix cycles: a single
missed registration generates 5–30 cascading test failures that require a second commit to fix.
Step 5: Final Verification
Read the configured test command(s) from .autoskillit/config.yaml: check test_check.commands (ordered list of commands, if set) or test_check.command (single command, default: task test-check). The test_check MCP tool runs all configured commands automatically.
Run the project's code quality checks and test suite from the worktree.
If conflicts occur, resolve them, git rebase --continue, then re-run tests. Report rebase status.
Step 7: Completion Report
Output to terminal: worktree path, branch name, base branch, status, summary of changes, and next steps (fast-forward merge then clean up).
Change directory before removing worktree to prevent deleting the cwd.
Always confirm the merge went through before removing work tree.
Do not merge until user confirms first!
Then emit these structured output tokens on their own lines so recipe capture blocks can extract them:
IMPORTANT: Emit the structured output tokens as literal plain text with no
markdown formatting on the token names. Do not wrap token names in **bold**,
*italic*, or any other markdown. The adjudicator performs a regex match on the
exact token name — decorators cause match failure.
Phase fails — report which phase and why, offer to fix/retry, skip (if optional), or abort and clean up
Tests fail — implementation is NOT complete. Fix the issue. If truly unfixable, report to user and ask for guidance. Do NOT proceed or mark as complete.
Rebase conflicts — resolve keeping implementation intent intact, re-run full test suite after
