Planning Command

You are orchestrating the project planning phase using the pragmatic approach. This involves two sequential agent invocations with optional parallel development track support.

Command Usage

/multi-agent:planning                    # Single track (default)
/multi-agent:planning 3                  # Request 3 parallel development tracks (state-only mode)
/multi-agent:planning 3 --use-worktrees  # Request 3 tracks with git worktrees for isolation
/multi-agent:planning 5                  # Request 5 parallel tracks (will use max possible if less)

Your Process

Step 0: Parse Parameters

Extract the number of requested parallel tracks and worktree mode from the command:

• If no parameter provided: tracks = 1 (single track mode), use_worktrees = false
• If parameter provided: tracks = requested number
• If --use-worktrees flag present: use_worktrees = true, otherwise use_worktrees = false
• Pass both tracks and use_worktrees to sprint-planner in Step 2

Worktree Mode:

• false (default): State-only mode - tracks use logical separation via state files
• true: Git worktrees mode - each track gets isolated directory and branch

Step 1: Task Analysis

1. Read docs/planning/PROJECT_PRD.yaml
2. Launch the task-graph-analyzer agent using the Task tool:
   • Pass the PRD content
   • Ask it to break down requirements into tasks
   • Ask it to identify dependencies between tasks
   • NEW: Ask it to calculate maximum possible parallel development tracks
3. Have the agent create individual task files: docs/planning/tasks/TASK-001.yaml, TASK-002.yaml, etc.
4. Have the agent create docs/planning/task-dependency-graph.md showing relationships
5. NEW: Agent should report the max possible parallel tracks in its summary

Step 2: Sprint Planning

1. After task analysis completes, launch the sprint-planner agent using the Task tool:
   • Pass all task definitions
   • Pass the dependency graph
   • Pass number of requested tracks (from Step 0)
   • Pass max possible tracks (from Step 1)
   • NEW: Pass use_worktrees flag (from Step 0)
   • Ask it to organize tasks into sprints
2. If tracks > 1:
   • Have agent create sprint files with track suffix: docs/sprints/SPRINT-XXX-YY.yaml
   • Have agent initialize state file: docs/planning/.project-state.yaml
   • Example: SPRINT-001-01.yaml, SPRINT-001-02.yaml for 2 tracks
   • NEW: If use_worktrees = true:
     • Have agent create git worktrees: .multi-agent/track-01/, .multi-agent/track-02/, etc.
     • Have agent create branches: dev-track-01, dev-track-02, etc.
     • Have agent copy planning artifacts to each worktree
     • State file should include worktree paths and branch names
3. If tracks = 1 (default):
   • Have agent create traditional sprint files: docs/sprints/SPRINT-001.yaml, SPRINT-002.yaml, etc.
   • Still initialize state file for progress tracking
   • No worktrees needed for single track

Special Pattern: API-First Full-Stack Applications

Use this pattern when building applications with separate backend and frontend that communicate via API.

When to Use API-First Pattern

Use this when your PRD indicates:

• Full-stack application (backend + frontend)
• REST API or GraphQL API
• Mobile app + backend
• Microservices architecture
• Any scenario with API contract between components

How API-First Works

1. First Task = API Design: Create OpenAPI specification BEFORE any code
2. Backend implements FROM spec: Exact schemas, no deviations
3. Frontend generates FROM spec: Auto-generated type-safe client
4. Result: Perfect alignment, compile-time safety

Task Structure Template

When you detect a full-stack project, ensure tasks follow this order:

TASK-001: Design API Specification (NO dependencies)
  ├── Agent: backend:api-designer
  ├── Output: docs/api/openapi.yaml
  └── Critical: This runs FIRST

TASK-002: Design Database Schema (depends on TASK-001)
  └── Agent: database:designer

TASK-003: Implement Database Models (depends on TASK-002)
  └── Agent: database:developer-{language}-t1

TASK-004: Implement Backend API (depends on TASK-001, TASK-003)
  ├── Agent: backend:api-developer-{language}-t1
  ├── Input: docs/api/openapi.yaml
  └── Must match spec EXACTLY

TASK-005: Generate Frontend API Client (depends on TASK-001 ONLY)
  ├── Agent: frontend:developer-t1
  ├── Input: docs/api/openapi.yaml
  ├── Tool: openapi-typescript-codegen
  └── Output: Auto-generated type-safe client

TASK-006: Implement Frontend UI (depends on TASK-005)
  └── Agent: frontend:developer-t1
  └── Uses ONLY generated client

Important Dependencies

• Backend depends on: API spec + Database models
• Frontend client depends on: API spec ONLY (not backend implementation!)
• Frontend UI depends on: Generated client

This allows frontend and backend to develop in parallel after the API spec is complete.

Validation Requirements

When creating tasks for API-first projects, include these acceptance criteria:

For TASK-001 (API Design):

• OpenAPI 3.0 specification at docs/api/openapi.yaml
• Passes openapi-spec-validator
• All endpoints, schemas, errors documented

For TASK-004 (Backend):

• Implements ONLY endpoints in spec
• Schemas match spec EXACTLY
• Passes openapi-spec-validator
• /docs endpoint serves the specification

For TASK-005 (Frontend Client):

• Client auto-generated from spec
• NO manual endpoint definitions
• TypeScript types from spec
• CI verifies client is up-to-date

For TASK-006 (Frontend UI):

• Uses ONLY generated client
• NO fetch/axios outside generated code
• TypeScript compilation enforces correctness

Example Detection

