Intelligence API
The Intelligence API provides intelligent agent orchestration, workflow management, context analysis, decision tracking, and learning capabilities.
Overview#
The Intelligence module is the brain of Bootspring, providing:
- Orchestrator: Coordinates agents based on project phase and context
- Workflows: Predefined multi-phase development workflows
- Memory: Decision tracking and outcome learning
- Recommendations: Smart suggestions based on context and history
REST API Endpoints#
Analyze Context#
POST /api/v1/context/analyzeAnalyze context and get agent recommendations.
Request Body:
{
"context": "I need to implement user authentication with OAuth"
}Response:
1{
2 "data": {
3 "phase": 4,
4 "phaseName": "Implementation",
5 "suggestions": [
6 {
7 "agent": "security-expert",
8 "reason": "Detected authentication context (matched: auth, oauth)",
9 "priority": "high",
10 "source": "trigger"
11 },
12 {
13 "agent": "backend-expert",
14 "reason": "Phase 4 (Implementation) - primary agent",
15 "priority": "high",
16 "source": "phase"
17 }
18 ],
19 "skills": ["auth/clerk", "auth/nextauth"]
20 },
21 "meta": {
22 "requestId": "req_abc123"
23 }
24}JavaScript/Node.js API#
Module Import#
const intelligence = require('bootspring/intelligence');Context Analysis#
analyzeContext(input)#
Analyze context and suggest agents.
Parameters:
| Parameter | Type | Description |
|---|---|---|
input | string | Context text to analyze |
Returns: Analysis result with suggestions.
1const analysis = intelligence.analyzeContext('building authentication api');
2// Returns:
3// {
4// phase: 4,
5// phaseConfig: { name: 'Implementation', ... },
6// suggestions: [
7// { agent: 'security-expert', reason: '...', priority: 'high' }
8// ],
9// skills: ['auth/clerk', 'auth/nextauth'],
10// input: 'building authentication api'
11// }Workflow Management#
listWorkflows()#
List all available workflows.
1const workflows = intelligence.listWorkflows();
2// Returns:
3// [
4// {
5// key: 'feature-development',
6// name: 'Feature Development',
7// description: 'End-to-end feature implementation workflow',
8// phaseCount: 4,
9// tier: 'free',
10// outcomes: ['Feature shipped with tests and review complete'],
11// completionSignals: ['PR merged', 'Tests passing in CI']
12// },
13// ...
14// ]getWorkflow(name)#
Get a specific workflow by name.
const workflow = intelligence.getWorkflow('feature-development');
// Returns full workflow definitionstartWorkflow(workflowName)#
Start a new workflow.
1const result = intelligence.startWorkflow('feature-development');
2// Returns:
3// {
4// success: true,
5// workflowKey: 'feature-development',
6// workflow: 'Feature Development',
7// currentPhase: { name: 'Design', agents: [...], duration: '1-2 days' },
8// totalPhases: 4,
9// completionSignals: [...]
10// }advanceWorkflow()#
Advance to the next workflow step.
1const result = intelligence.advanceWorkflow();
2// Returns:
3// {
4// success: true,
5// complete: false,
6// currentPhase: { name: 'Implementation', ... },
7// step: 2,
8// totalSteps: 4
9// }pauseWorkflow()#
Pause the active workflow.
1const result = intelligence.pauseWorkflow();
2// Returns:
3// {
4// success: true,
5// workflow: 'feature-development',
6// step: 2,
7// message: 'Workflow "feature-development" paused at step 2'
8// }resumeWorkflow()#
Resume a paused workflow.
1const result = intelligence.resumeWorkflow();
2// Returns:
3// {
4// success: true,
5// pauseDuration: 3600,
6// message: 'Workflow resumed (was paused for 3600s)'
7// }isWorkflowPaused()#
Check if workflow is paused.
const status = intelligence.isWorkflowPaused();
// Returns: { paused: true, workflow: 'feature-development', pausedAt: '...' }markWorkflowCheckpoint(workflowName, signalRef)#
Mark a completion signal as done.
1const result = intelligence.markWorkflowCheckpoint('feature-development', 'PR merged');
2// Returns:
3// {
4// success: true,
5// workflow: 'feature-development',
6// signal: 'PR merged',
7// progress: { totalSignals: 3, completedSignals: ['PR merged'], ... }
8// }getWorkflowSignalProgress(workflowName, state)#
Get completion signal progress.
1const progress = intelligence.getWorkflowSignalProgress('feature-development');
2// Returns:
3// {
4// workflow: 'feature-development',
5// totalSignals: 3,
6// completedSignals: ['PR merged'],
7// pendingSignals: ['Tests passing in CI', 'Security review completed']
8// }Parallel Phase Execution#
startParallelPhases(workflowName, startIndex)#
Start concurrent phase execution.
1const result = intelligence.startParallelPhases('full-stack-parallel', 1);
2// Returns:
3// {
4// success: true,
5// parallelPhases: [
6// { index: 1, name: 'Backend Development', agents: [...] },
7// { index: 2, name: 'Frontend Development', agents: [...] }
8// ]
9// }completeParallelPhase(phaseIndex)#
Mark a parallel phase as complete.
1const result = intelligence.completeParallelPhase(1);
2// Returns:
3// {
4// success: true,
5// phaseComplete: true,
6// allParallelComplete: false,
7// remaining: 1
8// }getParallelExecutionStatus()#
Get current parallel execution status.
1const status = intelligence.getParallelExecutionStatus();
2// Returns:
3// {
4// active: true,
5// workflow: 'full-stack-parallel',
6// phases: [...],
7// progress: { completed: 1, total: 2, percent: 50 }
8// }Failure Remediation#
reportPhaseFailure(failureType, details)#
Report a workflow phase failure.
1const result = intelligence.reportPhaseFailure('testing-failure', {
2 message: 'Integration tests failing',
3 errorCount: 5
4});
5// Returns:
6// {
7// success: true,
8// failureId: 'failure-1705123456789',
9// remediation: {
10// description: 'Tests failed during workflow',
11// steps: [...]
12// }
13// }Failure Types:
| Type | Description |
|---|---|
testing | Test failures |
security | Security issues found |
performance | Performance regressions |
deployment | Deployment failures |
database | Database/migration issues |
startRemediation(failureId)#
Start remediation for a failure.
1const result = intelligence.startRemediation('failure-1705123456789');
2// Returns:
3// {
4// success: true,
5// remediation: {
6// description: 'Tests failed during workflow',
7// currentStep: { action: 'analyze_failures', agent: 'testing-expert' },
8// totalSteps: 3
9// }
10// }advanceRemediation()#
Advance to next remediation step.
const result = intelligence.advanceRemediation();
// Returns step progress or completion statusState Management#
loadState()#
Load orchestrator state from project.
1const state = intelligence.loadState();
2// Returns:
3// {
4// lastAnalysis: '2024-01-15T10:30:00Z',
5// currentPhase: 4,
6// activeWorkflow: 'feature-development',
7// workflowStep: 2,
8// suggestions: [...],
9// history: [...]
10// }saveState(state)#
Save orchestrator state.
intelligence.saveState({
activeWorkflow: 'feature-development',
workflowStep: 2,
// ...
});getCurrentPhase()#
Get current project phase from ROADMAP.md.
const phase = intelligence.getCurrentPhase();
// Returns: 1-7 based on roadmap progressMemory & Decision Tracking#
logDecision(options)#
Log a decision for learning.
1const decision = intelligence.logDecision({
2 type: intelligence.DECISION_TYPES.ARCHITECTURE,
3 decision: 'Use server components by default',
4 context: { framework: 'nextjs', version: '14' },
5 agent: 'architecture-expert',
6 alternatives: ['Client components', 'Mixed approach'],
7 reasoning: 'Better performance and SEO',
8 confidence: 0.85,
9 tags: ['performance', 'nextjs'],
10 project_phase: 'implementation'
11});
12// Returns: { id: 'dec_abc123', timestamp: '...', ... }recordOutcome(decisionId, outcome)#
Record the outcome of a decision.
const updated = intelligence.recordOutcome('dec_abc123', {
status: intelligence.OUTCOME_STATUS.SUCCESS,
metrics: { performance_improvement: '40%' },
notes: 'Significant reduction in bundle size'
});Outcome Statuses:
| Status | Description |
|---|---|
SUCCESS | Decision worked well |
PARTIAL | Partially successful |
FAILURE | Decision didn't work |
REVERTED | Decision was rolled back |
PENDING | Outcome not yet known |
getRecommendation(type, decision)#
Get a recommendation based on historical data.
1const rec = intelligence.getRecommendation(
2 intelligence.DECISION_TYPES.DATABASE,
3 'Use connection pooling'
4);
5// Returns:
6// {
7// found: true,
8// recommendation: 'RECOMMENDED',
9// confidence: 0.85,
10// success_rate: 0.92,
11// occurrences: 15,
12// message: 'Based on 15 previous decisions, this approach has a 92% success rate.'
13// }getDecisionStats()#
Get decision statistics.
1const stats = intelligence.getDecisionStats();
2// Returns:
3// {
4// total_decisions: 150,
5// successful_decisions: 120,
6// failed_decisions: 15,
7// success_rate: 0.89,
8// pattern_count: 25
9// }getPatterns()#
Get learned patterns.
const patterns = intelligence.getPatterns();
// Returns array of detected patterns with success ratesgetRecentDecisions(count)#
Get recent decisions.
const recent = intelligence.getRecentDecisions(10);getPendingDecisions()#
Get decisions without recorded outcomes.
const pending = intelligence.getPendingDecisions();Learning & Insights#
analyzePatterns()#
Analyze patterns from decision history.
const analysis = intelligence.analyzePatterns();getSuggestions()#
Get suggestions based on learned patterns.
const suggestions = intelligence.getSuggestions();getInsights()#
Get insights from learning analysis.
const insights = intelligence.getInsights();getAntiPatterns()#
Get detected anti-patterns to avoid.
const antiPatterns = intelligence.getAntiPatterns();MCP Tool#
The bootspring_orchestrator MCP tool provides intelligence functionality.
Tool Definition#
1{
2 "name": "bootspring_orchestrator",
3 "description": "Intelligent agent coordination",
4 "inputSchema": {
5 "properties": {
6 "action": {
7 "enum": ["analyze", "suggest", "recommend", "workflows", "workflow", "start", "next", "checkpoint", "status"]
8 },
9 "context": { "type": "string" },
10 "workflow": { "type": "string" },
11 "signal": { "type": "string" },
12 "limit": { "type": "number" }
13 },
14 "required": ["action"]
15 }
16}Actions#
| Action | Description |
|---|---|
analyze | Analyze context and suggest agents |
suggest | Alias for analyze |
recommend | Get workflow/skill recommendations |
workflows | List available workflows |
workflow | Show specific workflow details |
start | Start a workflow |
next | Advance to next phase |
checkpoint | Mark completion signal |
status | Get orchestrator status |
Available Workflows#
Free Tier#
| Workflow | Phases | Description |
|---|---|---|
feature-development | 4 | End-to-end feature implementation |
security-audit | 3 | Comprehensive security review |
performance-optimization | 4 | Performance review and optimization |
api-development | 4 | API design and implementation |
database-migration | 4 | Schema changes and migrations |
launch-preparation | 4 | Pre-launch checklist |
full-stack-parallel | 5 | Concurrent frontend/backend development |
comprehensive-audit | 5 | Parallel security/performance/quality audits |
Pro Tier (Premium Packs)#
| Workflow | Pack | Description |
|---|---|---|
launch-pack | launch | Guided launch from freeze to production |
reliability-pack | reliability | Reliability hardening for incidents |
growth-pack | growth | Experimentation for activation/conversion |
Phase Agents Mapping#
Each project phase has recommended agents:
| Phase | Name | Primary Agents | Supporting Agents |
|---|---|---|---|
| 1 | Foundation | architecture, database | security, devops |
| 2 | Requirements | database, api | testing |
| 3 | Design | frontend, ui-ux, database, api | security |
| 4 | Implementation | backend, frontend, database | performance, code-review |
| 5 | Testing | testing, security, code-review | performance |
| 6 | Deployment | devops, vercel | security, performance |
| 7 | Launch | devops, performance | security |
Constants#
Decision Types#
1const { DECISION_TYPES } = require('bootspring/intelligence');
2
3// Available types:
4// AGENT_SELECTION, WORKFLOW_CHOICE, SKILL_USAGE
5// ARCHITECTURE, DATABASE, API, UI
6// TESTING, SECURITY, PERFORMANCE
7// DEPLOYMENT, REFACTOR, BUG_FIXOutcome Status#
const { OUTCOME_STATUS } = require('bootspring/intelligence');
// SUCCESS, PARTIAL, FAILURE, REVERTED, PENDINGConfidence Levels#
const { CONFIDENCE_LEVELS } = require('bootspring/intelligence');
// HIGH, MEDIUM, LOWError Handling#
Unknown Workflow#
1{
2 "error": {
3 "code": "NOT_FOUND",
4 "message": "Unknown workflow: invalid-workflow"
5 }
6}No Active Workflow#
1{
2 "error": {
3 "code": "VALIDATION_ERROR",
4 "message": "No active workflow"
5 }
6}Premium Workflow Required#
1{
2 "error": {
3 "code": "FORBIDDEN",
4 "message": "This workflow requires Pro tier"
5 }
6}Best Practices#
- Follow workflow phases: Don't skip phases - each builds on the previous
- Mark checkpoints: Track completion signals for accurate progress
- Record outcomes: Help the system learn from your decisions
- Use context analysis: Let the system suggest appropriate agents
- Handle failures: Use remediation paths when things go wrong