agentlaw 0.2.7

Law-first governance kit for AI coding agents: installable scaffold + memory MCP server that lets agents read project rules before they write code.

agentlaw

A law-first governance kit for AI coding agents — install governance structure before writing code.

agentlaw gives any repository a governed starting structure that AI coding agents can read, follow, and maintain. It works for brand-new repositories and already-existing codebases alike. Drop it in, run the bootstrap, and the agent knows what the rules are before it writes a single line.

This repository is the package source and authoring workspace for agentlaw. The installable Python package is published to PyPI as agentlaw; the target-facing public seed lives at paranmir/agentlaw. Most users want the public seed repo or the PyPI package; this workspace develops and releases the kit using the kit (recursive improvement).

---

For Humans

Install

Install from PyPI:

pipx install agentlaw

pipx is the preferred user install path because it gives agentlaw its own managed Python environment while exposing the agentlaw executable on PATH. If pipx is not available on the machine, uv tool install agentlaw is the supported fallback. In either case, host integrations should call the agentlaw executable, not python -m agentlaw.

The default install includes the local embedding runtime dependencies needed by agentlaw's semantic-memory features. The embedding model itself is still stored per target project under .agentlaw/models/ and is downloaded by agentlaw init unless you explicitly choose --skip-model.

For local development from this authoring source tree:

git clone https://github.com/paranmir/agentlaw-workspace
cd agentlaw-workspace
pip install -e .

Quick Start

# 1. Place agentlaw governance into your project
agentlaw init <your-project-dir>

# 2. Register the agentlaw-memory MCP server with your AI agent host.
#    The default `--setup-agents prompt` mode emits LLM-actionable
#    instructions — copy them into your agent and let it edit its host
#    config. Restart the host after the edit lands.

# 3. Open a fresh chat with your AI agent on the project and say:
#       Restore the session
#    The agent loads the harness context and you can start work.

Commands Users Should Know

These are the commands most users need after installing agentlaw from PyPI:

# Install or update the CLI
pipx install agentlaw
pipx upgrade agentlaw
# Fallback when pipx is unavailable on the host:
uv tool install agentlaw
uv tool upgrade agentlaw
agentlaw --version

# If an older 0.1.x install still reports 0.1.5 as current, force pipx
# to ask PyPI directly instead of a stale cache or mirror:
pipx upgrade agentlaw --pip-args "--no-cache-dir --index-url https://pypi.org/simple"

# Bootstrap or refresh a project
agentlaw init <target-project> --setup-agents prompt
agentlaw init <target-project> --merge

# Register, inspect, or repair agent host integration
agentlaw agent-setup --client auto --target <target-project> --verify
agentlaw agent-setup --client codex --target <target-project> --apply --yes
agentlaw setup-status --target <target-project>
agentlaw setup-status --target <target-project> --after-update
agentlaw align --check --target <target-project>
agentlaw align --write --target <target-project>
agentlaw mcp-recover --target <target-project> --client auto --json

# Restore, verify, and operate a target project
agentlaw session-restore --target <target-project> --json
agentlaw memory-runtime-check --target <target-project> --json
agentlaw memory-runtime-repair --target <target-project> --json
agentlaw verify <target-project>
agentlaw run-mcp --target <target-project>
agentlaw now --json

Global installation only makes the agentlaw command available. A project does not opt into agentlaw until someone explicitly runs agentlaw init in that project. After agentlaw init or pipx upgrade agentlaw, run agentlaw setup-status and report the result before claiming the harness is ready. The status report names optional pieces that were not installed, host/MCP pieces that are not activated yet, and the concrete next action for each gap.

MCP host registration uses the installed agentlaw app executable with run-mcp arguments. Do not register a pipx internal venv python.exe or a generic python -m agentlaw; those paths drift when pipx or uv changes its managed environment location. If a host cannot resolve agentlaw, first make the app executable visible to host-spawned processes (pipx ensurepath for pipx, or ensure ~/.local/bin is on PATH for uv tool), restart the host, and rerun agentlaw agent-setup --client <host> --target <target-project> --apply --yes.

