Eidos: Git-Native AI Software Development Ecosystem

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.

Quickstart

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

# Or install with pipx
pipx install eidos-ai

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

# Initialize Eidos in your repository (or use `eidos init --lite` for a 3-file starter profile)
eidos init

# Synchronize SQLite + FTS5 + AST knowledge graph index
eidos index sync

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

# 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, OpenCode, Codex)
eidos plugin install all

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 `agent-plugins.org v1.0.0` bundle & 4 workflow skills
│   └── 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-*)
│   └── deltas/                    # In-flight and applied SpecDelta mutations (DLT-*)
│
├── docs/                          # User documentation site (Zensical)
└── tests/                         # Engine & invariant verification test suites

Key Distinctions from Existing Tools

Navigating the Specifications

• Root System: eidos/system.adoc
• Product Domains:
  • Spec Engine Domain
  • Agent Intelligence Domain
  • VCS Lifecycle Domain
  • Experience Portal Domain
• Policies:
  • POL-001: Git Source of Truth
  • POL-002: Invariant Test Enforcement
• Technical Architecture:
  • Global System Architecture
  • Containers Directory
  • Contracts Directory
• SpecDeltas:
  • SpecDeltas Directory

Documentation & Living Portal

• User Documentation: https://mchawa.github.io/eidos/
• Interactive Living Architecture Portal: https://mchawa.github.io/eidos/portal/
• PyPI Package: https://pypi.org/project/eidos-ai/
• AI Agent Plugin Guide: https://mchawa.github.io/eidos/guides/agent-plugin/

License

Licensed under the MIT License.