spectra-sdd 0.4.0__tar.gz

spectra_sdd-0.4.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.1
+Name: spectra-sdd
+Version: 0.4.0
+Summary: Spec-Driven Development for the Agentic Era
+Author: GuiMiran
+License: CC-BY-NC-ND-4.0
+Project-URL: Homepage, https://github.com/GuiMiran/spectra
+Project-URL: Repository, https://github.com/GuiMiran/spectra
+Project-URL: Issues, https://github.com/GuiMiran/spectra/issues
+Keywords: spec-driven-development,sdd,ai-agents,specifications,agentic-ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Spectra — Python
+
+Spec-Driven Development for the Agentic Era.
+
+```
+pip install guimiran-spectra
+```
+
+## Commands
+
+```
+spectra init        Scaffold .spectra/ with 13 layers
+spectra status      Show which layers are filled vs pending
+spectra trace       Scan specs + code → generate 12-trace.md
+spectra validate    Validate spec quality and cross-refs
+spectra --version   Show installed version
+```
+
+## Docs
+
+https://github.com/GuiMiran/spectra

spectra_sdd-0.4.0/README.md

@@ -0,0 +1,21 @@
+# Spectra — Python
+
+Spec-Driven Development for the Agentic Era.
+
+```
+pip install guimiran-spectra
+```
+
+## Commands
+
+```
+spectra init        Scaffold .spectra/ with 13 layers
+spectra status      Show which layers are filled vs pending
+spectra trace       Scan specs + code → generate 12-trace.md
+spectra validate    Validate spec quality and cross-refs
+spectra --version   Show installed version
+```
+
+## Docs
+
+https://github.com/GuiMiran/spectra

spectra_sdd-0.4.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spectra-sdd"
+version = "0.4.0"
+description = "Spec-Driven Development for the Agentic Era"
+keywords = ["spec-driven-development", "sdd", "ai-agents", "specifications", "agentic-ai"]
+license = { text = "CC-BY-NC-ND-4.0" }
+authors = [{ name = "GuiMiran" }]
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/GuiMiran/spectra"
+Repository = "https://github.com/GuiMiran/spectra"
+Issues = "https://github.com/GuiMiran/spectra/issues"
+
+[project.scripts]
+spectra = "spectra.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["spectra*"]
+
+[tool.setuptools.package-data]
+spectra = ["data/**/*", "data/*"]

spectra_sdd-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spectra_sdd-0.4.0/spectra/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

spectra_sdd-0.4.0/spectra/__main__.py

@@ -0,0 +1,3 @@
+from spectra.cli import main
+
+main()

spectra_sdd-0.4.0/spectra/cli.py

@@ -0,0 +1,35 @@
+import sys
+from spectra import __version__
+from spectra.colors import p
+
+
+def main() -> None:
+    command = sys.argv[1] if len(sys.argv) > 1 else None
+
+    if command == 'init':
+        from spectra.commands.init import cmd_init
+        cmd_init()
+
+    elif command == 'status':
+        from spectra.commands.status import cmd_status
+        cmd_status()
+
+    elif command == 'trace':
+        from spectra.commands.trace import cmd_trace
+        cmd_trace()
+
+    elif command == 'validate':
+        from spectra.commands.validate import cmd_validate
+        cmd_validate()
+
+    elif command in ('help', '--help', '-h'):
+        from spectra.commands.help import cmd_help
+        cmd_help()
+
+    elif command in ('--version', '-v'):
+        p(f'  spectra v{__version__}')
+        p()
+
+    else:
+        from spectra.commands.welcome import welcome
+        welcome()

spectra_sdd-0.4.0/spectra/colors.py

@@ -0,0 +1,25 @@
+import sys
+
+_USE_COLOR = sys.stdout.isatty() or True  # always emit ANSI; terminals handle it
+
+RESET  = '\x1b[0m'
+BOLD   = '\x1b[1m'
+CYAN   = '\x1b[36m'
+WHITE  = '\x1b[97m'
+YELLOW = '\x1b[33m'
+GREEN  = '\x1b[32m'
+GRAY   = '\x1b[90m'
+MAGENTA = '\x1b[35m'
+RED    = '\x1b[31m'
+
+
+def c(color: str, text: str) -> str:
+    return f"{color}{text}{RESET}"
+
+
+def b(color: str, text: str) -> str:
+    return f"{BOLD}{color}{text}{RESET}"
+
+
+def p(line: str = '') -> None:
+    print(line)

spectra_sdd-0.4.0/spectra/commands/help.py

@@ -0,0 +1,24 @@
+from spectra.colors import p, b, c, CYAN, WHITE, GREEN, GRAY
+
+
+def cmd_help() -> None:
+    p()
+    p(b(CYAN, '  SPECTRA') + c(GRAY, '  ·  Spec-Driven Development for Agentic AI'))
+    p()
+    p(c(GRAY, '  ┌─ Commands ────────────────────────────────────────────────┐'))
+    p(f'  │  {b(GREEN, "spectra init")}        {c(GRAY, "Scaffold .spectra/ with 13 layers")}           │')
+    p(f'  │  {b(GREEN, "spectra status")}      {c(GRAY, "Show which layers are filled vs pending")}     │')
+    p(f'  │  {b(GREEN, "spectra trace")}       {c(GRAY, "Scan specs + code → generate 12-trace.md")}   │')
+    p(f'  │  {b(GREEN, "spectra validate")}    {c(GRAY, "Validate spec quality and cross-refs")}        │')
+    p(f'  │  {b(GREEN, "spectra --version")}   {c(GRAY, "Show installed version")}                     │')
+    p(c(GRAY, '  └───────────────────────────────────────────────────────────┘'))
+    p()
+    p(f'  {c(GRAY, "Workflow")}:')
+    p(f'  {c(GRAY, "1.")} {b(WHITE, "spectra init")}    {c(GRAY, "→")} scaffold layers')
+    p(f'  {c(GRAY, "2.")} Fill {b(WHITE, "SPECTRA-PROMPT.md")} {c(GRAY, "→")} paste into Claude/GPT-4/Gemini')
+    p(f'  {c(GRAY, "3.")} Copy generated specs {c(GRAY, "→")} paste into {b(WHITE, ".spectra/")}')
+    p(f'  {c(GRAY, "4.")} {b(WHITE, "spectra status")}  {c(GRAY, "→")} verify coverage')
+    p(f'  {c(GRAY, "5.")} {b(WHITE, "spectra trace")}   {c(GRAY, "→")} generate traceability matrix')
+    p()
+    p(f'  {c(GRAY, "Docs")}  {c(CYAN, "https://github.com/GuiMiran/spectra")}')
+    p()

spectra_sdd-0.4.0/spectra/commands/init.py

@@ -0,0 +1,182 @@
+import os
+import shutil
+from datetime import date
+from pathlib import Path
+from spectra.colors import p, b, c, CYAN, WHITE, YELLOW, GREEN, GRAY, MAGENTA
+
+DATA_DIR = Path(__file__).parent.parent / 'data'
+
+LAYERS = [
+    ('00', 'vision',              'Vision & Context'),
+    ('01', 'glossary',            'Domain Glossary'),
+    ('02', 'stories',             'User Stories'),
+    ('03', 'business-rules',      'Business Rules'),
+    ('04', 'invariants',          'Invariants'),
+    ('05', 'contracts',           'Operation Contracts'),
+    ('06', 'policies',            'Decision Policies'),
+    ('07', 'events',              'Domain Events'),
+    ('08', 'agents',              'Agents'),
+    ('09', 'skills',              'Skills'),
+    ('10', 'workflows',           'Workflows'),
+    ('11', 'acceptance-criteria', 'Acceptance Criteria'),
+    ('12', 'trace',               'SPECTRA-TRACE'),
+]
+
+
+def _generate_layer(num: str, name: str) -> str:
+    return f"""# LAYER {num} — {name.upper()}
+
+> **Status**: Pending — fill this layer with your domain knowledge.
+> Send `SPECTRA-PROMPT.md` to an LLM to generate all 13 layers at once.
+
+---
+
+<!-- Add your {name} here. Each element must have a unique ID. -->
+<!-- Example IDs: US-001, BR-001, INV-001, POL-001, EVT-001, SK-001, WF-001 -->
+"""
+
+
+def _generate_trace() -> str:
+    today = date.today().isoformat()
+    return f"""# LAYER 12 — SPECTRA-TRACE
+## Bidirectional Agentic Traceability Matrix
+
+> **Live layer** — updated automatically by the agent at the end of every iteration.
+> Forward: detects functional gaps (spec without code).
+> Reverse: detects technical gaps (code without spec).
+
+---
+
+## Coverage Dashboard
+> Last updated: iter-0 · {today} · Agent: —
+
+| Metric                  | Value | Trend |
+|-------------------------|-------|-------|
+| Total specs             | 0     | —     |
+| Implemented specs       | 0     | —     |
+| Functional coverage     | 0%    | —     |
+| Artifacts without spec  | 0     | —     |
+| CRITICAL gaps           | 0     | —     |
+| MAJOR gaps              | 0     | —     |
+| MINOR gaps              | 0     | —     |
+| Current iteration       | iter-0| —     |
+
+---
+
+## Forward Matrix — Spec → Code
+> Detects **functional gaps**: specs with no implementation.
+
+| spec_id | type | description | prio | status | artifacts | tests | severity | iter | notes |
+|---------|------|-------------|------|--------|-----------|-------|----------|------|-------|
+| — | — | *No specs registered yet* | — | — | — | — | — | — | — |
+
+**Status legend**: `✅ IMPL` · `⏳ PARTIAL` · `❌ PENDING` · `🚫 EXCLUDED`
+**Severity**: `CRITICAL` (invariant/legal) · `MAJOR` (MUST BR/US) · `MINOR` (SHOULD/COULD)
+
+---
+
+## Reverse Matrix — Code → Spec
+> Detects **technical gaps**: code artifacts with no spec justifying them.
+
+| artifact | type | description | specs | status | action | iter_detected |
+|----------|------|-------------|-------|--------|--------|---------------|
+| — | — | *No artifacts registered yet* | — | — | — | — |
+
+**Status legend**: `✅ TRACED` · `⚠️ ORPHAN` · `🔍 REVIEW`
+**Action**: `KEEP` · `SPECIFY` · `DELETE` · `REFACTOR`
+
+---
+
+## Gap Report — iter-0
+> No gaps detected yet. Start filling the spec layers and implementing features.
+
+---
+
+## Iteration Log
+
+| iter | date | specs_impl | coverage | critical_gaps | major_gaps | orphans | note |
+|------|------|------------|----------|---------------|-----------|---------|------|
+| iter-0 | {today} | 0/0 | 0% | 0 | 0 | 0 | Initial scaffold |
+
+---
+
+## Agent Protocol
+> Instructions for the agent on how to update this file.
+
+At the end of every iteration:
+1. Count total specs across layers 02–11
+2. For each spec, find its implementing artifacts and link them in the Forward Matrix
+3. Scan all source files for `// @spectra` trace comments → populate Reverse Matrix
+4. Recalculate coverage = implemented / total × 100
+5. Classify unimplemented specs by severity (CRITICAL / MAJOR / MINOR)
+6. Update Coverage Dashboard and append a row to Iteration Log
+7. Write Gap Report with actionable next steps
+
+```
+coverage = implemented_specs / total_specs × 100
+CRITICAL ← INV not implemented | BR from legal regulation | SK blocking
+MAJOR    ← MUST BR not implemented | MUST US not implemented
+MINOR    ← SHOULD/COULD BR or US | POL edge case
+```
+"""
+
+
+def cmd_init() -> None:
+    p()
+    p(b(CYAN, '  Initializing Spectra...'))
+    p()
+
+    spectra_dir = Path.cwd() / '.spectra'
+
+    if spectra_dir.exists():
+        p(c(YELLOW, '  ⚠  .spectra/ already exists in this directory.'))
+        p(c(GRAY, '     Remove it first if you want to re-initialize.'))
+        p()
+        raise SystemExit(1)
+
+    spectra_dir.mkdir(parents=True)
+
+    for num, slug, name in LAYERS:
+        file = spectra_dir / f'{num}-{slug}.md'
+        content = _generate_trace() if num == '12' else _generate_layer(num, name)
+        file.write_text(content, encoding='utf-8')
+        label = b(MAGENTA, name) if num == '12' else c(WHITE, name)
+        p(f'  {c(GRAY, num + " ·")} {label}')
+
+    # Copy SPECTRA-PROMPT.md from package data
+    prompt_src  = DATA_DIR / 'SPECTRA-PROMPT.md'
+    prompt_dest = Path.cwd() / 'SPECTRA-PROMPT.md'
+    if prompt_src.exists() and not prompt_dest.exists():
+        shutil.copy2(prompt_src, prompt_dest)
+
+    # Create .instructions.md for AI agents
+    instr_dest = Path.cwd() / '.instructions.md'
+    if not instr_dest.exists():
+        instr_dest.write_text(
+            '# Project Instructions\n\n'
+            '## Spectra Framework\n\n'
+            'This project uses **Spectra** for domain specification.\n\n'
+            '### AI Agent Instructions\n\n'
+            '1. Read relevant layers from `.spectra/` before making any changes\n'
+            '2. Never violate invariants defined in `04-invariants.md`\n'
+            '3. Apply business rules from `03-business-rules.md`\n'
+            '4. Use only canonical terms from `01-glossary.md`\n'
+            '5. Update `12-trace.md` (SPECTRA-TRACE) at the end of every iteration\n\n'
+            '> Specs are the source of truth. Code is the derivative.\n',
+            encoding='utf-8',
+        )
+
+    p()
+    p(c(GREEN, '  ✔  .spectra/ created with 13 layers'))
+    p(c(GREEN, '  ✔  SPECTRA-PROMPT.md ready'))
+    p(c(GREEN, '  ✔  .instructions.md created for AI agents'))
+    p()
+    p(b(YELLOW, '  Next steps'))
+    p()
+    p(f'  {c(GRAY, "1.")} Open {b(WHITE, "SPECTRA-PROMPT.md")} and fill in your domain')
+    p(f'  {c(GRAY, "2.")} Send it to {b(WHITE, "Claude, GPT-4, or Gemini")} to generate the 13 layers')
+    p(f'  {c(GRAY, "3.")} Drop the specs into {b(WHITE, ".spectra/")} — your agent reads them automatically')
+    p(f'  {c(GRAY, "4.")} Build. The agent now knows your domain.')
+    p()
+    p(c(GRAY, '  Docs: https://github.com/GuiMiran/spectra'))
+    p()

spectra_sdd-0.4.0/spectra/commands/status.py

@@ -0,0 +1,70 @@
+import re
+from pathlib import Path
+from spectra.colors import p, b, c, CYAN, WHITE, YELLOW, GREEN, GRAY, MAGENTA, RED
+from spectra.layers import LAYERS, ID_PATTERNS, STUB_MARKERS
+
+
+def cmd_status() -> None:
+    spectra_dir = Path.cwd() / '.spectra'
+
+    p()
+    p(b(CYAN, '  SPECTRA STATUS'))
+    p()
+
+    if not spectra_dir.exists():
+        p(c(YELLOW, '  ⚠  No .spectra/ directory found.'))
+        p(c(GRAY, '     Run: spectra init'))
+        p()
+        raise SystemExit(1)
+
+    def is_stub(content: str) -> bool:
+        return any(m in content for m in STUB_MARKERS)
+
+    total_ids    = 0
+    filled_layers = 0
+
+    p(c(GRAY, '  ─────────────────────────────────────────────────────────────'))
+    p(f'  {"Layer":<28} {"IDs":<6} Status')
+    p(c(GRAY, '  ─────────────────────────────────────────────────────────────'))
+
+    for num, slug, name in LAYERS:
+        file = spectra_dir / f'{num}-{slug}.md'
+
+        if not file.exists():
+            p(f'  {c(GRAY, num + " ·")} {name:<25} {c(RED, "——    ❌ missing")}')
+            continue
+
+        content = file.read_text(encoding='utf-8')
+        stub    = is_stub(content)
+
+        clean = re.sub(r'```[\s\S]*?```', '', content)
+        ids   = sum(len(rx.findall(clean)) for rx in ID_PATTERNS.values())
+        total_ids += ids
+        if not stub:
+            filled_layers += 1
+
+        is_trace  = (num == '12')
+        name_col  = b(MAGENTA, name) if is_trace else c(WHITE, name)
+        ids_col   = c(GREEN if ids > 0 else GRAY, str(ids).ljust(6))
+        status    = c(YELLOW, '⏳ pending') if stub else c(GREEN, '✅ filled')
+
+        extra = 20 if is_trace else 0
+        p(f'  {c(GRAY, num + " ·")} {name_col:<{25 + extra}} {ids_col} {status}')
+
+    p(c(GRAY, '  ─────────────────────────────────────────────────────────────'))
+    p()
+
+    spec_layers = len(LAYERS) - 1  # exclude trace
+    pct = round((filled_layers / spec_layers) * 100) if spec_layers else 0
+    bar = '█' * (pct // 5) + '░' * (20 - pct // 5)
+    p(f'  Layers filled   {b(WHITE, str(filled_layers) + "/" + str(spec_layers))}  {c(GREEN if filled_layers > 0 else GRAY, bar)}  {b(CYAN, str(pct) + "%")}')
+    p(f'  Total IDs       {b(WHITE, str(total_ids))}')
+    p()
+
+    if filled_layers == 0:
+        p(c(YELLOW, '  Next: fill SPECTRA-PROMPT.md and send it to an LLM to generate your specs.'))
+    elif pct < 80:
+        p(c(YELLOW, '  Some layers still pending. Run: spectra trace  to build the traceability matrix.'))
+    else:
+        p(c(GREEN, '  Specs look complete. Run: spectra trace  to generate the traceability matrix.'))
+    p()