specweave 0.26.3 → 0.26.5

package/plugins/specweave/skills/role-orchestrator/SKILL.md

@@ -3,1124 +3,448 @@ name: role-orchestrator
 description: Multi-agent orchestration system that coordinates specialized agents (PM, Architect, DevOps, QA, Tech Lead, Security) to work together on complex tasks. Implements hierarchical orchestrator-worker pattern. Activates for complex multi-step requests requiring multiple roles/skills. Keywords: build product, create SaaS, full implementation, end-to-end, multi-agent, orchestrate, coordinate roles, complex project.
 ---
 
-# Role Orchestrator - Multi-Agent Coordination System
+# Role Orchestrator - Multi-Agent Coordination
 
-**Purpose**: Coordinate multiple specialized agents to solve complex, multi-step problems through intelligent task decomposition and role assignment.
+**Self-contained orchestration that works in ANY user project after `specweave init`.**
 
-## Architecture Pattern
+---
+
+## Purpose
 
-The role-orchestrator implements the **Hierarchical Orchestrator-Worker Pattern** from multi-agent systems research:
+Coordinate multiple specialized agents for complex, multi-step tasks through intelligent decomposition and role assignment.
 
+**Architecture**: Hierarchical Orchestrator-Worker Pattern
 ```
-User Request
-     ↓
-Role Orchestrator (this skill)
-     ↓
-├── Task Decomposition (PM Agent)
-├── Architecture Design (Architect Agent)
-├── Technical Planning (Tech Lead Agent)
-├── Security Review (Security Agent)
-├── QA Strategy (QA Lead Agent)
-├── Implementation (Backend/Frontend Agents)
-└── Deployment (DevOps Agent)
+User Request → Orchestrator → PM → Architect → Tech Lead → Implement → QA → Deploy
 ```
 
+---
+
 ## When to Activate
 
-This skill activates for requests that require **3+ agents** or **full product development**:
+Activates for requests requiring **3+ agents** or **full product development**:
+
+| User Says | Agents Needed | Pattern |
+|-----------|---------------|---------|
+| "Build a SaaS for X" | PM → Architect → Tech Lead → Implement → QA → DevOps | Sequential |
+| "Create real-time chat" | Architect → Backend + Frontend (parallel) → QA | Parallel |
+| "Secure authentication" | Security → Tech Lead → Backend → QA | Sequential |
+| "Optimize performance" | Tech Lead → Performance → Backend → DevOps | Iterative |
 
-| User Says | Agents Needed | Orchestration Pattern |
-|-----------|---------------|---------------------|
-| "Build a SaaS for project management" | PM → Architect → Tech Lead → Implement → QA → DevOps | Sequential with feedback loops |
-| "Create real-time chat feature" | Architect → Tech Lead → Backend → Frontend → QA | Parallel (Backend + Frontend) |
-| "Secure our authentication system" | Security → Tech Lead → Backend → QA | Sequential validation |
-| "Deploy to production" | DevOps → QA → Backend → Tech Lead | Pre-flight checks |
-| "Optimize system performance" | Tech Lead → Performance → Backend → DevOps → QA | Iterative optimization |
+---
 
-## Agent Roles & Responsibilities
+## Agent Roles
 
 ### Strategic Layer
 
-**1. PM Agent (pm-agent)**
-- Product strategy and requirements
-- User story creation
-- Feature prioritization
-- Stakeholder communication
+**PM Agent (pm-agent)**
+- Product strategy, user stories, prioritization
 - **When**: Starting new products/features
 
-**2. Architect Agent (architect-agent)**
-- System design and architecture
-- Technology stack decisions
-- Create Architecture Decision Records (ADRs)
-- Component design
-- **When**: Designing new systems or major features
+**Architect Agent (architect-agent)**
+- System design, ADRs, technology stack
+- **When**: Designing systems or major features
 
 ### Execution Layer
 
-**3. Tech Lead Agent (tech-lead-agent)**
-- Technical planning and estimation
-- Code review and quality standards
-- Team guidance
-- Technology mentorship
-- **When**: Complex technical decisions needed
-
-**4. Backend Developers**
-- nodejs-backend: Node.js/TypeScript implementation
-- python-backend: Python/FastAPI implementation
-- dotnet-backend: C#/.NET implementation
-- **When**: Implementing server-side logic
-
-**5. Frontend Agent (frontend-agent)**
-- React/Next.js implementation
-- UI/UX implementation
-- Client-side logic
+**Tech Lead Agent (tech-lead-agent)**
+- Technical planning, code review, quality standards
+- **When**: Complex technical decisions
+
+**Backend Agents**
+- nodejs-backend, python-backend, dotnet-backend
+- **When**: Server-side implementation
+
+**Frontend Agent (frontend-agent)**
+- React/Next.js, UI/UX implementation
 - **When**: Building user interfaces
 
 ### Quality & Operations Layer
 
-**6. QA Lead Agent (qa-lead-agent)**
-- Test strategy creation
-- Quality assurance
-- Test case design
-- Test coverage analysis
+**QA Lead Agent (qa-lead-agent)**
+- Test strategy, quality assurance, coverage
 - **When**: Defining testing approach
 
-**7. Security Agent (security-agent)**
-- Security architecture review
-- Threat modeling
-- Penetration testing
-- Compliance validation (OWASP, PCI-DSS)
+**Security Agent (security-agent)**
+- Security architecture, threat modeling, compliance
 - **When**: Security-critical features
 
-**8. DevOps Agent (devops-agent)**
-- Infrastructure provisioning
-- CI/CD pipeline setup
-- Deployment automation
-- Monitoring and observability
-- **When**: Deployment and operations tasks
-
-## ⚠️ CRITICAL: Increment Creation FIRST
-
-**MANDATORY FIRST STEP**: Before invoking ANY agents, the role-orchestrator MUST create an increment folder.
+**DevOps Agent (devops-agent)**
+- Infrastructure, CI/CD, deployment, monitoring
+- **When**: Operations tasks
 
