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

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 (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:

Execution Modes - Automatic, Manual, Interactive workflows
LLM Usage Types - Provider optimization strategies
Security Features - Encryption implementation details

Technical Deep Dives:

Architecture - LLM separation design
Testing Guide - Running and writing tests
Migration Guide - Upgrading from v0.1.4

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:

✅ Expand Test Coverage — Integration tests for commands and end-to-end workflows ✓
✅ 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
✅ 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.

spectra_cli 0.1.5
spectra_cli: ^0.1.5 copied to clipboard

Metadata

Spectra #

Installation #

Why I Built This #

How It Works #

1. Configuration (First-time setup) #

2. New Projects (Greenfield) #

3. Existing Projects (Brownfield) #

4. Plan & Orchestrate #

Use Spectra Your Way #

🤖 Automatic Mode (Default) #

👤 Manual Mode (Planning Only) #

🤝 Interactive Mode #

LLM Usage Optimization #

Why Separate Planning from Coding? #

Architecture Overview #

Provider Comparison #

Recommended Configurations #

Cost & Speed Examples #

Usage Examples #

Why It Works: Context Engineering #

Commands #

Who This Is For #

Learn More #

Security Features #

Roadmap / TODO #

License #

← Metadata

Publisher

Weekly Downloads

Metadata

Documentation

License

Dependencies

More

spectra_cli 0.1.5 spectra_cli: ^0.1.5 copied to clipboard

Metadata

Spectra #

Installation #

Why I Built This #

How It Works #

1. Configuration (First-time setup) #

2. New Projects (Greenfield) #

3. Existing Projects (Brownfield) #

4. Plan & Orchestrate #

Use Spectra Your Way #

🤖 Automatic Mode (Default) #

👤 Manual Mode (Planning Only) #

🤝 Interactive Mode #

LLM Usage Optimization #

Why Separate Planning from Coding? #

Architecture Overview #

Provider Comparison #

Recommended Configurations #

Cost & Speed Examples #

Usage Examples #

Why It Works: Context Engineering #

Commands #

Who This Is For #

Learn More #

Security Features #

Roadmap / TODO #

License #

← Metadata

Publisher

Weekly Downloads

Metadata

Documentation

License

Dependencies

More

spectra_cli 0.1.5
spectra_cli: ^0.1.5 copied to clipboard