# Recursive Worktree

> Use when starting any recursive-mode requirement to set up an isolated git worktree. Required before implementation phases: create an isolated workspace, verify a clean baseline, and keep main/master clean.

- Skill: `try-works/recursive-worktree` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add try-works/recursive-worktree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/try-works/recursive-worktree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: try-works (https://skillmd.com/u/try-works)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/try-works/recursive-worktree

---


# recursive-worktree

## Purpose

Use this skill at the start of a recursive-mode run to set up an isolated worktree before Phase 1+ work begins.

The canonical overall workflow still lives in `/.recursive/RECURSIVE.md`. This skill covers only the worktree-isolation discipline for `00-worktree.md`.

## Hard Rule

Do not proceed with recursive-mode phase work until:

1. A feature-branch worktree exists.
2. The worktree directory is git-ignored if it lives inside the repo.
3. Project setup has completed.
4. A clean or explicitly acknowledged baseline test state has been recorded.

## Default Location Order

Use this priority:

1. Existing `.worktrees/`
2. Existing `worktrees/`
3. A preference documented in repo instructions
4. Ask the user
5. Default to `.worktrees/`

Global fallback location:

- `~/.config/recursive-mode/worktrees/<project-name>/`

## Main Branch Protection

If the current branch is `main` or `master`, default to creating a worktree on a feature branch:

```bash
git worktree add .worktrees/<run-id> -b recursive/<run-id>
cd .worktrees/<run-id>
```

If the user explicitly insists on main-branch work, record that exception in `00-worktree.md`.

## Minimum Phase 0 Checklist

`00-worktree.md` must cover:

- selected worktree location
- git-ignore verification
- branch name and worktree path
- setup commands executed
- baseline test command and result
- normalized diff basis fields including `Baseline type`, `Baseline reference`, `Comparison reference`, `Normalized baseline`, `Normalized comparison`, and `Normalized diff command`
- explicit note that subsequent phases run from the worktree
- the required `## TODO` heading from the scaffold

## Suggested Commands

Check branch:

```bash
git branch --show-current
```

Check ignore status:

```bash
git check-ignore -q .worktrees || git check-ignore -q worktrees
```

Create worktree:

```bash
git worktree add .worktrees/<run-id> -b recursive/<run-id>
```

## Setup Guidance

Run the setup command that matches the repo:

- Node.js: `npm install`
- Rust: `cargo build`
- Python: `pip install -r requirements.txt` or project-specific install
- Go: `go mod download`
- Maven: `mvn compile -q`
- Gradle: `./gradlew compileJava`
- .NET: `dotnet restore`

Then run the baseline test command appropriate to the project and record the result in `00-worktree.md`.

## Router State In Worktrees

Before delegated or routed work runs from an isolated worktree, verify the router files inside that same worktree:

```bash
test -f .recursive/config/recursive-router.json
test -f .recursive/config/recursive-router-discovered.json
```

```powershell
Test-Path .recursive/config/recursive-router.json
Test-Path .recursive/config/recursive-router-discovered.json
```

If the controller/source repo has a configured router policy or discovery inventory and the worktree lacks it, sync both files into the worktree before resolving or invoking routed roles. Preserve user edits to the worktree policy; when changing bindings, prefer `recursive-router-configure` over hand edits.

`recursive-router-discovered.json` is local discovery state and may be untracked. Its absence in a fresh worktree is expected, but it is still not safe to resolve an external role from stale assumptions. Refresh it with `python ./.recursive/scripts/recursive-router-probe.py --repo-root . --json` from the worktree, or copy the current inventory from the controller/source repo when that is the intended policy basis.

Record the router policy path, discovery path, validation/probe command, and resulting route decision in `00-worktree.md` or in the delegated action record before accepting routed work.

## Output Contract

Write the artifact to:

- `/.recursive/run/<run-id>/00-worktree.md`

Use feature branches named:

- `recursive/<run-id>`

## Routing Awareness

If this skill uses delegated review or any other routed external model to validate worktree setup, baseline verification, or branch safety, re-read:

- `/.recursive/config/recursive-router.json`
- `/.recursive/config/recursive-router-discovered.json`

immediately before choosing that CLI/model, and honor the routed policy or explicit fallback instead of hardcoding a reviewer model.

## Integration

- Invoke this skill before AS-IS analysis and planning.
- After Phase 0 is lock-valid, continue the run from the worktree context.
- Keep later phases, including `STATE.md`, `DECISIONS.md`, and memory updates, on the same feature branch until merge time.