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:

// 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:

{
  "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:

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:

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:

Use tool: dss_workflow_status
Parameters:
{
  "workflow_id": "uuid-from-previous-call"
}

Returns:

{
  "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:

{
  "evaluation_models": ["gpt-5.1-codex", "gemini-3-pro-preview"],
  "decide_model": "gpt-5-pro"
}

---

Example Workflows

Example 1: Add Feature with Full Pipeline

// 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

// 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

// 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

// 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

// 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:

// 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

// 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)