odin-agent

Use when a completed session needs an agent-environment retrospective: a severity-ranked list of environment improvement candidates, each backed by session evidence. Not for an engineering retrospective from telemetry — use engineering-retrospective.

Use when the user asks to audit or repair agent surfaces — plugin configs, agent definitions, skills, CLAUDE.md/AGENTS.md, docs, prompts, commands, or hooks. Produces a certainty-graded breadth report and applies only HIGH auto-fixable findings with --apply. Not for deep one-skill improvement — use skill-improver.

Use when setting up a repo for agents, adding AGENTS.md, auditing CLAUDE.md, scoring instructions, or pruning long/stale files via a three-check gate. Also handles lean pointer-only AGENTS.md under 100 lines. Not for remote, credential, publish, deploy, or irreversible changes.

Use when loop scaffold files have drifted from their provenance-pinned templates. Converges exactly four auto-fixable files (STATE.md, gate.yaml, loop-budget.md, loop-run-log.md) to template content with pre-write backup and rollback, and reports other drift. Not for remote, credential, publish, deploy, or irreversible changes.

Use when asked to create or refresh a personal mode skill and open a reviewable PR. Mines recent session history for a recurring manual workflow, drafts one self-contained skill file, and opens a PR with evidence. Not for shared repo skills or work that skips human approval.

Use when asked to audit an agent or AI feature for agentic-experience quality. Assesses target source or described behavior against Architecture and Agentic-experience rubrics, records findings with locators or logical bounds, and returns a severity-tiered report with a PASS/FAIL/INCOMPLETE verdict. Not for source or remote-system changes.

Use when the user names one book, course, paper, or source document and asks to distill it into a reusable skill. Classifies the source as procedure or reference, writes an attributed SKILL.md, and proves its routing. Not for a folder of sources — use map-corpus.

Use when prompt-doctrine is duplicated, drifted, or conflicting across output-style embeds and external harness AGENTS files. Strips duplicate directives from persona prefixes, repairs invariant-zone tail drift, classifies harness divergences, and records a divergence ledger before committing. Not for editing the canonical baseline itself.

Use when a human explicitly asks for a full repository agent-compatibility pass. Validates agent configuration surfaces, runs read-only startup and config loading, and returns a scored compatibility report with prioritized fixes. Not for tasks that require source or remote-system changes.

Use when setting up a project, auditing agent command permissions, or asking which read-only bash commands and domains to allow. Inspects repository manifests to detect the tech stack and synthesizes a least-privilege command and domain allowlist that forbids state-modifying commands. Not for remote, credential, publish, deploy, or irreversible changes.

Use when asked to build or review a CLI intended for coding agents and return flag-driven, pipeline-safe, idempotent design advice. Not for running or profiling a CLI — use control-cli.

Use when asked to create a local agent-plugin directory tree. Generates a valid scaffold with a host-specific manifest, entry point exporting the registration API, and standard directory layout, then validates the result. Not for remote, credential, publish, deploy, or irreversible changes.

Use when asked to deduplicate skills or prompt directories, find repeated rules, or check a skill tree for contradictions. Produces a read-only ledger classifying every repetition cluster and conflict candidate with evidence and zero unclassified cells.

Use when someone outside Warp wants to wire a third-party coding agent (Claude Code, Codex, or Cursor) to a Warp Factory MCP endpoint. Provisions a 30-day bearer credential, writes a bearer-token MCP registration in the target harness, reloads it, and verifies protocol-level tool and resource discovery. Not for unattended runs; credential minting requires explicit human invocation.

Use when asked to generate a personal taste skill from local evidence. Produces a <name>-taste skill with 5 evidence-derived anchors and a two-sided charter. Not for applying an existing taste register: use spine. Local writes only.

Use when a repository needs a safety net against force-push, forced refspec, hard reset, forced clean, forced branch deletion, working-tree discard, stash drop/clear, reflog expire, or gc prune; installs a PreToolUse hook exiting 2 on them; plain git push allowed. Not for remote, credential, publish, deploy, or irreversible changes.

Use when asked to draft copy-ready /goal objectives for long-running agents; returns one normalized one-line objective with measurable end state, grounded proof, easy-out invariants, a stop clause, and a Missing list. Not for source or remote-system changes.

Use when the user asks for a handoff, delegation, or clipboard-ready prompt for another agent: a standalone path-free prompt copied to the clipboard, confirmed by title. Not for session-snapshot briefs — use handoff; never remote, credential, publish, deploy, or irreversible.

Use when the user asks to make the skills framework work in a new harness, IDE, or CLI; the run delivers a port whose bootstrap auto-injects every session and passes the captured acceptance transcript. Don't use for remote, credential, publish, deploy, or irreversible changes.

Use when the user wants to compile taste and "this feels wrong" signals into machine-consumable tokens, rules, forbidden combinations, and examples. Elicits concrete cases, classifies each into one of four buckets, and writes a structured rule/pattern document. Not for remote, credential, publish, deploy, or irreversible changes.

Use when onboarding to a repository, capturing costly conventions, constraints, or rationale, or improving AGENTS.md. Produce a grounded AGENTS.md containing only prescriptive, non-derivable rules. Don't use for remote, credential, publish, deploy, or irreversible changes.

Use when changing the wording of a rule in a skill, prompt template, or agent instruction where the change is meant to alter model output. Produces a scored results table comparing each variant against a no-guidance control, with every match hand-verified.

