williamzujkowski/nexus-agents

> Autonomic control plane for AI coding agents — one entry point, adversarial review, tamper-evident hash-chained audit, human-gated closed-loop tuning (autonomous demotion, earned promotion)
---
Why Nexus Agents?
**Nexus-agents is an autonomic control plane for your AI coding agents** — Claude Code, Codex, Gemini, and OpenCode. The agents are the _data plane_: they do the engineering. Nexus-agents is the _control plane_: it admits work through one entry point, reviews it adversarially before it ships, records every action in a tamper-evident event log, and closes the loop by tuning where the next task goes based on what actually worked.
Borrowing the vocabulary of autonomic computing: the system runs a **MAPE-K** loop — Monitor, Analyze, Plan, Execute over a shared Knowledge base — so that operating your agent fleet is, as much as the evidence allows, self-managing rather than hand-driven.
The control-plane mapping
Each classic control-plane role maps to a shipped nexus-agents component — the metaphor is load-bearing, not decoration:
| Control-plane role | nexus-agents component | What it does |
| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------- |
| Scheduler | run / MetaOrchestrator | One entry point picks (and optionally runs) the right strategy for a goal |
| Admission control | gates (pr_review, consensus_vote, run_quality_gate) | Adversarial review and quality gates decide what is allowed to ship |
| Event log | AuditTrail hash chain + verify_audit_chain | Append-only, tamper-evident record of every decision |
| Data plane | engineering CLIs | Claude Code, Codex, Gemini, OpenCode do the file edits, tests, PRs |
The MAPE-K loop
Self-\* capabilities
Autonomic systems are described by their **self-\*** properties. Each row below maps to a loop that **exists in the codebase today** — nothing here is aspirational, and the authority each loop carries is bounded by ADR-0017's authority ladder (observe → suggest → advisory → enforce):
| Self-\* property | What it means here | Implementing loop (shipped) |
| ---------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Self-configuring | Detects environment and wires itself in | nexus-agents setup / doctor (cli-commands.ts) — detects CLIs, writes MCP config, reports health |
| Self-healing | Routes around failing dependencies automatically | Adapter circuit-breaker + swarm-health demotion (cli-adapters/circuit-breaker.ts); a capped, auto-decaying, demotion-only TuneAdjustmentStore adjustment |
| Self-optimizing | Learns where the next task should go | Closed-loop OutcomeStore → LinUCB + TOPSIS scoring in the CompositeRouter |
| Self-protecting | Constrains what untrusted input and tools can do | Trust-tiered input handling, PolicyFirewall secret-path denylist (secret-paths), Docker/policy sandboxing (security/) |
> **Honesty note:** these loops sit at different rungs of the authority ladder. The self-tuning demotion is enforce but bounded (capped, auto-decaying, demotion-only); learned selection and other promotions are still **earned** per-loop against an evidence threshold plus ratification, not flipped on by default. See ADR-0017.
**What it gives you:**
- **Adversarial PR review** — pr_review runs 5 voter roles (architect, security, devex, catfish, scope_steward) with a 4-point verification gate. On the v5 evaluation set: 100% bug-catch on a focused synthetic dataset (n=10) and a 50% raw false-positive rate; manual triage reclassified one of two inspected FP cases as a real finding the dataset had mislabeled. These are directional small-n figures, not measured rates. Full numbers and guardrails: docs/research/pr-review-experiment-results-v5.md
- **Drift-detected charter** — CLAUDE.md + governance:check + blocking CI gates fail the build when documented rules drift from registered behavior (model registry, MCP tools, expert types, skills)
- **Tamper-evident audit trail** — every tool call, every voter decision, every routing choice flows through AuditTrail with structured logging and hash-chained append-only storage; integrity is verifiable via the verify_audit_chain MCP tool (tamper-evident, not tamper-proof — see the audit hash-chain threat model)