SPECULA (Private Delivery)

This repository is a private client delivery of the SPECULA documentation set.

Recommended reading order

1. Foundations of the Specula Method
2. SPECULA AI Constitution
3. Technical Translation & Operational Governance
4. Control Logic & State Machine
5. System Architecture & Input Specifications
6. JSON Schemas & Output Architecture
7. Prompt Playbook v1.0
8. Specula Method v2.3
9. Specula Method Agent Protocol
10. Specula Method v2.4.5.2 (Aligned Proposal, IT)

Repository map

• docs/ — canonical documents (human-readable)
• specs/ — governance specs (precedence, terminology, versioning, compliance)
• schemas/ — machine-readable JSON schemas (runtime contracts)
• prompts/ — system + phase prompt templates
• src/ — executable runtime MVP (specula_agent)
• tests/ — executable validation and orchestrator tests
• templates/ — example payloads and project scaffolding

Governance

See specs/precedence.md and specs/terminology.md.

Versioning

See specs/versioning.md and CHANGELOG.md.

Runtime MVP (Local)

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .[dev]
specula-agent step --user-input "Start Phase 0 for a new project"
pytest

Runtime with LLM + PostgreSQL (Optional)

source .venv/bin/activate
python -m pip install -e .[postgres]
export OPENAI_API_KEY="..."
export SPECULA_DATABASE_URL="postgresql://user:pass@localhost:5432/specula"
specula-agent init-db --database-url "$SPECULA_DATABASE_URL"
specula-agent step \
  --user-input "Start Phase 1 for a mobility brand" \
  --llm-provider openai \
  --llm-model gpt-4o-mini \
  --llm-api-key-env OPENAI_API_KEY \
  --database-url "$SPECULA_DATABASE_URL"

Delivery date: 2026-01-04