/nexus

Nexus Charter Recipe Reference

Purpose: Comprehensively analyze a repository and author a self-contained team Charter — including the team-construction design — that a development team can self-drive from. Charter stops at the document; execution is a separate recipe (enact). Read when: User invokes /nexus charter, or asks to "analyze the whole repo and produce an instruction document (with team design) a team can run autonomously". For running a Charter, see reference/enact-recipe.md.

Contents

• Overview
• The charter → enact split
• Charter vs Apex vs Goal (disambiguation)
• Invocation Modes
• Topology
• Phase 0: Framing
• Phase 1: Comprehensive Repository Analysis
• Phase 2: Objective & Work Breakdown
• Phase 3: Charter Authoring
• Engine Assignment (multi-engine orchestration)
• Charter Document Schema
• AUTORUN Chain Template
• Failure Escalation
• Scale, Cost and Latency Profile

Overview

Charter is the repo-centric, document-first planning recipe. It reads the entire repository, distills a durable Charter artifact (docs/CHARTER.md), and designs the team that will execute it — but does not build or run that team. The Charter is the deliverable: a single self-contained operating manual that encodes everything a development team needs to run without further human design — repo map, conventions, mission, work breakdown, role→skill roster + spawn config, orchestration plan, verification gates, and escalation rules.

Two properties make Charter distinct:

1. The team is designed into the document. Phase 3 authors a roster (§5) and orchestration plan (§6) so the team is a pure function of the Charter — enact (or a fresh Nexus session) reconstructs the identical team by reading the same file. This is what "a self-driving instruction document" means: the document is the source of truth; the team is derived from it.
2. Comprehensive analysis is the foundation. Phase 1 is a full multi-axis sweep (structure, architecture, history, conventions, debt, risk) that grounds every roster and work-package decision in repo reality, so the Charter is buildable rather than aspirational.

Charter is not a default recipe. It is opt-in when the deliverable is the plan including who runs it — onboarding a new initiative into an existing codebase, or producing a reusable team runbook that outlives the session.

The charter → enact split

Planning and execution are deliberately two recipes:

The split lets a user pay for authoring first, inspect/edit the Charter, then commit to execution separately via enact docs/CHARTER.md — and re-run the same team later at execution-only cost. Charter never spawns execution agents; it only spawns analysis/authoring agents.

Charter vs Apex vs Goal (disambiguation)

Route to apex when the unit of work is a single feature and you want one-shot discovery→ship. Route to charter when you want the analysis + a durable, inspectable team design first; then enact to run it.

Invocation Modes

Charter always stops after authoring. To run the result: /nexus enact <out path>.

Topology

Five stages in sequence — Phase 0 Framing → Phase 1 Comprehensive Repository Analysis (parallel sweep) → Phase 2 Objective & Work Breakdown → Phase 3 Charter Authoring → DELIVER — each detailed in its own section below (full agent list, not repeated here). Failure escalation loops back to the originating phase (see § Failure Escalation).

Hub-and-spoke is preserved: Nexus is the only orchestrator. Charter spawns only analysis/authoring specialists. The Charter's §5 nominates sub-orchestrators (Vision/Orbit/Rally) for execution clusters, but they are instantiated later by enact, not here.

Phase 0: Framing

Purpose: Establish what is being chartered and how deep to go. No spawn — Nexus-internal detection.

Exit gate: repo type + stack + scope + objective-mode + out-path resolved.

Phase 1: Comprehensive Repository Analysis

The comprehensive-analysis foundation. Parallel multi-axis sweep; each analyzer owns one lens and returns a structured section. Reconverge into a Repository Intelligence Report — the single grounding input for Phase 2-3.

Nexus-internal (no spawn): read and summarize CLAUDE.md / AGENTS.md / README / .agents/PROJECT.md into the Conventions seed.

Exit gate: Repository Intelligence Report covers — structure, architecture, conventions, dependencies, test/coverage posture, debt, security baseline (if applicable), and history. Gaps flagged as UNKNOWN rather than guessed (do not fabricate; verify before asserting).

