Skip to content

pr-flow: always start work in a git worktree #2661

Closed

Description

@cliffhall

Problem

pr-flow step 2 (Branch) currently treats a worktree as optional:

Working in a git worktree is fine and often preferable.

In practice this repo is worked by several concurrent agent sessions on one machine (the premise behind #2338, #2339, #2473). When a session cuts its feature branch in the primary checkout, it switches the branch out from under any other session using that checkout, and uncommitted work, build output and node_modules state from one task leak into another.

Proposal

Make "start work in a worktree" the default in pr-flow, not an aside:

  • Step 2 (Branch): create the feature branch as a new worktree cut from the target base, e.g.
    git fetch origin
    git worktree add ../inspector-<issue> -b v2/fix/<issue>-<slug> origin/v2/main
    cd ../inspector-<issue> && npm install
    (or the harness's EnterWorktree where available), and do all subsequent work there.
  • Keep the existing ⚠️ that a worktree needs a real npm install, not a symlinked node_modules — promote it into the recipe itself rather than a trailing note.
  • Closing out (after merge): add removing the worktree (git worktree remove) and deleting the local branch.
  • Update the one-line rule in AGENTS.md → Issue-driven Work Style ("When work begins, assign the issue to yourself, create a feature branch…") to say the branch is created in a worktree, so the rule and the recipe agree.
  • Cross-check local-dev / pre-push-gate, which already document worktree hazards, so they point at the same recipe rather than describing a second one.

Acceptance

  • pr-flow step 2 creates the branch in a new worktree by default, with the npm install step inline.
  • Close-out step removes the worktree.
  • AGENTS.md rule updated to match.
  • npm run verify:skills passes; re-run skills:eval for pr-flow if its description changes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationv2Issues and PRs for v2

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions