dss/.dss/ZEN_WORKFLOW_ORCHESTRATION.md

# Zen Workflow Orchestration Tools

**Purpose**: Chain Zen AI tools together in intelligent pipelines for complex decision-making and implementation

**Created**: December 6, 2025
**Status**: Implemented in MCP, ready to use

---

## Overview

The Zen workflow orchestration tools automatically execute multi-step AI pipelines:

**Review → Brainstorm → Consensus → Gemini 3 Decides → Implement**

This automates the decision-making process for complex features, refactoring, and architectural decisions.

---

## Available Tools

### 1. `dss_smart_implement` (Full Pipeline)

**Purpose**: Complete implementation workflow with all steps

**Pipeline**:
1. **Review** - Analyze existing code with codereview
2. **Brainstorm** - Generate 3-5 solution approaches with chat
3. **Consensus** - Multi-model evaluation (GPT-5.1, Gemini-2.5-Pro, Claude Sonnet 4.5)
4. **Decide** - Gemini 3 Pro makes final decision
5. **Implement** - Returns implementation plan

**Usage**:
```javascript
// From Claude Code MCP:
Use tool: dss_smart_implement
Parameters:
{
  "task_description": "Add dark mode toggle to dashboard",
  "context_files": [
    "/home/overbits/dss/admin-ui/index.html",
    "/home/overbits/dss/admin-ui/js/core/app.js"
  ],
  "requirements": "Must persist user preference, support system theme",
  "skip_review": false
}
```

**Returns**:
```json
{
  "workflow_id": "uuid-here",
  "status": "completed",
  "steps": [
    {"step": "review", "status": "completed", "result": {...}},
    {"step": "brainstorm", "status": "completed", "result": {...}},
    {"step": "consensus", "status": "completed", "result": {...}},
    {"step": "decide", "status": "completed", "result": {...}},
    {"step": "implement", "status": "ready", "plan": "..."}
  ],
  "final_implementation": "Detailed implementation plan...",
  "decision_rationale": "Consensus analysis and reasoning...",
  "continuation_id": "continuation-id-here"
}
```

**When to Use**:
- Complex features requiring architectural decisions
- Refactoring that affects multiple components
- Security-sensitive implementations
- Performance optimizations
- Major UI/UX changes

---

### 2. `dss_review_brainstorm_decide` (Simplified Pipeline)

**Purpose**: Faster workflow without consensus step

**Pipeline**:
1. Review existing code
2. Brainstorm solutions
3. Gemini 3 decides

**Usage**:
```javascript
Use tool: dss_review_brainstorm_decide
Parameters:
{
  "issue_description": "Fix memory leak in browser logger",
  "context_files": [
    "/home/overbits/dss/admin-ui/js/core/browser-logger.js"
  ]
}
```

**When to Use**:
- Bug fixes
- Smaller features
- Quick decisions needed
- Time-sensitive tasks

---

### 3. `dss_consensus_implement` (Green-field Pipeline)

**Purpose**: New feature implementation without review

**Pipeline**:
1. Brainstorm approaches
2. Multi-model consensus
3. Implementation plan

**Usage**:
```javascript
Use tool: dss_consensus_implement
Parameters:
{
  "feature_description": "Add user authentication with OAuth",
  "evaluation_models": ["gpt-5.1", "gemini-2.5-pro", "claude-sonnet-4-5"],
  "decide_model": "gemini-3-pro-preview"
}
```

**When to Use**:
- New features (no existing code)
- Green-field development
- Prototype implementations
- Architecture design

---

### 4. `dss_workflow_status` (Status Check)

**Purpose**: Check status of running workflow

**Usage**:
```javascript
Use tool: dss_workflow_status
Parameters:
{
  "workflow_id": "uuid-from-previous-call"
}
```

**Returns**:
```json
{
  "workflow_id": "uuid",
  "type": "smart_implement",
  "status": "in_progress|completed|failed",
  "task": "Original task description",
  "steps": [...],
  "started_at": "2025-12-06T...",
  "completed_at": "2025-12-06T...",
  "error": null
}
```

---

## Workflow States

### Status Values
- **in_progress**: Workflow currently executing
- **completed**: All steps finished successfully
- **failed**: Workflow encountered error

### Step Statuses
- **completed**: Step finished successfully
- **ready**: Step ready to execute (for implement step)
- **failed**: Step encountered error

---

## How Context is Maintained

All workflows use Zen's `continuation_id` feature to maintain context across steps:

1. Step 1 (Review) creates continuation_id
2. Step 2 (Brainstorm) receives continuation_id, sees all context from Step 1
3. Step 3 (Consensus) receives continuation_id, sees context from Steps 1 & 2
4. And so on...

This ensures each step has full context from previous steps without re-sending data.

---

## Models Used

### Default Models by Step

| Step | Model | Reason |
|------|-------|--------|
| Review | gpt-5.1 | Excellent code analysis |
| Brainstorm | gpt-5.1 | Creative solution generation |
| Consensus (For) | gpt-5.1 | Optimistic evaluation |
| Consensus (Against) | gemini-2.5-pro | Critical evaluation |
| Consensus (Neutral) | claude-sonnet-4-5 | Balanced perspective |
| Final Decision | gemini-3-pro-preview | Best overall reasoning |

### Override Models

You can specify different models in `dss_consensus_implement`:
```javascript
{
  "evaluation_models": ["gpt-5.1-codex", "gemini-3-pro-preview"],
  "decide_model": "gpt-5-pro"
}
```

---

## Example Workflows

### Example 1: Add Feature with Full Pipeline

```javascript
// Step 1: Start workflow
Use tool: dss_smart_implement
{
  "task_description": "Add export functionality to browser logger",
  "context_files": [
    "/home/overbits/dss/admin-ui/js/core/browser-logger.js"
  ],
  "requirements": "Must support JSON and CSV formats, max 10MB export"
}

// Step 2: Receive implementation plan
{
  "workflow_id": "abc-123",
  "status": "completed",
  "final_implementation": "
    1. Add exportFormats property to BrowserLogger class
    2. Implement exportAsJSON() method
    3. Implement exportAsCSV() method with csv-stringify
    4. Add format parameter to export() method
    5. Add download trigger with file size check
    ...",
  "decision_rationale": "Consensus favored modular approach with separate
    format handlers. Gemini 3 confirmed this allows easy addition of new formats."
}

// Step 3: Execute implementation (use Write/Edit tools)
// Follow the implementation plan from the workflow result
```

---

### Example 2: Quick Bug Fix

```javascript
// Use simplified workflow for faster turnaround
Use tool: dss_review_brainstorm_decide
{
  "issue_description": "Browser logger not capturing fetch errors",
  "context_files": [
    "/home/overbits/dss/admin-ui/js/core/browser-logger.js"
  ]
}

// Returns focused fix without full consensus process
```

---

### Example 3: Check Long-Running Workflow

```javascript
// Start complex workflow
Use tool: dss_smart_implement
{ ... }

// Returns workflow_id: "abc-123"

// Later, check status
Use tool: dss_workflow_status
{ "workflow_id": "abc-123" }

// See current progress
{
  "status": "in_progress",
  "steps": [
    {"step": "review", "status": "completed"},
    {"step": "brainstorm", "status": "completed"},
    {"step": "consensus", "status": "in_progress"}
  ]
}
```

---

## Performance Characteristics

### Execution Times (Estimated)

| Workflow | Steps | Avg Time |
|----------|-------|----------|
| smart_implement | 5 | 3-5 min |
| review_brainstorm_decide | 3 | 1-2 min |
| consensus_implement | 3 | 2-3 min |

Times vary based on:
- Model response times
- Complexity of task
- Number of context files
- Length of code being analyzed

---

## Error Handling

### Common Errors

**Error**: "Workflow not found"
- **Cause**: Invalid workflow_id
- **Solution**: Check workflow_id from original call

**Error**: "Workflow failed: Model timeout"
- **Cause**: Zen tool took too long to respond
- **Solution**: Retry with simpler task or fewer context files

**Error**: "Invalid model specified"
- **Cause**: Model name not recognized by Zen
- **Solution**: Use `listmodels` tool to see available models

---

## Best Practices

### 1. Choose Right Workflow

- **Full pipeline** (smart_implement): Complex features, architecture decisions
- **Simplified** (review_brainstorm_decide): Bug fixes, quick tasks
- **Green-field** (consensus_implement): New features, no existing code

### 2. Provide Good Context

```javascript
// Good: Specific context files
"context_files": [
  "/path/to/exact/file.js",
  "/path/to/related/file.css"
]

// Bad: Too broad
"context_files": [
  "/entire/project/directory/*"
]
```

### 3. Write Clear Descriptions

```javascript
// Good
"task_description": "Add dark mode toggle that persists user preference
  in localStorage and syncs with system theme via matchMedia API"

// Bad
"task_description": "add dark mode"
```

### 4. Use Continuation ID

If workflow fails partway through, you can restart with the continuation_id:

```javascript
// Workflow failed at step 3
{
  "workflow_id": "abc-123",
  "status": "failed",
  "continuation_id": "cont-xyz",
  "steps": [
    {"step": "review", "status": "completed"},
    {"step": "brainstorm", "status": "completed"},
    {"step": "consensus", "status": "failed"}
  ]
}

// Resume manually with zen__consensus using continuation_id
Use tool: mcp__zen__consensus
{
  "continuation_id": "cont-xyz",
  ... // other params
}
```

---

## Integration with Existing Tools

### Combine with DSS Tools

```javascript
// 1. Use smart_implement to get plan
Use tool: dss_smart_implement
{ "task_description": "Add new component to design system" }

// 2. Use DSS project tools to check existing components
Use tool: dss_list_components
{ "project_id": "main" }

// 3. Implement using Write/Edit tools
// 4. Use DSS tools to verify
Use tool: dss_get_project_summary
```

---

## Future Enhancements

### Planned Features (Not Yet Implemented)
- [ ] Auto-implement step (actually writes code)
- [ ] Test generation after implementation
- [ ] Code review of generated code
- [ ] Rollback on failed implementation
- [ ] Workflow templates (save common pipelines)
- [ ] Background execution (async workflows)

---

## Related Documentation

- `.dss/MCP_DEBUG_TOOLS_ARCHITECTURE.md` - Overall MCP architecture
- `.dss/WORKFLOWS/` - Debug workflows
- `tools/dss_mcp/tools/workflow_tools.py` - Implementation source
- Zen MCP docs for underlying tools

---

## Quick Reference Card

```
┌─────────────────────────────────────────────────────────────┐
│  Zen Workflow Orchestration - Quick Reference              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Full Pipeline (3-5 min):                                   │
│    dss_smart_implement                                      │
│    → Review → Brainstorm → Consensus → Decide → Plan       │
│                                                             │
│  Quick Fix (1-2 min):                                       │
│    dss_review_brainstorm_decide                            │
│    → Review → Brainstorm → Decide                          │
│                                                             │
│  New Feature (2-3 min):                                     │
│    dss_consensus_implement                                  │
│    → Brainstorm → Consensus → Plan                         │
│                                                             │
│  Check Status:                                              │
│    dss_workflow_status { workflow_id }                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

**Status**: ✅ Implemented and ready to use
**Location**: `tools/dss_mcp/tools/workflow_tools.py`
**Registered**: DSS MCP Server (will be available after restart)