@awebai/claude-skills 0.1.0 → 0.2.1

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "aweb-skills",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "aweb agent coordination skills — teach your Claude Code agent how to use the aw CLI for mail, chat, tasks, and team coordination."
 }

package/README.md

@@ -1,7 +1,8 @@
 # `@awebai/claude-skills`
 
-Content-only Claude Code plugin packaging the three canonical aweb skills:
-`aweb-coordination`, `aweb-messaging`, `aweb-team-membership`.
+Content-only Claude Code plugin packaging the four canonical aweb skills:
+`aweb-coordination`, `aweb-messaging`, `aweb-team-membership`, and
+`aweb-bootstrap`.
 
 Distinct from [`@awebai/claude-channel`](https://github.com/awebai/aweb/tree/main/channel),
 which ships the real-time channel runtime and requires

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@awebai/claude-skills",
-  "version": "0.1.0",
-  "description": "Content-only Claude Code plugin shipping the canonical aweb agent-coordination skills: aweb-coordination, aweb-messaging, aweb-team-membership.",
+  "version": "0.2.1",
+  "description": "Content-only Claude Code plugin shipping the canonical aweb agent-coordination skills: aweb-coordination, aweb-messaging, aweb-team-membership, aweb-bootstrap.",
   "license": "MIT",
   "homepage": "https://aweb.ai",
   "repository": {
@@ -23,8 +23,9 @@
     "package.json"
   ],
   "scripts": {
-    "sync-skills": "rm -rf skills && mkdir -p skills && cp -R ../../skills/aweb-coordination ../../skills/aweb-messaging ../../skills/aweb-team-membership skills/",
-    "prepack": "npm run sync-skills",
-    "prepublishOnly": "npm run sync-skills"
+    "sync-skills": "rm -rf skills && mkdir -p skills && cp -R ../../skills/aweb-coordination ../../skills/aweb-messaging ../../skills/aweb-team-membership ../../skills/aweb-bootstrap skills/",
+    "sync-plugin-version": "node -e \"const p=JSON.parse(require('fs').readFileSync('.claude-plugin/plugin.json','utf8')); p.version=require('./package.json').version; require('fs').writeFileSync('.claude-plugin/plugin.json',JSON.stringify(p,null,2)+'\\n')\"",
+    "prepack": "npm run sync-skills && npm run sync-plugin-version",
+    "prepublishOnly": "npm run sync-skills && npm run sync-plugin-version"
   }
 }