-### Phase 0: Create Increment Structure
-
-```typescript
-async function createIncrementFirst(userRequest: string): Promise<IncrementInfo> {
-  // 1. Parse user request to extract project name
-  const projectName = extractProjectName(userRequest);
-  // e.g., "event management" → "event-management"
-
-  // 2. Auto-number increment (scan .specweave/increments/ for highest)
-  const nextNumber = await getNextIncrementNumber();
-  // e.g., 0001, 0002, 0003
-
-  // 3. Create increment folder
-  const incrementPath = `.specweave/increments/${nextNumber}-${projectName}/`;
-  await mkdir(incrementPath, { recursive: true });
-
-  // 4. Create subdirectories
-  await mkdir(`${incrementPath}logs/`);
-  await mkdir(`${incrementPath}scripts/`);
-  await mkdir(`${incrementPath}reports/`);
-
-  // 5. Create placeholder files
-  await writeFile(`${incrementPath}spec.md`, SPEC_TEMPLATE);
-  await writeFile(`${incrementPath}tasks.md`, TASKS_TEMPLATE);
-  await writeFile(`${incrementPath}tests.md`, TESTS_TEMPLATE);
-  await writeFile(`${incrementPath}context-manifest.yaml`, CONTEXT_MANIFEST_TEMPLATE);
-
-  // 6. Return increment info for agents
-  return {
-    id: `${nextNumber}-${projectName}`,
-    path: incrementPath,
-    number: nextNumber,
-    name: projectName
-  };
-}
-```
-
-**Templates**:
-
-```yaml
-# spec.md frontmatter
----
-increment: 0001-event-management
-title: "Event Management SaaS"
-priority: P1
-status: planned
-created: 2025-10-26
-structure: user-stories
 ---
 
-# Event Management SaaS
-
-## Overview
-
-(To be filled by PM Agent)
-```
+## CRITICAL: Safe Orchestration Pattern
 
-```yaml
-# context-manifest.yaml
----
-spec_sections:
-  - .specweave/docs/internal/strategy/README.md
+**Rule**: Orchestrator creates structure, guides user to invoke agents in MAIN context (NOT nested spawning).
 
-documentation:
-  - .specweave/docs/internal/architecture/README.md
+### Phase 0: Create Increment Structure FIRST
 
-max_context_tokens: 10000
-priority: high
-auto_refresh: false
----
-```
+Before invoking ANY agents, create increment folder:
 
-**Then pass increment path to ALL agents**:
 ```typescript
-const increment = await createIncrementFirst(userRequest);
-
-// Now invoke agents with increment path
-await invokeAgent('pm', {
-  task: 'Define product requirements',
-  outputPath: `${increment.path}reports/pm-analysis.md`,
-  incrementId: increment.id
-});
-```
+// 1. Parse user request
+const projectName = extractProjectName(userRequest);
+// "event management" → "event-management"
 
-### ⚠️ CRITICAL: File Reading Instructions for Agents
+// 2. Get next number
+const nextNumber = getNextIncrementNumber();
+// e.g., 0001, 0002, 0003
 
-When invoking agents, provide clear instructions to **read FILES, not DIRECTORIES**:
+// 3. Create structure
+const incrementPath = `.specweave/increments/${nextNumber}-${projectName}/`;
+mkdir -p ${incrementPath}
+mkdir -p ${incrementPath}logs/
+mkdir -p ${incrementPath}scripts/
+mkdir -p ${incrementPath}reports/
 
-**❌ WRONG**:
-```typescript
-await invokeAgent('architect', {
-  task: 'Read .specweave/docs/internal/strategy and design architecture'
-});
-```
-This will fail with `EISDIR: illegal operation on a directory, read`
-
-**✅ CORRECT**:
-```typescript
-await invokeAgent('architect', {
-  task: `Read .specweave/docs/internal/strategy/README.md for existing strategy.
-         Use Glob to find additional files: .specweave/docs/internal/strategy/**/*.md
-         Then design system architecture.`
-});
+// 4. Create placeholder files
+write ${incrementPath}spec.md (basic template)
+write ${incrementPath}plan.md (basic template)
+write ${incrementPath}tasks.md (basic template)
+write ${incrementPath}metadata.json (MANDATORY)
 ```
 
