@bradheitmann/odin-sentinel 0.4.5 → 0.4.6

package/AGENTS.md

@@ -0,0 +1,64 @@
+# ODIN Sentinel Agent Instructions
+
+These instructions are for public repo-local agents working with ODIN Sentinel.
+They are intentionally lightweight starter guidance, not a replacement for a
+user's own development process.
+
+## Role Pattern
+
+ODIN uses a simple PM/DEV/QA pattern for visible multi-agent work.
+
+- EXEC PM owns launch and activation decisions, readiness waivers or
+  substitutions, CMUX topology, staffing, final claim framing, and escalation to
+  the human operator.
+- TEAM PM owns local routing, worker activation, and status inside an assigned
+  team after EXEC PM activation. TEAM PM does not create staff, waive readiness,
+  mutate CMUX topology, or close lifecycle unless EXEC PM explicitly delegates
+  that authority.
+- DEV implements only the assigned write scope. DEV cannot QA-accept its own
+  work and must report changed files plus verification commands and results.
+- QA starts fresh, reviews adversarially, verifies DEV work independently,
+  does not fix code during QA, and reports PASS or FAIL with evidence.
+- ODIN monitors health, scope, readiness, delivery, and drift. ODIN may prod,
+  halt, or escalate, but is not a DEV, not a QA acceptor, and not the PM launch
+  authority.
+
+## Operating Rules
+
+- Stay inside the assigned files and task scope.
+- Do not print secrets. Report secret status by provider/name only.
+- Do not assume MCP alone is enough for governed team mode. Confirm MCP,
+  native skill or prompt fallback, CMUX layout, auth readiness, and model smoke
+  tests before launch.
+- Use CMUX for governed team mode. Without CMUX, ODIN can still provide protocol
+  resources and validation tools, but the visible governed-team experience is not
+  active.
+- Treat local operator planning folders as optional private workspace, not
+  required product internals.
+- Use `templates/` as starter material. Replace placeholders with project-owned
+  criteria before dispatching work.
+
+## Operator Ergonomics
+
+- Assume the operator may be new to terminals, agent harnesses, and API-key
+  setup. Explain blockers in plain language before using protocol labels.
+- Never frame setup gaps as user failure. Say what is blocked, what is safe, and
+  what choice the operator has next.
+- Treat prod, halt, freeze, warn, and stalled language as safety language. Pair
+  it with the reason and the next human choice so the operator feels protected,
+  not punished.
+- Prefer short status lines: "KiloCode needs sign-in", "Crush is waiting for
+  permission", "Goose is still producing hidden reasoning", or "OpenHands needs
+  provider credentials".
+- Do not ask the operator to paste secrets. Ask whether each harness is already
+  provisioned through an account, environment, secret manager, or local config.
+
+## Completion Report
+
+Every agent handoff should include:
+
+- role and assigned scope
+- files changed
+- commands run and results
+- blocked or waived readiness checks
+- risks or integration notes

package/CLAUDE.md

@@ -0,0 +1,43 @@
+# ODIN Sentinel Guidance For Claude
+
+Use this public role contract when Claude Code or another Claude surface is part
+of an ODIN Sentinel run.
+
+## Public Role Contract
+
+- EXEC PM: choose launch timing, approve readiness waivers or substitutions,
+  own staffing and CMUX topology, assign scope, define acceptance criteria, and
+  escalate to the human operator.
+- TEAM PM: route work and activate workers inside an already launched team.
+  TEAM PM does not staff new occupants, waive launch readiness, mutate CMUX
+  topology, or close lifecycle unless EXEC PM explicitly delegates that authority.
+- DEV: implement only assigned files, avoid unrelated edits, never accept own
+  work as QA, and report changed files plus verification commands.
+- QA: start from a fresh review posture, verify independently, do not fix during
+  QA, and return PASS or FAIL with concrete evidence.
+- ODIN: monitor readiness, health, scope, delivery, and drift. ODIN can intervene
+  or escalate, but does not implement, QA-accept, or launch teams without PM
+  authority.
+
+## Claude-Specific Notes
+
+- If a native SCP skill is installed, use it. If not, ask the PM for the full
+  prompt or call the ODIN MCP server for `odin.get_bootstrap_skill`.
+- Do not ask users to paste API keys, tokens, or OAuth values into chat. Ask
+  whether providers are configured through Doppler, 1Password CLI, environment
+  variables, direnv, mise, or dotenv-style files, then verify status without
+  printing secret values.
+- Governed team mode requires visible CMUX role slots. A tab-only chat layout is
+  degraded and should be treated as a fallback, not the canonical mode.
+- If MCP, skill context, auth, permissions, or local inference are missing, report
+  the blocker and wait for PM/user direction instead of guessing.
+- When the operator appears new to agents or terminals, use plain-language status
+  before protocol labels. Make the next safe choice obvious and avoid implying
+  the operator did something wrong.
+- If you use terms like halt, warn, freeze, or stalled, immediately explain that
+  the pause is a safety rail for the operator and name the next safe choice.
+
+## Output Shape
+
+End work with changed files, commands run, command results, unmet criteria, and
+integration risks.

package/README.md

@@ -1,58 +1,83 @@
 # ODIN Sentinel
 
-**Multi-harness terminal-pane team builder and orchestrator.**
+**Visible multi-agent team coordination over MCP.**
+
+ODIN Sentinel is a local stdio MCP server plus a portable coordination protocol
+for visible agent teams. It gives agents a shared roster, startup packet,
+delegation contract, receipt shape, layout rule, and closeout checklist. It does
+not provide model inference, host a backend, or replace your development process.
+
+Plain version: ODIN Sentinel helps you put coding agents into named visible
+roles, check whether they are ready, and keep a human operator in control. If a
+tool asks you to sign in, approve a permission prompt, or configure an account,
+that is a normal setup blocker, not a personal failure. You can pause, choose a
+different harness, keep a role slot empty, or ask for help.
+
+For the fastest path, read [docs/guides/quick-start.md](docs/guides/quick-start.md).
+For copy-paste prompts, read [docs/guides/quickstart-prompts.md](docs/guides/quickstart-prompts.md).
+For a starter team shape, read [docs/guides/recommended-starter-team.md](docs/guides/recommended-starter-team.md).
+
+## Terms In Plain Language
+
+- MCP server: a local tool bridge that lets an agent ask ODIN Sentinel for
+  protocol documents and validation checks.
+- Harness: the app or CLI running an agent, such as Claude Code, Codex, Goose,
+  Crush, OpenHands, Cursor, Zed, or another MCP-capable host.
+- CMUX: the visible terminal workspace where the human can see named role slots.
+- Governed team mode: the stricter mode where persistent agents must be visible,
+  assigned to roles, and monitored.
+- Native skill or prompt fallback: the instructions that teach an agent how to
+  behave in this system.
+
+## Minimum Governed-Team Checklist
+
+Before launching persistent governed roles, confirm:
+
+- Node.js satisfies `package.json` (`>=22.13.0`).
+- `@bradheitmann/odin-sentinel` is installed or available through `npx`.
+- The ODIN MCP server is configured in each selected harness.
+- The SCP native skill is installed where supported, or the full prompt/resource
+  fallback is available.
+- CMUX is installed and the team will run in one visible CMUX workspace.
+- Harnesses and accounts are selected and authenticated.
+- Local inference is smoke-tested if used: endpoint reachable, content returned
+  within timeout, and not only `reasoning_content`.
+- Role-compatibility smoke test passes for each persistent role.
+
+Role slots may be prepared before readiness is complete, but occupants should
+not be launched until readiness passes or the PM records a waiver/substitution.
 