package/skills/aweb-bootstrap/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: aweb-bootstrap
+description: This skill should be used when helping a human create a new aweb team from a template (aw team bootstrap), choosing a template and bootstrap mode (hosted vs BYOT vs manual), selecting work-directory vs work-repo-url, provisioning optional worktree agents, and validating/re-running bootstrap safely.
+allowed-tools: "Bash(aw *)"
+---
+
+# aweb Bootstrap
+
+Use this skill when a human wants to create a new aweb team for the first time, and you need to guide them through `aw team bootstrap` decisions and validation.
+
+This skill is about **decision policy + safe execution**, not memorizing flags.
+
+Related skills:
+
+- For day-to-day coordination once the team exists: `aweb-coordination`
+- For mail/chat response policy: `aweb-messaging`
+- For joining an existing team, multi-team membership, custody, addressability, and contacts: `aweb-team-membership`
+
+Long-form reference: docs/team-bootstrap.md in the aweb repo.
+
+## Bootstrap vs join (first decision)
+
+Bootstrap when:
+
+- You are creating a brand-new team (new template repo clone, new identities, new role bundle).
+- You want reproducible setup for multiple agents/workspaces.
+- You want a “one command creates the team + installs roles + provisions agent dirs” flow.
+
+Do NOT bootstrap when:
+
+- The team already exists and you just need to add yourself: use `aweb-team-membership` and the `aw id team ...` commands.
+- You only need another workspace for yourself: use `aw workspace add-worktree` (git worktree) or create another directory and `aw init` it.
+
+## Pick a template (what team shape are we creating?)
+
+Canonical templates:
+
+- awebai/aweb-team-dev-review (2 agents)
+  Use when you want the smallest meaningful team: implementation + review.
+
+- 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:
+
+- Use as-is to learn the flow or to run a standard team.
+- Fork when you want to customize roles, responsibilities, or instructions.
+
+## Before running bootstrap (safety checks)
+
+1) Run bootstrap from a directory that is NOT already inside a git repo/worktree.
+
+- If you are inside a git repo/worktree and you are using a remote template ref, bootstrap will refuse to clone by default.
+- Use `--template-cache-dir` as the explicit escape hatch when you must run from inside a repo.
+
+2) Decide the “work” directory model (see next section). This affects whether agents share one checkout or get isolated worktrees.
+
+## Exactly one of: work-directory OR work-repo-url (XOR)
+
+Bootstrap needs a directory to symlink into each agent workspace as ./work.
+
+You must provide exactly one of:
+
+A) --work-directory PATH
+
+- Use when you already have a local directory you want agents to use as work.
+- For code teams with worktree agents (team.yaml worktrees:), PATH must be a git repo.
+
+B) --work-repo-url VALUE
+
+- Use when you want bootstrap to clone a repo for you.
+- VALUE can be a URL or a local path; bootstrap runs “git clone VALUE” into:
+
+  <template-checkout>/worktrees/<derived-name>/
+
+  where <derived-name> matches git’s default directory naming (basename, .git stripped).
+
+- That clone destination is then used as the effective work directory (symlinked as ./work in each agent workspace).
+
+If both flags are set, treat it as a user error and stop.
+
+## Hosted vs BYOT vs manual bootstrap modes
+
+Bootstrap can be used in three broad modes:
+
+1) Hosted (aweb.ai)
+
+- Best for first-time teams.
+- Bootstrap will prompt for hosted onboarding details when appropriate, then provision each agent workspace.
+
+2) BYOT (your own controller + namespace)
+
+- Use when the team’s namespace and controller key live in your environment.
+- Bootstrap can create/ensure the team in that namespace and provision all agents.
+
+3) Manual (print next commands)
+
+- Use when you cannot or should not auto-provision from this run (for example, non-interactive environments or policy constraints).
+- Bootstrap will print the next `aw init ...` commands to run inside each agent directory.
+
+Policy guidance:
+
+- Prefer hosted for “get a working team now”.
+- Prefer BYOT when you need local control over identity and routing.
+- Prefer manual when you need human confirmation at each step.
+
+## Worktree agents (team.yaml worktrees:)
+
+Worktree agents are an OPTIONAL second layer for codebases where multiple agents will edit in parallel.
+
+- Responsibility workspaces live under agents/<responsibility>/.
+- Worktree agents live under worktrees/ and each has its own git worktree checkout and its own .aw/ identity state.
+
+Turn worktree agents on when:
+
+- The work directory is a git repo.
+- Multiple agents will change files in parallel.
+- You want each agent’s edits isolated until you merge.
+
+Leave it off when:
+
+- Work is non-code.
+- Only one agent edits at a time.
+
+Operational note:
+
+- Worktree agents are local-only identities by design; they are for parallel local work, not for global addressability.
+
+## After bootstrap: validate that the team is actually usable
+
+For each agent directory under agents/<responsibility>/:
+
+- Run `aw workspace status` to confirm:
+  - the workspace is initialized
+  - the active team is correct
+  - the identity is present
+
+- Run `aw whoami` to confirm the identity fields are present.
+
+- If you use a wake-up path (Pi extension / Claude Code channel plugin), start it inside the agent directory after initialization.
+
+## Re-run safety and idempotence (how to avoid making a mess)
+
+When iterating on templates or recovering from partial setup:
+
+- Use `--dry-run` first to validate the plan.
+- Use `--refresh-template` only when you intend to re-clone over a previous template checkout.
+- Treat identity/certificate state under .aw/ as the source of truth; do not delete it casually.
+- If you need to create a fresh workspace, do it in a new directory rather than mutating an existing identity in place.
+
+If bootstrap fails mid-way:
+
+- Capture the first failing command and error.
+- Do not keep retrying blindly; first confirm whether some workspaces were already created and connected.
+- Prefer completing the remaining agent dirs rather than redoing everything.
+
+## Adding agents later
+
+Two common expansions after initial bootstrap:
+
+- Add another responsibility workspace: create a new directory and run `aw init` (or extend your template and bootstrap a new repo).
+- Add another isolated code workspace on the same repo: use `aw workspace add-worktree`.
+
+When in doubt, choose the smallest change that preserves existing identities and avoids rewriting certificates.
+
+## References
+
+Read these only when deeper context is needed:
+
+- references/bootstrap-scenarios.md: scenarios, checklists, and troubleshooting.
+- https://aweb.ai/docs/team-bootstrap/ : full reference guide.
+- docs/team-bootstrap.md (aweb repo checkout): full reference guide.

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

