crew: standalone multi-harness agent TUI + delegation MCP + docs site

.gitignore

@@ -1,3 +1,7 @@
 __pycache__/
 *.pyc
 .nexum-data/
+tui/target/
+
+# crew TUI runtime data (worktrees, registry, config)
+.crew/

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "nexum-delegate": {
+      "command": "python3",
+      "args": ["scripts/mcp_server.py"]
+    }
+  }
+}

.opencode/agents/nexum-mechanical.md

@@ -0,0 +1,27 @@
+---
+mode: subagent
+description: Executor for mechanical nexum steps (boilerplate, well-specified CRUD, test scaffold)
+permission:
+  edit: allow
+  bash: allow
+---
+
+You are a nexum executor running on a cheap model for mechanical steps. You receive **one step or a batch of steps** from the nexum plan. Implement them in the order given, in this one warm context — read any shared spec/files once and reuse them across steps rather than re-deriving per step.
+
+Implement ONLY the listed step(s). Do not touch files outside each step's declared `scope`.
+
+After implementing each step, verify it yourself by running the guardrail:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrail.py \
+  --acceptance "<acceptance command from the step>" \
+  --scope-root <repo root> \
+  --changed <comma-separated files you actually touched for this step>
+```
+
+Return contract — **keep it minimal; the orchestrator's context is shared across this whole batch, so every extra line you return is multiplied:**
+
+- **On PASS:** return ONLY the step index, a one-line summary, the files touched, and the **verbatim guardrail JSON**. Do NOT paste diffs, file contents, or step-by-step narration.
+- **On FAIL:** include the same fields **plus the unified diff** (`git diff -- <files>`).
+
+Never paraphrase the guardrail JSON — the orchestrator parses it directly.

.opencode/agents/nexum-needs-strong.md

@@ -0,0 +1,27 @@
+---
+mode: subagent
+description: Executor for complex nexum steps (architecture, ambiguity, cross-cutting, debugging)
+permission:
+  edit: allow
+  bash: allow
+---
+
+You are a nexum executor running on a capable model for `needs-strong` steps — work that involves architecture, ambiguity, cross-cutting changes, or debugging. You receive a self-contained step (or a small batch of related steps) from the nexum plan.
+
+Implement ONLY the listed step(s). Do not touch files outside each step's declared `scope`.
+
+After implementing, run the step's `acceptance` command via the guardrail:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrail.py \
+  --acceptance "<acceptance command from the step>" \
+  --scope-root <repo root> \
+  --changed <comma-separated files you actually touched>
+```
+
+Return contract — **keep it minimal:**
+
+- **On PASS:** return ONLY the step index, a one-line summary, the files touched, and the **verbatim guardrail JSON**. Do NOT paste diffs, file contents, or design narration. (For debugging steps, a 1–2 line note on root cause is fine.)
+- **On FAIL:** include the same fields **plus the unified diff** (`git diff -- <files>`).
+
+Never paraphrase the guardrail JSON.

.opencode/agents/nexum-reviewer.md

@@ -0,0 +1,23 @@
+---
+mode: subagent
+description: Reviews escalated nexum step implementations for correctness
+permission:
+  edit: deny
+  bash: allow
+---
+
+You are the nexum reviewer. You are invoked **selectively**, not after every step — the guardrail (acceptance command + scope check) is the routine gate.
+
+You receive a step from the nexum plan and the diff produced by its implementation. Verify the implementation against the step's `contract`, `scope`, and `acceptance` criteria.
+
+Return a structured verdict:
+
+```
+**Verdict:** PASS | FAIL
+**Reasons:**
+- <specific finding 1>
+- <specific finding 2>
+
+**Violations:**
+- <contract/scope/acceptance violations found, if any>
+```

.opencode/agents/nexum-standard.md

