# Implement Worktree No Merge

> Implementation executor. ALWAYS invoke this skill when instructed to implement a plan in a worktree. Do not read the plan or edit files directly — use this skill first to load the full implementation workflow.

- Skill: `talont-org/implement-worktree-no-merge` (Agent Skill)
- Install (CLI): `npx skillmds@latest add talont-org/implement-worktree-no-merge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/talont-org/implement-worktree-no-merge/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-no-merge

---


# Implement in Worktree (No Merge) Skill

Implement a provided plan in an isolated git worktree branched from the current branch.
The worktree is left intact for the orchestrator to test and merge separately.

## When to Use

- MCP orchestrator calls this via `run_skill`
- Orchestrator wants to control test/merge gates independently

## 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
- Merge the worktree branch into any branch
- Delete or remove the worktree
- Run the full test suite (the orchestrator handles testing)
- Rebase onto the base branch
- Clean up the worktree environment
- Re-run tests just to see failures — grep the saved output file instead
- Pipe test output through `tail`, `head`, or other truncation commands
- **Execute `git merge` commands** (including `--no-ff`, `--no-commit`, or any variant). All branch content must be applied via `git cherry-pick <commit>` for individual commits or `git checkout <branch> -- <file>` for specific files. `merge_worktree` requires linear commit history — merge commits cannot be rebased and will cause `WORKTREE_INTACT_MERGE_COMMITS_DETECTED` failure.
- 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
- Commit per phase with descriptive messages
- Leave the worktree intact when done
- **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.
- **Read files fully**: When reading a file to understand it in full, read it in a single call without a `limit` parameter. Do not paginate files with sequential offset reads — read once completely. Use `limit`/`offset` only for targeted section reads of files you have already read in full.

## 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`)
- The `run_skill` response now includes `worktree_path` as a top-level JSON
  field when `needs_retry=true`. The orchestrator reads it from
  `result.worktree_path` — no filesystem search is needed.
- 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 (orchestrators sometimes prepend descriptive text such
   as "the verified plan"). When no path-like token is present, 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-no-merge <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)"

# Record the base branch in two ways for reliable discovery by retry-worktree:
# 1) Write an explicit file store (stdlib-only, works with any Git version, works offline)
python3 -c "
from pathlib import Path
import tempfile, os
project_root = Path('$(git rev-parse --show-toplevel)')
sidecar_dir = project_root / '.autoskillit' / 'temp' / 'worktrees' / '${WORKTREE_NAME}'
sidecar_dir.mkdir(parents=True, exist_ok=True)
sidecar_file = sidecar_dir / 'base-branch'
fd, tmp = tempfile.mkstemp(dir=str(sidecar_dir))
os.write(fd, ('${CURRENT_BRANCH}' + '\n').encode())
os.close(fd)
os.replace(tmp, str(sidecar_file))
"
# 2) Set git upstream tracking (requires remote tracking ref in local fetch cache)
REMOTE=$(git remote get-url upstream 2>/dev/null | grep -qv "^file://" && echo upstream || echo origin)
if ! git fetch "$REMOTE" "${CURRENT_BRANCH}" 2>/dev/null; then
    echo "NOTE: Branch '${CURRENT_BRANCH}' has no remote tracking ref on $REMOTE."
    echo "      merge_worktree will fail unless you push first: git push -u $REMOTE ${CURRENT_BRANCH}"
    echo "      Continuing — implementation will proceed, but the merge step will be blocked."
fi
if ! git -C "${WORKTREE_PATH}" branch --set-upstream-to="${REMOTE}/${CURRENT_BRANCH}" "${WORKTREE_NAME}" 2>/dev/null; then
    echo "NOTE: Could not set upstream tracking for '${WORKTREE_NAME}' → '$REMOTE/${CURRENT_BRANCH}'."
fi
```

### Step 1 (cont.): Emit Structured Tokens Early

Immediately after the worktree is created, output these tokens on their own
lines so the execution layer can capture them from `assistant_messages` even
if context is exhausted before Step 6:

> **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}
```

**Why emit early?** If context exhaustion occurs during Steps 2–5, the
execution layer scans `assistant_messages` for `worktree_path=` and surfaces
it as a top-level field in the `run_skill` JSON response. The orchestrator
reads this field directly without filesystem discovery heuristics.

### 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–5 must run from `${WORKTREE_PATH}`.** Use absolute paths to avoid CWD drift across Bash tool calls.

### Step 4: Implement Phase by Phase

For each phase, begin implementation immediately (no announcement):
1. Implement changes guided by understanding from Step 2
2. Run per-phase verification if plan specifies it
3. Commit per phase with descriptive messages. If the project has pre-commit
   hooks, run `pre-commit run --all-files` and stage any auto-fixed files
   before each commit.

Where practical, delegate test updates to subagents to keep main conversation context lean.

### Step 5: Run Pre-commit Checks

```bash
cd "${WORKTREE_PATH}" && pre-commit run --all-files
```

Fix any formatting or linting issues. Do NOT run the full test suite.

### Step 5.5: Completeness Self-Check (Conflict Resolution Plans Only)

If the plan contains a `PR Changes Inventory` section, perform a completeness check before
handoff:

1. Extract the **Category C — Clean Carry-Overs** file list from the plan.
2. Run `git diff {base_branch}...HEAD --name-only` to get all files in the implementation.
3. For each Category C file, verify it appears in the diff.
4. If any Category C files are missing from the diff:
   - Fetch them from the PR branch: `git show origin/{pr_branch}:{file_path}`
   - Write them to the worktree and commit: `fix: carry over {file_path} from PR branch`
   - Re-run the check until all Category C files are present.

This guard prevents silent data loss: Category C files are PR-only changes that require no
conflict resolution and must be preserved in full.

### Step 6: Handoff Report

Output to terminal:
- **Worktree path:** `${WORKTREE_PATH}`
- **Branch name:** `${WORKTREE_NAME}`
- **Base branch:** the branch the worktree was created from
- **Summary:** list of implemented phases and key changes

Explicitly state: "Worktree left intact for orchestrator to test and merge."

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.

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

**If this is a `_part_` plan file:** The orchestrator MUST merge this worktree
(`merge_worktree`) into the base branch BEFORE invoking
`implement-worktree-no-merge` for the next part. Part N+1's worktree must be
created from the post-merge state of the base branch, not from Part N's base
commit. This is a global sequencing rule — it applies even when operating
off-recipe.

## 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. Do NOT clean up the worktree.
- **Pre-commit fails** — fix formatting/linting issues and re-commit