Initial commit
This commit is contained in:
Zhongwei Li
13
.claude-plugin/plugin.json
Normal file
13
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"name": "orchestration",
|
||||
"description": "Shared multi-agent coordination and workflow orchestration patterns for complex Claude Code workflows. Skills-only plugin providing proven patterns for parallel execution (3-5x speedup), multi-model validation (Grok/Gemini/GPT-5), quality gates, TDD loops, TodoWrite phase tracking, and comprehensive error recovery. Battle-tested patterns from 100+ days production use.",
|
||||
"version": "0.1.1",
|
||||
"author": {
|
||||
"name": "Jack Rudenko",
|
||||
"email": "i@madappgang.com",
|
||||
"company": "MadAppGang"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# orchestration
|
||||
|
||||
Shared multi-agent coordination and workflow orchestration patterns for complex Claude Code workflows. Skills-only plugin providing proven patterns for parallel execution (3-5x speedup), multi-model validation (Grok/Gemini/GPT-5), quality gates, TDD loops, TodoWrite phase tracking, and comprehensive error recovery. Battle-tested patterns from 100+ days production use.
|
||||
61
plugin.lock.json
Normal file
61
plugin.lock.json
Normal file
@@ -0,0 +1,61 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:MadAppGang/claude-code:plugins/orchestration",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "ad90df36843224b97a17f14cfd5a207d4e053c67",
|
||||
"treeHash": "811ec6920184f4235cc78d0b9ca0025fae96488caf35059ca1224e8d5cb24150",
|
||||
"generatedAt": "2025-11-28T10:12:05.859643Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "orchestration",
|
||||
"description": "Shared multi-agent coordination and workflow orchestration patterns for complex Claude Code workflows. Skills-only plugin providing proven patterns for parallel execution (3-5x speedup), multi-model validation (Grok/Gemini/GPT-5), quality gates, TDD loops, TodoWrite phase tracking, and comprehensive error recovery. Battle-tested patterns from 100+ days production use.",
|
||||
"version": "0.1.1"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "215babb6dff86f8783d8e97d0a21546e2aaa3b055bc1cde5c4e16c6bf3d6c7a5"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "36414e18947889714f9d80576e01edaab8b3ffdf9efd44107e0f5fb42b0e2270"
|
||||
},
|
||||
{
|
||||
"path": "skills/todowrite-orchestration/SKILL.md",
|
||||
"sha256": "f681467a2eef99945f90b8f2b654c8c9713f4153afdff19a0c0b312d2f6084de"
|
||||
},
|
||||
{
|
||||
"path": "skills/quality-gates/SKILL.md",
|
||||
"sha256": "ba13c21d8e9f8abeb856bbec4a6ebc821e92dfe0857942797959087452b175c3"
|
||||
},
|
||||
{
|
||||
"path": "skills/error-recovery/SKILL.md",
|
||||
"sha256": "133564d1bc0d35a8c35074b089120fe7d7a757b71bdd6222a7a5c23e45f20aa3"
|
||||
},
|
||||
{
|
||||
"path": "skills/multi-agent-coordination/SKILL.md",
|
||||
"sha256": "9e0156350eb09447221898598611a5270921c31168e7698c4bd0d3bd0ced4616"
|
||||
},
|
||||
{
|
||||
"path": "skills/multi-model-validation/SKILL.md",
|
||||
"sha256": "9d5c46dfa531f911f4fcc4070fd6c039900bcdb440c997f7eac384001a1ba33e"
|
||||
}
|
||||
],
|
||||
"dirSha256": "811ec6920184f4235cc78d0b9ca0025fae96488caf35059ca1224e8d5cb24150"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
1107
skills/error-recovery/SKILL.md
Normal file
1107
skills/error-recovery/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
742
skills/multi-agent-coordination/SKILL.md
Normal file
742
skills/multi-agent-coordination/SKILL.md
Normal file
@@ -0,0 +1,742 @@
|
||||
---
|
||||
name: multi-agent-coordination
|
||||
description: Coordinate multiple agents in parallel or sequential workflows. Use when running agents simultaneously, delegating to sub-agents, switching between specialized agents, or managing agent selection. Trigger keywords - "parallel agents", "sequential workflow", "delegate", "multi-agent", "sub-agent", "agent switching", "task decomposition".
|
||||
version: 0.1.0
|
||||
tags: [orchestration, multi-agent, parallel, sequential, delegation, coordination]
|
||||
keywords: [parallel, sequential, delegate, sub-agent, agent-switching, multi-agent, task-decomposition, coordination]
|
||||
---
|
||||
|
||||
# Multi-Agent Coordination
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Purpose:** Patterns for coordinating multiple agents in complex workflows
|
||||
**Status:** Production Ready
|
||||
|
||||
## Overview
|
||||
|
||||
Multi-agent coordination is the foundation of sophisticated Claude Code workflows. This skill provides battle-tested patterns for orchestrating multiple specialized agents to accomplish complex tasks that are beyond the capabilities of a single agent.
|
||||
|
||||
The key challenge in multi-agent systems is **dependencies**. Some tasks must execute sequentially (one agent's output feeds into another), while others can run in parallel (independent validations from different perspectives). Getting this right is the difference between a 5-minute workflow and a 15-minute one.
|
||||
|
||||
This skill teaches you:
|
||||
- When to run agents in **parallel** vs **sequential**
|
||||
- How to **select the right agent** for each task
|
||||
- How to **delegate** to sub-agents without polluting context
|
||||
- How to manage **context windows** across multiple agent calls
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Pattern 1: Sequential vs Parallel Execution
|
||||
|
||||
**When to Use Sequential:**
|
||||
|
||||
Use sequential execution when there are **dependencies** between agents:
|
||||
- Agent B needs Agent A's output as input
|
||||
- Workflow phases must complete in order (plan → implement → test → review)
|
||||
- Each agent modifies shared state (same files)
|
||||
|
||||
**Example: Multi-Phase Implementation**
|
||||
|
||||
```
|
||||
Phase 1: Architecture Planning
|
||||
Task: api-architect
|
||||
Output: ai-docs/architecture-plan.md
|
||||
Wait for completion ✓
|
||||
|
||||
Phase 2: Implementation (depends on Phase 1)
|
||||
Task: backend-developer
|
||||
Input: Read ai-docs/architecture-plan.md
|
||||
Output: src/auth.ts, src/routes.ts
|
||||
Wait for completion ✓
|
||||
|
||||
Phase 3: Testing (depends on Phase 2)
|
||||
Task: test-architect
|
||||
Input: Read src/auth.ts, src/routes.ts
|
||||
Output: tests/auth.test.ts
|
||||
```
|
||||
|
||||
**When to Use Parallel:**
|
||||
|
||||
Use parallel execution when agents are **independent**:
|
||||
- Multiple validation perspectives (designer + tester + reviewer)
|
||||
- Multiple AI models reviewing same code (Grok + Gemini + Claude)
|
||||
- Multiple feature implementations in separate files
|
||||
|
||||
**Example: Multi-Perspective Validation**
|
||||
|
||||
```
|
||||
Single Message with Multiple Task Calls:
|
||||
|
||||
Task: designer
|
||||
Prompt: Validate UI against Figma design
|
||||
Output: ai-docs/design-review.md
|
||||
---
|
||||
Task: ui-manual-tester
|
||||
Prompt: Test UI in browser for usability
|
||||
Output: ai-docs/testing-report.md
|
||||
---
|
||||
Task: senior-code-reviewer
|
||||
Prompt: Review code quality and patterns
|
||||
Output: ai-docs/code-review.md
|
||||
|
||||
All three execute simultaneously (3x speedup!)
|
||||
Wait for all to complete, then consolidate results.
|
||||
```
|
||||
|
||||
**The 4-Message Pattern for True Parallel Execution:**
|
||||
|
||||
This is **CRITICAL** for achieving true parallelism:
|
||||
|
||||
```
|
||||
Message 1: Preparation (Bash Only)
|
||||
- Create workspace directories
|
||||
- Validate inputs
|
||||
- Write context files
|
||||
- NO Task calls, NO TodoWrite
|
||||
|
||||
Message 2: Parallel Execution (Task Only)
|
||||
- Launch ALL agents in SINGLE message
|
||||
- ONLY Task tool calls
|
||||
- Each Task is independent
|
||||
- All execute simultaneously
|
||||
|
||||
Message 3: Consolidation (Task Only)
|
||||
- Launch consolidation agent
|
||||
- Automatically triggered when N agents complete
|
||||
|
||||
Message 4: Present Results
|
||||
- Show user final consolidated results
|
||||
- Include links to detailed reports
|
||||
```
|
||||
|
||||
**Anti-Pattern: Mixing Tool Types Breaks Parallelism**
|
||||
|
||||
```
|
||||
❌ WRONG - Executes Sequentially:
|
||||
await TodoWrite({...}); // Tool 1
|
||||
await Task({...}); // Tool 2 - waits for TodoWrite
|
||||
await Bash({...}); // Tool 3 - waits for Task
|
||||
await Task({...}); // Tool 4 - waits for Bash
|
||||
|
||||
✅ CORRECT - Executes in Parallel:
|
||||
await Task({...}); // Task 1
|
||||
await Task({...}); // Task 2
|
||||
await Task({...}); // Task 3
|
||||
// All execute simultaneously
|
||||
```
|
||||
|
||||
**Why Mixing Fails:**
|
||||
|
||||
Claude Code sees different tool types and assumes there are dependencies between them, forcing sequential execution. Using a single tool type (all Task calls) signals that operations are independent and can run in parallel.
|
||||
|
||||
---
|
||||
|
||||
### Pattern 2: Agent Selection by Task Type
|
||||
|
||||
**Task Detection Logic:**
|
||||
|
||||
Intelligent workflows automatically detect task type and select appropriate agents:
|
||||
|
||||
```
|
||||
Task Type Detection:
|
||||
|
||||
IF request mentions "API", "endpoint", "backend", "database":
|
||||
→ API-focused workflow
|
||||
→ Use: api-architect, backend-developer, test-architect
|
||||
→ Skip: designer, ui-developer (not relevant)
|
||||
|
||||
ELSE IF request mentions "UI", "component", "design", "Figma":
|
||||
→ UI-focused workflow
|
||||
→ Use: designer, ui-developer, ui-manual-tester
|
||||
→ Optional: ui-developer-codex (external validation)
|
||||
|
||||
ELSE IF request mentions both API and UI:
|
||||
→ Mixed workflow
|
||||
→ Use all relevant agents from both categories
|
||||
→ Coordinate between backend and frontend agents
|
||||
|
||||
ELSE IF request mentions "test", "coverage", "bug":
|
||||
→ Testing-focused workflow
|
||||
→ Use: test-architect, ui-manual-tester
|
||||
→ Optional: codebase-detective (for bug investigation)
|
||||
|
||||
ELSE IF request mentions "review", "validate", "feedback":
|
||||
→ Review-focused workflow
|
||||
→ Use: senior-code-reviewer, designer, ui-developer
|
||||
→ Optional: external model reviewers
|
||||
```
|
||||
|
||||
**Agent Capability Matrix:**
|
||||
|
||||
| Task Type | Primary Agent | Secondary Agent | Optional External |
|
||||
|-----------|---------------|-----------------|-------------------|
|
||||
| API Implementation | backend-developer | api-architect | - |
|
||||
| UI Implementation | ui-developer | designer | ui-developer-codex |
|
||||
| Testing | test-architect | ui-manual-tester | - |
|
||||
| Code Review | senior-code-reviewer | - | codex-code-reviewer |
|
||||
| Architecture Planning | api-architect OR frontend-architect | - | plan-reviewer |
|
||||
| Bug Investigation | codebase-detective | test-architect | - |
|
||||
| Design Validation | designer | ui-developer | designer-codex |
|
||||
|
||||
**Agent Switching Pattern:**
|
||||
|
||||
Some workflows benefit from **adaptive agent selection** based on context:
|
||||
|
||||
```
|
||||
Example: UI Development with External Validation
|
||||
|
||||
Base Implementation:
|
||||
Task: ui-developer
|
||||
Prompt: Implement navbar component from design
|
||||
|
||||
User requests external validation:
|
||||
→ Switch to ui-developer-codex OR add parallel ui-developer-codex
|
||||
→ Run both: embedded ui-developer + external ui-developer-codex
|
||||
→ Consolidate feedback from both
|
||||
|
||||
Scenario 1: User wants speed
|
||||
→ Use ONLY ui-developer (embedded, fast)
|
||||
|
||||
Scenario 2: User wants highest quality
|
||||
→ Use BOTH ui-developer AND ui-developer-codex (parallel)
|
||||
→ Consensus analysis on feedback
|
||||
|
||||
Scenario 3: User is out of credits
|
||||
→ Fallback to ui-developer only
|
||||
→ Notify user external validation unavailable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 3: Sub-Agent Delegation
|
||||
|
||||
**File-Based Instructions (Context Isolation):**
|
||||
|
||||
When delegating to sub-agents, use **file-based instructions** to avoid context pollution:
|
||||
|
||||
```
|
||||
✅ CORRECT - File-Based Delegation:
|
||||
|
||||
Step 1: Write instructions to file
|
||||
Write: ai-docs/architecture-instructions.md
|
||||
Content: "Design authentication system with JWT tokens..."
|
||||
|
||||
Step 2: Delegate to agent with file reference
|
||||
Task: api-architect
|
||||
Prompt: "Read instructions from ai-docs/architecture-instructions.md
|
||||
and create architecture plan."
|
||||
|
||||
Step 3: Agent reads file, does work, writes output
|
||||
Agent reads: ai-docs/architecture-instructions.md
|
||||
Agent writes: ai-docs/architecture-plan.md
|
||||
|
||||
Step 4: Agent returns brief summary ONLY
|
||||
Return: "Architecture plan complete. See ai-docs/architecture-plan.md"
|
||||
|
||||
Step 5: Orchestrator reads output file if needed
|
||||
Read: ai-docs/architecture-plan.md
|
||||
(Only if orchestrator needs to process the output)
|
||||
```
|
||||
|
||||
**Why File-Based?**
|
||||
|
||||
- **Avoids context pollution:** Long user requirements don't bloat orchestrator context
|
||||
- **Reusable:** Multiple agents can read same instruction file
|
||||
- **Debuggable:** Files persist after workflow completes
|
||||
- **Clean separation:** Input file, output file, orchestrator stays lightweight
|
||||
|
||||
**Anti-Pattern: Inline Delegation**
|
||||
|
||||
```
|
||||
❌ WRONG - Context Pollution:
|
||||
|
||||
Task: api-architect
|
||||
Prompt: "Design authentication system with:
|
||||
- JWT tokens with refresh token rotation
|
||||
- Email/password login with bcrypt hashing
|
||||
- OAuth2 integration with Google, GitHub
|
||||
- Rate limiting on login endpoint (5 attempts per 15 min)
|
||||
- Password reset flow with time-limited tokens
|
||||
- Email verification on signup
|
||||
- Role-based access control (admin, user, guest)
|
||||
- Session management with Redis
|
||||
- Security headers (CORS, CSP, HSTS)
|
||||
- ... (500 more lines of requirements)"
|
||||
|
||||
Problem: Orchestrator's context now contains 500+ lines of requirements
|
||||
that are only relevant to the architect agent.
|
||||
```
|
||||
|
||||
**Brief Summary Returns:**
|
||||
|
||||
Sub-agents should return **2-5 sentence summaries**, not full output:
|
||||
|
||||
```
|
||||
✅ CORRECT - Brief Summary:
|
||||
"Architecture plan complete. Designed 3-layer authentication:
|
||||
JWT with refresh tokens, OAuth2 integration (Google/GitHub),
|
||||
and Redis session management. See ai-docs/architecture-plan.md
|
||||
for detailed component breakdown."
|
||||
|
||||
❌ WRONG - Full Output:
|
||||
"Architecture plan:
|
||||
[500 lines of detailed architecture documentation]
|
||||
Components: AuthController, TokenService, OAuthService...
|
||||
[another 500 lines]"
|
||||
```
|
||||
|
||||
**Proxy Mode Invocation:**
|
||||
|
||||
For external AI models (Claudish), use the PROXY_MODE directive:
|
||||
|
||||
```
|
||||
Task: codex-code-reviewer PROXY_MODE: x-ai/grok-code-fast-1
|
||||
Prompt: "Review authentication implementation for security issues.
|
||||
Code context in ai-docs/code-review-context.md"
|
||||
|
||||
Agent Behavior:
|
||||
1. Detects PROXY_MODE directive
|
||||
2. Extracts model: x-ai/grok-code-fast-1
|
||||
3. Extracts task: "Review authentication implementation..."
|
||||
4. Executes: claudish --model x-ai/grok-code-fast-1 --stdin <<< "..."
|
||||
5. Waits for full response (blocking execution)
|
||||
6. Writes: ai-docs/grok-review.md (full detailed review)
|
||||
7. Returns: "Grok review complete. Found 3 CRITICAL issues. See ai-docs/grok-review.md"
|
||||
```
|
||||
|
||||
**Key: Blocking Execution**
|
||||
|
||||
External models MUST execute synchronously (blocking) so the agent waits for the full response:
|
||||
|
||||
```
|
||||
✅ CORRECT - Blocking:
|
||||
RESULT=$(claudish --model x-ai/grok-code-fast-1 --stdin <<< "$PROMPT")
|
||||
echo "$RESULT" > ai-docs/grok-review.md
|
||||
echo "Review complete - see ai-docs/grok-review.md"
|
||||
|
||||
❌ WRONG - Background (returns before completion):
|
||||
claudish --model x-ai/grok-code-fast-1 --stdin <<< "$PROMPT" &
|
||||
echo "Review started..." # Agent returns immediately, review not done!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 4: Context Window Management
|
||||
|
||||
**When to Delegate:**
|
||||
|
||||
Delegate to sub-agents when:
|
||||
- Task is self-contained (clear input → output)
|
||||
- Output is large (architecture plan, test suite, review report)
|
||||
- Task requires specialized expertise (designer, tester, reviewer)
|
||||
- Multiple independent tasks can run in parallel
|
||||
|
||||
**When to Execute in Main Context:**
|
||||
|
||||
Execute in main orchestrator when:
|
||||
- Task is small (simple file edit, command execution)
|
||||
- Output is brief (yes/no decision, status check)
|
||||
- Task depends on orchestrator state (current phase, iteration count)
|
||||
- Context pollution risk is low
|
||||
|
||||
**Context Size Estimation:**
|
||||
|
||||
**Note:** Token estimates below are approximations based on typical usage. Actual context consumption varies by skill complexity, Claude model version, and conversation history. Use these as guidelines, not exact measurements.
|
||||
|
||||
Estimate context usage to decide delegation strategy:
|
||||
|
||||
```
|
||||
Context Budget: ~200k tokens (Claude Sonnet 4.5 - actual varies by model)
|
||||
|
||||
Current context usage breakdown:
|
||||
- System prompt: 10k tokens
|
||||
- Skill content (5 skills): 10k tokens
|
||||
- Command instructions: 5k tokens
|
||||
- User request: 1k tokens
|
||||
- Conversation history: 20k tokens
|
||||
───────────────────────────────────
|
||||
Total used: 46k tokens
|
||||
Remaining: 154k tokens
|
||||
|
||||
Safe threshold for delegation: If task will consume >30k tokens, delegate
|
||||
|
||||
Example: Architecture planning for large system
|
||||
- Requirements: 5k tokens
|
||||
- Expected output: 20k tokens
|
||||
- Total: 25k tokens
|
||||
───────────────────────────────────
|
||||
Decision: Delegate (keeps orchestrator lightweight)
|
||||
```
|
||||
|
||||
**Delegation Strategy by Context Size:**
|
||||
|
||||
| Task Output Size | Strategy |
|
||||
|------------------|----------|
|
||||
| < 1k tokens | Execute in orchestrator |
|
||||
| 1k - 10k tokens | Delegate with summary return |
|
||||
| 10k - 30k tokens | Delegate with file-based output |
|
||||
| > 30k tokens | Multi-agent decomposition |
|
||||
|
||||
**Example: Multi-Agent Decomposition**
|
||||
|
||||
```
|
||||
User Request: "Implement complete e-commerce system"
|
||||
|
||||
This is >100k tokens if done by single agent. Decompose:
|
||||
|
||||
Phase 1: Break into sub-systems
|
||||
- Product catalog
|
||||
- Shopping cart
|
||||
- Checkout flow
|
||||
- User authentication
|
||||
- Order management
|
||||
- Payment integration
|
||||
|
||||
Phase 2: Delegate each sub-system to separate agent
|
||||
Task: backend-developer
|
||||
Instruction file: ai-docs/product-catalog-requirements.md
|
||||
Output file: ai-docs/product-catalog-implementation.md
|
||||
|
||||
Task: backend-developer
|
||||
Instruction file: ai-docs/shopping-cart-requirements.md
|
||||
Output file: ai-docs/shopping-cart-implementation.md
|
||||
|
||||
... (6 parallel agent invocations)
|
||||
|
||||
Phase 3: Integration agent
|
||||
Task: backend-developer
|
||||
Instruction: "Integrate 6 sub-systems. Read output files:
|
||||
ai-docs/*-implementation.md"
|
||||
Output: ai-docs/integration-plan.md
|
||||
|
||||
Total context per agent: ~20k tokens (manageable)
|
||||
vs. Single agent: 120k+ tokens (context overflow risk)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
**multi-agent-coordination + multi-model-validation:**
|
||||
|
||||
```
|
||||
Use Case: Code review with multiple AI models
|
||||
|
||||
Step 1: Agent Selection (multi-agent-coordination)
|
||||
- Detect task type: Code review
|
||||
- Select agents: senior-code-reviewer (embedded) + external models
|
||||
|
||||
Step 2: Parallel Execution (multi-model-validation)
|
||||
- Follow 4-Message Pattern
|
||||
- Launch all reviewers simultaneously
|
||||
- Wait for all to complete
|
||||
|
||||
Step 3: Consolidation (multi-model-validation)
|
||||
- Auto-consolidate reviews
|
||||
- Apply consensus analysis
|
||||
```
|
||||
|
||||
**multi-agent-coordination + quality-gates:**
|
||||
|
||||
```
|
||||
Use Case: Iterative UI validation
|
||||
|
||||
Step 1: Agent Selection (multi-agent-coordination)
|
||||
- Detect task type: UI validation
|
||||
- Select agents: designer, ui-developer
|
||||
|
||||
Step 2: Iteration Loop (quality-gates)
|
||||
- Run designer validation
|
||||
- If not PASS: delegate to ui-developer for fixes
|
||||
- Loop until PASS or max iterations
|
||||
|
||||
Step 3: User Validation Gate (quality-gates)
|
||||
- MANDATORY user approval
|
||||
- Collect feedback if issues found
|
||||
```
|
||||
|
||||
**multi-agent-coordination + todowrite-orchestration:**
|
||||
|
||||
```
|
||||
Use Case: Multi-phase implementation workflow
|
||||
|
||||
Step 1: Initialize TodoWrite (todowrite-orchestration)
|
||||
- Create task list for all phases
|
||||
|
||||
Step 2: Sequential Agent Delegation (multi-agent-coordination)
|
||||
- Phase 1: api-architect
|
||||
- Phase 2: backend-developer (depends on Phase 1)
|
||||
- Phase 3: test-architect (depends on Phase 2)
|
||||
- Update TodoWrite after each phase
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Do:**
|
||||
- ✅ Use parallel execution for independent tasks (3-5x speedup)
|
||||
- ✅ Use sequential execution when there are dependencies
|
||||
- ✅ Use file-based instructions to avoid context pollution
|
||||
- ✅ Return brief summaries (2-5 sentences) from sub-agents
|
||||
- ✅ Select agents based on task type (API/UI/Testing/Review)
|
||||
- ✅ Decompose large tasks into multiple sub-agent calls
|
||||
- ✅ Estimate context usage before delegating
|
||||
|
||||
**Don't:**
|
||||
- ❌ Mix tool types in parallel execution (breaks parallelism)
|
||||
- ❌ Inline long instructions in Task prompts (context pollution)
|
||||
- ❌ Return full output from sub-agents (use files instead)
|
||||
- ❌ Use parallel execution for dependent tasks (wrong results)
|
||||
- ❌ Use single agent for >100k token tasks (context overflow)
|
||||
- ❌ Forget to wait for all parallel tasks before consolidating
|
||||
|
||||
**Performance Tips:**
|
||||
- Parallel execution: 3-5x faster than sequential (5min vs 15min)
|
||||
- File-based delegation: Saves 50-80% context usage
|
||||
- Agent switching: Adapt to user preferences (speed vs quality)
|
||||
- Context decomposition: Enables tasks that would otherwise overflow
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Parallel Multi-Model Code Review
|
||||
|
||||
**Scenario:** User requests "Review my authentication code with Grok and Gemini"
|
||||
|
||||
**Agent Selection:**
|
||||
- Task type: Code review
|
||||
- Agents: senior-code-reviewer (embedded), external Grok, external Gemini
|
||||
|
||||
**Execution:**
|
||||
|
||||
```
|
||||
Message 1: Preparation
|
||||
- Write code context to ai-docs/code-review-context.md
|
||||
|
||||
Message 2: Parallel Execution (3 Task calls in single message)
|
||||
Task: senior-code-reviewer
|
||||
Prompt: "Review ai-docs/code-review-context.md for security issues"
|
||||
---
|
||||
Task: codex-code-reviewer PROXY_MODE: x-ai/grok-code-fast-1
|
||||
Prompt: "Review ai-docs/code-review-context.md for security issues"
|
||||
---
|
||||
Task: codex-code-reviewer PROXY_MODE: google/gemini-2.5-flash
|
||||
Prompt: "Review ai-docs/code-review-context.md for security issues"
|
||||
|
||||
All 3 execute simultaneously (3x faster than sequential)
|
||||
|
||||
Message 3: Auto-Consolidation
|
||||
Task: senior-code-reviewer
|
||||
Prompt: "Consolidate 3 reviews from:
|
||||
- ai-docs/claude-review.md
|
||||
- ai-docs/grok-review.md
|
||||
- ai-docs/gemini-review.md
|
||||
Prioritize by consensus."
|
||||
|
||||
Message 4: Present Results
|
||||
"Review complete. 3 models analyzed your code.
|
||||
Top 5 issues by consensus:
|
||||
1. [UNANIMOUS] Missing input validation on login endpoint
|
||||
2. [STRONG] SQL injection risk in user query
|
||||
3. [MAJORITY] Weak password requirements
|
||||
See ai-docs/consolidated-review.md for details."
|
||||
```
|
||||
|
||||
**Result:** 5 minutes total (vs 15+ if sequential), consensus-based prioritization
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Sequential Multi-Phase Implementation
|
||||
|
||||
**Scenario:** User requests "Implement payment integration feature"
|
||||
|
||||
**Agent Selection:**
|
||||
- Task type: API implementation
|
||||
- Agents: api-architect → backend-developer → test-architect → senior-code-reviewer
|
||||
|
||||
**Execution:**
|
||||
|
||||
```
|
||||
Phase 1: Architecture Planning
|
||||
Write: ai-docs/payment-requirements.md
|
||||
"Integrate Stripe payment processing with webhook support..."
|
||||
|
||||
Task: api-architect
|
||||
Prompt: "Read ai-docs/payment-requirements.md
|
||||
Create architecture plan"
|
||||
Output: ai-docs/payment-architecture.md
|
||||
Return: "Architecture plan complete. Designed 3-layer payment system."
|
||||
|
||||
Wait for completion ✓
|
||||
|
||||
Phase 2: Implementation (depends on Phase 1)
|
||||
Task: backend-developer
|
||||
Prompt: "Read ai-docs/payment-architecture.md
|
||||
Implement payment integration"
|
||||
Output: src/payment.ts, src/webhooks.ts
|
||||
Return: "Payment integration implemented. 2 new files, 500 lines."
|
||||
|
||||
Wait for completion ✓
|
||||
|
||||
Phase 3: Testing (depends on Phase 2)
|
||||
Task: test-architect
|
||||
Prompt: "Write tests for src/payment.ts and src/webhooks.ts"
|
||||
Output: tests/payment.test.ts, tests/webhooks.test.ts
|
||||
Return: "Test suite complete. 20 tests covering payment flows."
|
||||
|
||||
Wait for completion ✓
|
||||
|
||||
Phase 4: Code Review (depends on Phase 3)
|
||||
Task: senior-code-reviewer
|
||||
Prompt: "Review payment integration implementation"
|
||||
Output: ai-docs/payment-review.md
|
||||
Return: "Review complete. 2 MEDIUM issues found."
|
||||
|
||||
Wait for completion ✓
|
||||
```
|
||||
|
||||
**Result:** Sequential execution ensures each phase has correct inputs
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Adaptive Agent Switching
|
||||
|
||||
**Scenario:** User requests "Validate navbar implementation" with optional external AI
|
||||
|
||||
**Agent Selection:**
|
||||
- Task type: UI validation
|
||||
- Base agent: designer
|
||||
- Optional: designer-codex (if user wants external validation)
|
||||
|
||||
**Execution:**
|
||||
|
||||
```
|
||||
Step 1: Ask user preference
|
||||
"Do you want external AI validation? (Yes/No)"
|
||||
|
||||
Step 2a: If user says NO (speed mode)
|
||||
Task: designer
|
||||
Prompt: "Validate navbar against Figma design"
|
||||
Output: ai-docs/design-review.md
|
||||
Return: "Design validation complete. PASS with 2 minor suggestions."
|
||||
|
||||
Step 2b: If user says YES (quality mode)
|
||||
Message 1: Parallel Validation
|
||||
Task: designer
|
||||
Prompt: "Validate navbar against Figma design"
|
||||
---
|
||||
Task: designer PROXY_MODE: design-review-codex
|
||||
Prompt: "Validate navbar against Figma design"
|
||||
|
||||
Message 2: Consolidate
|
||||
Task: designer
|
||||
Prompt: "Consolidate 2 design reviews. Prioritize by consensus."
|
||||
Output: ai-docs/design-review-consolidated.md
|
||||
Return: "Consolidated review complete. Both agree on 1 CRITICAL issue."
|
||||
|
||||
Step 3: User validation
|
||||
Present consolidated review to user for approval
|
||||
```
|
||||
|
||||
**Result:** Adaptive workflow based on user preference (speed vs quality)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Problem: Parallel tasks executing sequentially**
|
||||
|
||||
Cause: Mixed tool types in same message
|
||||
|
||||
Solution: Use 4-Message Pattern with ONLY Task calls in Message 2
|
||||
|
||||
```
|
||||
❌ Wrong:
|
||||
await TodoWrite({...});
|
||||
await Task({...});
|
||||
await Task({...});
|
||||
|
||||
✅ Correct:
|
||||
Message 1: await Bash({...}); (prep only)
|
||||
Message 2: await Task({...}); await Task({...}); (parallel)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Problem: Orchestrator context overflowing**
|
||||
|
||||
Cause: Inline instructions or full output returns
|
||||
|
||||
Solution: Use file-based delegation + brief summaries
|
||||
|
||||
```
|
||||
❌ Wrong:
|
||||
Task: agent
|
||||
Prompt: "[1000 lines of inline requirements]"
|
||||
Return: "[500 lines of full output]"
|
||||
|
||||
✅ Correct:
|
||||
Write: ai-docs/requirements.md
|
||||
Task: agent
|
||||
Prompt: "Read ai-docs/requirements.md"
|
||||
Return: "Complete. See ai-docs/output.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Problem: Wrong agent selected for task**
|
||||
|
||||
Cause: Task type detection failed
|
||||
|
||||
Solution: Explicitly detect task type using keywords
|
||||
|
||||
```
|
||||
Check user request for keywords:
|
||||
- API/endpoint/backend → api-architect, backend-developer
|
||||
- UI/component/design → designer, ui-developer
|
||||
- test/coverage → test-architect
|
||||
- review/validate → senior-code-reviewer
|
||||
|
||||
Default: Ask user to clarify task type
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Problem: Agent returns immediately before external model completes**
|
||||
|
||||
Cause: Background execution (non-blocking claudish call)
|
||||
|
||||
Solution: Use synchronous (blocking) execution
|
||||
|
||||
```
|
||||
❌ Wrong:
|
||||
claudish --model grok ... & (background, returns immediately)
|
||||
|
||||
✅ Correct:
|
||||
RESULT=$(claudish --model grok ...) (blocks until complete)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Multi-agent coordination is about choosing the right execution strategy:
|
||||
|
||||
- **Parallel** when tasks are independent (3-5x speedup)
|
||||
- **Sequential** when tasks have dependencies (correct results)
|
||||
- **File-based delegation** to avoid context pollution (50-80% savings)
|
||||
- **Brief summaries** from sub-agents (clean orchestrator context)
|
||||
- **Task type detection** for intelligent agent selection
|
||||
- **Context decomposition** for large tasks (avoid overflow)
|
||||
|
||||
Master these patterns and you can orchestrate workflows of any complexity.
|
||||
|
||||
---
|
||||
|
||||
**Extracted From:**
|
||||
- `/implement` command (task detection, sequential workflows)
|
||||
- `/validate-ui` command (adaptive agent switching)
|
||||
- `/review` command (parallel execution, 4-Message Pattern)
|
||||
- `CLAUDE.md` Parallel Multi-Model Execution Protocol
|
||||
1005
skills/multi-model-validation/SKILL.md
Normal file
1005
skills/multi-model-validation/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
996
skills/quality-gates/SKILL.md
Normal file
996
skills/quality-gates/SKILL.md
Normal file
@@ -0,0 +1,996 @@
|
||||
---
|
||||
name: quality-gates
|
||||
description: Implement quality gates, user approval, iteration loops, and test-driven development. Use when validating with users, implementing feedback loops, classifying issue severity, running test-driven loops, or building multi-iteration workflows. Trigger keywords - "approval", "user validation", "iteration", "feedback loop", "severity", "test-driven", "TDD", "quality gate", "consensus".
|
||||
version: 0.1.0
|
||||
tags: [orchestration, quality-gates, approval, iteration, feedback, severity, test-driven, TDD]
|
||||
keywords: [approval, validation, iteration, feedback-loop, severity, test-driven, TDD, quality-gate, consensus, user-approval]
|
||||
---
|
||||
|
||||
# Quality Gates
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Purpose:** Patterns for approval gates, iteration loops, and quality validation in multi-agent workflows
|
||||
**Status:** Production Ready
|
||||
|
||||
## Overview
|
||||
|
||||
Quality gates are checkpoints in workflows where execution pauses for validation before proceeding. They prevent low-quality work from advancing through the pipeline and ensure user expectations are met.
|
||||
|
||||
This skill provides battle-tested patterns for:
|
||||
- **User approval gates** (cost gates, quality gates, final acceptance)
|
||||
- **Iteration loops** (automated refinement until quality threshold met)
|
||||
- **Issue severity classification** (CRITICAL, HIGH, MEDIUM, LOW)
|
||||
- **Multi-reviewer consensus** (unanimous vs majority agreement)
|
||||
- **Feedback loops** (user reports issues → agent fixes → user validates)
|
||||
- **Test-driven development loops** (write tests → run → analyze failures → fix → repeat)
|
||||
|
||||
Quality gates transform "fire and forget" workflows into **iterative refinement systems** that consistently produce high-quality results.
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Pattern 1: User Approval Gates
|
||||
|
||||
**When to Ask for Approval:**
|
||||
|
||||
Use approval gates for:
|
||||
- **Cost gates:** Before expensive operations (multi-model review, large-scale refactoring)
|
||||
- **Quality gates:** Before proceeding to next phase (design validation before implementation)
|
||||
- **Final validation:** Before completing workflow (user acceptance testing)
|
||||
- **Irreversible operations:** Before destructive actions (delete files, database migrations)
|
||||
|
||||
**How to Present Approval:**
|
||||
|
||||
```
|
||||
Good Approval Prompt:
|
||||
|
||||
"You selected 5 AI models for code review:
|
||||
- Claude Sonnet (embedded, free)
|
||||
- Grok Code Fast (external, $0.002)
|
||||
- Gemini 2.5 Flash (external, $0.001)
|
||||
- GPT-5 Codex (external, $0.004)
|
||||
- DeepSeek Coder (external, $0.001)
|
||||
|
||||
Estimated total cost: $0.008 ($0.005 - $0.010)
|
||||
Expected duration: ~5 minutes
|
||||
|
||||
Proceed with multi-model review? (Yes/No/Cancel)"
|
||||
|
||||
Why it works:
|
||||
✓ Clear context (what will happen)
|
||||
✓ Cost transparency (range, not single number)
|
||||
✓ Time expectation (5 minutes)
|
||||
✓ Multiple options (Yes/No/Cancel)
|
||||
```
|
||||
|
||||
**Anti-Pattern: Vague Approval**
|
||||
|
||||
```
|
||||
❌ Wrong:
|
||||
|
||||
"This will cost money. Proceed? (Yes/No)"
|
||||
|
||||
Why it fails:
|
||||
✗ No cost details (how much?)
|
||||
✗ No context (what will happen?)
|
||||
✗ No alternatives (what if user says no?)
|
||||
```
|
||||
|
||||
**Handling User Responses:**
|
||||
|
||||
```
|
||||
User says YES:
|
||||
→ Proceed with workflow
|
||||
→ Track approval in logs
|
||||
→ Continue to next step
|
||||
|
||||
User says NO:
|
||||
→ Offer alternatives:
|
||||
1. Use fewer models (reduce cost)
|
||||
2. Use only free embedded Claude
|
||||
3. Skip this step entirely
|
||||
4. Cancel workflow
|
||||
→ Ask user to choose alternative
|
||||
→ Proceed based on choice
|
||||
|
||||
User says CANCEL:
|
||||
→ Gracefully exit workflow
|
||||
→ Save partial results (if any)
|
||||
→ Log cancellation reason
|
||||
→ Clean up temporary files
|
||||
→ Notify user: "Workflow cancelled. Partial results saved to..."
|
||||
```
|
||||
|
||||
**Approval Bypasses (Advanced):**
|
||||
|
||||
For automated workflows, allow approval bypass:
|
||||
|
||||
```
|
||||
Automated Workflow Mode:
|
||||
|
||||
If workflow is triggered by CI/CD or scheduled task:
|
||||
→ Skip user approval gates
|
||||
→ Use predefined defaults (e.g., max cost $0.10)
|
||||
→ Log decisions for audit trail
|
||||
→ Email report to stakeholders after completion
|
||||
|
||||
Example:
|
||||
if (isAutomatedMode) {
|
||||
if (estimatedCost <= maxAutomatedCost) {
|
||||
log("Auto-approved: $0.008 <= $0.10 threshold");
|
||||
proceed();
|
||||
} else {
|
||||
log("Auto-rejected: $0.008 > $0.10 threshold");
|
||||
notifyStakeholders("Cost exceeds automated threshold");
|
||||
abort();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 2: Iteration Loop Patterns
|
||||
|
||||
**Max Iteration Limits:**
|
||||
|
||||
Always set a **max iteration limit** to prevent infinite loops:
|
||||
|
||||
```
|
||||
Typical Iteration Limits:
|
||||
|
||||
Automated quality loops: 10 iterations
|
||||
- Designer validation → Developer fixes → Repeat
|
||||
- Test failures → Developer fixes → Repeat
|
||||
|
||||
User feedback loops: 5 rounds
|
||||
- User reports issues → Developer fixes → User validates → Repeat
|
||||
|
||||
Code review loops: 3 rounds
|
||||
- Reviewer finds issues → Developer fixes → Re-review → Repeat
|
||||
|
||||
Multi-model consensus: 1 iteration (no loop)
|
||||
- Parallel review → Consolidate → Present
|
||||
```
|
||||
|
||||
**Exit Criteria:**
|
||||
|
||||
Define clear **exit criteria** for each loop type:
|
||||
|
||||
```
|
||||
Loop Type: Design Validation
|
||||
|
||||
Exit Criteria (checked after each iteration):
|
||||
1. Designer assessment = PASS → Exit loop (success)
|
||||
2. Iteration count >= 10 → Exit loop (max iterations)
|
||||
3. User manually approves → Exit loop (user override)
|
||||
4. No changes made by developer → Exit loop (stuck, escalate)
|
||||
|
||||
Example:
|
||||
for (let i = 1; i <= 10; i++) {
|
||||
const review = await designer.validate();
|
||||
|
||||
if (review.assessment === "PASS") {
|
||||
log("Design validation passed on iteration " + i);
|
||||
break; // Success exit
|
||||
}
|
||||
|
||||
if (i === 10) {
|
||||
log("Max iterations reached. Escalating to user validation.");
|
||||
break; // Max iterations exit
|
||||
}
|
||||
|
||||
await developer.fix(review.issues);
|
||||
}
|
||||
```
|
||||
|
||||
**Progress Tracking:**
|
||||
|
||||
Show clear progress to user during iterations:
|
||||
|
||||
```
|
||||
Iteration Loop Progress:
|
||||
|
||||
Iteration 1/10: Designer found 5 issues → Developer fixing...
|
||||
Iteration 2/10: Designer found 3 issues → Developer fixing...
|
||||
Iteration 3/10: Designer found 1 issue → Developer fixing...
|
||||
Iteration 4/10: Designer assessment: PASS ✓
|
||||
|
||||
Loop completed in 4 iterations.
|
||||
```
|
||||
|
||||
**Iteration History Documentation:**
|
||||
|
||||
Track what happened in each iteration:
|
||||
|
||||
```
|
||||
Iteration History (ai-docs/iteration-history.md):
|
||||
|
||||
## Iteration 1
|
||||
Designer Assessment: NEEDS IMPROVEMENT
|
||||
Issues Found:
|
||||
- Button color doesn't match design (#3B82F6 vs #2563EB)
|
||||
- Spacing between elements too tight (8px vs 16px)
|
||||
- Font size incorrect (14px vs 16px)
|
||||
Developer Actions:
|
||||
- Updated button color to #2563EB
|
||||
- Increased spacing to 16px
|
||||
- Changed font size to 16px
|
||||
|
||||
## Iteration 2
|
||||
Designer Assessment: NEEDS IMPROVEMENT
|
||||
Issues Found:
|
||||
- Border radius too large (8px vs 4px)
|
||||
Developer Actions:
|
||||
- Reduced border radius to 4px
|
||||
|
||||
## Iteration 3
|
||||
Designer Assessment: PASS ✓
|
||||
Issues Found: None
|
||||
Result: Design validation complete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 3: Issue Severity Classification
|
||||
|
||||
**Severity Levels:**
|
||||
|
||||
Use 4-level severity classification:
|
||||
|
||||
```
|
||||
CRITICAL - Must fix immediately
|
||||
- Blocks core functionality
|
||||
- Security vulnerabilities (SQL injection, XSS, auth bypass)
|
||||
- Data loss risk
|
||||
- System crashes
|
||||
- Build failures
|
||||
|
||||
Action: STOP workflow, fix immediately, re-validate
|
||||
|
||||
HIGH - Should fix soon
|
||||
- Major bugs (incorrect behavior)
|
||||
- Performance issues (>3s page load, memory leaks)
|
||||
- Accessibility violations (keyboard navigation broken)
|
||||
- User experience blockers
|
||||
|
||||
Action: Fix in current iteration, proceed after fix
|
||||
|
||||
MEDIUM - Should fix
|
||||
- Minor bugs (edge cases, visual glitches)
|
||||
- Code quality issues (duplication, complexity)
|
||||
- Non-blocking performance issues
|
||||
- Incomplete error handling
|
||||
|
||||
Action: Fix if time permits, or schedule for next iteration
|
||||
|
||||
LOW - Nice to have
|
||||
- Code style inconsistencies
|
||||
- Minor refactoring opportunities
|
||||
- Documentation improvements
|
||||
- Polish and optimization
|
||||
|
||||
Action: Log for future improvement, proceed without fixing
|
||||
```
|
||||
|
||||
**Severity-Based Prioritization:**
|
||||
|
||||
```
|
||||
Issue List (sorted by severity):
|
||||
|
||||
CRITICAL Issues (must fix all before proceeding):
|
||||
1. SQL injection in user search endpoint
|
||||
2. Missing authentication check on admin routes
|
||||
3. Password stored in plaintext
|
||||
|
||||
HIGH Issues (fix before code review):
|
||||
4. Memory leak in WebSocket connection
|
||||
5. Missing error handling in payment flow
|
||||
6. Accessibility: keyboard navigation broken
|
||||
|
||||
MEDIUM Issues (fix if time permits):
|
||||
7. Code duplication in auth controllers
|
||||
8. Inconsistent error messages
|
||||
9. Missing JSDoc comments
|
||||
|
||||
LOW Issues (defer to future):
|
||||
10. Variable naming inconsistency
|
||||
11. Redundant type annotations
|
||||
12. CSS could use more specificity
|
||||
|
||||
Action Plan:
|
||||
- Fix CRITICAL (1-3) immediately → Re-run tests
|
||||
- Fix HIGH (4-6) before code review
|
||||
- Log MEDIUM (7-9) for next iteration
|
||||
- Ignore LOW (10-12) for now
|
||||
```
|
||||
|
||||
**Severity Escalation:**
|
||||
|
||||
Issues can escalate in severity based on context:
|
||||
|
||||
```
|
||||
Context-Based Escalation:
|
||||
|
||||
Issue: "Missing error handling in payment flow"
|
||||
Base Severity: MEDIUM (code quality issue)
|
||||
|
||||
Context 1: Development environment
|
||||
→ Severity: MEDIUM (not user-facing yet)
|
||||
|
||||
Context 2: Production environment
|
||||
→ Severity: HIGH (affects real users, money involved)
|
||||
|
||||
Context 3: Production + recent payment failures
|
||||
→ Severity: CRITICAL (actively causing issues)
|
||||
|
||||
Rule: Escalate severity when:
|
||||
- Issue affects production users
|
||||
- Issue involves money/security/data
|
||||
- Issue is currently causing failures
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 4: Multi-Reviewer Consensus
|
||||
|
||||
**Consensus Levels:**
|
||||
|
||||
When multiple reviewers evaluate the same code/design:
|
||||
|
||||
```
|
||||
UNANIMOUS (100% agreement):
|
||||
- ALL reviewers flagged this issue
|
||||
- VERY HIGH confidence
|
||||
- Highest priority (likely a real problem)
|
||||
|
||||
Example:
|
||||
3/3 reviewers: "SQL injection in search endpoint"
|
||||
→ UNANIMOUS consensus
|
||||
→ CRITICAL priority (all agree it's critical)
|
||||
|
||||
STRONG CONSENSUS (67-99% agreement):
|
||||
- MOST reviewers flagged this issue
|
||||
- HIGH confidence
|
||||
- High priority (probably a real problem)
|
||||
|
||||
Example:
|
||||
2/3 reviewers: "Missing input validation"
|
||||
→ STRONG consensus (67%)
|
||||
→ HIGH priority
|
||||
|
||||
MAJORITY (50-66% agreement):
|
||||
- HALF or more flagged this issue
|
||||
- MEDIUM confidence
|
||||
- Medium priority (worth investigating)
|
||||
|
||||
Example:
|
||||
2/3 reviewers: "Code duplication in controllers"
|
||||
→ MAJORITY consensus (67%)
|
||||
→ MEDIUM priority
|
||||
|
||||
DIVERGENT (< 50% agreement):
|
||||
- Only 1-2 reviewers flagged this issue
|
||||
- LOW confidence
|
||||
- Low priority (may be model-specific or false positive)
|
||||
|
||||
Example:
|
||||
1/3 reviewers: "Variable naming could be better"
|
||||
→ DIVERGENT (33%)
|
||||
→ LOW priority (one reviewer's opinion)
|
||||
```
|
||||
|
||||
**Consensus-Based Prioritization:**
|
||||
|
||||
```
|
||||
Prioritized Issue List (by consensus + severity):
|
||||
|
||||
1. [UNANIMOUS - CRITICAL] SQL injection in search
|
||||
ALL reviewers agree: Claude, Grok, Gemini (3/3)
|
||||
|
||||
2. [UNANIMOUS - HIGH] Missing input validation
|
||||
ALL reviewers agree: Claude, Grok, Gemini (3/3)
|
||||
|
||||
3. [STRONG - HIGH] Memory leak in WebSocket
|
||||
MOST reviewers agree: Claude, Grok (2/3)
|
||||
|
||||
4. [MAJORITY - MEDIUM] Code duplication
|
||||
HALF+ reviewers agree: Claude, Gemini (2/3)
|
||||
|
||||
5. [DIVERGENT - LOW] Variable naming
|
||||
SINGLE reviewer: Claude only (1/3)
|
||||
|
||||
Action:
|
||||
- Fix issues 1-2 immediately (unanimous + CRITICAL/HIGH)
|
||||
- Fix issue 3 before review (strong consensus)
|
||||
- Consider issue 4 (majority, but medium severity)
|
||||
- Ignore issue 5 (divergent, likely false positive)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 5: Feedback Loop Implementation
|
||||
|
||||
**User Feedback Loop:**
|
||||
|
||||
```
|
||||
Workflow: User Validation with Feedback
|
||||
|
||||
Step 1: Initial Implementation
|
||||
Developer implements feature
|
||||
Designer/Tester validates
|
||||
Present to user for manual validation
|
||||
|
||||
Step 2: User Validation Gate (MANDATORY)
|
||||
Present to user:
|
||||
"Implementation complete. Please manually verify:
|
||||
- Open app at http://localhost:3000
|
||||
- Test feature: [specific instructions]
|
||||
- Compare to design reference
|
||||
|
||||
Does it meet expectations? (Yes/No)"
|
||||
|
||||
Step 3a: User says YES
|
||||
→ ✅ Feature approved
|
||||
→ Generate final report
|
||||
→ Mark workflow complete
|
||||
|
||||
Step 3b: User says NO
|
||||
→ Collect specific feedback
|
||||
|
||||
Step 4: Collect Specific Feedback
|
||||
Ask user: "Please describe the issues you found:"
|
||||
|
||||
User response:
|
||||
"1. Button color is wrong (should be blue, not green)
|
||||
2. Spacing is too tight between elements
|
||||
3. Font size is too small"
|
||||
|
||||
Step 5: Extract Structured Feedback
|
||||
Parse user feedback into structured issues:
|
||||
|
||||
Issue 1:
|
||||
Component: Button
|
||||
Problem: Color incorrect
|
||||
Expected: Blue (#2563EB)
|
||||
Actual: Green (#10B981)
|
||||
Severity: MEDIUM
|
||||
|
||||
Issue 2:
|
||||
Component: Container
|
||||
Problem: Spacing too tight
|
||||
Expected: 16px
|
||||
Actual: 8px
|
||||
Severity: MEDIUM
|
||||
|
||||
Issue 3:
|
||||
Component: Text
|
||||
Problem: Font size too small
|
||||
Expected: 16px
|
||||
Actual: 14px
|
||||
Severity: LOW
|
||||
|
||||
Step 6: Launch Fixing Agent
|
||||
Task: ui-developer
|
||||
Prompt: "Fix user-reported issues:
|
||||
|
||||
1. Button color: Change from #10B981 to #2563EB
|
||||
2. Container spacing: Increase from 8px to 16px
|
||||
3. Text font size: Increase from 14px to 16px
|
||||
|
||||
User feedback: [user's exact words]"
|
||||
|
||||
Step 7: Re-validate
|
||||
After fixes:
|
||||
- Re-run designer validation
|
||||
- Loop back to Step 2 (user validation)
|
||||
|
||||
Step 8: Max Feedback Rounds
|
||||
Limit: 5 feedback rounds (prevent infinite loop)
|
||||
|
||||
If round > 5:
|
||||
Escalate to human review
|
||||
"Unable to meet user expectations after 5 rounds.
|
||||
Manual intervention required."
|
||||
```
|
||||
|
||||
**Feedback Round Tracking:**
|
||||
|
||||
```
|
||||
Feedback Round History:
|
||||
|
||||
Round 1:
|
||||
User Issues: Button color, spacing, font size
|
||||
Fixes Applied: Updated all 3 issues
|
||||
Result: Re-validate
|
||||
|
||||
Round 2:
|
||||
User Issues: Border radius too large
|
||||
Fixes Applied: Reduced border radius
|
||||
Result: Re-validate
|
||||
|
||||
Round 3:
|
||||
User Issues: None
|
||||
Result: ✅ APPROVED
|
||||
|
||||
Total Rounds: 3/5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 6: Test-Driven Development Loop
|
||||
|
||||
**When to Use:**
|
||||
|
||||
Use TDD loop **after implementing code, before code review**:
|
||||
|
||||
```
|
||||
Workflow Phases:
|
||||
|
||||
Phase 1: Architecture Planning
|
||||
Phase 2: Implementation
|
||||
Phase 2.5: Test-Driven Development Loop ← THIS PATTERN
|
||||
Phase 3: Code Review
|
||||
Phase 4: User Acceptance
|
||||
```
|
||||
|
||||
**The TDD Loop Pattern:**
|
||||
|
||||
```
|
||||
Step 1: Write Tests First
|
||||
Task: test-architect
|
||||
Prompt: "Write comprehensive tests for authentication feature.
|
||||
Requirements: [link to requirements]
|
||||
Implementation: [link to code]"
|
||||
Output: tests/auth.test.ts
|
||||
|
||||
Step 2: Run Tests
|
||||
Bash: bun test tests/auth.test.ts
|
||||
Capture output and exit code
|
||||
|
||||
Step 3: Check Test Results
|
||||
If all tests pass:
|
||||
→ ✅ TDD loop complete
|
||||
→ Proceed to code review (Phase 3)
|
||||
|
||||
If tests fail:
|
||||
→ Analyze failure (continue to Step 4)
|
||||
|
||||
Step 4: Analyze Test Failure
|
||||
Task: test-architect
|
||||
Prompt: "Analyze test failure output:
|
||||
|
||||
[test failure logs]
|
||||
|
||||
Determine root cause:
|
||||
- TEST_ISSUE: Test has bug (bad assertion, missing mock, wrong expectation)
|
||||
- IMPLEMENTATION_ISSUE: Code has bug (logic error, missing validation, incorrect behavior)
|
||||
|
||||
Provide detailed analysis."
|
||||
|
||||
test-architect returns:
|
||||
verdict: TEST_ISSUE | IMPLEMENTATION_ISSUE
|
||||
analysis: Detailed explanation
|
||||
recommendation: Specific fix needed
|
||||
|
||||
Step 5a: If TEST_ISSUE (test is wrong)
|
||||
Task: test-architect
|
||||
Prompt: "Fix test based on analysis:
|
||||
[analysis from Step 4]"
|
||||
|
||||
After fix:
|
||||
→ Re-run tests (back to Step 2)
|
||||
→ Loop continues
|
||||
|
||||
Step 5b: If IMPLEMENTATION_ISSUE (code is wrong)
|
||||
Provide structured feedback to developer:
|
||||
|
||||
Task: backend-developer
|
||||
Prompt: "Fix implementation based on test failure:
|
||||
|
||||
Test Failure:
|
||||
[failure output]
|
||||
|
||||
Root Cause:
|
||||
[analysis from test-architect]
|
||||
|
||||
Recommended Fix:
|
||||
[specific fix needed]"
|
||||
|
||||
After fix:
|
||||
→ Re-run tests (back to Step 2)
|
||||
→ Loop continues
|
||||
|
||||
Step 6: Max Iteration Limit
|
||||
Limit: 10 iterations
|
||||
|
||||
Iteration tracking:
|
||||
Iteration 1/10: 5 tests failed → Fix implementation
|
||||
Iteration 2/10: 2 tests failed → Fix test (bad mock)
|
||||
Iteration 3/10: All tests pass ✅
|
||||
|
||||
If iteration > 10:
|
||||
Escalate to human review
|
||||
"Unable to pass all tests after 10 iterations.
|
||||
Manual debugging required."
|
||||
```
|
||||
|
||||
**Example TDD Loop:**
|
||||
|
||||
```
|
||||
Phase 2.5: Test-Driven Development Loop
|
||||
|
||||
Iteration 1:
|
||||
Tests Run: 20 tests
|
||||
Results: 5 failed, 15 passed
|
||||
Failure: "JWT token validation fails with expired token"
|
||||
Analysis: IMPLEMENTATION_ISSUE - Missing expiration check
|
||||
Fix: Added expiration validation in TokenService
|
||||
Re-run: Continue to Iteration 2
|
||||
|
||||
Iteration 2:
|
||||
Tests Run: 20 tests
|
||||
Results: 2 failed, 18 passed
|
||||
Failure: "Mock database not reset between tests"
|
||||
Analysis: TEST_ISSUE - Missing beforeEach cleanup
|
||||
Fix: Added database reset in test setup
|
||||
Re-run: Continue to Iteration 3
|
||||
|
||||
Iteration 3:
|
||||
Tests Run: 20 tests
|
||||
Results: All passed ✅
|
||||
Result: TDD loop complete, proceed to code review
|
||||
|
||||
Total Iterations: 3/10
|
||||
Duration: ~5 minutes
|
||||
Benefits:
|
||||
- Caught 2 bugs before code review
|
||||
- Fixed 1 test quality issue
|
||||
- All tests passing gives confidence in implementation
|
||||
```
|
||||
|
||||
**Benefits of TDD Loop:**
|
||||
|
||||
```
|
||||
Benefits:
|
||||
|
||||
1. Catch bugs early (before code review, not after)
|
||||
2. Ensure test quality (test-architect fixes bad tests)
|
||||
3. Automated quality assurance (no manual testing needed)
|
||||
4. Fast feedback loop (seconds to run tests, not minutes)
|
||||
5. Confidence in implementation (all tests passing)
|
||||
|
||||
Performance:
|
||||
Traditional: Implement → Review → Find bugs → Fix → Re-review
|
||||
Time: 30+ minutes, multiple review rounds
|
||||
|
||||
TDD Loop: Implement → Test → Fix → Test → Review (with confidence)
|
||||
Time: 15 minutes, single review round (fewer issues)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
**quality-gates + multi-model-validation:**
|
||||
|
||||
```
|
||||
Use Case: Cost approval before multi-model review
|
||||
|
||||
Step 1: Estimate costs (multi-model-validation)
|
||||
Step 2: User approval gate (quality-gates)
|
||||
If approved: Proceed with parallel execution
|
||||
If rejected: Offer alternatives
|
||||
Step 3: Execute review (multi-model-validation)
|
||||
```
|
||||
|
||||
**quality-gates + multi-agent-coordination:**
|
||||
|
||||
```
|
||||
Use Case: Iteration loop with designer validation
|
||||
|
||||
Step 1: Agent selection (multi-agent-coordination)
|
||||
Select designer + ui-developer
|
||||
|
||||
Step 2: Iteration loop (quality-gates)
|
||||
For i = 1 to 10:
|
||||
- Run designer validation
|
||||
- If PASS: Exit loop
|
||||
- Else: Delegate to ui-developer for fixes
|
||||
|
||||
Step 3: User validation gate (quality-gates)
|
||||
Mandatory manual approval
|
||||
```
|
||||
|
||||
**quality-gates + error-recovery:**
|
||||
|
||||
```
|
||||
Use Case: Test-driven loop with error recovery
|
||||
|
||||
Step 1: Run tests (quality-gates TDD pattern)
|
||||
Step 2: If test execution fails (error-recovery)
|
||||
- Syntax error → Fix and retry
|
||||
- Framework crash → Notify user, skip TDD
|
||||
Step 3: If tests pass (quality-gates)
|
||||
- Proceed to code review
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Do:**
|
||||
- ✅ Set max iteration limits (prevent infinite loops)
|
||||
- ✅ Define clear exit criteria (PASS, max iterations, user override)
|
||||
- ✅ Track iteration history (document what happened)
|
||||
- ✅ Show progress to user ("Iteration 3/10 complete")
|
||||
- ✅ Classify issue severity (CRITICAL → HIGH → MEDIUM → LOW)
|
||||
- ✅ Prioritize by consensus + severity
|
||||
- ✅ Ask user approval for expensive operations
|
||||
- ✅ Collect specific feedback (not vague complaints)
|
||||
- ✅ Use TDD loop to catch bugs early
|
||||
|
||||
**Don't:**
|
||||
- ❌ Create infinite loops (no exit criteria)
|
||||
- ❌ Skip user validation gates (mandatory for UX)
|
||||
- ❌ Ignore consensus (unanimous issues are real)
|
||||
- ❌ Batch all severities together (prioritize CRITICAL)
|
||||
- ❌ Proceed without approval for >$0.01 operations
|
||||
- ❌ Collect vague feedback ("it's wrong" → what specifically?)
|
||||
- ❌ Skip TDD loop (catches bugs before expensive review)
|
||||
|
||||
**Performance:**
|
||||
- Iteration loops: 5-10 iterations typical, max 10-15 min
|
||||
- TDD loop: 3-5 iterations typical, max 5-10 min
|
||||
- User feedback: 1-3 rounds typical, max 5 rounds
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: User Approval Gate for Multi-Model Review
|
||||
|
||||
**Scenario:** User requests multi-model review, costs $0.008
|
||||
|
||||
**Execution:**
|
||||
|
||||
```
|
||||
Step 1: Estimate Costs
|
||||
Input: 450 lines × 1.5 = 675 tokens per model
|
||||
Output: 2000-4000 tokens per model
|
||||
Total: 3 models × 3000 avg = 9000 output tokens
|
||||
Cost: ~$0.008 ($0.005 - $0.010)
|
||||
|
||||
Step 2: Present Approval Gate
|
||||
"Multi-model review will analyze 450 lines with 3 AI models:
|
||||
- Claude Sonnet (embedded, free)
|
||||
- Grok Code Fast (external, $0.002)
|
||||
- Gemini 2.5 Flash (external, $0.001)
|
||||
|
||||
Estimated cost: $0.008 ($0.005 - $0.010)
|
||||
Duration: ~5 minutes
|
||||
|
||||
Proceed? (Yes/No/Cancel)"
|
||||
|
||||
Step 3a: User says YES
|
||||
→ Proceed with parallel execution
|
||||
→ Track approval: log("User approved $0.008 cost")
|
||||
|
||||
Step 3b: User says NO
|
||||
→ Offer alternatives:
|
||||
1. Use only free Claude (no external models)
|
||||
2. Use only 1 external model (reduce cost to $0.002)
|
||||
3. Skip review entirely
|
||||
→ Ask user to choose
|
||||
|
||||
Step 3c: User says CANCEL
|
||||
→ Exit gracefully
|
||||
→ Log: "User cancelled multi-model review"
|
||||
→ Clean up temporary files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Designer Validation Iteration Loop
|
||||
|
||||
**Scenario:** UI implementation with automated iteration until PASS
|
||||
|
||||
**Execution:**
|
||||
|
||||
```
|
||||
Iteration 1:
|
||||
Task: designer
|
||||
Prompt: "Validate navbar against Figma design"
|
||||
Output: ai-docs/design-review-1.md
|
||||
Assessment: NEEDS IMPROVEMENT
|
||||
Issues:
|
||||
- Button color: #3B82F6 (expected #2563EB)
|
||||
- Spacing: 8px (expected 16px)
|
||||
|
||||
Task: ui-developer
|
||||
Prompt: "Fix issues from ai-docs/design-review-1.md"
|
||||
Changes: Updated button color, increased spacing
|
||||
|
||||
Result: Continue to Iteration 2
|
||||
|
||||
Iteration 2:
|
||||
Task: designer
|
||||
Prompt: "Re-validate navbar"
|
||||
Output: ai-docs/design-review-2.md
|
||||
Assessment: NEEDS IMPROVEMENT
|
||||
Issues:
|
||||
- Border radius: 8px (expected 4px)
|
||||
|
||||
Task: ui-developer
|
||||
Prompt: "Fix border radius issue"
|
||||
Changes: Reduced border radius to 4px
|
||||
|
||||
Result: Continue to Iteration 3
|
||||
|
||||
Iteration 3:
|
||||
Task: designer
|
||||
Prompt: "Re-validate navbar"
|
||||
Output: ai-docs/design-review-3.md
|
||||
Assessment: PASS ✓
|
||||
Issues: None
|
||||
|
||||
Result: Exit loop (success)
|
||||
|
||||
Summary:
|
||||
Total Iterations: 3/10
|
||||
Duration: ~8 minutes
|
||||
Automated Fixes: 3 issues resolved
|
||||
Result: PASS, proceed to user validation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Test-Driven Development Loop
|
||||
|
||||
**Scenario:** Authentication implementation with TDD
|
||||
|
||||
**Execution:**
|
||||
|
||||
```
|
||||
Phase 2.5: Test-Driven Development Loop
|
||||
|
||||
Iteration 1:
|
||||
Task: test-architect
|
||||
Prompt: "Write tests for authentication feature"
|
||||
Output: tests/auth.test.ts (20 tests)
|
||||
|
||||
Bash: bun test tests/auth.test.ts
|
||||
Result: 5 failed, 15 passed
|
||||
|
||||
Task: test-architect
|
||||
Prompt: "Analyze test failures"
|
||||
Verdict: IMPLEMENTATION_ISSUE
|
||||
Analysis: "Missing JWT expiration validation"
|
||||
|
||||
Task: backend-developer
|
||||
Prompt: "Add JWT expiration validation"
|
||||
Changes: Updated TokenService.verify()
|
||||
|
||||
Bash: bun test tests/auth.test.ts
|
||||
Result: Continue to Iteration 2
|
||||
|
||||
Iteration 2:
|
||||
Bash: bun test tests/auth.test.ts
|
||||
Result: 2 failed, 18 passed
|
||||
|
||||
Task: test-architect
|
||||
Prompt: "Analyze test failures"
|
||||
Verdict: TEST_ISSUE
|
||||
Analysis: "Mock database not reset between tests"
|
||||
|
||||
Task: test-architect
|
||||
Prompt: "Fix test setup"
|
||||
Changes: Added beforeEach cleanup
|
||||
|
||||
Bash: bun test tests/auth.test.ts
|
||||
Result: Continue to Iteration 3
|
||||
|
||||
Iteration 3:
|
||||
Bash: bun test tests/auth.test.ts
|
||||
Result: All 20 passed ✅
|
||||
|
||||
Result: TDD loop complete, proceed to code review
|
||||
|
||||
Summary:
|
||||
Total Iterations: 3/10
|
||||
Duration: ~5 minutes
|
||||
Bugs Caught: 1 implementation bug, 1 test bug
|
||||
Result: All tests passing, high confidence in code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Problem: Infinite iteration loop**
|
||||
|
||||
Cause: No exit criteria or max iteration limit
|
||||
|
||||
Solution: Always set max iterations (10 for automated, 5 for user feedback)
|
||||
|
||||
```
|
||||
❌ Wrong:
|
||||
while (true) {
|
||||
if (review.assessment === "PASS") break;
|
||||
fix();
|
||||
}
|
||||
|
||||
✅ Correct:
|
||||
for (let i = 1; i <= 10; i++) {
|
||||
if (review.assessment === "PASS") break;
|
||||
if (i === 10) escalateToUser();
|
||||
fix();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Problem: User approval skipped for expensive operation**
|
||||
|
||||
Cause: Missing approval gate
|
||||
|
||||
Solution: Always ask approval for costs >$0.01
|
||||
|
||||
```
|
||||
❌ Wrong:
|
||||
if (userRequestedMultiModel) {
|
||||
executeReview();
|
||||
}
|
||||
|
||||
✅ Correct:
|
||||
if (userRequestedMultiModel) {
|
||||
const cost = estimateCost();
|
||||
if (cost > 0.01) {
|
||||
const approved = await askUserApproval(cost);
|
||||
if (!approved) return offerAlternatives();
|
||||
}
|
||||
executeReview();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Problem: All issues treated equally**
|
||||
|
||||
Cause: No severity classification
|
||||
|
||||
Solution: Classify by severity, prioritize CRITICAL
|
||||
|
||||
```
|
||||
❌ Wrong:
|
||||
issues.forEach(issue => fix(issue));
|
||||
|
||||
✅ Correct:
|
||||
const critical = issues.filter(i => i.severity === "CRITICAL");
|
||||
const high = issues.filter(i => i.severity === "HIGH");
|
||||
|
||||
critical.forEach(issue => fix(issue)); // Fix critical first
|
||||
high.forEach(issue => fix(issue)); // Then high
|
||||
// MEDIUM and LOW deferred or skipped
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Quality gates ensure high-quality results through:
|
||||
|
||||
- **User approval gates** (cost, quality, final validation)
|
||||
- **Iteration loops** (automated refinement, max 10 iterations)
|
||||
- **Severity classification** (CRITICAL → HIGH → MEDIUM → LOW)
|
||||
- **Consensus prioritization** (unanimous → strong → majority → divergent)
|
||||
- **Feedback loops** (collect specific issues, fix, re-validate)
|
||||
- **Test-driven development** (write tests, run, fix, repeat until pass)
|
||||
|
||||
Master these patterns and your workflows will consistently produce high-quality, validated results.
|
||||
|
||||
---
|
||||
|
||||
**Extracted From:**
|
||||
- `/review` command (user approval for costs, consensus analysis)
|
||||
- `/validate-ui` command (iteration loops, user validation gates, feedback collection)
|
||||
- `/implement` command (PHASE 2.5 test-driven development loop)
|
||||
- Multi-model review patterns (consensus-based prioritization)
|
||||
983
skills/todowrite-orchestration/SKILL.md
Normal file
983
skills/todowrite-orchestration/SKILL.md
Normal file
@@ -0,0 +1,983 @@
|
||||
---
|
||||
name: todowrite-orchestration
|
||||
description: Track progress in multi-phase workflows with TodoWrite. Use when orchestrating 5+ phase commands, managing iteration loops, tracking parallel tasks, or providing real-time progress visibility. Trigger keywords - "phase tracking", "progress", "workflow", "multi-step", "multi-phase", "todo", "tracking", "status".
|
||||
version: 0.1.0
|
||||
tags: [orchestration, todowrite, progress, tracking, workflow, multi-phase]
|
||||
keywords: [phase-tracking, progress, workflow, multi-step, multi-phase, todo, tracking, status, visibility]
|
||||
---
|
||||
|
||||
# TodoWrite Orchestration
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Purpose:** Patterns for using TodoWrite in complex multi-phase workflows
|
||||
**Status:** Production Ready
|
||||
|
||||
## Overview
|
||||
|
||||
TodoWrite orchestration is the practice of using the TodoWrite tool to provide **real-time progress visibility** in complex multi-phase workflows. It transforms opaque "black box" workflows into transparent, trackable processes where users can see:
|
||||
|
||||
- What phase is currently executing
|
||||
- How many phases remain
|
||||
- Which tasks are pending, in-progress, or completed
|
||||
- Overall progress percentage
|
||||
- Iteration counts in loops
|
||||
|
||||
This skill provides battle-tested patterns for:
|
||||
- **Phase initialization** (create complete task list before starting)
|
||||
- **Task granularity** (how to break phases into trackable tasks)
|
||||
- **Status transitions** (pending → in_progress → completed)
|
||||
- **Real-time updates** (mark complete immediately, not batched)
|
||||
- **Iteration tracking** (progress through loops)
|
||||
- **Parallel task tracking** (multiple agents executing simultaneously)
|
||||
|
||||
TodoWrite orchestration is especially valuable for workflows with >5 phases or >10 minutes duration, where users need progress feedback.
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Pattern 1: Phase Initialization
|
||||
|
||||
**Create TodoWrite List BEFORE Starting:**
|
||||
|
||||
Initialize TodoWrite as **step 0** of your workflow, before any actual work begins:
|
||||
|
||||
```
|
||||
✅ CORRECT - Initialize First:
|
||||
|
||||
Step 0: Initialize TodoWrite
|
||||
TodoWrite: Create task list
|
||||
- PHASE 1: Gather user inputs
|
||||
- PHASE 1: Validate inputs
|
||||
- PHASE 2: Select AI models
|
||||
- PHASE 2: Estimate costs
|
||||
- PHASE 2: Get user approval
|
||||
- PHASE 3: Launch parallel reviews
|
||||
- PHASE 3: Wait for all reviews
|
||||
- PHASE 4: Consolidate reviews
|
||||
- PHASE 5: Present results
|
||||
|
||||
Step 1: Start actual work (PHASE 1)
|
||||
Mark "PHASE 1: Gather user inputs" as in_progress
|
||||
... do work ...
|
||||
Mark "PHASE 1: Gather user inputs" as completed
|
||||
Mark "PHASE 1: Validate inputs" as in_progress
|
||||
... do work ...
|
||||
|
||||
❌ WRONG - Create During Workflow:
|
||||
|
||||
Step 1: Do some work
|
||||
... work happens ...
|
||||
TodoWrite: Create task "Did some work" (completed)
|
||||
|
||||
Step 2: Do more work
|
||||
... work happens ...
|
||||
TodoWrite: Create task "Did more work" (completed)
|
||||
|
||||
Problem: User has no visibility into upcoming phases
|
||||
```
|
||||
|
||||
**List All Phases Upfront:**
|
||||
|
||||
When initializing, include **all phases** in the task list, not just the current phase:
|
||||
|
||||
```
|
||||
✅ CORRECT - Complete Visibility:
|
||||
|
||||
TodoWrite Initial State:
|
||||
[ ] PHASE 1: Gather user inputs
|
||||
[ ] PHASE 1: Validate inputs
|
||||
[ ] PHASE 2: Architecture planning
|
||||
[ ] PHASE 3: Implementation
|
||||
[ ] PHASE 3: Run quality checks
|
||||
[ ] PHASE 4: Code review
|
||||
[ ] PHASE 5: User acceptance
|
||||
[ ] PHASE 6: Generate report
|
||||
|
||||
User sees: "8 tasks total, 0 complete, Phase 1 starting"
|
||||
|
||||
❌ WRONG - Incremental Discovery:
|
||||
|
||||
TodoWrite Initial State:
|
||||
[ ] PHASE 1: Gather user inputs
|
||||
[ ] PHASE 1: Validate inputs
|
||||
|
||||
(User thinks workflow is 2 tasks, then surprised by 6 more phases)
|
||||
```
|
||||
|
||||
**Why Initialize First:**
|
||||
|
||||
1. **User expectation setting:** User knows workflow scope (8 phases, ~20 minutes)
|
||||
2. **Progress visibility:** User can see % complete (3/8 = 37.5%)
|
||||
3. **Time estimation:** User can estimate remaining time based on progress
|
||||
4. **Transparency:** No hidden phases or surprises
|
||||
|
||||
---
|
||||
|
||||
### Pattern 2: Task Granularity Guidelines
|
||||
|
||||
**One Task Per Significant Operation:**
|
||||
|
||||
Each task should represent a **significant operation** (1-5 minutes of work):
|
||||
|
||||
```
|
||||
✅ CORRECT - Significant Operations:
|
||||
|
||||
Tasks:
|
||||
- PHASE 1: Ask user for inputs (30s)
|
||||
- PHASE 2: Generate architecture plan (2 min)
|
||||
- PHASE 3: Implement feature (5 min)
|
||||
- PHASE 4: Run tests (1 min)
|
||||
- PHASE 5: Code review (3 min)
|
||||
|
||||
Each task = meaningful unit of work
|
||||
|
||||
❌ WRONG - Too Granular:
|
||||
|
||||
Tasks:
|
||||
- PHASE 1: Ask user question 1
|
||||
- PHASE 1: Ask user question 2
|
||||
- PHASE 1: Ask user question 3
|
||||
- PHASE 2: Read file A
|
||||
- PHASE 2: Read file B
|
||||
- PHASE 2: Write file C
|
||||
- ... (50 micro-tasks)
|
||||
|
||||
Problem: Too many updates, clutters user interface
|
||||
```
|
||||
|
||||
**Multi-Step Phases: Break Into 2-3 Sub-Tasks:**
|
||||
|
||||
For complex phases (>5 minutes), break into 2-3 sub-tasks:
|
||||
|
||||
```
|
||||
✅ CORRECT - Sub-Task Breakdown:
|
||||
|
||||
PHASE 3: Implementation (15 min total)
|
||||
→ Sub-tasks:
|
||||
- PHASE 3: Implement core logic (5 min)
|
||||
- PHASE 3: Add error handling (3 min)
|
||||
- PHASE 3: Write tests (7 min)
|
||||
|
||||
User sees progress within phase: "PHASE 3: 2/3 complete"
|
||||
|
||||
❌ WRONG - Single Monolithic Task:
|
||||
|
||||
PHASE 3: Implementation (15 min)
|
||||
→ No sub-tasks
|
||||
|
||||
Problem: User sees "in_progress" for 15 min with no updates
|
||||
```
|
||||
|
||||
**Avoid Too Many Tasks:**
|
||||
|
||||
Limit to **max 15-20 tasks** for readability:
|
||||
|
||||
```
|
||||
✅ CORRECT - 12 Tasks (readable):
|
||||
|
||||
10-phase workflow:
|
||||
- PHASE 1: Ask user
|
||||
- PHASE 2: Plan (2 sub-tasks)
|
||||
- PHASE 3: Implement (3 sub-tasks)
|
||||
- PHASE 4: Test
|
||||
- PHASE 5: Review (2 sub-tasks)
|
||||
- PHASE 6: Fix issues
|
||||
- PHASE 7: Re-review
|
||||
- PHASE 8: Accept
|
||||
|
||||
Total: 12 tasks (clean, trackable)
|
||||
|
||||
❌ WRONG - 50 Tasks (overwhelming):
|
||||
|
||||
Every single action as separate task:
|
||||
- Read file 1
|
||||
- Read file 2
|
||||
- Write file 3
|
||||
- Run command 1
|
||||
- ... (50 tasks)
|
||||
|
||||
Problem: User overwhelmed, can't see forest for trees
|
||||
```
|
||||
|
||||
**Guideline by Workflow Duration:**
|
||||
|
||||
```
|
||||
Workflow Duration → Task Count:
|
||||
|
||||
< 5 minutes: 3-5 tasks
|
||||
5-15 minutes: 8-12 tasks
|
||||
15-30 minutes: 12-18 tasks
|
||||
> 30 minutes: 15-20 tasks (if more, group into phases)
|
||||
|
||||
Example:
|
||||
5-minute workflow (3 phases):
|
||||
- PHASE 1: Prepare
|
||||
- PHASE 2: Execute
|
||||
- PHASE 3: Present
|
||||
Total: 3 tasks ✓
|
||||
|
||||
20-minute workflow (6 phases):
|
||||
- PHASE 1: Ask user
|
||||
- PHASE 2: Plan (2 sub-tasks)
|
||||
- PHASE 3: Implement (3 sub-tasks)
|
||||
- PHASE 4: Test
|
||||
- PHASE 5: Review (2 sub-tasks)
|
||||
- PHASE 6: Accept
|
||||
Total: 11 tasks ✓
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 3: Status Transitions
|
||||
|
||||
**Exactly ONE Task In Progress at a Time:**
|
||||
|
||||
Maintain the invariant: **exactly one task in_progress** at any moment:
|
||||
|
||||
```
|
||||
✅ CORRECT - One In-Progress:
|
||||
|
||||
State at time T1:
|
||||
[✓] PHASE 1: Ask user (completed)
|
||||
[✓] PHASE 2: Plan (completed)
|
||||
[→] PHASE 3: Implement (in_progress) ← Only one
|
||||
[ ] PHASE 4: Test (pending)
|
||||
[ ] PHASE 5: Review (pending)
|
||||
|
||||
State at time T2 (after PHASE 3 completes):
|
||||
[✓] PHASE 1: Ask user (completed)
|
||||
[✓] PHASE 2: Plan (completed)
|
||||
[✓] PHASE 3: Implement (completed)
|
||||
[→] PHASE 4: Test (in_progress) ← Only one
|
||||
[ ] PHASE 5: Review (pending)
|
||||
|
||||
❌ WRONG - Multiple In-Progress:
|
||||
|
||||
State:
|
||||
[✓] PHASE 1: Ask user (completed)
|
||||
[→] PHASE 2: Plan (in_progress) ← Two in-progress?
|
||||
[→] PHASE 3: Implement (in_progress) ← Confusing!
|
||||
[ ] PHASE 4: Test (pending)
|
||||
|
||||
Problem: User confused about current phase
|
||||
```
|
||||
|
||||
**Status Transition Sequence:**
|
||||
|
||||
```
|
||||
Lifecycle of a Task:
|
||||
|
||||
1. Created: pending
|
||||
(Task exists, not started yet)
|
||||
|
||||
2. Started: pending → in_progress
|
||||
(Mark as in_progress when starting work)
|
||||
|
||||
3. Completed: in_progress → completed
|
||||
(Mark as completed immediately after finishing)
|
||||
|
||||
4. Next task: Mark next task as in_progress
|
||||
(Continue to next task)
|
||||
|
||||
Example Timeline:
|
||||
|
||||
T=0s: [→] Task 1 (in_progress), [ ] Task 2 (pending)
|
||||
T=30s: [✓] Task 1 (completed), [→] Task 2 (in_progress)
|
||||
T=60s: [✓] Task 1 (completed), [✓] Task 2 (completed)
|
||||
```
|
||||
|
||||
**NEVER Batch Completions:**
|
||||
|
||||
Mark tasks completed **immediately** after finishing, not at end of phase:
|
||||
|
||||
```
|
||||
✅ CORRECT - Immediate Updates:
|
||||
|
||||
Mark "PHASE 1: Ask user" as in_progress
|
||||
... do work (30s) ...
|
||||
Mark "PHASE 1: Ask user" as completed ← Immediate
|
||||
|
||||
Mark "PHASE 1: Validate inputs" as in_progress
|
||||
... do work (20s) ...
|
||||
Mark "PHASE 1: Validate inputs" as completed ← Immediate
|
||||
|
||||
User sees real-time progress
|
||||
|
||||
❌ WRONG - Batched Updates:
|
||||
|
||||
Mark "PHASE 1: Ask user" as in_progress
|
||||
... do work (30s) ...
|
||||
|
||||
Mark "PHASE 1: Validate inputs" as in_progress
|
||||
... do work (20s) ...
|
||||
|
||||
(At end of PHASE 1, batch update both to completed)
|
||||
|
||||
Problem: User doesn't see progress for 50s, thinks workflow is stuck
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 4: Real-Time Progress Tracking
|
||||
|
||||
**Update TodoWrite As Work Progresses:**
|
||||
|
||||
TodoWrite should reflect **current state**, not past state:
|
||||
|
||||
```
|
||||
✅ CORRECT - Real-Time Updates:
|
||||
|
||||
T=0s: Initialize TodoWrite (8 tasks, all pending)
|
||||
T=5s: Mark "PHASE 1" as in_progress
|
||||
T=35s: Mark "PHASE 1" as completed, "PHASE 2" as in_progress
|
||||
T=90s: Mark "PHASE 2" as completed, "PHASE 3" as in_progress
|
||||
...
|
||||
|
||||
User always sees accurate current state
|
||||
|
||||
❌ WRONG - Delayed Updates:
|
||||
|
||||
T=0s: Initialize TodoWrite
|
||||
T=300s: Workflow completes
|
||||
T=301s: Update all tasks to completed
|
||||
|
||||
Problem: No progress visibility for 5 minutes
|
||||
```
|
||||
|
||||
**Add New Tasks If Discovered During Execution:**
|
||||
|
||||
If you discover additional work during execution, add new tasks:
|
||||
|
||||
```
|
||||
Scenario: During implementation, realize refactoring needed
|
||||
|
||||
Initial TodoWrite:
|
||||
[✓] PHASE 1: Plan
|
||||
[→] PHASE 2: Implement
|
||||
[ ] PHASE 3: Test
|
||||
[ ] PHASE 4: Review
|
||||
|
||||
During PHASE 2, discover:
|
||||
"Implementation requires refactoring legacy code"
|
||||
|
||||
Updated TodoWrite:
|
||||
[✓] PHASE 1: Plan
|
||||
[✓] PHASE 2: Implement core logic (completed)
|
||||
[→] PHASE 2: Refactor legacy code (in_progress) ← New task added
|
||||
[ ] PHASE 3: Test
|
||||
[ ] PHASE 4: Review
|
||||
|
||||
User sees: "Additional work discovered: refactoring. Total now 5 tasks."
|
||||
```
|
||||
|
||||
**User Can See Current Progress at Any Time:**
|
||||
|
||||
With real-time updates, user can check progress:
|
||||
|
||||
```
|
||||
User checks at T=120s:
|
||||
|
||||
TodoWrite State:
|
||||
[✓] PHASE 1: Ask user
|
||||
[✓] PHASE 2: Plan architecture
|
||||
[→] PHASE 3: Implement core logic (in_progress)
|
||||
[ ] PHASE 3: Add error handling
|
||||
[ ] PHASE 3: Write tests
|
||||
[ ] PHASE 4: Code review
|
||||
[ ] PHASE 5: Accept
|
||||
|
||||
User sees: "3/8 tasks complete (37.5%), currently implementing core logic"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 5: Iteration Loop Tracking
|
||||
|
||||
**Create Task Per Iteration:**
|
||||
|
||||
For iteration loops, create a task for each iteration:
|
||||
|
||||
```
|
||||
✅ CORRECT - Iteration Tasks:
|
||||
|
||||
Design Validation Loop (max 10 iterations):
|
||||
|
||||
Initial TodoWrite:
|
||||
[ ] Iteration 1/10: Designer validation
|
||||
[ ] Iteration 2/10: Designer validation
|
||||
[ ] Iteration 3/10: Designer validation
|
||||
... (create all 10 upfront)
|
||||
|
||||
Progress:
|
||||
[✓] Iteration 1/10: Designer validation (NEEDS IMPROVEMENT)
|
||||
[✓] Iteration 2/10: Designer validation (NEEDS IMPROVEMENT)
|
||||
[→] Iteration 3/10: Designer validation (in_progress)
|
||||
[ ] Iteration 4/10: Designer validation
|
||||
...
|
||||
|
||||
User sees: "Iteration 3/10 in progress, 2 complete"
|
||||
|
||||
❌ WRONG - Single Loop Task:
|
||||
|
||||
TodoWrite:
|
||||
[→] Design validation loop (in_progress)
|
||||
|
||||
Problem: User sees "in_progress" for 10 minutes, no iteration visibility
|
||||
```
|
||||
|
||||
**Mark Iteration Complete When Done:**
|
||||
|
||||
```
|
||||
Iteration Lifecycle:
|
||||
|
||||
Iteration 1:
|
||||
Mark "Iteration 1/10" as in_progress
|
||||
Run designer validation
|
||||
If NEEDS IMPROVEMENT: Run developer fixes
|
||||
Mark "Iteration 1/10" as completed
|
||||
|
||||
Iteration 2:
|
||||
Mark "Iteration 2/10" as in_progress
|
||||
Run designer validation
|
||||
If PASS: Exit loop early
|
||||
Mark "Iteration 2/10" as completed
|
||||
|
||||
Result: Loop exited after 2 iterations
|
||||
[✓] Iteration 1/10 (completed)
|
||||
[✓] Iteration 2/10 (completed)
|
||||
[ ] Iteration 3/10 (not needed, loop exited)
|
||||
...
|
||||
|
||||
User sees: "Loop completed in 2/10 iterations"
|
||||
```
|
||||
|
||||
**Track Total Iterations vs Max Limit:**
|
||||
|
||||
```
|
||||
Iteration Progress:
|
||||
|
||||
Max: 10 iterations
|
||||
Current: 5
|
||||
|
||||
TodoWrite State:
|
||||
[✓] Iteration 1/10
|
||||
[✓] Iteration 2/10
|
||||
[✓] Iteration 3/10
|
||||
[✓] Iteration 4/10
|
||||
[→] Iteration 5/10
|
||||
[ ] Iteration 6/10
|
||||
...
|
||||
|
||||
User sees: "Iteration 5/10 (50% through max)"
|
||||
|
||||
Warning at Iteration 8:
|
||||
"Iteration 8/10 - approaching max, may escalate to user if not PASS"
|
||||
```
|
||||
|
||||
**Clear Progress Visibility:**
|
||||
|
||||
```
|
||||
Iteration Loop with TodoWrite:
|
||||
|
||||
User Request: "Validate UI design"
|
||||
|
||||
TodoWrite:
|
||||
[✓] PHASE 1: Gather design reference
|
||||
[✓] Iteration 1/10: Designer validation (5 issues found)
|
||||
[✓] Iteration 2/10: Designer validation (3 issues found)
|
||||
[✓] Iteration 3/10: Designer validation (1 issue found)
|
||||
[→] Iteration 4/10: Designer validation (in_progress)
|
||||
[ ] Iteration 5/10: Designer validation
|
||||
...
|
||||
[ ] PHASE 3: User validation gate
|
||||
|
||||
User sees:
|
||||
- 4 iterations completed (40% through max)
|
||||
- Issues reducing each iteration (5 → 3 → 1)
|
||||
- Progress toward PASS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 6: Parallel Task Tracking
|
||||
|
||||
**Multiple Agents Executing Simultaneously:**
|
||||
|
||||
When running agents in parallel, track each separately:
|
||||
|
||||
```
|
||||
✅ CORRECT - Separate Tasks for Parallel Agents:
|
||||
|
||||
Multi-Model Review (3 models in parallel):
|
||||
|
||||
TodoWrite:
|
||||
[✓] PHASE 1: Prepare review context
|
||||
[→] PHASE 2: Claude review (in_progress)
|
||||
[→] PHASE 2: Grok review (in_progress)
|
||||
[→] PHASE 2: Gemini review (in_progress)
|
||||
[ ] PHASE 3: Consolidate reviews
|
||||
|
||||
Note: 3 tasks "in_progress" is OK for parallel execution
|
||||
(Exception to "one in_progress" rule)
|
||||
|
||||
As models complete:
|
||||
[✓] PHASE 1: Prepare review context
|
||||
[✓] PHASE 2: Claude review (completed) ← First to finish
|
||||
[→] PHASE 2: Grok review (in_progress)
|
||||
[→] PHASE 2: Gemini review (in_progress)
|
||||
[ ] PHASE 3: Consolidate reviews
|
||||
|
||||
User sees: "1/3 reviews complete, 2 in progress"
|
||||
|
||||
❌ WRONG - Single Task for Parallel Work:
|
||||
|
||||
TodoWrite:
|
||||
[✓] PHASE 1: Prepare
|
||||
[→] PHASE 2: Run 3 reviews (in_progress)
|
||||
[ ] PHASE 3: Consolidate
|
||||
|
||||
Problem: No visibility into which reviews are complete
|
||||
```
|
||||
|
||||
**Update As Each Agent Completes:**
|
||||
|
||||
```
|
||||
Parallel Execution Timeline:
|
||||
|
||||
T=0s: Launch 3 reviews in parallel
|
||||
[→] Claude review (in_progress)
|
||||
[→] Grok review (in_progress)
|
||||
[→] Gemini review (in_progress)
|
||||
|
||||
T=60s: Claude completes first
|
||||
[✓] Claude review (completed)
|
||||
[→] Grok review (in_progress)
|
||||
[→] Gemini review (in_progress)
|
||||
|
||||
T=120s: Gemini completes
|
||||
[✓] Claude review (completed)
|
||||
[→] Grok review (in_progress)
|
||||
[✓] Gemini review (completed)
|
||||
|
||||
T=180s: Grok completes
|
||||
[✓] Claude review (completed)
|
||||
[✓] Grok review (completed)
|
||||
[✓] Gemini review (completed)
|
||||
|
||||
User sees real-time completion updates
|
||||
```
|
||||
|
||||
**Progress Indicators During Long Parallel Tasks:**
|
||||
|
||||
```
|
||||
For long-running parallel tasks (>2 minutes), show progress:
|
||||
|
||||
T=0s: "Launching 5 AI model reviews (estimated 5 minutes)..."
|
||||
T=60s: "1/5 reviews complete..."
|
||||
T=120s: "2/5 reviews complete..."
|
||||
T=180s: "4/5 reviews complete, 1 in progress..."
|
||||
T=240s: "All reviews complete! Consolidating results..."
|
||||
|
||||
TodoWrite mirrors this:
|
||||
[✓] Claude review (1/5 complete)
|
||||
[✓] Grok review (2/5 complete)
|
||||
[→] Gemini review (in_progress)
|
||||
[→] GPT-5 review (in_progress)
|
||||
[→] DeepSeek review (in_progress)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
**todowrite-orchestration + multi-agent-coordination:**
|
||||
|
||||
```
|
||||
Use Case: Multi-phase implementation workflow
|
||||
|
||||
Step 1: Initialize TodoWrite (todowrite-orchestration)
|
||||
Create task list for all 8 phases
|
||||
|
||||
Step 2: Sequential Agent Delegation (multi-agent-coordination)
|
||||
Phase 1: api-architect
|
||||
Mark PHASE 1 as in_progress
|
||||
Delegate to api-architect
|
||||
Mark PHASE 1 as completed
|
||||
|
||||
Phase 2: backend-developer
|
||||
Mark PHASE 2 as in_progress
|
||||
Delegate to backend-developer
|
||||
Mark PHASE 2 as completed
|
||||
|
||||
... continue for all phases
|
||||
```
|
||||
|
||||
**todowrite-orchestration + multi-model-validation:**
|
||||
|
||||
```
|
||||
Use Case: Multi-model review with progress tracking
|
||||
|
||||
Step 1: Initialize TodoWrite (todowrite-orchestration)
|
||||
[ ] PHASE 1: Prepare context
|
||||
[ ] PHASE 2: Launch reviews (5 models)
|
||||
[ ] PHASE 3: Consolidate results
|
||||
|
||||
Step 2: Parallel Execution (multi-model-validation)
|
||||
Mark "PHASE 2: Launch reviews" as in_progress
|
||||
Launch all 5 models simultaneously
|
||||
As each completes: Update progress (1/5, 2/5, ...)
|
||||
Mark "PHASE 2: Launch reviews" as completed
|
||||
|
||||
Step 3: Real-Time Visibility (todowrite-orchestration)
|
||||
User sees: "PHASE 2: 3/5 reviews complete..."
|
||||
```
|
||||
|
||||
**todowrite-orchestration + quality-gates:**
|
||||
|
||||
```
|
||||
Use Case: Iteration loop with TodoWrite tracking
|
||||
|
||||
Step 1: Initialize TodoWrite (todowrite-orchestration)
|
||||
[ ] Iteration 1/10
|
||||
[ ] Iteration 2/10
|
||||
...
|
||||
|
||||
Step 2: Iteration Loop (quality-gates)
|
||||
For i = 1 to 10:
|
||||
Mark "Iteration i/10" as in_progress
|
||||
Run designer validation
|
||||
If PASS: Exit loop
|
||||
Mark "Iteration i/10" as completed
|
||||
|
||||
Step 3: Progress Visibility
|
||||
User sees: "Iteration 5/10 complete, 5 remaining"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Do:**
|
||||
- ✅ Initialize TodoWrite BEFORE starting work (step 0)
|
||||
- ✅ List ALL phases upfront (user sees complete scope)
|
||||
- ✅ Use 8-15 tasks for typical workflows (readable)
|
||||
- ✅ Mark completed IMMEDIATELY after finishing (real-time)
|
||||
- ✅ Keep exactly ONE task in_progress (except parallel tasks)
|
||||
- ✅ Track iterations separately (Iteration 1/10, 2/10, ...)
|
||||
- ✅ Update as work progresses (not batched at end)
|
||||
- ✅ Add new tasks if discovered during execution
|
||||
|
||||
**Don't:**
|
||||
- ❌ Create TodoWrite during workflow (initialize first)
|
||||
- ❌ Hide phases from user (list all upfront)
|
||||
- ❌ Create too many tasks (>20 overwhelms user)
|
||||
- ❌ Batch completions at end of phase (update real-time)
|
||||
- ❌ Leave multiple tasks in_progress (pick one)
|
||||
- ❌ Use single task for loop (track iterations separately)
|
||||
- ❌ Update only at start/end (update during execution)
|
||||
|
||||
**Performance:**
|
||||
- TodoWrite overhead: <1s per update (negligible)
|
||||
- User visibility benefit: Reduces perceived wait time 30-50%
|
||||
- Workflow confidence: User knows progress, less likely to cancel
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: 8-Phase Implementation Workflow
|
||||
|
||||
**Scenario:** Full-cycle implementation with TodoWrite tracking
|
||||
|
||||
**Execution:**
|
||||
|
||||
```
|
||||
Step 0: Initialize TodoWrite
|
||||
TodoWrite: Create task list
|
||||
[ ] PHASE 1: Ask user for requirements
|
||||
[ ] PHASE 2: Generate architecture plan
|
||||
[ ] PHASE 3: Implement core logic
|
||||
[ ] PHASE 3: Add error handling
|
||||
[ ] PHASE 3: Write tests
|
||||
[ ] PHASE 4: Run test suite
|
||||
[ ] PHASE 5: Code review
|
||||
[ ] PHASE 6: Fix review issues
|
||||
[ ] PHASE 7: User acceptance
|
||||
[ ] PHASE 8: Generate report
|
||||
|
||||
User sees: "10 tasks, 0 complete, Phase 1 starting..."
|
||||
|
||||
Step 1: PHASE 1
|
||||
Mark "PHASE 1: Ask user" as in_progress
|
||||
... gather requirements (30s) ...
|
||||
Mark "PHASE 1: Ask user" as completed
|
||||
User sees: "1/10 tasks complete (10%)"
|
||||
|
||||
Step 2: PHASE 2
|
||||
Mark "PHASE 2: Architecture plan" as in_progress
|
||||
... generate plan (2 min) ...
|
||||
Mark "PHASE 2: Architecture plan" as completed
|
||||
User sees: "2/10 tasks complete (20%)"
|
||||
|
||||
Step 3: PHASE 3 (3 sub-tasks)
|
||||
Mark "PHASE 3: Implement core" as in_progress
|
||||
... implement (3 min) ...
|
||||
Mark "PHASE 3: Implement core" as completed
|
||||
User sees: "3/10 tasks complete (30%)"
|
||||
|
||||
Mark "PHASE 3: Add error handling" as in_progress
|
||||
... add error handling (2 min) ...
|
||||
Mark "PHASE 3: Add error handling" as completed
|
||||
User sees: "4/10 tasks complete (40%)"
|
||||
|
||||
Mark "PHASE 3: Write tests" as in_progress
|
||||
... write tests (3 min) ...
|
||||
Mark "PHASE 3: Write tests" as completed
|
||||
User sees: "5/10 tasks complete (50%)"
|
||||
|
||||
... continue through all phases ...
|
||||
|
||||
Final State:
|
||||
[✓] All 10 tasks completed
|
||||
User sees: "10/10 tasks complete (100%). Workflow finished!"
|
||||
|
||||
Total Duration: ~15 minutes
|
||||
User Experience: Continuous progress updates every 1-3 minutes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Iteration Loop with Progress Tracking
|
||||
|
||||
**Scenario:** Design validation with 10 max iterations
|
||||
|
||||
**Execution:**
|
||||
|
||||
```
|
||||
Step 0: Initialize TodoWrite
|
||||
TodoWrite: Create task list
|
||||
[ ] PHASE 1: Gather design reference
|
||||
[ ] Iteration 1/10: Designer validation
|
||||
[ ] Iteration 2/10: Designer validation
|
||||
[ ] Iteration 3/10: Designer validation
|
||||
[ ] Iteration 4/10: Designer validation
|
||||
[ ] Iteration 5/10: Designer validation
|
||||
... (10 iterations total)
|
||||
[ ] PHASE 3: User validation gate
|
||||
|
||||
Step 1: PHASE 1
|
||||
Mark "PHASE 1: Gather design" as in_progress
|
||||
... gather design (20s) ...
|
||||
Mark "PHASE 1: Gather design" as completed
|
||||
|
||||
Step 2: Iteration Loop
|
||||
Iteration 1:
|
||||
Mark "Iteration 1/10" as in_progress
|
||||
Designer: "NEEDS IMPROVEMENT - 5 issues"
|
||||
Developer: Fix 5 issues
|
||||
Mark "Iteration 1/10" as completed
|
||||
User sees: "Iteration 1/10 complete, 5 issues fixed"
|
||||
|
||||
Iteration 2:
|
||||
Mark "Iteration 2/10" as in_progress
|
||||
Designer: "NEEDS IMPROVEMENT - 3 issues"
|
||||
Developer: Fix 3 issues
|
||||
Mark "Iteration 2/10" as completed
|
||||
User sees: "Iteration 2/10 complete, 3 issues fixed"
|
||||
|
||||
Iteration 3:
|
||||
Mark "Iteration 3/10" as in_progress
|
||||
Designer: "NEEDS IMPROVEMENT - 1 issue"
|
||||
Developer: Fix 1 issue
|
||||
Mark "Iteration 3/10" as completed
|
||||
User sees: "Iteration 3/10 complete, 1 issue fixed"
|
||||
|
||||
Iteration 4:
|
||||
Mark "Iteration 4/10" as in_progress
|
||||
Designer: "PASS ✓"
|
||||
Mark "Iteration 4/10" as completed
|
||||
Exit loop (early exit)
|
||||
User sees: "Loop completed in 4/10 iterations"
|
||||
|
||||
Step 3: PHASE 3
|
||||
Mark "PHASE 3: User validation" as in_progress
|
||||
... user validates ...
|
||||
Mark "PHASE 3: User validation" as completed
|
||||
|
||||
Final State:
|
||||
[✓] PHASE 1: Gather design
|
||||
[✓] Iteration 1/10 (5 issues fixed)
|
||||
[✓] Iteration 2/10 (3 issues fixed)
|
||||
[✓] Iteration 3/10 (1 issue fixed)
|
||||
[✓] Iteration 4/10 (PASS)
|
||||
[ ] Iteration 5/10 (not needed)
|
||||
...
|
||||
[✓] PHASE 3: User validation
|
||||
|
||||
User Experience: Clear iteration progress, early exit visible
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Parallel Multi-Model Review
|
||||
|
||||
**Scenario:** 5 AI models reviewing code in parallel
|
||||
|
||||
**Execution:**
|
||||
|
||||
```
|
||||
Step 0: Initialize TodoWrite
|
||||
TodoWrite: Create task list
|
||||
[ ] PHASE 1: Prepare review context
|
||||
[ ] PHASE 2: Claude review
|
||||
[ ] PHASE 2: Grok review
|
||||
[ ] PHASE 2: Gemini review
|
||||
[ ] PHASE 2: GPT-5 review
|
||||
[ ] PHASE 2: DeepSeek review
|
||||
[ ] PHASE 3: Consolidate reviews
|
||||
[ ] PHASE 4: Present results
|
||||
|
||||
Step 1: PHASE 1
|
||||
Mark "PHASE 1: Prepare context" as in_progress
|
||||
... prepare (30s) ...
|
||||
Mark "PHASE 1: Prepare context" as completed
|
||||
|
||||
Step 2: PHASE 2 (Parallel Execution)
|
||||
Mark all 5 reviews as in_progress:
|
||||
[→] Claude review
|
||||
[→] Grok review
|
||||
[→] Gemini review
|
||||
[→] GPT-5 review
|
||||
[→] DeepSeek review
|
||||
|
||||
Launch all 5 in parallel (4-Message Pattern)
|
||||
|
||||
As each completes:
|
||||
T=60s: Claude completes
|
||||
[✓] Claude review
|
||||
User sees: "1/5 reviews complete"
|
||||
|
||||
T=90s: Gemini completes
|
||||
[✓] Gemini review
|
||||
User sees: "2/5 reviews complete"
|
||||
|
||||
T=120s: GPT-5 completes
|
||||
[✓] GPT-5 review
|
||||
User sees: "3/5 reviews complete"
|
||||
|
||||
T=150s: Grok completes
|
||||
[✓] Grok review
|
||||
User sees: "4/5 reviews complete"
|
||||
|
||||
T=180s: DeepSeek completes
|
||||
[✓] DeepSeek review
|
||||
User sees: "5/5 reviews complete!"
|
||||
|
||||
Step 3: PHASE 3
|
||||
Mark "PHASE 3: Consolidate" as in_progress
|
||||
... consolidate (30s) ...
|
||||
Mark "PHASE 3: Consolidate" as completed
|
||||
|
||||
Step 4: PHASE 4
|
||||
Mark "PHASE 4: Present results" as in_progress
|
||||
... present (10s) ...
|
||||
Mark "PHASE 4: Present results" as completed
|
||||
|
||||
Final State:
|
||||
[✓] All 8 tasks completed
|
||||
User sees: "Multi-model review complete in 3 minutes"
|
||||
|
||||
User Experience:
|
||||
- Real-time progress as each model completes
|
||||
- Clear visibility: "3/5 reviews complete"
|
||||
- Reduces perceived wait time (user knows progress)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Problem: User thinks workflow is stuck**
|
||||
|
||||
Cause: No TodoWrite updates for >1 minute
|
||||
|
||||
Solution: Update TodoWrite more frequently, or add sub-tasks
|
||||
|
||||
```
|
||||
❌ Wrong:
|
||||
[→] PHASE 3: Implementation (in_progress for 10 minutes)
|
||||
|
||||
✅ Correct:
|
||||
[✓] PHASE 3: Implement core logic (2 min)
|
||||
[✓] PHASE 3: Add error handling (3 min)
|
||||
[→] PHASE 3: Write tests (in_progress, 2 min so far)
|
||||
|
||||
User sees progress every 2-3 minutes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Problem: Too many tasks (>20), overwhelming**
|
||||
|
||||
Cause: Too granular task breakdown
|
||||
|
||||
Solution: Group micro-tasks into larger operations
|
||||
|
||||
```
|
||||
❌ Wrong (25 tasks):
|
||||
[ ] Read file 1
|
||||
[ ] Read file 2
|
||||
[ ] Write file 3
|
||||
... (25 micro-tasks)
|
||||
|
||||
✅ Correct (8 tasks):
|
||||
[ ] PHASE 1: Gather inputs (includes reading files)
|
||||
[ ] PHASE 2: Process data
|
||||
... (8 significant operations)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Problem: Multiple tasks "in_progress" (not parallel execution)**
|
||||
|
||||
Cause: Forgot to mark previous task as completed
|
||||
|
||||
Solution: Always mark completed before starting next
|
||||
|
||||
```
|
||||
❌ Wrong:
|
||||
[→] PHASE 1: Ask user (in_progress)
|
||||
[→] PHASE 2: Plan (in_progress) ← Both in_progress?
|
||||
|
||||
✅ Correct:
|
||||
[✓] PHASE 1: Ask user (completed)
|
||||
[→] PHASE 2: Plan (in_progress) ← Only one
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
TodoWrite orchestration provides real-time progress visibility through:
|
||||
|
||||
- **Phase initialization** (create task list before starting)
|
||||
- **Appropriate granularity** (8-15 tasks, significant operations)
|
||||
- **Real-time updates** (mark completed immediately)
|
||||
- **Exactly one in_progress** (except parallel execution)
|
||||
- **Iteration tracking** (separate task per iteration)
|
||||
- **Parallel task tracking** (update as each completes)
|
||||
|
||||
Master these patterns and users will always know:
|
||||
- What's happening now
|
||||
- What's coming next
|
||||
- How much progress has been made
|
||||
- How much remains
|
||||
|
||||
This transforms "black box" workflows into transparent, trackable processes.
|
||||
|
||||
---
|
||||
|
||||
**Extracted From:**
|
||||
- `/review` command (10-task initialization, phase-based tracking)
|
||||
- `/implement` command (8-phase workflow with sub-tasks)
|
||||
- `/validate-ui` command (iteration tracking, user feedback rounds)
|
||||
- All multi-phase orchestration workflows
|
||||
Reference in New Issue
Block a user