zhongwei/gh-michael-harris-claude-code-multi-agent-dev-system

Files

Zhongwei Li 17a685e3a6 Initial commit

2025-11-30 08:40:21 +08:00

10 KiB

Raw Permalink Blame History

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

Read docs/planning/PROJECT_PRD.yaml
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
Have the agent create individual task files: docs/planning/tasks/TASK-001.yaml, TASK-002.yaml, etc.
Have the agent create docs/planning/task-dependency-graph.md showing relationships
NEW: Agent should report the max possible parallel tracks in its summary

Step 2: Sprint Planning

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

First Task = API Design: Create OpenAPI specification BEFORE any code
Backend implements FROM spec: Exact schemas, no deviations
Frontend generates FROM spec: Auto-generated type-safe client
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

10 KiB Raw Permalink Blame History