Epic: Assimilate Aider into Ouroboros AgentOS while preserving the Aider UX

[shaun0927]

Summary

Assimilate Aider into the Ouroboros plugin ecosystem as a first-class AgentOS capability while preserving the Aider user experience as much as possible.

This epic extends the intent of #27: plugins are not merely command wrappers. They are the capability-assimilation layer that turns external tools and open-source workflows into permissioned, auditable, Seed-compatible, handoff-capable Ouroboros capabilities.

Aider is a strong candidate because it already behaves like an AI pair-programmer in the terminal:

• repo-grounded coding assistance,
• file selection and read-only context,
• code editing,
• architect / ask / code modes,
• repo map context,
• git integration,
• lint/test repair loops,
• model-provider configuration,
• optional web / browser / voice / GUI features,
• and a mature CLI-centered workflow.

The goal is not to hide Aider behind a thin subprocess("aider") wrapper. The goal is to let Ouroboros run Aider smoothly as an AgentOS-native capability while preserving the feel of using Aider directly.

Preserve Aider's user experience; assimilate Aider's authority, side effects, evidence, and lifecycle into Ouroboros.

---

AgentOS Thesis

Ouroboros should be able to execute powerful external agent tools without dissolving its OS boundary.

For Aider, the desired flow is:

Aider UX / command semantics / repo editing workflow
        ↓
Ouroboros plugin firewall and manifest contract
        ↓
permissions + capabilities + trust + audit
        ↓
Seed / Ledger / State / Provenance / Handoff artifacts
        ↓
Ouroboros AgentOS execution surface

This should make Aider feel native inside Ouroboros while keeping the external capability bounded, inspectable, resumable, and auditable.

In other words:

• Aider should remain recognizably Aider.
• Ouroboros should remain recognizably Ouroboros.
• The integration point is the plugin contract, not unbounded shell execution.

---

Why Aider Is a Good Capability-Assimilation Case

Aider is not a narrow SDK. It is a broad coding-agent surface with real authority over the local development environment.

Based on the Aider repository and docs:

• The Python package exposes the aider CLI via aider.main:main.
• It supports Python >=3.10,<3.15.
• It has a rich CLI configuration surface for models, providers, files, repo map, git behavior, lint/test behavior, terminal UX, and one-shot messages.
• It includes slash-command semantics such as ask/code/architect/context, commit, diff, lint, test, run, add/drop/read-only files, map, settings, load/save, editor, etc.
• It uses repo maps to provide codebase-wide context.
• It can edit files, run tests, run commands, commit changes, and interact with model-provider APIs.

That makes it an ideal reference for the hard case this repository must eventually support:

external AI coding agent
  + local filesystem authority
  + shell authority
  + network/model-provider authority
  + git authority
  + long-running user workflow
  + UX users already know
  → Ouroboros-native capability

If Ouroboros can assimilate Aider cleanly, it proves the plugin layer can handle serious real-world agent tools rather than only narrow API integrations.

---

Non-Goals

This epic should avoid the following outcomes:

• Do not add a bare manifest whose entrypoint is only aider with no policy, evidence, or handoff semantics.
• Do not treat this repository as a marketplace for Aider plugins.
• Do not fork Aider unless there is no viable adapter path.
• Do not depend on Aider internals as the first implementation strategy if the public CLI can satisfy the contract.
• Do not give Aider blanket destructive authority by default.
• Do not make ooo auto absorb Aider-specific branches.
• Do not require users to abandon familiar Aider workflows to use the integration.
• Do not store API keys, provider secrets, or raw sensitive environment values in audit artifacts.

---

Desired User Experience

The integration should preserve Aider's usage model while making Ouroboros the surrounding OS.

1. CLI-first experience

Users should be able to invoke Aider-like workflows through Ouroboros commands:

ooo aider ask --message "Explain how this module works" --file src/foo.py

ooo aider edit --message "Refactor this parser without changing behavior" --file src/parser.py --test-cmd "pytest tests/test_parser.py"

ooo aider architect --message "Design the migration path for this subsystem" --file src/service.py --read docs/architecture.md

ooo aider fix --test-cmd "pytest tests/test_regression.py" --file src/foo.py

These commands should feel close to Aider's own mental model:

• add files to context,
• mark read-only files,
• send a message,
• optionally run lint/test,
• inspect edits/diffs,
• continue from a generated handoff.

2. Familiar Aider concepts should remain visible

The plugin should preserve or translate these concepts:

• main model,
• weak model,
• editor model,
• reasoning effort / thinking-token style knobs where supported,
• edit format / architect mode,
• files to edit,
• read-only context files,
• repo map settings,
• lint command,
• test command,
• auto-lint / auto-test behavior,
• git commit behavior,
• chat/message mode,
• config/env behavior,
• model-provider API settings.

