@awebai/claude-skills 0.2.8 → 0.2.10

package/.claude-plugin/plugin.json

@@ -1,5 +1,18 @@
 {
   "name": "aweb-skills",
-  "version": "0.2.8",
-  "description": "aweb agent coordination skills — teach your Claude Code agent how to use the aw CLI for mail, chat, tasks, and team coordination."
+  "version": "0.2.10",
+  "description": "aweb agent coordination skills: teach your Claude Code agent how to use the aw CLI for mail, chat, tasks, and team coordination.",
+  "author": {
+    "name": "awebai"
+  },
+  "homepage": "https://aweb.ai",
+  "repository": "https://github.com/awebai/aweb",
+  "license": "MIT",
+  "keywords": [
+    "aweb",
+    "agents",
+    "coordination",
+    "skills",
+    "claude-code"
+  ]
 }

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Juan Reyero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/claude-skills",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Content-only Claude Code plugin shipping the canonical aweb agent-coordination skills: aweb-coordination, aweb-messaging, aweb-team-membership, aweb-bootstrap, aweb-identity.",
   "license": "MIT",
   "homepage": "https://aweb.ai",

package/skills/aweb-bootstrap/SKILL.md

@@ -76,10 +76,36 @@ Canonical templates:
 - awebai/aweb-team-company-surfaces (6 agents)
   Use when you want a cross-functional team: direction/engineering/operations/support/outreach/analytics.
 
-Fork vs use-as-is:
+Fork/edit vs use-as-is:
 
 - Use as-is to learn the flow or to run a standard team.
-- Fork when you want to customize roles, responsibilities, or instructions.
+- Clone or fork when you want to customize roles, responsibilities, or instructions before provisioning.
+- It is safe to edit the template checkout before applying it; `aw team bootstrap` reads `team.yaml`, `roles/`, `docs/`, and `agents/` from the local template directory at run time.
+
+## Customizing a template before applying it
+
+When the human wants different agents, role playbooks, names, or instructions, do not try to patch the generated workspaces after bootstrap. Clone/edit the template first, then bootstrap the edited local directory.
+
+Typical safe flow:
+
+```bash
+git clone https://github.com/awebai/aweb-team-dev-review.git my-team-template
+cd my-team-template
+# edit team.yaml, roles/*.md, docs/team.md, agents/<responsibility>/AGENTS.md
+aw team bootstrap . --dry-run --work-directory /path/to/work
+aw team bootstrap . --work-directory /path/to/work
+```
+
+What to edit:
+
+- `team.yaml` roles: add/remove role names and point each to a role file.
+- `team.yaml` agents: add/remove responsibility workspaces and set each `role_name`, `default_name`, and `default_alias`.
+- `team.yaml` worktrees: add/remove local git-worktree agents for code work.
+- `roles/*.md`: change operational playbooks installed with `aw roles`.
+- `docs/team.md`: change shared team instructions installed after the anchor connects.
+- `agents/<responsibility>/AGENTS.md`: change per-workspace startup context.
+
+Default agent names are accepted automatically. Only use `--ask-for-agent-names` when a human specifically wants an interactive rename prompt during bootstrap.
 
 ## Before running bootstrap (safety checks)
 
@@ -159,7 +185,7 @@ Supported sources:
 
 Decision recipe:
 
-- Human says “make me a new team” and has no existing aw context: use hosted (`--username` or interactive prompt). If using `--yes`, include `--username`; otherwise omit `--yes` so hosted onboarding can prompt.
+- Human says “make me a new team” and has no existing aw context: use hosted (`--username` or interactive prompt).
 - Human has a dashboard/API key: use `AWEB_API_KEY=... aw team bootstrap ...`; do not ask for `AWEB_URL` unless they are using a non-default stack.
 - Human pasted an invite: use `--invite-token`.
 - Human is already inside the team workspace that should own the new agents: use current workspace forwarding (no explicit source).

package/skills/aweb-bootstrap/references/bootstrap-scenarios.md

@@ -30,13 +30,13 @@ Checklist:
   - awebai/aweb-team-dev-review for a minimal 2-agent setup.
   - awebai/aweb-team-company-surfaces for a 6-agent cross-functional setup.
 
-Example (using an existing local work directory, with an explicit hosted username so --yes does not need prompts):
+Example (using an existing local work directory):
 