-**Best Practice**:
-- Always specify **file paths** (`.md` extension), NOT directory paths
-- Use `Glob` tool for pattern matching (`**/*.md`)
-- Read `README.md` files for directory overviews
-- List specific files to read
-
+**spec.md template**:
+```yaml
+---
+increment: 0001-project-name
+title: "Project Name"
+type: feature
+priority: P1
+status: planned
+created: 2025-11-24
 ---
 
-## Orchestration Workflows
+# Project Name
 
-### Workflow 1: New Product Development
+## Overview
+(To be filled by PM Agent)
 
-```yaml
-name: "Build SaaS Product"
-pattern: sequential_with_gates
-agents:
-  - role: pm-agent
-    task: "Define product requirements and user stories"
-    output: specifications/product.md
-    gate: user_approval_required
-
-  - role: architect-agent
-    task: "Design system architecture"
-    input: specifications/product.md
-    output: .specweave/docs/architecture/system-design.md
-    gate: tech_review_required
-
-  - role: tech-lead-agent
-    task: "Create technical implementation plan"
-    input: .specweave/docs/architecture/system-design.md
-    output: .specweave/increments/####-product/plan.md
-
-  - role: security-agent
-    task: "Security architecture review"
-    input: .specweave/docs/architecture/system-design.md
-    output: .specweave/docs/architecture/security/threat-model.md
-    gate: security_approval
-
-  - role: qa-lead-agent
-    task: "Define test strategy"
-    input: specifications/product.md
-    output: .specweave/increments/####-product/tests.md
-
-  - role: [nodejs-backend, frontend-agent]
-    task: "Implement features"
-    pattern: parallel
-    input: .specweave/increments/####-product/plan.md
-
-  - role: qa-lead-agent
-    task: "Execute tests"
-    input: .specweave/increments/####-product/tests.md
-    gate: all_tests_pass
-
-  - role: devops-agent
-    task: "Deploy to production"
-    input: .specweave/increments/####-product/plan.md#deployment
-    gate: deployment_approval
-
-success_criteria:
-  - All gates passed
-  - Tests passing (>80% coverage)
-  - Security review approved
-  - Deployed successfully
+## User Stories
+(To be filled by PM Agent)
 ```
 
-### Workflow 2: Feature Addition (Brownfield)
-
-```yaml
-name: "Add Feature to Existing System"
-pattern: analyze_then_build
-agents:
-  - role: tech-lead-agent
-    task: "Analyze existing codebase"
-    output: .specweave/increments/####-feature/analysis.md
-
-  - role: architect-agent
-    task: "Design integration approach"
-    input: .specweave/increments/####-feature/analysis.md
-    output: .specweave/increments/####-feature/plan.md
-
-  - role: qa-lead-agent
-    task: "Create regression test suite"
-    input: .specweave/increments/####-feature/analysis.md
-    output: .specweave/increments/####-feature/regression-tests.md
-    gate: user_validates_tests
-
-  - role: [backend-agent, frontend-agent]
-    task: "Implement feature"
-    pattern: parallel
-
-  - role: qa-lead-agent
-    task: "Run regression + new tests"
-    gate: no_regressions_detected
-
-  - role: devops-agent
-    task: "Deploy with canary release"
+**metadata.json template**:
+```json
+{
+  "id": "0001-project-name",
+  "status": "planned",
+  "type": "feature",
+  "priority": "P1",
+  "created": "2025-11-24T12:00:00Z",
+  "lastActivity": "2025-11-24T12:00:00Z"
+}
 ```
 
-### Workflow 3: Security Hardening
+### Phase 1: Guide User Through Agent Workflow
 
-```yaml
-name: "Secure Existing System"
-pattern: assess_fix_verify
-agents:
-  - role: security-agent
-    task: "Threat modeling and security assessment"
-    output: .specweave/docs/architecture/security/assessment.md
-
-  - role: tech-lead-agent
-    task: "Prioritize security issues"
-    input: .specweave/docs/architecture/security/assessment.md
-    output: work/issues/###-security-fixes/
-
-  - role: [backend-agent, frontend-agent]
-    task: "Implement security fixes"
-    pattern: parallel
-
-  - role: security-agent
-    task: "Penetration testing"
-    gate: no_critical_vulns
-
-  - role: qa-lead-agent
-    task: "Security regression tests"
-    gate: all_tests_pass
-
-  - role: devops-agent
-    task: "Deploy with zero-downtime"
-```
+**Output this workflow to user**:
 
-### Workflow 4: Performance Optimization
-
-```yaml
-name: "Optimize System Performance"
-pattern: measure_optimize_verify
-agents:
-  - role: tech-lead-agent
-    task: "Profile and identify bottlenecks"
-    output: work/issues/###-performance/analysis.md
-
-  - role: architect-agent
-    task: "Design optimization strategy"
-    input: work/issues/###-performance/analysis.md
-
-  - role: [backend-agent, frontend-agent, devops-agent]
-    task: "Implement optimizations"
-    pattern: parallel
-
-  - role: qa-lead-agent
-    task: "Performance regression tests"
-    gate: performance_targets_met
-
-  - role: devops-agent
-    task: "Deploy with traffic shaping"
 ```
+✅ Increment structure created: .specweave/increments/0001-project-name/
 
-## Task Decomposition Strategy
+🎯 Complete workflow (run these commands in MAIN conversation):
 
-### 1. Analyze Request Complexity
+STEP 1: Product Strategy & Requirements
+Tell Claude: "Complete the spec for increment 0001-project-name"
+(PM agent will activate automatically)
 
-```typescript
-interface ComplexityAnalysis {
-  scope: 'single-feature' | 'multi-feature' | 'full-product' | 'system-wide';
-  domains: string[];  // ['backend', 'frontend', 'database', 'infrastructure']
-  phases: number;     // Number of sequential phases
-  agents_needed: string[];
-  estimated_effort: 'small' | 'medium' | 'large' | 'xl';
-}
+STEP 2: Architecture & Design
+Tell Claude: "Design architecture for increment 0001-project-name"
+(Architect agent will create ADRs and system design)
 
-function analyzeComplexity(userRequest: string): ComplexityAnalysis {
-  // Use intent classification from skill-router
-  // Analyze keywords, scope, and requirements
-  // Return structured complexity analysis
-}
-```
-
-### 2. Create Execution Plan
-
-```typescript
-interface ExecutionPlan {
-  phases: Phase[];
-  parallel_groups: ParallelGroup[];
-  gates: QualityGate[];
-  estimated_duration: string;
-}
+STEP 3: Technical Planning
+Tell Claude: "Create technical plan for increment 0001-project-name"
+(Tech Lead agent will create implementation approach)
 
-interface Phase {
-  name: string;
-  agents: AgentAssignment[];
-  dependencies: string[];  // Phase IDs this depends on
-  outputs: string[];       // File paths to create
-}
+STEP 4: Implementation Tasks
+Tell Claude: "Create tasks for increment 0001-project-name"
+(Test-aware planner will generate tasks with tests)
 
-interface ParallelGroup {
-  agents: string[];
-  can_run_concurrently: boolean;
-  sync_point: string;  // Where they must sync
-}
+STEP 5: Security Review (if needed)
+Tell Claude: "Review security for increment 0001-project-name"
+(Security agent will perform threat modeling)
 
-interface QualityGate {
-  phase: string;
-  type: 'user_approval' | 'test_pass' | 'security_review' | 'performance_target';
-  criteria: string[];
-  blocker: boolean;  // If true, cannot proceed until gate passes
-}
-```
+STEP 6: Implementation
+Tell Claude: "Implement increment 0001-project-name"
+(Backend/Frontend agents will implement code)
 
