Workflow patterns - Claude Octopus

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:

Embrace
Factory
Debate
Individual Phases

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

Dark Factory (autonomous pipeline)

Command: /octo:factoryPhases: Discover → Define → Develop → Deliver → Test → ScoreUse when:

Spec-to-software automation
Autonomous development without supervision
Need holdout testing and satisfaction scoring

Flow:Example:

/octo:factory "build a CLI that converts CSV to JSON"

Duration: 10-20 minutes
Cost: $0.20-0.50

Multi-AI debate

Command: /octo:debateRounds: 1-10 (configurable)Use when:

Need to evaluate trade-offs
Want adversarial perspectives
Comparing two or more approaches

Flow:Example:

/octo:debate Redis vs DynamoDB for session storage
/octo:debate -r 3 monorepo vs microservices

Duration: 1-3 minutes per round
Cost: $0.05-0.15

Single-phase workflows

Run individual Double Diamond phases:

Command	Phase	Use When
`/octo:discover`	Discover	Research without full workflow
`/octo:define`	Define	Scope before implementation
`/octo:develop`	Develop	Implement with quality gates
`/octo:deliver`	Deliver	Review and validate

Examples:

# Research OAuth patterns
/octo:discover OAuth 2.0 for multi-tenant SaaS

# Scope requirements
/octo:define requirements for payment integration

# Implement feature
/octo:develop user registration API

# Validate implementation
/octo:deliver review auth module

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
Semi-Autonomous
Autonomous

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

Semi-autonomous mode

Behavior: Continue automatically unless quality gate failsEnable with:

export OCTOPUS_AUTONOMY=semi-autonomous

Use when:

Trusted workflow
Medium confidence in requirements
Human available for escalations

Example flow:

✅ Quality gate passed (82% consensus)
🛠️ Proceeding to Develop phase automatically...

---

⚠️ Quality gate failed (68% consensus)
Human review needed:
- Subtask 3 failed: JWT secret strength
- Subtask 7 failed: Rate limiting missing

Retry with fixes? (y/n) █

Pros:

Faster than supervised
Catches failures
Human in loop when needed

Cons:

Less predictable timing
May interrupt at inconvenient times

Autonomous mode

Behavior: Run all phases without interruptionEnable with:

export OCTOPUS_AUTONOMY=autonomous
# or use /octo:factory command

Use when:

Well-understood problem
High confidence in spec
Dark Factory mode
No human available

Example flow:

🐙 AUTONOMOUS MODE - All phases will run without approval

🔍 Discover: OAuth patterns... ✓
🎯 Define: Requirements... ✓
🛠️ Develop: Implementation... ✓ (passed quality gate: 85%)
✅ Deliver: Validation... ✓ (score: 92% - SHIP)

✓ Complete! Results: ~/.claude-octopus/results/

Pros:

Fully autonomous
No interruptions
Works while you sleep

Cons:

No human oversight
May make wrong decisions
Higher cost if goes off track

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

Discover → Define gate

Checks:

Research completeness (≥3 sources)
Perspective diversity (multiple viewpoints)
Actionable insights (clear next steps)

Threshold: 75% consensus

Define → Develop gate

Checks:

Clear problem statement
Measurable success criteria (≥3 criteria)
Known constraints and boundaries
Stakeholder agreement

Threshold: 75% consensus

Develop → Deliver gate

Checks:

Subtask success rate ≥75%
Provider agreement on approach
No critical conflicts
Implementation completeness

Threshold: 75% consensus (configurable)

Deliver validation

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

Use full workflows for new features

/octo:embrace ensures nothing is skipped. Research, planning, implementation, and validation all contribute to quality.

Use individual phases for iterations

When refining existing work, use single-phase commands (/octo:develop, /octo:review) instead of full embrace.

Respect quality gates

If a gate fails, investigate why. Forcing work through undermines the methodology and wastes downstream effort.

Start supervised, graduate to autonomous

Learn the workflow in supervised mode. Once confident, switch to semi-autonomous or autonomous for faster execution.

Compose workflows strategically

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

​What are workflows?

​Core workflow types

​Full Double Diamond workflow

​Dark Factory (autonomous pipeline)

​Multi-AI debate

​Single-phase workflows

​Specialized workflows

TDD

Security

Debug

PRD

Review

Research

Parallel

Sentinel

​Autonomy modes

​Supervised mode (default)

​Semi-autonomous mode

​Autonomous mode

​Workflow composition

​Sequential composition

​Parallel composition

​Conditional composition

​Quality gates and validation

​Gate placement

​Gate criteria

​State management

​State persistence

​Context passing

​Workflow interruption and resume

​Save checkpoint

​Resume workflow

​Workflow debugging

​Status check

​Debug mode

​Doctor diagnostics

​Cost optimization

Smart routing

Parallel execution

Prompt caching

Early exit

​Best practices

​Next steps

Double Diamond

Personas

Commands reference

Get started

What are workflows?

Core workflow types

Full Double Diamond workflow

Dark Factory (autonomous pipeline)

Multi-AI debate

Single-phase workflows

Specialized workflows

Autonomy modes

Supervised mode (default)

Semi-autonomous mode

Autonomous mode

Workflow composition

Sequential composition

Parallel composition

Conditional composition

Quality gates and validation

Gate placement

Gate criteria

State management

State persistence

Context passing

Workflow interruption and resume

Save checkpoint

Resume workflow

Workflow debugging

Status check

Debug mode

Doctor diagnostics

Cost optimization

Best practices

Next steps