aweb
AGENTS.md129 starsChanged 4 days agoMITView on GitHub
We use main as the sync branch. Work is done in worktrees. Landing follows the active team instructions (aw instructions show): get an independent review ACK on the exact head, push your branch, and send the coordinator a landing request. Authors do not merge to main. Do not copy teammate names, presence timestamps, or current availability into repository or profile instructions. Resolve current responsibility and reachability from the active team instructions and aw workspace status. We use pgdbm (you probably…
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 32,671 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 repository10 other files it gives its agents.
- code-review-disciplineSkill
- cross-repo-changeSkill
- deploy-awid-siteSkill
- releaseSkill
- aweb-bootstrapSkill
- aweb-coordinationSkill
- aweb-identitySkill
- aweb-messagingSkill
- aweb-tasksSkill
- aweb-team-membershipSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
15 rules. About 0 are common, 7 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 9
Do not copy teammate names, presence timestamps, or current availability into repository or profile instructions.
- Distinctive: line 16
Never edit existing migrations.
- Distinctive: line 35
Never make work-in-progress or temporary branches.
- Distinctive: line 38
When you finish a task, review your change, get an independent review ACK on the exact head SHA, push your branch and send the coordinator …
- Distinctive: line 48
Run these at the start of each session.
- Very specific: line 58
If aw workspace status reports the directory is not bound to a team (no .aw/workspace.yaml, no certificate, etc.), stop and load …
- Very specific: line 72
Use aw for coordination work.
- Very specific: line 74
Default to mail for non-blocking coordination: aw mail send --to <agent> --subject "<subject>" --body-file <body-path> starts a new thread.
- Very specific: line 75
Use chat when you need a synchronous answer: aw chat pending, then aw chat send-and-wait <agent> --body-file <body-path>.
- Very specific: line 77
Check aw workspace status before doing coordination work.
- Very specific: line 78
Prefer shared coordination state over local TODO notes: aw work ready and aw work active.
- Distinctive: line 103
The check is a read-back, not more care: After writing any file you intend to publish, read the bytes back and look for the characters you …
- Distinctive: line 153
Keep changes small and reviewable so others can build on them.
- Distinctive: line 166
Do not copy teammate names, presence timestamps, or current availability into repository or profile instructions.
- Very specific: line 167
Keep those changing facts and migration schedules out of durable team instructions too.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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
We use main as the sync branch.
Work is done in worktrees.
Landing follows the active team instructions (aw instructions show): get an
independent review ACK on the exact head, push your branch, and send the
coordinator a landing request. Authors do not merge to main.
Do not copy teammate names, presence timestamps, or current availability into
repository or profile instructions. Resolve current responsibility and
reachability from the active team instructions and aw workspace status.
We use pgdbm (you probably have a skill, it lives in https://github.com/juanre/pgdbm) for database management.
Never edit existing migrations.
<!-- AWEB:START -->aweb Coordination Rules
This project uses aw for coordination.
This file is not the team's active instructions. Run aw instructions show for the
authoritative version, which carries sections this file does not.
Authority
Active team instructions are authoritative for this team's branch and integration workflow. If a repository or profile copy disagrees, the active team instructions win and the copy is stale. Stop and report the disagreement rather than choosing silently.
Branches and code reviews
Never make work-in-progress or temporary branches. Stay on the worktree and branch assigned to you.
When you finish a task, review your change, get an independent review ACK on
the exact head SHA, push your branch and send the coordinator a landing
request. Authors do not merge to main. Who reviews, what the landing request
carries, the checks you run on the exact head before sending it, and how the
coordinator lands it and gates main are set in the "Branches and code reviews"
section of the active team instructions (aw instructions show). Follow them
there; this file does not restate them.
Start Here
Run these at the start of each session. Order is deliberate: inspect the team, then handle waiting mail and chat so a handoff, blocker, or waiting teammate does not go unnoticed.
aw workspace status # who is online, active team, identity, locks
aw mail inbox # async handoffs, reviews, blockers — process first
aw chat pending # someone may be blocked waiting on youIf aw workspace status reports the directory is not bound to a team (no .aw/workspace.yaml, no certificate, etc.), stop and load aweb-team-membership before doing coordination work.
The canonical source for this order is the aweb-coordination skill. This block
reproduces it so it is available without loading the skill. If the two ever
disagree, the skill wins and this block is stale. Report the conflict rather
than choosing silently. When the skill is not installed, this block is the
startup authority on its own; messaging needs neither the skill nor a profile
service.
This team tracks its work in aweb tasks: after the loop, follow the aweb-tasks
skill's ready/active loop (aw work ready, aw work active) before claiming.
Shared Rules
- Use
awfor coordination work. - Select the acting identity with
--identity-home, thenAWEB_IDENTITY_HOME, then the current directory's.aw. - Default to mail for non-blocking coordination:
aw mail send --to <agent> --subject "<subject>" --body-file <body-path>starts a new thread; answer in the conversation withaw mail reply <message-id> --body-file <body-path>. - Use chat when you need a synchronous answer:
aw chat pending, thenaw chat send-and-wait <agent> --body-file <body-path>. - Respond promptly to waiting conversations.
- Check
aw workspace statusbefore doing coordination work. - Prefer shared coordination state over local TODO notes:
aw work readyandaw work active. - How notifications reach you depends on the integration your session runs: a native aweb channel, a tool hook, or the host's external wake broker. The active team instructions and your instance briefing name the mechanism in use. Respond promptly when notified; when no delivery mechanism is registered for your session, check
aw mail inboxandaw chat pendingyourself at task boundaries.
Shell-safe message bodies
For Markdown, reports, or command examples, write the body to a file and use the
command's --body-file flag.
The hazard is a mechanism, not a surface. Any shell context that
interpolates will expand backticks and $(...) before the program ever sees the
text - and it does so at every layer between your keyboard and the artifact, not
just on the aw command line:
<<EOF interpolates <<'EOF' does not
printf "..." interpolates printf '%s' does not
echo "..." interpolates a quoted heredoc into a file does notUsing --body-file protects the last layer only. A file written by an unquoted
heredoc is already corrupted before aw reads it - this has happened here, in a
document about not trusting unreviewed text, and nothing failed: the writer
reported success and the diff reported the expected line count. Both were true and
neither measured the thing that mattered.
The check is a read-back, not more care. After writing any file you intend to publish, read the bytes back and look for the characters you meant to write:
grep -c '`' <the-written-file> # non-zero => backticks survived, so the context did not interpolateThat works because the corruption and its evidence are the same characters. Note the asymmetry: a zero is only meaningful if you meant to write backticks - for a file that never had any, "none present" cannot distinguish "I wrote none" from "the shell ate them", and that absence is not recoverable afterwards.
aw mail send --to <alias> --subject "<subject>" --body-file <body-path>
aw mail inboxChat
aw chat send-and-wait <alias> --body-file <body-path> --start-conversation
aw chat send-and-wait <alias> --body-file <body-path>
aw chat send-and-leave <alias> --body-file <body-path>
aw chat pending
aw chat open <alias>
aw chat history <alias>
aw chat extend-wait <alias> --body-file <body-path>Identity
aw selects the acting identity from --identity-home, otherwise
AWEB_IDENTITY_HOME, otherwise the current directory's .aw. A selected
identity that cannot be loaded fails; it never falls back to the checkout's
identity. See docs/cli-identity-selection.md for the full contract.
In an OATS seat, run aw from the assigned instance home. Use --identity-home
only when deliberately acting through another authorized identity. Repository
work stays in the assigned worktree. Check aw whoami and aw workspace status
before coordinating.
Teamwork
You are part of a team working toward a shared goal. Optimize for the project outcome, not your individual activity.
- Help teammates when they are blocked.
- Escalate blockers early rather than spinning alone.
- Keep changes small and reviewable so others can build on them.
Who to ask
Roles shown in aw workspace status are each workspace's current operating responsibility on this team.
In the optional aw profile-materialization path, the profile and role label
remain distinct. Setup initializes role_name from the materialized profile, but it remains independently mutable;
changing it does not change which profile the workspace runs or grant additional authority.
Presence shows which workspaces currently carry a responsibility and which are offline.
For OATS-managed homes, consult the soul source and instance briefing for
durable expertise, work mode and the current assignment. A role label does
not establish identity custody or authority in either path.
Do not copy teammate names, presence timestamps, or current availability into repository or profile instructions.
Keep those changing facts and migration schedules out of durable team
instructions too. Resolve current responsibility and reachability from the active team instructions and aw workspace status.
Route coordination, scope questions and handoffs to the currently assigned,
reachable owner. If that owner is offline or shared state contradicts a live
teammate, report the conflict rather than silently choosing a replacement.
For lifecycle disposition, inspect the current supported command:
aw team admin agent-status <name>. Interpret certificate, workspace and
claim results independently, including any explicit unknown or incomplete
result. A missing local path is not retirement; an offline presence entry
does not establish process absence or abandoned responsibility. Preserve
unaccepted learning and outstanding work until their disposition is recorded.
Retire through the supported lifecycle path only within the operator's
authorization, then verify the resulting state independently.
<!-- AWEB:END -->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.

