<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/eeco_logo_dark.png">
    <img src="assets/eeco_logo_light.png" alt="eeco" width="280">
  </picture>

<h1>Vision</h1>

<p><i>The AI-agnostic ecosystem for autonomous project housekeeping.</i></p>

<p>
    <a href="README.md"><b>README</b></a> ·
    <b>Vision</b> ·
    <a href="docs/COCKPIT.md"><b>Cockpit</b></a> ·
    <a href="docs/USAGE.md"><b>Usage</b></a> ·
    <a href="docs/ARCHITECTURE.md"><b>Architecture</b></a> ·
    <a href="docs/PUBLIC_API.md"><b>Public API</b></a> ·
    <a href="EXTENDING.md"><b>Extending</b></a> ·
    <a href="CONTRIBUTING.md"><b>Contributing</b></a> ·
    <a href="docs/UPGRADING.md"><b>Upgrading</b></a> ·
    <a href="VERSIONING.md"><b>Versioning</b></a> ·
    <a href="CHANGELOG.md"><b>Changelog</b></a> ·
    <a href="SECURITY.md"><b>Security</b></a>
  </p>

</div>

---

eeco is the AI-agnostic ecosystem for autonomous project housekeeping
— an intelligent, system-level framework that sits as a meta-layer
above modern software development. Its purpose is to radically
automate project housekeeping so developers can focus entirely on
creative implementation and problem-solving.

This document states where eeco is headed. The README and USAGE
describe what it does today.

## The vision

eeco is not a reactive tool — it is a proactive background process
that continuously analyses, understands, and actively maintains a
project. Through pattern recognition, eeco identifies recurring
development and maintenance patterns and derives workflows from
them automatically — proactively, or on explicit user request.

## Core concepts

### Model-agnostic interoperability — the context compiler

eeco is a universal abstraction layer. It ensures that every AI —
from specialised small models to high-end LLMs like Gemini, Claude,
or GPT — receives exactly the project context it needs. eeco acts
as a **context compiler** that translates complex project
documentation into a form any AI can process, in a standardised
shape.

### Autonomous housekeeping

With built-in standard workflows — a bug finder for error analysis,
a hygiene keeper for code-standards enforcement, drift detectors
across memory and docs — eeco takes the administrative load. The
system learns from the developer workflow and evolves through
AI-assisted self-optimisation.

### Intelligent context steering — AI guardrails

eeco is a **guardrail** for AI agents. It delivers cross-model
binding rules — language policies, attribution rules, project
conventions — that minimise hallucinations and keep project
quality consistent without the user repeating explicit
instructions on every call.

## The goal

eeco aims to become the standard for AI-assisted project steering:
the interface where human software architecture and AI-driven
implementation meet. Through the handshake between eeco and any
AI model, a seamless environment emerges in which the AI acts not
just as a code generator, but as part of a self-organising,
highly efficient development system.

## Operating principles

The vision above is the destination. These principles hold on the
way there and are never traded away:

- **Human-in-the-loop.** eeco proposes; the operator decides. It
  never commits to, pushes, or activates a workflow on your project's
  tracked tree without explicit consent.
- **Init exception.** `eeco init` is the single verb permitted to make
  one initial commit and one initial push to the HOST repo, both
  restricted to the `.gitignore` line that scopes eeco's workspace out
  of the tracked tree — plus the private workspace-history repo described
  below, which is local-only and confined to the gitignored workspace.
  Every other verb — `run`, `gc`, `hooks`, `gates`, `add`, etc. —
  continues to never commit to or push the tracked tree, and never write
  outside the workspace.
- **Workspace history (the AI's logbook).** eeco may keep a private,
  **local** git repository inside its own gitignored workspace directory
  (`<username>/`) to version its knowledge layer — memory, queue,
  decisions, manifests — over time. This repository **never leaves the
  machine** (no remote, no push by default) and **never touches the host
  project's tracked tree**: it records only what eeco already writes
  inside its own gitignored workspace. It is created opt-out at `eeco
  init` (`workspace_history`: `manual` by default, `auto` to commit on
  every change, `off` to disable) and removed at `eeco uninstall`. Inside
  this private repo eeco has a free hand — commit, squash, gc — because
  nothing there is shared or tracked by the host; every other verb still
  never commits to the tracked tree, pushes, or writes outside the
  workspace.
- **Opt-in AI spend.** Every AI call is consent-gated and
  budget-capped. The default automation level is manual.
- **Local-first and private.** eeco reads anywhere in the repo,
  writes only inside its gitignored workspace. No telemetry, no
  hosted service.
- **Reversible.** Every escape from the workspace — the pre-commit
  hook, the session-start integration, the commit-msg hook, the
  commit-guard PreToolUse hook — is opt-in, ledgered, and removable
  byte-for-byte.

## Non-goals

- Not a CI service, not a hosted product — it runs on your machine.
- Not tied to one AI vendor — the knowledge layer is
  provider-agnostic.
- Not a replacement for operator judgment — eeco surfaces and
  proposes; the operator approves.

## Roadmap

eeco follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
over the frozen surface in [`docs/PUBLIC_API.md`](docs/PUBLIC_API.md).
The next stretch deepens the context compiler and grows the
autonomous-housekeeping workflows. See [`CHANGELOG.md`](CHANGELOG.md)
for what has shipped.

## See also

- [README.md](README.md) — quick start and install
- [docs/USAGE.md](docs/USAGE.md) — full user reference
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — architecture overview

---

[← Prev: README](README.md) · [Next: Cockpit →](docs/COCKPIT.md)