Orchestrator API
The Orchestrator API provides intelligent agent coordination, context analysis, workflow management, and recommendation services. It is the brain behind Bootspring's intelligent assistance.
Overview#
The Orchestrator manages:
- Context Analysis: Understanding what you're working on
- Agent Suggestions: Recommending the right experts
- Workflow Management: Guiding structured development processes
- Recommendations: Suggesting skills, workflows, and actions
REST API Endpoints#
Analyze Context#
POST /api/v1/orchestrator/analyzeAnalyze context and get intelligent suggestions.
Request Body:
{
"context": "Building a user authentication system with OAuth"
}Response:
1{
2 "data": {
3 "phase": "feature-development",
4 "phaseName": "Feature Development",
5 "suggestions": [
6 {
7 "type": "agent",
8 "agent": "security-expert",
9 "reason": "Authentication requires security expertise"
10 }
11 ],
12 "skills": ["auth/oauth", "auth/clerk", "security/headers"]
13 },
14 "meta": {
15 "requestId": "req_abc123"
16 }
17}Get Recommendations#
POST /api/v1/orchestrator/recommendGet intelligent recommendations for agents, skills, and workflows.
Request Body:
{
"context": "Need to optimize database performance",
"limit": 5
}Response:
1{
2 "data": {
3 "agents": [
4 {
5 "id": "database-expert",
6 "name": "Database Expert",
7 "confidence": 0.95,
8 "reason": "Database optimization expertise"
9 },
10 {
11 "id": "performance-expert",
12 "name": "Performance Expert",
13 "confidence": 0.82,
14 "reason": "Performance profiling"
15 }
16 ],
17 "skills": [
18 {
19 "id": "database/query-optimization",
20 "name": "Query Optimization",
21 "confidence": 0.92
22 }
23 ],
24 "workflows": [
25 {
26 "id": "performance-optimization",
27 "name": "Performance Optimization",
28 "confidence": 0.88
29 }
30 ]
31 }
32}List Workflows#
GET /api/v1/orchestrator/workflowsList all available workflows.
Response:
1{
2 "data": {
3 "workflows": [
4 {
5 "key": "feature-development",
6 "name": "Feature Development",
7 "description": "Structured approach for building new features",
8 "tier": "free",
9 "phases": 5
10 },
11 {
12 "key": "deployment",
13 "name": "Production Deployment",
14 "description": "Step-by-step deployment process",
15 "tier": "free",
16 "phases": 4
17 }
18 ],
19 "hiddenCount": 3
20 }
21}Get Workflow Details#
GET /api/v1/orchestrator/workflows/:keyGet detailed information about a specific workflow.
Parameters:
| Parameter | Type | Description |
|---|---|---|
key | string | Workflow identifier |
Response:
1{
2 "data": {
3 "key": "feature-development",
4 "name": "Feature Development",
5 "description": "Structured approach for building new features",
6 "tier": "free",
7 "phases": [
8 {
9 "name": "Requirements",
10 "description": "Define requirements and acceptance criteria",
11 "agents": ["product-expert", "software-architect"],
12 "skills": ["planning/requirements"]
13 },
14 {
15 "name": "Design",
16 "description": "Design the technical solution",
17 "agents": ["software-architect", "frontend-expert"],
18 "skills": ["architecture/design"]
19 },
20 {
21 "name": "Implementation",
22 "description": "Build the feature",
23 "agents": ["frontend-expert", "backend-expert"],
24 "skills": ["varies by feature"]
25 },
26 {
27 "name": "Testing",
28 "description": "Write and run tests",
29 "agents": ["testing-expert"],
30 "skills": ["testing/vitest", "testing/playwright"]
31 },
32 {
33 "name": "Review",
34 "description": "Code review and refinement",
35 "agents": ["code-review-expert"],
36 "skills": ["quality/code-review"]
37 }
38 ],
39 "completionSignals": [
40 "Requirements documented",
41 "Design approved",
42 "Implementation complete",
43 "Tests passing",
44 "Review approved"
45 ]
46 }
47}Start Workflow#
POST /api/v1/orchestrator/workflows/:key/startStart a workflow.
Response:
1{
2 "data": {
3 "success": true,
4 "workflow": "feature-development",
5 "currentPhase": {
6 "index": 0,
7 "name": "Requirements",
8 "description": "Define requirements and acceptance criteria"
9 },
10 "agents": ["product-expert", "software-architect"],
11 "signalProgress": {
12 "total": 5,
13 "completed": 0,
14 "signals": []
15 }
16 }
17}Advance Workflow#
POST /api/v1/orchestrator/workflows/advanceAdvance to the next phase of the active workflow.
Response:
1{
2 "data": {
3 "success": true,
4 "workflow": "feature-development",
5 "previousPhase": "Requirements",
6 "currentPhase": {
7 "index": 1,
8 "name": "Design",
9 "description": "Design the technical solution"
10 },
11 "agents": ["software-architect", "frontend-expert"],
12 "signalProgress": {
13 "total": 5,
14 "completed": 1,
15 "signals": ["Requirements documented"]
16 }
17 }
18}Mark Checkpoint#
POST /api/v1/orchestrator/workflows/checkpointMark a completion signal as done.
Request Body:
{
"signal": "Design approved"
}Response:
1{
2 "data": {
3 "success": true,
4 "signal": "Design approved",
5 "progress": {
6 "total": 5,
7 "completed": 2,
8 "percentage": 40
9 }
10 }
11}Get Status#
GET /api/v1/orchestrator/statusGet current orchestrator status.
Response:
1{
2 "data": {
3 "currentPhase": "feature-development",
4 "lastAnalysis": "2024-01-15T10:30:00Z",
5 "activeWorkflow": {
6 "key": "feature-development",
7 "step": 2,
8 "totalSteps": 5,
9 "signalProgress": {
10 "completed": 2,
11 "total": 5
12 }
13 },
14 "availableAgents": 36,
15 "recentSuggestions": [
16 {
17 "type": "agent",
18 "agent": "frontend-expert"
19 }
20 ]
21 }
22}JavaScript/Node.js API#
Module Import#
const intelligence = require('bootspring/intelligence');Functions#
analyzeContext(context)#
Analyze context and get suggestions.
1const analysis = intelligence.analyzeContext('Building user authentication');
2
3// Returns:
4// {
5// phase: 'feature-development',
6// phaseConfig: {...},
7// suggestions: [...],
8// skills: [...]
9// }listWorkflows()#
List all available workflows.
const workflows = intelligence.listWorkflows();
// Returns array of workflow objectsgetWorkflow(key)#
Get a specific workflow by key.
const workflow = intelligence.getWorkflow('feature-development');
// Returns workflow object or nullstartWorkflow(key)#
Start a workflow.
1const result = intelligence.startWorkflow('feature-development');
2
3// Returns:
4// {
5// success: true,
6// workflow: 'feature-development',
7// phase: {...},
8// agents: [...]
9// }advanceWorkflow()#
Advance the active workflow to the next phase.
1const result = intelligence.advanceWorkflow();
2
3// Returns:
4// {
5// success: true,
6// previousPhase: 'Requirements',
7// currentPhase: {...}
8// }markWorkflowCheckpoint(workflow, signal)#
Mark a completion signal as done.
const result = intelligence.markWorkflowCheckpoint(
'feature-development',
'Requirements documented'
);getWorkflowSignalProgress(workflow)#
Get progress on workflow completion signals.
1const progress = intelligence.getWorkflowSignalProgress('feature-development');
2
3// Returns:
4// {
5// total: 5,
6// completed: 2,
7// signals: ['Requirements documented', 'Design approved']
8// }loadState() / saveState(state)#
Load and save orchestrator state.
const state = intelligence.loadState();
intelligence.saveState(state);getCurrentPhase()#
Get the current development phase.
const phase = intelligence.getCurrentPhase();
// Returns: 'feature-development', 'debugging', etc.getAvailableAgents()#
Get list of available agents for the current phase.
const agents = intelligence.getAvailableAgents();
// Returns array of agent objectsMCP Tool#
The bootspring_orchestrator MCP tool provides orchestrator functionality to AI assistants.
Tool Definition#
1{
2 "name": "bootspring_orchestrator",
3 "description": "Intelligent agent coordination. Analyze context, suggest agents, manage workflows.",
4 "inputSchema": {
5 "type": "object",
6 "properties": {
7 "action": {
8 "type": "string",
9 "enum": ["analyze", "suggest", "recommend", "workflows", "workflow", "start", "next", "checkpoint", "status"]
10 },
11 "context": {
12 "type": "string",
13 "description": "Context text to analyze"
14 },
15 "workflow": {
16 "type": "string",
17 "description": "Workflow name"
18 },
19 "signal": {
20 "type": "string",
21 "description": "Completion signal for checkpoint"
22 },
23 "limit": {
24 "type": "number",
25 "description": "Max recommendations (default: 5)"
26 }
27 },
28 "required": ["action"]
29 }
30}Actions#
| Action | Description | Parameters |
|---|---|---|
analyze | Analyze context | context |
suggest | Get agent suggestions | context |
recommend | Get recommendations | context, limit |
workflows | List all workflows | - |
workflow | Get workflow details | workflow |
start | Start a workflow | workflow |
next | Advance workflow | - |
checkpoint | Mark signal complete | signal, workflow (optional) |
status | Get current status | - |
Examples#
Analyze context:
{
"action": "analyze",
"context": "Building user authentication"
}Get recommendations:
{
"action": "recommend",
"context": "Need to optimize API performance",
"limit": 5
}Start workflow:
{
"action": "start",
"workflow": "feature-development"
}Mark checkpoint:
{
"action": "checkpoint",
"signal": "Requirements documented"
}Workflow Phases#
The orchestrator tracks development phases:
| Phase | Description | Typical Agents |
|---|---|---|
initialization | Project setup | software-architect, devops-expert |
requirements | Defining requirements | product-expert, software-architect |
design | Technical design | software-architect, frontend-expert |
implementation | Building features | frontend-expert, backend-expert |
testing | Writing tests | testing-expert |
debugging | Fixing issues | debugging-detective |
optimization | Performance tuning | performance-expert |
deployment | Going live | devops-expert, security-expert |
maintenance | Ongoing work | varies |
Advanced Features#
Workflow Composition#
Create custom workflows by composing phases:
const composition = intelligence.createComposition({
name: 'Custom Feature Flow',
workflows: ['requirements', 'feature-development', 'deployment']
});Agent Collaboration#
Coordinate multiple agents:
const session = intelligence.startCollabSession({
lead: 'software-architect',
participants: ['frontend-expert', 'backend-expert']
});Parallel Phase Execution#
Run phases in parallel:
const result = intelligence.startParallelPhases(
'feature-development',
['Frontend Implementation', 'Backend Implementation']
);Adaptive Workflows#
Handle failures and remediation:
1intelligence.reportPhaseFailure('testing', {
2 error: 'Tests failing',
3 context: 'Integration tests timeout'
4});
5
6const remediation = intelligence.startRemediation('testing');Error Handling#
Workflow Not Found#
1{
2 "error": {
3 "code": "WORKFLOW_NOT_FOUND",
4 "message": "Unknown workflow: invalid-workflow"
5 }
6}No Active Workflow#
1{
2 "error": {
3 "code": "NO_ACTIVE_WORKFLOW",
4 "message": "No active workflow to advance"
5 }
6}Premium Required#
1{
2 "error": {
3 "code": "PREMIUM_REQUIRED",
4 "message": "This workflow requires Pro tier",
5 "upgradeUrl": "https://bootspring.com/pricing"
6 }
7}Best Practices#
- Start with Analysis: Always analyze context before starting workflows
- Follow Workflow Phases: Let the orchestrator guide you through structured development
- Mark Checkpoints: Track progress by marking completion signals
- Use Recommendations: Follow agent and skill recommendations for best results
- Handle Failures: Use adaptive workflows when things go wrong
Related#
- Agents API - Agent invocation
- Skills API - Skill patterns
- Workflows - Workflow documentation
- bootspring_orchestrator MCP Tool - MCP tool reference