NTM

<!-- TOC: Non-Negotiable Rule | Start Here | Action Loop | Action Card | Intent Router | Throughput Doctrine | Pane Targeting | Project Resolution | Automation Rules | Verification Matrix | Failure Handling | Completion | Quick Search | Reference Index | Related Skills -->

NTM is a tmux control plane for multi-agent work. This entrypoint is the operating kernel. Load one linked reference only when the current action needs it.

Non-Negotiable Rule

Discover the live contract, choose the smallest non-interactive surface, act, then verify on the read surface that owns the resulting state.

Never infer success from command acceptance alone.

Start Here

1. Read the target repository's AGENTS.md and README.md.
2. Confirm project/session resolution.
3. Discover only the catalog slice you need:

   ntm --robot-capabilities --capability-compact
   ntm --robot-capabilities --capability-command=send --capability-compact
   ntm --robot-capabilities --capability-search=interrupt --capability-compact
   

4. Bootstrap state:

   ntm --robot-snapshot
   

5. Name the authoritative postcondition before mutating anything.

For older NTM builds without capability filters, use ntm --robot-capabilities and narrow locally.

Mandatory Action Loop

DISCOVER -> SNAPSHOT -> SELECT -> SCOPE -> EXECUTE -> VERIFY -> CLEAN UP

• Discover: Live capability, schema, repo policy, and tool availability.
• Snapshot: Session, panes, source health, work, mail, and locks.
• Select: Least interactive command with a structured result.
• Scope: Exact session, pane references, files, ownership, and blast radius.
• Execute: Prefer robot mode for automation.
• Verify: Owning state surface plus an independent artifact where useful.
• Clean up: Release or hand off locks, claims, pipelines, and sessions.

Re-snapshot after a cursor expiry, degraded-source recovery, or material state transition.

Action Card

Before a state change, answer:

- Target: <project/session and canonical pane refs>
- Contract: <capability/schema checked>
- Evidence before: <cursor, source health, state>
- Ownership: <bead assignee and file reservations>
- Safety: <user pane inclusion, approvals, blast radius>
- Postcondition: <owning read surface>
- Recovery: <retry, interrupt, smart restart, restore, handoff>

If any field is unknown, stay read-only.

Intent Router

Intent	First surface	Load
Install, configure, environment	ntm deps, config	CONFIG, ENV-VARS
Spawn/add/adopt agents	ntm spawn, ntm add	SPAWN
Send or batch prompts	--robot-send	SEND
Inspect state/output	snapshot, tail, inspect	ROBOT-MODE
Pick and assign work	work triage, assign	WORK-AND-ASSIGN
Coordinate files/agents	locks, mail, coordinator	INTEGRATIONS
Recover or resume	diagnose, checkpoint, handoff	TROUBLESHOOTING, DURABILITY
Run repeatable phases	pipeline	PIPELINES
Run reasoning ensembles	ensemble	ENSEMBLE
Operate HTTP/WebSocket API	serve	SERVE
Review policy/approvals	safety, policy, approve	SAFETY
Use human dashboard	dashboard/palette	DASHBOARD
Find exact CLI syntax	live capabilities first	COMMANDS
Run high-throughput coding waves	beads policy + orchestrator	CODE-FIRST-BATCH-VERIFY

For an already-running multi-pane swarm, use /vibing-with-ntm for the tending loop and return here for exact command contracts.

Swarm Throughput and Credit Doctrine

When many panes share one repo and one expensive build path, run the two-phase pump: parallel code-first waves (real code + real tests, syntax gate max, commit immediately) followed by one central batch-verify pass that alone closes work with revision-bound evidence.

PHASE 1 (all panes, parallel): claim -> code+tests -> syntax gate -> commit -> batch_pending -> next
        |  trigger: ready-pool dry | debt ceiling | articulation point | scope frontier | time/risk | rate dip
        v
PHASE 2 (orchestrator, once): commit-flush -> ONE verify over git-derived scope
        -> compile errors first -> cluster failures by file -> rework (same assignee)
        -> re-run green -> gate + close with evidence -> dependents unblock -> next wave

Full mechanics, tracker policy shape, triggers, and enforcement: CODE-FIRST-BATCH-VERIFY.

The pump is only safe on top of honest credit: process artifacts gate named features or don't exist; refusal-only work never closes a positive-capability item; closures cite evidence; metrics predeclare denominators. That incentive layer — including how to encode it into the beads themselves so every swarm agent sees it at claim time — is the vibing-with-ntm skill's HONEST-CREDIT reference; its DOCTRINE-BOOTSTRAP reference is the step-by-step setup (AGENTS.md law, tracker policy, root doctrine bead, AC templates, enforcement canary). Encode both doctrines in the target repo's AGENTS.md before the first wave.

Pane Targeting

Use canonical selectors returned by live robot state:

• %N: stable tmux pane ID.
• W.P: explicit window and pane.
• Bare N: pane index in one-window sessions; window index in multi-window sessions.

Do not assume the user pane is index 0. Both dispatch surfaces exclude user-typed panes by default, but their --all flags differ: robot --all opts the user pane in, while shell ntm send --all broadens to all agent panes and reaches the user pane only with --include-user. Prefer %N or W.P for any state-changing single-pane action.

A malformed, missing, or ambiguous selector is a command error, not an empty successful target set.

Project Resolution

A session is a project name or project--label. The project directory must resolve to the repository NTM, Beads, and Agent Mail should share. Check projects_base, session labels, and the resolved absolute path before claiming work or reserving files.

Do not repair resolution by guessing symlinks or moving repositories. Inspect configuration and follow repo policy.

Automation Rules

• Avoid ntm view, dashboard, palette, and other TUIs in automation.
• Prefer --robot-* output; use --robot-format=toon and --robot-verbosity=terse when supported and context is tight.
• Treat success as authoritative, then inspect error_code and hint.
• Exit 0 means success, 1 means command error, and 2 means unavailable/NOT_IMPLEMENTED.
• Critical arrays must be present as [], never inferred from omission.
• A degraded source is evidence with limits, not permission to invent state.
• Cursors are local to one attention store; checkpoint/handoff artifacts are the portable continuity mechanism.

Spawn and Detached-Session Guardrails

Treat the live capability catalog as the robot-surface count; do not copy a number into automation guidance:

ntm --robot-capabilities | jq '.commands | length'

ntm respawn <session> and ntm kill <session> ask for confirmation. An orchestrator must use --force only after its target and blast radius are explicitly verified; otherwise the command will wait at a prompt and silently stall automation.

For model-qualified launches, use N:model:effort where the agent supports an effort hint, for example --cod=2:gpt-5.6-terra:high. Before using either qualifier in a custom [agents] command, ensure the Go template contains {{.Model}} (or {{.ModelAlias}}) and, for effort, {{.ReasoningEffort}}. NTM rejects a requested qualifier that its template would ignore; fix the template rather than assuming the launch received the setting.

A detached tmux session may begin at 80x24; a wide swarm can leave each pane too small for agent dialogs and even make dialog detection miss wrapped options. Before spawning or tending a large detached swarm, size the window:

tmux resize-window -t <session> -x 420 -y 110

Re-check the actual pane geometry after layout changes; this is an operator environment constraint, not an agent failure.

Verification Matrix

Mutation	Required read-back
Spawn/add/restart	session status plus pane PID/current command
Send/interrupt	target receipt plus fresh pane capture
Bead claim/assign/close	native br show/ready plus assignment state
File reservation	Agent Mail reservation result/conflict list
Pipeline run/resume/cancel	pipeline state/run ID
Lock acquire/release	lock owner/lease state
Checkpoint/handoff	artifact metadata and restore target
Safety approval	policy/token state
Event-producing action	events/digest/attention cursor movement

Use git, Beads, process state, or emitted artifacts as independent evidence when the action is meant to change them.

Failure Handling

1. Preserve the structured error payload and exit code.
2. Re-read the relevant capability/schema when INVALID_FLAG appears; its hint field now carries a did-you-mean suggestion for near-miss flags.
3. Re-resolve session and pane references for not-found errors.
4. For dependency/source degradation, use the documented fallback once and report reduced confidence.
5. For a live agent that appears stuck, diagnose before interrupting or restarting.
6. Never loop indefinitely on mail, CASS, Beads, or provider failures.
7. Never use destructive recovery without the repository's explicit approval protocol.

Completion

An NTM action is complete only when:

• the authoritative read surface proves the intended transition;
• target panes, user-pane policy, and ownership are unambiguous;
• downstream git/Beads/mail/pipeline state agrees where applicable;
• any opened lease, reservation, pipeline, or temporary session is released, completed, or handed off;
• no required command session is still running.

Quick Search

Grep the references instead of loading them whole:

REFS=.claude/skills/ntm/references

# Find the exact flag/command contract
grep -niE "<flag-or-subcommand>" "$REFS"/COMMANDS.md "$REFS"/ROBOT-MODE.md

# Find pump mechanics by keyword
grep -niE "trigger|commit-flush|rework|gate|build-kill|revision" \
  "$REFS"/CODE-FIRST-BATCH-VERIFY.md

# Find closure/claim discipline
grep -niE "actor|close|ready|claim|dep add|cycles" "$REFS"/WORK-AND-ASSIGN.md

# Find recovery for an error string
grep -niE "<error-text>" "$REFS"/TROUBLESHOOTING.md "$REFS"/DURABILITY.md

Reference Index

• CODE-FIRST-BATCH-VERIFY: two-phase swarm pump
• COMMANDS: command catalog and syntax
• CONFIG: configuration and project resolution
• DASHBOARD: human dashboard behavior
• DURABILITY: checkpoint, restore, handoff
• ENSEMBLE: reasoning ensembles
• ENV-VARS: environment controls
• INTEGRATIONS: Beads, BV, mail, locks, CASS
• PIPELINES: pipeline lifecycle
• ROBOT-MODE: robot envelopes and surfaces
• SAFETY: approvals and policy
• SELF-TEST: validation checks
• SEND: targeting and dispatch
• SERVE: HTTP/WebSocket API
• SPAWN: session and agent creation
• TROUBLESHOOTING: diagnosis/recovery
• WORK-AND-ASSIGN: triage and assignment

Related Skills

• /vibing-with-ntm: tend active swarms
• /beads-br, /beads-bv: tracker mechanics and graph triage
• /agent-mail: coordination primitives
• /brennerbot-with-ntm: hypothesis research sessions
• /open-beads-weighted-tmux-agent-sessions: backlog-weighted spawning