workflow-orchestrator

What this skill does

# Workflow Orchestrator Skill

## When to Use

Auto-activates when:
- User invokes `/workflow:start-development-workflow`
- User requests to "build", "implement", "add", "create" features
- Any development task requiring structured workflow

## Overview

The orchestrator manages a **unified workflow** with three sequential stages. Based on complexity, stages can be:
- **Executed fully** (complex)
- **Simplified** (medium)
- **Skipped** (simple)

## Unified Workflow

```
┌─────────────────────────────────────────┐
│  WORKFLOW ORCHESTRATOR                  │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  STAGE A: SPECIFICATION STAGE           │
│  - Analyze requirements                 │
│  - Create spec (SDD + OpenSpec)         │
│  - Validate with PoC (if complex)       │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  STAGE B: DEVELOPMENT STAGE             │
│  - Define behaviors (BDD scenarios)     │
│  - Test-driven implementation (TDD)     │
│  - Iterative refinement                 │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  STAGE C: EXECUTION STAGE               │
│  - Task tracking (if available)         │
│  - Implementation execution             │
│  - Verification & completion            │
└─────────────────────────────────────────┘
```

## Complexity Detection

### Complex Projects (Full Flow)
**Triggers:**
- New system/architecture
- Security-critical features
- >15 steps estimated
- Multiple subsystems
- Unknown requirements

**Workflow:**
```
Stage A: FULL
  ├─ Research existing system
  ├─ Create comprehensive spec (OpenSpec if available)
  ├─ Generate PoC validation tests
  └─ Manual validation questions

Stage B: FULL
  ├─ Define BDD scenarios for all features
  ├─ TDD implementation (RED-GREEN-REFACTOR)
  └─ Continuous spec updates

Stage C: FULL
  ├─ Create tasks (if task-management exists)
  ├─ Track progress per task
  └─ Comprehensive verification
```

### Medium Projects (Streamlined Flow)
**Triggers:**
- Feature additions
- Refactoring
- 8-15 steps estimated
- Existing spec can be extended

**Workflow:**
```
Stage A: SIMPLIFIED
  ├─ Review existing spec
  ├─ Create spec change document
  └─ Skip PoC validation

Stage B: FULL
  ├─ Define BDD scenarios
  ├─ TDD implementation
  └─ Update spec as needed

Stage C: SIMPLIFIED
  ├─ Optional task tracking
  └─ Standard verification
```

### Simple Tasks (Minimal Flow)
**Triggers:**
- Bug fixes
- Small updates
- <8 steps estimated
- Single file/component

**Workflow:**
```
Stage A: SKIP
  └─ No formal spec needed

Stage B: SIMPLIFIED
  ├─ Write tests directly (TDD)
  └─ Implement

Stage C: MINIMAL
  └─ Quick verification
```

## Orchestration Process

### 1. Initialize

```bash
User: /workflow:start-development-workflow "Add user authentication"

Orchestrator:
  1. Analyze request
  2. Detect complexity → COMPLEX
  3. Check integrations:
     - ✓ task-management available
     - ✓ openspec/ directory found
  4. Prepare workflow plan
```

### 2. Execute Stage A (Specification)

**Complex:**
```
→ Invoke: /workflow:create-workflow-spec-stage --mode=full
  1. Research phase
  2. Create OpenAPI spec (using OpenSpec format)
  3. Generate PoC tests (invoke meta-validator agent)
  4. Manual validation questions
  5. Get user approval
```

**Medium:**
```
→ Invoke: /workflow:create-workflow-spec-stage --mode=light
  1. Review existing spec
  2. Create spec change document
  3. Get user approval
```

**Simple:**
```
→ Skip Stage A entirely
```

### 3. Execute Stage B (Development)

**Complex/Medium:**
```
→ Invoke: /workflow:dev-stage --mode=full
  1. Generate BDD scenarios from spec
     - Use /workflow:behavior-driven
  2. For each scenario:
     - Write failing test (RED)
     - Implement feature (GREEN)
     - Refactor (REFACTOR)
     - Use /workflow:test-driven
  3. Update spec as you learn
     - Use /workflow:openspec-integration
```

**Simple:**
```
→ Invoke: /workflow:dev-stage --mode=simple
  1. Write tests directly (TDD)
  2. Implement
  3. Refactor
```

### 4. Execute Stage C (Execution)

