name	merge-agent-work
description	Merge agent work from agent branch to task branch with validation
allowed-tools	Bash, Read

Merge Agent Work Skill

Purpose: Safely merge agent work from agent branch to task branch with proper validation and state tracking.

Performance: Reduces merge errors, ensures work properly integrated

When to Use This Skill

✅ Use merge-agent-work When:

Agent has completed work (status.json shows "completed")
Need to merge agent branch to task branch
Want validation that merge succeeded
Coordinating multiple agent merges

❌ Do NOT Use When:

Agent still working (status.json shows "in_progress")
Agent encountered errors (status.json shows "failed")
Conflicts expected (need manual resolution)
Merging to main (use git-merge-linear skill instead)

What This Skill Does

1. Verifies Agent Completion

# Check agent status
STATUS=$(jq -r '.status' /workspace/tasks/{task}/agents/{agent}/status.json)
if [ "$STATUS" != "completed" ]; then
  echo "Agent not completed: $STATUS"
  exit 1
fi

2. Switches to Task Worktree

# Must merge in task worktree
cd /workspace/tasks/{task-name}/code

3. Merges Agent Branch

# Merge agent branch to task branch
git merge {task-name}-{agent} --no-ff --no-edit

4. Validates Merge

# Verify merge succeeded
- No conflicts
- Files added/modified as expected
- Build still succeeds (optional)
- Commit created

5. Updates State Tracking

# Update task.json
jq '.agents.{agent}.merged = true | .agents.{agent}.merge_time = "timestamp"' \
  task.json > tmp.json
mv tmp.json task.json

Usage

Basic Agent Merge

# After architect agent completes
TASK_NAME="implement-formatter-api"
AGENT="architect"

/workspace/main/.claude/scripts/merge-agent-work.sh \
  --task "$TASK_NAME" \
  --agent "$AGENT"

With Build Validation

# Merge and validate build succeeds
TASK_NAME="implement-formatter-api"
AGENT="tester"

/workspace/main/.claude/scripts/merge-agent-work.sh \
  --task "$TASK_NAME" \
  --agent "$AGENT" \
  --validate-build true \
  --build-command "mvn test"

Merge Multiple Agents

# Merge all completed agents
TASK_NAME="implement-formatter-api"

for agent in architect tester formatter; do
  STATUS=$(jq -r '.status' /workspace/tasks/$TASK_NAME/agents/$agent/status.json)
  if [ "$STATUS" = "completed" ]; then
    /workspace/main/.claude/scripts/merge-agent-work.sh \
      --task "$TASK_NAME" \
      --agent "$agent"
  fi
done

Safety Features

Precondition Validation

✅ Verifies task exists
✅ Confirms agent completed successfully
✅ Checks we're in correct worktree
✅ Validates no uncommitted changes

Merge Validation

✅ Detects merge conflicts
✅ Confirms merge commit created
✅ Validates file changes reasonable
✅ Optional build/test validation

Error Handling

On any error:

Aborts merge if conflicts
Reports which validation failed
Returns JSON with error details
Leaves repository in consistent state

Recovery: Can retry after fixing issues

Workflow Integration

Multi-Agent Coordination

IMPLEMENTATION state: All agents working in parallel
  ↓
Agent 1 completes (status: completed)
  ↓
[merge-agent-work: Agent 1 → task branch]
  ↓
Agent 2 completes (status: completed)
  ↓
[merge-agent-work: Agent 2 → task branch]
  ↓
Agent 3 completes (status: completed)
  ↓
[merge-agent-work: Agent 3 → task branch]
  ↓
All agents merged, transition to VALIDATION

Iterative Agent Work

Agent implements feature (round 1)
  ↓
[merge-agent-work: Agent → task]
  ↓
Validation finds issues
  ↓
Re-invoke agent for fixes (round 2)
  ↓
[merge-agent-work: Agent → task]
  ↓
Validation passes

Output Format

Script returns JSON:

