Spectra

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

Spectra UI

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

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.

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 and approve. Best for production.

spectra execute  # Review each file before applying

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

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 (Sequential)
start Launch the Multi-Agent Orchestrator (Parallel execution)
dashboard Launch web UI for real-time agent monitoring
progress CLI dashboard of completed vs. upcoming phases
resume Detect interrupted states and pick up where you left off
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:

Technical Deep Dives:

Security Features

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

  • Encrypted Storage: All API keys are encrypted using machine-specific encryption before being stored
  • No Plain Text: API keys are never stored in plain YAML or configuration files
  • Automatic Migration: Legacy plain-text configs are automatically migrated to encrypted storage 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/

Your API keys are as secure as your machine's filesystem permissions.

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.

Libraries

agents/base_agent
agents/mayor_agent
agents/witness_agent
agents/worker_agent
commands/base_command
commands/config_command
commands/dashboard_command
commands/execute_command
commands/map_command
commands/new_command
commands/plan_command
commands/progress_command
commands/resume_command
commands/start_command
core/cached_llm_provider
core/claude_provider
core/deepseek_provider
core/gemini_provider
core/grok_provider
core/llm_provider
core/openai_provider
dashboard/components/agent_card
dashboard/components/progress_card
dashboard/dashboard_page
models/agent
models/convoy
models/execution_mode
models/llm_usage_type
models/spectra_config
models/task
services/codebase_context_service
services/config_service
services/dashboard_service
services/llm_cache
services/llm_service
services/orchestrator_service
services/secure_storage_service
utils/http_utils
utils/state_manager