Ralph Merge Worktrees

Analyze completed Ralph worktree PRDs, build a dependency-aware merge queue, and sequentially squash-merge each branch into main — removing the worktree after each successful merge.

Overview

Ralph worktrees live at

.claude/worktrees/ralph/<feature>/

with PRDs at

scripts/ralph/prd.json

inside each worktree. A worktree is "completed" when every user story in its PRD has

passes: true

. This skill finds all completed worktrees, determines the safest merge order, presents the plan for approval, and then executes it one branch at a time.

Step 1: Scan and Identify Completed Worktrees

Read every

.claude/worktrees/ralph/*/scripts/ralph/prd.json

file. For each PRD:

Parse the JSON — extract
```
branchName
```
,
```
description
```
, and
```
userStories[]
```
A worktree is completed when ALL stories have
```
passes: true
```
Skip any worktree whose PRD has at least one story with
```
passes: false
```
Also skip worktrees that don't have a
```
prd.json
```
(malformed or empty)

If no completed worktrees are found, tell the user and stop.

Step 2: Analyze Each Completed Branch

For each completed worktree, gather merge intelligence:

bash

# From the main repo root, diff the branch against main
git diff main...<branchName> --stat
git diff main...<branchName> --name-only
git log main..<branchName> --oneline

Collect for each branch:

Files changed — the full list of modified/added/deleted files
Change categories — classify files into buckets:
- ```
terraform
```
  — anything under
```
terraform/
```
  (infra, resolvers, functions, lambda)
- ```
types
```
  — anything under
```
types/
```
- ```
graphql
```
  — anything under
```
app/graphql/
```
- ```
services
```
  — anything under
```
services/
```
- ```
composables
```
  — anything under
```
app/composables/
```
- ```
components
```
  — anything under
```
app/components/
```
- ```
pages
```
  — anything under
```
app/pages/
```
- ```
layouts
```
  — anything under
```
app/layouts/
```
- ```
content
```
  — anything under
```
content/
```
- ```
config
```
  — root config files (
```
nuxt.config.ts
```
  ,
```
terraform-scaffold.config.ts
```
  , etc.)
- ```
other
```
  — everything else
Commit count — number of commits on the branch
Story count — total user stories in the PRD
File count — total files changed
Overlap matrix — which files are touched by multiple branches (potential conflict zones)

Step 3: Build the Priority Queue

Rank branches for merge order using these heuristics (most important first):

3a. Dependency Layer Ordering

Merge bottom-up through the stack so downstream features inherit upstream changes:

Infrastructure first — branches that primarily touch
```
terraform/
```
,
```
types/
```
,
```
services/
```
,
```
config
```
(schema, tables, resolvers, types)
Data/API layer — branches focused on
```
app/graphql/
```
,
```
app/composables/
```
(client-side data plumbing)
UI layer last — branches primarily touching
```
app/components/
```
,
```
app/pages/
```
,
```
app/layouts/
```
,
```
content/
```

Determine the "primary layer" by whichever category has the most changed files. If a branch spans multiple layers, it belongs to the lowest layer it touches (infra > api > ui).

3b. Within the Same Layer

When two branches are in the same layer, break ties using:

Less file overlap first — branches that share fewer files with other pending branches get merged first (lower conflict risk after merge)
Smaller changeset first — fewer files changed = less risk, gets quick wins merged early, and the larger branch can rebase more easily if needed
Fewer commits first — proxy for scope/complexity

3c. Special Cases

If a branch only touches
```
content/
```
files (e.g., legal pages, markdown), it's very low-risk — can go anywhere in the queue, but default to early since it won't conflict with code changes
If a branch touches
```
terraform-scaffold.config.ts
```
or
```
terraform/envs/staging/main.tf
```
, prefer merging it early — other branches may have stale copies of these high-contention files

Step 4: Present the Merge Plan

Show the user the proposed merge queue in a clear table format:

Ralph Merge Queue — N completed branches ready

Priority | Branch                          | Stories | Files | Layer        | Reason
---------|--------------------------------|---------|-------|--------------|------------------
1        | ralph/legal-pages              | 6/6     | 8     | content      | Content-only, low risk
2        | ralph/post-creation            | 12/12   | 34    | infra+ui     | Core data model, merge early
3        | ralph/like-thread-post-comment  | 8/8     | 15    | infra+ui     | Depends on thread model
...

File overlap warnings:
- terraform/envs/staging/main.tf: touched by 3 branches (post-creation, chat-and-messaging, like-thread-post-comment)
- terraform/envs/staging/schema.graphql: touched by 4 branches

Proceed with merge queue? (y/n)

Wait for user confirmation before proceeding. If the user wants to reorder or skip branches, adjust the queue accordingly.

Step 5: Execute the Merge Queue

For each branch in the queue, in order:

5a. Pre-merge Check

bash

# Ensure main is clean and up to date
git checkout main
git status --porcelain

If there are uncommitted changes on main, stop and alert the user.

5b. Squash-Merge via /git-squash

Invoke the

/git-squash

skill with the branch name. This handles:

Pre-flight checks (branch exists, has diverged from main)
```
git merge --squash <branchName>
```
Delegates commit to
```
/git-commit
```
(Conventional Commits, Co-Authored-By trailer)
Post-merge verification
Local branch cleanup (
```
git branch -d/-D
```
)

If the squash-merge fails due to conflicts:

```
git merge --abort
```
Report which files conflicted
Skip this branch — move it to the end of the queue or remove it
Ask the user: "Branch X has conflicts. Skip it and continue with the next branch, or stop the queue?"
Continue or stop based on the user's answer

5c. Remove the Worktree

After a successful merge and branch deletion:

bash

# Remove the git worktree
git worktree remove .claude/worktrees/ralph/<feature-name>

# If worktree remove fails (dirty), force it since we already merged
git worktree remove --force .claude/worktrees/ralph/<feature-name>

Verify the worktree directory is gone. If the directory still exists after

git worktree remove

, it may need manual cleanup — warn the user but continue.

5d. Prune and Report

bash

git worktree prune

Log the result:

[1/N] ralph/legal-pages — merged and worktree removed
[2/N] ralph/post-creation — merged and worktree removed
[3/N] ralph/chat-and-messaging — SKIPPED (merge conflict in schema.graphql)
...

5e. Continue to Next Branch

Move to the next branch in the queue. Each subsequent merge benefits from the prior merges already being on main, which reduces drift.

Step 6: Final Summary

After processing the entire queue:

Ralph Merge Complete
--------------------
Merged:  5 branches
Skipped: 1 branch (conflicts)
Remaining worktrees: 3 (incomplete PRDs)

Skipped branches (need manual resolution):
- ralph/chat-and-messaging: conflict in terraform/envs/staging/schema.graphql

Remaining incomplete worktrees:
- ralph/follow-and-unfollow (4/10 stories)
- ralph/test-coverage (0/8 stories)
- ralph/implement-reporting (2/6 stories)

If any branches were skipped due to conflicts, suggest next steps:

Go into the skipped worktree
```
git rebase main
```
to incorporate the newly merged changes
Resolve conflicts
Re-run
```
/ralph-merge-worktrees
```
to merge the remaining completed branches

Important Notes

Always get user confirmation before starting the merge queue — this is a destructive operation (worktree removal)
Each merge builds on the last — if branch 2 conflicts, branches 3+ might have different conflict profiles than predicted. Re-check is automatic since we run
```
/git-squash
```
which does pre-flight
The skill reads PRD files from the worktree directories, not from main — each worktree has its own copy
Worktree paths use the feature name without the
```
ralph/
```
prefix:
```
.claude/worktrees/ralph/post-creation/
```
for branch
```
ralph/post-creation
```
After all merges complete, run
```
bun run lint
```
on main to verify the combined codebase is healthy
Quote file paths with spaces in all git/bash commands (the project path contains spaces)

ralph-merge-worktrees

NPX Install

Tags

SKILL.md Content

Ralph Merge Worktrees

Overview

Step 1: Scan and Identify Completed Worktrees

Step 2: Analyze Each Completed Branch

Step 3: Build the Priority Queue

3a. Dependency Layer Ordering

3b. Within the Same Layer

3c. Special Cases

Step 4: Present the Merge Plan

Step 5: Execute the Merge Queue

5a. Pre-merge Check

5b. Squash-Merge via /git-squash

5c. Remove the Worktree

5d. Prune and Report

5e. Continue to Next Branch

Step 6: Final Summary

Important Notes