Parallel Agent Workflow

Execute multi-agent refactoring, feature development, or parallel work using git worktrees to prevent conflicts.

How It Works

1. •Split work across N agents, each in isolated git worktree
2. •Agents work independently on different components/files
3. •Merge in stages - combine related work into logical groups
4. •Final merge - all work combined into single branch

Instructions

Phase 1: Planning

1. •Identify the work units - What needs to be done?
2. •Determine agent count:
   • •If user specifies: Use that count
   • •If not specified: Auto-determine based on independent work units
3. •Ask for missing requirements if not in environment:
   • •Setup script (if dev-setup doesn't exist): "What command sets up dependencies?"
   • •Test command (if unknown): "What command verifies the build?"
4. •Create merge strategy:
   • •Group related work units logically
   • •Plan merge stages (N agents → M groups → 1 final)
   • •Example: 6 agents → 2 groups → 1 final

Phase 2: Execute Agent Work

For each agent:

1. •

   Create worktree:

   bash

   # Pattern: {project}@{branch-name}
   git worktree add ../{project}@{work-unit-name} -b {branch-name}
   

   • •CRITICAL: If worktree creation fails → STOP IMMEDIATELY, report error
2. •

   Agent instructions must include:

   • •cd into worktree
   • •Run setup script (or dev-setup if exists)
   • •Run test command BEFORE changes
   • •Do the work
   • •Run test command AFTER changes
   • •Commit changes
   • •Remove worktree
3. •

   Launch agents concurrently using Task tool with multiple invocations in single message

4. •

   Monitor results:

   • •Agent fails: Surface reason in conversation
   • •Agent succeeds: Note commit hash

Phase 3: Staged Merges

Merge in stages based on logical grouping:

1. •

   Stage 1: Merge related work into group branches

   • •Create worktree for each group
   • •Merge related branches
   • •Merge conflicts: Agent resolves automatically, surfaces resolution in output
   • •Run test command to verify merge
   • •Remove worktree
2. •

   Stage N: Final merge

   • •Create final worktree
   • •Merge all group branches
   • •Run test command
   • •Remove worktree

Phase 4: Completion

Report to user:

• •Final branch name
• •Final commit hash
• •Summary of all changes merged
• •Any conflicts that were resolved
• •Any failures that occurred

DO NOT create PR - just report the branch.

Worktree Naming Convention

{project-dir}@{descriptive-name}

Examples:

• •iac-lockin@headscale-refactor
• •myapp@feature-auth
• •webapp@fix-api-bug

Merge Strategy Examples

Example 1: Component Refactoring (6 → 2 → 1)

Stage 1: 6 agents work independently
  - Agent 1: Refactor ComponentA → branch: refactor/component-a
  - Agent 2: Refactor ComponentB → branch: refactor/component-b
  - Agent 3: Refactor ComponentC → branch: refactor/component-c
  - Agent 4: Refactor ComponentD → branch: refactor/component-d
  - Agent 5: Refactor ComponentE → branch: refactor/component-e
  - Agent 6: Refactor ComponentF → branch: refactor/component-f

Stage 2: 2 merge agents (logical grouping)
  - Merge Agent 1: Combine A+B+C → branch: refactor/merge-group-1
  - Merge Agent 2: Combine D+E+F → branch: refactor/merge-group-2

Stage 3: 1 final merge agent
  - Final Merge: Combine group-1 + group-2 → branch: refactor/final

Example 2: Feature Development (4 → 1)

Stage 1: 4 agents work independently
  - Agent 1: Backend API → branch: feature/backend-api
  - Agent 2: Frontend UI → branch: feature/frontend-ui
  - Agent 3: Database migrations → branch: feature/db-migrations
  - Agent 4: Tests → branch: feature/tests

Stage 2: 1 final merge agent
  - Final Merge: All branches → branch: feature/complete

Error Handling

Critical Failures (STOP)

• •Worktree creation fails
• •Setup script not found and user doesn't provide one
• •Test command not found and user doesn't provide one

Recoverable Issues (Agent handles)

• •Merge conflicts → Agent resolves, surfaces in output
• •Test failures → Agent reports, surfaces reason
• •Code errors → Agent fixes or reports

Template Agent Prompt

You are working on {WORK_DESCRIPTION}.

## Setup Instructions

1. **Create git worktree**:
   - Worktree path: `../{PROJECT}@{WORK_NAME}`
   - Branch: `{BRANCH_NAME}`
   - Command: `git worktree add ../{PROJECT}@{WORK_NAME} -b {BRANCH_NAME}`

2. **Setup worktree**:
   - cd into worktree
   - Run: `{SETUP_COMMAND}`
   - Run: `{TEST_COMMAND}` to verify initial state

3. **Do the work**:
   {SPECIFIC_WORK_INSTRUCTIONS}

4. **Verify**:
   - Run: `{TEST_COMMAND}` to verify changes
   - If tests fail: Fix issues before committing

5. **Finalize**:
   - Commit: "{COMMIT_MESSAGE}"
   - Remove worktree: `git worktree remove ../{PROJECT}@{WORK_NAME}`

## Important
- If worktree creation fails: STOP and report error
- If merge conflicts: Resolve them and document resolution
- If tests fail: Report failure reason with details

Return: Summary, files modified, commit hash, any issues.

Best Practices

1. •Work isolation: Each agent should modify different files/components
2. •Logical grouping: Merge related work together in stages
3. •Test coverage: Always verify before and after changes
4. •Clear naming: Use descriptive worktree and branch names
5. •Conflict resolution: Let agents resolve conflicts automatically when possible
6. •Status reporting: Surface all issues in conversation for user visibility

Version History

• •v1.0.0 (2025-11-09): Initial version based on component refactoring workflow