Parallel Features

---
name: parallel-features
description: |
  Workflow for parallel development on a feature branch with multiple Claude Code instances.
  Each worker operates on an isolated branch and merges into the main feature branch upon completion.
  Use when CLAUDE.md specifies parallel work, or when multiple Claude instances must collaborate
  on the same feature without conflicts.
---

# Parallel Features Workflow

This skill enables multiple Claude Code instances to work simultaneously on a shared feature
without stepping on each other's changes. Each worker gets an isolated branch and merges
back when done.

## Prerequisites

**REQUIRED**: You must know the feature branch name before proceeding.

If no feature branch is specified, **STOP** and ask the user:
> "What is the feature branch name?"

Without a feature branch name, this workflow cannot proceed.

---

## Phase 1: Session Initialization

**First action**: Generate your unique worker ID.

```bash
openssl rand -hex 8
```

Store the output as your `WORKER_UUID` (e.g., `a3f8b2c7`). This UUID identifies your session
for the entire workflow. You will use it in branch names and commit messages.

---

## Phase 2: Worker Branch Creation

Once you have the feature branch name and your UUID, create your isolated worker branch.

### Step 2.1: Fetch latest from feature branch

```bash
git fetch origin
```

### Step 2.2: Checkout the feature branch

```bash
git checkout feature/{feature-name}
```

Replace `{feature-name}` with the actual feature name (e.g., `checkout-redesign`).

### Step 2.3: Pull latest changes

```bash
git pull origin feature/{feature-name}
```

### Step 2.4: Create your worker branch

```bash
git checkout -b feature/{feature-name}-claude-{WORKER_UUID}
```

### Step 2.5: Push your worker branch to remote

```bash
git push -u origin feature/{feature-name}-claude-{WORKER_UUID}
```

---

## Phase 3: Working on Your Branch

### Commit your changes

```bash
git add {files}
```

```bash
git commit -m "{descriptive message}"
```

### Push regularly

```bash
git push origin feature/{feature-name}-claude-{WORKER_UUID}
```

### Critical Rules During Work

| Rule | Description |
|------|-------------|
| **Isolation** | Work ONLY on your branch `feature/{feature-name}-claude-{WORKER_UUID}` |
| **No switching** | NEVER checkout other worker branches (`-claude-*`) |
| **Stay focused** | Do not access or modify files on other branches |
| **Push often** | Push after each logical unit of work |

---

## Phase 4: Merge and Cleanup

When your work is complete, merge back into the feature branch.

### Step 4.1: Checkout the feature branch

```bash
git checkout feature/{feature-name}
```

### Step 4.2: Pull latest changes

```bash
git pull origin feature/{feature-name}
```

### Step 4.3: Merge your worker branch

```bash
git merge feature/{feature-name}-claude-{WORKER_UUID}
```

### Step 4.4: Handle merge conflicts (if any)

Conflicts are normal when multiple workers edit similar areas. To resolve:

1. Identify conflicting files from the merge output
2. Open each file and look for conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
3. Edit the file to resolve conflicts, keeping the correct code from both sides
4. Stage resolved files:

```bash
git add {resolved-files}
```

5. Complete the merge:

```bash
git commit -m "merge: worker {WORKER_UUID} into feature/{feature-name}"
```

### Step 4.5: Push the merged feature branch

```bash
git push origin feature/{feature-name}
```

### Step 4.6: Delete local worker branch

```bash
git branch -d feature/{feature-name}-claude-{WORKER_UUID}
```

### Step 4.7: Delete remote worker branch

```bash
git push origin --delete feature/{feature-name}-claude-{WORKER_UUID}
```

---

## Branch Structure

```
main
│
└── feature/{feature-name}           ← Main feature branch (shared)
    ├── feature/{feature-name}-claude-a3f8b2c7   ← Worker 1
    ├── feature/{feature-name}-claude-c7d1e9f0   ← Worker 2
    └── feature/{feature-name}-claude-b4e2f0a1   ← Worker 3
```

---

## Quick Reference

| Phase | Key Command |
|-------|-------------|
| Init UUID | `openssl rand -hex 4` |
| Create branch | `git checkout -b feature/{name}-claude-{UUID}` |
| Work & commit | `git add {files} && git commit -m "{msg}"` |
| Push work | `git push origin feature/{name}-claude-{UUID}` |
| Merge back | `git checkout feature/{name} && git merge feature/{name}-claude-{UUID}` |
| Cleanup | `git branch -d feature/{name}-claude-{UUID}` |

---

## Conflict Resolution Guidelines

When resolving merge conflicts:

1. **Understand both changes** — Read the code from both sides before deciding
2. **Preserve functionality** — Ensure both features work after resolution
3. **Test after merge** — Run relevant tests to verify the merge
4. **Document decisions** — If a complex resolution was needed, add a comment

---

## Error Recovery

### Wrong branch?

If you accidentally switched to the wrong branch:

```bash
git checkout feature/{feature-name}-claude-{WORKER_UUID}
```

### Merge failed?

To abort a problematic merge and try again:

```bash
git merge --abort
```

Then re-pull the feature branch and retry the merge.