Workflow Orchestration

Workflow Orchestration

Guide users through structured thinking and recommend appropriate tools for complex tasks.

Quick Decision

When to Orchestrate

Detect these signals for structured thinking:

Keyword triggers:

• "workflow", "orchestration", "coordinate", "parallel"
• "multi-step", "sequential", "dependencies"
• "break down", "plan this out", "how should I approach"

Context triggers:

• Architectural decisions affecting multiple components
• Multi-file changes requiring coordination
• Problems with unclear scope needing discovery
• Tasks that benefit from specialist agents

Orchestration Pattern

When structured approach is needed:

1. GATE     → Is the request clear and actionable?
2. CONTEXT  → What files/patterns are relevant?
3. PLAN     → What tasks? Parallel vs sequential?
4. EXECUTE  → Deploy specialists, maximize parallelism
5. VALIDATE → Confidence scoring (if needed)
6. REPORT   → Summary with next steps

Command Reference

/core:develop <request> [flags]

Unified SDLC command with 6-phase pipeline and multi-agent orchestration.

Flags:

• --plan-only - Stop after Phase 2 (save plan, don't implement)
• --validate - Enable deep validation with opus agent
• --phase=N - Execute specific phase only
• --auto - Autonomous mode (no checkpoints)

Best for: Feature implementations, refactoring projects, any multi-step development task.

Resume mode: /core:develop @path/to/plan.md loads existing plan and continues.

/think [problem]

Invoke deep-think-partner for collaborative reasoning.

Best for: Single complex problems, decision analysis, reasoning validation, architectural decisions.

Inline Guidance

For simpler tasks, provide structured thinking directly:

1. Clarify scope - What exactly needs to be done? 2. Identify dependencies - What must happen first? 3. Plan sequence - Parallel where possible, sequential where required 4. Execute - Work through each step 5. Verify - Check results meet requirements

Model Tier Strategy

Output

When providing orchestration guidance:

## Recommended Approach

**Complexity:** [Low | Medium | High]
**Suggested tool:** [command or inline]

### Why
[Brief explanation of why this approach fits]

### Steps
1. [First step]
2. [Second step]
...

Additional Resources

• WORKFLOW.md - Detailed orchestration patterns
• EXAMPLES.md - Real-world usage scenarios
• TROUBLESHOOTING.md - Common issues and solutions

Workflow Orchestration Examples

Real-world scenarios demonstrating when and how to use orchestration tools.

Example 1: Feature Implementation

User request:

"I need to add user authentication with JWT tokens to my Express app"

Analysis:

• Multi-step project with several components
• Can parallelize some work (routes, middleware, tests)
• Needs research for best practices
• Benefits from validation

Recommendation:

/core:develop implement user authentication with JWT tokens --validate

Why: This is a multi-agent task with parallel opportunities. The --validate flag ensures security is properly reviewed with deep opus-level validation.

Execution flow: 1. Gate: Clear request, proceed 2. Context: Find existing auth patterns, routes, middleware 3. Plan: Research JWT patterns, identify parallel tasks 4. Execute:

• Wave 1: Auth middleware, JWT utilities (parallel)
• Wave 2: Login/logout routes, token refresh (parallel)
• Wave 3: Integration, error handling

5. Validate: Security review, test coverage check 6. Report: Summary of implemented auth system

---

Example 2: Complex Debugging

User request:

"My API is returning intermittent 500 errors and I can't figure out why"

Analysis:

• Single problem needing deep investigation
• Requires hypothesis formation and testing
• Benefits from structured debugging approach

Recommendation:

/debug intermittent 500 errors in the API

Or for deeper analysis:

/think investigate the intermittent 500 errors - what could cause sporadic failures?

Why: This is a single complex problem, not a multi-agent orchestration task. The /debug command provides structured troubleshooting, while /think engages the deep-think-partner for reasoning through hypotheses.

---

Example 3: Architecture Decision

User request:

"Should I use a monolith or microservices for my new e-commerce platform?"

Analysis:

• Strategic decision with long-term implications
• Needs to weigh multiple trade-offs
• No implementation yet, just reasoning

Recommendation:

/think monolith vs microservices for e-commerce platform

Or for more thorough analysis:

/think evaluate monolith vs microservices architecture for e-commerce, considering team size, scalability needs, and operational complexity

Why: This is a strategic thinking task, not an implementation task. The deep-think-partner or think (extended) will explore trade-offs, consider constraints, and provide reasoned recommendations.

---

Example 4: Multi-File Refactoring

User request:

"Refactor the payment service to use the new API client pattern"

Analysis:

• Coordinated changes across multiple files
• Clear scope, no research needed
• Standard refactoring task

Recommendation:

/core:develop refactor payment service to use new API client pattern

Why: Multi-file coordination benefits from workflow orchestration. No flags needed for a straightforward refactoring task.

Execution flow: 1. Gate: Clear request, proceed 2. Context: Find payment service files, new API client pattern 3. Plan: Map current implementation to new pattern 4. Execute: Deploy agent to update service files 5. Report: Summary of refactored service

---

Example 5: Quick Task (No Orchestration)

User request:

"Add error handling to the getUserById function"

Analysis:

• Single function modification
• Clear scope
• No parallelization opportunity

Recommendation: Inline guidance - no command needed.

Why: This is a simple, focused task. Orchestration would be overkill. Just provide direct implementation guidance.

---

Example 6: Code Review Preparation

User request:

"I need to review and improve the quality of my authentication module before the PR"

Analysis:

• Quality-focused task
• Benefits from multiple angles of review
• Validation is core requirement

Recommendation:

/core:develop review authentication module --validate

Or use the dedicated review commands:

/double-check the authentication module implementation

Why: The --validate flag triggers opus-level deep validation. Alternatively, /double-check is purpose-built for quality validation.

---

Example 7: Learning/Understanding

User request:

"How does the event bus work in this codebase?"

Analysis:

• Understanding task, not implementation
• Needs code exploration
• No changes required

Recommendation: Direct exploration and explanation - no orchestration command needed.

Why: This is a knowledge query, not a task. Read the relevant files and explain the architecture directly.

---

Example 8: High-Stakes Implementation

User request:

"Implement the payment processing integration with Stripe"

Analysis:

• Critical functionality (payments)
• Security-sensitive
• Needs thorough research and validation

Recommendation:

/core:develop implement Stripe payment integration --validate

Why: The --validate flag is essential for high-stakes, security-sensitive implementations. It triggers opus-level deep validation to ensure security is properly reviewed.

---

Decision Matrix

Common Patterns

"How should I approach X?"

Start with /think to reason through the approach, then /core:develop if implementation is needed.

"I need to do A, B, and C"

If independent: /core:develop will parallelize them. If sequential: /core:develop will sequence them appropriately.

"This is really complex"

Use /think for deep analysis, then /core:develop --validate for implementation.

"Before I merge this..."

Use /double-check for quality validation.

Troubleshooting Workflow Orchestration

Common issues and solutions when using orchestration tools.

Choosing the Wrong Tool

Problem: Used /core:develop for a simple task

Symptoms: Excessive overhead, slow execution, unnecessary complexity.

Solution: For single-function changes or simple tasks, skip orchestration and provide direct implementation. Orchestration is for multi-component coordination.

Problem: Used /think when /core:develop was needed

Symptoms: Got analysis but no implementation, reasoning without action.

Solution: /think is for reasoning and decisions. Use /core:develop when you need actual implementation across multiple files/components.

Problem: Task is stuck in analysis

Symptoms: Deep thinking but no progress, endless exploration.

Solution: Set clear boundaries. If analysis is complete, transition to /core:develop for execution. Ask: "Do we understand the problem enough to act?"

---

Workflow Execution Issues

Problem: Gating rejects valid requests

Symptoms: Requests declined that should proceed.

Solutions: 1. Provide more context in the request 2. Break down vague requests into specific asks 3. Include relevant file paths or component names

Example fix:

Bad:  /core:develop make it better
Good: /core:develop refactor the UserService to use dependency injection

Problem: Context discovery misses relevant files

Symptoms: Implementation doesn't follow existing patterns.

Solutions: 1. Mention specific files or patterns to consider 2. Reference CLAUDE.md guidelines 3. Provide explicit file paths or component names in your request

Problem: Too much sequential execution

Symptoms: Slow workflow, tasks running one at a time.

Solutions: 1. Review the plan - are dependencies real? 2. Some tasks may be falsely marked as dependent 3. Consider if subtasks can be parallelized

Problem: Validation is too strict/lenient

Symptoms: Good work flagged as issues, or problems missed.

Solutions:

• Too strict: Focus on objective issues only
• Too lenient: Add --validate for opus-level deep analysis
• Consider what truly blocks vs. what's a nice-to-have

---

Performance Issues

Problem: Workflow takes too long

Symptoms: Extended wait times, timeout concerns.

Solutions: 1. Remove unnecessary flags (don't use all three unless needed) 2. Break large tasks into smaller workflows 3. Use haiku for gating/routing, save opus for deep analysis

Problem: Too many agents spawned

Symptoms: Confusion, conflicting changes, resource exhaustion.

Solutions: 1. Combine related tasks into single agent assignments 2. Ensure wave planning groups appropriately 3. Review if all tasks are truly necessary

---

Quality Issues

Problem: Output doesn't match expectations

Symptoms: Implementation differs from what was requested.

Solutions: 1. Clarify requirements in the initial request 2. Use --validate to add quality gates 3. Provide success criteria explicitly

Problem: Code doesn't follow project conventions

Symptoms: Style inconsistencies, pattern violations.

Solutions: 1. Ensure context discovery found CLAUDE.md 2. Reference specific conventions in request 3. Add examples of expected patterns

Problem: Missing edge cases

Symptoms: Implementation works for happy path only.

Solutions: 1. Mention edge cases explicitly in request 2. Use --validate for opus-level deep analysis 3. Include acceptance criteria with edge case coverage

---

Flag-Related Issues

Problem: --validate is too slow

Symptoms: Analysis takes much longer than expected.

Solutions: 1. Use --validate only for high-stakes implementations 2. Skip for simple refactoring or low-risk changes 3. Reserve opus for security-sensitive or critical features

Problem: --validate catches too much

Symptoms: Validation flags subjective issues.

Solutions: 1. Focus on high-signal criteria (bugs, blockers, violations) 2. Skip style and preference issues 3. Trust linters and tests for mechanical checks

Problem: --plan-only doesn't save plan

Symptoms: Plan not persisted to expected location.

Solutions: 1. Check .arkhe.yaml for custom specs_dir setting 2. Default location is arkhe/specs/NN-feature/ 3. Ensure you have write permissions to the directory

---

Integration Issues

Problem: Conflict between /core:develop and /think outputs

Symptoms: Analysis and implementation don't align.

Solutions: 1. Run /think first for decisions 2. Use conclusions to inform /core:develop request 3. Reference thinking output in develop request

Problem: deep-think-partner and develop don't coordinate

Symptoms: Duplicate analysis, conflicting recommendations.

Solutions: 1. Use one or the other for a given phase 2. deep-think-partner for strategic decisions 3. /core:develop for execution after decisions are made

---

Quick Fixes

Getting Help

If orchestration isn't working as expected:

1. Check if the task actually needs orchestration (simple tasks don't) 2. Review the decision matrix in EXAMPLES.md 3. Ensure the request is specific and actionable 4. Consider breaking complex requests into phases 5. Use /discuss to talk through the approach first

Workflow Orchestration Patterns

Detailed patterns for coordinating complex tasks with structured thinking and multi-agent execution.

The 6-Step Orchestration Model

Step 1: Gating

Purpose: Determine if the request is actionable before investing resources.

Questions to answer:

• Is the request clear enough to proceed?
• Are there obvious blockers (missing context, permissions)?
• Should we proceed, ask clarifying questions, or decline?

Outcomes:

• PROCEED - Request is clear, move to context discovery
• CLARIFY - Ask specific questions before continuing
• DECLINE - Explain why and stop (out of scope, impossible, etc.)

Model: Use haiku for quick gating decisions.

Step 2: Context Discovery

Purpose: Gather relevant project context before planning.

Actions: 1. Locate CLAUDE.md files for project guidelines 2. Check for spec-kit directories (.specify/, plan/, specs/) 3. Load constitutional principles if spec-kit exists 4. Identify key files related to the request 5. Note existing patterns and conventions

Output: List of relevant files, constraints, and principles.

Model: Use haiku for quick context gathering.

Step 3: Analysis & Planning

Purpose: Understand the problem and create an execution plan.

Produce: 1. Clear understanding of what needs to be done 2. List of parallel tasks (can run simultaneously) 3. List of sequential tasks (dependencies) 4. Success criteria for each task

Considerations:

• What can be parallelized?
• What must wait for other tasks?
• What specialist skills are needed?
• What are the acceptance criteria?

Model: Use sonnet for standard planning, opus for complex analysis (with --validate flag).

Step 4: Parallel Execution

Purpose: Deploy specialist agents efficiently.

Wave Pattern:

Wave 1: All independent tasks (parallel)
    ↓
Wave 2: Tasks depending on Wave 1 (parallel within wave)
    ↓
Wave N: Continue until all tasks complete

Agent Assignment Template:

You are assigned to: [task description]

**Context:** [relevant files and background]
**Deliverables:** [specific outputs expected]
**Success Criteria:** [measurable completion conditions]

Complete your task and report results.

Key principle: Maximize parallelism with multiple Agent tool calls in a single response.

Step 5: Validation (Optional)

Purpose: Verify results meet quality standards.

When to use: With --validate flag or for high-stakes changes.

Scoring:

• 90+: High confidence, meets all criteria → Report as complete
• 70-89: Medium confidence, minor issues → Report with caveats
• Below 70: Needs revision → Flag for attention

Model: Use opus for validation (requires deeper analysis).

Step 6: Report

Purpose: Summarize results clearly.

Template:

## Workflow Complete

**Request:** [original request]
**Status:** [Complete | Partial | Blocked]

### Completed
- [Task 1]: [result summary]
- [Task 2]: [result summary]

### Issues (if any)
- [Issue description and recommendation]

### Next Steps (if any)
- [Recommended follow-up actions]

Model Tier Strategy

Guidelines:

• Start with haiku for quick decisions
• Use sonnet for the bulk of work
• Reserve opus for genuinely complex analysis
• --validate flag enables opus-level deep validation

Parallelism Patterns

Independent Tasks (Parallelize)

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Task A     │  │  Task B     │  │  Task C     │
│  (tests)    │  │  (docs)     │  │  (types)    │
└─────────────┘  └─────────────┘  └─────────────┘
       ↓                ↓                ↓
       └────────────────┴────────────────┘
                        ↓
                   [Continue]

Dependent Tasks (Sequential)

┌─────────────┐
│  Task A     │
│  (schema)   │
└─────────────┘
       ↓
┌─────────────┐
│  Task B     │
│  (models)   │
└─────────────┘
       ↓
┌─────────────┐
│  Task C     │
│  (API)      │
└─────────────┘

Mixed Pattern

Wave 1 (parallel):
┌─────────────┐  ┌─────────────┐
│  Schema     │  │  Research   │
└─────────────┘  └─────────────┘
       ↓                ↓
Wave 2 (parallel, depends on Wave 1):
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Models     │  │  Types      │  │  Tests      │
└─────────────┘  └─────────────┘  └─────────────┘
       ↓                ↓                ↓
Wave 3 (depends on Wave 2):
┌─────────────────────────────────────────────────┐
│               Integration                        │
└─────────────────────────────────────────────────┘

High-Signal Issue Filtering

Report these (objective problems):

• Bugs and broken functionality
• Missing required functionality
• Broken dependencies
• Clear violations of CLAUDE.md guidelines
• Blockers preventing completion

Skip these (noise):

• Style preferences
• Subjective suggestions
• Potential/speculative issues
• Items linters or tests catch
• Minor improvements unrelated to task

Flag Reference

Common Patterns:

• --plan-only - Create plan for review before implementing
• --validate - For high-stakes or security-sensitive implementations
• --auto - For well-defined tasks that don't need checkpoints
• @arkhe/specs/01-feature/ - Resume existing spec