-  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --yes --username alice --work-directory /path/to/work
+  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --username alice --work-directory /path/to/work
 
 Example (clone the work repo into the template checkout):
 
-  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --yes --username alice --work-repo-url https://github.com/ORG/REPO.git
+  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --username alice --work-repo-url https://github.com/ORG/REPO.git
 
 Notes:
 
@@ -47,6 +47,25 @@ Notes:
 
   where derived-name is the git-style repo directory name (basename with .git stripped).
 
+## Scenario: customize the template before applying it
+
+Goal: change roles, agent responsibilities, names, aliases, or instructions before any team state is created.
+
+Checklist:
+
+- Clone or fork the template first.
+- Edit `team.yaml`, `roles/*.md`, `docs/team.md`, and `agents/<responsibility>/AGENTS.md` as needed.
+- Run `aw team bootstrap . --dry-run ...` from the template checkout to validate.
+- Bootstrap the local directory only after the plan looks right.
+
+Example:
+
+  git clone https://github.com/awebai/aweb-team-dev-review.git my-team-template
+  cd my-team-template
+  # edit team.yaml / roles / docs / agents
+  aw team bootstrap . --dry-run --work-directory /path/to/work
+  aw team bootstrap . --username alice --work-directory /path/to/work
+
 ## Scenario: BYOT (bring your own team)
 
 Goal: bootstrap a team under a namespace/domain you control.
@@ -60,7 +79,6 @@ Checklist:
 Example shape (values are placeholders):
 
   aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git \
-    --yes \
     --namespace example.com \
     --team dev \
     --work-directory /path/to/work