Use when skill or knowledge activation is unreliable, or setup reaches activation reliability. Configures a project-scoped, marker-gated hook and measures affected evals before and after. Don't use for remote, credential, publish, deploy, or irreversible changes.

Use when a button click, dashboard check, or human verdict sits inside an iteration loop. Replaces it with an autonomous gate or moves non-automatable work outside the loop. Don't use for remote, credential, publish, deploy, or irreversible changes.

Use when a human invokes the release gate to prove all 28 ODIN plugins share one canonical version. Emits a per-file comparison and exits non-zero on mismatch. Don't use to edit release metadata or for remote, credential, publish, deploy, or irreversible changes.

Use when asked to create an MCP server to integrate an API or service in Python or TypeScript. Produces a server with typed tools, tests, and a read-only evaluation suite. Don't use for remote, credential, publish, deploy, or irreversible changes.

Use when plan-mode enforcement hooks intercept a plan review or the user runs /plan-review-tune to tune which plan-review questions fire. Persists the tuned question flow to a local question-registry and hook configuration. Not for auditing a plan against code — use plan-review.

Use when a user wants to define patterns the agent should not do; result is structured project docs or agent-rule files listing each prohibited pattern. Don't use for remote, credential, publish, deploy, or irreversible changes.

Use when asked to improve, optimize, rewrite, tune, or port a prompt, skill, or tool description, to build prompt evals, or to audit prompt text for dated instructions. Optimize mode returns a shorter prompt validated on holdout cases; audit mode returns a confidence-ordered findings report and a proposed diff, and applies nothing.

Use when a completed task needs reflection on the invoked skills to propose and apply approved improvements, with explicit human approval before any edit. Not for remote, credential, publish, deploy, or irreversible changes.

Use when asked to review a plugin for marketplace readiness through a read-only audit of every published quality gate. Returns a sectioned pass/fail report with a submission recommendation. Not for reviewing a PR or code diff — use review.

Use when the user asks to set up or configure the agent environment from a fresh or existing clone. Configures credentials, placeholders, and the virtual environment with explicit human confirmation at each step. Not for automated or unattended runs.

Use when installing a third-party automation pack or template repository safely and deterministically. Fetches the source archive, verifies every file against an expected manifest of hashes, applies required transformations using strict unique anchors, checks for destination conflicts, and atomically moves files to the target with a saved rollback manifest. Not for unattended runs; requires explicit human invocation.

Use when asked to configure pstack role-to-model choices so every role maps to an available model. Writes one user-level pstack model rule file. Not for remote, credential, publish, deploy, or irreversible changes.

Use when the user runs /skill-benchmark to score agent skills via LLM judges with baseline comparison, regression detection, and trend analysis, or to compare candidate models on a shared task set in a ranked table with per-model spend tracking. Not for release gating — use skill-benchmark-gate.

Use when a skill change is about to ship and must pass a release gate. Validates gate inputs fail-closed, runs activation and regression cases against an explicit baseline, measures context cost against an explicit ceiling, and emits PASS or FAIL with one issue per failure. Not for scoring without gating — use skill-benchmark.

Use when a user wants agent setup graded from conversation history. Produces an HTML report with 0-10 scores, evidence-cited findings, and ranked suggestions. Not for skill fixing — use skill-improver; not for security scanning — use skill-scanner.

Use when the model is creating or refactoring a skill, faces a SKILL.md over 300-400 lines, or confuses triggering with disclosure. Produces a justified split-or-monolith decision with pointer hygiene and an architecture-eval plan. Not for skill authoring, use writing-skills.

Use when a user asks to scan, audit, or validate a skill for security issues. Runs static analysis on skill files and returns a risk-level assessment with an install recommendation. Not for source-code or infrastructure review—use security-review—or for remote-system changes.

Use when a publisher wants a discoverable, integrity-protected agent-skill catalog served from a domain they control. Builds the discovery index with SHA-256 digests, deterministic flat archives, and verified install commands, then hands the publisher a post-deploy verification checklist. Not for remote mutation or deployment — the publisher deploys the output tree.

Use when the user asks to discover, generate, refresh, or validate skills from the Trail of Bits Testing Handbook or appsec.guide. Not for tasks that require source or remote-system changes.

Use when the user runs /toolchain-health and wants a trustworthy green/yellow/red verdict on the installed toolchain with ranked repairs. Runs the project diagnostic tools read-only under a stated timeout, scores five categories against a threshold table, and presents a weighted composite verdict with a per-category dashboard. Not for tasks that require source or remote-system changes.

Use when asked to audit validation that looks too clean or self-confirming. Identify each independence failure that applies, prescribe its fix, and audit the auditor's own evidence. Not for checking eval leakage — use evaluation-leakage-audit.

Use when a proven watch pattern should become a reusable harness artifact that replays the proven watch behavior with configurable inputs. Don't use for remote, credential, publish, deploy, or irreversible changes.

Use when the user runs /workspace-unfreeze on a frozen path to remove the freeze lock marker so the path is editable again. Resolves the marker from an explicit path or the freeze convention, previews the consequence, and deletes only that marker. Not for automated or unattended runs; requires explicit human invocation.

Use when asked to author or restructure any agent-consumed document so the agent routes and executes predictably. Produces a self-contained document with no stale duplication or unreachable pointers. Not for skill-specific mechanics like invocation choice — use writing-skills.

Use when a SKILL.md or AGENTS.md/CLAUDE.md is being authored, refactored, ported, or upgraded, or the user asks to write a skill, improve one, or fix unreliable skill firing. Not for general agent-consumed documents, use writing-for-agents.