When setup-status prints LLM disclosure required, the agent must tell the user the harness is not fully active before doing substantive work. Until MCP tools, Agent Skills, hooks, and runtime restore are confirmed, the agent follows AGENTS.md, the root control documents, and agentlaw_docs/law/* manually; non-trivial plans stay non-executable unless the required plan-review path has run.

When an LLM installs agentlaw for a user, it should not stop at "installed." It should explain the installed command path, whether optional embeddings were installed or skipped, whether the target project was initialized, what setup-status reports about MCP, skills, hooks, and session restore, how the user can restore the next session, and which commands are most likely to matter: agentlaw setup-status --target <target-project> --client auto for readiness, agentlaw session-restore --target <target-project> --json when MCP is not visible, agentlaw mcp-recover --target <target-project> --client auto --json for integration diagnosis, agentlaw verify <target-project> for scaffold integrity, and agentlaw align --check --target <target-project> before claiming routing or README surfaces are current.

What The Main Pieces Do

agentlaw init gives a project its governance scaffold. It writes the constitution, law documents, contracts, planning protocol, memory files, skills, and optional host-registration instructions into the chosen project. This is why installing the CLI alone is not enough: each project must explicitly opt in before an agent should treat it as governed.

setup-status is the readiness check. It tells the agent whether the project scaffold exists, whether the local runtime database is usable, whether optional embeddings are installed, whether host MCP registration appears active, whether skills and reminder hooks are present, and whether session restore can work. It exists to prevent the common false-readiness failure where an agent assumes the harness is active just because the package is installed.

Session restore and session save are the continuity path. Restore loads the working set, current rules, active plans, recent decisions, and memory lookup guidance before the agent answers. Save records the current goal, decisions, warnings, and next actions before handoff or context loss. They exist so the agent does not rely on chat memory or stale local impressions.

The memory layer has two parts: Markdown files are the source of truth, and the runtime index makes those files searchable through MCP. If the index drifts or is missing, repair commands rebuild derived state from the Markdown files. This keeps local project memory inspectable, versionable, and recoverable.

Hooks and Agent Skills are reminder channels. Hooks fire when the host supports prompt-time reminders, and skills route common work such as fix, update, planning, and retrospective closeout to the right documents. They do not replace the law layer; they make it harder for an agent to forget to read it.

agentlaw verify is the drift detector. In target projects it checks that the governance scaffold and runtime shape are intact. In this authoring workspace it also checks package/scaffold consistency, plan-review records, publish-gate coverage, and architecture-map freshness so releases do not ship untracked governance drift.

Ideas And Influences

agentlaw is not a fork or reimplementation of these projects. The links below name ideas that shaped the product:

• OpenAI Harness Engineering: agent-first harness design across context, tools, memory, checks, and recovery paths.
• OpenAI Agent evals: traceable, repeatable agent-behavior oracles.
• Ouroboros: What is an agent harness?: harness vocabulary and the two-step review/delivery flow: validate the plan, then verify delivery before archive.
• Hermes Agent and its learning loop: post-task retrospective route for skill, law/contract, test/verifier, memory/reference, tracker, or chat-only output.
• Wang et al., "Label Words are Anchors": rubric anchors that calibrate reviewers without narrowing judgment to listed examples.
• JuliusBrussee/caveman: the concise-accuracy rule; keep identifiers, paths, commands, and failure conditions while removing filler and self-narrating history.
• Agent Skills: small discoverable task descriptions with full procedures loaded only when needed.
• Model Context Protocol: explicit tools, resources, prompts, logging, and trust boundaries instead of hidden chat memory.

Harness Workflow

Use agentlaw as an operating loop, not only as a command set:

1. Restore context at the start of a session with agentlaw_session_restore or agentlaw session-restore --target <target-project> --json.
2. State the task and let the agent classify whether it is trivial, plan-required, fix/init/update, or release/deploy-adjacent.
3. For non-trivial work, require a reviewed plan before execution. The plan review selects the right persona review passes, records user gates, and names acceptance oracles.
4. Execute the reviewed plan, then run the listed oracle checks, agentlaw verify <target-project>, and any focused tests before archiving the plan.
5. Save session state with agentlaw_session_save at milestones and before context compaction.

When to use init, update, fix, and align

• Use AGENTLAW_INIT_TOOL.md when bootstrapping agentlaw into a new project or re-initializing a project scaffold.
• Use AGENTLAW_UPDATE_TOOL.md when the installed kit or scaffold has changed and an existing project needs those upstream harness updates merged without losing local project facts.
• Use AGENTLAW_FIX_TOOL.md when the harness is drifting, a tracker-policy violation happened, the agent bypassed a rule, MCP/memory state looks inconsistent, or the same governance failure repeats.
• Use AGENTLAW_ALIGN_TOOL.md and agentlaw align --check --target . when local laws, root controls, directories, or command surfaces changed and routing/README surfaces may be stale. Use agentlaw align --write --target . only for safe routing updates reported as autofixable.

These four root tools exist because different work needs different safeguards. Init creates a first scaffold. Update merges a newer shared kit into an already-localized project without erasing local law. Fix closes observed governance gaps by choosing the owning layer and the least sufficient correction. Align repairs routing surfaces after the rules or command surface move, so agents and humans keep entering through the same path.

Plan, Persona, And Oracle Review

The normal non-trivial path is plan first, execution second, oracle last. A plan states the task contract, affected surfaces, user gates, risks, rollback paths, and acceptance criteria. The persona review checks that plan from specific lenses such as trigger coverage, acceptance criteria, affected surfaces, external contracts, user gates, and form-vs-substance. The oracle phase checks whether the completed work satisfies the plan's criteria before the plan is archived.

The plan-review gate is intentionally strict. The interview step must be based on a real user touchpoint, and persona review starts only when the agent can defend very high clarity about the goal, constraints, success conditions, and context. Self-challenge is allowed to change the plan before it becomes final; it is not just a note-taking step. After implementation, oracle checks can run normally or be started and checked later for long-running work, so the agent does not need to repeat expensive checks in one blocking call. The archive step writes closure evidence into the completed plan and refuses to move the plan if checks are still pending, failing, or recorded in an unauditable shape.

For code changes, the expected evidence loop is focused tests while editing, then one full project pytest run at final readiness before commit, release, or any public-ready claim. Evidence-only closeout work should use the harness verifier and the relevant focused checks instead of rerunning the full suite.

If the harness looks broken

First ask the agent to restore context again. If MCP or host integration still looks wrong, run:

agentlaw setup-status --target . --client auto
agentlaw session-restore --target . --json
agentlaw mcp-recover --target . --client auto --json
agentlaw memory-runtime-check --target . --json
agentlaw memory-runtime-repair --target . --json
agentlaw verify .

If the problem is repeated, rule-related, or affects the agent's ability to follow the harness, treat it as fix-class work and tell the agent to start from AGENTLAW_FIX_TOOL.md.

Host reminder hooks and skills

agentlaw init can register host-side reminder hooks that run agentlaw user-prompt-hook before an agent handles a user prompt. Supported hosts use their normal configuration paths: Claude Code uses .claude/settings.json, and Codex uses .codex/config.toml. The hook is a reminder channel only; governing content remains in the root tools, agentlaw_docs/law/*, agentlaw_docs/contracts/*, and agentlaw_docs/planning-protocol/*.

The scaffold also ships Agent Skills for common host conventions:

• .agents/skills/agentlaw-governance/ and .claude/skills/agentlaw-governance/ route fix/init/update/governance work to the matching root control document.
• .agents/skills/agentlaw-plan-authoring/ and .claude/skills/agentlaw-plan-authoring/ route plan creation, review, execution, oracle, and archive work to the planning protocol.

The duplicated skill directories are compatibility paths for different agent hosts, not separate rule systems.

Memory layout

The canonical memory layer is Markdown under agentlaw_memory/*:

• agentlaw_memory/working-set.md stores the current goal, next actions, open questions, and handoff state.
• agentlaw_memory/LOOKUP_RULES.md tells agents when to use memory tools versus current repository reads.
• agentlaw_memory/known-facts/ stores durable facts about current project state.
• agentlaw_memory/logs/ stores append-only decisions, corrections, session saves, and verification notes.
• agentlaw_memory/rules/ stores project-local behavioral rules below shared law.
• agentlaw_memory/preferences.md stores user or maintainer preferences.

Derived runtime state belongs under .agentlaw/, including .agentlaw/index/meta.db and any downloaded embedding model. .agentlaw/ is rebuildable runtime state, not the source of truth.

Using agentlaw in Your AI Coding Session

Once agentlaw is initialized in a project and the agentlaw-memory MCP server is registered with your AI agent host, you drive the harness through natural-language triggers in your conversation. The agent maps each trigger to one of the harness's MCP tools and follows the procedure that the kit ships.

Triggering session restore — at the start of any new conversation on the project, say one of:

• "Restore the session" / "세션 복원해봐"
• "Pick up where we left off"
• "지금 어디까지 했어?"

The agent calls agentlaw_session_restore, the response packet carries the project's working set, every active plan body, the most recent session_save log entry, framework reminders (memory intent rule, write discipline, consult-before-answer rule), and a step-by-step reminder of the §Canonical Restore Route Mandatory Tier the agent must follow before answering. The first turn of every session is a context-loading turn; substantive work starts on turn two.

Triggering session save — when ending a session, before context compaction, or at any milestone, say one of:

• "Save the session" / "세션 저장해줘"
• "Wrap up and save state"
• "Snapshot what we did"

The agent calls agentlaw_session_save with the working frame, and the save tool surfaces a post-save verification obligation that you run after.

When something feels off — if the agent appears to be answering with stale context or missing rules, ask it to call agentlaw_session_restore again, or run agentlaw mcp-recover --target . --client auto --json to diagnose MCP connectivity from the shell side.

Multi-project usage

Install agentlaw once with pipx install agentlaw, then bootstrap each project independently with agentlaw init <dir> --setup-agents prompt so semantic memory is available by default. Use --skip-model only when the target already has a complete embedding model or the user explicitly chooses an FTS-only path. Each initialized project gets its own <dir>/.agentlaw/index/meta.db; the memory index is not shared across projects.

Host registration scope differs by agent host:

Host	Registration scope	Multi-project behavior
Claude Code	local, per-project and keyed by project path	each project sees only its own .agentlaw/index/meta.db
Gemini CLI	project-local .gemini/settings.json	each project sees only its own .agentlaw/index/meta.db
Codex	user-level, one global entry	the registration omits --target; agentlaw run-mcp resolves the target from the cwd where Codex is opened

For Codex, the global MCP entry only makes agentlaw available to Codex. It is not project setup. When Codex is opened in a project that has not explicitly run agentlaw init, agentlaw run-mcp exits instead of creating .agentlaw. agentlaw verify checks target scaffold integrity; it does not enforce host MCP scope. Use agentlaw agent-setup --verify to check the host registration contract.

What This Project Is

The problem. AI coding agents arrive at a repository without governance. They make plausible-looking changes that violate invariants the team has not written down. The team adds a CLAUDE.md or AGENTS.md to capture rules; the file grows; the agent reads less of it; the rules silently stop applying. The agent and the team need shared structure they can both rely on.

The kit. agentlaw installs that structure as governance scaffolding: a constitution, a law layer (memory, artifact, oracle, failure rules), root control tools (init / update / fix / align), contract documents, a memory subsystem (working set, logs, rules, preferences), and a runtime MCP server that surfaces the rules every session. The agent reads the law before it writes; the kit's verifier mechanically catches drift between the rules and the code.

Recursive improvement. This authoring workspace develops agentlaw by using agentlaw on itself. Every plan that lands here goes through AGENTLAW_INIT_TOOL.md / AGENTLAW_UPDATE_TOOL.md / AGENTLAW_FIX_TOOL.md / AGENTLAW_ALIGN_TOOL.md rules; shared law changes are reflected in the bundled package scaffold under src/agentlaw/scaffold/; routing and README drift is checked with agentlaw align --check --target .; the same agentlaw verify that ships to target projects also runs against this repo. The kit's failures and improvements both surface here first.

Requirements

• Python 3.11 or newer (the kit uses typing.Literal unpacking and other 3.11-era stdlib features).
• Operating systems: developed on Windows; Ubuntu and macOS are exercised through the publish-readiness CI matrix.
• Disk: the optional embedding model occupies roughly 500 MB once downloaded (cached under <your-project>/.agentlaw/models/).
• Runtime dependencies are declared in pyproject.toml under [project] dependencies (currently typer, mcp, sqlite-vec, PyYAML, sentence-transformers, and huggingface_hub). The embeddings extra remains only as a compatibility alias for older setup commands.
• Dev dependencies (pip install -e ".[dev,test]"): build, pytest, mutmut, and hypothesis.

Authoring Verification

For this authoring workspace, install development dependencies into the Python environment you intend to use, then run. On Linux hosts that do not expose a bare python command, use python3 or uv run python explicitly:

python -m pip install -e ".[dev,test]"
python -m pytest
python verify_agentlaw.py
uv run --extra test python -m pytest

For a project initialized by agentlaw, use the target verifier instead:

agentlaw verify <target-project>
python -m agentlaw verify <target-project>

Ubuntu and macOS do not need to be available locally. The repository's Compatibility checks GitHub Actions workflow uses GitHub-hosted Windows, Ubuntu, and macOS runners for the cross-platform baseline. The macOS job intentionally creates a venv from Homebrew Python and verifies sqlite loadable extension support before installing agentlaw, because sqlite-vec requires that Python capability. Treat non-Windows support as CI-ready until that workflow has actually run and passed.

Repository Layout (this authoring workspace)

agentlaw-workspace/
├── AGENTLAW_CONSTITUTION.md         # highest authority
├── AGENTLAW_INIT_TOOL.md            # bootstrap entry
├── AGENTLAW_UPDATE_TOOL.md          # update flow
├── AGENTLAW_FIX_TOOL.md             # gap-fix flow
├── AGENTLAW_ALIGN_TOOL.md           # local routing/readme alignment flow
├── AGENTS.md                       # routing-only entry map
├── README.md                       # this file
├── agentlaw_docs/
│   ├── law/                        # law layer
│   ├── contracts/                  # contract documents shared with target projects
│   ├── references/                 # local references (binaries gitignored)
│   └── plans/                      # active and completed plans
├── .agents/skills/                 # Codex-compatible agent skills
├── .claude/skills/                 # Claude Code-compatible agent skills
├── agentlaw_memory/                         # derived continuity (logs, rules, working-set)
├── src/agentlaw/                # Python package (CLI, MCP server, init, verify, scaffold)
├── agentlaw_tests/                          # pytest suite
├── sync_package_data.py            # shared docs → bundled scaffold sync
└── verify_agentlaw.py               # workspace integrity verifier

Links

• Public seed (target-facing starter content and release notes): https://github.com/paranmir/agentlaw
• PyPI: https://pypi.org/project/agentlaw/
• This authoring workspace: https://github.com/paranmir/agentlaw-workspace
• Issues: https://github.com/paranmir/agentlaw/issues

---

For AI Agents

This section is the agent-facing reading order for first-time entry into the kit. If you are reading this README as a new session on a project that has agentlaw installed, follow the §Canonical Restore Route Mandatory Tier in agentlaw_docs/law/MEMORY_AND_CONTINUITY_RULES.md instead — that procedure is the binding one. This README is the on-ramp; the law file is the substance.

Agent Bootstrap (first install)

When the user asks you to set up agentlaw in a project:

1. Install agentlaw from the approved source. Published path: pipx install agentlaw; fallback when pipx is unavailable: uv tool install agentlaw. For an existing 0.1.x install, use pipx upgrade agentlaw and verify with agentlaw --version; if the environment still reports 0.1.5 as latest, use pipx upgrade agentlaw --pip-args "--no-cache-dir --index-url https://pypi.org/simple" so pipx queries PyPI directly. Authoring-source development path: pip install -e . from this workspace.
2. Run agentlaw init <target-project> --setup-agents prompt only after the user chooses that target project for agentlaw. Use --skip-model only when the target already has a complete embedding model or the user explicitly accepts FTS-only memory search. The prompt default emits LLM-actionable instructions for registering the agentlaw-memory MCP server in your host config; read those instructions and edit your host config rather than letting init auto-write to user-level config (that requires --setup-agents auto --yes).
3. Restart your host after the config edit so the new MCP registration is picked up.
4. On the next agent session, call agentlaw_session_restore (MCP) or agentlaw session-restore --target . --json (CLI fallback) and follow the §Canonical Restore Route Mandatory Tier in the response.
5. If the MCP server is not visible in a new session despite restart, run agentlaw mcp-recover --target . --client auto --json to diagnose runtime + registration state.

Layer-by-layer map (what each artifact class is for)

• AGENTLAW_CONSTITUTION.md — highest authority; structural invariants. Rare changes; never violate.
• Root control tools (AGENTLAW_INIT_TOOL.md, AGENTLAW_UPDATE_TOOL.md, AGENTLAW_FIX_TOOL.md, AGENTLAW_ALIGN_TOOL.md) — agent-facing procedure documents. Init bootstraps a fresh project, Update incorporates kit upgrades into an existing target, Fix runs the gap-resolution protocol, Align reconciles local routing/readme surfaces after harness structure or command surfaces change.
• agentlaw_docs/law/* (law layer) — rules every session reads: memory and continuity, artifact rules, oracle and judgment, code authorship and stewardship, failure taxonomy, mechanical enforcement policy, starter specialization rules, scope, input/output contract.
• agentlaw_docs/contracts/* — boundary surfaces shared with target projects (MCP tool surface, shared baseline, update workflow). Distributed through the bundled scaffold.
• agentlaw_docs/references/* — research-and-context references; not authoritative.
• agentlaw_memory/* — derived continuity (working-set, logs, rules, preferences, lookup rules). Below law in authority.
• agentlaw_docs/plans/active/* and agentlaw_docs/plans/completed/* — work-in-flight and historical work. Active plans are read-on-restore.

Governing hierarchy

Authority flows top-down:

1. AGENTLAW_CONSTITUTION.md
2. Root control tools
3. agentlaw_docs/law/* (law)
4. agentlaw_docs/contracts/*
5. agentlaw_docs/references/* (non-authoritative)
6. agentlaw_memory/*
7. AGENTS.md (routing only — never a rule store)

When two artifacts seem to conflict, the higher one wins. Memory never overrides law; references never override contracts; AGENTS.md is the entry map, not a source of rules.

Restore procedure on every session start

§Canonical Restore Route Mandatory Tier (full body in agentlaw_docs/law/MEMORY_AND_CONTINUITY_RULES.md) requires 14 steps before composing a substantive response. Summary: confirm runtime integrity, read the working set, read every law file, read every active plan body, read the most recent session_save log entry, scan recent_logs titles, read every active rule's body, read agentlaw_memory/preferences.md, read agentlaw_memory/LOOKUP_RULES.md, scan the known-facts manifest, run a working-frame memory_search over current_goal + next_actions + open_questions, inspect governance drift, assemble the packet, surface gaps to the user. The runtime pre-fetches body fields into the restore packet so the substance is in your context without extra Read calls; the procedure is binding regardless.

Critical rules — quick reference

One-line restatements; the binding text lives at the anchors.

• Memory Intent Rule — when the user expresses intent to remember, persist, or carry forward, resolve to one of memory_write / promotion_proposal / associative_marker / explicit_non_save before final response. Anchor: agentlaw_docs/law/MEMORY_AND_CONTINUITY_RULES.md §Memory Intent Rule.
• Write Discipline — silence is a valid answer; a write must clear the §Log Write Criterion three-question gate (and the §Item Write Criterion applicability gate for items). Volume is not the target; selectivity is. Anchor: §Write Discipline.
• Read Routing Criterion — classify the question (prior judgment / cross-session / current source) before reaching for memory_search vs Grep/Read. Anchor: §Read Routing Criterion.
• Consult-Before-Answer Rule — for memory-routed questions, consult memory before composing the answer, not after. Anchor: §Consult-Before-Answer Rule.
• Self-Narration Prohibition — governed artifact bodies and code comments describe current state only; revision history lives in plans, tracker entries, memory logs, and git, not in the body. Anchor: agentlaw_docs/law/REPOSITORY_ARTIFACT_RULES.md §Self-Narration Prohibition (paired with §Reasoning-Critical Inline Comments in CODE_AUTHORSHIP_AND_STEWARDSHIP_RULES.md).
• Promotion Proposal Protocol — runtime never selects promotion candidates; the agent judges whether durability + future operational relevance + authority gap all hold, then calls memory_propose_promotion. Anchor: §Promotion Proposal Protocol.

---

License

MIT. See LICENSE.