{
  "status": "success",
  "message": "Agent work merged successfully",
  "task_name": "implement-formatter-api",
  "agent_name": "architect",
  "agent_branch": "implement-formatter-api-architect",
  "task_branch": "implement-formatter-api",
  "merge_commit": "abc123def456",
  "files_changed": 15,
  "insertions": 450,
  "deletions": 23,
  "build_validation": "passed",
  "timestamp": "2025-11-11T12:34:56-05:00"
}

Merge Strategies

No Fast-Forward (Default)

# Creates merge commit (preserves agent work history)
git merge {agent-branch} --no-ff

# Benefit: Clear history of agent contributions
# Result: Merge commit shows what agent did

Fast-Forward (Optional)

# Linear history (no merge commit)
git merge {agent-branch} --ff-only

# Benefit: Cleaner history
# Risk: Loses agent contribution visibility

Squash (NOT Recommended)

# Squashes all agent commits into one
git merge {agent-branch} --squash

# Problem: Loses agent work history
# Use case: Only if agent made many tiny commits

Conflict Resolution

Automatic Resolution

# For simple conflicts, skill can auto-resolve:
- Both added same file → Use agent's version
- Both modified same file → Use agent's version (if main agent made no changes)

Manual Resolution Required

# Skill reports conflict, main agent must resolve:
- Both modified same lines
- Complex merge conflicts
- Semantic conflicts (code compiles but behavior conflicts)

Validation Levels

Minimal (Default)

# Quick validation:
- Merge completed
- No conflicts
- Commit created

Standard

# More thorough:
- Minimal validation
- File count reasonable (not empty merge)
- Diff size reasonable (not huge merge)

Full

# Complete validation:
- Standard validation
- Build succeeds
- Tests pass
- No Checkstyle/PMD violations

Related Skills

gather-requirements: Invokes agents before merge needed
task-cleanup: Cleans up agent branches after merge
git-merge-linear: Merges task to main (different from agent to task)

Troubleshooting

Error: "Agent not completed"

# Check agent status
jq -r '.status' /workspace/tasks/{task}/agents/{agent}/status.json

# Possible statuses:
# - "in_progress" → Wait for completion
# - "failed" → Investigate agent error
# - "not_started" → Agent never invoked

# Wait for completion or re-invoke agent

Error: "Merge conflicts detected"

# View conflicts
cd /workspace/tasks/{task-name}/code
git status

# Resolve manually:
# 1. Edit conflicted files
# 2. Stage resolved files: git add <file>
# 3. Complete merge: git commit
# 4. Update state tracking

Error: "Build fails after merge"

# Merge succeeded but build broken

# Options:
# 1. Revert merge: git reset --hard HEAD~1
# 2. Re-invoke agent with fix requirements
# 3. Main agent fixes in VALIDATION state (if compilation error)

# After fix, retry merge

Error: "Wrong worktree"

# Must be in task worktree, not agent worktree

# Verify current directory
pwd
# Should be: /workspace/tasks/{task-name}/code
# NOT: /workspace/tasks/{task-name}/agents/{agent}/code

# Switch to task worktree
cd /workspace/tasks/{task-name}/code

Common Patterns

Pattern 1: Serial Merges

# Merge agents one at a time, validate each
merge architect → validate → merge tester → validate → merge formatter

Pattern 2: Batch Merge

# Merge all completed agents, then validate once
merge architect → merge tester → merge formatter → validate all

Pattern 3: Incremental Integration

# Merge agent, test, fix if needed, repeat
merge agent → test → if fail: fix → merge again

Implementation Notes

The merge-agent-work script performs:

Validation Phase
- Check task exists
- Verify agent completed
- Confirm correct worktree
- Validate no uncommitted changes
Merge Preparation Phase
- Switch to task worktree
- Verify task branch checked out
- Update working directory to latest
Merge Execution Phase
- Execute git merge command
- Capture merge output
- Detect conflicts
Merge Validation Phase
- Verify merge commit created
- Check file changes reasonable
- Optional: run build/tests
- Optional: check style compliance
State Update Phase
- Update task.json (agent merged)
- Record merge commit SHA
- Update merge timestamp
Reporting Phase
- Return status (success/failure)
- List files changed
- Provide merge statistics
- Report validation results

Install Skill

SKILL.md