Nexus Agents Documentation

Canonical Documentation Index | Last Updated: 2026-06-17 (the skills under skills/, 46 MCP tools, 12 expert types, 11 workflow templates)

This is the single source of truth for all nexus-agents documentation. All documentation must be indexed here to be considered valid.

Nexus-agents is an autonomic control plane for AI coding agents. This index is organized around that model: docs are grouped by the control-plane role they describe — scheduler, admission control, event log, data plane — and by the MAPE-K self-* loop they implement, rather than as a flat catalog. If you know which part of the control plane you care about, you can find its docs directly. See the root README for the framing and ADR-0017 for the authority model the loops are bounded by.

Quick Start by Role

AI agents working in this repo (Claude Code, Cursor, etc.) — see CLAUDE.md for project instructions, governance protocols, and canonical paths. CLAUDE.md is the rule book the agents follow, not a user-facing surface.

The Control-Plane Map

The docs below are grouped by where they sit in the control plane. Each classic control-plane role maps to a shipped component (see the root README’s control-plane mapping); the docs that describe each role are gathered under it.

Pipeline Terminology

The word “pipeline” gets used for several distinct things. This table disambiguates the namespace — read it once and the rest of the docs are unambiguous:

Mental model: a dev pipeline and workflow templates are pre-built pipelines you run; composition is how you build a new one from the research loop, consensus loop, and graph primitives. When a doc says “the full pipeline” (e.g. in CLAUDE.md’s working mode) it means the agent’s research→vote→plan→implement decision sequence — the same shape as the dev pipeline, applied to its own work.

Documentation Structure

docs/
├── README.md              # THIS FILE - Canonical index (control-plane organized)
├── INDEX.yaml             # Machine-parseable index
│
├── getting-started/       # Entry point: installation and configuration
├── architecture/          # System design — scheduler, gates, event log, data plane
├── development/           # Build & operate: contributor guides
├── governance/            # Authority ladder, loop promotion criteria
├── security/              # Self-protecting: trust tiers, audit threat model
├── research/              # Research loop tracking
├── adr/                   # Architecture Decision Records
├── guides/                # How-to guides
├── interfaces/            # Interface specifications
├── ops/                   # Operational runbooks
├── reference/             # Generated CLI/MCP/strategy references
├── metrics/               # System metrics
└── workflows/             # Workflow documentation

Tier 1: Essential (Always Current)

These documents define the system and must be kept up-to-date:

Entry Point — Getting In

One door in: install, verify, run your first task, then learn the full surface (CLI / MCP / REST). This is the run scheduler’s front door.

Scheduler — Routing & Orchestration

The scheduler is run / MetaOrchestrator: one entry point picks (and optionally runs) the right strategy for a goal. These docs describe how strategies are selected, routed across CLIs, and composed into pipelines.

How-to (composing & routing):

Admission Control — Gates

Nothing ships without passing a gate. Adversarial PR review, multi-voter consensus, and quality gates decide what is allowed through. These are the loops that sit at advisory/enforce on the authority ladder.

How-to (running gates):

Evidence (gate evaluations):

Event Log — Audit & Observability

Append-only, tamper-evident record of every decision, plus the observability surfaces that monitor the running system (the Monitor arm of MAPE-K).

How-to (observability):

Observability design:

Data Plane — Agents & Execution

The data plane is the engineering CLIs (Claude Code, Codex, Gemini, OpenCode) that do the actual file edits, tests, and PRs — and the harness/federation machinery that wires nexus-agents to them.

How-to (wiring agents & providers):

Self-* Loops (MAPE-K)

The autonomic loops. Each maps to a shipped mechanism and sits at a declared rung of the authority ladder (ADR-0017): self-configuring (setup/doctor), self-healing (circuit-breaker demotion), self-optimizing (LinUCB/TOPSIS), self-protecting (trust tiers / ClawGuard / sandbox).

Self-configuring & self-optimizing

Self-protecting (security)

Note: rows in the self-* loops are not equally autonomous. Where each loop sits on the ladder (observe → suggest → advisory → enforce) and how it earns promotion is governed by ADR-0017 and the loop promotion criteria under § Governance.

Governance & Authority

The rules that bound the loops: the authority ladder, claims-drift detection, and the runbooks that keep capability changes ratified and audited rather than autonomous.

Build & Operate

For contributors building on the control plane and operators running it.

Development (contributor guides)

Operations & runbooks

CI gates & coverage

Distribution

Reference & History

Interface specs, generated references, the research loop’s catalog, ADRs, and historical/archived material.

Interfaces

Generated references

Owned by the docs-site single-sourcing epics (#3532/#3688/#3763): these pages are emitted by their generators and live where the generators write them. This IA pass indexes them but does not own their bodies.

System maps & design

Research loop

Strategy & alignment

Maintainer reference (ADRs, V2 architecture, design proposals)

Workflows

Deprecated / Historical

Documents kept for historical reference only:

Previously Archived/Removed:

• PROJECT_PLAN.md, plan docs — archived/removed
• RESEARCH_SUMMARY.md — content in research/topics/agent-skills/
• SECURITY_AUDIT_2026-01-23.md — moved to archive/
• Proposal docs (implemented) — removed after completion

Root-Level Documents

Documents at repository root (for discoverability):

Machine-Parseable Index

For programmatic access, see INDEX.yaml.

Governance Rules

1. Canonical Index: This file is the single documentation entry point
2. Indexing Required: New documentation must be added to this index
3. No Parallel Indexes: This is the only documentation index permitted
4. Update on Change: Update this index when any documentation changes
5. Classification Required: All docs must have a classification (Canonical/Supporting/Deprecated)

Non-conflict with the docs-site epic (#3532)

This IA pass owns the narrative-doc grouping in this index — the control-plane sections above. It does not own the generated API/MCP/strategy reference pages (see § Generated references), which are emitted by the docs-site single-sourcing generators (#3532/#3688/#3763) and live where those generators write them. The two are coordinated: this index links the generated pages by their canonical generator-emitted paths; the generators are free to regenerate those bodies without touching this index’s structure.

Files Not Indexed (Intentionally Excluded)

The following are excluded from this index:

• .rules/ - Agent-specific configuration (loaded automatically)
• .claude/skills/ - Agent skill definitions (loaded automatically)
• coverage/ - Test coverage reports (generated)
• node_modules/ - Dependencies
• packages/nexus-agents/docs/api/ - Generated TypeDoc output

This index follows the documentation governance defined in CLAUDE.md.