@awebai/claude-skills 0.2.11 → 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/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,136 +1,207 @@
|
|
|
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
|
-
|
|
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`.
|
|
29
39
|
|
|
30
40
|
2) Generated project-local agents directory — where humans start agents.
|
|
31
41
|
|
|
32
42
|
- By default, run bootstrap from the root of the work repo.
|
|
33
|
-
- Bootstrap creates `agents/` in that repo. Every live agent home is
|
|
43
|
+
- Bootstrap creates `agents/` in that repo. Every live agent home is
|
|
44
|
+
under `agents/home/<responsibility>/`.
|
|
34
45
|
- The coordinator/global-style home normally has `work -> <repo-root>`.
|
|
35
|
-
- Worktree-bound homes still live under
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
|
|
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.
|
|
52
|
+
|
|
53
|
+
3) Team source — the authority/context the generated agents join.
|
|
54
|
+
|
|
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.
|
|
48
72
|
|
|
49
73
|
5) Generated workspaces — the identities that will act.
|
|
50
74
|
|
|
51
|
-
- Each `agents/home/<responsibility>/` directory becomes an aw
|
|
52
|
-
|
|
53
|
-
-
|
|
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.
|
|
54
82
|
|
|
55
83
|
Aweb team source terms:
|
|
56
84
|
|
|
57
85
|
- Hosted new team: aweb.ai creates/hosts the team.
|
|
58
|
-
- 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.
|
|
59
88
|
- Invite token: first generated workspace accepts an existing invite.
|
|
60
|
-
- Current workspace forwarding: caller cwd already has `.aw`;
|
|
61
|
-
|
|
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.
|
|
62
94
|
|
|
63
|
-
## Bootstrap vs
|
|
95
|
+
## Bootstrap vs provision vs add
|
|
64
96
|
|
|
65
|
-
|
|
97
|
+
Use `aw agents bootstrap` when:
|
|
66
98
|
|
|
99
|
+
- You are creating the committed `agents/` layout for a repo.
|
|
67
100
|
- You are creating a brand-new team from a template.
|
|
68
|
-
- You are extending an existing team with a template-defined set of
|
|
69
|
-
|
|
70
|
-
- You want a “one command resolves the team source + installs roles + provisions agent dirs” flow.
|
|
101
|
+
- You are extending an existing team with a template-defined set of
|
|
102
|
+
agent homes, roles, and instructions.
|
|
71
103
|
|
|
72
|
-
|
|
104
|
+
Use `aw agents provision` when:
|
|
73
105
|
|
|
74
|
-
- The
|
|
75
|
-
-
|
|
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.
|
|
76
111
|
|
|
77
|
-
|
|
112
|
+
Use `aw agents add` or `aw agents add-worktree` when:
|
|
78
113
|
|
|
79
|
-
|
|
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`).
|
|
80
117
|
|
|
81
|
-
|
|
82
|
-
|
|
118
|
+
Do NOT bootstrap when:
|
|
119
|
+
|
|
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.
|
|
83
125
|
|
|
84
|
-
|
|
85
|
-
Use when you want the smallest meaningful team: implementation + review.
|
|
126
|
+
## Pick a template
|
|
86
127
|
|
|
87
|
-
|
|
88
|
-
|
|
128
|
+
Canonical templates:
|
|
129
|
+
|
|
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.
|
|
89
136
|
|
|
90
137
|
Fork/edit vs use-as-is:
|
|
91
138
|
|
|
92
139
|
- Use as-is to learn the flow or to run a standard team.
|
|
93
|
-
- Clone or fork when you want to customize roles, responsibilities, or
|
|
94
|
-
|
|
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.
|
|
95
145
|
|
|
96
146
|
## Customizing a template before applying it
|
|
97
147
|
|
|
98
|
-
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.
|
|
99
152
|
|
|
100
153
|
Typical safe flow:
|
|
101
154
|
|
|
102
155
|
```bash
|
|
103
|
-
git clone https://github.com/awebai/aweb-team-
|
|
156
|
+
git clone https://github.com/awebai/aweb-team-coord-worktrees.git my-team-template
|
|
104
157
|
cd my-team-template
|
|
105
158
|
# edit team.yaml, roles/*.md, docs/team.md, home/<responsibility>/AGENTS.md
|
|
106
159
|
cd /path/to/project-repo
|
|
107
|
-
aw
|
|
108
|
-
aw
|
|
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
|
|
109
162
|
```
|
|
110
163
|
|
|
111
164
|
What to edit:
|
|
112
165
|
|
|
113
|
-
- `team.yaml` roles: add/remove role names and point each to a role
|
|
114
|
-
|
|
115
|
-
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- `
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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.
|
|
126
192
|
|
|
127
193
|
- Bootstrap creates `agents/` there.
|
|
128
|
-
- If `agents/` exists, stop. Do not ask bootstrap to adopt, merge, or
|
|
129
|
-
|
|
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>`.
|
|
130
198
|
|
|
131
|
-
2) Decide the team source. This affects whether bootstrap creates a
|
|
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.
|
|
132
202
|
|
|
133
|
-
3)
|
|
203
|
+
3) Decide the identity prefix. Shared repos should always pass
|
|
204
|
+
`--identity-prefix <human-slug>` explicitly.
|
|
134
205
|
|
|
135
206
|
## Default layout: project-local agents/
|
|
136
207
|
|
|
@@ -138,7 +209,9 @@ New bootstrap runs should normally use the default layout:
|
|
|
138
209
|
|
|
139
210
|
```bash
|
|
140
211
|
cd /path/to/project-repo
|
|
141
|
-
aw
|
|
212
|
+
aw agents bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git \
|
|
213
|
+
--username alice \
|
|
214
|
+
--identity-prefix juan
|
|
142
215
|
```
|
|
143
216
|
|
|
144
217
|
Expected generated shape:
|
|
@@ -156,158 +229,220 @@ agents/
|
|
|
156
229
|
developer/
|
|
157
230
|
.aw/
|
|
158
231
|
AGENTS.md
|
|
159
|
-
work -> ../../worktrees/
|
|
232
|
+
work -> ../../worktrees/developer
|
|
160
233
|
reviewer/
|
|
161
234
|
.aw/
|
|
162
235
|
AGENTS.md
|
|
163
|
-
work -> ../../worktrees/
|
|
236
|
+
work -> ../../worktrees/reviewer
|
|
164
237
|
worktrees/
|
|
165
|
-
|
|
166
|
-
|
|
238
|
+
developer/
|
|
239
|
+
reviewer/
|
|
167
240
|
```
|
|
168
241
|
|
|
169
|
-
The repo root itself is not an aw workspace. Start Codex, Claude Code,
|
|
242
|
+
The repo root itself is not an aw workspace. Start Codex, Claude Code,
|
|
243
|
+
or Pi from an agent home:
|
|
170
244
|
|
|
171
245
|
```bash
|
|
172
246
|
cd agents/home/coordinator
|
|
173
247
|
codex
|
|
174
248
|
```
|
|
175
249
|
|
|
176
|
-
Bootstrap writes scoped `.gitignore` entries for
|
|
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.
|
|
177
253
|
|
|
178
|
-
|
|
254
|
+
If an older generated repo tracked `agents/home/*/work`, remove those
|
|
255
|
+
symlinks from git after upgrading:
|
|
179
256
|
|
|
180
|
-
|
|
257
|
+
```bash
|
|
258
|
+
git rm --cached agents/home/*/work
|
|
259
|
+
git add .gitignore agents
|
|
260
|
+
git commit -m "agents: ignore generated work symlinks"
|
|
261
|
+
```
|
|
181
262
|
|
|
182
|
-
|
|
183
|
-
|
|
263
|
+
## Multi-human shared repo flow
|
|
264
|
+
|
|
265
|
+
First human:
|
|
266
|
+
|
|
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
|
+
```
|
|
184
275
|
|
|
185
|
-
|
|
276
|
+
Second human:
|
|
277
|
+
|
|
278
|
+
```bash
|
|
279
|
+
git pull
|
|
280
|
+
aw agents provision --invite-token <token> --identity-prefix maria
|
|
281
|
+
cd agents/home/coordinator
|
|
282
|
+
codex
|
|
283
|
+
```
|
|
284
|
+
|
|
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.
|
|
186
288
|
|
|
187
289
|
## Team source policy
|
|
188
290
|
|
|
189
|
-
Non-dry-run bootstrap needs one coherent team source.
|
|
291
|
+
Non-dry-run bootstrap needs one coherent team source.
|
|
190
292
|
|
|
191
293
|
Resolution order:
|
|
192
294
|
|
|
193
|
-
- If any explicit source is set (`AWEB_API_KEY`, `--invite-token`,
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
- If no source
|
|
197
|
-
|
|
198
|
-
|
|
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.
|
|
199
305
|
|
|
200
306
|
Supported sources:
|
|
201
307
|
|
|
202
|
-
1) Hosted new team
|
|
308
|
+
1) Hosted new team
|
|
203
309
|
|
|
204
310
|
- Best for first-time teams.
|
|
205
311
|
- Use `--username <name>` or run interactively in a TTY.
|
|
206
|
-
- 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.
|
|
207
314
|
|
|
208
315
|
2) Existing hosted team via API key
|
|
209
316
|
|
|
210
317
|
- If `AWEB_API_KEY` is set, bootstrap joins the API key's hosted team.
|
|
211
|
-
- `--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.
|
|
212
320
|
- Do not also pass `--username`, `--invite-token`, or BYOT flags.
|
|
213
321
|
|
|
214
322
|
3) Existing team via invite token
|
|
215
323
|
|
|
216
324
|
- Pass `--invite-token <token>`.
|
|
217
|
-
- 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.
|
|
218
327
|
|
|
219
328
|
4) Current workspace forwarding
|
|
220
329
|
|
|
221
|
-
- If
|
|
222
|
-
|
|
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.
|
|
223
333
|
|
|
224
|
-
5) BYOT
|
|
334
|
+
5) BYOT
|
|
225
335
|
|
|
226
|
-
- Use `--namespace <domain> --team <slug>` when the team's namespace/
|
|
227
|
-
|
|
228
|
-
- 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.
|
|
229
340
|
|
|
230
341
|
Decision recipe:
|
|
231
342
|
|
|
232
|
-
- Human says
|
|
233
|
-
|
|
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>`.
|
|
234
348
|
- Human pasted an invite: use `--invite-token`.
|
|
235
|
-
- Human is already inside the team workspace that should own the new
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
- Prefer hosted for “get a working team now”.
|
|
241
|
-
- Prefer API key or invite when the team already exists but the caller is not already inside it.
|
|
242
|
-
- Prefer current workspace forwarding when you are already inside the target team.
|
|
243
|
-
- Prefer BYOT when you need local control over the team namespace/domain and routing.
|
|
244
|
-
- 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.
|
|
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`).
|
|
245
353
|
|
|
246
|
-
##
|
|
354
|
+
## Adding agents later
|
|
247
355
|
|
|
248
|
-
|
|
356
|
+
Add a repo-root local responsibility:
|
|
249
357
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
358
|
+
```bash
|
|
359
|
+
aw agents add support --role support
|
|
360
|
+
```
|
|
253
361
|
|
|
254
|
-
|
|
362
|
+
Add a worktree-bound local responsibility:
|
|
255
363
|
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
364
|
+
```bash
|
|
365
|
+
aw agents add-worktree developer --role developer
|
|
366
|
+
```
|
|
259
367
|
|
|
260
|
-
|
|
368
|
+
Add a global BYOT responsibility:
|
|
261
369
|
|
|
262
|
-
|
|
263
|
-
|
|
370
|
+
```bash
|
|
371
|
+
aw agents add support \
|
|
372
|
+
--global \
|
|
373
|
+
--namespace example.com \
|
|
374
|
+
--team circle \
|
|
375
|
+
--identity-prefix juan
|
|
376
|
+
```
|
|
264
377
|
|
|
265
|
-
|
|
378
|
+
Remove explicitly separates layout and identity effects:
|
|
266
379
|
|
|
267
|
-
|
|
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
|
+
```
|
|
268
385
|
|
|
269
|
-
|
|
386
|
+
`--remove-layout` does not revoke other humans' certs and does not
|
|
387
|
+
delete their ignored `.aw/` state.
|
|
270
388
|
|
|
271
|
-
|
|
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.
|
|
272
393
|
|
|
273
|
-
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
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.
|
|
277
398
|
|
|
278
|
-
-
|
|
399
|
+
Map hosted self-deprovision structured errors to concrete recovery:
|
|
279
400
|
|
|
280
|
-
-
|
|
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.
|
|
281
410
|
|
|
282
|
-
##
|
|
411
|
+
## Legacy mode
|
|
283
412
|
|
|
284
|
-
|
|
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.
|
|
285
416
|
|
|
286
|
-
|
|
287
|
-
- Use `--refresh-template` only when you intend to re-clone over a previous template checkout.
|
|
288
|
-
- Treat identity/certificate state under .aw/ as the source of truth; do not delete it casually.
|
|
289
|
-
- If you need to create a fresh workspace, do it in a new directory rather than mutating an existing identity in place.
|
|
290
|
-
- If `agents/` already exists, do not retry over it. Pick a different `--agents-dir` or remove the existing directory only if the human confirms it is disposable.
|
|
417
|
+
## After bootstrap: validate that the team is usable
|
|
291
418
|
|
|
292
|
-
|
|
419
|
+
For each agent directory under `agents/home/<responsibility>/`:
|
|
293
420
|
|
|
294
|
-
-
|
|
295
|
-
|
|
296
|
-
-
|
|
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.
|
|
297
426
|
|
|
298
|
-
##
|
|
427
|
+
## Troubleshooting policy
|
|
299
428
|
|
|
300
|
-
|
|
429
|
+
If bootstrap fails:
|
|
301
430
|
|
|
302
|
-
-
|
|
303
|
-
-
|
|
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.
|
|
304
436
|
|
|
305
|
-
|
|
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.
|
|
306
441
|
|
|
307
442
|
## References
|
|
308
443
|
|
|
309
444
|
Read these only when deeper context is needed:
|
|
310
445
|
|
|
311
|
-
- references/bootstrap-scenarios.md: scenarios, checklists, and
|
|
312
|
-
|
|
446
|
+
- references/bootstrap-scenarios.md: scenarios, checklists, and
|
|
447
|
+
troubleshooting.
|
|
313
448
|
- docs/team-bootstrap.md (aweb repo checkout): full reference guide.
|
|
@@ -1,89 +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 agent home
|
|
10
|
-
|
|
11
|
-
-
|
|
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`).
|
|
12
19
|
- Team source = the authority the generated agents join.
|
|
13
|
-
-
|
|
14
|
-
|
|
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.
|
|
15
28
|
|
|
16
29
|
Team-source precedence:
|
|
17
30
|
|
|
18
|
-
- Explicit sources conflict: use only one of `AWEB_API_KEY`,
|
|
19
|
-
-
|
|
20
|
-
- With no explicit source
|
|
21
|
-
|
|
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.
|
|
22
39
|
|
|
23
|
-
## Scenario: first-time hosted team from a template
|
|
40
|
+
## Scenario: first-time hosted team from a template
|
|
24
41
|
|
|
25
|
-
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.
|
|
26
44
|
|
|
27
45
|
Checklist:
|
|
28
46
|
|
|
29
47
|
- Run from the root of the project git repo.
|
|
30
|
-
- Confirm the target agents directory does not already exist. Default:
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
- awebai/aweb-team-company-surfaces for a 6-agent cross-functional setup.
|
|
48
|
+
- Confirm the target agents directory does not already exist. Default:
|
|
49
|
+
`agents/`.
|
|
50
|
+
- Pick a template.
|
|
51
|
+
- Pick a human-specific `--identity-prefix`.
|
|
35
52
|
|
|
36
53
|
Example:
|
|
37
54
|
|
|
38
55
|
cd /path/to/project-repo
|
|
39
|
-
aw
|
|
56
|
+
aw agents bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git \
|
|
57
|
+
--username alice \
|
|
58
|
+
--identity-prefix juan
|
|
40
59
|
|
|
41
60
|
Example with a non-default agents directory:
|
|
42
61
|
|
|
43
62
|
cd /path/to/project-repo
|
|
44
|
-
aw
|
|
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
|
|
45
67
|
|
|
46
68
|
Notes:
|
|
47
69
|
|
|
48
|
-
- Bootstrap creates `agents/home/<
|
|
49
|
-
|
|
50
|
-
-
|
|
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
|
|
95
|
+
|
|
96
|
+
Expected behavior:
|
|
97
|
+
|
|
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/`.
|
|
51
103
|
|
|
52
104
|
## Scenario: customize the template before applying it
|
|
53
105
|
|
|
54
|
-
Goal: change roles, agent responsibilities,
|
|
106
|
+
Goal: change roles, agent responsibilities, naming policy, or
|
|
107
|
+
instructions before any team state is created.
|
|
55
108
|
|
|
56
109
|
Checklist:
|
|
57
110
|
|
|
58
111
|
- Clone or fork the template first.
|
|
59
|
-
- Edit `team.yaml`, `roles/*.md`, `docs/team.md`, and
|
|
60
|
-
|
|
61
|
-
-
|
|
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.
|
|
62
118
|
|
|
63
119
|
Example:
|
|
64
120
|
|
|
65
|
-
git clone https://github.com/awebai/aweb-team-
|
|
121
|
+
git clone https://github.com/awebai/aweb-team-coord-worktrees.git my-team-template
|
|
66
122
|
cd my-team-template
|
|
67
123
|
# edit team.yaml / roles / docs / home
|
|
68
124
|
cd /path/to/project-repo
|
|
69
|
-
aw
|
|
70
|
-
aw
|
|
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
|
|
71
127
|
|
|
72
|
-
## Scenario: BYOT
|
|
128
|
+
## Scenario: BYOT
|
|
73
129
|
|
|
74
130
|
Goal: bootstrap a team under a namespace/domain you control.
|
|
75
131
|
|
|
76
132
|
Checklist:
|
|
77
133
|
|
|
78
|
-
- Confirm
|
|
79
|
-
|
|
80
|
-
-
|
|
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.
|
|
81
140
|
|
|
82
|
-
Example shape
|
|
141
|
+
Example shape:
|
|
83
142
|
|
|
84
|
-
aw
|
|
143
|
+
aw agents bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git \
|
|
85
144
|
--namespace example.com \
|
|
86
|
-
--team dev
|
|
145
|
+
--team dev \
|
|
146
|
+
--identity-prefix juan
|
|
87
147
|
|
|
88
148
|
If you are also self-hosting the coordination stack, add:
|
|
89
149
|
|
|
@@ -92,76 +152,149 @@ If you are also self-hosting the coordination stack, add:
|
|
|
92
152
|
|
|
93
153
|
## Scenario: existing hosted team via API key
|
|
94
154
|
|
|
95
|
-
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.
|
|
96
157
|
|
|
97
158
|
Checklist:
|
|
98
159
|
|
|
99
|
-
- Set AWEB_API_KEY
|
|
100
|
-
- Optionally set AWEB_URL or pass
|
|
101
|
-
-
|
|
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.
|
|
102
164
|
|
|
103
165
|
Example:
|
|
104
166
|
|
|
105
167
|
AWEB_API_KEY=aw_sk_... \
|
|
106
|
-
aw
|
|
168
|
+
aw agents bootstrap /path/to/template --identity-prefix juan
|
|
107
169
|
|
|
108
170
|
## Scenario: existing team via invite token
|
|
109
171
|
|
|
110
|
-
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.
|
|
111
174
|
|
|
112
175
|
Example:
|
|
113
176
|
|
|
114
|
-
aw
|
|
115
|
-
--invite-token <token>
|
|
177
|
+
aw agents bootstrap /path/to/template \
|
|
178
|
+
--invite-token <token> \
|
|
179
|
+
--identity-prefix maria
|
|
116
180
|
|
|
117
181
|
## Scenario: current workspace forwarding
|
|
118
182
|
|
|
119
|
-
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.
|
|
120
185
|
|
|
121
186
|
Checklist:
|
|
122
187
|
|
|
123
188
|
- Confirm `aw workspace status` succeeds in the caller cwd.
|
|
124
189
|
- Do not pass another explicit team source.
|
|
125
|
-
- 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.
|
|
126
192
|
|
|
127
193
|
## Scenario: dry-run planning
|
|
128
194
|
|
|
129
|
-
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.
|
|
130
197
|
|
|
131
198
|
Example:
|
|
132
199
|
|
|
133
|
-
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.
|
|
243
|
+
|
|
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.
|
|
248
|
+
|
|
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.
|
|
134
260
|
|
|
135
261
|
## Legacy mode: old out-of-repo bootstrap
|
|
136
262
|
|
|
137
|
-
Use legacy mode only for existing scripts/templates that still expect
|
|
263
|
+
Use legacy mode only for existing scripts/templates that still expect
|
|
264
|
+
the old layout.
|
|
138
265
|
|
|
139
266
|
- `--work-directory <path>` selects legacy work-directory mode.
|
|
140
|
-
- `--work-repo-url <url-or-local-path>` selects legacy
|
|
267
|
+
- `--work-repo-url <url-or-local-path>` selects legacy
|
|
268
|
+
clone-then-bootstrap mode.
|
|
141
269
|
- The two flags are XOR.
|
|
142
270
|
- Do not combine `--agents-dir` with either legacy work flag.
|
|
143
271
|
|
|
144
|
-
## Worktree-bound agents
|
|
272
|
+
## Worktree-bound agents
|
|
145
273
|
|
|
146
|
-
Use `work: git_worktree` when multiple agents will edit code in
|
|
274
|
+
Use `work: git_worktree` when multiple agents will edit code in
|
|
275
|
+
parallel.
|
|
147
276
|
|
|
148
277
|
Requirements:
|
|
149
278
|
|
|
150
279
|
- The project directory must be a git repo.
|
|
151
|
-
- The template declares `work: git_worktree` for the relevant agent in
|
|
280
|
+
- The template declares `work: git_worktree` for the relevant agent in
|
|
281
|
+
`team.yaml`.
|
|
152
282
|
|
|
153
|
-
What bootstrap does:
|
|
283
|
+
What bootstrap/add-worktree does:
|
|
154
284
|
|
|
155
|
-
- It creates `agents/worktrees/` and writes scoped `.gitignore`
|
|
285
|
+
- It creates `agents/worktrees/` and writes scoped `.gitignore`
|
|
286
|
+
entries.
|
|
156
287
|
- It creates one git worktree per `work: git_worktree` agent.
|
|
157
288
|
- The live agent home remains under `agents/home/<responsibility>/`.
|
|
158
|
-
- Each worktree-bound agent gets its own `.aw/` state and local-scope
|
|
289
|
+
- Each worktree-bound agent gets its own `.aw/` state and local-scope
|
|
290
|
+
identity.
|
|
159
291
|
|
|
160
292
|
Common pitfall:
|
|
161
293
|
|
|
162
|
-
- Alias collisions:
|
|
294
|
+
- Alias collisions: in shared repos use `--identity-prefix` and a
|
|
295
|
+
template local alias pattern such as `{user}-{classic-name}`.
|
|
163
296
|
|
|
164
|
-
## Quick validation after bootstrap
|
|
297
|
+
## Quick validation after bootstrap/provision
|
|
165
298
|
|
|
166
299
|
In each generated agent directory (`agents/home/<responsibility>/`):
|
|
167
300
|
|
|
@@ -170,17 +303,28 @@ In each generated agent directory (`agents/home/<responsibility>/`):
|
|
|
170
303
|
|
|
171
304
|
If you are using a wake-up integration:
|
|
172
305
|
|
|
173
|
-
- 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
|
|
174
308
|
|
|
175
309
|
## Troubleshooting patterns
|
|
176
310
|
|
|
177
311
|
If bootstrap fails:
|
|
178
312
|
|
|
179
313
|
- Stop and capture the first error.
|
|
180
|
-
-
|
|
181
|
-
-
|
|
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.
|
|
182
325
|
|
|
183
|
-
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:
|
|
184
328
|
|
|
185
329
|
- Compare with aw chat history output.
|
|
186
330
|
- Confirm the channel plugin / Pi package version is current.
|
|
@@ -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`.
|