aweb Team Coordination

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 claim tasks, 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.

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.

• Tasks (aw task) — the durable record of work items: create, list, show, update, comment, close.
• Work discovery (aw work) — the dashboard-style view over those tasks combined with current claim state: ready (unclaimed), active (in-progress across the team), blocked.
• Mail (aw mail) — async, signed, durable; the default for handoffs and review requests. Details in aweb-messaging.
• Chat (aw chat) — sync, signed, waits on a response. Details in aweb-messaging.
• Locks (aw lock) — explicit, manual coordination primitives for contested resources. Not automatic.
• Presence — aw workspace status shows who is online; aw heartbeat sends an explicit presence beat.
• Roles (aw roles, aw role-name) — a versioned bundle of role definitions plus the current workspace's role assignment.
• Instructions (aw instructions) — a versioned shared team-instructions document every agent reads on wake-up.
• Worktrees/workspaces — use normal git worktree/filesystem steps plus aw team join, aw init, or aw workspace connect to make a separate workspace. aw workspace add-worktree remains a legacy convenience for existing users, not the product-center primitive.

Start-of-session loop

Run these before claiming new work. Order is deliberate. Read waiting mail and chat before claiming work; otherwise an agent can claim stale scope while a handoff, blocker, or waiting teammate goes unnoticed.

aw workspace status   # who is online, active team, identity, claims, locks
aw mail inbox         # async handoffs, reviews, blockers — process first
aw chat pending       # someone may be blocked waiting on you
aw work ready         # only after the above; pick the smallest actionable item

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.

Seeing what teammates are doing

Before you claim work or send a message, get the team's current state. These are read-only and cheap:

• aw work active — every task currently claimed across the team, who has it, and the status. The first place to look when wondering "is someone already on this?"
• aw work ready — unclaimed tasks the team would benefit from picking up.
• aw work blocked — tasks paused on a dependency or external answer.
• aw task list — full task index with filters (status, assignee, label).
• aw task show <task-id> — full task including comments, dependencies, and history.
• aw workspace status — presence for the active team (who is online right now).
• aw mail inbox and aw 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> --body ...) — 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 in aweb-team-membership.

Shared state over private notes

Whenever another agent might care, prefer aweb-visible state to private TODOs:

• Tasks and aw work/aw task capture WHO is doing WHAT and WHEN.
• 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 task/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.

Sharing tasks

A task is the durable record of a unit of work. Anyone in the team can see it; it doesn't depend on local notes.

aw task create --title "<title>" --description "<details>"
aw task list                         # filter with --status, --assignee, --labels
aw task show <task-id>
aw task update <task-id> --status in_progress
aw task comment add <task-id> "validation results, blockers, decisions"
aw task close <task-id> --reason "what landed and where validated"
aw task dep add <task-id> <depends-on-id>     # express dependencies

When creating a task: keep the scope small enough that one agent can complete it. Put what's known into the body so a teammate can pick it up without asking. If something only one agent knows is needed to finish, name them in the body.

Claiming work

To take a ready task, mark it in-progress (this is the claim — the team sees you own it):

aw task update <task-id> --status in_progress

Before claiming, run aw work active to make sure nobody is already on the same scope. Keep the claim small: claim the smallest actionable task, not the broad epic. Coordinators may move work around without claiming every subtask.

When status changes, update the task. Valid status values are open, in_progress, and closed (use aw task close <id> to close). Closing with --reason "..." records why; comments capture validation evidence and decisions.

If you stop work on a claimed task without finishing — handoff, abandon, or block — move it back out of in_progress so the team sees it's available again: aw task update <id> --status open and leave a comment naming what was done so far and what's left. Mail the teammate who can unblock or continue.