Nexus Agents Documentation

Canonical Documentation Index | Last Updated: 2026-04-17 (18 skills, 30 MCP tools, 11 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.

Quick Start by Role

RoleStart HereThen Read
New UserQuick StartInstallation
ContributorContributingDevelopment Guide
OperatorENTRYPOINTS.mdConfiguration
Agent (Claude)CLAUDE.mdThis index

Documentation Structure

docs/
├── README.md              # THIS FILE - Canonical index
├── INDEX.yaml             # Machine-parseable index
│
├── getting-started/       # Installation and configuration
├── architecture/          # System design documentation
├── development/           # Contributor guides
├── research/              # Research tracking
├── adr/                   # Architecture Decision Records
├── guides/                # How-to guides
├── interfaces/            # Interface specifications
├── proposals/             # Design proposals
├── plans/                 # Implementation plans
├── metrics/               # System metrics
└── workflows/             # Workflow documentation

Canonical Documentation

Tier 1: Essential (Always Current)

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

DocumentLocationDescription
Project InstructionsCLAUDE.mdAgent behavior, protocols, governance
Quick StartQUICK_START.md5-minute getting started
READMEREADME.mdProject overview
Architecture Overviewarchitecture/README.mdSystem design hub
Development Guidedevelopment/README.mdContributor hub
API ReferenceENTRYPOINTS.mdCLI, MCP, REST, API docs
TroubleshootingTROUBLESHOOTING.mdCommon issues, FAQ

Tier 2: Reference (Regularly Updated)

Detailed technical documentation:

Getting Started

DocumentDescriptionStatus
INSTALLATION.mdPlatform installation guideCanonical
CONFIGURATION.mdYAML and env configurationCanonical
PLUGIN_INSTALL.mdInstall nexus-agents as a Claude Code pluginCanonical
SANDBOXED-USAGE.mdDocker / restricted-FS / team-distribution flowsCanonical

Architecture

DocumentDescriptionStatus
AGENT_SYSTEM.mdAgent framework designCanonical
MEMORY_SYSTEM.md7-type memory architectureCanonical
ROUTING_SYSTEM.mdModel routing pipelineCanonical
RESEARCH_PIPELINE.mdResearch-to-project runnerCanonical
CONSENSUS_PROTOCOLS.md5 consensus algorithmsCanonical
CONTEXT_LOAD_BALANCING.mdClaude/Gemini/Codex routingCanonical
SECURITY.mdSecurity model, sandboxingCanonical
MCP_PROTOCOL.mdMCP integration detailsCanonical
ORCHESTRATOR_WORKFLOW_ENGINE.mdOrchestrator vs WorkflowEngineCanonical
ICTM_PATTERN.mdDynamic sub-agent creationCanonical
UNTRUSTED_INPUT_HARDENING.mdInput trust & sanitizationCanonical
SOFTWARE_FACTORY_REPORT.mdFactory hardening reviewCanonical
MULTI_REPO_ORCHESTRATION.mdCross-repo task coordinationCanonical
dependency-graph.mdModule dependency diagramGenerated
REGISTRY_COVERAGE.mdWiring-completeness CI gateCanonical
SCHEMA_FANOUT_COVERAGE.mdSchema-fan-out CI checkCanonical
IMPORT_GRAPH_ORPHANS.mdImport-graph orphan detectionCanonical
AGENT_COMPATIBILITY.mdPer-harness federation matrixCanonical

Development

DocumentDescriptionStatus
AGENT_DEVELOPMENT.mdBuilding new agentsCanonical
TOOL_DEVELOPMENT.mdAdding MCP toolsCanonical
MEMORY_DEVELOPMENT.mdMemory system extensionsCanonical
CLI_DELEGATION_GUIDE.mdCLI adapter patternsCanonical
CONTRIBUTION_GUIDE.mdPR workflow, git conventionsCanonical
SHELL_TESTING_ANTI_PATTERNS.mdShell testing pitfalls to avoidCanonical
CLI_UX_QUALITY_GATE.mdCLI UX pre-release checklistCanonical

Research

DocumentDescriptionStatus
RESEARCH_INDEX.mdResearch tracking hubCanonical
CONTRIBUTING.mdAdding researchCanonical
registry/papers.yamlPaper metadataCanonical
registry/techniques.yamlImplementation statusCanonical
cli-first-adapter-strategy.mdCLI-first adapter researchCanonical
pr-review-experiment-results.mdpr_review #2233 baseline experiment resultsCanonical
pr-review-experiment-results-v5.mdpr_review v5 — JSON-native findings; 100% bug-catch + caught a real bugCanonical
mcp-tool-distinctness-v1.mdMCP tool-description pairwise similarity report (#2650)Canonical
fitness-stratified-v1.mdStratified runtime-outcome report — per adapter / task-type / role (#2662)Canonical
fork-session-spike.mdSpike: fork_session / branch-comparison on the graph builder (#2665)Canonical

Tier 3: Supporting (Reference as Needed)

Architecture Decision Records (ADRs)

ADRTitleStatus
0001ADR TemplateTemplate
0002Orchestrator InterfaceAccepted
0003Quorum ValidatorAccepted
0004SharedTaskAnalyzerAccepted
0005Router ConsolidationAccepted
0006Determinism ProvidersAccepted
0007Utility ConsolidationAccepted
0008Routing StorageAccepted
0009Error Class HierarchyAccepted
0010Memory Helpers SeparationSuperseded
0011Orchestrator Interface DeferSuperseded
0012Registry API UnificationAccepted
0013Memory Helpers ConsolidationAccepted
0014Orchestrator Interface UnificationAccepted
0015Multi-Repo OrchestrationProposed
0016Multi-Round Consensus VotingAccepted

Guides

DocumentDescription
MCP_INTEGRATION.mdMCP server configuration
WORKFLOW_TEMPLATES.mdCreating YAML workflows
CUSTOM_ENDPOINT_SETUP.mdCustom OpenAI-compatible gateway (direct SDK + OpenCode paths)
CLOUD_PROVIDERS.mdBedrock/Vertex/Azure via OpenRouter / LiteLLM / custom-gateway
PR_REVIEW_LOCAL.mdRun pr_review on your machine using subscription CLI auth
HARNESS_COMPATIBILITY.mdWire nexus-agents from OpenCode/Codex/Cursor/Aider/Cline
RULE_PRECEDENCE.mdPer-adapter rule-loading precedence (Claude/Codex/Gemini/OpenCode)
DEBUGGING_OBSERVABILITY.mdDebug logging, tracing
Claude Code ObservabilityHooks, status line, MCP logging for Claude Code

Reference

DocumentDescriptionStatus
capabilities.mdCLI/MCP/Workflow capability indexGenerated
skills-index.mdLLM context loading indexCanonical

Operational Docs

DocumentDescriptionStatus
docops-spec.mdCanonical DocOps pipeline specCanonical
docops-manifest.jsonDocOps enforcement manifestCanonical
docs-inventory.mdDocumentation inventoryCanonical
release-changeset-race.mdPublish-race runbook (#2382)Canonical

Interfaces

DocumentDescription
README.mdInterface documentation hub
agent.mdAgent interface spec
model-adapter.mdModel adapter spec
orchestrator.mdOrchestrator interface spec
tool.mdTool interface spec
workflow-engine.mdWorkflow engine spec

Plans

No active plan documents. Historical plans have been archived.

Design Documents

DocumentDescriptionStatus
as-is.mdCurrent system state assessmentArchived
v2-proposal.mdV2 pipeline OS architectureArchived
components.mdComponent inventoryCanonical
interfaces.mdKey interfaces and contractsCanonical
flows.mdDataflow tracesCanonical
gaps.mdIntended vs actual gapsArchived
ARCHITECTURE_MAP.jsonMachine-readable component mapGenerated
scaling-coordination-predictor.mdScaling designCanonical
EXECUTION_DASHBOARD_DESIGN.mdDashboard designCanonical
SWARM_OBSERVER_DESIGN.mdOrchestrationObserver designCanonical
SWE_BENCH_HARNESS.mdSWE-Bench integrationCanonical

V2 Rearchitecture (Pipeline OS)

DocumentDescriptionStatus
04-v2-architecture-pipeline-os.mdFinal V2 specificationApproved
00-executive-summary.mdExecutive summaryApproved
01-as-is-architecture.mdCurrent architecture analysisApproved
02-system-goals-non-goals.mdGoals and non-goalsApproved
03-user-story-user-journey.mdUser stories and journeysApproved
05-plugin-system-spec.mdPlugin system specificationApproved
06-graph-execution-model.mdGraph execution modelApproved
07-policy-governance-gates.mdPolicy engine and governance gatesApproved
08-observability-eventing.mdEvent bus and observabilityApproved
09-context-store-turn-dag-option.mdContext store optionsApproved
10-migration-plan-v1-to-v2.mdMigration planApproved
api-contracts.mdTypeScript API contractsApproved
threat-model.mdV2 threat modelApproved
epics-and-issues.mdWork breakdown with acceptance criteriaApproved
ADR-0001Pipeline OS as orchestration primitiveProposed
ADR-0002Unified TaskContract + PlanContractProposed
ADR-0003Extend GraphBuilder (LangGraph-aligned)Proposed
ADR-0004Structural plugin flagsProposed
ADR-0005Unified adapter boundaryProposed
ADR-0006Observability as first-classProposed

Proposals

DocumentDescriptionStatus
cli-pr-review-workflow.mdPR review workflowArchived

Workflows

DocumentDescription
SELF_DEVELOPMENT_WORKFLOW.mdHistorical pointer — engine deleted in #2402, see epic notes

Operational

DocumentDescription
ALIGNMENT_ROADMAP.mdStrategic alignment, north star, gaps
archive/system-reviews-2026-01.mdHistorical system review transcripts
SECRETS_SETUP.mdSecrets configuration
security/API_KEY_BOUNDARIES.mdAPI key boundary documentation
system-map.mdSystem component map
deprecation-pipeline.mdDeprecation tracking & v3.0 migration guide
redundancy-analysis.mdCode redundancy analysis
invocation-matrix.mdComponent invocation map
distribution/LISTING_SUBMISSIONS.mdMCP registry & directory submission tracker
distribution/PUBLISHING_GUIDE.mdStep-by-step publishing commands

Root-Level Documents

Documents at repository root (for discoverability):

DocumentDescriptionCanonical Location
CLAUDE.mdAgent instructionsRoot (canonical)
README.mdProject overviewRoot (canonical)
QUICK_START.mdGetting startedRoot (canonical)
CONTRIBUTING.mdContribution guideRoot (canonical)
CODING_STANDARDS.mdCode standardsRoot (canonical)
ARCHITECTURE.mdArchitecture summaryRoot (canonical)
SECURITY.mdSecurity policyRoot (canonical)
CHANGELOG.mdVersion historyRoot (canonical)

Deprecated / Historical

Documents kept for historical reference only:

DocumentReasonReplacement
archive/REVIEW_2026-01-23.mdArchived system reviewCurrent system reviews
archive/SECURITY_AUDIT_2026-01-23.mdArchived security auditCurrent security docs
archive/consensus-vote-2026-01-17.mdArchived consensus voteCurrent consensus protocols

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

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)

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.