@awebai/claude-skills 0.1.0 → 0.2.0

package/.claude-plugin/plugin.json

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

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.0",
+  "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.