Nexus Agents Documentation

Canonical Documentation Index | Last Updated: 2026-06-17 (the skills under skills/, 47 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)
├── 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
└── 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 / PolicyFirewall / 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

There is no separate machine index. docs/INDEX.yaml was retired in #4810: it covered 17 of 208 documents (~8%), carried a Generated: header for a generator that was never built, and was skiplisted out of the Canonical Index Check that gates this file. An 8% index offered for programmatic access is worse than none, because the gap is invisible to the caller.

This README is the canonical index and is gated for completeness. For structured access, parse it, or use artifacts/repo-index.json for the code graph.

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
• docs/api/ - Generated TypeDoc API reference (gitignored; produced by the website prebuild, rendered at /api/)

Why three API pages are nested and sixteen are not

docs/api/ holds sixteen flat pages plus docs/api/exports/{pipeline,benchmarks,agents-ictm}.md. That asymmetry looks like an oversight and is not. Those three are the aggregate src/exports/* barrels; each carries a slash-bearing @module exports/<name> tag, and TypeDoc’s outputFileStrategy: "modules" derives the output path from the module name. The other sixteen carry no tag and fall back to the filename.

A 7-voter higher_order panel on #4523 resolved to leave it that way: /api/exports/pipeline and its two siblings are published URLs, and a published URL is a stable interface. Symmetry for its own sake is not worth breaking three live links.

Do not de-slash those @module tags. scripts/check-typedoc-layout.ts runs in the typedoc-check job of .github/workflows/docs-check.yml, immediately after generation, and fails if any page moves in either direction — so this is enforced, not merely asserted. If you genuinely intend to move a page, change NESTED_MODULES in that script in the same commit and say why.

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