eidos-ai 0.2.0

= Eidos: Git-Native AI Software Development Ecosystem
:toc: left
:icons: font
:source-highlighter: highlight.js

image:https://github.com/mchawa/eidos/actions/workflows/ci.yml/badge.svg[CI, link=https://github.com/mchawa/eidos/actions/workflows/ci.yml]
image:https://img.shields.io/pypi/v/eidos-ai.svg[PyPI, link=https://pypi.org/project/eidos-ai/]
image:https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.15-blue.svg[Python, link=https://pypi.org/project/eidos-ai/]
image:https://img.shields.io/badge/docs-zensical-blue.svg[Documentation, link=https://mchawa.github.io/eidos/]
image:https://img.shields.io/badge/portal-c4--explorer-green.svg[Living Portal, link=https://mchawa.github.io/eidos/portal/]
image:https://img.shields.io/badge/License-MIT-yellow.svg[License, link=https://opensource.org/licenses/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.

== Quickstart

[source,bash]
----
# Install with uv (recommended)
uv add --dev eidos-ai

# Or with pip
pip install eidos-ai

# Initialize Eidos in your repository
eidos init

# Validate living specifications
eidos validate eidos

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

# Install AI agent plugin (Antigravity, Claude, Cursor)
eidos plugin install --target all
----

== Repository Architecture

[source,text]
----
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 delta`, etc.)
│   ├── core/                      # AsciiDoc + YAML frontmatter parser & schema validator
│   ├── mcp/                       # Model Context Protocol stdio server
│   ├── plugin/                    # Agent plugin packager, validator, and installer
│   ├── portal/                    # Interactive Living Architecture static portal generator
│   └── schemas/v1/                # Portable JSON/YAML Schemas bundled as package data
│
├── eidos/                         # [THE LIVING SPECIFICATION / REAL USAGE]
│   ├── system.adoc                # Root system descriptor
│   ├── personas/                  # Human & AI actor roles
│   ├── policies/                  # Non-negotiable architectural invariants (POL-*)
│   ├── domains/                   # Bounded contexts & capabilities (CAP-*)
│   ├── architecture/              # System architecture, components, & contracts
│   └── deltas/                    # In-flight and applied mutations (DLT-*)
│
├── docs/                          # User documentation site (Zensical)
└── tests/                         # Engine & specification test suites
----

== Key Distinctions from Existing Tools

[cols="1,2,2", options="header"]
|===
| 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 agent-plugins.org v1.0.0 & Model Context Protocol (MCP)
| **VCS Support** | GitHub-only or closed web UI | Native bidirectional support for both GitHub and GitLab
|===

== Navigating the Specifications

* **Root System**: link:eidos/system.adoc[`system.adoc`]
* **Product Domains**:
** link:eidos/domains/product-core/domain.adoc[`Product Intelligence Domain`]
** link:eidos/domains/agent-harness/domain.adoc[`Agent Harness Domain`]
** link:eidos/domains/vcs-sync/domain.adoc[`VCS Sync Domain`]
* **Policies**:
** link:eidos/policies/POL-001-git-as-single-source-of-truth.adoc[`POL-001: Git Source of Truth`]
** link:eidos/policies/POL-002-invariant-test-enforcement.adoc[`POL-002: Invariant Test Enforcement`]
* **Technical Architecture**:
** link:eidos/architecture/system-architecture.adoc[`Global System Architecture`]
** link:eidos/architecture/components/[`Components Directory`]
** link:eidos/architecture/contracts/[`Contracts Directory`]
* **SpecDeltas**:
** link:eidos/deltas/[`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 link:LICENSE[MIT License].