Git Worktree Flow

If The Input Is A Poor Match

• Route to analyze-requirements when the intended behavior is still unsettled.
• Route to execute-work when the work is small enough that no explicit Git coordination is needed.
• Route to completion-gate when the implementation is already integrated and only needs readiness assessment.
• Ask the user only if repository policy, branch protection, or release constraints materially affect the landing strategy and cannot be inferred from context.

Process

1. Inspect the current repository state, base branch, and any active work on the same topic.
2. Choose a single integration base for the topic.
3. Create one active branch per workstream.
4. Prefer one writable worktree or equivalent isolated checkout per active branch.
5. Record branch ownership, base branch, and the expected integration order.
6. Require small coherent commits at natural checkpoints, especially before risky refactors, rebases, or handoffs.
7. Sync each workstream with its base before handoff and before final integration.
8. Integrate shared foundations first, then rebase or merge dependent branches in order.
9. Run final verification on the integration branch or exact integration commit, not on child branches alone.
10. After the integrated state is ready, use development-branch-finish for the landing choice when branch closure is still pending.
11. Clean up merged branches and worktrees when they are no longer needed.

Output Structure

When writing the flow inline or into a plan, include:

• Integration base
• Workstream-to-branch mapping
• Worktree or checkout mapping
• Commit cadence or handoff checkpoints
• Sync policy
• Integration order
• Final verification point

Escalate To A Human When

• Repository policy around force-push, rebase, merge, or protected branches is unclear and changes the landing strategy.
• The work requires an expensive migration, release train coordination, or a rollback policy that is not already defined.
• Parallel work would require multiple agents to edit the same branch or checkout concurrently.

Hard Rules

• Do not let multiple active writers share one worktree or checkout.
• Do not let separate workstreams share one active write branch.
• Prefer worktrees for parallel development; if unavailable, use equivalent isolated checkouts and say so.
• Commit before risky edits and before handoff.
• Sync from the base before integration instead of merging stale work blindly.
• Resolve conflicts in the owning branch or designated integration branch, not by overwriting another workstream.
• Final verification and completion claims must reference the exact integrated state.
• Landing, preservation, or discard decisions for a topic branch belong to development-branch-finish, not to mid-execution Git coordination.
• Do not use force-push or history rewriting on shared branches unless repository policy explicitly allows it.