agentleFS
strikersamstrikersam/autonomous-ai-agency/AGENTS.md

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

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
  1. Distinctive:

    No "done" without an independent verifier (pstack): Before any task is reported done, by a coding agent or by an agency agent, a verifier …

    line 17
  2. Very specific:

    Investigate before implementing: Use docs-auditor / codebase-explorer first.

    line 246
  3. Distinctive:

    Separate implementation from review: After implementation, run the two reviews independently and read-only.

    line 249

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.md for what duplicated rule sets did to this repo.

Verification rule (mirrored from CLAUDE.md §2, binding on every agent)

<!-- pstack-verification:start -->
  1. 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, or FAIL with a report: what it checked, what it found broken, what was fixed, and the evidence (command output; screenshots for any UI change). FAIL sends the work back: fix every defect it found, then verify again, until it passes. Only PASS or PASS+NOTES permits 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 control TASK_VERIFICATION_REQUIRED). Source: pstack's principle-prove-it-works and 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.py fails 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 → Verify

backend/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.

PathPurposeLinesRisk
backend/server.pyDashboard API server10,666HIGH
proxy.pyMain entry point, auth, rate limit, routing4,116HIGH
agent/loop.pyAgentRunner — plan/execute/verify loop2,940RISKY
packages/ai/router.pyMulti-provider backend with fallback1,988Medium
services/workflow_orchestrator.pyWorkflow execution engine1,940HIGH
services/scanner.pyTech stack scanner (Playwright)1,726Medium
services/company_graph_store.pyCompany knowledge graph persistence1,722Medium
services/ceo_dispatcher.pyCEO delegation + supervised escalation1,083HIGH
packages/config/control_catalogue.pyDeclarative platform-control table1,064Low
direct_chat.pyDirect chat sessions, intent classification892Medium
agent/repowise.pyRepowiseIntelligence — codebase analysis867Low
chat_handlers.pyOpenAI/Ollama streaming handlers866Medium
handlers/anthropic_compat.pyAnthropic API adapter739Medium
router/registry.pyModel capability registry671Medium
services/ceo_micromanager.pyTier ladder, decomposition, subtask briefs643Medium
services/ceo_ledger.pyDurable goal/subtask/attempt record616Medium
router/model_router.pyModelRouter — central routing logic529HIGH
services/ceo_supervisor.py24x7 sweep: close / re-drive / abandon goals497HIGH
agent/web_reach.pyZero-key read-only internet access460RISKY
langfuse_obs.pyLangfuse trace emission451Low
packages/config/settings.pyCentral settings / env resolution415Medium
packages/auth/rbac.pyRole-based access control391RISKY
key_store.pyAPI key CRUD, SHA-256 hashing, persistence305RISKY
services/ceo_quality.pyAnti-slop gate + bounded escalation ladder222Medium
agent/tools.pyWorkspaceTools — filesystem read/write210RISKY
handlers/v3_auth.pyJWT validation177RISKY
router/classifier.pyTask classification172Medium

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.

ModuleRisk
packages/auth/admin.pyAdmin session auth, cookie signing
packages/auth/rbac.pyPermission enforcement
packages/auth/oauth.pyGitHub/Google OAuth flows
packages/auth/service_token.pyService-token issuance and checks
key_store.pyAPI key storage, hash operations
agent/tools.pyFilesystem write surface
agent/web_reach.pyOutbound fetch surface — the SSRF boundary
handlers/v3_auth.pyJWT validation
proxy.py auth middlewareRequest 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

ServicePlatformTrigger
Proxy + BackendRender (deploy-backend.yml)Push to master
Frontend SPAGitHub Pages (deploy-frontend.yml, actions/deploy-pages)Push to master
Remote Admin / WorkerCloudflare 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 API

Release

  1. Move ## [Unreleased] to ## [vX.Y.Z] — YYYY-MM-DD in both changelogs.
  2. pytest green.
  3. git tag vX.Y.Z && git push origin vX.Y.Z.
  4. CI runs on the tag; deployment follows.

Full checklist: docs/runbooks/release.md. Run the release-readiness skill first.


Monitoring

EndpointAuthPurpose
GET /healthNoneProcess liveness
GET /api/doctor/publicNoneSystem-level checks
GET /api/doctor/diagnosticsJWTAuthenticated diagnostics
GET /api/pingJWTBackend liveness
GET /api/statusJWTSystem 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/:

AgentScopeSkills it leans on
SecurityVulnerability scanning, auth review, CVE monitoringrisky-module-review, security-review, dependency-audit
QATest coverage, regression detection, CI monitoringtest-first-executor, council-review
ArchitectureModule boundaries, technical debt, ADRsimplementation-planner, modularity-review
DevOpsCI/CD, Docker, Render/Cloudflare deploysrelease-readiness, docs-sync
DocumentationREADME, changelogs, API docs, runbooksdocs-sync, changelog-enforcer
Bug FixReproduce, isolate, fix, test, PRtest-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:

SubagentModelToolsWhy this tier
docs-auditorhaikuRead, Grep, GlobBounded, read-only doc accuracy review
codebase-explorerhaikuRead, Grep, GlobRead-only discovery; explicitly overrides the built-in Explore model choice
feature-implementersonnetRead, Edit, Write, Bash, Grep, GlobRoutine scoped implementation with clear acceptance criteria
verification-reviewersonnetRead, Grep, Glob, BashIndependent, evidence-based correctness check; runs the tests itself (rule 46)
risk-revieweropusRead, Grep, GlobIndependent 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-explorer first; call feature-implementer only 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:

FileContent
.claude/state/active-tasks.mdLive task tracker — injected at session start
.claude/state/NEXT_ACTION.mdNext step, read by scripts/ai_runner.py
.claude/state/agent-state.jsonMachine-readable session state
.claude/state/checkpoint.jsonlOrdered step log
.claude/state/learnings.mdAppend-only session learnings
.claude/state/runner.lockActive 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:

HookBlocks on
pre-commitStaged .env or keys.json; hardcoded SECRET_KEY; Python syntax errors
commit-msgCode changes with no docs/changelog.md entry, unless the subject carries an exempt prefix
pre-pushpytest -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

TopicLocation
The rulesCLAUDE.md §1
Naming, log levels, fixtures, performance targetsENGINEERING_STANDARDS.md
Architecture overviewdocs/architecture/overview.md, ARCHITECTURE.md
Model routingrouter/CLAUDE.md
Agent orchestrationdocs/architecture/agent-orchestration.md, agent/CLAUDE.md
Configurationdocs/configuration-reference.md
Runbooks, ADRs, changelogdocs/
Rules audit — what was cut and why.claude/rules-archive/

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.