agency — the discipline operating system for AI agents

One repo. Five systems. Every conclusion carries its own evidence chain.

Frameworks teach agents to act. Nothing makes them accountable. Agent output today has an honesty problem that no model upgrade will fix: research reports that sample 11 of 260 items and call it "audited", skill libraries that rot silently, "done" that means "I wrote a report about it", and AI sessions whose history nobody can prove wasn't rewritten.

agency is a zero-dependency monorepo that bolts a discipline layer onto any agent workflow:

              ┌──────────────────────────────────────┐
              │  protocol/  — 4 small contracts      │
              │  patches · three-state · coverage ·  │
              │  ledger-format                       │
              └───────┬──────────────────────────────┘
   agency audit ──────┤  six gates + source authenticity (HTTP HEAD→GET→SHA-256)
   agency govern ─────┤  skill-library health: graph, orphans, hubs, conflicts
   agency guard ──────┤  anti-shortcut hooks on completion claims
   agency gate ───────┤  eleven-check pre-release quality gate
   agency forge ──────┤  adversarial evolution engine (37 identities, 9-step loop)
        │                └── ledger/ — tamper-evident provenance chain
        └── one CLI, Python ≥ 3.10, zero dependencies

Why one repo

Because the pieces are useless alone. An audit that nobody re-runs, a patch log nobody can trust, a guard that only guards one script — single-point tools rot. agency is the integration that makes each part load-bearing for the others: forge rounds append to the ledger, audit results can be ledgered, gate won't open without tests, guard enforces the coverage arithmetic audit checks.

Quickstart

# six-gate adversarial audit of a research report
python bin/agency.py audit systems/audit/examples/clean_report.json
python bin/agency.py audit systems/audit/examples/fraudulent_report.json   # exit 1

# library health check (works on any folder of SKILL.md files)
python bin/agency.py govern path/to/skills --html report.html

# check a completion claim for the "sampled 11, claimed 260" fraud
echo '{"text":"Audited all 260 skills. coverage: 260/260."}' | python systems/guard/hooks/sample_coverage_hook.py

# eleven-check release gate
python bin/agency.py gate path/to/repo

# adversarial evolution with provenance chain
python bin/agency.py forge --topic "harden the audit gates" --rounds 10 --repo out
python bin/agency.py ledger verify out/ledger.jsonl

The five systems

System	Catch	Highlight
audit	research reports that lie without technically lying	gate 6 does real verification: cited URLs fetched, content hashed; proxy errors reported as unknown, never misreported as dead
govern	library decay: orphans, hubs, duplicate descriptions	zero-dep semantic near-duplicates (ASCII words + CJK bigrams, TF-IDF cosine, split name/body signals); calibrated on a real 464-skill library
guard	"I audited all 260" when 11 were examined	mechanical exit codes for CI hooks
gate	repos that shouldn't be pushed yet	11 checks incl. sensitivity scan with your own regex list (--sensitive-file)
forge	groupthink: one model debating itself into confidence	37 identities across 6 camps, rotation rules (no repeat, cross-camp), dry-round stop conditions, every round → ledger

The ledger — proof, not vibes

forge writes every round to a hash-chained JSON Lines file. Verify it anywhere, forever:

$ python bin/agency.py ledger verify out/ledger.jsonl
VERIFY OK — 8 records, head df7a58f2daeaa0cc…

Edit one payload, delete one line, reorder anything → VERIFY FAILED (first broken at seq N). Full format spec: protocol/ledger-format.md.

Honest boundaries

• forge ships with a deterministic mock LLM for zero-dep testing; real runs need OpenAI-compatible or Ollama endpoints (--llm openai|ollama). The real adapters ARE tested: local fake endpoints exercise the actual network code path (round-trip, HTTP errors, circuit breaker after 3 consecutive failures, transient-failure recovery), and an optional live-token smoke test runs one real round when AGENCY_LIVE_LLM=1 is set (see systems/forge/tests/test_llm_adapters.py).
• Semantic similarity is a ranking heuristic, not a verdict — it surfaces candidates for human review; it never deletes or merges anything.
• The audit reads report JSON, not minds: it verifies arithmetic, provenance and citation integrity — it cannot verify whether a claim about the world is true beyond its cited sources.

Works with

• nashsu/llm_wiki — real adapter: agency audit on a compiled wiki via systems/audit/adapters/llm_wiki.py (ghost citations, dangling [[wikilinks]], stale summaries).
• Any OpenClaw/Claude-Code-style skill folder — govern works on the stock library without loading your framework.

Collaboration

Read the whitepaper first: docs/whitepaper-zh.md — "Verifiable Evolution: every engine decision becomes a tamper-evident record" (Chinese, CC BY-NC-ND; the code stays MIT).

MIT, free to use. A collaboration unlocks what a public repo cannot:

• Integration — wiring audit/ledger into your research or agent pipeline, end to end
• Calibration — tuning gates and similarity thresholds to your corpus, language mix and failure modes
• Hardening — adversarial review of your own agent output contracts

Write to [email protected] with subject [agency], or open an issue.

License

Code: MIT. docs/whitepaper-zh.md: CC BY-NC-ND 4.0 (dual license by directory).