Parallel Development Planning

Create implementation plans to maximize parallelization of feature development with multiple developers. Also supports on-demand parallel tasks (bug fixes, feature additions) for completed projects.

Usage Modes

This skill has two modes:

Mode A: Initial Parallel Development (Planning Mode)

Used immediately after project initialization (right after uv init, create-react-app, etc.) when developing multiple features in parallel.

Trigger Phrases:

"Create a parallel development plan"
"I want to develop with multiple people simultaneously"
"Divide work with worktree"
"Maximize development parallelization"

Workflow: 9-step workflow (described below) to create a plan and start multiple tasks simultaneously.

Mode B: Maintenance Parallel Development (Quick Task Mode)

Used for bug fixes and feature additions to projects with existing implementations. Start work immediately without a plan document.

Trigger Phrases:

"Fix XX in parallel"
"Handle XX in parallel"
"Do YY with worktree"
"Add parallel task: XX"
"Do this with worktree: XX"

Workflow: See "Quick Task Workflow" section for details.

Mode Selection Guide

| Situation | Recommended Mode | | ----------------------------------------------- | ------------------------------------------ | | Right after project initialization, parallel features | A | | Single bug fix to existing project | B (single task) | | Medium-scale feature addition to existing project | B (multiple tasks + merge coordinator) |

Workflow (Mode A: Initial Parallel Development)

1. Understand Requirements
   └─→ Collect list of features to develop
   └─→ Confirm tech stack (BE/FE/Infrastructure, etc.)

2. Task Decomposition
   └─→ Split each feature into independent tasks
   └─→ Granularity: whichever is smaller
       ├─→ 0.5-2 days in human time
       ├─→ Within 20 files changed
       └─→ Independently testable feature unit
   └─→ ⚠️ UI specs require human approval (see below)

3. Dependency Analysis
   └─→ Identify blocking relationships between tasks
   └─→ Calculate critical path

4. Determine Parallelism
   └─→ Calculate number of Claude instances needed
   └─→ Assignment to minimize wait time

5. Branch Strategy
   └─→ Design integration branch
   └─→ Feature branch naming convention
   └─→ Determine merge order

6. Create Timeline
   └─→ Gantt-style parallel schedule

