aweb-coordination
Skill129 starsChanged 4 days agoMITView on GitHub
This skill should be used when working in an aweb-coordinated team — checking what teammates are doing, taking manual locks on contested resources, reading or setting shared team roles and instructions, deciding when to create separate worktrees/workspaces with explicit git + aw primitives, and deciding whether to record coordination in shared aweb state versus private notes.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- code-review-disciplineSkill
- cross-repo-changeSkill
- deploy-awid-siteSkill
- releaseSkill
- aweb-bootstrapSkill
- aweb-identitySkill
- aweb-messagingSkill
- aweb-tasksSkill
- aweb-team-membershipSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
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
- Distinctive: line 29
Run these at the start of each session.
- Very specific: line 39
If aw workspace status reports the directory is not bound to a team (no .aw/workspace.yaml, no certificate, etc.), stop and load …
- Distinctive: line 43
Before starting work or sending a message, get the team's current state.
- Distinctive: line 70
When an incident needs service evidence, check the deployment-owned documentation for the selected provider/resource, available tools and …
- Distinctive: line 80
If authority is missing, stop before loading credentials or calling the service and identify the exact operation whose authorization is …
- Distinctive: line 83
Keep credential input in private memory or the deployment's approved mechanism.
- Distinctive: line 182
When the human (or another agent) needs a second working copy of the same repo — to run a parallel agent without disturbing your own …
- Very specific: line 193
Ask an existing team member for aw team invite when this new worktree needs a fresh local identity.
- Distinctive: line 197
Use worktrees when work is happening in parallel against the same codebase.
- Distinctive: line 210
Read these only when deeper context is needed:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
aweb Coordination
Use this skill when sharing work with a team of agents through aweb. Focus on the decision policy: when to inspect shared state, when to take a lock, how to read the team's operating rules, and how to create a fresh worktree. Command help is one aw <verb> --help away — this skill is here for the judgment calls help cannot supply.
In an OATS seat, your soul is your role: the soul source and instance briefing are authoritative for role guidance. OATS seats do not use aw roles. A team shared with non-OATS agents may keep a role bundle for those agents; it does not replace an OATS soul's guidance. Team instructions still supply the team's shared operating rules.
For mail/chat response policy, load aweb-messaging. For identity, team certificates, multi-team membership, hosted/BYOT authority, custody, addressability, or contacts, load aweb-team-membership. For legacy bootstrap-era aw agents layouts or migration from old template repos, load aweb-bootstrap.
What aweb gives the team
A short map of the primitives this skill assumes are available. Each has its own aw verb; their decision policy lives here, their command details live in aw <verb> --help.
- Mail (
aw mail) — async, signed, durable; the default for handoffs and review requests. Details inaweb-messaging. - Chat (
aw chat) — sync, signed, waits on a response. Details inaweb-messaging. - Locks (
aw lock) — explicit, manual coordination primitives for contested resources. Not automatic. - Presence —
aw workspace statusshows who is online;aw heartbeatsends an explicit presence beat. - Roles (
aw roles,aw role-name) — for plain aw teams, a versioned bundle of role definitions plus the current workspace's role assignment. OATS seats use their soul for role guidance. - Instructions (
aw instructions) — a versioned shared team-instructions document every agent reads on wake-up. - Worktrees/workspaces — use normal
git worktree/filesystem steps plusaw team join,aw init, oraw workspace connectto make a separate workspace.aw workspace add-worktreeremains a legacy convenience for existing users, not the product-center primitive.
Start-of-session loop
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.
Seeing what teammates are doing
Before starting work or sending a message, get the team's current state. These are read-only and cheap:
aw workspace status— presence and current team binding.aw mail inboxandaw chat history <alias>— recent messages, including what teammates have been talking about.
Some teammates may be members of more than one team. The commands above only show the active team's state. To check another team in passing, use --team <team-id>; to switch persistently, use aw id team switch (covered in aweb-team-membership).
Contacting teammates
Mail and chat are the contact surface. The policy lives in aweb-messaging, but in a coordination context the defaults are:
- Mail (
aw mail send --to <alias> --subject ... --body ...starts a thread;aw mail reply <message_id>answers in it) — durable handoffs, review requests, status updates, anything that doesn't need an answer in the next few seconds. - Chat (
aw chat send-and-wait <alias> "...") — when the teammate is online and you are blocked on their answer. Sets a wait state the harness surfaces to them. - For cross-team addressing, use
<domain>/<alias>or a saved contact. Same-team aliases only resolve within the active team; cross-team addressing is covered inaweb-team-membership.
Shared state over private notes
Whenever another agent might care, prefer aweb-visible state to private TODOs:
- Mail captures durable handoffs and review evidence.
- Locks capture exclusive holds on shared resources.
- Roles and instructions capture team-wide operating rules.
Private notes go stale and strand context if another agent takes over. Reserve them for short-term scratch.
Diagnostic access before escalation
When an incident needs service evidence, check the deployment-owned documentation for the selected provider/resource, available tools and configured credential stores before declaring access unavailable. A missing environment variable, executable or connector is only an observation about that surface. Do not scan unrelated identity stores or assume a teammate's custody is available.
Separate discovery from authority: a configured credential does not authorize its use, mutation or broader access. Use the existing assignment/user authorization; when it covers the required diagnostic read, perform the smallest supported read using that selected authority instead of requesting another generic login or owner. If authority is missing, stop before loading credentials or calling the service and identify the exact operation whose authorization is missing.
Keep credential input in private memory or the deployment's approved mechanism; do not print secrets or their private locations. Retain raw diagnostic evidence with operator-only access and hand off only sanitized cause/status/request-ID or other required public facts. Never copy raw logs into shared review artifacts. Distinguish capability/store discovery failure, missing authorization, failed authentication, denied resource access, missing resource and a successful read with no matching records. Report what the service actually establishes; ambiguous responses remain ambiguous. A successful empty query does not prove no effects. Escalate only the remaining precise blocker, with the selected resource and safe observations. Reuse a successful read's evidence; do not repeat it or expand scope merely to reconfirm access. Hosted repairs remain with their authorized owner.
Locks — manual, not automatic
aweb's locks are explicit and manual: starting work does not lock anything. Acquire a lock yourself when you genuinely need exclusive access to a mutable shared resource:
aw lock acquire --resource-key <key> --ttl-seconds <n>
aw lock renew --resource-key <key> --ttl-seconds <n>
aw lock release --resource-key <key>
aw lock list # see what's currently held
aw lock revoke --prefix <prefix> # emergency override, by prefixTake a lock for: deployments, production DB maintenance, shared staging environments, long-running migrations, generated artifacts where concurrent writers corrupt output. Do NOT take a lock for ordinary file edits in your own worktree.
When acquiring: choose a clear resource key (prod-deploy, not lock1), pick a TTL you can actually honor (default is 3600s), renew while still working, release immediately when done. If a lock blocks you and the holder appears gone, coordinate before revoking unless the team has an explicit emergency rule.
Roles and team instructions
The role-bundle commands below are for plain aw teams. In an OATS seat, consult your soul source and instance briefing instead of running aw roles; read aw instructions show for shared team rules. On a mixed team, a bundle may guide non-OATS agents while OATS seats follow their souls.
Two distinct shared documents live on the aweb server:
- Role bundle (
aw roles) — a versioned set of role definitions for the team. Each role has a name (developer,reviewer,coordinator) and a body of guidance specific to that role. The active bundle applies to the whole team. - Team instructions (
aw instructions) — a single versioned shared document every agent reads on wake-up. Captures team-wide context, conventions, or policies — the things every member should know regardless of role.
Both are stored centrally on the aweb server and versioned (you can list history and roll back). Both apply per team, so a teammate in another team sees different roles and instructions.
Neither lives in the repo by default. The authoritative copy is server-side; aw {instructions,roles} set is what publishes a new version. Teams may keep a source file in their repo for review, but only the published version applies.
Reading them (OATS seats skip the role-bundle commands):
aw instructions show # team-wide rules
aw roles list # role names in the active bundle
aw roles show <role-name> # guidance for one role
aw workspace status # reports this workspace's assigned role among other thingsOn Cloud, publishing role bundles (aw roles add, set, activate, reset, or deactivate) requires an owner/admin human, including a human-owned API key. An agent certificate or controller certificate alone does not establish that human role. Agents may still read bundles and select their own role name normally. Standalone OSS operators define their own publication policy.
Setting and updating them (requires whatever permission the team's authority model demands — coordinator/owner, typically):
aw instructions set --body-file <path> # publish a new version of team instructions (markdown body)
aw instructions activate <version-id> # roll back/forward to a previous version
aw instructions history # see what changed and when
aw roles add <role-name> --title <title> --playbook-file <path> # add/update one role from Markdown
aw roles set --bundle-file <path> # publish a full JSON role bundle
aw roles activate <version-id> # roll to a previous bundle
aw roles history
aw role-name set <role-name> # assign a role to THIS workspaceTeam instructions and individual role playbooks are markdown. For resource packs or novice application, prefer aw roles add ... --playbook-file <path> one role at a time. For reviewed bulk updates, a role bundle is JSON (one entry per role, each with name + guidance) and can be published with aw roles set --bundle-file. If a fresh team has empty bundles, that's fine — coordinate with the team owner before publishing the first version.
A role name clarifies responsibility but does not bypass judgment. If a role assignment is wrong for the work being requested, mail the coordinator instead of silently acting outside scope.
Applying resource packs safely
A resource pack is a set of reusable resources, not a setup command. Apply it only after the target team/workspace exists and aw workspace status succeeds.
Novice-friendly order:
In an OATS seat, skip the role-bundle steps below and use your soul's role guidance. On Cloud, an owner/admin human performs the publication steps; agents can prepare the files and read the resulting bundle. A mixed team's owner may publish a bundle for its non-OATS agents.
# 1. Inspect the pack first.
ls <pack-dir>
# 2. Publish team-wide instructions from Markdown.
aw instructions set --body-file <pack-dir>/resources/instructions.md
# 3. Add roles one by one from Markdown playbooks.
aw roles add coordinator --title "Coordinator" --playbook-file <pack-dir>/resources/roles/coordinator.md
aw roles add developer --title "Developer" --playbook-file <pack-dir>/resources/roles/developer.md
# 4. Verify what the team now sees.
aw instructions show
aw roles list
aw roles show --all-rolesIf a role already exists, stop and ask whether to update it; do not pass --replace silently. Use aw roles set --bundle-file only for a reviewed full-bundle replacement, not as the default novice path. Apply harness adapters (Claude/Codex/Pi/Cursor files) only after the human chooses that harness. Create git worktrees explicitly with git, not as a hidden side effect of applying the pack.
Worktrees for parallel local work
When the human (or another agent) needs a second working copy of the same repo — to run a parallel agent without disturbing your own working tree — prefer explicit steps:
git worktree add ../repo-feature -b feature-branch
cd ../repo-feature
# A fresh invite join connects this directory using the invite's service URL:
aw team join <invite-token>
# For an already-certified BYOT/global workspace instead:
aw workspace connect --service <service-url> --team <team>:<namespace>Ask an existing team member for aw team invite when this new worktree needs a fresh local identity. Use aweb-team-membership if you need to choose between hosted invite, BYOT request/fetch-cert, or service-init paths.
aw workspace add-worktree remains available as a legacy convenience for existing users. Do not make it the default product path in new guidance unless it has been reduced to a transparent wrapper with no identity/team/template magic.
Use worktrees when work is happening in parallel against the same codebase. Use separate initialized directories when the work isn't tied to one repo.
Wrap-up at session end
Before stopping work:
- Record the current outcome and any remaining work in the team's shared state.
- Send any handoff or review-request mail.
- Release locks you still hold (
aw lock release --resource-key <key>). - Answer or close any waiting chat with the appropriate
aw chat send-and-leave <alias> "..."so teammates aren't left in a wait state.
References
Read these only when deeper context is needed:
references/coordination-patterns.md: detailed coordination scenarios and anti-patterns.- https://aweb.ai/docs/agent-guide/: full aweb agent guide.
- https://aweb.ai/docs/teams/: team model and cross-team coordination.
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.

