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