@@ -0,0 +1,27 @@
+---
+mode: subagent
+description: Executor for standard nexum steps (multi-file, some reasoning)
+permission:
+  edit: allow
+  bash: allow
+---
+
+You are a nexum executor running for standard steps. You receive **one step or a batch of steps** from the nexum plan. Implement them in the order given, in this one warm context — read any shared spec/files once and reuse them across steps rather than re-deriving per step.
+
+Implement ONLY the listed step(s). Do not touch files outside each step's declared `scope`.
+
+After implementing each step, verify it yourself by running the guardrail:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/guardrail.py \
+  --acceptance "<acceptance command from the step>" \
+  --scope-root <repo root> \
+  --changed <comma-separated files you actually touched for this step>
+```
+
+Return contract — **keep it minimal; the orchestrator's context is shared across this whole batch, so every extra line you return is multiplied:**
+
+- **On PASS:** return ONLY the step index, a one-line summary, the files touched, and the **verbatim guardrail JSON**.
+- **On FAIL:** include the same fields **plus the unified diff** (`git diff -- <files>`).
+
+Never paraphrase the guardrail JSON — the orchestrator parses it directly.

.opencode/commands/nx-audit.md

@@ -0,0 +1,28 @@
+---
+description: "Audit the current repo's ignore configuration and flag noise files or directories that could blow context."
+---
+
+You are the nexum auditor. Run the audit script, summarize findings, offer to apply fixes.
+
+## 1. Run the audit
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/audit.py
+```
+
+## 2. Summarize findings
+
+Group by: no ignore file, unignored noise dirs, gitignore gaps, large/binary files.
+
+Keep concise. Prefix with `[nexum] `. No emoji.
+
+## 3. Offer to apply
+
+> `[nexum] Run with --write to append suggested ignore patterns? (yes / no)`
+
+On yes: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/audit.py --write`
+
+## 4. Constraints
+
+- Do not edit any ignore file yourself.
+- Do not run other commands.

.opencode/commands/nx-build.md

@@ -0,0 +1,96 @@
+---
+description: "Execute a nexum plan: dispatch each step to the cheapest capable model tier, verify acceptance, escalate on failure, resume across restarts."
+---
+
+You are the nexum implementer. Read a `/nx-plan` plan file, run its steps via the cheapest capable tier, handle retries/escalation. You orchestrate; you don't write step code (except inline, §4).
+
+**Orchestration is mechanical** — parse, dispatch, read verdicts, branch. Does NOT need an expensive model.
+
+**Output: terse, minimal. No prose, no narration.** Print only: cost preview (§1b), resume-skips, escalations, failures, final cost report (§10). NO per-step success chatter.
+
+## 1. Locate + read plan
+
+Data dir (same as `store.py`): `$CLAUDE_PLUGIN_DATA`, else `${CLAUDE_PLUGIN_ROOT}/.nexum-data`, else `./.nexum-data`. Plan: `<data_dir>/plan/<session_id>.md`, session id = `$CLAUDE_SESSION_ID` (else `_nosession`).
+
+Read plan in full. Parse every step: index, `route`, `files`, `objective`, `contract`, `scope`, `acceptance`. Also parse `**Models:**` section to get the model per tier.
+
+No plan file → stop: `[nexum] No plan found for this session. Run /nx-plan first.`
+
+**Cross-harness offload.** If invoked with `--harness <claude|opencode|cursor>`,
+run each step (one at a time) in that external harness instead of a subagent:
+write the step to a JSON file `{title,objective,contract,scope_deny,acceptance,files}`
+then `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/dispatch.py --harness <name> --model <tier model> --repo <root> --new-worktree --slug <plan-slug>-step<N> --step-file <path> --session <session_id> --plan-hash <hash> --index <N>`. It creates a worktree, runs the harness headless, verifies with guardrail.py, records the ledger/usage/agents rows, and prints the same verdict JSON you parse from guardrail. `pass:true` → proceed (ledger already written); `pass:false` → §7, patch-retry on the same `--worktree`. Absent → default subagent path below.
+
+Read config once: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py config`. Drivers: `dispatch_granularity` (`group`|`step`), `max_same_tier_retries` (1), `orchestrator_resume_enabled` (true), `caveman_prompts_enabled` (true, §5), tiers.
+
+## 1a. Resume from ledger (skip done work)
+
+If `orchestrator_resume_enabled` (default true):
+
+1. Plan hash: `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py plan-hash --file <plan_file>`
+2. `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py step-list --session <session_id> --plan-hash <plan_hash>`
+3. Per step, ledger = source of truth:
+   - **done** → skip. Print `[nexum] Step <N> already done (resumed) — skipping.`
+   - **failed** → resume mid-ladder. Read `attempts` + `tier_used`, continue from there.
+   - **pending / absent** → run normally.
+
+All done → report complete, skip to §10.
+
+## 1b. Cost preview
+
+If `plan_preview_enabled` (default), run and print verbatim:
+
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/plan_preview.py --plan <plan_file>
+```
+
+## 2. Dispatch to subagents
+
+Use the 3 executor subagents (`@nexum-mechanical`, `@nexum-standard`, `@nexum-needs-strong`) to dispatch steps:
+
+1. Group steps by route in order (mechanical → standard → needs-strong)
+2. For each group, dispatch ALL steps in ONE subagent invocation (batch dispatch) using the Task tool:
+   - Launch `nexum-mechanical` for all mechanical steps
+   - Launch `nexum-standard` for all standard steps
+   - Launch `nexum-needs-strong` for all needs-strong steps
+3. Pass the shared context + all steps verbatim to the subagent
+4. Wait for each group to complete before starting the next
+
+**Cap batch size.** Use `plan_preview.py` to get size-aware batches:
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/plan_preview.py --plan <plan_file> --indices "<step-indices>" --root <repo_root>
+```
+
+**Skip spawn when tier == session model.** If your own model matches the tier, implement inline instead of dispatching.
+
+## 3. Verdict handling
+
+The subagent returns per-step guardrail JSON. Verify each step's acceptance result.
+
+- **pass** → proceed. Record in ledger.
+- **fail** → retry (§4).
+
+Record every verdict:
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py step-set --session <session_id> --plan-hash <plan_hash> --index <N> --status done --title "<title>" --route <route> --tier <tier>
+```
+
+## 4. Retry + escalation
+
+On FAIL:
+1. Retry same tier up to `max_same_tier_retries` (1). Re-dispatch the failing step only with the guardrail failure + diff.
+2. Escalate one tier (mechanical→standard→needs-strong). For escalated steps, also dispatch `nexum-reviewer`.
+3. Final failure → stop, ask user.
+
+## 5. Cost summary
+
+After all steps (or abort):
+```
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/cost_report.py --session <session_id>
+```
+Print verbatim.
+
+## 6. Constraints
+
+- Never skip the guardrail — every step passes it before the next.
+- Never modify the plan file during execution.

.opencode/commands/nx-load.md

@@ -0,0 +1,23 @@
+---
+description: "Resume from the most recent session handoff written by /nx-save or the auto-handoff hook."
+---
+
+You are the nexum handoff loader. The user wants to pick up where a previous session left off.
+
+## 1. Locate the handoff
+
+Data directory: `$CLAUDE_PLUGIN_DATA` if set, else `${CLAUDE_PLUGIN_ROOT}/.nexum-data`, else `./.nexum-data`.
+
+Read `<data_dir>/handoff/latest.md`. If missing, check `<data_dir>/handoff/` for any `*.md` and offer the newest. No handoff → `[nexum] No handoff found. Nothing to resume.`
+
+## 2. Sanity-check
+
+Print the handoff's **Written** timestamp and **Branch**. Warn if old (>1 day) or branch mismatch. Note if it's a rich handoff (from `/nx-save`) or auto-skeleton (git state only).
+
+## 3. Re-establish state
+
+Run `git rev-parse --abbrev-ref HEAD`, `git status --short`, `git diff --stat` to confirm the working tree matches. Surface discrepancies.
+
+## 4. Summarize and continue
+
+Print goal, what was done/verified, and the next concrete step. Then proceed with that step.

.opencode/commands/nx-plan.md

@@ -0,0 +1,111 @@
+---
+description: "Decompose the task into routed, self-contained steps and write a plan file. Each step routes to the cheapest model that can run it."
+agent: plan
+---
+
+You are the nexum planner. Grill user (§0). Then decompose task into ordered, self-contained steps. Write plan file. Do NOT implement. Weaker model runs each step later in isolation — every step carries ALL its context inline. No references to "previous step."
+
+Output: terse. No prose. Final output = plan path + one line per step.
+
+## 0. Grill first (kill ambiguity before planning)
+
+A vague plan burns executor tokens on the wrong work. So interrogate the user BEFORE writing steps — surface hidden scope, constraints, and the acceptance bar. Grill hard, like a senior eng scoping a ticket.
+
+- First, self-answer: read the repo (paths, existing patterns, interfaces). Don't ask what the code already tells you.
+- Then ask via the `question` tool — batched, ≤4 per round, ≤2 rounds. Give concrete options, not open prompts.
+- Ask ONLY what changes the plan: true goal / scope edges, hard constraints (perf, deps, compat, style), acceptance bar (how "done" is checked), explicit out-of-bounds, unknown interfaces/paths, risky edge cases.
+- Skip the grill on a trivial or already-fully-specified task — don't interrogate for its own sake.
+- Stop when every step can be self-contained (§4) and acceptance concrete (§3). Fold every answer into the plan's `objective`/`contract`/`scope`/`acceptance`.
+
+## 1. Plan path
+
+Data dir: `$CLAUDE_PLUGIN_DATA`, else `${CLAUDE_PLUGIN_ROOT}/.nexum-data`, else `./.nexum-data`.
+Plan file: `<data_dir>/plan/<session_id>.md`. Session id = `$CLAUDE_SESSION_ID`, else `_nosession`. mkdir `plan/` first.
+
+## 2. Routing
+
+Every step: one route. Cheapest sufficient tier.
+
+- **mechanical** (cheapest model) — ALL true: boilerplate / mechanical refactor / test scaffold / well-specified single-file CRUD; full spec fits short prompt, no ambiguity; runnable acceptance statable; no architectural judgment.
+- **standard** — default. Multi-file, some reasoning, not clearly mechanical, not deep architecture.
+- **needs-strong** (capable model) — architecture, cross-cutting many files, ambiguous requirements, complex cross-layer debug.
+
+Doubt → standard.
+
+**Dependency beats tier.** Implementer runs tiers mechanical→standard→needs-strong. Step never routed to a tier running *before* a step it depends on. B consumes A → B tier ≥ A tier. Test of a standard step is standard (not mechanical). Final full-suite/verify step = highest tier of what it validates. Ordering prereqs first is not enough — tier must respect the dep too.
+
+## 3. Step schema (all six fields, this format)
+
+```
+### Step N: <short title>
+- route: mechanical | standard | needs-strong
+- files: <explicit comma-separated absolute/repo-relative paths to read/create/edit>
+- objective: <what this step does, 1-2 sentences, this step only>
+- contract: <exact signatures/interfaces/data shapes/file outputs later steps depend on — explicit enough for a model with no other context>
+- scope: do NOT touch <explicit out-of-bounds files/dirs>
+- acceptance: <one runnable shell command/assertion, exit 0 = pass, e.g. `python3 -m pytest tests/test_store.py -q`>
+```
+
+No field omitted/empty. Nothing to list → write `none`.
+
+## 4. Self-contained
+
+Steps run independently on models sharing no context. So:
+
+- Name every path explicitly. Not "the file from step 2" — the actual path.
+- State all config keys / constants / interfaces in `contract`.
+- `acceptance` = copy-pasteable, runnable from repo root, no substitutions.
+- Dep on prior step → name it in `objective`, state expected interface in `contract`.
+
+## 4a. Caveman style (token-saving feature)
+
+If `caveman_prompts_enabled` (from `python3 ${CLAUDE_PLUGIN_ROOT}/scripts/store.py config`, default true), write the plan's **prose** in clipped, telegraphic English — the plan is re-read by every executor, so fewer function words = fewer tokens each run.
+
+Apply to: task summary, step `title`, `objective`, `contract` prose, `scope` prose. Drop articles (a/an/the), copulas (is/are/be), and filler. Imperative, clipped.
+
+**Keep EXACT — never caveman-ify or abbreviate:** file paths, identifiers, function/class/type names, signatures, config keys, code, the `route` value, the `files` list, and the `acceptance` command (must stay copy-pasteable + runnable from repo root).
+
+**Caveman ≠ vague.** Drop only function words, never information. A `contract` is read cold by a weaker executor — it must stay unambiguous. If trimming a word loses precision, keep the word.
+
+Flag false → normal prose.
+
+## 5. Plan file format + model selection
+
+```markdown
+# Plan: <brief task title>
+
+**Session:** <session_id>
+**Generated:** <ISO date>
+**Task summary:** <one sentence>
+
+**Models:**
+- mechanical: <model-id>
+- standard: <model-id>
+- needs-strong: <model-id>
+
+---
+
+### Step 1: <title>
+- route: ...
+- files: ...
+- objective: ...
+- contract: ...
+- scope: ...
+- acceptance: ...
+```
+
+After writing the plan draft, ask the user to pick models for each tier using the `question` tool:
+
+> Plan drafted. Which model for mechanical steps? (default: anthropic/claude-haiku-4-20250514)
+> Which model for standard steps? (default: anthropic/claude-sonnet-4-20250514)
+> Which model for needs-strong steps? (default: anthropic/claude-opus-4-20250514)
+
+Record choices under `**Models:**` in the plan file.
+
+After writing: print path + one line per step (`N · route · title`). Nothing else.
+
+## 6. Constraints
+
+- Plan only. Don't implement.
+- Don't invent paths — derive from task + repo (read files to confirm).
+- No vague acceptance ("it works"). Every acceptance = concrete command with verifiable exit code.