| name | spectra |
| version | 1.0.0 |
| author | Guido Miranda (GuiMiran) |
| repository | https://github.com/GuiMiran/spectra |
| category | agentic-specification |
| compatible_with | ["claude","chatgpt","gpt-4o","codex","gemini"] |
| tags | ["spec-driven-development","sdd","agentic-ai","domain-specs","ai-agents","invariants","spectra-trace","reconstructable","qa-engineering"] |
| description | Spectra is the agentic specification framework. Domain-first specs that AI can consume directly. It is the knowledge infrastructure an agent needs to operate alone in a complex domain — before any code is written. S·P·E·C·T·R·A: Source · Product · Exhaustive · Contractual · Truth · Reconstructable · Agentic
|
SPECTRA Skill
The specification framework designed to be consumed by AI, not humans.
Spectra is NOT documentation. NOT a README. NOT code comments.
Spectra is the domain source of truth: business rules, invariants, contracts,
regulations, decisions — structured in 13 layers so an agent can operate autonomously.
You define the domain → Spectra structures the specs → AI builds, maintains and evolves the system
Spectra goes BEFORE everything else:
Spectra (domain) → OpenSpec / GitHub Spec Kit (construction) → Code
The 7 principles — if something violates one, it is not Spectra
| Letter | Principle | Meaning |
|---|
| S | Source | Specs are the source. Code is the derivative. Lose the code, lose nothing essential. Lose the specs, lose everything. |
| P | Product | Business domain, not technical architecture. No table names, endpoints or React components in specs. |
| E | Exhaustive | Every rule, every edge case, every exception. An incomplete spec is worse than no spec. |
| C | Contractual | Preconditions, postconditions, boolean invariants. Not narratives — contracts. |
| T | Truth | One single source of truth. No contradictions. Unique IDs make everything traceable. |
| R | Reconstructable | The complete system must be reconstructable from specs alone, agent in empty context. |
| A | Agentic | Designed to be consumed by AI, not humans. Nothing implicit. Everything explicit. |
The reconstructability test: give specs to an agent in empty context, no existing code,
no conversation history. Can it rebuild the system identically? If yes — specs are complete.
When to activate this skill
Activate Spectra when the user:
- Starts a new project, feature, module, or API
- Says "generate specs", "write specs", "define the behaviour of X"
- Wants to work in SDD (Spec-Driven Development) mode
- Asks an agent to build something non-trivial
- Needs to document business rules, invariants, or regulations
- Wants to ensure an AI agent can work autonomously without constant correction
- Asks to review, evolve, or update existing specs
- Mentions SPECTRA-TRACE, gap detection, or traceability
The 13 layers of a Spectra specification
Static layers — define the domain
──────────────────────────────────────────────────────────────
00 · Vision & Context ← what it is, who it's for, scope
01 · Domain Glossary ← canonical language, one definition per term
02 · User Stories ← AS A / I WANT / SO THAT
03 · Business Rules ← every rule with regulatory source
04 · Invariants ← always-true boolean conditions
05 · Operation Contracts ← pre/postconditions per operation
06 · Decision Policies ← IF/THEN decision trees and tables
07 · Domain Events ← facts that occur and their consequences
08 · Agents ← autonomous AI actors in the domain
09 · Skills ← atomic invocable capabilities
10 · Workflows ← agent and skill orchestration
11 · Acceptance Criteria ← GIVEN/WHEN/THEN in natural language
──────────────────────────────────────────────────────────────
Live layer — updated by the agent every iteration
──────────────────────────────────────────────────────────────
12 · SPECTRA-TRACE ← bidirectional traceability matrix
Layer 00 — Vision & Context
Product purpose, problem solved, target users, functional scope (what IS and what is NOT
included), applicable regulatory framework summary.
Layer 01 — Domain Glossary
Dictionary of all business terms. Each entry: Name · Unambiguous definition · Example ·
Synonyms to avoid. This glossary IS the canonical language — all layers use these exact terms.
Layer 02 — User Stories
Format: US-XXX: AS A [role] I WANT [action] SO THAT [benefit]
Each story: unique ID · Priority (Must/Should/Could) · Acceptance criteria GIVEN/WHEN/THEN.
Include main flows AND alternative/error flows.
Layer 03 — Business Rules
Format: BR-XXX: [Rule description]
Each rule: ID · Description · Normative source (law, article, regulation) · Examples · Exceptions.
Include ALL rules derived from applicable regulations — even "obvious" ones.
Layer 04 — Invariants
Conditions that MUST ALWAYS be true at any system state.
Format: INV-XXX: [boolean condition in natural language]
Example: INV-001: Invoice total ALWAYS equals sum of lines + taxes - withholdings
If an invariant is violated → the system is in a corrupt state.
Layer 05 — Operation Contracts
OPERATION: [name]
PRE: [what must be true before executing]
POST: [what must be true after executing]
ERROR: [what happens if it fails]
Layer 06 — Decision Policies
Format: POL-XXX: IF [condition] THEN [action] ELSE [alternative]
Decision tables for complex logic. Complete decision trees for fiscal and business flows.
Layer 07 — Domain Events
Format: EVT-XXX: [EventName] → TRIGGERS: [list of reactions]
Example: EVT-012: InvoiceIssued → record VAT ledger + update client balance + generate PDF
Layer 08 — Agents
Autonomous AI actors operating on the domain.
Each agent: Name · Responsibility · Skills it uses (SK-XXX) ·
Events it listens to (EVT-XXX) · Events it produces · Invariants it must respect (INV-XXX).
Layer 09 — Skills
Atomic, invocable capabilities. The lego pieces that agents combine.
Each skill: Name · Description · Input · Output ·
Business Rules applied (BR-XXX refs) · Invariants verified (INV-XXX refs).
Layer 10 — Workflows
Orchestrations of agents and skills.
Each workflow: Name · Trigger · Ordered steps · Agents · Skills per step ·
Expected result · Error handling.
Layer 11 — Acceptance Criteria
GIVEN/WHEN/THEN format. Linked to: US-XXX · BR-XXX · INV-XXX.
Cover: happy path · expected errors · edge cases · regulatory combinations.
Layer 12 — SPECTRA-TRACE (KEY INNOVATION)
The bidirectional traceability matrix. The living layer. Updated by the agent every iteration.
Forward direction (Spec → Code) — detects FUNCTIONAL GAPS:
specs that exist but have no corresponding code implementation.
Reverse direction (Code → Spec) — detects TECHNICAL GAPS:
code that exists but has no business rule justifying it (orphaned code).
SPECTRA-TRACE FORMAT:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ITERATION: [n] | DATE: [date] | AGENT: [agent name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FORWARD MATRIX (Spec → Code)
[US-001] → [module/component] : COVERED ✓ | PARTIAL ⚠ | MISSING ✗
[BR-003] → [function/service] : COVERED ✓ | PARTIAL ⚠ | MISSING ✗
[INV-002] → [validation] : COVERED ✓ | PARTIAL ⚠ | MISSING ✗
REVERSE MATRIX (Code → Spec)
[module/function] → [BR-XXX or US-XXX] : TRACED ✓ | ORPHAN ✗
FUNCTIONAL GAPS (forward MISSING): [count]
TECHNICAL GAPS (reverse ORPHAN): [count]
COVERAGE SCORE: [0-100%]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Unique ID system — the nervous system of Spectra
| Layer | ID Format | Example |
|---|
| User Stories | US-XXX | US-042 |
| Business Rules | BR-XXX | BR-015 |
| Invariants | INV-XXX | INV-003 |
| Operation Contracts | OP-XXX | OP-008 |
| Decision Policies | POL-XXX | POL-021 |
| Domain Events | EVT-XXX | EVT-007 |
| Agents | AG-XXX | AG-002 |
| Skills | SK-XXX | SK-011 |
| Workflows | WF-XXX | WF-004 |
| Acceptance Criteria | AC-XXX | AC-088 |
Cross-reference rule: every element that depends on another MUST cite its ID.
Example: SK-007 applies: BR-015, BR-016 / verifies: INV-003, INV-004
How to generate a complete Spectra specification
Step 1 — Collect the 6 information blocks from the user
BLOCK 1 — Project context
Project name · product type · sector/industry
country/jurisdiction · applicable regulations · business model
BLOCK 2 — Product description
What does it do? (problem + solution in natural language)
Who are the users? (roles list)
What are the main modules?
BLOCK 3 — Known rules and constraints
Business rules already known
Regulatory constraints (laws, compliance)
Required external integrations
BLOCK 4 — What to generate
All 13 layers (always all of them)
BLOCK 5 — Format instructions
Language · detail level (always: exhaustive)
unique ID format · cross-reference requirements
BLOCK 6 — Optional context
Competitors/references · differentiation · scope constraints
Step 2 — Generate layer by layer in order
Generate: 00 → 01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09 → 10 → 11
Layer 12 (SPECTRA-TRACE) initializes empty, populated by agent during iteration.
Critical constraint: do NOT generate code or technical architecture.
No table names, endpoints, frameworks, or design patterns in specs.
Step 3 — Self-validate before output
Step 4 — Generate SPEC-INDEX.md
Navigable master index: cross-reference map · naming conventions ·
instructions for any AI agent on how to consume these specs.
Autonomous agent operation protocol
Before building anything
- Read Layer 00 — understand scope
- Read Layer 01 — adopt the canonical vocabulary
- Read Layer 04 — internalize all invariants as hard constraints
- Read Layer 03 — understand all business rules
During each iteration
- Identify the US-XXX story being implemented
- Find all BR-XXX rules linked to that story
- Find all INV-XXX invariants that apply
- Find SK-XXX skills and AG-XXX agents involved
- Check POL-XXX decision policies for conditional logic
- Verify AC-XXX acceptance criteria before completing
After each iteration — mandatory SPECTRA-TRACE update
- Update Layer 12 with all changes (forward + reverse matrix)
- Recalculate gap counts and coverage score
- Flag any MISSING or ORPHAN items for human review
- If coverage < 80% → alert before proceeding
Self-maintenance protocol (for evolving systems)
When the agent detects a requirement change:
- Identify which spec elements are affected (via ID cross-references)
- Update the relevant layers before touching any code
- Update SPECTRA-TRACE to reflect all changes
- Flag all downstream elements that depend on the changed spec
- Propose spec version increment (v1.0 → v1.1 → v2.0)
- Rule: specs are ALWAYS updated before code. Never the reverse.
What Spectra is NOT
- NOT a code linter — it does not analyze code quality
- NOT a code generator — it gives agents the context to generate correct code
- NOT technical documentation — architecture and infrastructure go elsewhere
- NOT BDD/TDD — acceptance criteria are business behaviour, not software tests
- NOT a development process — works with Agile, Shape Up, waterfall, or anything else
Comparison with other frameworks
| Traditional docs | BDD/Cucumber | OpenSpec | Spectra |
|---|
| Audience | Humans | Developers | Coding agents | Domain agents |
| Describes | How it works | Behaviour tests | How code evolves | What the system IS |
| Regulations | Rarely | ❌ | ❌ | ✅ Required |
| Boolean invariants | ❌ | ❌ | ❌ | ✅ |
| Full reconstruction | ❌ | ❌ | ❌ | ✅ |
| Bidirectional trace | ❌ | ❌ | ❌ | ✅ SPECTRA-TRACE |
| Layer position | After code | After code | After code | Before code |
| Gap detection | ❌ | ❌ | ❌ | ✅ Bidirectional |
Quick reference — phrases that trigger Spectra
| User says | Action |
|---|
| "generate specs for X" | Full 13-layer generation |
| "write the spec for this feature" | L02 + L03 + L04 + L11 |
| "what invariants apply here" | Query Layer 04 |
| "define business rules for X" | Generate Layer 03 section |
| "update the trace" | Update Layer 12 SPECTRA-TRACE |
| "detect gaps" | Forward + reverse trace analysis |
| "is the system reconstructable" | Reconstructability check across all 13 layers |
| "what does [term] mean" | Query Layer 01 Glossary |
| "the regulation changed" | Update BR-XXX → flag dependents → update TRACE |
Core rules for any AI agent using this skill
- Specs before code. Always. No code without specs existing first.
- The glossary is law. Every term must be in Layer 01. No informal synonyms.
- Invariants are inviolable. An INV-XXX violation means stop and flag immediately.
- SPECTRA-TRACE is accountability. Update it every iteration without exception.
- When in doubt — specify, don't assume. Over-specifying costs zero. Under-specifying produces bugs.
- Reconstructability is the test. A spec is complete when another agent with zero context can rebuild the system from it.
Resources
Spectra was built with AI, describes how to build with AI, and is the manual AI uses
to maintain itself. That recursion is not accidental — it's the point.
SPECTRA — Source · Product · Exhaustive · Contractual · Truth · Reconstructable · Agentic
Created by Guido Miranda Mercado · CC BY-NC-ND 4.0 · https://github.com/GuiMiran/spectra
