agentleFS
awebaiawebai/aweb/AGENTS.md

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…

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
  1. Very specific:

    Do not copy teammate names, presence timestamps, or current availability into repository or profile instructions.

    line 9
  2. Distinctive:

    Never edit existing migrations.

    line 16
  3. Distinctive:

    Never make work-in-progress or temporary branches.

    line 35
  4. Distinctive:

    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 …

    line 38
  5. Distinctive:

    Run these at the start of each session.

    line 48
  6. Very specific:

    If aw workspace status reports the directory is not bound to a team (no .aw/workspace.yaml, no certificate, etc.), stop and load …

    line 58
  7. Very specific:

    Use aw for coordination work.

    line 72
  8. Very specific:

    Default to mail for non-blocking coordination: aw mail send --to <agent> --subject "<subject>" --body-file <body-path> starts a new thread.

    line 74
  9. Very specific:

    Use chat when you need a synchronous answer: aw chat pending, then aw chat send-and-wait <agent> --body-file <body-path>.

    line 75
  10. Very specific:

    Check aw workspace status before doing coordination work.

    line 77
  11. Very specific:

    Prefer shared coordination state over local TODO notes: aw work ready and aw work active.

    line 78
  12. Distinctive:

    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 …

    line 103
  13. Distinctive:

    Keep changes small and reviewable so others can build on them.

    line 153
  14. Distinctive:

    Do not copy teammate names, presence timestamps, or current availability into repository or profile instructions.

    line 166
  15. Very specific:

    Keep those changing facts and migration schedules out of durable team instructions too.

    line 167

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

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

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 you

If 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 aw for coordination work.
  • Select the acting identity with --identity-home, then AWEB_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 with aw mail reply <message-id> --body-file <body-path>.
  • Use chat when you need a synchronous answer: aw chat pending, then aw chat send-and-wait <agent> --body-file <body-path>.
  • Respond promptly to waiting conversations.
  • Check aw workspace status before doing coordination work.
  • Prefer shared coordination state over local TODO notes: aw work ready and aw 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 inbox and aw chat pending yourself 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 not

Using --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 interpolate

That 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.

Mail

aw mail send --to <alias> --subject "<subject>" --body-file <body-path>
aw mail inbox

Chat

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 -->

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.