harness-agent-research

A self-improving agent governance framework for Claude Code. Scaffold it into any repository to get a disciplined, self-correcting agent workflow:

• Meta-skills (/meta-scope-guard, /meta-anti-patterns, /meta-learn, /meta-commit, /meta-self-audit, /meta-evolve, /meta-critique, /meta-red-team, …) that make the agent scope-aware, mistake-avoiding, and self-reflecting.
• Hooks that structurally enforce governance — hard-block edits before scope is declared, block session end without reflection, enforce memory budgets — not just docs the agent can ignore.
• A memory hierarchy (MEMORY.md root index → sub-indexes → topic files) with byte budgets and an always-load composition law, keeping cross-session knowledge principle- centric instead of bloating context.
• An anti-pattern system (P1–P12 operational principles + an append-only incident log) the agent extends every time it's corrected.

It ships only the reusable core — no domain-specific skills or content. You add your project's skills, rules, and memory on top.

Install

pip install harness-agent-research

Use

From your project root:

harness-agent-research init     # scaffold AGENTS.md + .claude/ + .agent/
harness-agent-research link     # once per machine: link memory for Claude Code

(har is a short alias for harness-agent-research.)

Then commit and open the project in Claude Code — the governance hooks activate automatically.

git add AGENTS.md .claude .agent && git commit -m "feat: add agent governance framework"

What gets scaffolded

your-project/
├── AGENTS.md                     # canonical conventions (Claude reads via .claude/CLAUDE.md; Codex natively)
├── .claude/
│   ├── CLAUDE.md                 # thin @../AGENTS.md import stub
│   ├── settings.json             # hook wiring + permission split (non-destructive allow / catastrophic deny)
│   └── {commands,hooks,memory,rules,scripts} -> ../.agent/*   (symlinks, created by `init`)
└── .agent/                       # the editable home (NOT a Claude Code protected path)
    ├── commands/                 # 14 meta-skills + poe-call + README
    ├── hooks/                    # 6 governance hooks + lib.sh
    ├── scripts/                  # poe_query.py (optional external-LLM helper)
    ├── rules/structure.md        # path-scoped codebase reference (fill in)
    └── memory/                   # MEMORY.md, indexes, anti-patterns/, ops/, workstreams/, …

Why the .agent/ + .claude/-symlink split: .claude/ is a Claude Code protected path (edits there always prompt the user), so the editable surface lives in .agent/ and .claude/ holds only the two files Claude Code reads directly (CLAUDE.md, settings.json) plus symlinks into .agent/. The symlinks are created by init at scaffold time — they are not stored in the wheel (so packaging is free of the "symlinks don't survive a wheel" problem). See .agent/memory/ops/governance-system-reference.md.

After scaffolding

1. Fill in AGENTS.md (Project Overview) and .agent/rules/structure.md (package map).
2. (Optional) export POE_API_KEY (or put it in .env) to enable /poe-call second opinions in /meta-critique and /meta-red-team; otherwise delete .agent/scripts/poe_query.py + .agent/commands/poe-call.md — both skills degrade gracefully to self-critique.
3. Add your own skills via /meta-propose-skill; record work via /track-workstream.

Notes

• Excluded by design: GPU/domain profiling skills, a shared-resource scheduler, and the autonomous-work playbook that depended on them. This is the pure meta core.
• init never clobbers an existing AGENTS.md (it writes AGENTS.framework.md for you to merge) and refuses to overwrite an existing .agent/ without --force.

Develop / publish

pip install -e ".[dev]"
python -m build                       # sdist + wheel
python -m twine check dist/*          # verify metadata
python -m twine upload dist/*         # publish to PyPI

Replace chless in pyproject.toml and AGENTS.md before publishing.

License

MIT — see LICENSE.