autonomous-ai-agency: Instructions file for Claude Code

CLAUDE.md — Operating Manual

§1 and §2 are the binding ruleset for every AI agent working in this repository — Claude, Codex, Cursor, Aider, or anything else. Read them before changing code. §1 is repo-specific wiring; §2 is agent discipline, extracted verbatim into the production prompts of this repo's own agents. Everything after §2 is reference: facts about the system, not instructions.

The rules live here and nowhere else. AGENTS.md and ENGINEERING_STANDARDS.md hold reference material and point back to this section rather than restating it. If you find a rule duplicated somewhere, delete the copy — duplicated rules drift, and this repo has the scars to prove it (.claude/rules-archive/CONFLICTS.md).

Before opening a source file, query the knowledge graph — it costs a fraction of a Read/Grep pass:

graphify query "how does model routing work"
graphify explain "AgentRunner"
graphify path "OnboardingScreen" "CompanyGraphStore"
cat graphify-out/GRAPH_REPORT.md     # free overview: god nodes, communities
graphify update .                    # refresh after you change things

If graphify is missing: python -m pip install graphifyy && graphify install && graphify update .

---

1. The Rules

44 rules. They survive because an agent that had never read them would get this repo wrong. Generally-good engineering practice is deliberately absent — it is assumed, not legislated. See .claude/rules-archive/ for the audit that produced this list and the 308 statements it replaced.

A. Prime directive

1. Do not change user-visible behaviour that was not requested. If a refactor could alter an output, capture the before/after and revert on any difference.

B. Wiring — where things must go

1. All LLM/provider calls go through packages/ai/router.py (ProviderManager). Never call a provider SDK or HTTP endpoint directly.
2. Every provider implements generate, chat, stream, health, cost, limits.
3. Failover chain is NVIDIA NIM → TokenIn → Cerebras → Groq → Ollama — the recommended_priority in config/models.yaml, mirrored by RECOMMENDED_PROVIDER_PRIORITY in packages/ai/brain_config.py and overridable per deploy by that YAML. NVIDIA leads (not Ollama) because Ollama needs OLLAMA_BASE_URL, unset on the Render free tier. 429 → failover plus exponential backoff; 410 → permanent removal plus long cooldown; 419 → skip that model only and try the next on the same provider.
4. Read environment variables only in config modules: packages/ai/brain.py, packages/ai/brain_config.py, app_settings.py, packages/config/. No os.environ.get() anywhere else.
5. Secrets are environment-only: never written to disk, never logged (not even partially), never in test files.
6. Frontend HTTP goes through the shared axios instance in frontend/src/api.js. No API calls elsewhere in the frontend.
7. One auth system: get_current_user / get_optional_user, _require_admin for admin surfaces, verify_api_key for the proxy surface, X-Service-Token for Telegram→backend only.
8. One BrainConfig model, in packages/ai/brain_config.py. The scheduler decides and workers execute; workers emit events and never touch the UI.