Skip to main content

​
What are workflows?

Workflows are structured patterns for coordinating multiple AI providers across phases. Unlike one-shot queries, workflows manage state, enforce quality gates, and persist decisions across sessions.
Claude Octopus gives you workflows, not just orchestration infrastructure. These patterns are battle-tested across hundreds of projects.

​
Core workflow types

Claude Octopus includes several pre-built workflow patterns:

​
Full Double Diamond workflow

Command: /octo:embracePhases: All four (Discover → Define → Develop → Deliver)Use when:
  • Starting a new feature from scratch
  • Need comprehensive end-to-end development
  • Want research, planning, implementation, and validation
Flow:Example:
/octo:embrace build user authentication with OAuth 2.0
Duration: 5-15 minutes
Cost: $0.10-0.30

​
Specialized workflows

Beyond core patterns, Claude Octopus includes specialized workflows:

TDD

Command: /octo:tddTest-driven development with red-green-refactor cycle

Security

Command: /octo:securityOWASP vulnerability scan and remediation

Debug

Command: /octo:debugRoot cause analysis and fix generation

PRD

Command: /octo:prdAI-optimized PRD with 100-point scoring

Review

Command: /octo:reviewMulti-perspective code review with 4x10 scoring

Research

Command: /octo:researchDeep multi-source research with synthesis

Parallel

Command: /octo:parallelLaunch multiple agents in parallel

Sentinel

Command: /octo:sentinelGitHub-aware work monitor

​
Autonomy modes

Workflows support three autonomy levels:

​
Supervised mode (default)

Behavior: Ask for approval before each phaseUse when:
  • Learning the workflow
  • High-stakes or costly projects
  • Want control over each step
Example flow:
🔍 Discover phase complete
Results: ~/.claude-octopus/results/discover.md

Continue to Define phase? (y/n) █
Pros:
  • Full control
  • Cost awareness
  • Learning opportunity
Cons:
  • Slower execution
  • Requires human presence

​
Workflow composition

Workflows can be nested and composed:

​
Sequential composition

Example: 
# Research → Plan → Execute
/octo:discover OAuth patterns
/octo:define requirements
/octo:develop implementation

​
Parallel composition

Example: 
# Parallel feature development
/octo:parallel --workflows "develop auth" "develop payments" "develop notifications"

​
Conditional composition

Example: 
# Auto-retry on failure
/octo:develop implement feature
# If quality gate fails:
/octo:debug failed subtasks
/octo:develop retry implementation

​
Quality gates and validation

Workflows enforce quality standards at key points:

​
Gate placement

​
Gate criteria

Checks:
  • Research completeness (≥3 sources)
  • Perspective diversity (multiple viewpoints)
  • Actionable insights (clear next steps)
Threshold: 75% consensus
Checks:
  • Clear problem statement
  • Measurable success criteria (≥3 criteria)
  • Known constraints and boundaries
  • Stakeholder agreement
Threshold: 75% consensus
Checks:
  • Subtask success rate ≥75%
  • Provider agreement on approach
  • No critical conflicts
  • Implementation completeness
Threshold: 75% consensus (configurable)
Checks:
  • Code quality score
  • Security findings (no critical)
  • Performance benchmarks met
  • Test coverage ≥80%
Thresholds:
  • ≥90%: SHIP IT
  • 75-89%: SHIP WITH CAUTION
  • Less than 75%: DO NOT SHIP

​
State management

Workflows persist state across phases and sessions:

​
State persistence

.octo/
├── STATE.md              # Current phase, progress
├── decisions.json        # Architectural decisions
├── quality-gates.json    # Gate results
└── context/
    ├── discover.md
    ├── define.md
    ├── develop.md
    └── deliver.md

~/.claude-octopus/
├── results/
│   └── [session-id]/
│       ├── discover-synthesis.md
│       ├── define-requirements.md
│       ├── develop-implementation.md
│       └── deliver-validation.md
└── state.json

​
Context passing

Each phase reads context from prior phases: 
# Define phase
prior_research=$(get_context "discover")

# Develop phase  
requirements=$(get_context "define")
research=$(get_context "discover")

# Deliver phase
full_history=$(get_decisions "all")
implementation=$(get_context "develop")
State persists across Claude Code plan mode context clears (v2.1.63+). Workflows automatically restore from files.

​
Workflow interruption and resume

Workflows can be paused and resumed:

​
Save checkpoint

# Workflow saves state automatically at phase boundaries
# User can Ctrl+C at any time
^C

# State saved to .octo/STATE.md:
# current_phase: 2
# status: "interrupted"
# last_checkpoint: "2026-03-04T15:30:00Z"

​
Resume workflow

/octo:resume

# Output:
# 📋 Found interrupted workflow:
#    Phase: Define (phase 2/4)
#    Last checkpoint: 5 minutes ago
#    
# Resume from Define phase? (y/n)

​
Workflow debugging

Debug workflows with built-in tools:

​
Status check

/octo:status

# Output:
# Current workflow: embrace
# Phase: 3/4 (Develop)
# Status: in_progress
# Quality gates:
#   ✓ Discover: passed (82%)
#   ✓ Define: passed (88%)
#   ⏳ Develop: in progress
#   ⏸ Deliver: pending

​
Debug mode

export OCTOPUS_DEBUG=true
/octo:embrace build auth

# Shows:
# - Provider commands executed
# - Quality gate scores
# - Consensus calculations
# - State transitions

​
Doctor diagnostics

/octo:doctor

# Runs 9-category health checks:
# ✓ Provider availability
# ✓ Authentication status  
# ✓ State file integrity
# ✓ Quality gate configuration
# ⚠ Codex sandbox mode: workspace-write (consider read-only)
# ✓ Cost controls configured
# ...

​
Cost optimization

Workflows are designed for cost efficiency:

Smart routing

Provider router selects cheapest capable provider based on task requirements

Parallel execution

Research and review phases run providers simultaneously (2x faster)

Prompt caching

System prompts and context cached across phases

Early exit

Quality gates prevent wasted work on doomed paths
Cost controls: 
# Set spending limit
export OCTOPUS_MAX_COST_USD=0.50

# Workflow aborts if estimated cost exceeds limit
/octo:embrace build feature
# Error: Estimated cost $0.65 exceeds limit $0.50

​
Best practices

/octo:embrace ensures nothing is skipped. Research, planning, implementation, and validation all contribute to quality.
When refining existing work, use single-phase commands (/octo:develop, /octo:review) instead of full embrace.
If a gate fails, investigate why. Forcing work through undermines the methodology and wastes downstream effort.
Learn the workflow in supervised mode. Once confident, switch to semi-autonomous or autonomous for faster execution.
Use parallel composition for independent features. Use sequential for dependent work.

​
Next steps

Double Diamond

Learn about the four-phase methodology

Personas

Understand specialized agent personas

Commands reference

Browse all 39 workflow commands

Get started

Install and run your first workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us