Parallel Dev Fullstack

---
description: Execute parallel fullstack development with TDD
argument-hint: [workers]
---

# Execute Parallel Fullstack Development

## Your Task
Execute all frontend and backend tasks in parallel following the dependency graph.

## Prerequisites
- Fullstack dependency graph exists in task_registry.json
- Design artifacts available (wireframes, user flows)

## File Format References
This command reads and updates two central JSON files:
- **📄 [state.json Template](../.claude/templates/state.json.template)** - Global state tracking
- **📄 [task_registry.json Template](../.claude/templates/task_registry.json.template)** - Task definitions and dependencies

Refer to these templates for complete field definitions and usage examples.

## Steps

### 1. Load Configuration and Check State

#### 1.1 Load Task Registry
Read execution_order from task_registry.json.
Parse workers argument (default: 5).

#### 1.2 Check Existing State
Check if `.claude_tasks/state.json` exists:
- If exists: Resume from last completed wave
- If not exists: Start from Wave 1

**📄 State File Format**: See [state.json Template](../.claude/templates/state.json.template) for complete structure.

**Key fields used**:
- `development_phase.status`: "not_started" | "in_progress" | "completed"
- `development_phase.current_wave`: Current wave number
- `development_phase.completed_waves`: Number of completed waves
- `development_phase.completed_tasks`: Array of completed task IDs
- `development_phase.failed_tasks`: Array of failed task IDs
- `development_phase.workers`: Worker pool size
- `development_phase.wave_progress[N]`: Per-wave execution details

#### 1.3 Resume Logic
If resuming (state.json exists and development_phase.status == "in_progress"):
- Read `development_phase.current_wave` and `development_phase.completed_waves`
- Output: "🔄 Resuming from Wave {current_wave} (Waves 1-{completed_waves} already complete)"
- Output: "📊 Progress: {completed_tasks.length} tasks completed, {failed_tasks.length} failed"
- Skip completed waves (waves 1 to completed_waves)
- For current wave in progress:
  - Check task_registry.json for tasks with status="completed" in this wave
  - Read `wave_progress[current_wave].current_batch` to determine batch position
  - Only process remaining batches in current wave
  - Continue from first incomplete batch

If starting fresh (state.json doesn't exist or development_phase.status == "not_started"):
- Output: "🚀 Starting fullstack development from Wave 1"
- Initialize state.json with development_phase structure
- Set `development_phase.status = "in_progress"`
- Set `development_phase.current_wave = 1`
- Set `development_phase.completed_waves = 0`
- Start from Wave 1, Batch 1

### 2. Process Each Wave (Serial Waves, Parallel Batches)

**Wave Execution Model**:
- Waves are executed SERIALLY (one wave at a time, respecting dependencies)
- Within each wave, tasks are divided into BATCHES
- Batch size = worker count (e.g., workers=5 means 5 tasks per batch)
- Batches execute SERIALLY (one batch at a time within wave)
- Tasks within a batch execute in PARALLEL
- Wait for current batch to complete before creating next batch
- Wait for current wave to complete before starting next wave

For each wave in execution_order:

#### 2.1 Identify Wave Category and Level
Determine task level and types in current wave:
- **Level 3 tasks (Leaf nodes)**: Direct implementation
  - Backend functions: Use @backend-developer
  - Frontend components: Use @frontend-developer
- **Level 2 tasks (Integration)**: Assemble children into cohesive units
  - Backend services: Use @backend-integrator (assemble functions)
  - Frontend pages: Use @frontend-integrator (assemble components)
- **Level 1 tasks (Final assembly)**: Integrate modules
  - Backend modules: Use @backend-integrator
  - Frontend modules: Use @frontend-integrator
- Mixed wave: Use appropriate developer/integrator for each task

#### 2.2 Create Developer Subagents for Wave

**State Management via Python Scripts**:
After EACH subagent task completes, use Python scripts to update state:

**📄 Script Reference**: See [.claude/scripts/README.md](../.claude/scripts/README.md) for complete API documentation.

**For Successful Task Completion**:
```python
from utils import ProjectManager

manager = ProjectManager()
manager.complete_task_full(
    task_id="1.2.3",  # Task ID in dot notation (e.g., "1.2.3")
    implementation_file="src/components/auth/LoginForm.tsx",
    test_file="src/components/auth/LoginForm.test.tsx",
    test_coverage=95,  # Percentage
    duration_minutes=12.5
)

For Failed Task:

from utils import ProjectManager

manager = ProjectManager()
manager.fail_task_full(
    task_id="1.2.3",
    error="Test coverage below 80% threshold"
)

This automatically updates both:

• task_registry.json: Task status, files, coverage, duration
• state.json: Adds task_id to completed_tasks or failed_tasks array

2.3 Batch Completion

After each batch completes, update batch progress:

from utils import ProjectManager

manager = ProjectManager()

# After batch completes
completed = ["1.2.1", "1.2.2", "1.2.3"]  # Dot notation IDs
failed = []  # Task IDs that failed in this batch

manager.complete_batch(
    wave_number=3,
    completed_tasks=completed,
    failed_tasks=failed
)

This updates state.json:

• Increments wave_progress[N].completed counter
• Increments wave_progress[N].current_batch counter

CRITICAL - BATCH EXECUTION WITHIN WAVE:

• Divide wave tasks into batches of size = worker count
• Process batches SERIALLY (one batch at a time)
• Within each batch, create ALL <subagent_task> blocks in ONE response
• Wait for current batch to complete before creating next batch
• Continue until ALL tasks in wave are processed (100% wave coverage)

Execution Rules:

1. Count tasks in wave: wave_task_count = tasks in current wave
2. Calculate batches: num_batches = ceil(wave_task_count / workers)
3. **Proc