@awebai/claude-skills 0.2.10 → 0.2.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/package.json +1 -1
- package/skills/aweb-bootstrap/SKILL.md +320 -139
- package/skills/aweb-bootstrap/references/bootstrap-scenarios.md +222 -67
- package/skills/aweb-identity/SKILL.md +3 -3
- package/skills/aweb-messaging/SKILL.md +10 -8
- package/skills/aweb-team-membership/SKILL.md +10 -3
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/claude-skills",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.12",
|
|
4
4
|
"description": "Content-only Claude Code plugin shipping the canonical aweb agent-coordination skills: aweb-coordination, aweb-messaging, aweb-team-membership, aweb-bootstrap, aweb-identity.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://aweb.ai",
|
|
@@ -1,267 +1,448 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: aweb-bootstrap
|
|
3
|
-
description: This skill should be used when helping a human create or
|
|
3
|
+
description: This skill should be used when helping a human create, provision, add, or remove repo-local aweb agents with the `aw agents` lifecycle from a template, choosing a team source (hosted new team, BYOT, API key, invite, or current workspace forwarding), using the project-local agents/ layout, provisioning optional worktree-bound agents, and validating/re-running safely.
|
|
4
4
|
allowed-tools: "Bash(aw *)"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# aweb Bootstrap
|
|
8
8
|
|
|
9
|
-
Use this skill when a human wants to create or extend
|
|
9
|
+
Use this skill when a human wants to create or extend a repo-local
|
|
10
|
+
aweb agent team from a reusable template, and you need to guide them
|
|
11
|
+
through `aw agents` decisions and validation.
|
|
10
12
|
|
|
11
|
-
This skill is about **mental model + decision policy + safe
|
|
13
|
+
This skill is about **mental model + decision policy + safe
|
|
14
|
+
execution**, not memorizing flags.
|
|
12
15
|
|
|
13
16
|
Related skills:
|
|
14
17
|
|
|
15
18
|
- For day-to-day coordination once the team exists: `aweb-coordination`
|
|
16
19
|
- For mail/chat response policy: `aweb-messaging`
|
|
17
|
-
- For joining an existing team, multi-team membership, custody,
|
|
20
|
+
- For joining an existing team, multi-team membership, custody,
|
|
21
|
+
addressability, and contacts: `aweb-team-membership`
|
|
18
22
|
|
|
19
23
|
Long-form reference: docs/team-bootstrap.md in the aweb repo.
|
|
20
24
|
|
|
21
25
|
## Mental model: what bootstrap is assembling
|
|
22
26
|
|
|
23
|
-
`aw
|
|
27
|
+
`aw agents bootstrap` combines five separate things that are easy to
|
|
28
|
+
confuse:
|
|
24
29
|
|
|
25
30
|
1) Template repo — the blueprint.
|
|
26
31
|
|
|
27
|
-
- Contains `team.yaml`, role playbooks, shared instructions, and
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
32
|
+
- Contains `team.yaml`, role playbooks, shared instructions, and
|
|
33
|
+
`home/<responsibility>/AGENTS.md` files.
|
|
34
|
+
- The template says what responsibilities should exist and which
|
|
35
|
+
`role_name` each should use.
|
|
36
|
+
- The template is identity-free. Do not put final aliases, DIDs,
|
|
37
|
+
global addresses, certs, or per-human state in committed
|
|
38
|
+
`team.yaml`.
|
|
39
|
+
|
|
40
|
+
2) Generated project-local agents directory — where humans start agents.
|
|
41
|
+
|
|
42
|
+
- By default, run bootstrap from the root of the work repo.
|
|
43
|
+
- Bootstrap creates `agents/` in that repo. Every live agent home is
|
|
44
|
+
under `agents/home/<responsibility>/`.
|
|
45
|
+
- The coordinator/global-style home normally has `work -> <repo-root>`.
|
|
46
|
+
- Worktree-bound homes still live under
|
|
47
|
+
`agents/home/<responsibility>/`; their `work` symlink points at
|
|
48
|
+
`agents/worktrees/<worktree-name>/`.
|
|
49
|
+
- Use `--agents-dir <name>` only when the repo already uses `agents/`
|
|
50
|
+
for something else. If the target directory exists, bootstrap must
|
|
51
|
+
fail before side effects.
|
|
35
52
|
|
|
36
53
|
3) Team source — the authority/context the generated agents join.
|
|
37
54
|
|
|
38
|
-
- Hosted new team, existing hosted team via `AWEB_API_KEY`, explicit
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
55
|
+
- Hosted new team, existing hosted team via `AWEB_API_KEY`, explicit
|
|
56
|
+
`--invite-token`, current workspace forwarding, or BYOT.
|
|
57
|
+
- Exactly one explicit source is allowed. If no explicit source is set
|
|
58
|
+
and cwd is already an aw workspace, bootstrap forwards that current
|
|
59
|
+
team. If no current workspace exists and the run is interactive,
|
|
60
|
+
bootstrap creates a hosted team. Non-interactive runs need an
|
|
61
|
+
explicit source.
|
|
62
|
+
|
|
63
|
+
4) Per-human naming — how shared layouts avoid collisions.
|
|
64
|
+
|
|
65
|
+
- Use `--identity-prefix <slug>` for shared repos. Examples: `juan`,
|
|
66
|
+
`maria`, `acme-dev`.
|
|
67
|
+
- Canonical multi-human templates use patterns such as
|
|
68
|
+
`{user}-{classic-name}` for local aliases and
|
|
69
|
+
`{user}-{responsibility}` for global address names.
|
|
70
|
+
- Never commit the final planned alias/address to `team.yaml`; it
|
|
71
|
+
belongs in ignored `.aw/` state under each agent home.
|
|
72
|
+
|
|
73
|
+
5) Generated workspaces — the identities that will act.
|
|
74
|
+
|
|
75
|
+
- Each `agents/home/<responsibility>/` directory becomes an aw
|
|
76
|
+
workspace with its own identity and team certificate.
|
|
77
|
+
- The **first generated plan** is the anchor: bootstrap connects it
|
|
78
|
+
first, installs roles/instructions from that workspace's team
|
|
79
|
+
context, then invites/connects the rest.
|
|
80
|
+
- Do not assume a responsibility named `implementation` is special.
|
|
81
|
+
The anchor is the first plan the CLI generated.
|
|
46
82
|
|
|
47
83
|
Aweb team source terms:
|
|
48
84
|
|
|
49
85
|
- Hosted new team: aweb.ai creates/hosts the team.
|
|
50
|
-
- API key: joins the hosted team represented by `AWEB_API_KEY`;
|
|
86
|
+
- API key: joins the hosted team represented by `AWEB_API_KEY`;
|
|
87
|
+
`--aweb-url`/`AWEB_URL` is optional and defaults to hosted aweb.ai.
|
|
51
88
|
- Invite token: first generated workspace accepts an existing invite.
|
|
52
|
-
- Current workspace forwarding: caller cwd already has `.aw`;
|
|
53
|
-
|
|
89
|
+
- Current workspace forwarding: caller cwd already has `.aw`;
|
|
90
|
+
bootstrap creates a one-use invite from that active team.
|
|
91
|
+
- BYOT: bring your own team. This includes bringing your own
|
|
92
|
+
domain/namespace and controller key. Do not describe a separate
|
|
93
|
+
domain-only bootstrap mode.
|
|
54
94
|
|
|
55
|
-
## Bootstrap vs
|
|
95
|
+
## Bootstrap vs provision vs add
|
|
56
96
|
|
|
57
|
-
|
|
97
|
+
Use `aw agents bootstrap` when:
|
|
58
98
|
|
|
99
|
+
- You are creating the committed `agents/` layout for a repo.
|
|
59
100
|
- You are creating a brand-new team from a template.
|
|
60
|
-
- You are extending an existing team with a template-defined set of
|
|
61
|
-
|
|
62
|
-
|
|
101
|
+
- You are extending an existing team with a template-defined set of
|
|
102
|
+
agent homes, roles, and instructions.
|
|
103
|
+
|
|
104
|
+
Use `aw agents provision` when:
|
|
105
|
+
|
|
106
|
+
- The repo already has a committed `agents/` layout.
|
|
107
|
+
- Another human needs their own local `.aw/` state for the same
|
|
108
|
+
responsibilities.
|
|
109
|
+
- They have an invite, API key, BYOT authority, or current workspace
|
|
110
|
+
context for the same team.
|
|
111
|
+
|
|
112
|
+
Use `aw agents add` or `aw agents add-worktree` when:
|
|
113
|
+
|
|
114
|
+
- The layout already exists and you need one more responsibility.
|
|
115
|
+
- You want a repo-root agent (`add`) or isolated git worktree agent
|
|
116
|
+
(`add-worktree`).
|
|
63
117
|
|
|
64
118
|
Do NOT bootstrap when:
|
|
65
119
|
|
|
66
|
-
- The team already exists and you just need to add yourself: use
|
|
67
|
-
-
|
|
120
|
+
- The team already exists and you just need to add yourself: use
|
|
121
|
+
`aweb-team-membership` and the `aw id team ...` commands.
|
|
122
|
+
- You only need another workspace for yourself outside the repo-local
|
|
123
|
+
convention: use `aw workspace add-worktree` or create another
|
|
124
|
+
directory and `aw init` it.
|
|
68
125
|
|
|
69
|
-
## Pick a template
|
|
126
|
+
## Pick a template
|
|
70
127
|
|
|
71
128
|
Canonical templates:
|
|
72
129
|
|
|
73
|
-
- awebai/aweb-team-
|
|
74
|
-
Use when you want
|
|
75
|
-
|
|
76
|
-
- awebai/aweb-team-company-surfaces
|
|
77
|
-
Use when you want a cross-functional team: direction/engineering/
|
|
130
|
+
- awebai/aweb-team-coord-worktrees
|
|
131
|
+
Use when you want a coordinator plus isolated developer/reviewer git
|
|
132
|
+
worktrees in the current repo.
|
|
133
|
+
- awebai/aweb-team-company-surfaces
|
|
134
|
+
Use when you want a cross-functional team: direction/engineering/
|
|
135
|
+
operations/support/outreach/analytics.
|
|
78
136
|
|
|
79
137
|
Fork/edit vs use-as-is:
|
|
80
138
|
|
|
81
139
|
- Use as-is to learn the flow or to run a standard team.
|
|
82
|
-
- Clone or fork when you want to customize roles, responsibilities, or
|
|
83
|
-
|
|
140
|
+
- Clone or fork when you want to customize roles, responsibilities, or
|
|
141
|
+
instructions before provisioning.
|
|
142
|
+
- It is safe to edit the template checkout before applying it;
|
|
143
|
+
`aw agents bootstrap` reads `team.yaml`, `roles/`, `docs/`, and
|
|
144
|
+
`home/` from the local template directory at run time.
|
|
84
145
|
|
|
85
146
|
## Customizing a template before applying it
|
|
86
147
|
|
|
87
|
-
When the human wants different agents, role playbooks, names, or
|
|
148
|
+
When the human wants different agents, role playbooks, names, or
|
|
149
|
+
instructions, do not patch generated workspaces after bootstrap.
|
|
150
|
+
Clone/edit the template first, then bootstrap the edited local
|
|
151
|
+
directory.
|
|
88
152
|
|
|
89
153
|
Typical safe flow:
|
|
90
154
|
|
|
91
155
|
```bash
|
|
92
|
-
git clone https://github.com/awebai/aweb-team-
|
|
156
|
+
git clone https://github.com/awebai/aweb-team-coord-worktrees.git my-team-template
|
|
93
157
|
cd my-team-template
|
|
94
|
-
# edit team.yaml, roles/*.md, docs/team.md,
|
|
95
|
-
|
|
96
|
-
aw
|
|
158
|
+
# edit team.yaml, roles/*.md, docs/team.md, home/<responsibility>/AGENTS.md
|
|
159
|
+
cd /path/to/project-repo
|
|
160
|
+
aw agents bootstrap /path/to/my-team-template --dry-run --identity-prefix juan
|
|
161
|
+
aw agents bootstrap /path/to/my-team-template --username alice --identity-prefix juan
|
|
97
162
|
```
|
|
98
163
|
|
|
99
164
|
What to edit:
|
|
100
165
|
|
|
101
|
-
- `team.yaml` roles: add/remove role names and point each to a role
|
|
102
|
-
|
|
103
|
-
- `team.yaml`
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
- `
|
|
166
|
+
- `team.yaml` roles: add/remove role names and point each to a role
|
|
167
|
+
file.
|
|
168
|
+
- `team.yaml` agents: add/remove responsibility workspaces and set
|
|
169
|
+
each `role_name`, optional `identity_scope`, optional
|
|
170
|
+
`home_template`, and optional `work`.
|
|
171
|
+
- `team.yaml` naming: for shared repos, prefer
|
|
172
|
+
`naming.local_alias.pattern: "{user}-{classic-name}"`.
|
|
173
|
+
- Use `work: repo_root` for an agent whose `work` symlink points to
|
|
174
|
+
the project repo root.
|
|
175
|
+
- Use `work: git_worktree` for an agent whose `work` symlink points
|
|
176
|
+
to a generated git worktree under `agents/worktrees/`.
|
|
177
|
+
- `roles/*.md`: change operational playbooks installed with
|
|
178
|
+
`aw roles`.
|
|
179
|
+
- `docs/team.md`: change shared team instructions installed after the
|
|
180
|
+
anchor connects.
|
|
181
|
+
- `home/<responsibility>/AGENTS.md`: change per-workspace startup
|
|
182
|
+
context.
|
|
183
|
+
|
|
184
|
+
Do not use `default_name` or `default_alias` in current templates.
|
|
185
|
+
Those are legacy hints only and must not become committed identity
|
|
186
|
+
state.
|
|
187
|
+
|
|
188
|
+
## Before running bootstrap
|
|
189
|
+
|
|
190
|
+
1) For the default layout, run bootstrap from the root of the project
|
|
191
|
+
git repo.
|
|
192
|
+
|
|
193
|
+
- Bootstrap creates `agents/` there.
|
|
194
|
+
- If `agents/` exists, stop. Do not ask bootstrap to adopt, merge, or
|
|
195
|
+
overwrite it.
|
|
196
|
+
- If the project already has a different `agents/` directory, ask the
|
|
197
|
+
human for a different `--agents-dir <name>`.
|
|
198
|
+
|
|
199
|
+
2) Decide the team source. This affects whether bootstrap creates a
|
|
200
|
+
new hosted team, joins an API-key/invite team, forwards the current
|
|
201
|
+
team, or uses BYOT.
|
|
202
|
+
|
|
203
|
+
3) Decide the identity prefix. Shared repos should always pass
|
|
204
|
+
`--identity-prefix <human-slug>` explicitly.
|
|
205
|
+
|
|
206
|
+
## Default layout: project-local agents/
|
|
207
|
+
|
|
208
|
+
New bootstrap runs should normally use the default layout:
|
|
107
209
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
- If you are inside a git repo/worktree and you are using a remote template ref, bootstrap will refuse to clone by default.
|
|
115
|
-
- Use `--template-cache-dir` as the explicit escape hatch when you must run from inside a repo.
|
|
210
|
+
```bash
|
|
211
|
+
cd /path/to/project-repo
|
|
212
|
+
aw agents bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git \
|
|
213
|
+
--username alice \
|
|
214
|
+
--identity-prefix juan
|
|
215
|
+
```
|
|
116
216
|
|
|
117
|
-
|
|
217
|
+
Expected generated shape:
|
|
218
|
+
|
|
219
|
+
```text
|
|
220
|
+
agents/
|
|
221
|
+
team.yaml
|
|
222
|
+
docs/
|
|
223
|
+
roles/
|
|
224
|
+
home/
|
|
225
|
+
coordinator/
|
|
226
|
+
.aw/
|
|
227
|
+
AGENTS.md
|
|
228
|
+
work -> ../../..
|
|
229
|
+
developer/
|
|
230
|
+
.aw/
|
|
231
|
+
AGENTS.md
|
|
232
|
+
work -> ../../worktrees/developer
|
|
233
|
+
reviewer/
|
|
234
|
+
.aw/
|
|
235
|
+
AGENTS.md
|
|
236
|
+
work -> ../../worktrees/reviewer
|
|
237
|
+
worktrees/
|
|
238
|
+
developer/
|
|
239
|
+
reviewer/
|
|
240
|
+
```
|
|
118
241
|
|
|
119
|
-
|
|
242
|
+
The repo root itself is not an aw workspace. Start Codex, Claude Code,
|
|
243
|
+
or Pi from an agent home:
|
|
120
244
|
|
|
121
|
-
|
|
245
|
+
```bash
|
|
246
|
+
cd agents/home/coordinator
|
|
247
|
+
codex
|
|
248
|
+
```
|
|
122
249
|
|
|
123
|
-
|
|
250
|
+
Bootstrap writes scoped `.gitignore` entries for
|
|
251
|
+
`agents/home/*/.aw/`, `agents/home/*/work`, and `agents/worktrees/`.
|
|
252
|
+
It must not ignore the whole `agents/` directory.
|
|
124
253
|
|
|
125
|
-
|
|
254
|
+
If an older generated repo tracked `agents/home/*/work`, remove those
|
|
255
|
+
symlinks from git after upgrading:
|
|
126
256
|
|
|
127
|
-
|
|
128
|
-
|
|
257
|
+
```bash
|
|
258
|
+
git rm --cached agents/home/*/work
|
|
259
|
+
git add .gitignore agents
|
|
260
|
+
git commit -m "agents: ignore generated work symlinks"
|
|
261
|
+
```
|
|
129
262
|
|
|
130
|
-
|
|
263
|
+
## Multi-human shared repo flow
|
|
131
264
|
|
|
132
|
-
|
|
133
|
-
- VALUE can be a URL or a local path; bootstrap runs “git clone VALUE” into:
|
|
265
|
+
First human:
|
|
134
266
|
|
|
135
|
-
|
|
267
|
+
```bash
|
|
268
|
+
cd /path/to/project-repo
|
|
269
|
+
aw agents bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git \
|
|
270
|
+
--username alice \
|
|
271
|
+
--identity-prefix juan
|
|
272
|
+
git add agents .gitignore
|
|
273
|
+
git commit -m "agents: add team layout"
|
|
274
|
+
```
|
|
136
275
|
|
|
137
|
-
|
|
276
|
+
Second human:
|
|
138
277
|
|
|
139
|
-
|
|
278
|
+
```bash
|
|
279
|
+
git pull
|
|
280
|
+
aw agents provision --invite-token <token> --identity-prefix maria
|
|
281
|
+
cd agents/home/coordinator
|
|
282
|
+
codex
|
|
283
|
+
```
|
|
140
284
|
|
|
141
|
-
|
|
285
|
+
The second human does not run bootstrap over the existing `agents/`
|
|
286
|
+
directory. Provision reads the committed layout and writes only ignored
|
|
287
|
+
local state.
|
|
142
288
|
|
|
143
289
|
## Team source policy
|
|
144
290
|
|
|
145
|
-
Non-dry-run bootstrap needs one coherent team source.
|
|
291
|
+
Non-dry-run bootstrap needs one coherent team source.
|
|
146
292
|
|
|
147
293
|
Resolution order:
|
|
148
294
|
|
|
149
|
-
- If any explicit source is set (`AWEB_API_KEY`, `--invite-token`,
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
- If no source
|
|
153
|
-
|
|
154
|
-
|
|
295
|
+
- If any explicit source is set (`AWEB_API_KEY`, `--invite-token`,
|
|
296
|
+
`--username`, or `--namespace/--team`), do not set another explicit
|
|
297
|
+
source.
|
|
298
|
+
- If no explicit source is set and cwd is an initialized aw workspace,
|
|
299
|
+
bootstrap forwards the current active team.
|
|
300
|
+
- If no explicit source is set, cwd is not an aw workspace, and the
|
|
301
|
+
run is interactive, bootstrap creates/uses a hosted team through
|
|
302
|
+
onboarding prompts.
|
|
303
|
+
- If no source can be resolved, stop and ask the human which team
|
|
304
|
+
source to use.
|
|
155
305
|
|
|
156
306
|
Supported sources:
|
|
157
307
|
|
|
158
|
-
1) Hosted new team
|
|
308
|
+
1) Hosted new team
|
|
159
309
|
|
|
160
310
|
- Best for first-time teams.
|
|
161
311
|
- Use `--username <name>` or run interactively in a TTY.
|
|
162
|
-
- Bootstrap uses the same hosted onboarding path as `aw init` for the
|
|
312
|
+
- Bootstrap uses the same hosted onboarding path as `aw init` for the
|
|
313
|
+
first generated workspace.
|
|
163
314
|
|
|
164
315
|
2) Existing hosted team via API key
|
|
165
316
|
|
|
166
317
|
- If `AWEB_API_KEY` is set, bootstrap joins the API key's hosted team.
|
|
167
|
-
- `--aweb-url`/`AWEB_URL` is optional; when omitted, the hosted
|
|
318
|
+
- `--aweb-url`/`AWEB_URL` is optional; when omitted, the hosted
|
|
319
|
+
aweb.ai default is used.
|
|
168
320
|
- Do not also pass `--username`, `--invite-token`, or BYOT flags.
|
|
169
321
|
|
|
170
322
|
3) Existing team via invite token
|
|
171
323
|
|
|
172
324
|
- Pass `--invite-token <token>`.
|
|
173
|
-
- Bootstrap accepts it into the first generated workspace, then
|
|
325
|
+
- Bootstrap accepts it into the first generated workspace, then
|
|
326
|
+
creates further invites from that established team context.
|
|
174
327
|
|
|
175
328
|
4) Current workspace forwarding
|
|
176
329
|
|
|
177
|
-
- If
|
|
178
|
-
|
|
330
|
+
- If caller cwd is already initialized for aw and no explicit source
|
|
331
|
+
is set, bootstrap creates a one-use invite from the current active
|
|
332
|
+
team and accepts it into the first generated workspace.
|
|
179
333
|
|
|
180
|
-
5) BYOT
|
|
334
|
+
5) BYOT
|
|
181
335
|
|
|
182
|
-
- Use `--namespace <domain> --team <slug>` when the team's namespace/
|
|
183
|
-
|
|
184
|
-
- Bootstrap creates/ensures the team in that namespace, invites the
|
|
336
|
+
- Use `--namespace <domain> --team <slug>` when the team's namespace/
|
|
337
|
+
domain and controller key live in your environment.
|
|
338
|
+
- Bootstrap creates/ensures the team in that namespace, invites the
|
|
339
|
+
first generated workspace, then uses it as the anchor.
|
|
185
340
|
|
|
186
341
|
Decision recipe:
|
|
187
342
|
|
|
188
|
-
- Human says
|
|
189
|
-
|
|
343
|
+
- Human says "make me a new team" and has no existing aw context: use
|
|
344
|
+
hosted (`--username` or interactive prompt) plus
|
|
345
|
+
`--identity-prefix`.
|
|
346
|
+
- Human has a dashboard/API key: use
|
|
347
|
+
`AWEB_API_KEY=... aw agents bootstrap ... --identity-prefix <slug>`.
|
|
190
348
|
- Human pasted an invite: use `--invite-token`.
|
|
191
|
-
- Human is already inside the team workspace that should own the new
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
349
|
+
- Human is already inside the team workspace that should own the new
|
|
350
|
+
agents: use current workspace forwarding.
|
|
351
|
+
- Human controls a namespace/domain and wants the team under that
|
|
352
|
+
namespace: use BYOT (`--namespace` + `--team`).
|
|
195
353
|
|
|
196
|
-
|
|
197
|
-
- Prefer API key or invite when the team already exists but the caller is not already inside it.
|
|
198
|
-
- Prefer current workspace forwarding when you are already inside the target team.
|
|
199
|
-
- Prefer BYOT when you need local control over the team namespace/domain and routing.
|
|
200
|
-
- Use `--dry-run` for planning only. It prints the resolved plan (template ref, work directory, team source, generated workspaces) without writing identities, files, or server state. Do not pair it with side-effecting flags expecting partial provisioning.
|
|
201
|
-
|
|
202
|
-
## Worktree agents (team.yaml worktrees:)
|
|
354
|
+
## Adding agents later
|
|
203
355
|
|
|
204
|
-
|
|
356
|
+
Add a repo-root local responsibility:
|
|
205
357
|
|
|
206
|
-
|
|
207
|
-
|
|
358
|
+
```bash
|
|
359
|
+
aw agents add support --role support
|
|
360
|
+
```
|
|
208
361
|
|
|
209
|
-
|
|
362
|
+
Add a worktree-bound local responsibility:
|
|
210
363
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
364
|
+
```bash
|
|
365
|
+
aw agents add-worktree developer --role developer
|
|
366
|
+
```
|
|
214
367
|
|
|
215
|
-
|
|
368
|
+
Add a global BYOT responsibility:
|
|
216
369
|
|
|
217
|
-
|
|
218
|
-
|
|
370
|
+
```bash
|
|
371
|
+
aw agents add support \
|
|
372
|
+
--global \
|
|
373
|
+
--namespace example.com \
|
|
374
|
+
--team circle \
|
|
375
|
+
--identity-prefix juan
|
|
376
|
+
```
|
|
219
377
|
|
|
220
|
-
|
|
378
|
+
Remove explicitly separates layout and identity effects:
|
|
221
379
|
|
|
222
|
-
|
|
380
|
+
```bash
|
|
381
|
+
aw agents remove support --remove-layout
|
|
382
|
+
aw agents remove support --deprovision-local
|
|
383
|
+
aw agents remove support --delete-global-address
|
|
384
|
+
```
|
|
223
385
|
|
|
224
|
-
|
|
386
|
+
`--remove-layout` does not revoke other humans' certs and does not
|
|
387
|
+
delete their ignored `.aw/` state.
|
|
225
388
|
|
|
226
|
-
|
|
389
|
+
`--deprovision-local` uses the local team controller key for self-custodial
|
|
390
|
+
teams. For hosted-managed cert-only agents, it can use the agent's own signing
|
|
391
|
+
key and active team certificate to ask the hosted service to deprovision that
|
|
392
|
+
same agent. It must not be described as dashboard authority over BYOT members.
|
|
227
393
|
|
|
228
|
-
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
394
|
+
`--delete-global-address` is opt-in. Self-custodial namespaces require the
|
|
395
|
+
local namespace controller key. Hosted-managed global agents can delete only
|
|
396
|
+
hosted-managed addresses through hosted self-deprovision; BYOT/unmanaged
|
|
397
|
+
addresses remain customer-controller-owned.
|
|
232
398
|
|
|
233
|
-
-
|
|
399
|
+
Map hosted self-deprovision structured errors to concrete recovery:
|
|
234
400
|
|
|
235
|
-
-
|
|
401
|
+
- `hosted_team_controller_required`: use/restore the self-custodial team
|
|
402
|
+
controller key; this is not a hosted-managed team.
|
|
403
|
+
- `global_address_not_hosted_managed`: delete the address with the customer
|
|
404
|
+
namespace controller; the hosted service must not delete BYOT/unmanaged
|
|
405
|
+
addresses.
|
|
406
|
+
- `delete_global_address_required`: rerun with `--delete-global-address` for a
|
|
407
|
+
hosted-managed global agent.
|
|
408
|
+
- `local_identity_has_no_global_address`: rerun without
|
|
409
|
+
`--delete-global-address`; local identities do not have global addresses.
|
|
236
410
|
|
|
237
|
-
##
|
|
411
|
+
## Legacy mode
|
|
238
412
|
|
|
239
|
-
|
|
413
|
+
Legacy out-of-repo mode is still supported for existing scripts that
|
|
414
|
+
pass `--work-directory` or `--work-repo-url`. Do not choose it for a
|
|
415
|
+
new customer unless they explicitly need the old shape.
|
|
240
416
|
|
|
241
|
-
|
|
242
|
-
- Use `--refresh-template` only when you intend to re-clone over a previous template checkout.
|
|
243
|
-
- Treat identity/certificate state under .aw/ as the source of truth; do not delete it casually.
|
|
244
|
-
- If you need to create a fresh workspace, do it in a new directory rather than mutating an existing identity in place.
|
|
417
|
+
## After bootstrap: validate that the team is usable
|
|
245
418
|
|
|
246
|
-
|
|
419
|
+
For each agent directory under `agents/home/<responsibility>/`:
|
|
247
420
|
|
|
248
|
-
-
|
|
249
|
-
|
|
250
|
-
-
|
|
421
|
+
- Run `aw workspace status` to confirm the workspace is initialized,
|
|
422
|
+
the active team is correct, and the identity is present.
|
|
423
|
+
- Run `aw whoami` to confirm identity fields are present.
|
|
424
|
+
- If you use a wake-up path (Pi extension / Claude Code channel
|
|
425
|
+
plugin), start it inside the agent directory after initialization.
|
|
251
426
|
|
|
252
|
-
##
|
|
427
|
+
## Troubleshooting policy
|
|
253
428
|
|
|
254
|
-
|
|
429
|
+
If bootstrap fails:
|
|
255
430
|
|
|
256
|
-
-
|
|
257
|
-
-
|
|
431
|
+
- Stop and capture the first error.
|
|
432
|
+
- Do not retry over an existing `agents/` directory.
|
|
433
|
+
- Prefer explicit recovery with `aw agents provision`, `aw agents add`,
|
|
434
|
+
or `aw agents remove` over deleting `.aw/` state.
|
|
435
|
+
- If you must remove generated state, inspect/back up `.aw/` first.
|
|
258
436
|
|
|
259
|
-
|
|
437
|
+
If a multi-human provision hits an alias/address conflict, rerun with a
|
|
438
|
+
different `--identity-prefix` or naming pattern. Invite-only flows may
|
|
439
|
+
discover collisions only when accepting/registering; this is expected
|
|
440
|
+
fail-closed behavior.
|
|
260
441
|
|
|
261
442
|
## References
|
|
262
443
|
|
|
263
444
|
Read these only when deeper context is needed:
|
|
264
445
|
|
|
265
|
-
- references/bootstrap-scenarios.md: scenarios, checklists, and
|
|
266
|
-
|
|
446
|
+
- references/bootstrap-scenarios.md: scenarios, checklists, and
|
|
447
|
+
troubleshooting.
|
|
267
448
|
- docs/team-bootstrap.md (aweb repo checkout): full reference guide.
|
|
@@ -1,87 +1,149 @@
|
|
|
1
|
-
# aweb
|
|
1
|
+
# aweb agents bootstrap scenarios and checklists
|
|
2
2
|
|
|
3
|
-
This reference is support material for the aweb-bootstrap skill. Use it
|
|
3
|
+
This reference is support material for the aweb-bootstrap skill. Use it
|
|
4
|
+
when you need concrete examples, troubleshooting checklists, or a quick
|
|
5
|
+
"what should I run next?" guide.
|
|
4
6
|
|
|
5
|
-
It is intentionally narrower than docs/team-bootstrap.md: it focuses on
|
|
7
|
+
It is intentionally narrower than docs/team-bootstrap.md: it focuses on
|
|
8
|
+
common decision points and failure modes.
|
|
6
9
|
|
|
7
10
|
## Quick mental model
|
|
8
11
|
|
|
9
|
-
- Template repo = blueprint for roles, instructions, and
|
|
10
|
-
|
|
12
|
+
- Template repo = blueprint for roles, instructions, and agent home
|
|
13
|
+
templates.
|
|
14
|
+
- Default generated layout = project-local `agents/` directory
|
|
15
|
+
containing `home/`, `worktrees/`, `roles/`, `docs/`, and `team.yaml`.
|
|
16
|
+
- Work target = what each agent's `work` symlink points at: the repo
|
|
17
|
+
root (`work: repo_root`) or a generated git worktree
|
|
18
|
+
(`work: git_worktree`).
|
|
11
19
|
- Team source = the authority the generated agents join.
|
|
12
|
-
-
|
|
13
|
-
|
|
20
|
+
- Identity prefix = the per-human slug used to avoid alias/address
|
|
21
|
+
collisions in shared repos.
|
|
22
|
+
- First generated workspace = bootstrap anchor. It connects first;
|
|
23
|
+
roles/instructions install through it; all other generated agents
|
|
24
|
+
join through invites from that established team context.
|
|
25
|
+
- BYOT means bring your own team, including your own namespace/domain
|
|
26
|
+
and controller key. Do not present a separate domain-only bootstrap
|
|
27
|
+
mode.
|
|
14
28
|
|
|
15
29
|
Team-source precedence:
|
|
16
30
|
|
|
17
|
-
- Explicit sources conflict: use only one of `AWEB_API_KEY`,
|
|
18
|
-
-
|
|
19
|
-
- With no explicit source
|
|
20
|
-
|
|
31
|
+
- Explicit sources conflict: use only one of `AWEB_API_KEY`,
|
|
32
|
+
`--invite-token`, `--username`, or `--namespace/--team`.
|
|
33
|
+
- With no explicit source, an initialized caller cwd forwards its
|
|
34
|
+
current active team.
|
|
35
|
+
- With no explicit source and no caller workspace, an interactive run
|
|
36
|
+
uses hosted onboarding.
|
|
37
|
+
- Non-interactive runs need an explicit source or initialized caller
|
|
38
|
+
workspace.
|
|
21
39
|
|
|
22
|
-
## Scenario: first-time hosted team from a template
|
|
40
|
+
## Scenario: first-time hosted team from a template
|
|
23
41
|
|
|
24
|
-
Goal: create a new aweb.ai team and provision agent workspaces from a
|
|
42
|
+
Goal: create a new aweb.ai team and provision agent workspaces from a
|
|
43
|
+
template.
|
|
25
44
|
|
|
26
45
|
Checklist:
|
|
27
46
|
|
|
28
|
-
- Run from
|
|
29
|
-
-
|
|
30
|
-
|
|
31
|
-
|
|
47
|
+
- Run from the root of the project git repo.
|
|
48
|
+
- Confirm the target agents directory does not already exist. Default:
|
|
49
|
+
`agents/`.
|
|
50
|
+
- Pick a template.
|
|
51
|
+
- Pick a human-specific `--identity-prefix`.
|
|
32
52
|
|
|
33
|
-
Example
|
|
53
|
+
Example:
|
|
34
54
|
|
|
35
|
-
|
|
55
|
+
cd /path/to/project-repo
|
|
56
|
+
aw agents bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git \
|
|
57
|
+
--username alice \
|
|
58
|
+
--identity-prefix juan
|
|
36
59
|
|
|
37
|
-
Example
|
|
60
|
+
Example with a non-default agents directory:
|
|
38
61
|
|
|
39
|
-
|
|
62
|
+
cd /path/to/project-repo
|
|
63
|
+
aw agents bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git \
|
|
64
|
+
--username alice \
|
|
65
|
+
--identity-prefix juan \
|
|
66
|
+
--agents-dir aweb-agents
|
|
40
67
|
|
|
41
68
|
Notes:
|
|
42
69
|
|
|
43
|
-
-
|
|
44
|
-
|
|
70
|
+
- Bootstrap creates `agents/home/<responsibility>/` for every live
|
|
71
|
+
agent home.
|
|
72
|
+
- Worktree-bound agents get checkouts under
|
|
73
|
+
`agents/worktrees/<worktree-name>/`.
|
|
74
|
+
- The repo root is not an aw workspace; humans should start
|
|
75
|
+
Codex/Claude/Pi from `agents/home/<responsibility>/`.
|
|
76
|
+
|
|
77
|
+
## Scenario: second human provisions the same repo
|
|
78
|
+
|
|
79
|
+
Goal: another human clones the repo and creates their own ignored
|
|
80
|
+
identity state for the same committed layout.
|
|
81
|
+
|
|
82
|
+
Checklist:
|
|
83
|
+
|
|
84
|
+
- Do not run bootstrap over the existing `agents/` directory.
|
|
85
|
+
- Get an invite token, API key, BYOT authority, or current workspace
|
|
86
|
+
context for the same team.
|
|
87
|
+
- Use a different `--identity-prefix`.
|
|
88
|
+
|
|
89
|
+
Example:
|
|
90
|
+
|
|
91
|
+
git pull
|
|
92
|
+
aw agents provision --invite-token <token> --identity-prefix maria
|
|
93
|
+
cd agents/home/coordinator
|
|
94
|
+
codex
|
|
45
95
|
|
|
46
|
-
|
|
96
|
+
Expected behavior:
|
|
47
97
|
|
|
48
|
-
|
|
98
|
+
- Committed `agents/team.yaml`, `roles/`, `docs/`, and
|
|
99
|
+
`home/*/AGENTS.md` remain unchanged.
|
|
100
|
+
- Local `.aw/` state and `work` symlinks are regenerated under
|
|
101
|
+
`agents/home/*/`.
|
|
102
|
+
- Worktree directories are under `agents/worktrees/`.
|
|
49
103
|
|
|
50
104
|
## Scenario: customize the template before applying it
|
|
51
105
|
|
|
52
|
-
Goal: change roles, agent responsibilities,
|
|
106
|
+
Goal: change roles, agent responsibilities, naming policy, or
|
|
107
|
+
instructions before any team state is created.
|
|
53
108
|
|
|
54
109
|
Checklist:
|
|
55
110
|
|
|
56
111
|
- Clone or fork the template first.
|
|
57
|
-
- Edit `team.yaml`, `roles/*.md`, `docs/team.md`, and
|
|
58
|
-
|
|
59
|
-
-
|
|
112
|
+
- Edit `team.yaml`, `roles/*.md`, `docs/team.md`, and
|
|
113
|
+
`home/<responsibility>/AGENTS.md` as needed.
|
|
114
|
+
- Run `aw agents bootstrap /path/to/template --dry-run` from the
|
|
115
|
+
project repo root to validate.
|
|
116
|
+
- Bootstrap the local template directory only after the plan looks
|
|
117
|
+
right.
|
|
60
118
|
|
|
61
119
|
Example:
|
|
62
120
|
|
|
63
|
-
git clone https://github.com/awebai/aweb-team-
|
|
121
|
+
git clone https://github.com/awebai/aweb-team-coord-worktrees.git my-team-template
|
|
64
122
|
cd my-team-template
|
|
65
|
-
# edit team.yaml / roles / docs /
|
|
66
|
-
|
|
67
|
-
aw
|
|
123
|
+
# edit team.yaml / roles / docs / home
|
|
124
|
+
cd /path/to/project-repo
|
|
125
|
+
aw agents bootstrap /path/to/my-team-template --dry-run --identity-prefix juan
|
|
126
|
+
aw agents bootstrap /path/to/my-team-template --username alice --identity-prefix juan
|
|
68
127
|
|
|
69
|
-
## Scenario: BYOT
|
|
128
|
+
## Scenario: BYOT
|
|
70
129
|
|
|
71
130
|
Goal: bootstrap a team under a namespace/domain you control.
|
|
72
131
|
|
|
73
132
|
Checklist:
|
|
74
133
|
|
|
75
|
-
- Confirm
|
|
76
|
-
|
|
77
|
-
-
|
|
134
|
+
- Confirm the namespace is registered and the controller key is
|
|
135
|
+
available locally.
|
|
136
|
+
- Remember BYOT includes bringing your own domain; there is no separate
|
|
137
|
+
supported domain-only bootstrap mode.
|
|
138
|
+
- Bootstrap will connect the first generated workspace, install
|
|
139
|
+
roles/instructions there, then invite/connect the remaining agents.
|
|
78
140
|
|
|
79
|
-
Example shape
|
|
141
|
+
Example shape:
|
|
80
142
|
|
|
81
|
-
aw
|
|
143
|
+
aw agents bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git \
|
|
82
144
|
--namespace example.com \
|
|
83
145
|
--team dev \
|
|
84
|
-
--
|
|
146
|
+
--identity-prefix juan
|
|
85
147
|
|
|
86
148
|
If you are also self-hosting the coordination stack, add:
|
|
87
149
|
|
|
@@ -90,86 +152,179 @@ If you are also self-hosting the coordination stack, add:
|
|
|
90
152
|
|
|
91
153
|
## Scenario: existing hosted team via API key
|
|
92
154
|
|
|
93
|
-
Goal: provision a template into the hosted team associated with an API
|
|
155
|
+
Goal: provision a template into the hosted team associated with an API
|
|
156
|
+
key.
|
|
94
157
|
|
|
95
158
|
Checklist:
|
|
96
159
|
|
|
97
|
-
- Set AWEB_API_KEY
|
|
98
|
-
- Optionally set AWEB_URL or pass
|
|
99
|
-
-
|
|
160
|
+
- Set `AWEB_API_KEY`.
|
|
161
|
+
- Optionally set `AWEB_URL` or pass `--aweb-url` to target a
|
|
162
|
+
non-default stack; otherwise the hosted default is used.
|
|
163
|
+
- Do not also pass `--username`, `--invite-token`, or BYOT flags.
|
|
100
164
|
|
|
101
165
|
Example:
|
|
102
166
|
|
|
103
167
|
AWEB_API_KEY=aw_sk_... \
|
|
104
|
-
aw
|
|
168
|
+
aw agents bootstrap /path/to/template --identity-prefix juan
|
|
105
169
|
|
|
106
170
|
## Scenario: existing team via invite token
|
|
107
171
|
|
|
108
|
-
Goal: accept an invite into the first generated workspace and use it as
|
|
172
|
+
Goal: accept an invite into the first generated workspace and use it as
|
|
173
|
+
the anchor for the rest of bootstrap.
|
|
109
174
|
|
|
110
175
|
Example:
|
|
111
176
|
|
|
112
|
-
aw
|
|
177
|
+
aw agents bootstrap /path/to/template \
|
|
113
178
|
--invite-token <token> \
|
|
114
|
-
--
|
|
179
|
+
--identity-prefix maria
|
|
115
180
|
|
|
116
181
|
## Scenario: current workspace forwarding
|
|
117
182
|
|
|
118
|
-
Goal: run bootstrap from an existing aw workspace and forward that
|
|
183
|
+
Goal: run bootstrap from an existing aw workspace and forward that
|
|
184
|
+
active team into the generated template workspaces.
|
|
119
185
|
|
|
120
186
|
Checklist:
|
|
121
187
|
|
|
122
188
|
- Confirm `aw workspace status` succeeds in the caller cwd.
|
|
123
189
|
- Do not pass another explicit team source.
|
|
124
|
-
- Bootstrap will create a one-use invite from the current active team
|
|
190
|
+
- Bootstrap will create a one-use invite from the current active team
|
|
191
|
+
for the first generated workspace.
|
|
125
192
|
|
|
126
193
|
## Scenario: dry-run planning
|
|
127
194
|
|
|
128
|
-
Goal: validate the plan and see generated workspace commands without
|
|
195
|
+
Goal: validate the plan and see generated workspace commands without
|
|
196
|
+
changing files, identities, or server state.
|
|
129
197
|
|
|
130
198
|
Example:
|
|
131
199
|
|
|
132
|
-
aw
|
|
200
|
+
aw agents bootstrap /path/to/template --dry-run --identity-prefix juan
|
|
201
|
+
|
|
202
|
+
## Scenario: add a new responsibility later
|
|
203
|
+
|
|
204
|
+
Repo-root local agent:
|
|
205
|
+
|
|
206
|
+
aw agents add support --role support
|
|
207
|
+
|
|
208
|
+
Worktree-bound local agent:
|
|
209
|
+
|
|
210
|
+
aw agents add-worktree developer --role developer
|
|
211
|
+
|
|
212
|
+
Global BYOT agent:
|
|
213
|
+
|
|
214
|
+
aw agents add support \
|
|
215
|
+
--global \
|
|
216
|
+
--namespace example.com \
|
|
217
|
+
--team circle \
|
|
218
|
+
--identity-prefix juan
|
|
219
|
+
|
|
220
|
+
## Scenario: remove a responsibility
|
|
221
|
+
|
|
222
|
+
Remove the shared blueprint entry:
|
|
223
|
+
|
|
224
|
+
aw agents remove support --remove-layout
|
|
225
|
+
|
|
226
|
+
Remove this human's local ignored state:
|
|
227
|
+
|
|
228
|
+
aw agents remove support --deprovision-local
|
|
229
|
+
|
|
230
|
+
Delete a global address when you have the required namespace authority:
|
|
231
|
+
|
|
232
|
+
aw agents remove support --delete-global-address
|
|
233
|
+
|
|
234
|
+
`--remove-layout` is not a team-wide revocation. Other humans' local
|
|
235
|
+
`.aw/` state and certificates continue until they deprovision or the
|
|
236
|
+
certs expire/revoke separately.
|
|
237
|
+
|
|
238
|
+
`--deprovision-local` uses local team-controller authority for self-custodial
|
|
239
|
+
teams. Hosted-managed cert-only agents may self-deprovision through the hosted
|
|
240
|
+
service using their own signing key and active team certificate. That hosted
|
|
241
|
+
path applies only to the same agent and must not be described as dashboard
|
|
242
|
+
authority over BYOT members.
|
|
133
243
|
|
|
134
|
-
|
|
244
|
+
`--delete-global-address` is opt-in. Self-custodial namespaces require the
|
|
245
|
+
local namespace controller key. Hosted-managed global agents can delete only
|
|
246
|
+
hosted-managed addresses through hosted self-deprovision; unmanaged/BYOT
|
|
247
|
+
addresses remain customer-controller-owned.
|
|
135
248
|
|
|
136
|
-
|
|
249
|
+
Hosted self-deprovision errors are actionable:
|
|
250
|
+
|
|
251
|
+
- `hosted_team_controller_required`: use/restore the self-custodial team
|
|
252
|
+
controller key; this is not a hosted-managed team.
|
|
253
|
+
- `global_address_not_hosted_managed`: delete the address with the customer
|
|
254
|
+
namespace controller; the hosted service must not delete BYOT/unmanaged
|
|
255
|
+
addresses.
|
|
256
|
+
- `delete_global_address_required`: rerun with `--delete-global-address` for a
|
|
257
|
+
hosted-managed global agent.
|
|
258
|
+
- `local_identity_has_no_global_address`: rerun without
|
|
259
|
+
`--delete-global-address`; local identities do not have global addresses.
|
|
260
|
+
|
|
261
|
+
## Legacy mode: old out-of-repo bootstrap
|
|
262
|
+
|
|
263
|
+
Use legacy mode only for existing scripts/templates that still expect
|
|
264
|
+
the old layout.
|
|
265
|
+
|
|
266
|
+
- `--work-directory <path>` selects legacy work-directory mode.
|
|
267
|
+
- `--work-repo-url <url-or-local-path>` selects legacy
|
|
268
|
+
clone-then-bootstrap mode.
|
|
269
|
+
- The two flags are XOR.
|
|
270
|
+
- Do not combine `--agents-dir` with either legacy work flag.
|
|
271
|
+
|
|
272
|
+
## Worktree-bound agents
|
|
273
|
+
|
|
274
|
+
Use `work: git_worktree` when multiple agents will edit code in
|
|
275
|
+
parallel.
|
|
137
276
|
|
|
138
277
|
Requirements:
|
|
139
278
|
|
|
140
|
-
- The
|
|
141
|
-
- The template
|
|
279
|
+
- The project directory must be a git repo.
|
|
280
|
+
- The template declares `work: git_worktree` for the relevant agent in
|
|
281
|
+
`team.yaml`.
|
|
142
282
|
|
|
143
|
-
What bootstrap does:
|
|
283
|
+
What bootstrap/add-worktree does:
|
|
144
284
|
|
|
145
|
-
- It creates
|
|
146
|
-
|
|
147
|
-
-
|
|
285
|
+
- It creates `agents/worktrees/` and writes scoped `.gitignore`
|
|
286
|
+
entries.
|
|
287
|
+
- It creates one git worktree per `work: git_worktree` agent.
|
|
288
|
+
- The live agent home remains under `agents/home/<responsibility>/`.
|
|
289
|
+
- Each worktree-bound agent gets its own `.aw/` state and local-scope
|
|
290
|
+
identity.
|
|
148
291
|
|
|
149
292
|
Common pitfall:
|
|
150
293
|
|
|
151
|
-
- Alias collisions:
|
|
294
|
+
- Alias collisions: in shared repos use `--identity-prefix` and a
|
|
295
|
+
template local alias pattern such as `{user}-{classic-name}`.
|
|
152
296
|
|
|
153
|
-
## Quick validation after bootstrap
|
|
297
|
+
## Quick validation after bootstrap/provision
|
|
154
298
|
|
|
155
|
-
In each generated agent directory (agents/<responsibility
|
|
299
|
+
In each generated agent directory (`agents/home/<responsibility>/`):
|
|
156
300
|
|
|
157
301
|
- aw workspace status
|
|
158
302
|
- aw whoami
|
|
159
303
|
|
|
160
304
|
If you are using a wake-up integration:
|
|
161
305
|
|
|
162
|
-
- start the Pi extension or the Claude Code channel plugin in that
|
|
306
|
+
- start the Pi extension or the Claude Code channel plugin in that
|
|
307
|
+
directory after initialization
|
|
163
308
|
|
|
164
309
|
## Troubleshooting patterns
|
|
165
310
|
|
|
166
311
|
If bootstrap fails:
|
|
167
312
|
|
|
168
313
|
- Stop and capture the first error.
|
|
169
|
-
-
|
|
170
|
-
-
|
|
314
|
+
- Do not retry over an existing `agents/` directory.
|
|
315
|
+
- Inspect/back up `.aw/` state before deleting generated directories.
|
|
316
|
+
- Prefer `aw agents provision`, `aw agents add`, or
|
|
317
|
+
`aw agents remove` recovery commands over hand-editing identity
|
|
318
|
+
state.
|
|
319
|
+
|
|
320
|
+
If a multi-human provision hits a conflict:
|
|
321
|
+
|
|
322
|
+
- Rerun with a different `--identity-prefix` or naming pattern.
|
|
323
|
+
- Invite-only flows may discover existing aliases only at mutation
|
|
324
|
+
time; this is expected fail-closed behavior.
|
|
171
325
|
|
|
172
|
-
If you see identity_mismatch or unverified messages in live channel
|
|
326
|
+
If you see identity_mismatch or unverified messages in live channel
|
|
327
|
+
metadata:
|
|
173
328
|
|
|
174
329
|
- Compare with aw chat history output.
|
|
175
330
|
- Confirm the channel plugin / Pi package version is current.
|
|
@@ -67,7 +67,7 @@ The normative E2E contract is `docs/e2e-messaging-contract.md`. Do not invent pr
|
|
|
67
67
|
|
|
68
68
|
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.
|
|
69
69
|
|
|
70
|
-
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
|
|
70
|
+
An identity must publish an identity-signed encryption-key assertion before it can receive E2E messages. New self-custodial identity and team-install paths create local encryption key material automatically, including `aw id create`, `aw init`, `aw service init`, `aw id team accept-invite`, `aw id team fetch-cert`, and bootstrap/add-worktree flows. Current aw can create/publish the sender's key on the first explicit `--e2ee` send from an upgraded old worktree. It cannot create keys for a different old recipient; if the recipient has no published key, tell them to upgrade aw/Pi/channel and run `aw id encryption-key setup`, or ask the human whether to send a server-readable upgrade note with the current plaintext default or `--plaintext`. Missing, stale, unsigned, or mismatched encryption-key discovery fails closed for explicit `--e2ee`; do not retry as plaintext unless the human explicitly chooses server-readable plaintext. 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.
|
|
71
71
|
|
|
72
72
|
Use the CLI keyring commands for self-custodial E2E readiness:
|
|
73
73
|
|
|
@@ -79,7 +79,7 @@ aw id encryption-key show # inspect local keyring state
|
|
|
79
79
|
|
|
80
80
|
`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/`.
|
|
81
81
|
|
|
82
|
-
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
|
|
82
|
+
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 use the end-to-end label for hosted custodial/server-side messaging unless a future design keeps plaintext and decryption fully outside AC.
|
|
83
83
|
|
|
84
84
|
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.
|
|
85
85
|
|
|
@@ -161,7 +161,7 @@ Interpret failures by what's missing (file references assume a self-custodial CL
|
|
|
161
161
|
|
|
162
162
|
- **No `.aw/` in this directory** — there is no workspace here at all. Run `aw init` or move to a directory that has been initialized.
|
|
163
163
|
- **`.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.
|
|
164
|
-
- **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.
|
|
164
|
+
- **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. Use `--plaintext` only when the human explicitly chooses server-readable plaintext.
|
|
165
165
|
- **`.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`.
|
|
166
166
|
- **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.
|
|
167
167
|
- **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:
|
|
@@ -10,9 +10,11 @@ This skill is the playbook for aweb channel awakenings. When you receive an inje
|
|
|
10
10
|
|
|
11
11
|
It also covers explicit user requests to send mail or chat through aweb.
|
|
12
12
|
|
|
13
|
-
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
|
|
13
|
+
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 use the end-to-end label for hosted custodial/server-side messaging.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Interim plaintext boundary: in the current aw CLI release, mail and chat are server-readable plaintext by default. Do not describe default CLI mail/chat as E2E. Pass `--e2ee` only when the human explicitly wants encrypted send; if that encrypted send fails because keys, capability, route support, or version support is missing/stale/mismatched, stop and report the exact failure. Do not silently retry as plaintext.
|
|
16
|
+
|
|
17
|
+
Mixed-version boundary: old pre-E2E aw/channel/Pi clients may not have published recipient encryption keys yet. A current aw CLI can create/publish the sender's local encryption key for explicit `--e2ee` sends, but it cannot create keys for another recipient. If the recipient lacks a key, report that they need to upgrade aw/Pi/channel and publish a key. Plain default sends and `--plaintext` are server-readable.
|
|
16
18
|
|
|
17
19
|
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`.
|
|
18
20
|
|
|
@@ -77,15 +79,15 @@ aw chat extend-wait <from> "working on it, 2 minutes"
|
|
|
77
79
|
|
|
78
80
|
Before replying to a confusing chat, inspect pending/open/history state. Do not use chat for broad FYI updates. Send mail instead.
|
|
79
81
|
|
|
80
|
-
|
|
82
|
+
Mail and chat are server-readable plaintext by default in the current aw CLI release. Add `--e2ee` only when the human explicitly wants an encrypted send; it fails closed if keys, capability, route support, or version support are missing. `--plaintext` is an explicit clarifier for the current default.
|
|
81
83
|
|
|
82
84
|
```bash
|
|
83
|
-
aw chat send-and-wait <alias-or-address> "..." --start-conversation
|
|
84
|
-
aw chat send-and-leave <alias-or-address> "..."
|
|
85
|
-
aw chat extend-wait <from> "working on it"
|
|
85
|
+
aw chat send-and-wait <alias-or-address> "..." --start-conversation
|
|
86
|
+
aw chat send-and-leave <alias-or-address> "..."
|
|
87
|
+
aw chat extend-wait <from> "working on it"
|
|
86
88
|
```
|
|
87
89
|
|
|
88
|
-
|
|
90
|
+
Encrypted read paths such as `aw chat pending`, `aw chat history`, and channel listen/decrypt paths show plaintext only after local decryption. If an explicit `--e2ee` send 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 server-readable plaintext.
|
|
89
91
|
|
|
90
92
|
## Harness surfaces
|
|
91
93
|
|
|
@@ -109,7 +111,7 @@ Harness support differs:
|
|
|
109
111
|
|
|
110
112
|
The channel is inbound only. Use `aw mail` or `aw chat` to respond.
|
|
111
113
|
|
|
112
|
-
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.
|
|
114
|
+
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. If the local channel/Pi process was upgraded from a pre-E2E version, run `aw id encryption-key setup` in the workspace before expecting it to receive encrypted messages.
|
|
113
115
|
|
|
114
116
|
## Control and work awakenings
|
|
115
117
|
|
|
@@ -84,7 +84,7 @@ aw init # if the joining directory still needs server binding
|
|
|
84
84
|
|
|
85
85
|
No token round-trip. Direct controller-mint. Available only for hosted teams because BYOT controller keys aren't held by aweb.
|
|
86
86
|
|
|
87
|
-
**Path 3 — CLI invite-token, for hosted
|
|
87
|
+
**Path 3 — CLI invite-token, for hosted self-custodial local or global identities.** Hosted CLI invite tokens are redeemed through the cloud, but the accepting directory keeps its own signing key. Use the default form when the owner wants to invite a new local-workspace identity by token:
|
|
88
88
|
|
|
89
89
|
```bash
|
|
90
90
|
# Owner side (in a workspace with the necessary authority):
|
|
@@ -97,7 +97,14 @@ aw id team accept-invite <token> --alias <alias>
|
|
|
97
97
|
aw init # finish wiring the new workspace
|
|
98
98
|
```
|
|
99
99
|
|
|
100
|
-
`accept-invite` refuses to overwrite an existing `.aw/` identity and generates a fresh local self-custodial identity in the target directory before requesting the certificate. For
|
|
100
|
+
`accept-invite` refuses to overwrite an existing `.aw/` identity and generates a fresh local self-custodial identity in the target directory before requesting the certificate. For a hosted global identity, accept the hosted token with `--address <domain>/<name>`:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
aw id team accept-invite <token> --address <domain>/<name>
|
|
104
|
+
aw init # finish wiring the new workspace
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
In the hosted `--address` case, the CLI creates a fresh self-custodial global identity for the address, registers it through the hosted service, and installs the hosted team certificate. The hosted service signs the team certificate; it does not receive the accepting directory's private signing key. If the user already has a global identity and only needs a certificate for an existing hosted team, Path 2 (dashboard Add existing identity + `fetch-cert`) remains valid.
|
|
101
108
|
|
|
102
109
|
This is **not** the cross-machine BYOT path. Do not present it as the normal way to join a BYOT team from another machine.
|
|
103
110
|
|
|
@@ -161,7 +168,7 @@ This is the local-controller convenience case only. For cross-machine BYOT joins
|
|
|
161
168
|
|
|
162
169
|
Two distinct local actions install a membership:
|
|
163
170
|
|
|
164
|
-
- **`aw id team accept-invite <token>`** — redeems a CLI invite token. For hosted
|
|
171
|
+
- **`aw id team accept-invite <token>`** — redeems a CLI invite token. For hosted invites (Path 3), generates a fresh self-custodial identity in the current directory (refusing to overwrite) and installs the certificate; default is local, while `--address <domain>/<name>` creates/registers a fresh global identity through the hosted service before certificate install. For local-controller same-machine invites (BYOT Case 3), local-member behaves the same way as hosted local; global accepts require an existing global identity (from `aw id create`) and attach a team certificate to it via `--address <namespace>/<name>`.
|
|
165
172
|
- **`aw id team fetch-cert --namespace <namespace> --team <team> --cert-id <id>`** — installs a certificate that has already been minted server-side (by hosted "Add existing identity") or signed by a controller (BYOT `add-member`). Used for hosted Path 2 and BYOT Case 1.
|
|
166
173
|
|
|
167
174
|
If you have a token, use `accept-invite`. If you have a `cert-id` printed by the dashboard or controller, use `fetch-cert`.
|