Where exact parity is unsafe or impractical, the plugin should document the difference and prefer a bounded AgentOS-native substitute.

3. Interactive experience should be preserved carefully

Aider's interactive terminal session is a major part of the product experience. The plugin should eventually support it, but not at the cost of bypassing the Ouroboros firewall.

Suggested staged target:

1. v0: one-shot, bounded commands with structured handoff artifacts.
2. v1: resumable session metadata and continuation commands.
3. v2: controlled interactive passthrough mode with explicit trust boundary, transcript capture, and post-session diff/handoff emission.

Interactive support should be treated as an AgentOS session, not as an opaque subprocess.

---

Proposed Plugin Package

Suggested name:

plugins/aider-assist/

Suggested command namespace:

aider

Suggested package layout:

plugins/aider-assist/
  ouroboros.plugin.json
  README.md
  aider_assist/
    __main__.py
    cli.py
    runner.py
    policy.py
    git_state.py
    artifacts.py
    handoff.py
    audit.py
    config.py
    tests/

The adapter should initially call the Aider CLI as a subprocess rather than importing unstable internal modules. Importing Aider internals can be evaluated later if the CLI cannot provide enough control.

---

Proposed Command Surface

ooo aider ask

Read-only repo-grounded question answering.

Example:

ooo aider ask --message "What owns retry behavior?" --file src/client.py --read docs/networking.md

Expected behavior:

• Invoke Aider in a no-edit path.
• Pass selected files/read-only context.
• Capture answer as an artifact.
• Emit provenance with Aider version, model settings, repo ref, and selected context.
• Require no filesystem write except Ouroboros artifact/state writes.

Risk:

read_only

Primary value:

• Proves Aider can be assimilated as an analysis capability before write authority is granted.

---

ooo aider edit

Bounded editing task.

Example:

ooo aider edit \
  --message "Simplify this function without changing behavior" \
  --file src/parser.py \
  --test-cmd "pytest tests/test_parser.py"

Expected behavior:

• Require at least one explicit editable file unless a future policy allows broader scope.
• Capture pre-run git state.
• Invoke Aider with bounded file arguments.
• Prefer --no-auto-commits by default so Ouroboros owns provenance.
• Capture post-run git state and diff.
• Capture touched files.
• Run optional verification command.
• Emit handoff artifact summarizing edits, evidence, tests, and next steps.

Risk:

write

Primary value:

• Proves Aider can perform real edits while Ouroboros retains audit, provenance, and continuation semantics.

---

ooo aider architect

Architecture/planning mode with optional implementation handoff.

Example:

ooo aider architect \
  --message "Design a migration from this adapter to the new plugin contract" \
  --file src/plugin_loader.py \
  --read docs/contract.md

Expected behavior:

• Preserve Aider's architect-style workflow as much as possible.
• Produce an architecture or change-plan artifact.
• Optionally hand off to ooo aider edit or a later ooo auto flow.
• Avoid uncontrolled edits unless explicitly enabled.

Risk:

read_only or write depending on selected mode

Primary value:

• Preserves one of Aider's key UX modes while allowing Ouroboros to decide whether planning and editing are separate lifecycle phases.

---

ooo aider fix

Test/lint repair loop.

Example:

ooo aider fix \
  --test-cmd "pytest tests/test_regression.py" \
  --file src/foo.py

Expected behavior:

• Capture failing command and output.
• Invoke Aider with the failure context.
• Apply bounded edits.
• Re-run the verification command.
• Emit structured success/failure/blocked artifact.

Risk:

write

Primary value:

• Connects Aider's repair loop to Ouroboros verification evidence.

---

Deferred: ooo aider session

Controlled interactive session mode.

Example target UX:

ooo aider session --file src/foo.py --read docs/spec.md

This should eventually preserve the direct Aider experience, but it must not bypass AgentOS requirements.

Minimum requirements before enabling:

• explicit trust boundary,
• transcript capture or summary artifact,
• pre/post git state capture,
• touched-file detection,
• final diff artifact,
• permission-use events,
• clear blocked/failed/completed status,
• no secret leakage in artifacts.

Risk:

write

Potentially destructive if shell/git behaviors are enabled broadly.

---

Draft Manifest Direction

A first implementation can start with a conservative manifest similar to:

{
  "schema_version": "0.1",
  "name": "aider-assist",
  "version": "0.1.0",
  "description": "Assimilates Aider as a bounded, auditable AI pair-programming capability for Ouroboros AgentOS.",
  "source": {
    "type": "local_path",
    "path": "plugins/aider-assist"
  },
  "commands": [
    {
      "namespace": "aider",
      "name": "ask",
      "summary": "Ask Aider about the repository without editing files.",
      "usage": "ooo aider ask --message <question> [--file path...] [--read path...]",
      "risk": "read_only",
      "requires_confirmation": false
    },
    {
      "namespace": "aider",
      "name": "edit",
      "summary": "Run a bounded Aider edit task and emit diff, verification, and handoff evidence.",
      "usage": "ooo aider edit --message <goal> --file path... [--test-cmd cmd]",
      "risk": "write",
      "requires_confirmation": true
    },
    {
      "namespace": "aider",
      "name": "architect",
      "summary": "Use Aider architect mode to produce a plan or bounded implementation handoff.",
      "usage": "ooo aider architect --message <goal> [--file path...] [--read path...]",
      "risk": "read_only",
      "requires_confirmation": false
    },
    {
      "namespace": "aider",
      "name": "fix",
      "summary": "Use Aider to repair a failing lint/test command within bounded files.",
      "usage": "ooo aider fix --test-cmd <cmd> --file path...",
      "risk": "write",
      "requires_confirmation": true
    }
  ],
  "capabilities": [
    {
      "name": "ledger",
      "access": "write",
      "reason": "Record task inputs, selected context, diffs, verification, and decisions."
    },
    {
      "name": "provenance",
      "access": "write",
      "reason": "Record Aider version, invocation arguments, model settings, repo ref, and produced artifacts."
    },
    {
      "name": "state",
      "access": "write",
      "reason": "Persist Aider run/session status for resumable workflows."
    },
    {
      "name": "handoff",
      "access": "attach",
      "reason": "Attach answer, diff, touched files, test output, and next-step guidance."
    },
    {
      "name": "progress",
      "access": "write",
      "reason": "Report long-running coding-agent progress."
    }
  ],
  "permissions": [
    {
      "scope": "filesystem:read",
      "risk": "read_only",
      "required": true,
      "reason": "Read selected repository files and context."
    },
    {
      "scope": "filesystem:write",
      "risk": "write",
      "required": false,
      "reason": "Apply bounded code edits for write-capable commands."
    },
    {
      "scope": "shell:execute",
      "risk": "write",
      "required": true,
      "reason": "Invoke the Aider CLI and optional verification commands."
    },
    {
      "scope": "network:write",
      "risk": "write",
      "required": true,
      "reason": "Call configured model-provider APIs through Aider."
    }
  ],
  "entrypoint": {
    "type": "command",
    "command": "python -m aider_assist"
  }
}

This is intentionally a starting point. Implementation may need additional argument metadata as the manifest schema evolves.

---

Permission and Trust Requirements

Aider has broad potential authority. The plugin must make that authority explicit.

Required or likely permissions

Permission	Risk	Notes
filesystem:read	read_only	Needed for repo context and selected files.
filesystem:write	write	Needed for edit/fix/session modes. Should not be required for ask-only usage.
shell:execute	write	Needed to invoke Aider and run lint/test commands. Needs careful policy.
network:write	write	Needed for model-provider API calls.
network:read	read_only	Needed only if web/URL scraping modes are enabled.
github:read / other VCS-host permissions	read_only or write	Only if future integration directly reads/writes GitHub metadata.

Trust policy

• ask should be available with read-only file context plus model-provider network permission.
• edit and fix should require explicit write trust.
• Commands that run arbitrary user-supplied shell commands should require confirmation and strong audit capture.
• Auto-commit should be disabled by default until commit provenance policy is explicitly designed.
• Destructive shell or git operations should not be enabled implicitly.

---

Artifact and Handoff Contract

Each invocation should produce an Ouroboros-readable artifact.

Suggested artifact location pattern:

.omx/artifacts/plugins/aider-assist/<run-id>/
  invocation.json
  stdout.txt
  stderr.txt
  answer.md
  diff.patch
  touched-files.txt
  verification.json
  handoff.md

Suggested handoff contents:

# Aider Assist Handoff

## Command
## User Goal
## Repo State Before
## Repo State After
## Selected Editable Files
## Selected Read-only Context
## Aider Version
## Model / Provider Metadata
## Permissions Used
## Summary of Result
## Diff Summary
## Verification
## Known Gaps
## Recommended Next Step

The handoff should be consumable by:

• a human developer,
• ooo auto,
• a future workflow harness,
• or a plugin verification command.

---

Implementation Plan

Phase 0: RFC / design lock

• Decide whether aider-assist belongs in this repository as a reference plugin or in a separate experimental plugin repository.
• Define what UX parity means for v0, v1, and v2.
• Decide the first supported Aider installation strategy: existing aider on PATH vs Python dependency vs uvx aider-chat.
• Decide how model-provider secrets are supplied without leaking into audit artifacts.

Phase 1: Read-only POC

• Add plugins/aider-assist/ouroboros.plugin.json with ask only or ask + future command declarations.
• Implement python -m aider_assist ask.
• Detect Aider availability and version.
• Accept --message, --file, and --read arguments.
• Invoke Aider in a no-edit / answer-producing mode.
• Capture stdout/stderr/exit status.
• Emit invocation/provenance/handoff artifacts.
• Validate the manifest with scripts/validate_contract.py.

Phase 2: Bounded write mode

• Implement edit with explicit --file allowlist.
• Capture pre-run git state and dirty diff.
• Invoke Aider with bounded files and --message.
• Default to no auto-commit.
• Capture post-run diff and touched files.
• Emit structured handoff.
• Add tests for policy refusal when no editable files are supplied.
• Add tests for artifact creation.

Phase 3: Verification integration

• Add --test-cmd and/or --lint-cmd support.
• Capture command output and exit code.
• Re-run verification after Aider edits.
• Represent success, failure, and blocked states clearly.
• Attach verification to handoff artifacts.

Phase 4: Architect mode

• Preserve Aider's architect mode as a planning/handoff command.
• Decide whether architect mode is read-only by default.
• Support explicit promotion from architect plan to edit command.

Phase 5: Session parity

• Design controlled interactive passthrough.
• Capture transcript or summary without leaking secrets.
• Capture pre/post state and final diff.
• Emit post-session handoff.
• Decide which Aider slash commands are allowed, blocked, or require confirmation inside AgentOS session mode.

---

UX Parity Checklist

This epic should be considered successful only if the integration preserves the core Aider experience in an Ouroboros-safe way.

• Users can select editable files.
• Users can select read-only context files.
• Users can send one-shot messages.
• Users can ask repo-grounded questions without edits.
• Users can request bounded code edits.
• Users can run test/lint repair loops.
• Users can inspect diffs.
• Users can preserve Aider-like model configuration.
• Users can preserve Aider-like architect/planning flow.
• Users can continue from generated handoff artifacts.
• Users can understand what permissions were used.
• Users can see what files were touched.
• Users can see what verification ran.
• Users can use the integration without thinking of it as a degraded wrapper.

---

Safety and Policy Checklist

• No API key values are written to artifacts, logs, audit events, or handoffs.
• Write-capable commands require explicit file bounds or an intentionally designed broader-scope policy.
• Shell commands are captured and classified.
• Auto-commit is off by default unless explicitly enabled by policy.
• Interactive mode is deferred until transcript/diff/handoff semantics are designed.
• Network access is declared and justified.
• Filesystem write permission is optional for read-only commands.
• Plugin failure does not pretend success.
• Partial results are represented as partial/blocked with evidence.
• Destructive behavior is not implicitly trusted.

---

Acceptance Criteria

This epic is complete when:

• A design document or README explains how Aider is assimilated as an Ouroboros AgentOS capability.
• The integration explicitly references and conforms to SSOT: UserLevel plugin authoring and capability assimilation #27's capability-assimilation thesis.
• A valid aider-assist plugin manifest exists or a separate plugin repository is linked.
• At least one read-only Aider workflow runs through the Ouroboros plugin contract.
• At least one bounded write workflow runs through the Ouroboros plugin contract.
• Invocation artifacts include input, command, selected files, Aider version, model metadata where safe, exit status, and handoff.
• Write workflows capture pre/post git state and diff.
• Verification output is captured when --test-cmd or --lint-cmd is supplied.
• The plugin declares capabilities and permissions narrowly enough for trust UX to make sense.
• The plugin does not leak provider secrets.
• The integration preserves the recognizable Aider user experience for the supported command subset.
• Deferred UX gaps, especially full interactive session support, are documented with a staged plan.

---

Open Questions

1. Should aider-assist live in this repository as a reference plugin, or should this repo host only the contract/RFC while the implementation lives in a dedicated third-party plugin repository?
2. Should v0 require aider to already be installed on PATH, use uvx aider-chat, or vendor a Python dependency path?
3. How should Ouroboros expose Aider model/provider configuration while preserving secret hygiene?
4. Should architect mode be read-only by default, or should it mirror Aider's native architect edit flow more closely?
5. What is the minimum acceptable transcript capture for future interactive session mode?
6. Should Aider's auto-commit feature remain disabled by default so Ouroboros owns provenance?
7. How much of Aider's slash-command surface should be allowed in controlled session mode?

---

References

• Related SSOT issue: SSOT: UserLevel plugin authoring and capability assimilation #27
• Aider repository: https://github.com/aider-ai/aider
• Aider usage documentation: https://aider.chat/docs/usage.html
• Aider repo map documentation: https://aider.chat/docs/repomap.html
• Aider lint/test documentation: https://aider.chat/docs/usage/lint-test.html
• Ouroboros plugin contract: docs/contract.md
• Ouroboros plugin lifecycle: docs/lifecycle.md
• Ouroboros plugin permissions: docs/permissions.md
• Ouroboros plugin audit model: docs/audit.md