Orchestrator
The orchestrator is the execution engine that powers Bootspring workflows. It manages phase transitions, coordinates agents, handles failures, and ensures complex tasks complete successfully.
How the Orchestrator Works
The orchestrator coordinates the entire workflow lifecycle:
┌─────────────────────────────────────────────────────────────────────────┐
│ Orchestrator Engine │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Workflow │ │ Phase │ │ Agent │ │
│ │ Registry │───>│ Manager │───>│ Coordinator │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ State │ │ Gate │ │ Artifact │ │
│ │ Manager │<──>│ Manager │<──>│ Manager │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ═══════════════════════════════════════════════════════════════════ │
│ Persistence Layer │
│ Checkpoints │ Logs │ Artifacts │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Development Lifecycle Phases
The orchestrator understands 9 standard development phases:
┌──────────────────────────────────────────────────────────────────────────┐
│ Development Lifecycle │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Ideation 2. Planning 3. Design 4. Development │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │Concepts │──>│ Scope & │──>│ Schema │──>│ Code │ │
│ │Research │ │Strategy │ │API, UX │ │Building │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────┘ │
│ │ │
│ │ 5. Testing 6. Review 7. Deploy 8. Monitor │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ └─>│ Unit │──>│Security │──>│Release │──>│ Health │ │
│ │E2E, QA │ │ Code QA │ │ CI/CD │ │Analytics│ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────┘ │
│ │ │
│ │ 9. Iterate │
│ │ ┌─────────┐ │
│ └─>│Feedback │──────────────────────────────────┐ │
│ │ Improve │ │ │
│ └─────────┘ ▼ │
│ Back to any phase │
│ │
└──────────────────────────────────────────────────────────────────────────┘
Phase Details
| Phase | Purpose | Default Agent |
|---|---|---|
| Ideation | Brainstorm and research | research-expert |
| Planning | Scope and strategy | architecture-expert |
| Design | Technical specifications | database-expert, api-expert |
| Development | Code implementation | backend-expert, frontend-expert |
| Testing | Quality assurance | testing-expert |
| Review | Code and security review | security-expert, code-review-expert |
| Deploy | Release to production | devops-expert |
| Monitor | Track health and metrics | monitoring-expert |
| Iterate | Improve based on feedback | product-expert |
Execution Modes
Sequential Execution
Phases run one after another:
Plan ──> Design ──> Build ──> Test ──> Review
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
Done Done Done Done Done
Parallel Execution
Multiple agents work simultaneously:
┌──> Backend ──┐
Plan ──> Design ──>│ ├──> Test ──> Review
└──> Frontend ─┘
Adaptive Execution
The orchestrator can adjust based on results:
Plan ──> Design ──> Build ──> Test ──┬──> Review (pass)
│
└──> Fix ──> Test (fail, retry)
State Management
The orchestrator maintains comprehensive state:
Loading code block...
Status Values
| Status | Description |
|---|---|
pending | Not yet started |
running | Currently executing |
paused | Manually or automatically paused |
completed | Successfully finished |
failed | Encountered an error |
cancelled | Manually stopped |
Agent Coordination
The orchestrator manages multiple agents working together:
Agent Assignment
Each phase can have:
- Single agent: One expert handles the phase
- Multiple agents: Several experts collaborate
- Parallel agents: Agents work simultaneously
Loading code block...
Agent Communication
Agents share context through:
- Workflow context: Initial parameters and requirements
- Phase artifacts: Documents created by previous phases
- State updates: Real-time progress information
Phase 1 Output ──────────────────────────────────────┐
│
Phase 2 reads Phase 1 artifacts │
│ │
▼ ▼
Phase 2 Output ───────────> Phase 3 reads all previous artifacts
Quality Gate Integration
The orchestrator enforces quality gates between phases:
Development ──┬──> pre-commit gate ──> pass ──> Testing
│ │
│ └──> fail ──> Fix & Retry
│
└──> blocked until gate passes
Gate Types
| Gate | When | What It Checks |
|---|---|---|
| pre-commit | After development | Linting, formatting, types |
| pre-push | After testing | Tests pass, coverage threshold |
| pre-deploy | After review | Security scan, build success |
Gate Failure Handling
When a gate fails:
- Workflow pauses
- Failure details recorded
- Options presented:
- Fix and retry
- Skip gate (if allowed)
- Cancel workflow
Checkpoint System
The orchestrator creates checkpoints for recovery:
Automatic Checkpoints
Created after each phase completes:
.bootspring/workflows/wf_abc123/
├── checkpoints/
│ ├── planning.json
│ ├── design.json
│ └── development.json
└── state.json
Checkpoint Content
Loading code block...
Recovery
Restore from any checkpoint:
Restore workflow wf_abc123 to the design checkpoint.
The orchestrator will:
- Load checkpoint state
- Reset phases after checkpoint
- Resume from that point
Failure Handling
Automatic Retries
Transient failures are retried automatically:
Loading code block...
Pause on Failure
Significant failures pause the workflow:
Loading code block...
Manual Intervention
Some failures require human decision:
The workflow has paused because tests are failing.
Options:
1. Fix the tests and retry
2. Skip the testing phase (not recommended)
3. Cancel the workflow
Configuration
Basic Configuration
Loading code block...
Phase Configuration
Loading code block...
Checkpoint Configuration
Loading code block...
Monitoring and Logs
Workflow Logs
All orchestrator activity is logged:
.bootspring/workflows/wf_abc123/
└── logs/
├── orchestrator.log # Orchestrator decisions
├── phase-planning.log # Planning phase log
├── phase-design.log # Design phase log
└── phase-dev.log # Development phase log
Log Format
[2024-02-19T10:00:00Z] [INFO] Workflow wf_abc123 started
[2024-02-19T10:00:00Z] [INFO] Phase: planning - Starting
[2024-02-19T10:00:00Z] [INFO] Agent: architecture-expert - Invoked
[2024-02-19T10:03:00Z] [INFO] Phase: planning - Completed (180s)
[2024-02-19T10:03:00Z] [INFO] Checkpoint saved: planning
[2024-02-19T10:03:00Z] [INFO] Phase: design - Starting
Metrics
The orchestrator tracks:
- Total workflow duration
- Phase durations
- Retry counts
- Gate pass/fail rates
- Agent utilization
Best Practices
1. Let the Orchestrator Drive
Don't manually skip phases without good reason. The workflow structure exists for quality.
2. Review Checkpoints
Before resuming a paused workflow, review the last checkpoint to understand the state.
3. Use Quality Gates
Enable gates for production-critical workflows:
Loading code block...
4. Monitor Long Workflows
For workflows over an hour, consider:
- Breaking into smaller workflows
- Adding more checkpoints
- Enabling notifications
5. Handle Failures Properly
- Always investigate failures before skipping
- Use retry for transient issues
- Cancel and restart for fundamental problems
Related
- Workflows - Workflow concepts
- bootspring_orchestrator - Tool reference
- bootspring_loop - Autonomous execution
- Quality Gates - Gate configuration