spine-showcase

SPINE - Multi-Agent Orchestration System

A context engineering and multi-agent backbone framework for complex software development workflows.

---

Overview

SPINE (Software Pipeline for INtelligent Engineering) provides standardized instrumentation, multi-provider LLM access, and orchestration patterns that connect agentic projects for long-running, complex development workflows.

Key Capabilities

Capability	Description
🔄 Multi-Agent Orchestration	Fan-out (parallel) and Pipeline (sequential) patterns
📊 Full Traceability	ToolEnvelope instrumentation with hierarchical trace correlation
🤖 Multi-Provider Support	Anthropic, OpenAI, Google Gemini, Grok
📋 Tiered Enforcement	Balanced capability usage based on task complexity
🧠 Context Stacks	Reproducible, structured context management via YAML scenarios
🔁 Agentic Loop	Autonomous “run until done” with oscillation detection
📝 AI Code Review	Multi-persona parallel review with consensus ranking
📈 Observability	Static HTML reports, REST API, health checks
⚙️ Pluggable Executors	SubagentExecutor (personas) and ClaudeCodeExecutor (CLI)
🧠 Persistent Memory	Optional Minna Memory integration for cross-session memory

---

🏗️ Architectural Foundation: The Multi-Agent Playbook

SPINE implements patterns from the Multi-Agent Playbook—an architectural blueprint for production-ready multi-agent systems that addresses the core challenge: How do you manage delegation, state, execution, and failure without creating chaos?

The General Contractor Model

SPINE follows a closed-loop orchestrator pattern where:

User
  │
  ▼
┌─────────────────────────────────────────────┐
│              SPINE Orchestrator              │
│  AgenticLoop + ToolEnvelope instrumentation │
└──────────────────┬──────────────────────────┘
                   │ fan_out() or pipeline()
       ┌───────────┼───────────┐
       ▼           ▼           ▼
   ┌───────┐   ┌───────┐   ┌───────┐
   │Worker │   │Worker │   │Worker │
   │Agent 1│   │Agent 2│   │Agent 3│
   └───┬───┘   └───┬───┘   └───┬───┘
       │           │           │
       └───────────┼───────────┘
                   │ Results via ToolEnvelope
                   ▼
┌─────────────────────────────────────────────┐
│         Synthesized Response to User         │
└─────────────────────────────────────────────┘

• You prompt the Orchestrator, not sub-agents directly
• Sub-agents report exclusively to the Orchestrator
• The Orchestrator synthesizes and delivers results
• Direct user communication from sub-agents is forbidden

The Five Pillars

SPINE implements all five architectural pillars from the blueprint:

Pillar	Blueprint Principle	SPINE Implementation
I. Communication	Closed loops, verifiable artifacts	ToolEnvelope result wrapping, structured logs
II. Execution	Parallel for speed, sequential for logic	fan_out() and pipeline() patterns
III. Empowerment	Right tooling in isolated environments	MCP integration, TraceScope boundaries
IV. State	State in environment, not agent memory	NEXT.md integration, Context Stacks
V. Resilience	Blast radius containment, error routing	OscillationTracker, LoopVerdict system

Context Management: Signal vs. Noise

The Orchestrator holds executive signal (low context), while sub-agents absorb execution noise (high context):

Orchestrator Context (Signal)          Sub-Agent Context (Noise)
├── Master Plan                        ├── Full document content
├── Operational metrics                ├── Raw API responses
├── Synthesized outputs                ├── Detailed logs
└── Error signals                      └── Environment state

→ Read the full Blueprint Implementation Guide

→ View the Multi-Agent Playbook (PDF)

---

Architecture

SPINE operates across three distinct capability layers:

┌─────────────────────────────────────────────────────────────┐
│                    Layer 1: Claude Native                    │
│  Built-in Task tool with subagent_types                     │
│  (Explore, Plan, code-architect, visual-tester, etc.)       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Layer 2: MCP Servers                      │
│  External tools via Model Context Protocol                   │
│  (browser-mcp, next-conductor, research-agent-mcp)          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Layer 3: SPINE Python                      │
│  Custom orchestration framework                              │
│  (fan_out, pipeline, ToolEnvelope, AgenticLoop)             │
└─────────────────────────────────────────────────────────────┘

Context Stack Structure

SPINE uses a hierarchical context stack for consistent LLM interactions:

{
  "global": { "operator": "...", "brand": "..." },
  "character": { "speaker": "...", "audience": "..." },
  "command": { "task": "...", "success": "..." },
  "constraints": { "tone": "...", "format": "...", "do": [], "dont": [] },
  "context": { "background": "...", "references": [] },
  "input": { "user_request": "..." }
}

Module Structure (v0.3.21)

spine/
├── core/           # ToolEnvelope, TraceScope
├── client/         # InstrumentedLLMClient, provider configs
├── patterns/       # fan_out(), pipeline()
├── orchestrator/   # AgenticLoop, OscillationTracker, TaskQueue
│   ├── context_stack.py    # Context stack loader/builder
│   └── executors/          # Pluggable executors
│       ├── base.py         # Executor interface
│       ├── subagent.py     # SubagentExecutor + context stacks
│       ├── claude_code.py  # ClaudeCodeExecutor (CLI subprocess)
│       └── mcp_orchestrator.py  # MCPOrchestratorExecutor (NEW)
├── memory/         # kv_store, vector_store, scratchpad
├── review/         # AI-powered code review
├── integration/    # Token-optimized MCP execution
├── enforcement/    # Tiered enforcement gate
├── health/         # Component health monitoring
├── api/            # FastAPI REST API + /api/reviews
├── reports/        # Static HTML report generator
└── logging/        # Structured JSON logging

---

Tiered Enforcement Protocol

SPINE balances capability usage against overhead costs through a three-tier system:

Tier	Task Type	Enforcement	Examples
Tier 1	Simple	None required	Typo fixes, single-file edits
Tier 2	Medium	Recommended	Multi-file changes, new features
Tier 3	Complex	Mandatory	Architecture decisions, research, UI-heavy

Why Tiered Enforcement?

Factor	Consideration
Token Cost	Parallel subagents = 2-6x cost increase
Latency	Subagent spawn adds 10-30 seconds
Over-engineering	Simple tasks don’t need orchestration
Context Fragmentation	Subagents don’t share full conversation context

→ Try the Interactive Tier Classifier

---

Core Patterns

Fan-Out (Parallel Execution)

Execute multiple tasks simultaneously with automatic result aggregation:

                    ┌─────────────┐
                    │   Parent    │
                    │  Envelope   │
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
    ┌────────────┐  ┌────────────┐  ┌────────────┐
    │  Analyst A │  │  Analyst B │  │  Analyst C │
    └────────────┘  └────────────┘  └────────────┘
           │               │               │
           └───────────────┼───────────────┘
                           ▼
                    ┌─────────────┐
                    │  Aggregate  │
                    │   Results   │
                    └─────────────┘

Use Cases: Research tasks, parallel code analysis, multi-source data gathering

Pipeline (Sequential Processing)

Chain processing steps with automatic result transformation:

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│ Analyze │ ──▶ │ Extract │ ──▶ │Transform│ ──▶ │Synthesize│
└─────────┘     └─────────┘     └─────────┘     └─────────┘

Use Cases: Document processing, staged analysis, build pipelines

Agentic Loop (Autonomous Execution)

Run tasks until completion with built-in resilience:

┌──────────────────────────────────────────────────────────┐
│                     AgenticLoop                          │
├──────────────────────────────────────────────────────────┤
│  ┌─────────┐    ┌──────────┐    ┌───────────┐           │
│  │  Task   │───▶│ Execute  │───▶│ Evaluate  │           │
│  │  Queue  │    │          │    │           │           │
│  └─────────┘    └──────────┘    └─────┬─────┘           │
│                                       │                  │
│       ┌───────────────────────────────┼──────────┐      │
│       │                               │          │      │
│       ▼                               ▼          ▼      │
│   ┌────────┐                    ┌────────┐  ┌────────┐  │
│   │ ACCEPT │                    │ REVISE │  │ REJECT │  │
│   │  Done  │                    │ Retry  │  │  Skip  │  │
│   └────────┘                    └────────┘  └────────┘  │
│                                                          │
│  OscillationTracker: Detects stuck states               │
│  (A-B-A-B patterns, repeated errors)                    │
└──────────────────────────────────────────────────────────┘

ToolEnvelope (Instrumentation)

Every LLM call is wrapped for full traceability:

┌─────────────────────────────────────────┐
│              ToolEnvelope               │
├─────────────────────────────────────────┤
│  id: "call-abc123"                      │
│  tool: "anthropic:claude-sonnet-4-5"    │
│  trace:                                 │
│    root_id: "task-xyz"                  │
│    parent_id: "orchestrator-001"        │
│    span_id: "subagent-research"         │
│  metadata:                              │
│    tags: ["research", "phase-1"]        │
│    experiment_id: "exp-2025-001"        │
│  metrics:                               │
│    tokens_in, tokens_out, latency_ms    │
└─────────────────────────────────────────┘

---

Interactive Demos

View all demos →

Demo	Description
Tier Classifier	Determine the appropriate enforcement tier for any task
Provider Picker	Choose the right LLM provider based on your task type
Cost Calculator	Estimate API costs by model and token usage
Fan-Out Simulator	Visualize parallel task execution with configurable workers
Pipeline Builder	Build and simulate sequential processing chains

---

Use Cases

Autonomous Software Development

SPINE enables coordinated multi-agent workflows for:

• Code Review: Parallel reviewers for security, style, and logic with consensus ranking
• Research Tasks: Multi-source investigation with conflict detection and synthesis
• UI Development: Visual verification with browser automation
• Architecture Design: Structured design reviews with documentation generation

Project Integration

SPINE has been successfully integrated with:

Project	Integration Type
Golden Thread System	Full MVP development with tiered enforcement
spine-dashboard	Real-time monitoring via SPINE API
Adaptivearts.ai	Research and content generation workflows

---

Technical Highlights

Multi-Provider Support

Provider	Models	Status
Anthropic	Claude Opus 4.5, Sonnet 4.5, Haiku 4.5	✅ Active
OpenAI	GPT-5.1, GPT-5 mini	✅ Active
Google	Gemini 3 Pro, Gemini 3 Flash	✅ Active
xAI	Grok	✅ Active

Observability Stack

Component	Purpose
spine/logging/	Structured JSON logs with trace hierarchy
spine/api/	FastAPI REST API with OpenAPI docs
spine/reports/	Self-contained HTML reports with Chart.js
spine/health/	Component health monitoring

CLI Tools

# Run orchestrator with SubagentExecutor (uses .claude/agents/ personas)
python -m spine.orchestrator run --project /path --executor subagent

# Run orchestrator with ClaudeCodeExecutor (spawns CLI subprocess)
python -m spine.orchestrator run --project /path --executor claude-code --executor-budget 10.0

# Run with context stacks from scenario files
python -m spine.orchestrator run --project /path --executor subagent --scenario scenarios/research.yaml

# Run with LLM evaluation
python -m spine.orchestrator run --project /path --llm-eval

# Generate reports
python -m spine.reports generate --title "Sprint Report" --days 7

# Health checks
python -m spine.health --verbose

# Code review
python -m spine.review . --parallel

# Start API server
python -m spine.api --port 8000

---

Documentation

Document	Description
Blueprint Implementation	How SPINE implements the Multi-Agent Playbook
Architecture Overview	System design and components
Pattern Guide	Fan-out and Pipeline usage
Tiered Protocol	Full enforcement protocol
Executor Framework	SubagentExecutor, ClaudeCodeExecutor, MCPOrchestratorExecutor
Context Stack Integration	YAML scenario files for prompt building
MCP Orchestrator Integration	Optional intelligent tool routing
Minna Memory Integration	Persistent cross-session memory (NEW)
Claude Code Automation	Disable prompts, auto-reload context

Reference Materials

Resource	Description
Multi-Agent Playbook (PDF)	Architectural blueprint for production-ready multi-agent systems

---

Version History

Version	Highlights
0.3.22	Minna Memory Integration - persistent cross-session memory with graceful fallback
0.3.21	MCP Orchestrator Integration - optional intelligent tool routing with graceful fallback
0.3.20	Context Stack Integration - executors use scenarios/*.yaml for prompt building
0.3.19	Executor Framework - SubagentExecutor, ClaudeCodeExecutor with pluggable design
0.3.18	Dashboard integration - /api/reviews endpoints for review history
0.3.17	Inline diff annotations, cost tracking per review
0.3.16	NEXT.md integration for AgenticLoop
0.3.15	create_spine_llm_evaluator() factory
0.3.14	Static HTML report generator
0.3.13	FastAPI REST API surface
0.3.12	Health check system, common utilities
0.3.11	Tier enforcement gate (commit-msg hook)
0.3.10	Token-optimized MCP execution (57-87% savings)
0.3.9	ConflictResolver for multi-agent synthesis
0.3.6-8	AI-powered code review module

---

About

SPINE is developed as part of the AdaptiveArts.ai research initiative, focusing on intelligent software development workflows and multi-agent coordination.

The Meta-Goal

“The goal is not to build the application. It is to build the system that builds the application.”

SPINE embodies this philosophy—it’s a backbone framework that enables building applications through orchestrated multi-agent workflows.

Contact

• GitHub: github.com/fbratten
• Portfolio: View all projects

---

License

This project is licensed under the MIT License.

This site is open source. Improve this page.