@@ -0,0 +1,112 @@
+# aweb Bootstrap scenarios and checklists
+
+This reference is support material for the aweb-bootstrap skill. Use it when you need concrete examples, troubleshooting checklists, or a quick “what should I run next?” guide.
+
+It is intentionally narrower than docs/team-bootstrap.md: it focuses on common decision points and failure modes.
+
+## Scenario: first-time hosted team from a template (recommended)
+
+Goal: create a new aweb.ai team and provision agent workspaces from a template.
+
+Checklist:
+
+- Run from a directory that is not inside an existing git repo/worktree.
+- Pick a template:
+  - 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):
+
+  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --yes --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 --work-repo-url https://github.com/ORG/REPO.git
+
+Notes:
+
+- work-directory and work-repo-url are XOR: set exactly one.
+- When work-repo-url is used, bootstrap clones into:
+
+  <template-checkout>/worktrees/<derived-name>/
+
+  where derived-name is the git-style repo directory name (basename with .git stripped).
+
+## Scenario: BYOT (your own controller + namespace)
+
+Goal: bootstrap a team under a namespace you control.
+
+Checklist:
+
+- Confirm you have a controller identity key for the namespace.
+- Decide whether bootstrap should auto-provision (interactive) or just print next commands.
+
+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
+
+If you are also self-hosting the coordination stack, add:
+
+  --aweb-url http://localhost:8000
+  --registry http://localhost:8010
+
+## Scenario: manual mode (print next commands)
+
+Goal: validate the plan and generate the next steps without changing server state.
+
+Checklist:
+
+- Use dry-run to see the plan.
+- Use the printed aw init commands inside each agent directory.
+
+Example:
+
+  aw team bootstrap /path/to/template --dry-run --work-directory /path/to/work
+
+## Worktree agents: when to enable and what to expect
+
+Use worktree agents when multiple agents will edit code in parallel.
+
+Requirements:
+
+- The work directory must be a git repo.
+- The template must declare a worktrees: block in team.yaml.
+
+What bootstrap does:
+
+- It creates template worktrees/ (if missing) and git-excludes it locally.
+- It creates one git worktree per entry.
+- Each worktree agent gets its own .aw/ state and local-scope identity.
+
+Common pitfall:
+
+- Alias collisions: worktree agent aliases must not collide with existing team aliases.
+
+## Quick validation after bootstrap
+
+In each generated agent directory (agents/<responsibility>/):
+
+- aw workspace status
+- aw whoami
+
+If you are using a wake-up integration:
+
+- start the Pi extension or the Claude Code channel plugin in that directory after initialization
+
+## Troubleshooting patterns
+
+If bootstrap fails:
+
+- Stop and capture the first error.
+- Identify which directories were already created.
+- Prefer completing the remaining steps rather than deleting existing .aw state.
+
+If you see identity_mismatch or unverified messages in live channel metadata:
+
+- Compare with aw chat history output.
+- Confirm the channel plugin / Pi package version is current.
+- Prefer collecting a raw fetch payload before changing trust logic.

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

@@ -39,7 +39,7 @@ Interpret failures by layer:
 - Missing signing key: local identity is incomplete.
 - Missing team certificate: identity may exist but cannot act in the team.
 - Active team mismatch: the identity has multiple memberships but this workspace is using the wrong one.
-- Address route, inbound-mode, or contact failure: the sender and recipient may both exist, but route validation or `inbound_mode=open|contacts_only` policy prevents discovery or inbound delivery.
+- Address route, inbound-mode, or contact failure: the sender and recipient may both exist, but route validation or `inbound_mode=open|team_and_contacts` policy prevents discovery or inbound delivery.
 
 ## Joining a team
 
@@ -143,7 +143,7 @@ For custodial identities, rotation and recovery are cloud-account operations. Do
 
 First contact to a global identity uses a concrete address route such as `<domain>/<alias>`. A bare `did:aw` is identity binding, not a first-contact delivery route. Legacy reachability fields may still appear in support/audit views, but they are compatibility/audit state, not live delivery authority.
 
-Delivery authorization is `inbound_mode=open|contacts_only`: `open` accepts valid senders after route validation, while `contacts_only` requires an exact active identity contact after the route is valid. Contacts do not synthesize routes and are not team-global authority.
+Delivery authorization is `inbound_mode=open|team_and_contacts`: `open` accepts valid routed senders, while `team_and_contacts` accepts verified same-team senders plus exact active identity contacts after the route is valid. Team membership is always delivery authority in `team_and_contacts`; contacts only add trusted non-team senders. Contacts do not synthesize routes or resolver visibility.
 
 Contacts are saved identity/address relationships for repeated cross-team messaging. They are per-identity, not per-team. Add a contact when repeated communication is expected; otherwise use a one-shot namespace address.
 
@@ -168,8 +168,8 @@ Treat teams as separate coordination boundaries for tasks, locks, roles, instruc
 Check:
 
 1. Global address registration and route resolution.
-2. Inbound mode (`open` or `contacts_only`).
-3. Exact active contact state when the recipient uses `contacts_only`.
+2. Inbound mode (`open` or `team_and_contacts`).
+3. Verified shared team membership, or exact active contact state for non-team senders, when the recipient uses `team_and_contacts`.
 4. Whether X is using a same-team alias or a concrete cross-team address.
 5. Whether the active team is the intended team for sender context.
 6. Whether the workspace has a valid certificate.

package/skills/aweb-team-membership/references/team-membership-reference.md

@@ -40,9 +40,9 @@ Addressability and delivery authorization are separate:
 
 - First contact uses a concrete address route (`domain/alias`).
 - `did:aw` is identity binding, not a first-contact delivery route.
-- `inbound_mode=open|contacts_only` controls delivery after route validation.
-- Exact active identity contacts authorize `contacts_only`; contacts do not create routes or resolver visibility.
-- Legacy reachability/access-mode fields may still appear in support or migration output, but they are compatibility/audit state, not live delivery authority.
+- `inbound_mode=open|team_and_contacts` controls delivery after route validation.
+- `team_and_contacts` accepts verified same-team senders plus exact active identity contacts for trusted non-team senders. Contacts do not create routes or resolver visibility.
+- Legacy reachability fields may still appear in support or migration output, but they are compatibility/audit state, not live delivery authority.
 - `aw contacts ...` manages saved contact relationships.
 - `aw directory <domain>/<alias>` performs directory lookup.