7. Create Plan and Instruction Documents
   └─→ Communicate plan content to user (present execution order, parallelism, and task content in table format)
   └─→ Create files in .parallel-dev/
       ├─→ PLAN.md (plan document)
       ├─→ README.md (overall overview and progress management)
       ├─→ merge-coordinator.md (for merge coordinator)
       ├─→ tasks/*.md (for each task)
       ├─→ signals/ (completion notification directory)
       └─→ issues/ (issue report directory)

8. Environment Setup
   └─→ Create integration branch and push to remote
   └─→ Create worktree for each task
   └─→ Install dependencies in each worktree
   └─→ Copy .env in each worktree

9. Launch merge coordinator Claude in tmux new-window
   └─→ Create new window with tmux new-window -n "coordinator" and launch claude
   └─→ Pass initial instructions to merge coordinator

Quick Task Workflow (Mode B: Quick Task)

Mode for immediately starting bug fixes or feature additions to existing projects without a plan document.

Features:

Start immediately without plan document
Support multiple concurrent sessions with session files (.parallel-dev/quick-session-{timestamp}.md)
Merge directly to main

→ See references/quick-mode-guide.md for details

Terminology

To avoid confusion, unify the following terms:

| Term | Description | Example | | ----------------- | ----------------------------------------- | -------------------------------------- | | Task Name | Identical to branch name. Work unit ID | skill-files-api, recommendation-ui | | Person/Role | Worker identifier. Tech area + number | BE-1, FE-1, INFRA-1 | | Integration Branch | Target branch to merge all tasks | feature/multi-file-skills |

Important: Use task name (branch name) for completion reports and state management. Person name alone cannot identify the task when handling multiple tasks.

Task Decomposition Rules

Task splitting principles:

Single Responsibility: 1 task = 1 feature/1 component
Appropriate Granularity: whichever is smaller
- 0.5-2 days in human time
- Within 20 files changed
- Independently testable feature unit
Clear Deliverables: Each task has concrete deliverables like API/component/file
Testable: Unit that can be independently tested and reviewed
Minimize Conflicts: Minimize file edit overlaps, consolidate common file changes (routing, type definitions, etc.) into one task

Branch naming:

feature/recommendation-api  # Feature name based
feature/notification-api
feature/project-card-enhance

Role (person) naming:

BE-1, BE-2, ...    # Backend
FE-1, FE-2, ...    # Frontend
INFRA-1, ...       # Infrastructure

Dependency Analysis

Dependency types:

| Dependency Type | Symbol | Description | | --------------- | ------ | --------------------- | | Blocking | → | Must complete | | Parallel | // | Can proceed independently | | Waiting for integration | ↓ | Start after merge |

Critical path calculation:

Longest path = max(total effort of each path)
Optimal number of people = ceil(total effort / critical path)

Create dependency matrix:

         BE-01  BE-02  FE-01  FE-02
BE-01      -      //     ↓      //
BE-02     //       -     //      ↓
FE-01    Wait     //      -      //
FE-02     //     Wait    //       -

Developer Role Assignment

Role definition template:

| Role | Assigned Branch | Required Skills | | ---- | --------------- | ----------------- | | BE-1 | feature/xxx-api | Python, FastAPI | | FE-1 | feature/xxx-ui | React, TypeScript |

Principles for minimizing wait time:

Assign dependent tasks to the dependency source worker
Fill wait time with independent tasks
Utilize idle time for review and support

Branch Strategy with Worktree

Git worktree basics for parallel development:

main
└── feature/integration (integration branch)
    ├── feature/xxx-api     → worktree/xxx-api/
    ├── feature/yyy-api     → worktree/yyy-api/
    └── feature/xxx-ui      → worktree/xxx-ui/

→ See references/worktree-guide.md for details

Agent Instruction Files

For parallel development with Claude, place instruction documents for each Claude in .parallel-dev/.

Directory Structure:

| Directory/File | Purpose | | ------------------------------------ | ------------------------ | | .parallel-dev/ | Parallel dev management (git-managed) | | .parallel-dev/PLAN.md | Plan document | | .parallel-dev/merge-coordinator.md | For merge coordinator | | .parallel-dev/tasks/*.md | Instruction docs per task | | .parallel-dev-signals/ | Completion notifications (.gitignore) | | .parallel-dev-issues/ | Issue reports (.gitignore) |

Templates:

Task Completion Flow

Role Division:

Worker Claude: Code implementation → Create .done file (don't commit)
Merge Coordinator: Commit → Test → Merge → Push

Design Philosophy: Worker Claude focuses on writing code. Only merge coordinator manages merge order.

→ See references/worktree-guide.md for details

Rules (Common to all Claude)

Worker Claude Rules

Don't commit: Just write code. Merge coordinator does commits
Don't push: Merge coordinator handles remote pushes
Report completion with .done file: Describe implementation and changed files
UI specs require human approval: Submit confirmation request to issues/, implement after approval

Merge Coordinator Rules

Launch worker Claude with tmux new-window -n "{task-name}" (don't use Task tool)

Always pass initial instructions as argument when launching claude:

tmux new-window -n "{task-name}" "cd worktree/{task-name} && PROJECT_ROOT=$PROJECT_ROOT claude 'Please read ../../.parallel-dev/tasks/{task-name}.md and implement. Create \$PROJECT_ROOT/.parallel-dev-signals/{task-name}.done when complete (create in parent project, not in worktree).'"

Terminate worker Claude after successful merge: tmux send-keys -t "{task-name}" C-c C-c
Always merge with --no-ff
Conflict resolution: Merge coordinator resolves (don't delegate to worker Claude)

Dependency Rules

Don't launch dependent tasks until dependency tasks are merged into integration branch

→ See references/worktree-guide.md for details

Additional Guides

references/worktree-guide.md - Worktree operations, workflows, detailed rules
references/quick-mode-guide.md - Quick task mode operations
references/testing-guide.md - Testing policy (production-equivalent tests, E2E visual checks)
references/ui-approval-guide.md - Human approval flow for UI specs
references/advanced-features.md - Phase separation, timeline visualization, plan templates

plan-parallel-dev

Parallel Development Planning

Usage Modes

Mode A: Initial Parallel Development (Planning Mode)

Mode B: Maintenance Parallel Development (Quick Task Mode)

Mode Selection Guide

Workflow (Mode A: Initial Parallel Development)

Quick Task Workflow (Mode B: Quick Task)

Terminology

Task Decomposition Rules

Dependency Analysis

Developer Role Assignment

Branch Strategy with Worktree

Agent Instruction Files

Task Completion Flow

Rules (Common to all Claude)

Worker Claude Rules

Merge Coordinator Rules

Dependency Rules

Additional Guides