📖 Browse the full documentation at automatetheplanet.github.io/Spectra
AI-native test case generation and execution framework.
From documentation to deterministic test execution.
The name evokes the visible spectrum — SPECTRA covers the full spectrum of test activities, from documentation analysis through generation, verification, execution, coverage, and reporting. Nothing in the workflow is left dark.
It also reads as a backronym:
Spec-driven · Protocol for · Executable · Coverage, · Testing, · Reasoning · and · Automation
In practice it's a single product with two halves that can be used independently:
- An AI test-generation CLI that turns product documentation into versioned Markdown test cases.
- A deterministic execution engine (
spectra run) that drives those tests through a state machine any assistant or terminal can step through.
SPECTRA reads your product documentation, generates comprehensive test suites, keeps them current as the docs change, and executes them through a deterministic protocol. It doesn't replace your existing tools — it adds an AI layer.
-
Reads your documentation — Point SPECTRA at your product docs and it generates comprehensive test suites automatically.
-
AI with guardrails — Dual-model grounding verification catches hallucinated test steps before they reach your suite.
-
Test cases as Markdown — Test cases are plain Markdown files with YAML frontmatter. They live in GitHub, versioned alongside your code.
-
Deterministic execution —
spectra runprovides a state machine that an assistant (or you, in a terminal) drives without holding state. -
Coverage visibility — Three-dimensional coverage analysis: documentation, acceptance criteria, and automation. Visual dashboard included.
-
No migration needed — Integrates with Azure DevOps, Jira, Teams, Slack through their MCP servers. No data sync. No vendor lock-in.
Generate test cases from product documentation by asking Claude Code — the bundled spectra-generate skill runs the
flow in your session: it analyzes your docs, identifies testable behaviors, shows what existing tests already cover,
generates structured test cases batch by batch, and lets you describe undocumented behaviors. SPECTRA itself makes no
model call: every step is a deterministic spectra ai compile-* / ingest-* command, and the model work happens in
your own Claude Code session.
Behavior analysis applies six ISTQB test design techniques systematically (Equivalence Partitioning, Boundary Value Analysis, Decision Table, State Transition, Error Guessing, Use Case) so the produced suites have meaningful boundary and negative coverage instead of happy-path-only scenarios. Analysis output exposes both a category breakdown and a per-technique breakdown.
"Generate test cases for checkout" "Generate 15 test cases for checkout focusing on error handling" "Add a test case for a session timeout after 30 minutes"
Every generated or edited test is verified by the spectra-critic subagent (on its own model, ai.critic.model)
against the source documentation. Hallucinated steps are caught and rejected; partial tests get one repair. The
critic reads only the doc sections each test cites, so verification stays cheap on large documentation sets.
Flagged tests go to a human reviewer (spectra ai review-flagged, or the spectra-review-flagged skill): accepting,
giving feedback or deleting records who reviewed the test, when, and why in its grounding: block, next to the
critic's verdict. Feedback can also challenge a test the critic passed and send it back for repair.
When documentation changes, SPECTRA tells you which tests are affected and why — without a model: spectra ai update-triage compares each test's referenced doc sections and criteria with their recorded baseline and groups the
tests by what changed. The spectra-update skill then relinks renamed docs, edits the affected tests group by group,
re-verifies them with the critic, and acknowledges the rest. See
When documentation changes for the whole flow with a worked example.
Three coverage dimensions tracked automatically:
- Documentation — which docs have linked tests
- Acceptance Criteria — which criteria are tested
- Automation — which tests have automation code
spectra ai analyze --coverage --auto-linkStatic HTML dashboard with suite browser, test viewer, run history, and coverage visualizations. Deploy to Cloudflare Pages with GitHub OAuth authentication.
spectra dashboard --output ./siteExecute tests from the CLI with spectra run — nothing to configure or host.
Deterministic state machine with pause/resume, durable SQLite state with crash recovery, and three
report formats (JSON, Markdown, HTML). Run state survives process exits (each short-lived command
reconstructs the queue from a durable snapshot), so the agent loop is just commands between turns.
Bundled skills (.claude/skills/) and subagents (.claude/agents/) let you use SPECTRA through natural language in
Claude Code. Say "generate test cases for checkout" and the skill runs the CLI commands, reads their JSON, and presents
the results; the heavy reading happens in subagents, so your conversation stays small.
spectra init # Creates the config, folders, 16 skills and 6 subagents
spectra update-skills # Update skills and agents when the CLI is upgraded (edited files are kept)spectra init --agent <list> also installs the skills, the six subagents and an always-on instructions file for other
AI coding agents. Without --agent, spectra init installs for Claude Code exactly as before.
spectra init --agent copilot # one agent
spectra init --agent claude,copilot,codex # several (a skills folder they share is written once)
spectra init --agent auto # the agents already installed, or the one detected in the repo
spectra init --agent cursor --dry-run # list every file it would write; write nothingAgent (--agent) |
Instructions | Skills | Subagents |
|---|---|---|---|
claude |
— | .claude/skills/ |
.claude/agents/ |
copilot |
.github/instructions/spectra.instructions.md |
.github/skills/ (or reuses .claude/skills/) |
.github/agents/ (or reuses .claude/agents/) |
cursor |
.cursor/rules/spectra.mdc |
.cursor/skills/ (or reuses .claude/skills/, .agents/skills/) |
.cursor/agents/ |
devin (windsurf) |
.devin/rules/spectra.md |
.devin/skills/ |
.devin/agents/ |
codex |
a SPECTRA block in AGENTS.md |
.agents/skills/ |
.codex/agents/*.toml |
gemini (enterprise) |
a SPECTRA block in GEMINI.md |
.agents/skills/ |
.gemini/agents/ |
antigravity (agy) |
.agents/rules/spectra.md |
.agents/skills/ |
.agents/agents/ |
kiro |
.kiro/steering/spectra.md |
.kiro/skills/ |
.kiro/agents/ |
opencode |
a SPECTRA block in AGENTS.md |
.opencode/skills/ (or reuses .claude/skills/, .agents/skills/) |
.opencode/agents/ |
The names, aliases and detection match BELLATRIX Agent, so both tools can be installed in the same repository. Your
AGENTS.md / GEMINI.md keep their content; SPECTRA adds one marked block. A file you edit is never overwritten on a
re-run unless you pass --regenerate.
Known limitation: the critic's isolated, mandatory verification is enforced by the platform only in Claude Code. In the other agents the critic runs when the agent follows the skill's instruction to start it. A critic gate enforced by the CLI is planned for a later version.
See AI Agents for the full guide: choosing agents, what is installed where, re-runs and upgrades, coexistence with BELLATRIX Agent, removing an agent and troubleshooting.
Customize AI output with natural language profiles — detail level, negative scenario count, domain rules, formatting preferences.
Prerequisites: .NET 8.0+
# Install
dotnet tool install -g Spectra.CLI
# Initialize (creates config, folders, skills and subagents)
spectra init
# Build the document index
spectra docs index
# Validate test files
spectra validate
# Analyze coverage
spectra ai analyze --coverage
# Generate a visual dashboard
spectra dashboard --output ./siteThen open Claude Code in the project and ask:
"Extract acceptance criteria from my documentation" "Generate test cases for checkout"
Generation, criteria extraction, updates and verification need a model, so they run in your Claude Code session (the skills drive the CLI). Everything else is a plain command.
For CI — the deterministic commands support --output-format json and --no-interaction:
spectra validate --output-format json --no-interaction
spectra ai update-triage --all-suites --dry-run --output-format json
spectra ai audit-grounding --suite checkout --output-format json
spectra ai analyze --coverage --output-format json
spectra dashboard --output ./siteSee Getting Started for detailed instructions.
After spectra init, the bundled spectra-quickstart skill is a guided onboarding entry point. Open Claude Code in the project and ask:
"Help me get started"
The assistant walks you through every workflow (test generation, criteria extraction, coverage, dashboard, execution, customization) with copyable example prompts. For an offline reference covering the same workflows, see the auto-generated USAGE.md at your project root.
docs/ <- Source documentation
|
docs/_index/ <- Document index (manifest + per-suite files, incremental)
|
spectra CLI <- Deterministic: compiles prompts, validates and persists results
| (no model call; the model work runs in your Claude Code session)
Claude Code skills/subagents <- spectra-generate, spectra-criteria, spectra-update, spectra-critic, ...
|
test-cases/ <- Markdown test cases + _index.json + _source-baseline.json
|
spectra run <- Deterministic execution state machine (.execution/spectra.db)
| (as needed)
Azure DevOps / Jira / Teams <- Bug logging and notifications through their own integrations
| Subsystem | Purpose | Independent? |
|---|---|---|
Authoring (spectra ai … + skills) |
Generate, update, verify and analyze test cases from documentation | Yes |
Execution (spectra run) |
Execute tests through a deterministic, resumable state machine | Yes |
SPECTRA is part of the Automate The Planet ecosystem:
| Tool | Purpose |
|---|---|
| BELLATRIX | Test automation framework |
| Testimize | Test case optimization (hybrid ABC algorithm) |
| SPECTRA | AI test generation and execution protocol |
BELLATRIX automates test execution. Testimize optimizes test case selection. SPECTRA generates and maintains the test cases themselves — closing the loop between documentation and quality assurance.
Optional Testimize integration: SPECTRA ships with the Testimize library bundled as an in-process NuGet dependency (no separate installation needed). When enabled, it replaces AI-approximated boundary values with mathematically precise ones — exact min-1/min/max/max+1 BVA, security-focused invalid patterns (XSS, SQLi), and optimized multi-field pairwise/ABC combinations. Disabled by default; set
testimize.enabledtotrueinspectra.config.json. See Testimize Integration.
| Guide | Description |
|---|---|
| Getting Started | Install, prerequisites, first run |
| CLI Reference | All commands, flags, and options |
| Configuration | Full spectra.config.json reference |
| Test Format | Markdown format, YAML frontmatter, metadata schema |
| Coverage Analysis | Documentation, Requirements, and Automation coverage |
| Generation Profiles | Customize AI output style and quality |
| Grounding Verification | Dual-model critic for hallucination detection |
| Document Index | Pre-built doc index for efficient generation |
| Skills Integration | Claude Code skills and subagents |
| AI Agents | spectra init --agent: SPECTRA in Copilot, Cursor, Devin, Codex, Gemini, Antigravity, Kiro, OpenCode |
| Usage (Claude Code) | Workflow-by-workflow guide for driving SPECTRA from Claude Code |
| When documentation changes | Bringing tests up to date after a doc change, end to end |
| Customization | Every customization knob — config, profiles, prompts, palettes |
| Testimize Integration | Optional algorithmic test data optimization (BVA / EP / pairwise / ABC) |
| Execution Agents | Driving test execution with spectra run |
| Architecture | System design and key decisions |
| Development Guide | Building, testing, and running locally |
SPECTRA is in active development.
- Phase 1: AI Test Generation CLI ✓
- Phase 2: Execution Engine ✓
- Phase 3: Dashboard & Coverage Analysis ✓
- Phase 4: Test Generation Profiles ✓
- Phase 5: Grounding Verification ✓
- Phase 6: Integrations and Ecosystem ← current
Contributions are welcome! See CONTRIBUTING.md for build instructions, code style guidelines, and the PR process.
Licensed under the Apache License, Version 2.0. See LICENSE for the full text.
Copyright 2024-2026 Automate The Planet Ltd.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
