Skip to content
mchawaPublic

About

Bridging architectural intent and autonomous coding agents through living specifications, SpecDeltas, and invariant-test traceability.

Resources

Contributing

Stars

15 stars

Watchers

0 watching

Forks

Repository files navigation

Eidos: Git-Native AI Software Development Ecosystem

CI PyPI Python Documentation Living Portal License: MIT

Eidos is an open, Git-native, agent-agnostic development framework designed to unify product definition, architectural invariants, and autonomous coding agents under executable living specifications.

This repository dogfoods the Eidos Specification Standard to define Eidos itself.

Why Eidos?

When working with AI coding agents (Claude Code, Cursor, Antigravity, Copilot, Aider, Cline) on growing codebases, static instruction files like CLAUDE.md get large and hard to maintain, traditional ADRs go out of date, and architectural boundaries can silently drift.

Eidos takes an opinionated approach built on Spec-Driven Development, Domain-Driven Design (DDD), Arc42 & the C4 Model, TDD, and a Kanban SpecDelta lifecycle—with Git as the single source of truth and 100% local execution (zero API keys or external LLM calls required):

  • Living Architecture in Git (DDD + Arc42/C4 + Kanban): Codifies bounded domains (DOM-*), capabilities (CAP-*), C4 architecture (CNT-*, CMP-*, CTR-*), and in-place design decisions (DEC-*) as AsciiDoc with YAML frontmatter, tracking architectural transitions via SpecDeltas (DLT-*) across a Kanban lifecycle.
  • Local SQLite + AST + Hybrid Semantic Knowledge Graph: Indexes code symbols, spec hierarchies, and x-eidos-ref links locally (eidos/.cache/index.db)—combining SQLite FTS5 BM25 search, recursive graph traversal, and optional local ONNX semantic embeddings (Hybrid RRF) to serve token-budgeted context slices (eidos context), structural repo maps, and transitive blast-radius queries (eidos index blast-radius) offline with no API keys.
  • Test-Bound Invariants (TDD + eidos drift): Binds capability and policy invariants (INV-*) directly to automated tests (file::func) across Python, TypeScript/JS, Go, Rust, Java, and Kotlin, checking for spec-to-code drift in CI or via an agent Stop hook.
  • Static C4 Architecture & Kanban Portal: Generates a self-contained web viewer (eidos portal serve) to browse containers, components, contracts, blast radius, and the SpecDelta Kanban board—View Eidos's Portal
                    ┌───────────────────────────────────┐
                    │   Living Specifications (eidos/)  │
                    │  CNT-* │ CMP-* │ CTR-* │ CAP/INV  │
                    └─────────────────┬─────────────────┘
                                      │
                      ┌───────────────┴───────────────┐
                      ▼ (SQLite + AST Graph)          ▼ (eidos portal)
            ┌───────────────────┐           ┌───────────────────┐
            │  AI Coding Agents │           │  Human Engineers  │
            │ (eidos context &  │           │   (C4 Explorer    │
            │   Agent Skills)   │           │  & Blast Radius)  │
            └─────────┬─────────┘           └─────────┬─────────┘
                      │                               │
                      └───────────────┬───────────────┘
                                      ▼
                    ┌───────────────────────────────────┐
                    │   Codebase & Polyglot Test Suite  │
                    │   Checked by: eidos drift / hook  │
                    └───────────────────────────────────┘

Quickstart

# Install globally as a standalone CLI tool with uv (recommended)
uv tool install eidos-ai

# Or install with optional local Harrier ONNX Hybrid RRF semantic search support (Python 3.11–3.14)
uv tool install --python 3.14 "eidos-ai[semantic]"

# Or install with pipx
pipx install eidos-ai

# Or run ephemerally without installing
uvx --from eidos-ai eidos --help

# Initialize Eidos in your repository
eidos init

# (Optional) Provision local Harrier-OSS-v1-0.6B ONNX model for Hybrid RRF semantic search
eidos index semantic setup

# Synchronize SQLite + FTS5 + AST knowledge graph (and semantic embeddings when provisioned)
eidos index sync

# Inspect structural repo map or find code symbols and their owning specs
eidos index repo-map --max-tokens 1500
eidos index find-symbol "ArchitecturalIndex" --json

# Extract a token-budgeted architectural context slice for a file or task
eidos context -t "authentication and drift detection"

# Inspect v1 YAML frontmatter schema constraints & templates for any spec type
eidos spec schema capability

# Validate living specifications
eidos validate eidos

# Verify zero drift between code, tests, and living specs
eidos drift

# Launch interactive C4 architecture portal
eidos portal serve --path eidos --port 8080

# Install AI agent plugin (4 skills for Antigravity, Claude, Cursor, Copilot, Aider, Cline, Kilo Code, OpenCode, Codex)
eidos plugin install all

Dev Container Feature (VS Code Dev Containers & GitHub Codespaces)

Add the official Eidos Dev Container Feature (ghcr.io/mchawa/eidos/eidos:1) to .devcontainer/devcontainer.json:

{
  "features": {
    "ghcr.io/mchawa/eidos/eidos:1": {
      "version": "latest",
      "semantic": true,
      "pythonVersion": "3.14"
    }
  }
}

Optional Local Semantic Search (Hybrid RRF)

By default, Eidos runs with zero model weights using SQLite FTS5 BM25, architectural synonym expansion, and recursive CTE graph traversal (< 4ms). To enable Hybrid Reciprocal Rank Fusion (RRF) combining lexical BM25 with local dense embeddings (microsoft/harrier-oss-v1-0.6b ONNX, 100% offline):

Note (Python Version): onnxruntime currently publishes prebuilt wheels only for Python 3.11–3.14 (python_version < '3.15'). If your default interpreter is Python 3.15, pass --python 3.14 when installing or syncing the [semantic] extra; on Python 3.15, Eidos automatically falls back to lexical FTS5 BM25 retrieval.

# 1. Install optional ONNX Runtime + Tokenizers + NumPy extra (Python 3.11–3.14)
uv tool install --python 3.14 "eidos-ai[semantic]"   # or: uv sync --python 3.14 --extra semantic

# 2. Download Harrier ONNX artifacts into eidos/.cache/models/harrier-oss-v1-0.6b/
eidos index semantic setup             # --model quantized (default INT8, 706 MB) | fp16 | fp32

# 3. Sync the index (automatically builds & refreshes spec_embeddings whenever Harrier is provisioned)
eidos index sync
eidos index semantic status

Once provisioned, eidos context -t "<task>", eidos index search "<query>", and eidos drift automatically fuse FTS5 BM25 and Harrier cosine similarity (or pass --no-semantic for pure lexical retrieval).


Repository Architecture

eidos/
├── pyproject.toml                 # Modern Python package definition (eidos-ai on PyPI)
├── zensical.toml                  # Zensical documentation site configuration
│
├── src/eidos/                     # [THE ENGINE / SOLUTION]
│   ├── cli/                       # CLI commands (`eidos validate`, `eidos drift`, `eidos context`, etc.)
│   ├── core/                      # Spec parser, validator, scaffolder, DeltaEngine & knowledge graph (`index/`)
│   ├── plugin/                    # Agent plugin installer (`TargetAdapter`), validator, and lifecycle hooks
│   ├── portal/                    # Interactive Living Architecture server & static portal generator
│   └── vcs/                       # Git spec-to-code drift detection, AST symbol diffing & invariant verification
│
├── assets/                        # [BUNDLED SCHEMAS, SKILLS & PORTAL ASSETS]
│   ├── schemas/v1/                # 16 canonical JSON/YAML schemas + shared `common/defs.yaml`
│   ├── plugin_reference/          # Canonical `agentskills.io` 4 workflow skills & reference `hooks.json`
│   └── portal/                    # Pre-compiled air-gapped portal SPA (`bundle.html.gz`)
│
├── eidos/                         # [THE LIVING SPECIFICATION / DOGFOODED CATALOG]
│   ├── system.adoc                # Root system descriptor (SYS-*)
│   ├── personas/                  # Human & AI actor roles (PER-*)
│   ├── policies/                  # Non-negotiable architectural policies (POL-*)
│   ├── domains/                   # Bounded contexts (DOM-*) & capabilities with test-bound invariants (CAP-*, INV-*)
│   ├── architecture/              # Arc42/C4 architecture (ARCH-*), containers (CNT-*), components (CMP-*), contracts (CTR-*)
│   ├── design/                    # Multi-Design Systems (DS-*), W3C tokens, UI components (UIC-*), clients (CLT-*), screens (SCR-*), flows (FLOW-*)
│   ├── explorations/              # Hypothesis-driven technical spikes (EXP-*) & archive/
│   └── deltas/                    # Active and recent SpecDelta mutations (DLT-*) & archive/
│
├── docs/                          # User documentation site (Zensical)
└── tests/                         # Engine & invariant verification test suites

Key Distinctions from Existing Tools

Dimension Traditional / Existing Tools Eidos Approach
Scope Coding loop only (Aider, Claude Code) or monolithic bot (Devin) Full SDLC: Exploration → Product Baseline → SpecDelta → Code → CI
Specifications Ephemeral Jira tickets, stale Confluence/Notion pages Versioned YAML frontmatter + AsciiDoc living in Git
Change Management Narrative RFC essays that rot in archive folders Declarative SpecDelta mutations applied automatically upon merge
Agent Support Vendor-locked to a single proprietary LLM Agent-agnostic via agentskills.io CLI-first Agent Skills across 9 coding clients
VCS Support Tied to a single SaaS platform or closed web UI 100% Git-native local repository engine

Navigating the Specifications


Documentation & Living Portal


License

Licensed under the MIT License.

About

Bridging architectural intent and autonomous coding agents through living specifications, SpecDeltas, and invariant-test traceability.

Resources

Contributing

Stars

15 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages