# Implement Worktree

> 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.

- Skill: `talont-org/implement-worktree` (Agent Skill)
- Install (CLI): `npx skillmds@latest add talont-org/implement-worktree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/talont-org/implement-worktree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: TalonT-Org (https://skillmd.com/u/talont-org)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/talont-org/implement-worktree

---


# 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

1. 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>"`
2. **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
3. Check `git status --porcelain` — if dirty, warn user
4. Parse plan: phases, files per phase, verification commands
5. **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.

### Step 1: Create Git Worktree

```bash
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
WORKTREE_NAME="impl-{plan_name}-$(date +%Y%m%d-%H%M%S)"
WORKTREE_PATH="../worktrees/${WORKTREE_NAME}"
git worktree add -b "${WORKTREE_NAME}" "${WORKTREE_PATH}"
WORKTREE_PATH="$(cd "${WORKTREE_PATH}" && pwd)"
mkdir -p "{{AUTOSKILLIT_TEMP}}/worktrees/${WORKTREE_NAME}"
echo "${CURRENT_BRANCH}" > "{{AUTOSKILLIT_TEMP}}/worktrees/${WORKTREE_NAME}/base-branch"
```

### Step 2: Deep System Understanding (Subagents)

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.

```bash
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:
1. Announce phase objective and files to modify
2. Implement changes guided by understanding from Step 2
3. Run per-phase verification if plan specifies it
4. Commit per phase if possible
5. 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.

```bash
cd "${WORKTREE_PATH}" && pre-commit run --all-files
cd "${WORKTREE_PATH}" && \
  AUTOSKILLIT_TEST_FILTER="${AUTOSKILLIT_TEST_FILTER:-conservative}" \
  AUTOSKILLIT_TEST_BASE_REF=$(cat "{{AUTOSKILLIT_TEMP}}/worktrees/${WORKTREE_NAME}/base-branch") \
  {test_command}
```

If tests fail, fix the issue and re-run.

### Step 6: Rebase for Squash-and-Merge

```bash
CURRENT_BRANCH=$(cat "{{AUTOSKILLIT_TEMP}}/worktrees/${WORKTREE_NAME}/base-branch")
REMOTE=$(git remote get-url upstream >/dev/null 2>&1 && echo upstream || echo origin)
git fetch "$REMOTE"
git rebase "$REMOTE/${CURRENT_BRANCH}"
```

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:

```bash
CURRENT_BRANCH=$(cat "{{AUTOSKILLIT_TEMP}}/worktrees/${WORKTREE_NAME}/base-branch")
```

> **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.

```
worktree_path = ${WORKTREE_PATH}
branch_name = ${WORKTREE_NAME}
base_branch = ${CURRENT_BRANCH}
```

## Error Handling

- **Worktree creation fails** — check `git worktree list`, suggest `git worktree prune`
- **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