If PRD contains:

• "backend API" + "frontend application"
• "REST API" + "React/Vue/Angular"
• "mobile app" + "API server"
• "microservices" with communication

Then recommend API-first pattern and structure tasks accordingly.

Reference

See complete example: examples/api-first-fullstack-workflow.md See task templates: docs/templates/api-first-tasks.yaml

---

Agent References

• Task Graph Analyzer: .claude/agents/multi-agent:planning/task-graph-analyzer.md
• Sprint Planner: .claude/agents/multi-agent:planning/multi-agent:sprint-planner.md

After Completion

Report Format - Single Track Mode

Planning complete!

Task Analysis:
- Created 15 tasks in docs/planning/tasks/
- Max possible parallel tracks: 3
- Critical path: 5 tasks (20 hours)

Sprint Planning:
- Created 3 sprints in docs/sprints/
- SPRINT-001: Foundation (5 tasks, 40 hours)
- SPRINT-002: Core Features (6 tasks, 52 hours)
- SPRINT-003: Polish (4 tasks, 36 hours)

Artifacts:
- Tasks: docs/planning/tasks/
- Sprints: docs/sprints/
- Dependency graph: docs/planning/task-dependency-graph.md
- State file: docs/planning/.project-state.yaml

Ready to start development:
/multi-agent:sprint all              # Execute all sprints
/multi-agent:sprint SPRINT-001       # Execute specific sprint

Tip: For parallel development, try:
/multi-agent:planning 3                  # Re-run with 3 tracks for faster execution
/multi-agent:planning 3 --use-worktrees  # Use worktrees for physical isolation

Report Format - Parallel Track Mode (State-Only)

Planning complete!

Task Analysis:
- Created 15 tasks in docs/planning/tasks/
- Max possible parallel tracks: 3
- Critical path: 5 tasks (20 hours)

Sprint Planning:
- Requested tracks: 5
- Max possible: 3
- Using: 3 tracks
- Mode: State-only (logical separation)

Track Distribution:
- Track 1: 5 tasks, 42 hours (SPRINT-001-01, SPRINT-002-01)
- Track 2: 6 tasks, 48 hours (SPRINT-001-02, SPRINT-002-02)
- Track 3: 4 tasks, 38 hours (SPRINT-001-03, SPRINT-002-03)

Total: 15 tasks, ~128 hours development time
Parallel execution time: ~48 hours (62% faster)

Artifacts:
- Tasks: docs/planning/tasks/
- Sprints: docs/sprints/ (6 sprint files across 3 tracks)
- Dependency graph: docs/planning/task-dependency-graph.md
- State file: docs/planning/.project-state.yaml

Ready to start development:
/multi-agent:sprint all              # Execute all tracks sequentially
/multi-agent:sprint all 01           # Execute track 1 only
/multi-agent:sprint all 02           # Execute track 2 only
/multi-agent:sprint all 03           # Execute track 3 only

Or run in parallel (multiple terminals):
Terminal 1: /multi-agent:sprint all 01
Terminal 2: /multi-agent:sprint all 02
Terminal 3: /multi-agent:sprint all 03

Tip: For stronger isolation, try:
/multi-agent:planning 3 --use-worktrees  # Use git worktrees for physical separation

Report Format - Parallel Track Mode (With Worktrees)

Planning complete!

Task Analysis:
- Created 15 tasks in docs/planning/tasks/
- Max possible parallel tracks: 3
- Critical path: 5 tasks (20 hours)

Sprint Planning:
- Requested tracks: 5
- Max possible: 3
- Using: 3 tracks
- Mode: Git worktrees (physical isolation)

Worktree Configuration:
  ✓ Track 1: .multi-agent/track-01/ (branch: dev-track-01)
  ✓ Track 2: .multi-agent/track-02/ (branch: dev-track-02)
  ✓ Track 3: .multi-agent/track-03/ (branch: dev-track-03)

Track Distribution:
- Track 1: 5 tasks, 42 hours (SPRINT-001-01, SPRINT-002-01)
- Track 2: 6 tasks, 48 hours (SPRINT-001-02, SPRINT-002-02)
- Track 3: 4 tasks, 38 hours (SPRINT-001-03, SPRINT-002-03)

Total: 15 tasks, ~128 hours development time
Parallel execution time: ~48 hours (62% faster)

Artifacts:
- Tasks: docs/planning/tasks/
- Sprints: docs/sprints/ (6 sprint files across 3 tracks)
- Dependency graph: docs/planning/task-dependency-graph.md
- State file: docs/planning/.project-state.yaml
- Worktrees: .multi-agent/track-01/, track-02/, track-03/

Ready to start development:
/multi-agent:sprint all              # Execute all tracks sequentially
/multi-agent:sprint all 01           # Execute track 1 (auto-switches to worktree)
/multi-agent:sprint all 02           # Execute track 2 (auto-switches to worktree)
/multi-agent:sprint all 03           # Execute track 3 (auto-switches to worktree)

Or run in parallel (multiple terminals):
Terminal 1: /multi-agent:sprint all 01
Terminal 2: /multi-agent:sprint all 02
Terminal 3: /multi-agent:sprint all 03

After all tracks complete, merge them:
/multi-agent:merge-tracks            # Merges all tracks, cleans up worktrees

Important Notes

• Use the Task tool to launch each agent
• Wait for each agent to complete before moving to the next
• Agents should reference the PRD's technology stack for language-specific tasks
• Ensure dependency order is preserved in sprint plans