Skip to content

feat: add worktree isolation to /implement, /validate, and /release#566

Open
frosty-geek wants to merge 2 commits into
BugRoger:mainfrom
frosty-geek:feature/worktree-isolation
Open

feat: add worktree isolation to /implement, /validate, and /release#566
frosty-geek wants to merge 2 commits into
BugRoger:mainfrom
frosty-geek:feature/worktree-isolation

Conversation

@frosty-geek
Copy link
Copy Markdown

@frosty-geek frosty-geek commented Apr 22, 2026

Summary

  • /implement now creates a dedicated git worktree at .claude/worktrees/<epic-slug> before dispatching the taskplanner, enabling parallel feature implementation
  • /validate now enters the matching worktree before running tests, so it validates the correct code even when invoked from a fresh session
  • /release now enters the matching worktree before generating release notes and dispatching the retro context walker, so the retro reads/writes the feature branch's state and its edits land in the squash-merge
  • Moved the TRANSITION BOUNDARY callout in /release Phase 3 from above Step 2 to above Step 3 — Step 2 (Commit to Feature Branch) still runs in the worktree; the actual transition to the main repo is at Step 3 (Squash Merge to Main)

Closes #564

Changes

plugin/skills/implement/SKILL.md

  • Updated working directory isolation principle to reflect skill-managed worktrees
  • Added Phase 0: Worktree Setup with existing-worktree check (0a) and create-worktree (0b) steps

plugin/skills/validate/SKILL.md

  • Added Step 0: Enter Worktree to Phase 0 (Pre-Execute)
  • Checks git worktree list, enters matching worktree, or blocks if none exists

plugin/skills/release/SKILL.md

  • Added Phase 0: Pre-Execute with Step 0: Enter Worktree, mirroring /validate's pattern
  • Without this, /release invoked from a fresh session at the repo root runs Phase 1 and Phase 3 Step 1 (retro context walker) from the main repo, not the worktree. The retro is dispatched as a general-purpose subagent that inherits the parent's cwd; with no Phase 0 entry, it reads main's .beastmode/artifacts/* and writes to main's .beastmode/context/* — the worktree's edits never make it through the squash-merge
  • Moved the TRANSITION BOUNDARY callout from above Phase 3 Step 2 to above Step 3 (Step 2 is the feature-branch checkpoint commit, which still runs in the worktree; only Step 3+ navigates to the main repo via explicit cd)

Context

Without these changes, running /implement on two features simultaneously corrupts the working tree, running /validate in a new session tests main instead of the feature branch, and the /release retro context walker silently writes to whichever directory the session happens to be in (often main, where the edits get clobbered by the subsequent squash-merge from the worktree). All three were discovered while running parallel beastmode sessions on a real project.

Test plan

  • Run /implement on a feature — verify worktree is created at .claude/worktrees/<epic-slug>
  • Run /implement on a second feature in parallel — verify each gets its own worktree
  • Run /validate in a fresh session — verify it finds and enters the worktree
  • Run /validate with no worktree — verify it blocks with a clear message
  • Run /release in a fresh session — verify it enters the worktree before the retro fires
  • Run /release with no worktree — verify it blocks with a clear message
  • Inspect the squash-merge commit — verify retro context edits (e.g., updates to .beastmode/context/*.md) are present on main

frosty-geek and others added 2 commits April 22, 2026 17:46
/implement now creates a dedicated git worktree at
.claude/worktrees/<epic-slug> before dispatching the taskplanner.
This keeps the main repo clean and enables parallel feature
implementation across multiple sessions.

/validate now enters the matching worktree before running tests,
so it validates the feature branch code even when invoked from
a fresh session at the repo root.

The worktree persists until /release completes the squash-merge.
Without this, /release invoked from a fresh session at the repo root
runs Phase 1 and Phase 3 Step 1 (retro context walker) from the main
repo, not the worktree. The retro is dispatched as a general-purpose
subagent that inherits the parent's cwd; with no Phase 0 entry, it
reads main's .beastmode/artifacts/* and writes to main's
.beastmode/context/* — the worktree's edits never make it through the
squash-merge.

Mirrors the Phase 0 "Enter Worktree" step that /validate already has,
with the same BLOCKED guard if no worktree exists.

Also moves the TRANSITION BOUNDARY callout from above Step 2 to above
Step 3. Step 2 ("Commit to Feature Branch") still operates from the
worktree — the actual transition to the main repo happens in Step 3
("Squash Merge to Main") via explicit cd.
@frosty-geek frosty-geek changed the title feat: add worktree isolation to /implement and /validate feat: add worktree isolation to /implement, /validate, and /release May 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Worktree isolation for /implement and /validate

1 participant