Metadata-Version: 2.4
Name: harness-agent-research
Version: 0.1.0
Summary: Scaffold a self-improving agent governance framework (meta-skills, hooks, memory hierarchy) for Claude Code.
Author: chless
License: MIT
Project-URL: Homepage, https://github.com/chless/harness-agent-research
Keywords: claude-code,agent,governance,meta-skills,scaffold
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# harness-agent-research

A **self-improving agent governance framework** for [Claude Code](https://claude.com/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

```bash
pip install harness-agent-research
```

## Use

From your project root:

```bash
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.

```bash
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

```bash
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](LICENSE).
