Worktree Feature Execution

Purpose

Execute feature delivery in isolated git worktrees with consistent automation for branch creation, synchronization, pull request creation, merge safety, and cleanup. Use this skill to reduce branch switching, minimize cross-feature interference, and maintain a clean integration path into main.

Harness Contract

Read project instructions from AGENTS.md first. Read project.yaml second when present. Prefer AGENTS-defined conventions over CLAUDE-specific conventions.

Use this directory resolution priority unless the project explicitly overrides it:

1. Existing .worktrees/
2. Existing worktrees/
3. Config value from project.yaml
4. Default .worktrees/

For project-local roots (.worktrees/ or worktrees/), verify ignore coverage before worktree creation. Add ignore entries when missing.

Operating Principles

• Keep one feature per worktree and one branch per worktree.
• Keep branch names predictable and slug-safe.
• Keep PRs small and short-lived.
• Rebase frequently to reduce conflict depth.
• Run quality checks before PR creation and before merge.
• Avoid destructive git actions.

Command Resources

Use bundled scripts in scripts/ for deterministic execution:

• scripts/preflight-check.sh - repository, branch, remote, and gh readiness checks.
• scripts/create-worktree.sh - branch + worktree creation with ignore safeguards.
• scripts/sync-worktree.sh - fetch + rebase branch onto base branch.
• scripts/open-pr.sh - push and create or reuse pull requests.
• scripts/merge-pr.sh - merge pull request with checks and queue support.
• scripts/cleanup-worktree.sh - safe worktree removal and prune.

Standard Workflow

1) Preflight

Run:

bash .agents/skills/worktree-feature-execution/scripts/preflight-check.sh

Verify:

• Current directory belongs to a git repository.
• Base branch can be resolved.
• origin remote exists.
• gh is installed and authenticated.

If authentication or permissions fail, stop and report the blocking condition.

2) Create Isolated Worktree

Run:

bash .agents/skills/worktree-feature-execution/scripts/create-worktree.sh \
  --feature "add billing retries" \
  --base "current-branch" \
  --prefix "feat"

Behavior:

• Resolve base branch from current branch when --base current-branch.
• Resolve worktree root using priority order.
• Ensure root is gitignored when local to repository.
• Create feat/<slug> branch if missing, or reuse existing branch.
• Create worktree path <root>/<slug>.

3) Implement Feature

Perform implementation inside the created worktree path only. Keep scope aligned with the feature statement.

Recommended checks:

• Type checks
• Unit/integration tests
• Build command

Record notable changes and compatibility concerns for PR body.

4) Sync With Base Branch

Run in the worktree:

bash .agents/skills/worktree-feature-execution/scripts/sync-worktree.sh \
  --base "main"

Behavior:

• Fetch remote updates.
• Rebase feature branch on top of latest base branch.
• Stop on conflicts and report exact conflict files.

5) Open Pull Request

Run in the worktree:

bash .agents/skills/worktree-feature-execution/scripts/open-pr.sh \
  --base "main" \
  --title "feat: add billing retry policy" \
  --body-file ".git/PR_BODY.md"

Behavior:

• Push branch with upstream tracking if needed.
• Reuse open PR when one already exists.
• Create PR when missing.
• Return PR URL.

6) Merge Pull Request

Run:

bash .agents/skills/worktree-feature-execution/scripts/merge-pr.sh \
  --pr "<url-or-number>" \
  --method "squash" \
  --queue

Behavior:

• Validate merge method.
• Confirm checks status.
• Queue merge (--auto) when requested.
• Delete remote branch after merge when supported.

7) Cleanup

Run:

bash .agents/skills/worktree-feature-execution/scripts/cleanup-worktree.sh \
  --path ".worktrees/add-billing-retries"

Behavior:

• Refuse cleanup when uncommitted changes exist unless --force.
• Remove worktree and prune stale metadata.

Multi-Agent Coordination

Use one worktree per agent. Assign explicit ownership boundaries by directory, module, or capability.

Execution order:

1. Merge foundational PRs first.
2. Rebase dependent PRs after each upstream merge.
3. Re-run checks after every rebase.
4. Merge dependent PRs only after compatibility verification.

For shared contracts (API/schema/event payloads), include compatibility notes in PR body and require contract tests.

Edge Cases

Detached HEAD

Resolve base branch using origin/HEAD fallback. Stop when neither current branch nor remote default branch can be resolved.

Existing Branch Already Checked Out

If branch is already attached to another worktree, stop and select a new branch name or reuse that worktree.

Worktree Path Exists

Refuse creation when target path exists and is non-empty.

Missing Ignore Rule

Append missing root ignore entry to .gitignore before creating local worktree roots.

Diverged Branches

Require rebase and conflict resolution before PR creation.

Existing PR

Return existing PR URL instead of creating duplicate PR.

CI Failures

Do not merge. Report failed checks and keep worktree active for remediation.

Merge Queue Enabled

Use --queue flow and avoid direct merge bypass.

Permission Errors

Stop and report required gh scope or repository role.

Red Flags

Never:

• Run git reset --hard or force-push to main.
• Merge with known failing checks.
• Delete worktree containing uncommitted work without explicit force signal.
• Create worktrees in unignored project-local directories.

Always:

• Run preflight before worktree creation.
• Run sync before PR and before merge.
• Surface PR URL and merge status.
• Clean up merged worktrees.

Additional Resources

Reference files:

• references/branch-naming.md
• references/conflict-playbook.md
• references/merge-policy.md