Initial commit

2025-11-30 08:40:21 +08:00
commit 17a685e3a6
89 changed files with 43606 additions and 0 deletions
--- a/commands/planning.md
+++ b/commands/planning.md
@@ -0,0 +1,303 @@
+# 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