Parallel Agent Workflow Skill

Parallel Agent Workflow

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

How It Works

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

Instructions

Phase 1: Planning

Identify the work units - What needs to be done?
Determine agent count:
- If user specifies: Use that count
- If not specified: Auto-determine based on independent work units
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?"
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:

Create worktree:

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

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

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
Launch agents concurrently using Task tool with multiple invocations in single message
Monitor results:
- Agent fails: Surface reason in conversation
- Agent succeeds: Note commit hash

Phase 3: Staged Merges

Merge in stages based on logical grouping:

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
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

Work isolation: Each agent should modify different files/components
Logical grouping: Merge related work together in stages
Test coverage: Always verify before and after changes
Clear naming: Use descriptive worktree and branch names
Conflict resolution: Let agents resolve conflicts automatically when possible
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

Agent Skills: Parallel Agent Workflow

Install this agent skill to your local

Skill Files