-ODIN Sentinel is a portable control layer for visible agent teams running across
-terminal panes, local CLIs, editors, and MCP-capable harnesses. It does not try
-to be another agent. It gives the agents a room, a roster, and a way to work
-without dissolving into chatter.
-
-The questions are practical. Who is here? What role do they hold? Who may
-delegate? Who may verify? What changed, what passed, what failed, and how does
-the session end without leaving a pane stack full of unfinished business?
-
-ODIN starts with shape: an executive office, development pods, and ODIN
-roles across the mesh. Then it provides the protocol pieces that keep the shape
-honest: startup packets, role contracts, model and harness defaults, delegation
-envelopes, receipts, manifests, and closeout checklists.
-
-No hand-copied ritual. No private lore. Any MCP-capable harness can ask. Codex,
-Claude, Droid, Crush, Goose, Zed, OpenCode, or a client written in Rust, Go,
-Zig, or WebAssembly all fit the same boundary when they can launch or bridge
-stdio MCP. These are examples, not bundled dependencies. One server. Many
-harnesses. Same map, same names, same flame.
-
-The repository is named `odin-sentinel` to avoid confusion with the Odin
-programming language.
+## Install
 
-For a recommended first team, see
-[docs/guides/recommended-starter-team.md](docs/guides/recommended-starter-team.md).
+```bash
+npm i -g @bradheitmann/odin-sentinel
+```
 
-For copy-paste setup and team-bootstrap prompts you can hand to Claude Code or
-Codex on a fresh machine, see
-[docs/guides/quickstart-prompts.md](docs/guides/quickstart-prompts.md).
+Zero-install MCP host config can use:
 
-## Quick Start
+```bash
+npx -y -p @bradheitmann/odin-sentinel odin-sentinel-mcp
+```
 
-### 1. Install
+A stdio smoke test that does not require an MCP host:
 
 ```bash
-npm i -g @bradheitmann/odin-sentinel
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' \
+  | npx -y -p @bradheitmann/odin-sentinel odin-sentinel-mcp
 ```
 
-Or use `npx` without installing — see the host-specific configs below.
+A successful response includes `"serverInfo":{"name":"odin-sentinel","version":"0.4.6"}`.
+Minimum compatible child MCP version for governed-team docs is `0.4.5`.
 
-### 2. Configure your MCP host
+## MCP Host Examples
 
-Pick the one you use. Restart the host after editing.
-
-**Claude Code**
+Claude Code:
 
 ```bash
 claude mcp add odin-sentinel -- npx -y -p @bradheitmann/odin-sentinel odin-sentinel-mcp
 ```
 
-**Codex** (`~/.codex/config.toml`)
+Codex (`~/.codex/config.toml`):
 
 ```toml
 [mcp_servers.odin-sentinel]
@@ -60,7 +85,7 @@ command = "npx"
 args = ["-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"]
 ```
 
-**Cursor / Cursor CLI / VS Code / Factory (Droid) / Pi** (`mcpServers` JSON)
+Generic `mcpServers` JSON:
 
 ```json
 {
@@ -73,146 +98,49 @@ args = ["-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"]
 }
 ```
 
-**Zed** (`~/.config/zed/settings.json` → `context_servers`)
-
-```json
-"odin-sentinel": {
-  "source": "custom",
-  "command": "npx",
-  "args": ["-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"]
-}
-```
-
-**Goose** (`~/.config/goose/config.yaml` → `extensions`)
-
-```yaml
-odin-sentinel:
-  type: stdio
-  cmd: npx
-  args: ["-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"]
-  enabled: true
-```
-
-**Crush** (`~/.config/crush/crush.json` → `mcp`)
-
-```json
-{
-  "mcp": {
-    "odin-sentinel": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"]
-    }
-  }
-}
-```
-
-**OpenCode** (`~/.config/opencode/opencode.json` → `mcp`)
-
-```json
-{
-  "mcp": {
-    "odin-sentinel": {
-      "type": "local",
-      "command": ["npx", "-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"],
-      "enabled": true
-    }
-  }
-}
-```
-
-**OpenHands** (`~/.openhands/config.toml`)
-
-```toml
-[mcp.stdio_servers.odin-sentinel]
-name = "odin-sentinel"
-command = "npx"
-args = ["-y", "-p", "@bradheitmann/odin-sentinel", "odin-sentinel-mcp"]
-```
-
-### 3. Use it
-
-After restarting the host, give the agent an instruction like:
+## MCP, Skill, Plugin, Prompt Fallback
 
-> Use the `odin-sentinel` MCP server. Call `odin.get_startup_packet`, then bootstrap an executive office and one development pod.
+- MCP server: supplies protocol resources and validation tools.
+- Native skill: improves discoverability and automatic invocation in supported
+  harnesses.
+- Plugin: may package the MCP server and native skill together for a host.
+- Full prompt injection: fallback only when MCP/native skill/plugin support is
+  unavailable.
 
-The agent will read the protocol resources (`odin://protocol/*`), follow the role contracts, and stay inside the SCP governance rules.
+MCP alone is useful, but governed team mode is strongest when the persistent
+roles also have native skill context or the full bootstrap prompt.
 
-### 4. Verify (optional)
-
-A one-line smoke test that works without any host:
-
-```bash
-printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' \
-  | npx -y -p @bradheitmann/odin-sentinel odin-sentinel-mcp
-```
+## CMUX Requirement
 
-A successful response includes `"serverInfo":{"name":"odin-sentinel","version":"0.4.5"}`.
+Governed team mode requires CMUX or a compatible visible terminal-pane surface.
+The EXEC PM should remain in the same CMUX workspace as the rest of the team by
+default. Tab-only layouts are degraded; the canonical layout is human-readable
+spatial/pod organization.
 
-### Claude Code plugin (optional)
+Without CMUX, ODIN can still expose MCP resources, validation tools, and protocol
+snapshots, but the visible team-management experience is not active governed
+mode.
 
-If you're on Claude Code, you can install the SCP skill + MCP server together as a plugin:
+## Public Starter Templates
 
-```bash
-claude plugin marketplace add bradheitmann/odin-sentinel
-claude plugin install sentinel-coordination-protocol@odin-sentinel
-```
+The `templates/` directory contains intentionally basic PM, DEV, QA, and team
+manifest templates. They are starter material only. Add your own criteria before
+using them for real work.
 
-## Terms
-
-- ODIN Sentinel: this MCP server and its portable team-coordination protocol.
-- SCP: Sentinel Coordination Protocol, the ODIN startup, delegation, receipt,
-  manifest, and closeout contract. It is not Secure Copy.
-- CMUX: a compatible terminal-pane control surface. ODIN can support CMUX-style
-  teams, but CMUX is not required by this repository.
-- Harness: a local agent runtime, CLI, editor integration, or MCP client.
-
-## How It Works
-
-```text
-                    MCP-capable clients
-          ┌─────────────────────────────────────┐
-          │ Codex │ Claude │ Droid │ Crush │ UI │
-          └───┬──────┬────────┬───────┬─────┬───┘
-              │      │        │       │     │
-              └──────┴────────┴───────┴─────┘
-                            │
-                            ▼
-                  ┌───────────────────┐
-                  │  odin-sentinel    │
-                  │  MCP server       │
-                  └─────────┬─────────┘
-                            │
-        ┌───────────────────┼───────────────────┐
-        ▼                   ▼                   ▼
-  ┌───────────┐       ┌───────────┐       ┌────────────┐
-  │ Resources │       │   Tools   │       │  Exports   │
-  │ protocol  │       │ validate  │       │ standalone │
-  │ roles     │       │ startup   │       │ protocol   │
-  │ topology  │       │ closeout  │       │ snapshots  │
-  └───────────┘       └───────────┘       └────────────┘
-        │                   │                   │
-        └───────────────────┼───────────────────┘
-                            ▼
-              ┌─────────────────────────┐
-              │ Visible role topology   │
-              │ EXEC PM, EXEC ODIN,     │
-              │ TEAM PM, TEAM ODIN,     │
-              │ DEV, QA, SHADOW         │
-              └─────────────────────────┘
-```
+Local operator planning folders may be useful private workspaces, but they are
+not shipped product internals and are not required for public users.
 
 ## Provided MCP Resources
 
-- `odin://protocol/main` - core coordination protocol
-- `odin://protocol/roles` - generic role contracts
-- `odin://protocol/topology` - executive office, pod, and ODIN mesh defaults
-- `odin://protocol/model-profiles` - recommended starter model/harness profiles
-- `odin://protocol/closeout` - continuity parking and full shutdown checklists
-- `odin://protocol/delegation` - visible-role delegation contract
-- `odin://protocol/receipts/boot` - boot receipt template
-- `odin://protocol/receipts/team-manifest` - team manifest template
-- `odin://protocol/bootstrap-skill` - full Sentinel Coordination Protocol skill
+- `odin://protocol/main`
+- `odin://protocol/roles`
+- `odin://protocol/topology`
+- `odin://protocol/model-profiles`
+- `odin://protocol/closeout`
+- `odin://protocol/delegation`
+- `odin://protocol/receipts/boot`
+- `odin://protocol/receipts/team-manifest`
+- `odin://protocol/bootstrap-skill`
 
 ## Provided MCP Tools
 
@@ -220,6 +148,11 @@ claude plugin install sentinel-coordination-protocol@odin-sentinel
 - `odin.get_startup_packet`
 - `odin.get_role_profile`
 - `odin.get_bootstrap_skill`
+- `odin.get_boot_receipt_schema`
+- `odin.get_boot_receipt_examples`
+- `odin.get_active_watch_packet`
+- `odin.get_harness_probe_matrix`
+- `odin.evaluate_readiness_gate`
 - `odin.validate_boot_receipt`
 - `odin.validate_team_manifest`
 - `odin.get_delegation_packet`
@@ -229,186 +162,16 @@ claude plugin install sentinel-coordination-protocol@odin-sentinel
 - `odin.export_protocol_snapshot`
 - `odin.compute_surface_layout`
 - `odin.compute_surface_layout_gate`
+- `odin.compute_human_cmux_quad_layout`
 - `odin.compile_session_report`
 - `odin.preview_telemetry_redaction`
 - `odin.submit_session_report`
 - `odin.get_telemetry_config`
 
-## Self-Contained Protocol
-
-ODIN Sentinel must not depend on external local extensions. Concepts such as
-delegation, handoff discovery, startup topology, model/harness profiles, receipt
-validation, and closeout are implemented as MCP resources and tools inside this
-server.
-
-A client may have other local extensions installed, but those extensions are optional
-and cannot be required for the ODIN Sentinel protocol to work.
-
-## Client Compatibility
-
-ODIN Sentinel is implemented in TypeScript and runs on Node.js, but MCP clients
-can be written in Rust, Zig, Go, WebAssembly, Python, or any other environment
-that can speak MCP over stdio.
-
-The boundary is plain MCP JSON-RPC:
-
-```text
-native / WASM / CLI client
-          │
-          │ MCP over stdio
-          ▼
-node dist/src/bin/index.js
-```
-
-For clients that cannot spawn stdio subprocesses, use a host bridge or consume
-the fallback files returned by `odin.export_protocol_snapshot`.
-
-See [docs/reference/client-compatibility.md](docs/reference/client-compatibility.md).
-For the current release-surface inventory, see
-[docs/reference/public-surface-audit.md](docs/reference/public-surface-audit.md).
-
-## Install
-
-For a step-by-step setup, see [docs/guides/quick-start.md](docs/guides/quick-start.md).
-
-For local source builds:
-
-```bash
-pnpm install
-pnpm run build
-```
-
-Or install from npm:
-
-```bash
-npm i -g @bradheitmann/odin-sentinel
-```
-
-Then run the MCP server directly:
-
-```bash
-odin-sentinel-mcp
-```
-
-For zero-install use from any MCP host config:
-
-```bash
-npx -y -p @bradheitmann/odin-sentinel odin-sentinel-mcp
-```
-
-See [docs/reference/distribution.md](docs/reference/distribution.md).
-
-## Run Over stdio
-
-```bash
-pnpm run dev
-```
-
-After building:
-
-```bash
-node dist/src/bin/index.js
-```
-
-When installed from a package, the executable names are:
-
-```bash
-odin-sentinel
-odin-sentinel-mcp
-```
-
-## Example MCP Client Configuration
-
-```json
-{
-  "mcpServers": {
-    "odin-sentinel": {
-      "command": "node",
-      "args": ["/absolute/path/to/odin-sentinel/dist/src/bin/index.js"]
-    }
-  }
-}
-```
-
-For local development, clients that support direct command execution can use:
-
-```json
-{
-  "mcpServers": {
-    "odin-sentinel": {
-      "command": "pnpm",
-      "args": ["exec", "tsx", "/absolute/path/to/odin-sentinel/src/bin/index.ts"]
-    }
-  }
-}
-```
-
-## Harness Setup Notes
-
-MCP-capable harnesses should point at the built stdio server:
-
-```text
-node /absolute/path/to/odin-sentinel/dist/src/bin/index.js
-```
-
-Common config shapes:
-
-- Claude/Cursor-style: add `odin-sentinel` under `mcpServers`.
-- Codex CLI: use `codex mcp add odin-sentinel -- node /path/to/dist/src/bin/index.js`.
-- Droid CLI: use `droid mcp add odin-sentinel node /path/to/dist/src/bin/index.js --type stdio`.
-- OpenCode-style: add a local `mcp.odin-sentinel` command entry.
-- Goose-style: add an enabled `type: mcp` extension entry.
-- Zed-style: add an enabled custom `context_servers.odin-sentinel` entry.
-
-These are MCP client patterns, not a compatibility certification for every
-release of every harness. For harnesses without discoverable MCP configuration,
-use the self-contained protocol snapshot from `odin.export_protocol_snapshot`
-or a thin prompt that directs the agent to an MCP-capable host bridge.
-
-ODIN Sentinel does not provide hosted inference and should not cost the
-maintainer money when users run it locally. See
-[docs/reference/cost-and-privacy.md](docs/reference/cost-and-privacy.md).
-
-## Startup Defaults
-
-Fresh startup returns an executive office plus one development pod unless the
-user or a handoff overrides it.
-
-Executive office:
-
-- `A/EXEC-PM`
-- `A/EXEC-ODIN`
-- `A/EXEC-ASST`
-- `A/EXEC-RSCH`
-- `A/EXEC-QA`
-
-Development pod:
-
-- `<TEAM>/TEAM-PM`
-- `<TEAM>/ODIN`
-- `<TEAM>/DEV-1`
-- `<TEAM>/QA-1`
-- `<TEAM>/SHADOW-1`
-
-## Closeout Modes
-
-- `PARK_FOR_CONTINUITY`: keep role slots open and park occupants.
-- `FULL_SESSION_SHUTDOWN`: quit occupants, verify exit, and close panes except
-  the final user-designated surface.
-
 ## Development
 
-Source layout:
-
-- `src/bin/` - stdio entry point
-- `src/mcp/` - MCP resource and tool adapter
-- `src/protocol/` - ODIN protocol loading, packet construction, and validation
-- `protocol/` - portable protocol data
-- `docs/guides/` - onboarding and starter team guidance
-- `docs/reference/` - compatibility, distribution, cost, and privacy notes
-- `scripts/audit/` - package and public-surface release checks
-
 ```bash
+pnpm install
 pnpm run typecheck
 pnpm test
 pnpm run build