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

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:

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:

1. Single Responsibility: 1 task = 1 feature/1 component
2. Appropriate Granularity: whichever is smaller
   • 0.5-2 days in human time
   • Within 20 files changed
   • Independently testable feature unit
3. Clear Deliverables: Each task has concrete deliverables like API/component/file
4. Testable: Unit that can be independently tested and reviewed
5. 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:

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:

Principles for minimizing wait time:

1. Assign dependent tasks to the dependency source worker
2. Fill wait time with independent tasks
3. 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:

Templates:

• references/templates/parallel-dev-readme.md
• references/templates/merge-coordinator.md
• references/templates/task-instruction.md

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

  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