armenr

debrief

Post-dispatch verification. After a dispatched sub-agent, workflow step, or dispatch-charter (FR-NNNN) returns, verify it actually achieved the intent, that its findings were persisted to disk (not left only in the dispatch's conversation), and that production-reachability holds (IMPL vs WIRED). Updates the traceability ledger + log.md. Use after EVERY dispatch before the orchestrator treats the work as done. Catches the

distill-lessons

Surface candidate lessons (or near-misses) from recent log.md journal entries + session activity — scanning for false-beliefs, over-generalizations, staleness, tool-failures, and near-misses. Writes proposals to .agent-docs/now/lessons/proposals.md for two-step human-gated promotion (maturity seedling→budding→evergreen; provenance llm-draft→llm-reviewed). Use after a failed-then-fixed pattern, a surprising discovery, a runbook's first run, or as part of /handoff.

flush

Mid-session housekeeping. The main agent updates .agent-docs/now/{status,work-plan,open-questions}.md + log.md to current reality, then continues working in the same session. Does NOT regenerate handoff.md, does NOT archive, does NOT auto-commit. Use when work has progressed and now/* has drifted but you're NOT ending the session.

handoff

Capture current session state to a curated artifact at .agent-docs/now/handoff.md plus an archive entry at .claude/handoffs/<timestamp>-<slug>.md. Updates now/status.md, now/work-plan.md, now/open-questions.md, log.md to current reality; sweeps the inter-party obligations ledger both directions (owed-by / owed-to, each receivable carrying a trigger + a default-if-silent) — the standalone now/obligations.md when it exists, else a handoff Obligations section; on multi-party installs, sweeps live inter-agent room threads into a Room-threads continuity block (participants/roles, message anchors, standing hooks, the re-read rule). Accepts optional session notes as arguments. Use at natural checkpoints, before compaction, before session-end, or when context exceeds ~80%. Does NOT auto-commit.

Data & Documents Listed

kit-doctor

Re-runnable Fieldbook health check. Verifies the Claude Code version against the kit's assumptions, that the hooks fire and core.hooksPath is set, that every hook script has a tracked settings.json registration (and every registration a script), that jq/python3/stat are present, that the doc-schema + index lint are clean, and that the install manifest matches what's on disk (flagging drift/missing files). Reports findings and SUGGESTS fixes but mutates nothing without consent. Use when hooks seem inert, after a Claude Code update, after a fresh clone, or any time you want to confirm the install is still live and wired.

kit-upgrade

Reconcile an installed Fieldbook copy against a NEWER kit zip. Reads .agent-docs/.kit-manifest.json, 3-way diffs ONLY kit-owned files (skills/hooks/rules/templates/schema — never the colleague's content dirs), and uses sha256-vs-manifest so a file the colleague edited is treated as "theirs" (shows a diff, never overwrites). Bumps the recorded kit-version. Reconciles the obligations-ledger form (ADR-0012) against re-detected comms posture — promoting a handoff `## Obligations` section into a standalone now/obligations.md, or retiring an empty file back to a section, content-preserving and manifest-recorded. When the manifest is MISSING but the tree is kit-lineage-shaped (hand-seeded / pre-kit port), emits a retro-adoption plan and backfills the manifest instead of stopping. Use when the author sends a newer Fieldbook zip, when a new kit's kit-version.txt is ahead of the installed one, or when upgrading/repairing an existing install. Consent-gated; shows a plan before writing.

orient

Read .agent-docs/now/handoff.md and surface current session state. Use at session start, after time away, or when reorienting ("where are we?"). Pulls live git state at invocation, verifies the handoff isn't stale against git reality (code ahead of docs → trust the code), runs a quick state-file health sweep (the folded-in /status check), surfaces obligations-ledger deltas — landed / came due / overdue / dangling — from now/obligations.md when it exists, else the handoff's Obligations section, and on multi-party installs runs the Room-threads resume step (read the handoff's continuity block, refresh from the comms log since the handoff timestamp, apply the re-read rule before any post).

explain-modelmux

Use when someone wants to understand how modelmux works — why a proxy is needed, what signals it routes on, and how the cascade keeps the orchestrator on Claude while diverting chosen subagents.

getting-started

Use when someone has just cloned modelmux and wants to plug in OpenRouter and see heterogeneous routing working. Walks clone → install → key → run → verify, checking each step.

switch-models

Use when someone wants to change which OpenRouter (or Claude) models the proxy routes to — swapping a model behind an alias, retargeting an agent, overriding at runtime, or checking that slugs are still live.