Phase 2: Objective & Work Breakdown

Turn analysis (+ objective) into a prioritized, decomposed, acceptance-bounded plan.

Exit gate: every work package has (1) an atomic step list, (2) measurable AC, (3) dependency/sequence position, (4) — provisionally — a recommended owner skill (finalized as the §5 roster in Phase 3). Autonomous mode additionally carries the selected scope + rejected alternatives.

Phase 3: Charter Authoring

Synthesize Phases 1-2 into the Charter document — the self-contained operating manual, including the team-construction design. Authored by scribe with scribe[unified] supplying traceability; void optionally trims scope (full mode).

The Charter MUST be self-driving: a reader (human, enact, or a fresh Nexus session) can construct the team and execute every work package from the document alone, without re-running analysis. This self-containment check is the reader-path test of reference/doc-quality-protocol.md (W12, reader = enact/the executing team); the Charter also follows its grounding (W4-W5 — Phase 1's UNKNOWN-over-guessing rule), coherence (W8-W9, terms follow the repo's vocabulary), and freshness (W3: as-of + review trigger) rules. Write it to out (default docs/CHARTER.md) and a machine-readable companion (docs/CHARTER.roster.yaml) holding the roster + orchestration plan for enact re-entry.

Team-construction design (not execution). Phase 3 finalizes §5 (roster: per work package, owner skill + model tier + engine + spawn config) and §6 (orchestration plan: chain order, parallel branches + file ownership, checkpoints, per-package engine assignment). It does not verify spawn prereqs or instantiate agents — that is enact Phase 1.

Exit gate: Charter passes the self-containment check — roster, work breakdown, AC, conventions, orchestration plan, and verification gates are all present and mutually consistent; every work package maps to exactly one owner skill that exists in the ecosystem, and every package carries an engine assignment; and §10 checklists (pre-flight incl. team-readiness, per-package DoD, progress tracker, final delivery) are generated from §3+§4+§7 (team-readiness cross-references §1/§2/§5/§6) with one DoD block and one tracker row per §4 package. Then DELIVER the Charter and hand off to enact (recommend the /nexus enact <out path> command in NEXUS_COMPLETE).

Engine Assignment (multi-engine orchestration)

The Charter is multi-engine by default (engines=claude+codex). Phase 3 assigns each §5 work package a runner engine in §6 so enact spawns it on the right CLI. This applies the Plan-and-Execute pattern across engines (SKILL.md Core Contract): capable models plan/design, cheaper or coding-tuned engines execute.

Authoring rules:

• Tag every §5 roster entry with engine: and the verified authorized model/effort (or explicitly inherit). Resolve available stable IDs through _common/CLI_COMPATIBILITY.md; keep runtime choices out of the immutable task methodology.
• Where §5 nominates Orbit for a build loop, pin its sub-hub engine to Codex CLI (Orbit drives spawn_agent per iteration), mirroring Apex.
• Record per-engine prerequisites in §6 so enact Phase 1 can verify spawn capacity, permissions, skill loading and result capture under _common/CLI_COMPATIBILITY.md. A PTY is not a default prerequisite.
• Specify a fallback per Codex/agy package (fallback_engine: claude-code) so enact degrades gracefully when an engine is unreachable instead of hard-failing — and note the cost/throughput trade-off the fallback implies.
• engines=claude forces single-engine (no Codex) when the environment cannot reach Codex; engines=all adds agy as a third axis; engines=auto lets Phase 3 pick per detected availability, defaulting to claude+codex.

Charter Document Schema

The Charter (docs/CHARTER.md) contains these sections; the companion CHARTER.roster.yaml mirrors §5-§6 machine-readably.

§1 Mission & Objectives      goal statement, success definition, non-goals
§2 Repository Map            structure, architecture summary, key modules, data flows  (from Phase 1)
§3 Conventions & Guardrails  commit style, test/lint/build/typecheck commands, coding
                             standards, branch policy, L4/destructive-action rules     (from Phase 0/1)
§4 Work Breakdown            epics → atomic steps, dependencies, sequencing, AC per
                             package, traceability IDs                                  (from Phase 2)
§5 Team Roster               per work package: owner skill + model tier +
                             engine (claude-code|codex-cli|agy) + fallback_engine +
                             spawn config + context envelope; sub-orchestrator
                             nominations (Vision/Orbit/Rally) where a cluster needs one
§6 Orchestration Plan        chain order, parallel branches + file ownership,
                             checkpoints, max-hop limits, aggregation strategy,
                             per-package engine assignment + per-engine prerequisites
                             (multi-engine: Claude Code plan/design, Codex CLI build loops)
§7 Verification Plan         per-package + final gates (tests/build/security/AC checks)
§8 Escalation & Rollback     failure tiers, circuit-breaker, rollback boundaries,
                             human-confirm triggers
§9 Execution Log             (empty at authoring; during execution `enact` keeps this as
                             a pointer + summary and streams the timeline to an append-only
                             run-log file, default `docs/CHARTER.run.log.md`)
§10 Checklists & Trackers    pre-flight checklist (run prerequisites); per-package
                             Definition-of-Done checklist (AC met + tests + lint/build/
                             typecheck + review + docs, derived from §3+§4); progress
                             tracker (one checkbox per §4 package); final delivery
                             checklist (§7 gates + ship readiness + rollback ready)

§10 makes the Charter actionable and self-tracking: the pre-flight and DoD checklists give enact (and a human) an explicit, testable gate at each boundary instead of prose judgment, and the progress tracker is the at-a-glance status surface (checkboxes enact ticks at each PKG_DONE, complementing the append-only run log). Author each checklist item as a concrete, verifiable assertion (command to run, file to exist, gate to pass) — not a vague "looks done".

§10 template (GitHub-flavored checkboxes so they render and tick in-place):

### Pre-flight
- [ ] Charter §1-§8 present and self-consistent
- [ ] Every §4 package maps to a constructable §5 owner skill
- [ ] Engine prereqs met (Codex C1 capacity/nesting check) or `fallback_engine` set
- [ ] Working tree clean; branch per §3 policy

### Team readiness (human-agent teaming — 5 diagnostic questions)
Derived from the human-agent-team diagnostic [Source: claude.com/blog/building-effective-human-agent-teams]. Each item is a cross-reference to the Charter section that must already answer it — a failed item means that section is under-specified, not a new work package.
- [ ] **Information public & searchable** — every fact an owner/agent needs to act is in the Charter or a path it cites (§2 repo map, §3 conventions); no load-bearing knowledge lives only in a human's head or an unsearchable channel (§1·L1)
- [ ] **Roster written, ownership unambiguous** — every team member (human + agent) and what they own is named; every §4 package maps to exactly one §5 owner (§5·L2)
- [ ] **Tool/engine access matches the job** — each §5 owner has the engine + tool access its package requires; prereqs met or `fallback_engine` set (§5/§6·L2)
- [ ] **Verification rubric or test exists** — every package has a testable gate, not prose judgment (§7 + §10 DoD·L4)
- [ ] **North Star referenced** — §1 Mission is an ambitious, written goal every owner can point to, and at least one owner is tasked to propose North-Star-aligned work proactively (§1·L3)

### Per-package DoD (one block per §4 package, instantiated from §3 commands)
- [ ] PKG-<id>: acceptance criteria (§4) met
- [ ] PKG-<id>: tests added/updated and green (`<§3 test cmd>`)
- [ ] PKG-<id>: lint + typecheck + build pass (`<§3 cmds>`)
- [ ] PKG-<id>: reviewed (judge) / docs updated if public surface changed

### Progress tracker (one row per §4 package)
- [ ] PKG-001 <title> — owner <skill> — status: pending
- [ ] PKG-002 <title> — owner <skill> — status: pending

### Final delivery
- [ ] All §7 gates pass (or failures reported honestly)
- [ ] No SKIPPED package is release-critical (else flagged in DELIVER)
- [ ] Run log RUN_END written; Charter §9 pointer current
- [ ] Rollback plan (§8) ready; launch artifacts (if in scope) prepared

§5 + §6 make the team a pure function of the document. Each §5 entry is a ready-to-use spawn spec aligned to the Agent Spawn Template (SKILL.md) — role → skill SKILL.md path, model tier, engine, acceptance criteria, output envelope — so enact can construct the team without re-deriving anything.

AUTORUN Chain Template

# ── Autonomous mode (no objective) ───────────────────
Nexus AUTORUN charter
  ── Phase 0 Framing ──────────────────────────────────
  → detect(repo_type, stack, size, scope, out_path); objective = autonomous
  ── Phase 1 Comprehensive Analysis (parallel) ────────
  → [parallel] lens(structure+dataflow)
            ‖ atlas(arch+deps+debt+ADR)
            ‖ grove(layout)?       ‖ trail(history)?
            ‖ sentinel(sec)?       ‖ canon(std)? ‖ sweep(dead)? ‖ pulse(health)?
  → internal: read CLAUDE/AGENTS/README/PROJECT → conventions seed
  → reconverge → Repository Intelligence Report
  ── Phase 2 Objective & WBS ──────────────────────────
  → spark(propose) → rank(ICE/RICE select)        # autonomous only
  → sherpa(atomic step WBS) → scribe[unified](AC + trace)
  → magi(arbitrate)? → omen+ripple(risk gate)?
  ── Phase 3 Charter Authoring (incl. team design) ────
  → scribe(+scribe[unified] trace, void? full)
       → finalize §5 roster + §6 orchestration plan
       → assign engine per package: Claude Code (plan/design/review)
         ‖ Codex CLI with verified authorized model (build loops + high-volume parallel
           coding; Orbit sub-hub pinned to Codex) ‖ agy? (engines=all)
       → record per-engine prereqs + fallback_engine in §6
       → write docs/CHARTER.md + CHARTER.roster.yaml
  → [self-containment check]
  ── DELIVER ──────────────────────────────────────────
  → NEXUS_COMPLETE(charter_path) + recommend `/nexus enact docs/CHARTER.md`


# ── Objective-supplied mode ──────────────────────────
Nexus AUTORUN charter "<objective>"
  → Phase 0-1 same; Phase 2 skips spark+rank (objective bound directly)
  → Phase 3 + DELIVER identical

Failure Escalation

Because charter stops at the document and runs no execution (reference/recipe-contract.md §3: no execution → no confirm gate), most rows below are authoring-time gates that prevent failures from surfacing expensively downstream in enact.

Resume

Checkpoint-resume (≥ 4 phases): persist each analysis subsystem's findings as it completes, and the Charter draft at each section boundary. Resume continues authoring from the last completed section against the already-gathered analysis — the repo scan is not repeated.

Termination Bound

N/A — charter is a non-loop recipe. It runs a single analysis-then-author pass and stops at the document; the loops it configures belong to enact and to the team the Charter describes, not to charter itself.

Scale, Cost and Latency Profile

The profile table is canonical; the scale line is read off it. 5-15 agents, single pass, low-to-medium cost — repo-size dependent, since the Phase 1 analysis fan-out over subsystems dominates and authoring is a small tail. No cycle multiplier — see Termination Bound.

Charter only spawns analysis/authoring agents, so it stays cheap relative to enact. The durable Charter means the user reviews the Charter before paying for execution — and the same Charter can drive enact repeatedly.

Visualization

See § Topology for the phase flow. The Charter document (docs/CHARTER.md) is the human-facing artifact; CHARTER.roster.yaml is the machine-readable team/orchestration spec consumed by enact.