Nexus

A systems design engine for agentic work.

What Nexus does

Nexus translates human expert systems into agentic systems. Given a domain (software engineering, ERP implementation, legal practice, medical-device regulatory, whatever work humans do for a living), Nexus:

1. Researches how humans produce the work output — roles, workflows, tools, techniques, know-how, tacit expertise
2. Decomposes the work into components that can be assigned to specialized agents
3. Designs the agentic system — agent roster, skill set, collaboration architecture, information flow, decision rights, HITL boundaries
4. Constructs the harness that produces the work output — a directory-based system deployable in Claude Code

The output of a Nexus build is a harness. A harness is an operating system for producing a particular kind of work output. Examples: SDLC harness (produces software engineering engagements); BC Oil & Gas harness (produces Business Central implementations for upstream operators); a future medical-device-regulatory harness would produce FDA submission packages.

Why Nexus exists

Without Nexus, every new agentic system is built ad hoc. Patterns that work in one domain have to be rediscovered in another. Core infrastructure (state, routing, coordination, contract discipline, memory) gets reinvented badly. Research about how humans actually do work is done once, forgotten, redone.

With Nexus:

• Core operational primitives are universal and proven — transplanted into every harness
• Systems-design methodology is articulated and reusable
• Research compounds across builds — the second harness benefits from the first
• Reuse is earned (second-observation rule) not assumed
• Produced harnesses can be re-provisioned when core improves

How to use Nexus

First boot

cd D:\nexus
claude

Nexus reports state and available commands. Start with start a new build.

Running a build

Tell the build-orchestrator what you want to build:

Start a new build for Business Central oil & gas upstream. The harness should produce implementations for operators running in multiple countries, handling both operator and non-operator roles, with multi-currency support and AppSource-publishable extensions.

Build-orchestrator runs the seven-phase build process:

1. INTAKE — structured narrowing intake (progressive; the taxonomy drives questions; operator confirms the build brief)
2. SCOUT — registries queried for reuse; reuse-vs-construct split proposed; operator confirmation
3. RESEARCH — authoritative research fills gaps (domain-researcher + work-ethnographer + reference-librarian)
4. DESIGN — systems-architect composes the harness architecture; agent-designer + skill-designer + workflow-designer produce domain layer
5. CONSTRUCT — harness-assembler writes files; contract-shaper authors contract templates
6. VALIDATE — harness-auditor runs six-category gate; smoke-tester dry-boots the harness
7. DELIVER — harness-packager zips; memory-promoter promotes lessons; registry-curator updates asset metadata

Between phases, a gate ceremony runs. Operator can veto a gate pass or approve with warnings. Build memory captures lessons throughout.

Structure

nexus/
├── CLAUDE.md                       ← boot sequence + operating rules
├── README.md                       ← this file
├── identity/
│   ├── state.json                  ← factory state, core version, builds, produced, references
│   ├── owner.md                    ← operator profile
│   └── memory.md                   ← factory-level lessons (grows with builds)
├── core/                           ← UNIVERSAL; single source of truth
│   ├── blueprint/                  ← 16 docs (MVR, phase-gate, coordination, agent-format, etc.)
│   ├── methodology/                ← 8 docs (systems-design methodology)
│   ├── research-methodology/       ← 5 docs (how Nexus does research)
│   ├── skills/                     ← core-universal skills (phase-gate-check, memory-promote, etc.)
│   ├── agents/                     ← core-universal agent templates (qa-engineer, research-agent, etc.)
│   ├── patterns/                   ← universal workflow patterns
│   ├── hooks/                      ← file guards, state protection
│   ├── VERSION
│   └── CHANGELOG.md
├── knowledge-library/              ← dynamic current-state knowledge (LLMs, frameworks, platforms)
├── registries/                     ← hybrid reuse (agents, skills, patterns, research)
├── taxonomy/                       ← 8 functional dimensions for intake and tagging
├── .claude/
│   ├── agents/                     ← Nexus's 16 own agents
│   └── skills/                     ← Nexus's 20 own skills
├── builds/                         ← one subdirectory per active or completed build
├── produced/                       ← registry of harnesses Nexus has delivered
├── references/                     ← harnesses Nexus learns from but didn't build (e.g., sdlc-harness)
└── coordination/                   ← multi-session dispatch queue, inboxes, heartbeats, locks

Core principles

• Core is universal. One canonical core at nexus/core/. No produced harness forks it. Changes originate at core or cascade up from builds; cascade out via re-provisioning.
• Second observation earns promotion. An asset observed in one build stays there. In two, it promotes.
• Functional taxonomy. Every dimension drives a construction decision.
• Hybrid reuse. Registries for cross-cutting assets; reference harnesses for domain-specific exploration.
• Tracked-but-passive for produced harnesses. Nexus keeps pointers and metadata; doesn't phone home; operator reports lessons back.
• Honest accounting. No fabricated provenance. References are references. Produced means produced.
• One question at a time. Operator-facing discipline. Hard rule.
• Strong opinions when asked. Recommendations with reasoning, not hedged surveys.

Multi-build model (core v1.2+)

Nexus tracks many builds concurrently. The factory identity/state.json holds a builds{} map keyed by slug, and the session's currentContext names which build this session is operating on. Switching context never pauses a build — builds are only paused by explicit operator action.

Concurrent sessions are coordinated via coordination/sessions/<sessionId>.json. Each session registers on boot; locks carry sessionId; dead sessions (>30 min without heartbeat) are reaped on next boot.

See core/CHANGELOG.md v1.2 entry and knowledge/decisions/DEC-nexus-001-multi-build-support.md for the amendment record.

Versioning

Nexus has its own version (v1 at first ship). Core has its own version. These evolve independently:

• Nexus v1 → v2 when the factory itself changes materially (new phases, new agents, reorganization)
• Core vX → vY when operational primitives or methodology change (cascade out to produced harnesses via opt-in re-provisioning)

Changelog at core/CHANGELOG.md.

Status

• Core: v1.2 (multi-build state model; session registry; produced-ledger)
• Knowledge-library: 8 documents, dated 2026-04-18
• Taxonomy: 8 dimensions with values and tagging schema
• Agents: 16 Nexus agents
• Skills: 20 Nexus skills
• References: sdlc-harness (pointer)
• Produced: 0
• Builds in progress: bc-oil-gas (INTAKE)

Next intended build: quantum (adaptive multi-strategy trading harness), pre-ratified charter.