304 lines
10 KiB
Markdown
304 lines
10 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
/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
|