AgentWeave
AGENTS.md4 starsChanged 2 months agoApache-2.0View on GitHub
The full guide is CLAUDE.md. Read it. It is not Claude-specific despite the name; it is simply the file this repository's own tooling loads automatically. This file exists because Codex, Kimi, OpenCode and others look for AGENTS.md rather than CLAUDE.md. It deliberately does not restate the guide. Two 500-line documents describing the same repository is how both of them ended up wrong: this one spent weeks documenting a watchdog daemon, a Git transport and a role system that had all…
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 31,439 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 repository19 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- autonomous-prepSkill
- autonomous-sessionSkill
- backlogSkill
- check-buildSkill
- copilot-test-setupSkill
- daily-reviewSkill
- e2e-loopSkill
- handoffSkill
- harness-auditSkill
- harness-refreshSkill
- night-briefingSkill
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- resumeSkill
- review-iterationSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Do not run the product against this checkout.
- Very specific: line 21
Do not invoke aw-* skills here.
- Distinctive: line 31
Read this before proposing anything structural.
- Distinctive: line 34
Never mark a task complete because a plan exists.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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 — guide for any AI coding agent working on AgentWeave
The full guide is CLAUDE.md. Read it. It is not Claude-specific despite the name;
it is simply the file this repository's own tooling loads automatically.
This file exists because Codex, Kimi, OpenCode and others look for AGENTS.md rather than
CLAUDE.md. It deliberately does not restate the guide. Two 500-line documents describing the
same repository is how both of them ended up wrong: this one spent weeks documenting a watchdog
daemon, a Git transport and a role system that had all been deleted.
Below is only what you need before you have read CLAUDE.md.
The one thing that catches everybody
This repository is AgentWeave's source code, not a project that runs AgentWeave.
Do not run the product against this checkout. Do not create .agentweave/, agentweave.yml, or
spec/ at the repository root — they read as project state and were deleted once already for that
reason. If you need to exercise the product, do it in testbed/.
Do not invoke aw-* skills here. They are a feature AgentWeave ships to its users. This repository
plans its own work in openspec/.
Where planning lives
openspec/specs/<capability>/spec.md— current behaviour of shipped capabilitiesopenspec/changes/<date>-<name>/— one in-flight change:proposal.md,design.md,tasks.md, andspecs/<capability>/spec.mddeltasopenspec/changes/archive/— completed changesopenspec/explorations/2026-08-02-product-direction.md— why the architecture is what it is. Read this before proposing anything structural; it exists specifically so the scope that was removed is not quietly restored.
Never mark a task complete because a plan exists. Only working, verified implementation closes one.
Deleted, and not to be recreated
watchdog.py, messaging.py, runner.py, transport/local.py, transport/git.py, the role
subsystem, and the collaboration CLI. The Hub owns execution; there is no second runtime, no
filesystem or git collaboration substrate, and the CLI does only what cannot be done from inside the
app.
Verifying your work
pytest tests/ -q # CLI
pytest hub/tests/ -q # Hub
cd hub/ui && npx vitest run # dashboard
cd hub/ui && npx tsc --noEmit
npx openspec validate --specs --stricthub/hub/static/ui is a committed build artefact. If you changed the dashboard, rebuild it and copy
hub/ui/dist over that directory, then confirm with diff -rq.
Skills
Hand-written skills live in .claude/skills/. Claude Code and OpenCode read them there. Kimi reads
.agents/skills/, and Codex reads ~/.codex/skills/ only — it has no project-level discovery at
all, so no arrangement of files inside this repository can reach it. Run make sync-skills to
mirror them out.
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.