**Complex:**
```
→ Invoke: /workflow:exec-stage --mode=full
  1. Create tasks (if task-management exists)
     - Use /workflow:task-integration
  2. For each task:
     - Mark in_progress
     - Execute
     - Mark completed
  3. Comprehensive verification
  4. Final review
```

**Medium:**
```
→ Invoke: /workflow:exec-stage --mode=standard
  1. Optional task tracking
  2. Execute implementation
  3. Standard verification
```

**Simple:**
```
→ Invoke: /workflow:exec-stage --mode=minimal
  1. Run tests
  2. Quick verification
  3. Done
```

## Integration Points

### OpenSpec Integration
```
if [ -d "openspec/" ]; then
  USE_OPENSPEC=true
  BLOCK_A_FORMAT="openspec"
fi
```

### Task Management Integration
```
if task-management plugin exists; then
  USE_TASKS=true
  BLOCK_C_TRACKING="task-based"
fi
```

### SDD Integration
```
For Stage A:
  - Use /workflow:create-workflow-spec-driven-development
  - Create OpenAPI/AsyncAPI specs
```

### BDD Integration
```
For Stage B:
  - Use /workflow:behavior-driven
  - Generate Given-When-Then scenarios
```

### TDD Integration
```
For Stage B:
  - Use /workflow:test-driven-development
  - RED-GREEN-REFACTOR cycle
```

## State Management

Track workflow state in `.claude/workflow-state.md`:

```yaml
---
workflow_id: WF-2026-02-09-001
started: 2026-02-09T10:30:00Z
complexity: complex
status: in_progress
current_block: B
---

# Workflow State

## Request
"Add user authentication with OAuth2"

## Complexity Analysis
- Type: Complex
- Reason: Security-critical, new system
- Estimated steps: 20

## Stage A: Specification ✓
- Spec created: openspec/spec/auth-api.yaml
- PoC validated: Yes
- Approved: 2026-02-09T11:00:00Z

## Stage B: Development (IN PROGRESS)
- BDD scenarios: 8/8 defined
- TDD progress: 4/8 implemented
- Current: Implementing OAuth2 token refresh

## Stage C: Execution (PENDING)
- Tasks created: Yes (TASK-123)
- Subtasks: 0/8 completed
```

## User Interface

**Starting workflow:**
```
User: /workflow:start-development-workflow "Add payment processing"

Orchestrator:
  🔍 Analyzing request...

  Complexity: MEDIUM
  Reason: Feature addition to existing system

  Workflow Plan:
  ┌─ Stage A: Specification (LIGHT)
  │  └─ Update existing payment spec
  ├─ Stage B: Development (FULL)
  │  ├─ BDD scenarios
  │  └─ TDD implementation
  └─ Stage C: Execution (STANDARD)
     └─ Task tracking + verification

  Integrations:
  ✓ OpenSpec (openspec/ found)
  ✓ Task Management (plugin available)

  Proceed? [Y/n]
```

**During execution:**
```
[Stage A] ━━━━━━━━━━━━━━━━━━━━ 100% Complete
[Stage B] ━━━━━━━━━━░░░░░░░░░░  45% In Progress
[Stage C] ░░░░░░░░░░░░░░░░░░░░   0% Pending

Current: Implementing payment validation (TDD)
  RED: Test written ✓
  GREEN: Implementation...
```

## Commands

The orchestrator provides:

**Start workflow:**
```bash
/workflow:start-development-workflow "<description>"
```

**Check status:**
```bash
/workflow:check-workflow-status
# Shows current block, progress, next steps
```

**Skip to block:**
```bash
/workflow:skip-to-b
# Skip Stage A, jump to Stage B
```

**Override complexity:**
```bash
/workflow:start-development-workflow "<description>" --complexity=simple
# Force simple workflow
```

## Decision Matrix

| Complexity | Stage A | Stage B | Stage C |
|------------|---------|---------|---------|
| **Complex** | Full spec + PoC validation | BDD + TDD | Full task tracking |
| **Medium** | Light spec change | BDD + TDD | Standard tracking |
| **Simple** | SKIP | TDD only | Minimal |

## Error Handling

**Block fails:**
```
Stage B failed at step 3/8
  Error: Test failure in OAuth2 validation

Options:
  1. Fix and resume Stage B
  2. Go back to Stage A (update spec)
  3. Switch to simple workflow
```

**User interrupt:**
```
Workflow paused at