-### 3. Execute with Monitoring
+STEP 7: Quality Assurance
+Tell Claude: "Run QA for increment 0001-project-name"
+(QA agent will verify tests and coverage)
 
-```typescript
-interface ExecutionState {
-  current_phase: number;
-  completed_tasks: string[];
-  blocked_tasks: string[];
-  gates_status: Record<string, 'pending' | 'passed' | 'failed'>;
-  agent_outputs: Record<string, any>;
-}
+STEP 8: Deployment Planning
+Tell Claude: "Plan deployment for increment 0001-project-name"
+(DevOps agent will create infrastructure)
 
-async function execute(plan: ExecutionPlan): Promise<ExecutionResult> {
-  const state: ExecutionState = initializeState();
-
-  for (const phase of plan.phases) {
-    // Check dependencies satisfied
-    if (!areDependenciesMet(phase, state)) {
-      await waitForDependencies(phase);
-    }
-
-    // Execute agents (parallel or sequential)
-    const results = await executePhase(phase);
-
-    // Update state
-    state.completed_tasks.push(...results.tasks);
-    state.agent_outputs[phase.name] = results.outputs;
-
-    // Check quality gates
-    if (phase.gates) {
-      const gateResults = await checkGates(phase.gates);
-      if (gateResults.failed.length > 0) {
-        // Handle gate failures
-        await handleGateFailures(gateResults.failed);
-      }
-    }
-  }
-
-  return {
-    success: state.blocked_tasks.length === 0,
-    outputs: state.agent_outputs,
-    summary: generateSummary(state)
-  };
-}
+⚠️  Run these sequentially in MAIN conversation to prevent context explosion!
 ```
 
-## Agent Communication Patterns
+**DO NOT spawn all agents from this skill using Task() tool!**
 
-### 1. Sequential Handoff
-
-```
-PM Agent → Architect Agent → Tech Lead → Implementation
-   (specs)     (design)         (plan)      (code)
-```
+---
 
-Each agent receives the previous agent's output and builds upon it.
+## Orchestration Patterns
 
-### 2. Parallel Execution with Shared State
+### Pattern 1: Sequential (Default)
 
+**When**: Dependencies between steps
 ```
-Backend Agent ─┐
-               ├─→ Shared Memory (Context) ─→ Integration Phase
-Frontend Agent ─┘
+PM → Architect → Tech Lead → Backend → Frontend → QA → DevOps
 ```
 
-Multiple agents work simultaneously, coordinated through shared context.
+**User workflow**:
+1. Create increment structure
+2. Guide user to invoke agents one by one
+3. Each agent completes before next starts
+4. User tracks progress
 
-### 3. Feedback Loops
+### Pattern 2: Parallel Execution
 
+**When**: Independent work streams
 ```
-Implementation → QA → [FAIL] → Tech Lead (analysis) → Implementation
-                  ↓
-               [PASS]
-                  ↓
-              DevOps
+PM + Architect (parallel)
+    ↓
+Backend + Frontend (parallel)
+    ↓
+QA + DevOps (parallel)
 ```
 
-Iterative refinement with quality gates.
+**User workflow**:
+1. Create increment structure
+2. Identify parallel opportunities
+3. Guide user: "You can run these in parallel: [list]"
+4. User invokes agents concurrently
 
-### 4. Hierarchical Decision-Making
+### Pattern 3: Adaptive (Context-Aware)
 
+**When**: Requirements discovered during execution
 ```
-Role Orchestrator (strategic decisions)
-         ↓
-Tech Lead Agent (tactical decisions)
-         ↓
-Implementation Agents (execution)
+PM → Architect → [Discover need] → Security → Tech Lead → ...
 ```
 
-## Context Management
-
-### Shared Context Structure
-
-```yaml
-# .specweave/orchestration/context.yaml
-project:
-  name: "E-Commerce Platform"
-  phase: "implementation"
-  current_feature: "003-payment-processing"
-
-agents_active:
-  - pm-agent: "requirements_complete"
-  - architect-agent: "design_approved"
-  - backend-agent: "in_progress"
-  - frontend-agent: "in_progress"
-  - qa-lead-agent: "test_strategy_ready"
-
-shared_artifacts:
-  specifications: "specifications/modules/payments/"
-  architecture: ".specweave/docs/architecture/payment-system.md"
-  feature_plan: "features/003-payment-processing/plan.md"
-  implementation: "src/payments/"
-
-quality_gates:
-  - name: "security_review"
-    status: "passed"
-    approved_by: "security-agent"
-  - name: "test_coverage"
-    status: "pending"
-    target: ">80%"
-    current: "67%"
-```
-
-### Agent-to-Agent Communication
-
-Agents communicate through:
-1. **File outputs**: Each agent creates files in designated locations
-2. **Shared memory**: `.specweave/orchestration/context.yaml`
-3. **Event system**: Agents emit events when tasks complete
-4. **Quality gates**: Explicit approval/rejection points
-
-## Decision-Making Framework
+**User workflow**:
+1. Start with basic plan
+2. Agent discovers additional needs
+3. Inject new agents mid-workflow
+4. Adjust plan dynamically
 
-### When to Use Which Agent
-
-```typescript
-const agentSelectionRules = {
-  // Product/Business decisions
-  'requirements|user-stories|product-strategy': 'pm-agent',
-
-  // Architecture decisions
-  'design|architecture|system-design|tech-stack': 'architect-agent',
+---
 
-  // Technical guidance
-  'code-review|best-practices|technical-debt|refactoring': 'tech-lead-agent',
+## Quality Gates (Checkpoints)
 
-  // Security
-  'security|authentication|authorization|encryption|compliance': 'security-agent',
+### Gate 1: After PM (Requirements Complete)
+**Check**:
+- [ ] User stories defined with AC-IDs
+- [ ] Success criteria measurable
+- [ ] Dependencies identified
+- [ ] Out of scope defined
 
-  // Quality assurance
-  'testing|qa|test-strategy|test-coverage': 'qa-lead-agent',
+**Decision**: Proceed to architecture OR refine requirements
 
-  // Implementation
-  'implement-nodejs|api|backend': 'nodejs-backend',
-  'implement-python|ml|data': 'python-backend',
-  'implement-dotnet|csharp|enterprise': 'dotnet-backend',
-  'implement-ui|frontend|react': 'frontend-agent',
+### Gate 2: After Architect (Design Complete)
+**Check**:
+- [ ] System design documented
+- [ ] ADRs created (≥3)
+- [ ] Technology stack chosen
+- [ ] Data model defined
 
-  // Operations
-  'deploy|infrastructure|ci-cd|monitoring': 'devops-agent'
-};
+**Decision**: Proceed to implementation OR redesign
 
-function selectAgents(task: string): string[] {
-  const keywords = extractKeywords(task);
-  const matchedAgents = [];
+### Gate 3: After Implementation (Code Complete)
+**Check**:
+- [ ] All P1 tasks completed
+- [ ] Tests passing (≥80% coverage)
+- [ ] Code reviewed
+- [ ] Documentation updated
 
-  for (const [pattern, agent] of Object.entries(agentSelectionRules)) {
-    if (keywords.some(kw => pattern.includes(kw))) {
-      matchedAgents.push(agent);
-    }
-  }
+**Decision**: Proceed to deployment OR fix issues
 
-  return matchedAgents;
-}
-```
+### Gate 4: Before Deployment (Production Ready)
+**Check**:
+- [ ] Security review passed
+- [ ] Performance acceptable
+- [ ] Monitoring configured
+- [ ] Rollback plan exists
 
-## Error Handling & Resilience
+**Decision**: Deploy OR address blockers
 
-### Retry Strategy
+---
 
-```typescript
-interface RetryConfig {
-  max_attempts: number;
-  backoff: 'linear' | 'exponential';
-  fallback_agent?: string;
-}
+## Error Handling
 
-async function executeWithRetry(
-  agent: string,
-  task: string,
-  config: RetryConfig
-): Promise<AgentResult> {
-  for (let attempt = 1; attempt <= config.max_attempts; attempt++) {
-    try {
-      const result = await invokeAgent(agent, task);
-      if (result.success) {
-        return result;
-      }
-    } catch (error) {
-      if (attempt === config.max_attempts) {
-        // Try fallback agent if configured
-        if (config.fallback_agent) {
-          return await invokeAgent(config.fallback_agent, task);
-        }
-        throw error;
-      }
-      await sleep(calculateBackoff(attempt, config.backoff));
-    }
-  }
-}
+### Agent Failure
 ```
-
-### Feedback Loops with Auto-Refinement
-
-**NEW: Automatic quality improvement through iterative refinement**
-
-```typescript
-interface FeedbackLoopConfig {
-  enabled: boolean;
-  max_retries: 3;
-  stop_on_improvement: boolean;
-  quality_threshold: number;  // 0.0-1.0
-  require_user_approval: boolean;
-}
-
-interface RefinementResult {
-  attempt: number;
-  output: string;
-  score: number;
-  issues: Issue[];
-  improved: boolean;
-  final: boolean;
-}
-
-async function executeWithFeedback(
-  agent: string,
-  task: string,
-  validator: (output: string) => Promise<ValidationResult>,
-  config: FeedbackLoopConfig
-): Promise<RefinementResult> {
-
-  let bestResult = null;
-  let bestScore = 0;
-
-  for (let attempt = 1; attempt <= config.max_retries; attempt++) {
-    // Execute agent
-    const output = await invokeAgent(agent, task);
-
-    // Validate output
-    const validation = await validator(output);
-
-    // Track progress
-    console.log(`🔄 Refinement Attempt ${attempt}/${config.max_retries}`);
-    console.log(`   Score: ${validation.score.toFixed(2)} (Target: ${config.quality_threshold})`);
-
-    // Check if quality threshold met
-    if (validation.score >= config.quality_threshold) {
-      console.log(`✅ Quality threshold met (${validation.score.toFixed(2)} >= ${config.quality_threshold})`);
-      return {
-        attempt,
-        output,
-        score: validation.score,
-        issues: [],
-        improved: true,
-        final: true
-      };
-    }
-
-    // Track best result
-    if (validation.score > bestScore) {
-      bestScore = validation.score;
-      bestResult = { attempt, output, score: validation.score, issues: validation.issues };
-    }
-
-    // Check if should stop (improvement + stop_on_improvement flag)
-    if (config.stop_on_improvement && attempt > 1 && validation.score > bestScore) {
-      console.log(`⏸️  Stopping early (score improved: ${bestScore.toFixed(2)} → ${validation.score.toFixed(2)})`);
-      return {
-        ...bestResult,
-        improved: true,
-        final: true
-      };
-    }
-
-    // If not last attempt, prepare feedback for next iteration
-    if (attempt < config.max_retries) {
-      const feedback = generateFeedback(validation.issues);
-
-      // Update task with feedback
-      task = `${task}\n\n**Feedback from previous attempt (${validation.score.toFixed(2)}/1.00):**\n${feedback}`;
-
-      console.log(`   Issues found: ${validation.issues.length}`);
-      console.log(`   Retrying with feedback...`);
-    }
-  }
-
-  // Max retries reached, return best result
-  console.log(`⚠️  Max retries reached. Best score: ${bestScore.toFixed(2)}`);
-
-  return {
-    ...bestResult,
-    improved: bestScore > 0,
-    final: true
-  };
-}
-
-function generateFeedback(issues: Issue[]): string {
-  const feedback: string[] = [];
-
-  for (const issue of issues) {
-    feedback.push(`• ${issue.severity.toUpperCase()}: ${issue.description}`);
-    if (issue.location) {
-      feedback.push(`  Location: ${issue.location}`);
-    }
-    if (issue.suggestion) {
-      feedback.push(`  Suggestion: ${issue.suggestion}`);
-    }
-  }
-
-  return feedback.join('\n');
-}
+If agent fails:
+1. Capture error details
+2. Retry with backoff (max 3 attempts)
+3. Try fallback agent if available
+4. If critical: pause and notify user
+5. NEVER fail silently
 ```
 
-### Feedback Loop Workflow
-
+### Graceful Degradation
 ```
-Agent generates output
-         ↓
-Validate output (rule-based + LLM-judge)
-         ↓
-Score < threshold? ──No──→ ✅ Accept output
-         ↓ Yes
-Extract issues and suggestions
-         ↓
-Generate feedback prompt
-         ↓
-Agent regenerates with feedback ──┐
-         ↓                         │
-Validate again                     │
-         ↓                         │
-Score improved? ──No──→ Retry ────┘ (max 3x)
-         ↓ Yes
-✅ Accept improved output
+If PM fails → Use basic template
+If Architect fails → Tech Lead creates simple design
+If Backend fails → Create manual implementation guide
+If DevOps fails → Create manual deployment steps
 ```
 
-### Agent-Specific Feedback Integration
-
-**PM Agent (Requirements)**
-```typescript
-const pmValidator = async (spec: string) => {
-  // Rule-based checks
-  const ruleScore = await runRuleBasedValidation(spec);
-
-  // Optional: LLM-as-judge quality check
-  const qualityScore = await incrementQualityJudge.evaluate(spec);
-
-  return {
-    score: (ruleScore + qualityScore) / 2,
-    issues: [...ruleIssues, ...qualityIssues]
-  };
-};
-
-await executeWithFeedback(
-  'pm-agent',
-  'Define requirements for authentication',
-  pmValidator,
-  config
-);
+### User Intervention
 ```
-
-**Architect Agent (Design)**
-```typescript
-const architectValidator = async (design: string) => {
-  return await incrementQualityJudge.evaluate(design, {
-    dimensions: ['feasibility', 'scalability', 'maintainability']
-  });
-};
-
-await executeWithFeedback(
-  'architect-agent',
-  'Design authentication system',
-  architectValidator,
-  config
-);
+If orchestrator stuck:
+1. Show current state
+2. Present options to user
+3. Let user decide next step
+4. Resume from checkpoint
 ```
 
-**QA Lead Agent (Test Strategy)**
-```typescript
-const qaValidator = async (testPlan: string) => {
-  // Check test coverage
-  const coverage = await analyzeTestCoverage(testPlan);
-
-  // Check testability
-  const testability = await incrementQualityJudge.evaluate(testPlan, {
-    dimensions: ['testability', 'completeness']
-  });
-
-  return {
-    score: coverage >= 0.80 ? testability.score : 0.60,
-    issues: testability.issues
-  };
-};
-
-await executeWithFeedback(
-  'qa-lead-agent',
-  'Create test strategy',
-  qaValidator,
-  config
-);
-```
-
-### Example: PM Agent with Feedback Loop
-
-```markdown
-🔷 SpecWeave Multi-Agent Orchestration Active
-
-**Task**: Create authentication feature
-**Agent**: PM Agent (Requirements)
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Attempt 1/3**: Generating requirements...
-
-✅ PM Agent completed
-🔍 Validating output...
-
-Validation Results:
-  Rule-based: ✅ 47/47 passed
-  Quality Score: 0.72/1.00 ⚠️ (Needs improvement)
-
-Issues Found:
-  • MAJOR: Acceptance criteria not testable
-    Location: Section "Success Criteria"
-    Suggestion: Use measurable metrics (e.g., "Login completes in <2s")
-
-  • MINOR: Missing rate limiting specification
-    Location: Section "Security"
-    Suggestion: Specify brute-force protection (5 attempts, 15min lockout)
-
-Score: 0.72 < 0.80 (threshold)
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-🔄 **Attempt 2/3**: Refining with feedback...
-
-✅ PM Agent completed (with feedback)
-🔍 Validating output...
-
-Validation Results:
-  Rule-based: ✅ 47/47 passed
-  Quality Score: 0.85/1.00 ✓ (Improved!)
-
-Issues Found:
-  • MINOR: Performance requirements could be more specific
-    Location: Section "Non-functional Requirements"
-    Suggestion: Add p95/p99 latency targets
+---
 
-Score: 0.85 > 0.80 (threshold) ✅
+## Progress Tracking
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+### Real-Time Updates
 
-✅ **Final Result**: Requirements validated (0.85/1.00)
+Show user current phase and progress:
+```
+🚀 Building SaaS for Event Management
 
-Improvements made:
-  ✓ Acceptance criteria now measurable
-  ✓ Rate limiting specified (5 attempts, 15min lockout)
-  ✓ Testable success metrics added
+Progress: 3/8 phases complete (37.5%)
 
-Minor issues remaining (can be addressed later):
-  • Performance requirements (p95/p99 targets)
+✅ Phase 1: Requirements (PM) - COMPLETE
+✅ Phase 2: Architecture (Architect) - COMPLETE
+✅ Phase 3: Technical Planning (Tech Lead) - COMPLETE
+🔄 Phase 4: Implementation (Backend + Frontend) - IN PROGRESS
+⏳ Phase 5: QA - PENDING
+⏳ Phase 6: Security Review - PENDING
+⏳ Phase 7: DevOps - PENDING
+⏳ Phase 8: Deployment - PENDING
 
-Proceeding to architecture phase...
+Current: Backend implementing user authentication (T-015/45)
 ```
 
-### Configuration for Feedback Loops
+---
 
+## Example Workflows
 
+### Example 1: Build SaaS Product
 
-### Gate Failure Handling
+**User request**: "Build a SaaS for event management"
 
-```typescript
-async function handleGateFailure(gate: QualityGate): Promise<void> {
-  switch (gate.type) {
-    case 'test_pass':
-      // Route to QA Lead for analysis
-      await invokeAgent('qa-lead-agent', 'Analyze test failures');
-      // Then route to appropriate implementation agent
-      break;
-
-    case 'security_review':
-      // Route to Security Agent for details
-      await invokeAgent('security-agent', 'Detail security issues');
-      // Create work items for fixes
-      break;
-
-    case 'performance_target':
-      // Route to Tech Lead for optimization strategy
-      await invokeAgent('tech-lead-agent', 'Performance optimization plan');
-      break;
-
-    case 'user_approval':
-      // Notify user, wait for feedback
-      await notifyUser(gate);
-      await waitForUserApproval(gate);
-      break;
-  }
-}
+**Orchestrator response**:
 ```
+🎯 Creating increment for Event Management SaaS
 
-## Monitoring & Observability
+Created: .specweave/increments/0001-event-management/
 
-### Progress Tracking
+📋 8-Phase Workflow:
 
-```typescript
-interface OrchestrationMetrics {
-  total_phases: number;
-  completed_phases: number;
-  agents_invoked: Record<string, number>;
-  gates_passed: number;
-  gates_failed: number;
-  execution_time: number;
-  estimated_time_remaining: number;
-}
+Phase 1: Requirements & Strategy
+Tell Claude: "Complete spec for increment 0001"
+→ PM will define user stories, features, success criteria
 
-function trackProgress(state: ExecutionState): OrchestrationMetrics {
-  // Calculate metrics
-  // Store in .specweave/orchestration/metrics.json
-  // Display to user
-}
-```
+Phase 2: System Architecture
+Tell Claude: "Design architecture for increment 0001"
+→ Architect will create system design and ADRs
 
-### User Visibility
+Phase 3: Technical Planning
+Tell Claude: "Create technical plan for increment 0001"
+→ Tech Lead will plan implementation approach
 
-Provide clear progress updates:
+Phase 4: Test Strategy
+Tell Claude: "Create test strategy for increment 0001"
+→ QA Lead will define testing approach
 
-```markdown
-🔷 SpecWeave Multi-Agent Orchestration Active
+Phase 5: Backend Implementation
+Tell Claude: "Implement backend for increment 0001"
+→ Backend agent will build APIs and services
 
-**Task**: Build E-Commerce Platform
-**Progress**: Phase 3 of 6 (Implementation)
+Phase 6: Frontend Implementation
+Tell Claude: "Implement frontend for increment 0001"
+→ Frontend agent will build UI
 
-✅ Phase 1: Requirements (PM Agent) - Complete
-✅ Phase 2: Architecture (Architect Agent) - Complete
-🔄 Phase 3: Implementation - In Progress
-   ├─ Backend (nodejs-backend): 65% complete
-   └─ Frontend (frontend-agent): 45% complete
-⏳ Phase 4: Testing (QA Lead) - Waiting
-⏳ Phase 5: Security Review - Waiting
-⏳ Phase 6: Deployment - Waiting
+Phase 7: Security Review
+Tell Claude: "Review security for increment 0001"
+→ Security agent will validate security
 
-**Quality Gates**:
-✅ Architecture Review: Passed
-⏳ Test Coverage (Target: >80%): Currently 67%
-⏳ Security Review: Pending
+Phase 8: Deployment Setup
+Tell Claude: "Setup deployment for increment 0001"
+→ DevOps agent will create infrastructure
 
