merge-protocol

Merge Protocol

Overview

Coordinate the final step of development: moving finished work into the mainline or disposing of it cleanly.

Core principle: Validate first, present choices, execute the selected path, then tidy up.

Announce at start: "I'm using the merge-protocol skill to finalize this work."

Prime Directive

NO INTEGRATION WITHOUT PASSING TESTS

No exceptions. No workarounds. No shortcuts.

When to Use

• All planned implementation work is done and committed
• The test suite runs green on the current branch
• Review feedback (if solicited) has been resolved
• You are ready to land, shelve, or abandon the branch
• Following delegated-execution or task-runner completion
• When a workspace-isolation branch needs teardown

Cognitive Traps

Rationalization	Truth
"Tests were green an hour ago, no need to re-run"	Any commit since then invalidates stale results. Re-verify now.
"Merging is mechanical — nothing breaks"	Conflicts and integration regressions are real. Test the merged state.
"I'll remove the worktree tomorrow"	Orphaned worktrees pile up and create confusion. Remove them immediately.
"Let me just merge — skip the menu"	Always present all four paths. The human picks the workflow.
"Abandonment is obvious — no confirmation needed"	Destroying work permanently demands explicit typed confirmation. Always.

The Workflow

Phase 1: Validate the Suite

Run the full test suite before anything else:

# Execute the project's test runner
npm test / cargo test / pytest / go test ./...

On failure:

Suite failures detected (<N> failing). Resolution required before proceeding:

[Display failing tests]

Integration cannot continue until the suite is green.

Halt here. Do not advance to Phase 2.

On success: Proceed to Phase 2.

Phase 2: Identify the Trunk Branch

# Determine the ancestor branch
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Or confirm: "This branch diverged from main — correct?"

Phase 3: Offer Integration Paths

Present exactly these four choices:

Work is complete and verified. Select an integration path:

1. Merge into <trunk> locally
2. Push and open a Pull Request
3. Leave the branch untouched (I'll handle it myself)
4. Abandon this work entirely

Which path?

Keep it terse — no extra commentary.

Phase 4: Execute the Selected Path

Path 1: Local Merge

# Switch to trunk
git checkout <trunk>

# Sync with remote
git pull

# Integrate the feature branch
git merge <feature-branch>

# Validate the merged state
<test command>

# Remove the merged branch
git branch -d <feature-branch>

Then: Proceed to Phase 5 (Worktree Teardown)

Path 2: Pull Request

# Push the branch upstream
git push -u origin <feature-branch>

# Open the PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets describing the changes>

## Verification Steps
- [ ] <checklist items>
EOF
)"

Then: Proceed to Phase 5 (Worktree Teardown)

Path 3: Defer

Report: "Branch preserved. Worktree remains at ."

Do not tear down the worktree.

Path 4: Abandon

Require explicit confirmation:

Permanent deletion warning:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'abandon' to proceed.

Wait for the exact word.

After confirmation:

git checkout <trunk>
git branch -D <feature-branch>

Then: Proceed to Phase 5 (Worktree Teardown)

Phase 5: Worktree Teardown

Applies to Paths 1, 2, and 4:

Detect if the current branch lives in a worktree:

git worktree list | grep $(git branch --show-current)

If so:

git worktree remove <worktree-path>

Path 3: Worktree stays intact.

Decision Matrix

Path	Merges	Pushes	Keeps Worktree	Removes Branch
1. Local merge	Yes	No	No	Yes
2. Pull request	No	Yes	Yes	No
3. Defer	No	No	Yes	No
4. Abandon	No	No	No	Yes (force)

Frequent Errors

Skipping validation

• Consequence: Broken code lands on trunk, failing PR created
• Correction: Always verify the suite before presenting paths

Open-ended prompting

• Consequence: "What now?" leads to ambiguity and stalling
• Correction: Present exactly four structured paths

Premature worktree removal

• Consequence: Destroys workspace needed for PR or deferred work
• Correction: Only tear down worktrees for Paths 1 and 4

Silent abandonment

• Consequence: Work deleted without the human's awareness
• Correction: Require typed "abandon" before any destructive action

Guardrails

Prohibited:

• Proceeding when tests fail
• Merging without validating the integrated result
• Deleting branches without explicit confirmation
• Force-pushing unless the human specifically asks

Mandatory:

• Run suite before presenting paths
• Present exactly four options
• Obtain typed confirmation for Path 4
• Tear down worktree only for Paths 1 and 4

Integration

Invoked by:

• godmode:delegated-execution (final step) — After all delegated tasks finish
• godmode:task-runner (final step) — After all execution batches complete

Complements:

• godmode:workspace-isolation — Tears down the worktree created by that skill