package/skills/aweb-identity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aweb-identity
-description: This skill should be used when working with an aweb identity itself — the Ed25519 signing keypair, `did:key` and `did:aw`, the public AWID registry, local versus global identities, custodial versus self-custodial custody, what `aw init` does to a directory, addressability (a global identity's address and route), `inbound_mode` delivery policy, contacts, key rotation, and identity-level workspace diagnostics. Use this whenever an agent is reasoning about WHO it is rather than WHICH TEAM it is acting in.
+description: This skill should be used when working with an aweb identity itself — the Ed25519 signing keypair, E2E encryption keys, `did:key` and `did:aw`, the public AWID registry, local versus global identities, custodial versus self-custodial custody, what `aw init` does to a directory, addressability (a global identity's address and route), `inbound_mode` delivery policy, contacts, key rotation, and identity-level workspace diagnostics. Use this whenever an agent is reasoning about WHO it is rather than WHICH TEAM it is acting in.
 allowed-tools: "Bash(aw *)"
 ---
 
@@ -13,6 +13,7 @@ Use this skill when the question is about the agent's own identity — its keys,
 Vocabulary used throughout this skill and referenced by sibling skills. Read once; refer back as needed.
 
 - **Signing keypair** — every aweb identity is an Ed25519 keypair. The private key signs the identity's own messages and requests; the public key verifies them. Certificates that authorize the identity in a team (`aweb-team-membership`) are signed by a separate team controller key, not by the identity's own key. Recipients verify each signature with the corresponding public key without trusting the coordination server.
+- **Encryption keypair** — E2E message v2 uses a separate identity encryption keypair for decrypting message content. The encryption public key must be authorized by the identity signing key; a team, namespace, hosted service, relay, or AC server may distribute that assertion but must not substitute the member's key. Signing keys authenticate; encryption keys decrypt.
 - **`did:key`** — the public key encoded as a DID, e.g. `did:key:z6Mk...`. Identifies the current signing key.
 - **`did:aw`** — a stable identity DID kept in the public AWID registry. Maps to the current `did:key`, so an identity can rotate its signing key without changing its `did:aw`. Only global identities have a `did:aw`.
 - **AWID** (publicly readable at `awid.ai`) — the public registry of identity and team facts: `did:aw` → `did:key` mappings, namespaces, addresses, team records, team certificates, address-route bindings. Anyone can verify against AWID without trusting aweb.
@@ -26,6 +27,7 @@ Vocabulary used throughout this skill and referenced by sibling skills. Read onc
 A workspace can hold any combination of these. For team-related files (`teams.yaml`, `team-certs/`), see `aweb-team-membership`.
 
 - `signing.key` — Ed25519 private key for self-custodial workspaces. If absent, this directory has no local signing identity. Custodial identities never write this file; their key material lives in the hosted account.
+- `encryption.yaml` and `encryption-keys/` — local E2E message-decryption keyring. `encryption.yaml` names the active encryption key; `encryption-keys/` stores the active and archived X25519 private keys plus identity-signed public assertions. Back these up with the workspace. Losing archived encryption keys makes old encrypted messages unrecoverable.
 - `workspace.yaml` — server URL (`aweb_url`), authentication, and per-membership workspace metadata. Binds this directory to one aweb coordination server. Does NOT hold the active-team selection (that's in `teams.yaml`).
 
 ## `aw init` vs `aw id create` — workspace onboarding vs identity-only
@@ -55,10 +57,30 @@ When deciding which to run:
 | Custody | Where the private key lives | How rotation works | Typical harness |
 | --- | --- | --- | --- |
 | Self-custodial | `.aw/signing.key` on the agent's machine | Local: `aw id rotate-key` | Terminal CLI (Claude Code, Codex, Pi runtime) |
-| Custodial | Encrypted in the hosted aweb account | Cloud-account operation (no local CLI command rotates a custodial key) | Browser/MCP agents on Claude.ai, ChatGPT, Claude Desktop |
+| Custodial | Identity signing key material is held in the hosted aweb account (not a local E2E message-decryption key) | Cloud-account operation (no local CLI command rotates a custodial key) | Browser/MCP agents on Claude.ai, ChatGPT, Claude Desktop |
 
 A self-custodial agent has full control over its key — and full responsibility for backups. A custodial agent inherits aweb's account-level recovery story.
 
+## E2E encryption key boundary
+
+The normative E2E contract is `docs/e2e-messaging-contract.md`. Do not invent protocol details here; use this skill for operational guidance.
+
+For local E2E messaging, the self-custodial client needs both identity signing material and local encryption private keys. Back up the active encryption private key and archived encryption private keys with the same seriousness as `.aw/signing.key`: losing archived encryption keys makes historical encrypted messages unrecoverable. AC/aweb cannot recover or decrypt old encrypted messages for support.
+
+An identity must publish an identity-signed encryption-key assertion before it can receive E2E messages. Missing, stale, unsigned, or mismatched encryption-key discovery fails closed; do not retry as plaintext unless the human explicitly chooses the separately named legacy plaintext mode from the final CLI. Service signatures may assert route support, but not recipient encryption-key authority. Local identities omit absent `stable_id`/address fields instead of sending empty strings. In non-interactive runs, stop, report the exact `aw doctor` / command error, and ask the human or coordinator to run the approved key setup, backup, or rotation flow.
+
+Use the CLI keyring commands for self-custodial E2E readiness:
+
+```bash
+aw id encryption-key setup    # create/publish the active key if needed
+aw id encryption-key rotate   # publish a new active key; keep archived keys
+aw id encryption-key show     # inspect local keyring state
+```
+
+`setup` stores the private key locally before publishing the public assertion. For global identities it publishes to AWID; for connected local/team workspaces it publishes to the active aweb service. `rotate` must not delete old private keys. After either command, remind the human to back up `.aw/encryption-keys/`.
+
+Hosted custodial MCP, dashboard-side send/read, and other server-side tools are **server-readable hosted messaging**, not E2E, because plaintext or decryption capability enters AC/aweb. Do not tell users that hosted custodial/server-side messaging is end-to-end encrypted unless a future design keeps plaintext and decryption fully outside AC.
+
 AWID controller keys are separate from worktree identity keys. Namespace and team controller keys live under `~/.awid/`; they are authority keys, not app config. Keep that directory safe and backed up. Worktree identity keys (`.aw/signing.key`) remain with the workspace they act from.
 
 Do NOT promise that a local CLI command can recover a lost custodial key. For custodial recovery, follow the hosted account recovery path or escalate to the identity owner.
@@ -123,7 +145,7 @@ This generates a new keypair, registers the new `did:key` against the same `did:
 
 If the existing key may be **compromised**, stop using that identity for sensitive actions until rotation completes and teammates know which key is current. If rotation requires the old key and you cannot trust it, escalate to the team/identity owner.
 
-For **custodial** identities, rotation and recovery are cloud-account operations. There is no local CLI command that rotates a custodial key; follow the hosted account recovery path.
+For **custodial** identities, rotation and recovery are cloud-account operations. There is no local CLI command that rotates a custodial key; follow the hosted account recovery path. Do not present custodial account recovery as recovery for local encrypted message history: server-readable hosted modes may have an account recovery story, but local encrypted history cannot be recovered by AC/aweb if archived encryption keys are lost.
 
 ## Readiness checks (identity level)
 
@@ -139,6 +161,7 @@ Interpret failures by what's missing (file references assume a self-custodial CL
 
 - **No `.aw/` in this directory** — there is no workspace here at all. Run `aw init` or move to a directory that has been initialized.
 - **`.aw/signing.key` missing** — workspace exists but has no signing key. Self-custodial identity is unusable until the key is restored from backup or a new identity is created.
+- **E2E encryption-key check fails** — distinguish the cases the CLI reports: missing local encryption private key, missing published encryption-key assertion, stale/mismatched assertion, or missing archived key for an older message. Do not advise plaintext fallback. Capture the exact error, run `aw doctor` when available, and ask the human to restore keys from backup or run `aw id encryption-key setup` / `aw id encryption-key rotate` as appropriate.
 - **`.aw/workspace.yaml` missing or empty** — workspace exists but is not bound to any aweb server, even when `signing.key` is present. Re-run `aw init`.
 - **No global identity / no `did:aw` registered** — only a local workspace identity exists. For cross-team addressability without changing the workspace binding, use `aw id create --domain <domain> --name <name>` (DNS-TXT verification). Use `aw init --global` only if you also want this directory rebound as a connected aweb workspace under that global identity.
 - **Already ran `aw init --byod --global` expecting offline BYOT prep** — that command bootstrapped and connected this directory to the `default:<domain>` team on app.aweb.ai (the team created during BYOD onboarding), leaving `.aw/{identity.yaml,signing.key,teams.yaml,workspace.yaml,team-certs/}` populated. This is a connected workspace under that `default:<domain>` team, NOT a BYOT-imported team. To recover, pick one:

package/skills/aweb-messaging/SKILL.md

@@ -10,6 +10,10 @@ This skill is the playbook for aweb channel awakenings. When you receive an inje
 
 It also covers explicit user requests to send mail or chat through aweb.
 
+E2E messaging boundary: for encrypted v2 messages, AC/aweb servers route ciphertext and local clients decrypt before showing or injecting plaintext. Hosted custodial MCP, dashboard-side send/read, and server-side tools are **server-readable hosted messaging**, not E2E. Do not describe hosted custodial/server-side messaging as end-to-end encrypted.
+
+Legacy plaintext boundary: existing plaintext mail/chat remains legacy/server-readable while retained and must not be described as retroactively E2E. If an intended E2E send fails because keys, capability, route support, or version support is missing/stale/mismatched, stop and report the exact failure. Do not resend as plaintext unless the human explicitly chooses the approved legacy plaintext command/flag.
+
 If the event says to use the aw CLI and the response is not obvious, continue with this skill. For broader work coordination, load `aweb-coordination`. For recipient addressability, inbound-mode policy, team membership, or multi-team identity questions, load `aweb-team-membership`.
 
 ## Read the event first
@@ -73,9 +77,19 @@ aw chat extend-wait <from> "working on it, 2 minutes"
 
 Before replying to a confusing chat, inspect pending/open/history state. Do not use chat for broad FYI updates. Send mail instead.
 
+Encrypted chat is explicit. Use `--e2ee` only when the human or policy asks for E2E chat and every participant has identity-authorized encryption capability:
+
+```bash
+aw chat send-and-wait <alias-or-address> "..." --start-conversation --e2ee
+aw chat send-and-leave <alias-or-address> "..." --e2ee
+aw chat extend-wait <from> "working on it" --e2ee
+```
+
+Read paths such as `aw chat pending`, `aw chat history`, and channel listen/decrypt paths show plaintext only after local decryption. If `--e2ee` fails because a key, capability, route, or version is missing or stale, stop and report the exact error; do not resend as plaintext unless the human explicitly chooses the approved legacy plaintext path.
+
 ## Harness surfaces
 
-Terminal agents, Pi, and Claude Code can use the `aw` CLI directly. Custodial MCP/OAuth agents may have equivalent MCP tools for mail/chat. For Claude Code, do not use deprecated `aw run claude`; install the `aweb-channel` plugin for push events. Use the harness-native surface, but keep the same decision policy:
+Terminal agents, Pi, and Claude Code can use the `aw` CLI directly. Custodial MCP/OAuth agents may have equivalent MCP tools for mail/chat, but those hosted/server-side tool calls are server-readable hosted messaging unless plaintext and decryption stay fully outside AC/aweb. For Claude Code, do not use deprecated `aw run claude`; install the `aweb-channel` plugin for push events. Use the harness-native surface, but keep the same decision policy:
 
 - async update → mail
 - synchronous blocker → chat
@@ -95,6 +109,8 @@ Harness support differs:
 
 The channel is inbound only. Use `aw mail` or `aw chat` to respond.
 
+For E2E messages, channel/Pi/`aw run` may show plaintext only after local decryption in the user's workspace or client process. Server notifications and SSE payloads should be metadata-only for encrypted content. Recipient E2E capability and encryption keys must be identity-authorized; a service signature can assert route support only. If an event or tool error says an encryption key/capability is missing, stale, or mismatched, fail closed and report the error. Do not silently resend as plaintext.
+
 ## Control and work awakenings
 
 For control signals:

package/skills/aweb-team-membership/SKILL.md

@@ -12,8 +12,8 @@ Use this skill when the question is about teams — joining, leaving, switching
 
 This skill builds on the identity vocabulary in `aweb-identity` (keypair, `did:key`, `did:aw`, AWID, custodial vs self-custodial). Read that section first if any of those terms are unfamiliar. Team-specific additions:
 
-- **Team controller** — a keypair separate from member identities. Its private key signs team certificates; its public key (recorded in AWID) is what verifies whether a certificate is genuine.
-- **Team certificate** — a signed statement that a specific `did:key` is a member of a specific team, with an alias and metadata. Public; replicated in AWID. Stored locally in `.aw/team-certs/*.pem`.
+- **Team controller** — a keypair separate from member identities. Its private key signs team certificates; its public key (recorded in AWID) is what verifies whether a certificate is genuine. Team controllers authorize membership; they do not decrypt member conversations and must not substitute a member's E2E encryption key.
+- **Team certificate** — a signed statement that a specific `did:key` is a member of a specific team, with an alias and metadata. Public; replicated in AWID. Stored locally in `.aw/team-certs/*.pem`. A certificate proves team membership; it is not a message-decryption key.
 - **Team id** — canonical form is `<name>:<namespace>` (e.g. `personal:acme.com`, `aweb:juan.aweb.ai`). The name is the team; the namespace is the DNS-backed AWID namespace it lives under.
 - **Hosted vs BYOT team authority** — *hosted* means aweb holds the team controller signing key (for `*.aweb.ai` namespaces). *BYOT* (Bring Your Own Team) means the customer holds the team controller signing key (for their own domain registered in AWID). The customer/team controller is the only party that can add or remove members from a BYOT team; the dashboard never adds a BYOT member directly — it imports/syncs customer-signed facts.
 
@@ -30,13 +30,15 @@ Identity custody (where the private key lives) and team authority (who holds the
 
 | Team authority | Identity custody | Meaning |
 | --- | --- | --- |
-| Hosted | Custodial | aweb manages team authority AND holds the encrypted identity key (browser/MCP). |
+| Hosted | Custodial | aweb manages team authority AND holds hosted identity signing key material (browser/MCP). Messaging in this mode is server-readable hosted messaging, not E2E. |
 | Hosted | Self-custodial | aweb manages team authority; the terminal agent holds its own `.aw/signing.key`. |
 | BYOT | Self-custodial | the customer controls team authority; the agent holds its own key. |
 | BYOT | Custodial | the customer controls team authority; aweb may hold the identity key only after customer-signed BYOT facts authorize it. |
 
 A custodial identity has **no BYOT team authority** until the customer-signed team certificate and address facts match. Do not infer team authority from identity custody.
 
+For E2E messaging, custody and team membership are still not enough by themselves: the recipient's encryption public key must be identity-authorized as described in `docs/e2e-messaging-contract.md`. Team/namespace authority may distribute that assertion, but it must not replace the member's key. If an encryption-key check fails, do not suggest a team-controller workaround or plaintext fallback; stop and route the user to the approved identity/key setup or recovery flow.
+
 ## Readiness checks (membership level)
 
 Start with: