spectra: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What is Spectra?

Spectra deploys 8 AI agents (6 parallel specialists + MetaPrompter + CritiqueAgent) to analyze entire repositories across 6 dimensions — architecture, security, quality, documentation, maintainability, performance — in under 5 minutes. Python CLI. Clean Architecture.

Tagline: "The full spectrum of your codebase." One-liner: "8 AI agents analyze your entire repository in under 5 minutes."

---

Development Commands

# Install dependencies
pip install -e ".[dev]"

# Run CLI
spectra analyze <repo-url>
spectra analyze <repo-url> --quick    # Skip CritiqueAgent
spectra analyze <repo-url> --format json
spectra analyze <repo-url> --audit-sink stdout|file:<path>|otlp:<url>
spectra verify spectra-report.json    # Verify Ed25519 receipt

# Run tests
pytest tests/ -v
pytest tests/entities/ -v              # Unit tests only
pytest tests/integration/ -v           # Integration tests
pytest tests/ --cov=spectra --cov-report=html

# Lint and type check
ruff check src/ tests/
ruff format src/ tests/
mypy src/

# Build and publish
python -m build
pip install dist/spectra_cli-*.whl

---

Architecture — ABSOLUTE RULES (NEVER VIOLATE)

The Dependency Rule

Source code dependencies ONLY point inward:

Layer 1 (entities/)         → imports NOTHING from spectra package
Layer 2 (use_cases/)        → imports ONLY from entities/
Layer 3 (adapters/)         → imports from entities/ + use_cases/
Layer 4 (infrastructure/)   → imports from all inner layers

Violation = immediate rejection. No exceptions.

Code Standards

• Functions: ≤20 lines, ≤3 parameters, cyclomatic complexity ≤10
• No Any type. No # type: ignore.
• No print() in src/ — use ProgressObserver port via Rich Console
• Every entity: frozen=True on Pydantic models. Immutable.
• Fallible operations: Result dataclass pattern
• All agent outputs: validated with Pydantic model BEFORE merge
• Literal types for enums: Severity = Literal["critical", "high", "medium", "low", "info"]
• Export everything from __init__.py with __all__