autonomous-ai-agency
AGENTS.md12 starsChanged 29 days agoMITView on GitHub
The rules are in CLAUDE.md §1. All 44 of them, binding on every agent — Claude, Codex, Cursor, Aider, or anything else. Read that section before changing code. This file is reference: where things are, how big they are, how the system is deployed and monitored. It restates exactly one rule, rule 49 below, mirrored verbatim at the operator's request and kept identical by scripts/check_verification_rule.py. Any other restated rule is a bug: delete the copy — see .claude/rules-archive/CONFLICTS.md for what…
- Reads credentials
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository22 other files it gives its agents.
- docs/agents.mdAGENTS.md
- agent/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- router/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/verification.mdcCursor rule
- agentic-agileSkill
- agentic-portfolioSkill
- client-onboardingSkill
- cooldown-resumeSkill
- drillSkill
- ecc-harness-patternsSkill
- fabric-patternsSkill
- graphiti-temporalSkill
- managed-agents-dreamsSkill
- model-catalogue-updateSkill
- platform-setupSkill
- repowise-intelligenceSkill
- risky-module-reviewSkill
- seo-audit-reportSkill
- user-researchSkill
- video-contextSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
No "done" without an independent verifier (pstack): Before any task is reported done, by a coding agent or by an agency agent, a verifier …
- Very specific: line 246
Investigate before implementing: Use docs-auditor / codebase-explorer first.
- Distinctive: line 249
Separate implementation from review: After implementation, run the two reviews independently and read-only.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — Codebase Map & Operations Reference
The rules are in
CLAUDE.md§1. All 44 of them, binding on every agent — Claude, Codex, Cursor, Aider, or anything else. Read that section before changing code.This file is reference: where things are, how big they are, how the system is deployed and monitored. It restates exactly one rule, rule 49 below, mirrored verbatim at the operator's request and kept identical by
scripts/check_verification_rule.py. Any other restated rule is a bug: delete the copy — see.claude/rules-archive/CONFLICTS.mdfor what duplicated rule sets did to this repo.
Verification rule (mirrored from CLAUDE.md §2, binding on every agent)
<!-- pstack-verification:start -->- No "done" without an independent verifier (pstack). Before any task is reported
done, by a coding agent or by an agency agent, a verifier that did not write the
change tries to break it. It exercises the real artifact (runs the feature, the
tests, the built page; not "it compiles", not the author's own report) and returns
PASS,PASS+NOTES, orFAILwith a report: what it checked, what it found broken, what was fixed, and the evidence (command output; screenshots for any UI change).FAILsends the work back: fix every defect it found, then verify again, until it passes. OnlyPASSorPASS+NOTESpermits a done claim, and the report quotes that verdict. Work in small units that each end in a check. Agency tasks enforce this in code (tasks/verification.py, live controlTASK_VERIFICATION_REQUIRED). Source: pstack'sprinciple-prove-it-worksand its independent per-PR verdict (github.com/cursor/plugins/tree/main/pstack, github.com/michael-denyer/pstack-claude). This rule is mirrored byte-for-byte in every agent instruction file;python scripts/check_verification_rule.pyfails if a copy drifts.
<!-- pstack-verification:end -->Architecture
Client: Claude Code / Cursor / Aider / Continue / Telegram / SPA
│ HTTP (OpenAI / Anthropic / Ollama format)
Bearer Auth / JWT
▼
proxy.py (FastAPI :8000)
Auth → Rate Limit → Route
│
┌────────────────────┼────────────────────┐
/v1/messages /v1/chat/completions /api/*
Anthropic compat OpenAI handlers Ollama native
└────────────────────┼────────────────────┘
▼
router/ModelRouter
classify_task()
▼
Ollama
▲
agent/AgentRunner
Plan → Execute → Verifybackend/server.py (FastAPI :8001) is the second app: dashboard API, company graph,
onboarding, workflow orchestrator, secrets, skills.
Codebase map
Line counts re-measured 2026-08-10 (wc -l). Re-run before trusting them — the previous
version of this table was off by up to 4,179 lines on a single file.
| Path | Purpose | Lines | Risk |
backend/server.py | Dashboard API server | 10,666 | HIGH |
proxy.py | Main entry point, auth, rate limit, routing | 4,116 | HIGH |
agent/loop.py | AgentRunner — plan/execute/verify loop | 2,940 | RISKY |
packages/ai/router.py | Multi-provider backend with fallback | 1,988 | Medium |
services/workflow_orchestrator.py | Workflow execution engine | 1,940 | HIGH |
services/scanner.py | Tech stack scanner (Playwright) | 1,726 | Medium |
services/company_graph_store.py | Company knowledge graph persistence | 1,722 | Medium |
services/ceo_dispatcher.py | CEO delegation + supervised escalation | 1,083 | HIGH |
packages/config/control_catalogue.py | Declarative platform-control table | 1,064 | Low |
direct_chat.py | Direct chat sessions, intent classification | 892 | Medium |
agent/repowise.py | RepowiseIntelligence — codebase analysis | 867 | Low |
chat_handlers.py | OpenAI/Ollama streaming handlers | 866 | Medium |
handlers/anthropic_compat.py | Anthropic API adapter | 739 | Medium |
router/registry.py | Model capability registry | 671 | Medium |
services/ceo_micromanager.py | Tier ladder, decomposition, subtask briefs | 643 | Medium |
services/ceo_ledger.py | Durable goal/subtask/attempt record | 616 | Medium |
router/model_router.py | ModelRouter — central routing logic | 529 | HIGH |
services/ceo_supervisor.py | 24x7 sweep: close / re-drive / abandon goals | 497 | HIGH |
agent/web_reach.py | Zero-key read-only internet access | 460 | RISKY |
langfuse_obs.py | Langfuse trace emission | 451 | Low |
packages/config/settings.py | Central settings / env resolution | 415 | Medium |
packages/auth/rbac.py | Role-based access control | 391 | RISKY |
key_store.py | API key CRUD, SHA-256 hashing, persistence | 305 | RISKY |
services/ceo_quality.py | Anti-slop gate + bounded escalation ladder | 222 | Medium |
agent/tools.py | WorkspaceTools — filesystem read/write | 210 | RISKY |
handlers/v3_auth.py | JWT validation | 177 | RISKY |
router/classifier.py | Task classification | 172 | Medium |
Risky modules
Rule 15 gates these behind the risky-module-review skill. The auth modules moved into
packages/auth/ — the old top-level admin_auth.py, rbac.py, and social_auth.py
paths no longer exist, so any document still naming them is stale and the gate it
describes cannot fire.
| Module | Risk |
packages/auth/admin.py | Admin session auth, cookie signing |
packages/auth/rbac.py | Permission enforcement |
packages/auth/oauth.py | GitHub/Google OAuth flows |
packages/auth/service_token.py | Service-token issuance and checks |
key_store.py | API key storage, hash operations |
agent/tools.py | Filesystem write surface |
agent/web_reach.py | Outbound fetch surface — the SSRF boundary |
handlers/v3_auth.py | JWT validation |
proxy.py auth middleware | Request authentication |
File-size exceptions
Four files are past rule 28's 800-line limit with justification on record. Add to this list rather than silently exceeding it.
packages/config/control_catalogue.py (1,064) is one flat declarative table — the
platform controls an operator can set from the dashboard — with no executable logic. The
types and builders live in control_specs.py and the lookup, grouping, and coercion API
in control_registry.py, both well inside the limit. Cutting the table at a group
boundary would not shrink any reader's working set, only make "where is control X
declared" a two-step question. Revisit if logic accumulates in the catalogue, which is
what the limit exists to catch.
services/ceo_dispatcher.py (1,083) is a pre-existing orchestration hub sitting on
the EXECUTE hot path, so splitting it is a standalone refactor rather than a rider on a
behaviour change. Decompose along the seam the CEO work already exposes: delegation and
planning, supervised execution, ledger writes. services/ceo_micromanager.py was split
at that seam — the judging half became services/ceo_quality.py.
tasks/store.py (854) and agent/skill_registry.py (853) were both
already past the limit on master (833 and 839) when 2026-11-14's event-loop work touched
them; that work added a few lines each and moved no logic. Neither is a split worth
doing as a rider on a behaviour change. tasks/store.py divides along its query methods
(list_*, get_due_soon) versus its write path; agent/skill_registry.py along remote
fetching (_fetch_*) versus the pure text-analysis helpers (_extract_*, _analyse_text),
which need no registry state.
backend/server.py and proxy.py are also over the limit and are being migrated per
REWRITE_PLAN.md. Neither is licence to add more.
agent/loop.py (3,892) is the pre-existing AgentRunner plan/execute/verify loop,
a risky module (agent/CLAUDE.md). The durable side effect recording of the 2026-11
reliability plan added a small net delta to _auto_push_and_pr and keeps its logic
in packages/runs/side_effects.py. Splitting the runner is a standalone refactor; new
logic belongs in helper modules, not here.
Deployment
| Service | Platform | Trigger |
| Proxy + Backend | Render (deploy-backend.yml) | Push to master |
| Frontend SPA | GitHub Pages (deploy-frontend.yml, actions/deploy-pages) | Push to master |
| Remote Admin / Worker | Cloudflare Workers (deploy-cloudflare.yml) | Push to master |
There is no Vercel deployment. Earlier versions of this file said there was; no workflow
has ever referenced it (grep -rli vercel .github/workflows/ returns nothing).
Local development:
source .venv/bin/activate
uvicorn proxy:app --reload --port 8000 # AI proxy
uvicorn backend.server:app --reload --port 8001 # dashboard APIRelease
- Move
## [Unreleased]to## [vX.Y.Z] — YYYY-MM-DDin both changelogs. pytestgreen.git tag vX.Y.Z && git push origin vX.Y.Z.- CI runs on the tag; deployment follows.
Full checklist: docs/runbooks/release.md. Run the release-readiness skill first.
Monitoring
| Endpoint | Auth | Purpose |
GET /health | None | Process liveness |
GET /api/doctor/public | None | System-level checks |
GET /api/doctor/diagnostics | JWT | Authenticated diagnostics |
GET /api/ping | JWT | Backend liveness |
GET /api/status | JWT | System status summary |
LLM traces go to Langfuse (LANGFUSE_PUBLIC_KEY + LANGFUSE_SECRET_KEY), errors to
Sentry when SENTRY_DSN is set, and verbosity is controlled by LOG_LEVEL.
Conditions worth an alert: 5xx rate above 1% over 5 minutes; Ollama health failing for more than 60 seconds; an agent session with no progress for 10 minutes; rate-limit buckets above 80% of capacity; memory above 85%.
Agent roles
agents/ holds 24 specialist profiles. The six with matching slash commands in
.claude/commands/:
| Agent | Scope | Skills it leans on |
| Security | Vulnerability scanning, auth review, CVE monitoring | risky-module-review, security-review, dependency-audit |
| QA | Test coverage, regression detection, CI monitoring | test-first-executor, council-review |
| Architecture | Module boundaries, technical debt, ADRs | implementation-planner, modularity-review |
| DevOps | CI/CD, Docker, Render/Cloudflare deploys | release-readiness, docs-sync |
| Documentation | README, changelogs, API docs, runbooks | docs-sync, changelog-enforcer |
| Bug Fix | Reproduce, isolate, fix, test, PR | test-first-executor, risky-module-review |
Claude Code subagents (cost-aware routing)
.claude/agents/*.md files with YAML frontmatter (name, description,
tools, model) are Claude Code project subagents — orchestrated by a human's
Claude Code session, not by the product runtime. Do not confuse them with two
neighbours: agents/ above holds the 24 product specialist profiles, and the
frontmatter-less files in this same directory (planner.md, implementer.md,
reviewer.md, judge.md) are documentation of the internal
nvidia-model plan→execute→verify loop, which Claude Code ignores because they
carry no frontmatter.
The routing principle: use the smallest model that reliably passes the task's own evaluation. Optimise for cost per accepted task, not raw token cost — a cheaper model whose work is reworked costs more. Model tiers map to task shape:
| Subagent | Model | Tools | Why this tier |
docs-auditor | haiku | Read, Grep, Glob | Bounded, read-only doc accuracy review |
codebase-explorer | haiku | Read, Grep, Glob | Read-only discovery; explicitly overrides the built-in Explore model choice |
feature-implementer | sonnet | Read, Edit, Write, Bash, Grep, Glob | Routine scoped implementation with clear acceptance criteria |
verification-reviewer | sonnet | Read, Grep, Glob, Bash | Independent, evidence-based correctness check; runs the tests itself (rule 46) |
risk-reviewer | opus | Read, Grep, Glob | Independent ship / no-ship judgment over security, privacy, migration, rollback |
Discipline for the orchestrating session (the parent task is the contract):
- Investigate before implementing. Use
docs-auditor/codebase-explorerfirst; callfeature-implementeronly once the plan and acceptance criteria are clear. Do not widen its write scope because a task "sounds small". - Separate implementation from review. After implementation, run the two reviews independently and read-only. Never have multiple agents implement the same feature — that multiplies cost and merge work. Parallelism is for genuinely independent research or review.
- Reserve Opus for difficult architecture, ambiguous failure analysis, or high-risk changes where the added capability is justified by evidence — not by default, and not the reverse (Haiku is not the default just because it is cheaper).
- Verify on evidence, not confidence (rules 45-47). The human owns consequential decisions, approvals, and final ownership (rule 40).
Whether the routing actually pays off is a measured question, not an assumed one.
The harness for it is evals/cost_aware_routing/ (make eval-routing, or
python -m evals.cost_aware_routing --example): a fixed task catalogue and a
cost-per-accepted-task score in which rework and rejected work count against
a cheap model. It ships the instrument, not results — record real runs per its
README and score them; do not quote the illustrative sample as a finding.
Session state
Rules 43 and 44 govern what may be written where. The files:
| File | Content |
.claude/state/active-tasks.md | Live task tracker — injected at session start |
.claude/state/NEXT_ACTION.md | Next step, read by scripts/ai_runner.py |
.claude/state/agent-state.json | Machine-readable session state |
.claude/state/checkpoint.jsonl | Ordered step log |
.claude/state/learnings.md | Append-only session learnings |
.claude/state/runner.lock | Active session lock |
.claude/state/archive/ | Completed task rows, moved out of the live tracker |
The parent directory is tracked in git and team-shared. .claude/state/sessions/<id>/ is
gitignored and is the only place session-private material — anything that may contain the
operator's literal credentials — may go. The convention is documented in
harness/skills/CATALOG.md, and the redaction discipline in the replay-learnings skill.
Git hooks
git config core.hooksPath .claude/hooks activates four blocking hooks. They enforce
mechanically what would otherwise have to be prose:
| Hook | Blocks on |
pre-commit | Staged .env or keys.json; hardcoded SECRET_KEY; Python syntax errors |
commit-msg | Code changes with no docs/changelog.md entry, unless the subject carries an exempt prefix |
pre-push | pytest -x failing |
post-commit | (non-blocking) refreshes the graphify knowledge graph |
.claude/settings.json adds two SessionStart hooks — graphify-refresh and
session-plan-bootstrap — plus a Stop hook that refreshes the graph in the background.
Further reading
| Topic | Location |
| The rules | CLAUDE.md §1 |
| Naming, log levels, fixtures, performance targets | ENGINEERING_STANDARDS.md |
| Architecture overview | docs/architecture/overview.md, ARCHITECTURE.md |
| Model routing | router/CLAUDE.md |
| Agent orchestration | docs/architecture/agent-orchestration.md, agent/CLAUDE.md |
| Configuration | docs/configuration-reference.md |
| Runbooks, ADRs, changelog | docs/ |
| Rules audit — what was cut and why | .claude/rules-archive/ |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

