mcpField
R
recursive-worktree

recursive-worktree

github.com/try-worksDevelopment13668 installsUpdated 14w ago
Repository

About recursive-worktree

recursive-worktree is a skill for setting up an isolated feature-branch worktree at the start of a recursive-mode run. It defines setup, baseline-test, and branch-safety checks that must be recorded before later phases begin.

Key features

  1. 01Create an isolated feature worktree
  2. 02Verify worktree location is ignored
  3. 03Run project setup and baseline tests
  4. 04Record branch and normalized diff basis
  5. 05Check router state in the worktree

Use cases

  1. 01Preparing a repository before Phase 1
  2. 02Isolating changes from the main branch
  3. 03Recording a clean or acknowledged test baseline

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/try-works/recursive-mode --skill recursive-worktree

After installing, type/recursive-worktreein Claude Code to confirm it loaded.

Bundled filesagents/openai.yaml

Details

From the project README

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:

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:

git branch --show-current

Check ignore status:

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

Create worktree:

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:

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

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.

Comments

Markdown supported