-**Estimated Time Remaining**: 2-3 hours
+Start with Phase 1!
 ```
 
-## Integration with Other Skills
+### Example 2: Critical Hotfix
 
-### Skill Invocation
+**User request**: "Fix critical security vulnerability CVE-2024-1234"
 
-```typescript
-// role-orchestrator can invoke any other skill
-async function invokeSkill(skillName: string, task: string, context: any) {
-  // Load skill context
-  const skillContext = await loadSkillContext(skillName);
-
-  // Merge with orchestration context
-  const mergedContext = {
-    ...context,
-    ...skillContext,
-    orchestration: {
-      coordinator: 'role-orchestrator',
-      phase: context.current_phase,
-      task_id: generateTaskId()
-    }
-  };
-
-  // Invoke skill
-  const result = await executeSkill(skillName, task, mergedContext);
-
-  // Store result in shared memory
-  await storeResult(skillName, result);
-
-  return result;
-}
+**Orchestrator response**:
 ```
+🚨 CRITICAL HOTFIX WORKFLOW
 
-### Called By
-
-- **specweave-detector**: For complex multi-agent requests
-- **skill-router**: When complexity analysis indicates >3 agents needed
+Created: .specweave/increments/0016-security-fix-cve-2024-1234/
+Type: hotfix (expedited workflow)
 
-### Calls
+⚡ 4-Phase Fast Track:
 
-- All SpecWeave agent skills (pm-agent, architect-agent, etc.)
-- SpecWeave utility skills (context-loader, docs-updater, etc.)
+Phase 1: Security Assessment (5 min)
+Tell Claude: "Assess security vulnerability for increment 0016"
 
-## Configuration
+Phase 2: Fix Implementation (15 min)
+Tell Claude: "Implement security fix for increment 0016"
 
+Phase 3: Validation (10 min)
+Tell Claude: "Validate security fix for increment 0016"
 
+Phase 4: Emergency Deploy (5 min)
+Tell Claude: "Deploy hotfix for increment 0016"
 
-## Testing
-
-### Test Cases
-
-**TC-001: Simple Product Development**
-- Given: User requests "Build a todo app"
-- When: role-orchestrator analyzes request
-- Then: Invokes PM → Architect → Backend → Frontend → QA → DevOps
-- And: All phases complete successfully
-
-**TC-002: Parallel Execution**
-- Given: User requests "Implement payment feature"
-- When: Implementation phase starts
-- Then: Backend and Frontend agents run in parallel
-- And: Both complete without conflicts
-
-**TC-003: Quality Gate Failure**
-- Given: Test coverage is 65% (target: >80%)
-- When: QA gate evaluates
-- Then: Gate fails, blocks deployment
-- And: Routes to QA Lead for analysis
-
-**TC-004: Security Gate**
-- Given: Security review finds critical vulnerability
-- When: Security gate evaluates
-- Then: Blocks deployment
-- And: Creates work items for security fixes
+Total estimated time: 35 minutes
+```
 
-**TC-005: Brownfield Integration**
-- Given: Existing codebase needs new feature
-- When: role-orchestrator receives request
-- Then: Starts with Tech Lead analysis
-- And: Creates regression tests before modification
+---
 
 ## Best Practices
 
-### 1. Clear Phase Boundaries
-
-Each phase should have:
-- Clear inputs
-- Clear outputs
-- Success criteria
-- Failure handling
-
-### 2. Explicit Dependencies
-
-Always declare:
-- Which phases depend on which
-- What artifacts are required
-- What approvals are needed
+**✅ DO**:
+- Create increment structure FIRST
+- Guide user through sequential workflow
+- Use quality gates between phases
+- Track progress and show user updates
+- Handle errors gracefully with retry
+- Allow user to skip optional phases
+
+**❌ DON'T**:
+- Spawn all agents at once (context explosion)
+- Skip increment creation
+- Proceed without quality gate checks
+- Fail silently on agent errors
+- Assume agents are infallible
+- Block user from manual intervention
 
-### 3. Quality Gates at Key Points
-
-Insert gates:
-- After architecture decisions
-- Before implementation
-- After implementation (tests)
-- Before deployment
-
-### 4. User Visibility
-
-Keep users informed:
-- Show current phase
-- Display progress percentage
-- Estimate time remaining
-- Highlight blockers
+---
 
-### 5. Graceful Degradation
+## Integration with SpecWeave Commands
 
-If an agent fails:
-- Retry with backoff
-- Try fallback agent
-- If critical, pause and notify user
-- Don't fail silently
+**After orchestration complete**:
 
-## Resources
+```bash
+# Check status
+/specweave:status
 
-### Multi-Agent Systems Research
-- [Microsoft Autogen](https://microsoft.github.io/autogen/) - Multi-agent conversation framework
-- [LangGraph Multi-Agent](https://blog.langchain.com/langgraph-multi-agent-workflows/) - LangChain's orchestration
-- [CrewAI](https://www.crewai.io/) - Role-based agent collaboration
-- [Amazon Bedrock Multi-Agent](https://aws.amazon.com/blogs/machine-learning/design-multi-agent-orchestration-with-reasoning-using-amazon-bedrock-and-open-source-frameworks/) - AWS multi-agent patterns
+# Sync to external tools
+/specweave:sync-progress 0001
 
-### Orchestration Patterns
-- [Azure AI Agent Patterns](https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns) - Microsoft's agent design patterns
-- [Orchestrator-Worker Pattern](https://www.confluent.io/blog/event-driven-multi-agent-systems/) - Event-driven multi-agent systems
+# Validate quality
+/specweave:qa 0001
 
-### Quality Gates
-- [Shift-Left Testing](https://www.atlassian.com/continuous-delivery/software-testing/shift-left-testing) - Early quality gates
-- [DORA Metrics](https://cloud.google.com/blog/products/devops-sre/using-the-four-keys-to-measure-your-devops-performance) - Deployment quality metrics
+# Close increment
+/specweave:done 0001
+```
 
 ---
 
-## Summary
-
-The **role-orchestrator** skill is the **central nervous system** of SpecWeave's multi-agent architecture:
-
-✅ Coordinates 10+ specialized agents
-✅ Implements hierarchical orchestrator-worker pattern
-✅ Supports sequential, parallel, and adaptive workflows
-✅ Enforces quality gates at critical points
-✅ Provides real-time progress tracking
-✅ Handles failures gracefully with retry and fallback
-✅ Enables complex product development with AI agents
-
-**User benefit**: Submit complex requests like "Build a SaaS" and watch multiple AI agents collaborate seamlessly to deliver the complete solution, from requirements to deployment.
-
-This is the **factory of agents** that makes SpecWeave a true AI-powered development framework.
+**This skill is self-contained and works in ANY user project after `specweave init`.**