agent-harness

Agent Harness Plugin

Claude Code plugin that packages agent readiness evaluation, a global behavioral/tooling ruleset, and stage-specific coding methodology skills (planning, implementation, review, commit, pull requests) into a single global package. It also wires up language servers, Ruff and rumdl auto-format hooks, and MCP servers (chrome-devtools, notion).

The CLI tools and language servers below are prerequisites — install them first, then install the harness itself (Installation). The detailed inventory of what the plugin contains is in What's Included and the docs/ reference.

CLI Tools Required

Installation is left to the developer's own environment and package manager; docs/cli-tools.md has concrete install commands.

Tool	Purpose	Install
ast-grep	Structural code search via AST — precise matches, less context bloat	Installation guide
RTK	Terminal output compression (60-90% fewer tokens)	Repository
gh	GitHub integration and ADRs	Installation guide
mergiraf	Syntax-aware git merge driver — auto-resolves AST-equivalent conflicts	Installation guide
uv	Run/manage Python3 (scripts/sync.py, the Ruff hook, any Python)	Installation guide

Language Servers (Claude Code)

The plugin declares its language servers internally (in .lsp.json); the binaries — for Python, Markdown, Bash, TypeScript/JS, HTML/CSS, and Rust — are a prerequisite you install before the Claude setup. See docs/lsp.md for the per-language binaries, their install commands, and how to add a server, and docs/hooks.md for why Python formatting runs through a Ruff hook rather than a second LSP.

Installation

rtk

Install rtk once per client, globally, so its command-intercept hook is active — the hook routes supported commands through rtk automatically, with no per-command discipline needed:

# Claude Code (default agent)
rtk init -g

Check rtk config afterward to confirm the hook is installed (it warns No hook installed otherwise). Later, rtk session shows adoption per session and rtk discover lists specific commands still bypassing it.

git & mergiraf

Configure git to favor linear history and enable mergiraf as a syntax-aware merge driver, so conflicts that are only formatting differences (AST-equivalent) resolve automatically instead of landing on the agent:

git config --global pull.rebase true
git config --global merge.ff only
git config --global merge.conflictStyle diff3
git config --global merge.mergiraf.name mergiraf
git config --global merge.mergiraf.driver 'mergiraf merge --git %O %A %B -s %S -x %X -y %Y -p %P -l %L'

Apply mergiraf to all files globally by adding this line to git's global attributes file (~/.config/git/attributes, git's default — no extra config needed):

* merge=mergiraf

Claude Code

uv run scripts/sync.py

Copies rules/agent-harness.md into ~/.claude/rules/ (a global rule loaded at session start; your own ~/.claude/CLAUDE.md is left untouched unless it is a legacy copy of this ruleset, which is removed) and installs the plugin (skills, the bundled language servers, the Ruff/rumdl hooks, the chrome-devtools MCP dependency, the bundled notion MCP server, and the attribution settings.json). Re-run after every update to this repo, then restart Claude Code to apply.

What's Included

Rules (always-on)

A single consolidated rules/agent-harness.md holds the behavior that applies regardless of which skill is active — guard duty and scope control, documentation currency, conversational register, CLI tooling preferences, and the rules for when each workflow skill is invoked. Detailed, stage-specific procedures live in the skills instead.

Origins are not tracked per rule — they are noted here as inspiration instead: