AgentRig
View as Markdown

Commands

Examples use agentrig as shorthand for npx @doidor/agentrig. path defaults to cwd. All commands are idempotent.

init#

Investigate the repo and install a best-practice agent harness. Non-destructive by default — existing AGENTS.md, .mcp.json, and .agents/rules/ content is preserved.

agentrig init [path]
Flag Purpose
--force Overwrite preserved user files with canonical templates.
--skip-agent Deterministic install — no agentic exploration. CI-safe.
--dry-run Show every file as (new), (preserve existing), or (OVERWRITE) without writing.
--yes Non-interactive (skip all prompts).
--model <id> Model for the investigation step (e.g. claude-sonnet-4.6, gpt-5.5).
--verbose Stream the agent's exploration.

update#

Re-sync newer best practices into an existing harness. Refreshes manifest-managed files (PRINCIPLES.md, harness scaffolding) while preserving AGENTS.md, .agents/rules/, and .agents/wiki/. Validates the result and refuses to leave a broken install in place.

agentrig update [path]
  • --diff — show how preserved files have drifted from canonical (no writes); classified as 🔴 broken / 🟡 stale / 🟢 enhancement / ⚪ mixed with a per-severity summary at the top.
  • --auto-fix — after the refresh, run agentrig fix to repair deterministic A1 failures (broken YAML, unknown model ids) from canonical. Saves you a follow-up command when the audit was previously dropping to PART/FAIL on a refreshed install.
  • --skip-agent — update without the agentic step. The output enumerates every preserved file inline so you know exactly what wasn't reconciled.
  • --dry-run — print changes only.

Decisions for preserved files are recorded in .agentrig/state.json under reconciled[]. The next update skips re-prompting on files you've consciously diverged on — unless canonical has drifted past the hash that was recorded at decision time.

compile#

Project AGENTS.md + .agents/rules/ into every agent surface (.github/copilot-instructions.md, .github/instructions/, CLAUDE.md, .cursor/rules/, MCP configs). Also re-populates the auto-maintained marker blocks in AGENTS.md (<!-- AGENTRIG:skills-inventory:start --> ... :end -->) by walking .agents/skills/ on disk — so both AgentRig-bundled and user-added skills appear.

agentrig compile [path]

fix#

Deterministically repair the install — no agent, no network. Restores broken YAML from canonical and replaces unknown model ids in .agentrig/agents/*.yml with the safe auto fallback. Each modified file is backed up to <path>.bak before the change.

agentrig fix [path]
  • --dry-run — show what would change without writing.
  • --json — machine-readable result ({ ok, actions[], unresolved[] }).

Tracks the same validators that agentrig update --auto-fix runs at the end of an update.

eval#

Evaluate the harness itself. Defaults to the full agentic run; use --static for a fast, deterministic structural audit (Layer A1 + A2).

agentrig eval [path]
Flag Purpose
--static Structural completeness + quality probes only — no model. CI-safe.
--scaffold Generate repo-specific scenarios via an agent turn (use --scaffold-count N, default 2).
--include-bundled Also run the generic bundled template scenarios (default: only repo-specific ones run).
--rubric Print measured axes + issue codes + installed scenarios.
--scenario <id> Run only one scenario.
--variant <name> Tag the run (harness vs baseline) for paired-trial lift comparison.
--producer-model <id> Model that executes the scenario task (default: .agentrig/agents/developer.yml model).
--judge-model <id> Model that scores soft axes — must be a different family than the producer (default: .agentrig/agents/reviewer.yml model).
--allow-same-family Override the producer/judge family check (recorded in every result).
--n <int> Trials per scenario (default 1 single, 5 in baseline mode).
--seed <int> Reproducibility seed (passed through where supported).
--timeout <min> Cap per agent turn (default 45).
--min <pct> (with --static) Exit non-zero if Install Completeness < threshold.
--json Machine-readable output.

Evaluating the harness →

doctor#

Health check — harness installed? agent provider reachable? current Install Completeness + Quality Probes scores? Any YAML / model-id validation failures? Any judge below the 80% calibration agreement threshold? Plus install provenance (registry vs linked-checkout) and a quick npm-latest comparison so you notice if your local agentrig is stale.

agentrig doctor [path]      # --json for machine output

Exits non-zero if the harness is missing, the agent provider is unreachable, validation reports any blockers, or the worst judge is below the calibration threshold.

dashboard#

Agent roster, live GitHub tasks (when available), latest Install Completeness + Quality Probes scores, recent eval runs.

agentrig dashboard [path]
  • --html [file] — write a self-contained HTML dashboard (default .agentrig/dashboard/dashboard.html).
  • --no-tasks — skip GitHub lookups (offline).

Global: --verbose · -h, --help · -v, --version Env: AGENTRIG_PROVIDER (default copilot)