This page is auto-generated from knowledge/PRINCIPLES.md. To change the principles, edit that file and re-run npm run docs:build.

This is AgentRig's canonical, editable copy of the harness principles. Edit it freely; agentrig update will carry your edits into any repo that uses AgentRig.

A harness is the surrounding scaffolding (orchestration, prompts, skills, memory, evaluation) that lets autonomous coding agents reliably triage → implement → review → judge → merge with minimal human babysitting. AgentRig installs an opinionated harness into any repo, keeps context of what the repo is about, and ships a way to evaluate the harness itself.

Each principle below names the concrete artifact(s) AgentRig installs and how the install-completeness audit and quality probes (agentrig eval --static) score it.

1. Treat the workflow as an explicit state machine#

Every task moves through named states (ingested → queued → implementing → reviewing → judging → ready_to_merge → merged → closed) and every transition declares its trigger. The DAG is the contract; agents do not invent transitions and reviewers cannot skip gates. Artifact: .agentrig/harness/state-machine.yml.

2. Specialize roles, vary models#

Route each state to a role (triager, developer, reviewer, judge), each with a short prompt and its own model_tier. Run the reviewer on a different model than the developer — single-model -bias mitigation matters more than any prompt tweak. A read-only security-reviewer ships as an optional fifth role (it audits the diff for security/privacy risk on a non-developer model). The roster is extensible: add more agent types (designer, release-manager, …) by dropping a <role>.{yml,md} in and wiring a transition. Artifact: .agentrig/agents/{triager,developer,reviewer,judge}.{yml,md} (+ optional security-reviewer.{yml,md}, + README.md) with distinct models.

3. Externalize state in a system of record#

GitHub is the source of truth. Labels are the contract, not decoration. Pollers reconcile the engine against GitHub on a cadence; events drive reactive transitions. If the engine crashes, GitHub still tells you the truth. A dashboard surfaces the live picture: which tasks sit in which state (by label), who they're assigned to, plus harness score and eval status. Artifact: labels/state mapping in the state machine + MCP GitHub server + .agentrig/dashboard/dashboard.mjs (agentrig dashboard).

4. Skills are procedural memory; rules are reflexes#

Skills (SKILL.md with YAML frontmatter for triggers, allowed-tools, argument-hint) encode how to do one thing well. They are composable, auto-discovered, tool-scoped, and mirrored across vendor surfaces (.claude/, .copilot/, .agents/, …). Rules are glob-scoped and auto-loaded when matching files are edited, with an explicit priority order. Artifact: .agents/skills/*/SKILL.md, .agents/rules/*.md + README.md.

5. Self-verify before handoff#

After producing work, the implementing agent runs its own verification loop (build/test/visual) pinned to its own HEAD and decides between iterate, continue, or self-park. The reviewer is only invoked once the producer's loop has converged. Cap iteration attempts (N=3) and fall back. Artifact: .agents/skills/self-verify/SKILL.md.

6. Independent, rubric-driven evaluation#

Score work on explicit axes with credit tiers (0 / 0.5 / 1.0), a mandatory issue code plus evidence whenever a score is < full, and a deterministic aggregator (never hand-edited JSON). This is how you tell whether a prompt change made the agent better or worse — and it is how you evaluate the harness itself. Artifact: .agentrig/eval/ (RUBRIC.md, checks.json, scenarios, score.mjs, static-audit.mjs) and the harness-eval skill.

7. Hermetic per-agent environments#

Each concurrent agent runs in its own git worktree so developers, reviewers, and judges never trip over each other's working trees or lockfiles. A repair script prunes stale worktree metadata before every add. Isolation is a hard prerequisite for multi-agent throughput. Artifact: scripts/repair-worktrees.sh + worktree guidance in the wiki.

8. Continuous self-improvement: every mistake is a prompt bug#

Agents log new gotchas to a tiered memory (central committed wiki → local git-ignored wiki → session scratch). A skill-improver turns reviewer feedback into instruction-surface changes that must pass a prevention test ("would this new wording have changed the original failure?"). Strict admission tests stop duplication from killing the wiki. Artifact: .agents/wiki/ + .agents/skills/skill-improver/SKILL.md.

9. Human-in-the-loop where reversibility is low#

Low-reversibility actions are recommend-then-apply: the agent surfaces proposed changes and waits for explicit apply/approve/skip. Certain labels are human-only gates the agent must never apply or even name. These are deliberate trust boundaries, not friction. Artifact: human-gate declarations in the state machine + rules.

10. Hard limits and safety nets#

Set max_review_iterations, max_diff_chars, a token runaway_cap, and pre_pr/pre_merge hooks. Protected files require a human-override label. A recovery scan re-queues anything stuck too long. These caps keep an agent pool from melting the repo. Artifact: limits: block in .agentrig/harness/state-machine.yml.

11. One canonical source, projected to every agent surface (local + remote)#

The harness keeps one source of truth (AGENTS.md + .agents/rules/ + .agents/skills/) and projects it into each ecosystem's native discovery format so any agent benefits without lock-in — local CLIs and remote/cloud agents:

• GitHub Copilot (remote coding agent + IDE): .github/copilot-instructions.md, path-scoped .github/instructions/*.instructions.md (applyTo globs), and .github/workflows/copilot-setup-steps.yml for the cloud agent's environment.
• Claude Code: CLAUDE.md. Cursor: .cursor/rules/*.mdc. OpenCode/Codex: AGENTS.md.
• MCP mirrored to each surface (.mcp.json, .vscode/mcp.json, .github/copilot/mcp.json).

This is the meta-harness payoff: assign an issue to the web GitHub Copilot agent and it sees the same rules/setup/MCP as your local Copilot CLI, Claude Code, or Cursor. Projections regenerate from the source; never hand-edit the generated files. Artifact: the compiler (agentrig compile) + the projected files above; symlinked vendor dirs for skills.

12. Instructions are the source of truth, not existing code#

A short, unmissable Critical Rules block at the top of AGENTS.md beats a 50-page contributing guide. Pair it with package-local AGENTS.md, golden-principles docs, and a directory map so an agent can answer "what should I do?" without spelunking. Legacy code is not the spec. Artifact: root AGENTS.md with a Critical Rules section + repo context.