autonomous-ai-agency / agent
CLAUDE.md12 starsChanged 29 days agoMITView on GitHub
RISKY MODULE. This package orchestrates multi-step AI task execution and writes files to the filesystem. The invariants you must not break are CLAUDE.md rules 16–20; the SSRF boundary is rule 14; agent/tools.py and agent/web_reach.py are both gated by rule 15. Read those first. This file covers what the package is and how to extend it. The three-role orchestration loop: AgentRunner.run() in loop.py drives the cycle. RepowiseIntelligence in repowise.py provides codebase understanding. WorkspaceTools in tools.py is the only place that writes…
- Reads credentials
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/agents.mdAGENTS.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 CLAUDE.md into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
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 78
Add a dispatch case in _dispatch_tool() — it is checked after the tool registry.
- Very specific: line 79
Document the tool in agent/models.py (ToolCall schema).
- Very specific: line 80
Add tests in tests/test_agent_tools.py, or tests/test_repowise_intelligence.py for intelligence tools.
- Very specific: line 91
Add it to build_tool_prompt() in prompts.py — rule 19.
- Very specific: line 93
Test the module directly, plus one test asserting the registry exposes it (see tests/test_web_reach.py).
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.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
CLAUDE.md — agent/
RISKY MODULE. This package orchestrates multi-step AI task execution and writes files to the filesystem.
The invariants you must not break are
CLAUDE.mdrules 16–20; the SSRF boundary is rule 14;agent/tools.pyandagent/web_reach.pyare both gated by rule 15. Read those first. This file covers what the package is and how to extend it.
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 -->What this package does
The three-role orchestration loop:
Planner → produces an AgentPlan with ordered steps
Executor → applies file changes per step
Verifier → validates each change before it is writtenAgentRunner.run() in loop.py drives the cycle. RepowiseIntelligence in
repowise.py provides codebase understanding. WorkspaceTools in tools.py is the
only place that writes to the filesystem.
Per-role models come from AGENT_PLANNER_MODEL, AGENT_EXECUTOR_MODEL,
AGENT_VERIFIER_MODEL, and AGENT_JUDGE_MODEL, all defaulting to
nvidia/nemotron-3-ultra-550b-a55b (the judge falls back to the verifier's model). Override in .env to test without large
models.
Security surface
tools.py → apply_diff() writes arbitrary content to disk. It resolves paths but
does not enforce a strict root boundary by default — any change to path handling must
keep resolved paths inside self.root, and must never take a raw path from untrusted
input.
loop.py → _local_safety_check() scans generated code for hardcoded secrets (JWT
secret keys, fake user DBs). Add new risky patterns here — OS command injection, eval
— as you find them. The verifier LLM is best-effort and is not a security layer on its
own.
loop.py → _commit_step() auto-commits when auto_commit=True. Never pass an
unsanitised step description as a commit message.
Adding a new tool
Two supported paths. Pick one.
A. Hardcoded dispatch — for filesystem or container operations that need self._mcp
routing or other AgentRunner state (see read_file, write_file, run_command):
- Implement the operation in
tools.py. - Add a dispatch case in
_dispatch_tool()— it is checked after the tool registry. - Document the tool in
agent/models.py(ToolCallschema). - Add tests in
tests/test_agent_tools.py, ortests/test_repowise_intelligence.pyfor intelligence tools.
B. Capability registry — for self-contained capabilities with no AgentRunner state
dependency (see web_reach.py's fetch_url / web_search):
- Implement it as its own module, with its own tests. Fail soft — never raise; return a result dict the model can read.
- Register it with
registry.agent_tool(...)from a_register_*_tools()function called by_register_builtin_tools()incapability_registry.py._dispatch_tool()already checks the registry first, so no dispatch-chain edit is needed. - Add it to
build_tool_prompt()inprompts.py— rule 19. Registration alone is silent. - Test the module directly, plus one test asserting the registry exposes it (see
tests/test_web_reach.py).
Any tool accepting a URL, path, or other externally-influenced target needs its
SSRF/traversal guard before the first network or filesystem call — unsafe_target_reason()
in web_reach.py is the pattern. That is rule 14, and it is not optional.
Testing
| File | Covers |
tests/test_agent_runner.py | AgentRunner integration, via mocks and monkeypatching |
tests/test_agent_tools.py | WorkspaceTools units |
tests/test_web_reach.py | Web Reach capabilities and registry exposure |
pytest -x tests/test_agent_runner.py tests/test_agent_tools.pySkills worth invoking here
risky-module-review (required by rule 15 for tools.py and web_reach.py),
test-first-executor, implementation-planner.
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.

