AI Agent Integration¶

Eidos is agent-agnostic and model-agnostic. It provides a standardized plugin bundle conforming to agent-plugins.org v1.0.0 and 4 cohesive Agent Skills conforming to agentskills.io so any AI coding assistant—such as Google Antigravity, Claude Code, Cursor, GitHub Copilot, Aider, Cline, OpenCode, or OpenAI Codex—can understand, query, and mutate your living specifications safely through direct CLI execution.

                    ┌─────────────────────────────────────────┐
                    │          AI Coding Assistant            │
                    │ (Google Antigravity, Claude, Cursor, …) │
                    └────────────────────┬────────────────────┘
                                         │
                    Direct CLI / Skills  │   Rules & Guidelines
                    (eidos validate, …)  │   (AGENTS.md, .mdc)
                                         ▼
                    ┌─────────────────────────────────────────┐
                    │           Eidos Agent Plugin            │
                    │        (agent-plugins.org v1)           │
                    └────────────────────┬────────────────────┘
                                         │
                    Inspect Architecture │   Scaffold & Apply
                    & Invariants         │   SpecDeltas (DLT-*)
                                         ▼
                    ┌─────────────────────────────────────────┐
                    │          Living Specifications          │
                    │      (eidos/*.adoc in Git repo)         │
                    └─────────────────────────────────────────┘

The CLI-First Architecture for AI Agents¶

Modern AI coding agents (Claude Code, Cursor Composer, Google Antigravity, Copilot, Cline, Aider) operate inside terminal-capable sandboxes, subshells, and Docker containers. Eidos is built CLI-first:

• Zero Daemon Flakiness: No long-running background stdio server processes to crash, disconnect, deadlock, or require manual port management.
• Universal Cloud & Sandbox Portability: Works out-of-the-box in GitHub Codespaces, remote SSH sessions, CI/CD runners, and ephemeral cloud devboxes where local stdio daemon connections are unreliable.
• Deterministic --json Contracts: Every inspection, validation, and drift check command supports --json output, providing deterministic schemas that agents can parse programmatically without regex or LLM hallucination.
• Token-Efficient Progressive Disclosure: Through eidos context, agents extract targeted architectural slices (~140 to ~1,500 tokens) rather than dumping thousands of lines of documentation into the context window.
• Strict Exit Code Semantics: Commands return standard Unix exit codes (0 for success/clean, 1 for validation errors or drift), enabling automated tool loops and pre-commit hooks to halt instantly on failure.

One-Command Setup¶

Eidos automatically configures your project for all supported AI coding assistants in a single step:

# Default installation (configures project scope, Cursor, and Claude Code):
eidos plugin install

# Full installation across all supported AI assistants:
eidos plugin install all

# Targeted installation for a specific assistant:
eidos plugin install cursor
eidos plugin install claude
eidos plugin install copilot

Installation Targets¶

Assistant Integration Guides¶

Select your AI coding assistant below for step-by-step setup instructions and configuration examples:

eidos plugin install antigravity

.agents/plugins/eidos/
├── plugin.json               # agent-plugins.org v1.0.0 manifest
├── hooks.json                # Document linting & drift gate hooks
└── skills/
    ├── eidos/                # Master orchestrator, context slicing & continuous drift detection
    ├── eidos-spec/           # Product, Arc42/C4 architecture, design systems & invariants (NO ADRs)
    ├── eidos-plan/           # Technical spikes (EXP-*), SpecDeltas (DLT-*) & Staff Architect review
    └── eidos-ops/            # Greenfield init, brownfield extraction & Living Web Portal

eidos plugin install claude

<!-- CLAUDE.md -->
## Eidos Architectural Guidelines
- Adhere strictly to the guidelines in `.agents/plugins/eidos/skills/eidos/SKILL.md`.
- Treat `eidos/` living specifications as the single source of truth.
- Never create ADRs; all mutations must follow the SpecDelta lifecycle (`eidos delta create`).
- Validate specifications with `eidos validate --json` before completing tasks.
- Check for spec-to-code drift with `eidos drift --uncommitted --json`.

eidos plugin install cursor

---
description: "Eidos living specifications and architectural governance"
alwaysApply: true
---

# Eidos Living Specifications

This repository is governed by Eidos living specifications under `eidos/`.

## Core Principles
- Consult living specifications before modifying code or proposing architectural changes.
- Strictly enforce living specifications (NO ADRs). All architectural mutations follow the SpecDelta lifecycle (`eidos/deltas/`).
- Preserve bidirectional invariant-test traceability (`POL-002`).
- Verify specification schemas with `eidos validate eidos` (or `eidos validate --json`).
- Verify synchronization with `eidos drift --uncommitted` (or `eidos drift --uncommitted --json`) before finalizing tasks.
- Use Eidos CLI commands (`eidos context`, `eidos index search`, `eidos drift`) for real-time inspection.
- Consult installed Agent Skills in `.cursor/skills/` for specialized architectural workflows.

eidos plugin install copilot

eidos plugin install aider

aider

eidos plugin install cline

eidos plugin install open-code
# or
eidos plugin install opencode

eidos plugin install codex

# Check specification validity
eidos validate --json

# Inspect spec-to-code drift
eidos drift --uncommitted --json

# Extract architectural context slice
eidos context -f <touched-file> --json

CLI Automation Commands for AI Agents¶

AI agents execute Eidos CLI commands directly from terminal / subshell tools. All core commands support machine-readable --json output:

Machine-Readable JSON Output Reference¶

When agents pass --json, Eidos outputs structured JSON payloads designed for programmatic consumption:

1. Specification Validation (eidos validate --json)¶

{
  "is_clean": true,
  "total_docs": 62,
  "valid_docs": 62,
  "schema_errors": {},
  "broken_references": []
}

2. Drift Detection (eidos drift --uncommitted --json)¶

{
  "is_clean": true,
  "drift_detected": false,
  "workflow_mode": "planned",
  "code_files": ["src/eidos/cli/main.py"],
  "spec_files": ["eidos/architecture/containers/cli.adoc"],
  "delta_files": ["eidos/deltas/dlt-2026-016.adoc"],
  "test_files": ["tests/test_cli_json.py"],
  "touched_components": ["CNT-EIDOS-CLI"],
  "unmapped_code_files": [],
  "valid_specs": 62,
  "total_specs": 62,
  "validation_errors": [],
  "uncovered_invariants": [],
  "orphan_invariants": [],
  "remediation_suggestions": [],
  "trivially_covered_files": []
}

3. Context Slicing (eidos context -f src/eidos/cli/main.py --json)¶

{
  "tier": "guardrails",
  "components": [
    {
      "id": "CNT-EIDOS-CLI",
      "title": "Eidos Command-Line Interface",
      "type": "tech/container",
      "source_path": "src/eidos/cli"
    }
  ],
  "contracts": [
    {
      "id": "CTR-EIDOS-CLI",
      "protocol": "cli_args",
      "container": "CNT-EIDOS-CLI"
    }
  ],
  "capabilities": [
    {
      "id": "CAP-AGENT-001",
      "title": "Agent Adapter & Context Engine",
      "domain": "DOM-AGENT-INTELLIGENCE"
    }
  ],
  "invariants": [
    {
      "id": "INV-AGENT-GRAPH-INDEX-FRESHNESS",
      "rule": "Every CLI query lazily checks dirty status via SHA-256 and mtime hashing.",
      "has_test_coverage": true,
      "test_binding": "tests/test_graph_index.py::test_spike_b_incremental_dirty_check_and_lazy_sync"
    }
  ],
  "policies": [
    {
      "id": "POL-001-GIT-SOURCE-OF-TRUTH",
      "title": "Git Repository as the Single Source of Truth"
    }
  ]
}

The 7 Constitutional Guardrails¶

Eidos embeds seven non-negotiable architectural guardrails in its master skill skills/eidos/SKILL.md. When working in an Eidos repository, every AI assistant is instructed to obey them:

1. Single Source of Truth (POL-001)¶

All product domains, capabilities, personas, C4 architecture containers/components, interface contracts, design systems, and policies live inside eidos/ as structured AsciiDoc (.adoc) files with YAML frontmatter.

2. Zero ADRs (POL-001)¶

Standalone Architecture Decision Records (docs/adr/, eidos/adr/, or ADR-*.md) are strictly prohibited. Current architectural state lives in eidos/architecture/, durable design rationale and rejected alternatives are recorded in-place under the decisions: (DEC-*) frontmatter block of the owning specification, and transitions are governed by SpecDeltas (eidos/deltas/dlt-*.adoc).

3. Dual Workflow Mode Selection (POL-003)¶

Every task operates in either Direct Mode (fast, in-place co-evolution of code, tests, and owning specs for localized edits) or Planned Mode (formal SpecDelta DLT-* lifecycle for cross-container or breaking changes). Agents classify the workflow mode before writing code.

4. Mandatory Invariant-Test Traceability (POL-002)¶

Every capability invariant (INV-*) must declare a concrete test_binding (path/to/test_file::test_function or path/to/test_file::TestClass::test_method), and the bound test function must explicitly reference the INV-* ID.

5. Deterministic Engine Only (POL-004)¶

Eidos CLI commands are 100% deterministic local operations with zero external AI/LLM runtime calls. Agents always invoke Eidos CLI commands rather than guessing schemas or manually wiring symlinks.

6. Zero Unreconciled Drift¶

No task may conclude with failing specification schemas (eidos validate eidos) or unmanaged code-to-spec drift (eidos drift --uncommitted).

7. Mandatory Autonomous Adversarial Gap Self-Review¶

Before presenting work or concluding a task, the agent executes an autonomous adversarial review over its own git diff—auditing requirements completeness, edge cases, contract SemVer consistency (CTR-*), genuine test assertions (INV-*), and embedded decision capture (DEC-*)—and fixes any gaps immediately.

Stateless Stop Lifecycle Hook (eidos hook)¶

In agent harnesses that support lifecycle hooks (Google Antigravity, Claude Code, Cursor, Cline, OpenCode, and Codex), Eidos registers a single stateless Stop hook in hooks.json:

• eidos-drift-gate (eidos hook):
• Stateless Unified Check: When an agent finishes its task (Stop event), eidos hook runs detect_drift(uncommitted=True), which verifies living specification schemas and cross-references (SpecValidator), invariant test bindings (INV-*), and spec-to-code synchronization in a single pass.
• Non-Blocking Advisory Warning: Returns {"decision": "allow"} when clean, or {"decision": "allow", "systemMessage": "⚠️ ..."} with exact remediation steps when validation errors, broken invariant bindings, or code drift are detected—requiring zero state files, zero per-edit subprocesses, and never trapping agents in infinite retry loops.

Bundled Skills for AI Agents¶

When using an agent client that supports skill bundles (such as Google Antigravity, Claude Code, Cursor, Cline, OpenCode, Codex, Aider, or GitHub Copilot), 4 cohesive workflow skills are available:

• eidos: Master workflow orchestrator (Direct vs. Planned Mode), token-efficient architectural context slicing (eidos context), and continuous spec-to-code drift detection (eidos drift).
• eidos-spec: Unified authoring reference for Product domains (DOM-*), capabilities (CAP-*), personas (PER-*), Arc42/C4 architecture (CNT-*, inline and promoted CMP-*, CTR-*, embedded decisions:), Multi-Design Systems (DS-*, W3C Design Tokens, UIC-*, CLT-*, SCR-*, FLOW-*), and system policies/invariants (POL-*, INV-* with polyglot file::func test bindings).
• eidos-plan: Technical feasibility spikes (EXP-*), the SpecDelta mutation lifecycle (DLT-*, create, verify, audit, apply, changelog), and 5-dimension Staff Systems Architect reviews.
• eidos-ops: Greenfield repository initialization (eidos init, eidos init --lite), systematic reverse-engineering of brownfield codebases into living specifications, and Living Web Portal operations (eidos portal serve, eidos portal build).

Plugin Lifecycle & Maintenance¶

Eidos provides a complete suite of commands to manage, inspect, and update the installed agent plugin:

Inspect Plugin Manifest¶

Display full metadata and configuration for the Eidos Agent Plugin:

eidos plugin info

Output:

╭──────────────────────── Eidos Agent Plugin Manifest ─────────────────────────╮
│ Plugin Identifier:  eidos                                                    │
│           Version:  0.8.0                                                    │
│       Description:  Git-native, agent-agnostic development AI ecosystem and  │
│                     lifecycle orchestration framework.                       │
│           License:  MIT                                                      │
│     Specification:  agent-plugins.org v1.0.0                                 │
│            Skills:  eidos, eidos-ops, eidos-plan, eidos-spec                 │
│       MCP Servers:  None                                                     │
│   Lifecycle Hooks:  eidos-drift-gate                                         │
│        Extensions:  com.google.antigravity                                   │
╰──────────────────────────────────────────────────────────────────────────────╯

Inspect Version Status¶

Compare the currently installed plugin against the version bundled with the Eidos engine:

eidos plugin version

Upgrade the Installed Plugin¶

When upgrading eidos-ai, update the project's installed plugin files in-place:

eidos plugin update all

Verify Conformance¶

Ensure that your plugin bundle strictly complies with the agent-plugins.org v1.0.0 specification:

eidos plugin validate

Output:

              Agent Plugin Conformance (agent-plugins.org v1.0.0)               
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Property               ┃ Value                                               ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Plugin Name            │ eidos                                               │
│ Plugin Version         │ 0.8.0                                               │
│ Overall Status         │ CONFORMANT                                          │
│ Discovered Skills      │ eidos, eidos-ops, eidos-plan, eidos-spec            │
│ Configured MCP Servers │ None                                                │
│ Lifecycle Hooks        │ eidos-drift-gate                                    │
│ Client Extensions      │ com.google.antigravity                              │
└────────────────────────┴─────────────────────────────────────────────────────┘

[!NOTE] Under agent-plugins.org v1.0.0, MCP servers are strictly optional. Eidos plugins decommissioned local stdio MCP servers in favor of direct CLI execution with machine-readable --json output, providing superior reliability in cloud, sandbox, and container environments.

Uninstall / Clean Up¶

To cleanly remove plugin files and agent configurations:

eidos plugin uninstall all