Skip to content

Worktree isolation for /implement and /validate #564

@frosty-geek

Description

@frosty-geek

Problem

/implement currently relies on the CLI to provide the working directory and does not manage worktrees. The guiding principle states: "the CLI provides the working directory; skills don't manage worktrees."

In practice, the CLI does not create worktrees either. This means:

  1. Parallel features collide. Two /implement sessions running simultaneously write to the same working tree, corrupting each other's files and commits.
  2. /validate in a new session tests the wrong code. When implement-to-validate is auto, validate runs in the same session (inside the worktree if one exists). But when /validate is invoked manually in a fresh session, it starts at the repo root on main — running tests against main's code, not the feature branch.

Proposed Solution

/implement: Create and enter a worktree

Add a Phase 0: Worktree Setup before the taskplanner dispatch:

  1. Check git worktree list for an existing .claude/worktrees/<epic-slug> (handles session resume)
  2. If not found, create one: git worktree add .claude/worktrees/<epic-slug> -b feat/<epic-slug>
  3. Enter it via EnterWorktree with the path

All subsequent work runs inside the worktree. The main repo working directory is never touched.

/validate: Enter the existing worktree

Add a Step 0: Enter Worktree to Phase 0 (Pre-Execute):

  1. Check git worktree list for .claude/worktrees/<epic-slug>
  2. If found and not already inside it, enter via EnterWorktree
  3. If not found, STOP with a message directing the user to run /implement first

Why this matters

  • Enables parallel feature implementation across multiple Claude sessions
  • Prevents silent data corruption from concurrent git add -A on the same tree
  • Makes /validate safe to invoke from a cold session
  • The worktree persists until /release completes the squash-merge (existing behavior)

Reference implementation

See feature/worktree-isolation on the fork — minimal patch to implement/SKILL.md and validate/SKILL.md.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions