Spectra

A Multi-LLM Spec-Driven Development System written in Dart

AI-driven development often leads to technical debt, inconsistent patterns, and "AI hallucinations" that break your build.

Spectra fixes that. It's the multi-agent context engineering layer that makes LLMs (Gemini, Claude, OpenAI, Grok, DeepSeek) reliable for real software engineering.

Use Spectra your way:

• 🤖 Automatic: AI plans AND implements code
• 👤 Manual: AI plans tasks, YOU implement (NEW in v0.1.5)
• 🤝 Interactive: AI suggests, you review
• 🎼 Symphony Mode (NEW in v0.2.0): drive long-running runs from a repo-owned WORKFLOW.md, use a tracker (Linear or local PLAN.md), get per-issue git worktrees, structured retries, and a run-first dashboard at /api/v1/state.

THIS is how you build systems that actually last.

Perfect for developers who want smart planning without losing control of their code.

---

Installation

dart pub global activate spectra_cli

Use it: spectra

---

Why I Built This

I'm an engineer who loves building, not babysitting LLMs.

Most AI tools treat code like a single-shot generation problem. They lack "living memory" of your project state and fail when projects grow beyond a few files. I didn't want a "chat with your code" tool; I wanted a Spec-Driven Execution Engine that respects my architecture, follows my conventions, and doesn't forget decisions made three days ago.

So I built Spectra. It's designed for small-to-medium projects (1–50 files) where precision matters more than volume.

• Context Engineering: Strict line limits and structured state tracking.
• XML Prompting: Optimized for LLM precision (especially Claude & Gemini).
• Multi-LLM Agnostic: Switch between Gemini-3.0, Claude-4.5, GPT-5, Grok-4.1, and DeepSeek-V3.2 with ease.
• Git Native: Every task is an atomic commit with clear rationale.

Spectra allows me to focus on high-level architecture while it handles the implementation and verification. It's the system I trust to get work done.

---

How It Works

1. Configuration (First-time setup)

spectra config

Spectra will prompt you for your API keys for Google Gemini, OpenAI, Anthropic Claude, xAI Grok, and DeepSeek. These are stored securely encrypted in ~/.spectra/.secure/ using machine-specific encryption.

NEW: You can now configure separate providers for:

• Planning Provider: Strategic tasks (plan, map, architecture analysis)
• Coding Provider: Tactical tasks (execute, worker agents, code generation)

Recommended: Claude for planning, Gemini Flash for coding. See LLM Usage Types for details.

2. New Projects (Greenfield)

spectra new

Interactive onboarding. Spectra asks about your project vision, tech stack, and constraints. It initializes the .spectra/ directory with your "Living Memory".

3. Existing Projects (Brownfield)

spectra map

Scans your existing repository to extract architecture, naming conventions, and tech stack into the .spectra/ context. Spectra learns your style before it writes a single line of code.

4. Plan & Orchestrate

spectra plan "Auth Implementation"
spectra start --workers 3

The Planner breaks your roadmap into 2–5 atomic tasks. While spectra execute runs tasks sequentially, spectra start launches a Multi-Agent Orchestrator inspired by Gastown.

• Mayor Agent: Coordinates task assignment.
• Worker Agents: Parallel executors that implement tasks.
• Witness Agent: Monitors health and detects stuck workers.

Monitor in real-time: While spectra start is running, you can use spectra progress in another terminal to see the live status of all active agents and their assigned tasks. For a visual experience, run spectra dashboard to launch a web-based monitoring UI.

5. Symphony Mode (v0.2.0)

When a repo-owned WORKFLOW.md is present (scaffolded by spectra new), spectra start runs the tracker-driven scheduler instead of the legacy convoy:

---
tracker:
  kind: local_plan        # default — or `linear` with an API key
agent:
  runner: llm
  max_concurrent_agents: 2
  max_turns: 10
---
You are working on {{ issue.identifier }}. Implement it end-to-end.

Each issue gets an isolated git worktree under .spectra/workspaces/, lifecycle hooks, exponential retries, a proof.md artifact per run, and a runtime snapshot at GET /api/v1/state (or spectra progress --runs). Use spectra start --legacy to force the classic PLAN.md flow. See Multi-Agent Orchestrator for the full picture.

---

Use Spectra Your Way

Spectra adapts to your workflow with flexible execution modes:

🤖 Automatic Mode (Default)

AI plans AND implements code automatically. Best for rapid prototyping.

spectra plan "Features" → spectra execute
# AI does everything

👤 Manual Mode (Planning Only)

AI plans, YOU code. Use Spectra as a planning tool only.

spectra plan "Features" → spectra execute --manual
# AI creates task breakdown
# You implement in your IDE

🤝 Interactive Mode

AI suggests code, you review every file before it touches disk. Best for production.

spectra execute
# Per file: [A] Apply as-is · [E] Edit in $EDITOR · [S] Skip · [Q] Quit
# Per task: [Y] Commit now · [N] Skip commit · [E] Edit message

Choose what works for you. See Execution Modes for details.

---

LLM Usage Optimization

Spectra intelligently separates LLM usage into Planning and Coding tasks for maximum efficiency:

Why Separate Planning from Coding?

Different tasks need different strengths:

• Strategic Planning → Strong reasoning, architectural thinking (Claude, GPT-5)
• Tactical Coding → Fast generation, syntax accuracy (Gemini Flash, DeepSeek)

Cost Optimization:

• Planning happens once per phase → Use powerful models ($0.50)
• Coding happens many times → Use fast models ($2.00 for 50 tasks)
• Result: $2.50 total vs $25 with expensive models everywhere (90% savings!)

Architecture Overview

┌─────────────────────────────┐  ┌─────────────────────────────┐
│   🎯 PLANNING (Strategic)   │  │   💻 CODING (Tactical)      │
├─────────────────────────────┤  ├─────────────────────────────┤
│                             │  │                             │
│  Commands:                  │  │  Commands:                  │
│  • spectra plan             │  │  • spectra execute          │
│  • spectra map              │  │  • spectra start (workers)  │
│                             │  │                             │
│  Agents:                    │  │  Agents:                    │
│  • Mayor (coordination)     │  │  • Workers (implementation) │
│  • Witness (monitoring)     │  │                             │
│                             │  │                             │
│  Recommended:               │  │  Recommended:               │
│  • Claude (reasoning)       │  │  • Gemini Flash (speed)     │
│  • GPT-5 (balanced)         │  │  • DeepSeek (code-focused)  │
│                             │  │                             │
│  Frequency: LOW             │  │  Frequency: HIGH            │
│  Cost/Use: HIGH             │  │  Cost/Use: LOW              │
└─────────────────────────────┘  └─────────────────────────────┘

Provider Comparison

For Planning (Strategic Tasks)

Provider	Reasoning	Speed	Cost	Recommendation
Claude	⭐⭐⭐⭐⭐	⭐⭐⭐	💰💰💰	Best
GPT-5	⭐⭐⭐⭐	⭐⭐⭐⭐	💰💰💰	Great
Gemini Pro	⭐⭐⭐	⭐⭐⭐⭐⭐	💰💰	Good

For Coding (Tactical Tasks)

Provider	Code Quality	Speed	Cost	Recommendation
Gemini Flash	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	💰	Best
DeepSeek	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	💰	Great
GPT-5 Mini	⭐⭐⭐⭐	⭐⭐⭐⭐	💰💰	Good

Recommended Configurations

Balanced (Most Projects)

Planning: Claude (best reasoning)
Coding: Gemini Flash (fastest, cheapest)
Mode: Automatic

Cost-Optimized

Planning: Gemini Flash
Coding: DeepSeek
Mode: Automatic
Savings: Up to 95%

Speed-First

Planning: Gemini Pro
Coding: Gemini Flash
Mode: Automatic
Speedup: 3-4x faster

Planning-Only (Manual)

Planning: Claude
Mode: Manual
Cost: Just planning (~$0.50 per phase)
You: Implement code yourself

Cost & Speed Examples

20-Task Project

Configuration	Planning	Coding	Total	Time
Claude Only	$0.50	$20.00	$20.50	64s
Claude + Gemini	$0.50	$1.50	$2.00	19s
Manual Mode	$0.50	$0.00	$0.50	You code

Savings with dual providers: 90% cost, 70% time!

Usage Examples

Example 1: Cost-Optimized Automation

$ spectra config
Planning Provider: Claude
Coding Provider: Gemini Flash
Mode: Automatic

$ spectra plan "E-commerce Platform"
✅ 50 tasks planned with Claude ($0.50)

$ spectra start --workers 5
✅ All 50 tasks completed with Gemini ($3.00)

Total: $3.50 (vs $25 with Claude only)
Savings: 86%

Example 2: Planning-Only Workflow

$ spectra config
Planning Provider: Claude
Mode: Manual

$ spectra plan "Full Stack App"
✅ AI creates 20 task breakdown

$ spectra execute --manual
📋 20 tasks displayed with details
# You implement in your IDE

Total: $0.50 for planning only

Example 3: Mixed Workflow

# AI handles boilerplate
$ spectra plan "Models & Config"
$ spectra execute  # AI generates

# You handle business logic
$ spectra plan "Payment Processing"
$ spectra execute --manual  # You implement

---

Why It Works: Context Engineering

Spectra maintains a "Living Memory" in the .spectra/ directory. Every file has strict line limits to prevent LLM context degradation.

File	Purpose
PROJECT.md	Core vision, tech stack, and constraints (Immutable)
ROADMAP.md	High-level phases and milestones
STATE.md	Current technical decisions & blockers (Auto-pruned)
PLAN.md	Atomic tasks in XML format
SUMMARY.md	Results of the last execution
ISSUES.md	Deferred enhancements and technical debt

When STATE.md grows too large, Spectra automatically archives older decisions to history/, keeping the most relevant context at the forefront.

---

Commands

Command	Description
new	Interactive onboarding to start a new project
map	Analyze existing repository architecture (Brownfield)
plan	Break a roadmap phase into atomic XML tasks
execute	Parse plans, apply changes, and commit to Git (skips completed tasks; --manual/--auto override the mode)
start	Launch the orchestrator — Symphony scheduler when WORKFLOW.md exists (--workflow <path>), legacy convoy with --legacy
dashboard	Launch web UI for real-time agent monitoring (--port, default 3000)
progress	CLI dashboard of completed vs. upcoming phases; --runs prints the runtime snapshot
resume	Count completed vs. remaining tasks in PLAN.md and continue with the first uncompleted one
config	Set up API keys for Gemini, Claude, OpenAI, Grok, and DeepSeek

---

Who This Is For

Creative engineers who want to build complex systems without being bogged down by manual implementation details.

If you want to define the what and have a system you trust handle the how—while maintaining full architectural control—Spectra is for you.

---

Learn More

Want deeper insights? Check out our comprehensive guides:

Core Features:

• Getting Started - Install and initialize your first project
• Core Concepts - The Living Memory and spec-driven flow
• Execution Modes - Automatic, Manual, Interactive workflows
• LLM Usage Types - Provider optimization strategies
• Security Features - Encryption implementation details

Technical Deep Dives:

• Multi-Agent Orchestrator - Legacy convoy and the Symphony scheduler
• Orchestration Overview - How the two orchestration paths fit together
• Context Engineering - STATE.md pruning and focused prompts
• Architecture - LLM separation design
• Testing Guide - Running and writing tests
• Migration Guide - Upgrading from v0.1.4
• Symphony Adaptation Plan - The design behind v0.2.0

---

Security Features

Spectra takes security seriously, especially when handling sensitive API keys:

• Encrypted Storage: All API keys are encrypted with an XOR stream cipher whose keystream is SHA-256-derived (counter mode), with a random IV per write
• No Plain Text: API keys are never stored in plain YAML or configuration files
• Automatic Migration: Legacy plain-text configs — and files encrypted by pre-0.2.1 versions — are automatically migrated on first use
• Secure Key Derivation: Encryption keys are derived from system-specific information using PBKDF2 with 10,000 iterations
• Local-Only Storage: All credentials remain on your machine in ~/.spectra/.secure/, which Spectra restricts to 700/600 permissions on POSIX systems

See Security Features for the full details and limitations.

---

Roadmap / TODO

Future enhancements planned for Spectra:

• x Expand Test Coverage — Integration tests for commands and end-to-end workflows ✓
• x Security Hardening — Encrypted storage for API keys with automatic migration ✓
• Metrics & Telemetry — Track agent performance, task completion times, and LLM costs over time
• Plugin System — Allow custom LLM providers and agent types via plugins
• x Web Dashboard — Real-time browser UI for monitoring agents, built with Jaspr
• Task Dependencies — Support for task ordering and prerequisite chains in PLAN.md
• Rollback Support — Automatic Git rollback when a task fails verification

Contributions welcome! Feel free to open issues or pull requests on GitHub.

---

License

MIT License. See LICENSE for details.

---

Spectra: Precision-guided software engineering.