@awebai/oats 0.69.8 → 0.69.9
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/README.md +8 -5
- package/bin/oats.mjs +2 -2
- package/docs/desktop-cli-api.md +7 -2
- package/docs/first-team.md +3 -2
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.9.md +92 -0
- package/docs/upgrading.md +10 -5
- package/docs/workspaces.md +1 -1
- package/lib/status-words.mjs +32 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/needs-input-reporting-gap.mjs +25 -0
- package/skills/oats-getting-started/SKILL.md +367 -242
|
@@ -2,36 +2,40 @@
|
|
|
2
2
|
name: oats-getting-started
|
|
3
3
|
description: >-
|
|
4
4
|
The way into OATS (Open Agent Team Specification) for a person who has only
|
|
5
|
-
a coding agent. Asks about their project, installs OATS
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
5
|
+
a coding agent. Asks about their project, installs OATS, OATS Desktop and
|
|
6
|
+
the messaging CLI, signs the person in to their messaging account and
|
|
7
|
+
creates the workspace's team, writes a new workspace's skeleton (or joins
|
|
8
|
+
this machine to an existing workspace), spawns the workspace's setup
|
|
9
|
+
expert, which does the rest, and opens the Desktop on it. Offers the TUI.
|
|
10
|
+
Use for "get started with OATS", "set up / install / adopt OATS", "set up
|
|
11
|
+
OATS for this project", "join our OATS workspace", or when someone gives
|
|
12
|
+
you this file or its URL.
|
|
11
13
|
---
|
|
12
14
|
|
|
13
15
|
# Getting started with OATS
|
|
14
16
|
|
|
15
17
|
You are the person's own coding agent. This skill takes them from nothing to
|
|
16
18
|
a running **setup expert**: an OATS agent of their workspace that does the
|
|
17
|
-
rest of the setup with them (
|
|
18
|
-
their first agents). You install, ask,
|
|
19
|
-
you are done.
|
|
19
|
+
rest of the setup with them (their repositories, their own coordination,
|
|
20
|
+
knowledge and tasks capabilities, their first agents). You install, ask,
|
|
21
|
+
write a few files and spawn it. Then you are done.
|
|
20
22
|
|
|
21
23
|
OATS in one paragraph: a **workspace** is one Git repository declaring which
|
|
22
24
|
repositories belong to an organisation and which packages it trusts. A
|
|
23
25
|
**soul** is a durable agent role defined in Git; an **instance** is a soul at
|
|
24
|
-
work, in its own home and terminal.
|
|
25
|
-
|
|
26
|
+
work, in its own home and terminal. A new workspace's setup expert is the
|
|
27
|
+
`oats.framework` package's soul `oats-setup-expert`, spawned as the instance
|
|
28
|
+
`<workspace>-oats-setup-expert`. It holds the `oats.setup` and
|
|
29
|
+
`oats.onboarding` capabilities.
|
|
26
30
|
|
|
27
31
|
**A machine found-list.** Your prompt may hand you a found-list, a JSON file
|
|
28
32
|
whose `machine.platform` is set (oats-omarchy's installer writes one). Then
|
|
29
33
|
the workspace you make is this machine's own workspace. Its setup soul is
|
|
30
|
-
the machine's steward, `oats.machine/steward`, in place of
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
34
|
+
the machine's steward, `oats.machine/steward`, in place of the setup expert,
|
|
35
|
+
and the steward gets a global aweb address. Steps 1, 5, 7, 8 and 9 say what
|
|
36
|
+
changes. When the found-list lists a deployment whose `steward` is `true`,
|
|
37
|
+
this machine already has its workspace and steward: tell the person so, and
|
|
38
|
+
stop. Wherever a later step says to ask the
|
|
35
39
|
person, on a machine found-list you tell them what happened, as it is, and
|
|
36
40
|
stop instead: the person answers nothing after step 1.
|
|
37
41
|
|
|
@@ -40,9 +44,9 @@ stop instead: the person answers nothing after step 1.
|
|
|
40
44
|
steps yourself and read back what each did.
|
|
41
45
|
- **Secrets.** The person types only what you must never hold: passwords,
|
|
42
46
|
tokens and logins. Before the spawn there are two ways for that: a browser
|
|
43
|
-
device flow you start (the GitHub login, step 3
|
|
44
|
-
their own terminal (a `sudo` or Homebrew
|
|
45
|
-
which you open for them (below).
|
|
47
|
+
device flow you start (the GitHub login, step 3, and the messaging login,
|
|
48
|
+
step 5), and the exact command in their own terminal (a `sudo` or Homebrew
|
|
49
|
+
password, an aweb invite token), which you open for them (below).
|
|
46
50
|
- Never ask for a secret in the conversation, and never write one to a file.
|
|
47
51
|
- Never suggest Claude Code's `! <command>` for one: its command and output
|
|
48
52
|
enter your context.
|
|
@@ -50,7 +54,7 @@ stop instead: the person answers nothing after step 1.
|
|
|
50
54
|
command in a new shell, in the same starting folder.
|
|
51
55
|
- Run each fenced block below as one command.
|
|
52
56
|
- When a later block needs a value an earlier one found (`V`, `ARCH`, a
|
|
53
|
-
path), write that value in literally.
|
|
57
|
+
path, the team id `T`), write that value in literally.
|
|
54
58
|
- **Sandboxes.** If your harness sandboxes commands, these steps need network
|
|
55
59
|
access and writes in the home folder: ask the person to approve them.
|
|
56
60
|
Starting the Desktop and opening a terminal also run outside the sandbox.
|
|
@@ -75,7 +79,8 @@ stop instead: the person answers nothing after step 1.
|
|
|
75
79
|
Only when no window opens do you give them the command to run themselves.
|
|
76
80
|
- **Touch nothing you were not asked to.** Don't edit an existing
|
|
77
81
|
deployment's files (`oats-local.yaml`, `oats-lock.json`, `agents/`), and
|
|
78
|
-
don't push to a repository the person did not create in step
|
|
82
|
+
don't push to a repository the person did not create in step 6 or name as
|
|
83
|
+
the workspace's host there.
|
|
79
84
|
|
|
80
85
|
## 1. Ask, in one round
|
|
81
86
|
|
|
@@ -91,28 +96,36 @@ On a machine found-list, ask the machine's round below instead of this list.
|
|
|
91
96
|
`git:github.com/acme/acme-oats`. They get it from whoever runs that
|
|
92
97
|
workspace.
|
|
93
98
|
- New: the **workspace name**: lowercase letters and digits, words joined
|
|
94
|
-
by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`.
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
99
|
+
by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`. Refuse
|
|
100
|
+
`agents`: OATS keeps instance homes in a folder of that name.
|
|
101
|
+
- **New workspace: where the workspace lives.** The workspace's files live in
|
|
102
|
+
one repository, its host. Three cases, from their repositories:
|
|
103
|
+
- **One repository (a monorepo):** the host is that repository, and the
|
|
104
|
+
files go at its root. Ask for its GitHub owner and name.
|
|
105
|
+
- **Several repositories:** a dedicated host repository, private, created
|
|
106
|
+
in step 6. Ask for its owner (their user, or an organisation they can
|
|
107
|
+
create repositories in) and name; suggest `<workspace>-oats`.
|
|
108
|
+
- **No repositories yet:** create their first one in step 6; it is the
|
|
109
|
+
host. Ask for its owner and name.
|
|
110
|
+
|
|
111
|
+
Whatever the case, if any repository of theirs is private, the host is
|
|
112
|
+
private: the workspace file names every member, so whoever reads it sees
|
|
113
|
+
the list.
|
|
114
|
+
- **Messaging between agents:** which messaging capability, or none. The
|
|
115
|
+
default, and the one this skill sets up, is aweb (`oats.aweb`):
|
|
116
|
+
recommended, because agents that can mail each other can coordinate. A new
|
|
117
|
+
workspace needs nothing more from them now: they sign in to their aweb
|
|
118
|
+
account, or create one, in their browser in step 5. For another messaging
|
|
119
|
+
capability, leave messaging out here: the setup expert adds it.
|
|
107
120
|
- **The harness for the setup expert:** `claude`, `codex` or `pi`. Default:
|
|
108
121
|
the one you are, if it is one of these.
|
|
109
122
|
- **The deployment directory `D`:** where OATS lives on this machine. Any
|
|
110
123
|
folder but their home folder itself works: ask for it, and suggest none.
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
124
|
+
`oats onboard` adds `D` to this computer's list of deployments
|
|
125
|
+
(`~/.oats/config/deployments.json`, which `oats deployments` reads), so the
|
|
126
|
+
Desktop and the TUI find it wherever it is. Write `D` everywhere below as
|
|
127
|
+
an absolute path, with the home folder spelled out: never `~`, which the
|
|
128
|
+
shell does not expand inside quotes.
|
|
116
129
|
- **OATS Desktop:** installed and started unless they decline. **The TUI**
|
|
117
130
|
(`oats tui`, a terminal client, preview): opened for them or not.
|
|
118
131
|
|
|
@@ -124,12 +137,12 @@ steward takes them up with the person later.
|
|
|
124
137
|
- **The workspace:** a new one, the machine's own. Its name defaults to the
|
|
125
138
|
hostname, lowercased, with every character outside `[a-z0-9-]` turned
|
|
126
139
|
into `-` (`Ada's-Laptop` gives `ada-s-laptop`). Its repository defaults to
|
|
127
|
-
`<github.login>/<workspace>-oats`, private. Or an
|
|
128
|
-
reference.
|
|
140
|
+
`<github.login>/<workspace>-oats`, private, a dedicated host. Or an
|
|
141
|
+
existing workspace's reference.
|
|
129
142
|
- **The namespace `N`:** the part of every agent's address before the `/`,
|
|
130
143
|
which other people's agents use to reach this machine's agents. Default:
|
|
131
|
-
the hostname, normalised as above, so the namespace is the machine's own.
|
|
132
|
-
|
|
144
|
+
the hostname, normalised as above, so the namespace is the machine's own.
|
|
145
|
+
Messaging is aweb, and the root's name `A` is `<workspace>-root`.
|
|
133
146
|
- **The steward's name:** lowercase letters and digits, words joined by
|
|
134
147
|
single `-`. Default: `steward`. It gives `R`, the steward's instance name
|
|
135
148
|
here and the name in its address, `N.aweb.ai/R`. `R` is the chosen name,
|
|
@@ -148,8 +161,9 @@ steward takes them up with the person later.
|
|
|
148
161
|
uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
149
162
|
```
|
|
150
163
|
|
|
151
|
-
- **Versions:** Node 22 or later; Git 2.45 or later
|
|
152
|
-
|
|
164
|
+
- **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
|
|
165
|
+
caches), and older Git works with whole-tree fetches; `gh` 2.49 or later
|
|
166
|
+
(step 4 uses `gh attestation`).
|
|
153
167
|
- **The harness** they chose must be installed and logged in (`claude
|
|
154
168
|
--version`, `codex --version` or `pi --version`).
|
|
155
169
|
- **macOS:** with Homebrew (`brew --version`), `brew install node git tmux gh`.
|
|
@@ -166,14 +180,29 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
|
166
180
|
- **gh:** from GitHub's own apt or rpm repository
|
|
167
181
|
(<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>), because
|
|
168
182
|
distributions ship versions too old for step 4.
|
|
169
|
-
- **Node 22:**
|
|
170
|
-
|
|
183
|
+
- **Node 22:** distributions ship older ones (Debian 13 has 20, Ubuntu
|
|
184
|
+
24.04 has 18). On Debian and Ubuntu, x64 or arm64, from NodeSource:
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
|
|
188
|
+
```
|
|
189
|
+
- **Git 2.45 (recommended):** Debian 13's is new enough. Ubuntu 24.04
|
|
190
|
+
ships 2.43; on Ubuntu, x64 or arm64, from the git-core PPA:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install -y git
|
|
194
|
+
```
|
|
171
195
|
- **Passwords:** a line that needs `sudo` goes to their own terminal,
|
|
172
196
|
unless `sudo -n true` succeeds.
|
|
197
|
+
- **Then check again** with `node --version` and `git --version`. When
|
|
198
|
+
Node is still under 22 (on another distribution, or where that route does
|
|
199
|
+
not apply), stop: tell the person the minimum and the version found, and
|
|
200
|
+
go no further until they have installed it. Git under 2.45 is no stop:
|
|
201
|
+
tell them it works with whole-tree fetches, and go on.
|
|
173
202
|
- **npm's global folder** (`npm prefix -g`) must be writable for step 4's
|
|
174
|
-
|
|
175
|
-
under `/usr`, as NodeSource installs it), either they run
|
|
176
|
-
`sudo` in their own terminal, or set a per-user prefix:
|
|
203
|
+
installs (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node
|
|
204
|
+
under `/usr`, as NodeSource installs it), either they run those installs
|
|
205
|
+
with `sudo` in their own terminal, or set a per-user prefix:
|
|
177
206
|
`npm config set prefix ~/.local`. Then put `~/.local/bin` on PATH: start
|
|
178
207
|
each later command of yours with `export PATH="$HOME/.local/bin:$PATH"`
|
|
179
208
|
(your shell does not reread their profile). Add that line to their shell's
|
|
@@ -188,14 +217,16 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
|
188
217
|
|
|
189
218
|
## 3. Log in to GitHub
|
|
190
219
|
|
|
191
|
-
|
|
192
|
-
|
|
220
|
+
GitHub stays where the flow needs it: the Desktop's download and its
|
|
221
|
+
attestation (step 4), creating and pushing the host repository (step 6), and
|
|
222
|
+
OATS reading the workspace and its repositories with Git (step 8). Check
|
|
223
|
+
first:
|
|
193
224
|
|
|
194
225
|
```bash
|
|
195
226
|
gh auth status
|
|
196
227
|
```
|
|
197
228
|
|
|
198
|
-
If it is logged in, let Git use it (without this, step
|
|
229
|
+
If it is logged in, let Git use it (without this, step 6's push and step 8
|
|
199
230
|
fail with "could not read Username"), then go to step 4:
|
|
200
231
|
|
|
201
232
|
```bash
|
|
@@ -227,10 +258,12 @@ cat "$HOME/.oats-gh-login.txt"
|
|
|
227
258
|
gh auth status && gh auth setup-git && rm -f "$HOME/.oats-gh-login.txt"
|
|
228
259
|
```
|
|
229
260
|
|
|
230
|
-
The token stays in gh's store and never reaches you.
|
|
231
|
-
signing and the DCO sign-off
|
|
261
|
+
The token stays in gh's store and never reaches you. That is all the Git
|
|
262
|
+
setup this needs. An SSH key, commit signing and the DCO sign-off are
|
|
263
|
+
optional: the setup expert's `/oats-git-setup` sets them up when Git access
|
|
264
|
+
is broken or the person wants them, and says plainly what it changes.
|
|
232
265
|
|
|
233
|
-
## 4. Install OATS Desktop,
|
|
266
|
+
## 4. Install OATS Desktop, the CLI and the messaging CLI
|
|
234
267
|
|
|
235
268
|
The Desktop accepts a band of CLI versions around its own, so install it
|
|
236
269
|
first, then the CLI of the same version `V`. Find `V`, and on macOS `ARCH`:
|
|
@@ -307,14 +340,14 @@ Terminal=false
|
|
|
307
340
|
Categories=Development;
|
|
308
341
|
```
|
|
309
342
|
|
|
310
|
-
- **Without FUSE** (step
|
|
343
|
+
- **Without FUSE** (step 10's start fails with a FUSE message; Ubuntu 22.04
|
|
311
344
|
and later ship without `libfuse2`), add ` --appimage-extract-and-run` after
|
|
312
|
-
the AppImage's path in `Exec=` and in step
|
|
345
|
+
the AppImage's path in `Exec=` and in step 10's start. That needs no
|
|
313
346
|
`sudo`; installing `libfuse2` (`libfuse2t64` on Ubuntu 24.04) does.
|
|
314
347
|
- **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
|
|
315
348
|
download, say so and go on.
|
|
316
349
|
|
|
317
|
-
**Don't start the Desktop yet;** step
|
|
350
|
+
**Don't start the Desktop yet;** step 10 starts it on the new deployment.
|
|
318
351
|
|
|
319
352
|
**Then the CLI, and for pi its bridge:**
|
|
320
353
|
|
|
@@ -323,24 +356,150 @@ npm install -g "@awebai/oats@V" && oats version
|
|
|
323
356
|
pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
|
|
324
357
|
```
|
|
325
358
|
|
|
326
|
-
|
|
359
|
+
**A new workspace needs `oats.framework` 1.18.0 or later,** the release
|
|
360
|
+
that ships the setup expert soul. Read the installed CLI's catalog:
|
|
327
361
|
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
362
|
+
```bash
|
|
363
|
+
node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
It prints the two refs, for example `oats-framework/v1.19.0 v1.33.1`. If the
|
|
367
|
+
framework's version (the part after the `/`) is below `1.18.0`, this OATS
|
|
368
|
+
release is older than this skill: stop, and tell the person to wait for the
|
|
369
|
+
next OATS release. Never write a setup soul into the workspace in its place.
|
|
370
|
+
|
|
371
|
+
**With aweb, the messaging CLI `aw`, and the harness's aweb channel.**
|
|
372
|
+
Skip this without messaging. The channel is what wakes an agent when mail
|
|
373
|
+
arrives: Claude
|
|
374
|
+
`claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
|
|
375
|
+
pi `pi install npm:@awebai/pi`; Codex nothing (it is woken another way, which
|
|
376
|
+
the setup expert sets up).
|
|
377
|
+
|
|
378
|
+
```bash
|
|
379
|
+
npm install -g @awebai/aw && aw version
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
`aw` must be 1.36.33 or later.
|
|
383
|
+
|
|
384
|
+
## 5. Your messaging account and the workspace's team
|
|
385
|
+
|
|
386
|
+
**New workspace with aweb only.** An existing workspace joins in step 9, and
|
|
387
|
+
a machine found-list signs up there too: skip this step for both.
|
|
388
|
+
|
|
389
|
+
The workspace's agents share one team, its **default team**. Here the person
|
|
390
|
+
signs in to their own aweb account, and that account creates the team. Say
|
|
391
|
+
to them, in your words, exactly three things:
|
|
392
|
+
- you are creating a team for the workspace, owned by your aweb account;
|
|
393
|
+
- you sign in as yourself, in your own browser;
|
|
394
|
+
- every agent you spawn joins this default team. More teams are an explicit
|
|
395
|
+
later choice.
|
|
396
|
+
|
|
397
|
+
Don't say that the agents are attributed or bound to them: the team is owned
|
|
398
|
+
by their account, and tying each agent to them is a later step the setup
|
|
399
|
+
expert offers.
|
|
400
|
+
|
|
401
|
+
**The workspace key `K`** is the host repository's key: `github.com/<owner>/<repo>`,
|
|
402
|
+
with the host's owner and name from step 1 (for `acme/acme-oats`,
|
|
403
|
+
`github.com/acme/acme-oats`). It must be exactly this: aweb keys the team on
|
|
404
|
+
that string, and a different spelling makes a different team.
|
|
405
|
+
|
|
406
|
+
**Sign in.** First check whether this machine's `aw` is signed in already:
|
|
407
|
+
|
|
408
|
+
```bash
|
|
409
|
+
aw auth status --json
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
If it prints `"status": "authorized"` with an `account`, go on to the team.
|
|
413
|
+
Otherwise start the login yourself, detached, as with GitHub. aw prints a URL
|
|
414
|
+
and a one-time code, and waits:
|
|
334
415
|
|
|
335
416
|
```bash
|
|
336
|
-
|
|
417
|
+
nohup aw auth login </dev/null >"$HOME/.oats-aw-login.txt" 2>&1 &
|
|
337
418
|
```
|
|
338
419
|
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
420
|
+
A few seconds later, in a separate command:
|
|
421
|
+
|
|
422
|
+
```bash
|
|
423
|
+
cat "$HOME/.oats-aw-login.txt"
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
Open the URL in their browser and give them the code. They sign in, or
|
|
427
|
+
create their aweb account there, and approve. The code is not a secret, and
|
|
428
|
+
the login's token stays in aw's store and never reaches you. Once they say
|
|
429
|
+
they approved:
|
|
430
|
+
|
|
431
|
+
```bash
|
|
432
|
+
aw auth status --json && rm -f "$HOME/.oats-aw-login.txt"
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
`account.id` is the account `ACCOUNT`; `account.handle` is its name, to tell
|
|
436
|
+
the person.
|
|
437
|
+
|
|
438
|
+
**Create the team, with its root in `D/.aw`.** On a first run `D/.aw` must
|
|
439
|
+
not exist yet: if it does and this skill did not make it, stop, and ask the
|
|
440
|
+
person what it is. With `D`, `K`, the workspace name and `ACCOUNT` written in:
|
|
441
|
+
|
|
442
|
+
```bash
|
|
443
|
+
mkdir -p "D" && test ! -e "D/.aw" && cd "D" && aw --identity-home "D/.aw" team ensure --workspace-key "K" --label "<workspace>" --expect-account "ACCOUNT" --json
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
- **Success** prints a JSON answer. Its `canonical_team_id` is the team id
|
|
447
|
+
`T`, of the form `<name>:<domain>`: step 7 writes it into the workspace.
|
|
448
|
+
Never write its `team_id` (an internal id), and never guess `T`.
|
|
449
|
+
- **It installs the team's root** in `D/.aw`: the identity that adds each
|
|
450
|
+
agent the person spawns to the team, with no login at spawn. It holds keys:
|
|
451
|
+
leave it alone.
|
|
452
|
+
- **A failure** prints one line on stderr and exits 2:
|
|
453
|
+
- `authorization-required`: the login is missing or expired. Sign in
|
|
454
|
+
again, then rerun.
|
|
455
|
+
- `identity-home-occupied`: `D/.aw` holds something else. Stop and tell the
|
|
456
|
+
person.
|
|
457
|
+
- `unsupported-server`, or anything else: stop and tell the person what it
|
|
458
|
+
printed.
|
|
459
|
+
- **After an interrupted run** (killed, timed out, or its answer lost),
|
|
460
|
+
`D/.aw` exists, and the first-run line stops at its check. Run the same
|
|
461
|
+
call without that check, with exactly the same `D`, `K`, workspace name and
|
|
462
|
+
`ACCOUNT`: aw continues its own run, or answers `identity-home-occupied`
|
|
463
|
+
for anything else. Never remove or edit `D/.aw`.
|
|
464
|
+
|
|
465
|
+
```bash
|
|
466
|
+
cd "D" && aw --identity-home "D/.aw" team ensure --workspace-key "K" --label "<workspace>" --expect-account "ACCOUNT" --json
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
Tell the person the team exists, owned by their aweb account `<handle>`.
|
|
470
|
+
|
|
471
|
+
## 6. The host repository
|
|
472
|
+
|
|
473
|
+
**New workspace,** by step 1's case. `<repo>` is the host's name.
|
|
474
|
+
- **A dedicated host (several repositories), or the first repository (no
|
|
475
|
+
repositories yet):** create it inside `D`, private unless every repository
|
|
476
|
+
of theirs is public. `D/<repo>` must not exist yet: an existing folder's
|
|
477
|
+
files would end up in the first commit.
|
|
478
|
+
|
|
479
|
+
```bash
|
|
480
|
+
mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
|
|
481
|
+
```
|
|
482
|
+
- **A monorepo:** clone it into `D`, so the setup expert's tools find it
|
|
483
|
+
there. If `D/<repo>` already holds a clone of it, use that clone.
|
|
484
|
+
|
|
485
|
+
```bash
|
|
486
|
+
mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo clone "<owner>/<repo>" "<repo>" && git -C "<repo>" status --short --branch
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
Its root must not hold `oats-workspace.yaml` or `oats-membership.yaml`
|
|
490
|
+
yet: if it does, stop and ask the person.
|
|
491
|
+
|
|
492
|
+
The workspace reference `W` is then `git:github.com/<owner>/<repo>`, here
|
|
493
|
+
`git:github.com/acme/acme-oats`.
|
|
494
|
+
|
|
495
|
+
**Existing workspace.** `W` is the reference they gave. Write nothing in its
|
|
496
|
+
repositories.
|
|
497
|
+
|
|
498
|
+
## 7. The skeleton
|
|
499
|
+
|
|
500
|
+
**New workspace.** Write two files at the root of `D/<repo>`, in one commit.
|
|
501
|
+
They show a workspace named `acme`, hosted in `acme/acme-oats`, with aweb:
|
|
502
|
+
write the person's own workspace name, host and team id in their place.
|
|
344
503
|
|
|
345
504
|
`oats-workspace.yaml`:
|
|
346
505
|
|
|
@@ -348,42 +507,33 @@ their place.
|
|
|
348
507
|
schemaVersion: 2
|
|
349
508
|
name: acme
|
|
350
509
|
members:
|
|
351
|
-
- git:github.com/acme/acme-oats # the host
|
|
510
|
+
- git:github.com/acme/acme-oats # the host; the setup expert adds the others
|
|
352
511
|
packages:
|
|
353
|
-
oats.framework: v1.
|
|
354
|
-
oats.aweb: v1.
|
|
512
|
+
oats.framework: v1.19.0 # the installed CLI's catalog versions (below)
|
|
513
|
+
oats.aweb: v1.33.1 # messaging: agent identities, mail and chat
|
|
355
514
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
356
515
|
defaults:
|
|
357
516
|
capabilities:
|
|
358
517
|
oats.core: { from: package }
|
|
359
518
|
messaging: { oats.aweb: { from: package } }
|
|
360
|
-
tasks: { oats.aweb-tasks: { from: package } } # aweb tasks: assignment, claims, status and handoff
|
|
361
519
|
teams:
|
|
362
|
-
acme: { description: The acme workspace's
|
|
520
|
+
acme: { description: The acme workspace's team, team: "T" }
|
|
363
521
|
defaultTeam: acme # every soul starts in this team
|
|
364
522
|
```
|
|
365
523
|
|
|
366
|
-
- **The versions** are the
|
|
367
|
-
`
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
one.
|
|
524
|
+
- **The versions** are the ones step 4 printed: the framework's (the part
|
|
525
|
+
after `oats-framework/`) and `oats.aweb`'s, but never below `v1.31.0` for
|
|
526
|
+
`oats.aweb`.
|
|
527
|
+
- **The team** is `T` from step 5, written in literally; its label (here
|
|
528
|
+
`acme`) is the workspace name. On a machine found-list, which signs up in
|
|
529
|
+
step 9, it is `default:N.aweb.ai`, with `N` the namespace from step 1.
|
|
373
530
|
- **On a machine found-list only,** keep the `oats.machine` line, at the
|
|
374
|
-
catalog's `packages."oats.machine".ref
|
|
375
|
-
`souls/<workspace>-oats-setup-expert` files below: the steward is the
|
|
376
|
-
workspace's setup soul. Elsewhere, leave the line out.
|
|
377
|
-
- **The team** is `default:N.aweb.ai`, with `N` the username from step 1;
|
|
378
|
-
its label (here `acme`) is the workspace name.
|
|
379
|
-
- **Tasks** use aweb, the same identities as messaging: agents assign,
|
|
380
|
-
claim and hand off work as aweb tasks the person sees on the aweb
|
|
381
|
-
dashboard. A workspace that uses Jira or Linear writes that provider in
|
|
382
|
-
`tasks:` instead (the setup expert sets it up).
|
|
531
|
+
catalog's `packages."oats.machine".ref`. Elsewhere, leave it out.
|
|
383
532
|
- **Without messaging,** leave out the `oats.aweb` line, the `messaging`
|
|
384
|
-
line,
|
|
385
|
-
- **Add nothing else:**
|
|
386
|
-
|
|
533
|
+
line, `teams` and `defaultTeam`.
|
|
534
|
+
- **Add nothing else:** no soul (the setup expert is `oats.framework`'s), no
|
|
535
|
+
`tasks:` default, no knowledge. The setup expert authors the workspace's
|
|
536
|
+
own coordination, knowledge and tasks capabilities with the person.
|
|
387
537
|
|
|
388
538
|
`oats-membership.yaml`:
|
|
389
539
|
|
|
@@ -392,95 +542,27 @@ schemaVersion: 2
|
|
|
392
542
|
workspace: git:github.com/acme/acme-oats
|
|
393
543
|
```
|
|
394
544
|
|
|
395
|
-
`souls/acme-oats-setup-expert/soul.yaml`:
|
|
396
|
-
|
|
397
|
-
```yaml
|
|
398
|
-
schemaVersion: 2
|
|
399
|
-
name: acme-oats-setup-expert
|
|
400
|
-
description: The OATS setup expert for the acme workspace — onboards machines and people, and keeps this workspace's OATS setup working.
|
|
401
|
-
work: worktree # it changes this repository from its own worktree
|
|
402
|
-
capabilities:
|
|
403
|
-
oats.setup: { from: package }
|
|
404
|
-
knowledge: none # so it spawns on a machine before knowledge is set up there
|
|
405
|
-
launch: { harness: claude } # the harness the person chose: claude, codex or pi
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
`souls/acme-oats-setup-expert/AGENTS.md`, and beside it the symlink
|
|
409
|
-
`CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`):
|
|
410
|
-
|
|
411
|
-
```markdown
|
|
412
|
-
# acme-oats-setup-expert
|
|
413
|
-
|
|
414
|
-
You are the OATS setup expert for the acme workspace. You set up and keep
|
|
415
|
-
working this workspace's OATS: its machines, members, souls, packages,
|
|
416
|
-
knowledge, messaging and automations. The `oats.setup` capability is your
|
|
417
|
-
toolkit: its briefing says what the person types and what you run, and its
|
|
418
|
-
skills hold every procedure. Start with `/oats-setup-model`. When your task
|
|
419
|
-
is a hand-over from the getting-started skill, follow `/oats-setup-expert`,
|
|
420
|
-
or `/oats-onboarding` if your `oats.setup` is older than 2.8.0 and lacks it.
|
|
421
|
-
```
|
|
422
|
-
|
|
423
|
-
`souls/acme-developer/soul.yaml`, a first developer for the person's tasks:
|
|
424
|
-
|
|
425
|
-
```yaml
|
|
426
|
-
schemaVersion: 2
|
|
427
|
-
name: acme-developer
|
|
428
|
-
description: A developer in the acme workspace — builds what its task asks.
|
|
429
|
-
work: directory # its own folder; the setup expert points it at the person's repositories later
|
|
430
|
-
knowledge: none
|
|
431
|
-
launch: { harness: claude }
|
|
432
|
-
```
|
|
433
|
-
|
|
434
|
-
`souls/acme-developer/AGENTS.md`, and beside it the symlink
|
|
435
|
-
`CLAUDE.md -> AGENTS.md`:
|
|
436
|
-
|
|
437
|
-
```markdown
|
|
438
|
-
# acme-developer
|
|
439
|
-
|
|
440
|
-
You are a developer in the acme workspace. You build what your task asks,
|
|
441
|
-
in your own `work/` directory: write the code, run it and test it. Keep the
|
|
442
|
-
solution small and simple. When you finish, say what you built, where it is
|
|
443
|
-
and how you checked it. If you are blocked on a decision, ask whoever gave
|
|
444
|
-
you the task.
|
|
445
|
-
```
|
|
446
|
-
|
|
447
|
-
**Keep the soul this thin.** Everything it knows comes from `oats.setup`, so
|
|
448
|
-
it improves when the workspace's `oats.framework` pin moves. It has no
|
|
449
|
-
knowledge of its own, so it can be spawned on a machine before knowledge is
|
|
450
|
-
set up there. It takes the workspace's messaging and doesn't empty that
|
|
451
|
-
slot: a setup soul that empties the messaging slot the workspace fills is
|
|
452
|
-
not the workspace's operator, and gets no mail.
|
|
453
|
-
|
|
454
545
|
**Commit and push.**
|
|
455
|
-
-
|
|
456
|
-
is the person's own, just created.
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
for a member repository only on the person's yes; otherwise it opens a
|
|
462
|
-
pull request. An older `oats.setup` always opens one.
|
|
546
|
+
- **A repository created in step 6:** the first commit goes straight to its
|
|
547
|
+
default branch: it is the person's own, just created.
|
|
548
|
+
- **A monorepo:** show the person the two files first. Commit to its default
|
|
549
|
+
branch only on their yes. If the push is refused (a protected branch, say),
|
|
550
|
+
push a branch instead, open a pull request, tell them, and stop until it is
|
|
551
|
+
merged.
|
|
463
552
|
- If `git config user.email` prints nothing, the person's Git identity is not
|
|
464
553
|
set up yet. After they confirm their name, commit with
|
|
465
554
|
`-c user.name="<their name>" -c user.email="<their noreply address>"`. The
|
|
466
555
|
noreply address comes from
|
|
467
|
-
`gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`.
|
|
468
|
-
setup expert sets up their identity properly later.
|
|
556
|
+
`gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`.
|
|
469
557
|
|
|
470
558
|
```bash
|
|
471
|
-
cd "D/<repo>" && git add -
|
|
559
|
+
cd "D/<repo>" && git add oats-workspace.yaml oats-membership.yaml && git commit -m "OATS workspace acme: workspace and team" && git push -u origin HEAD
|
|
472
560
|
```
|
|
473
561
|
|
|
474
|
-
|
|
475
|
-
`git:github.com/acme/acme-oats`.
|
|
476
|
-
|
|
477
|
-
**Existing workspace.** `W` is the reference they gave. Write nothing in its
|
|
478
|
-
repositories.
|
|
479
|
-
|
|
480
|
-
## 6. Onboard this machine
|
|
562
|
+
## 8. Onboard this machine
|
|
481
563
|
|
|
482
564
|
```bash
|
|
483
|
-
oats onboard D --workspace W
|
|
565
|
+
oats onboard D --workspace W --json
|
|
484
566
|
```
|
|
485
567
|
|
|
486
568
|
- **Effects:** it writes `D/oats-local.yaml` and `D/agents/`, reads every
|
|
@@ -491,53 +573,73 @@ oats onboard D --workspace W
|
|
|
491
573
|
- **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
|
|
492
574
|
person whether to use it as it is or to choose another directory.
|
|
493
575
|
|
|
494
|
-
**
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
`<workspace>-oats-setup-expert`, else one whose definition declares
|
|
500
|
-
`oats.setup`.
|
|
576
|
+
**The setup expert, `S`, and its spawn line.** `result.next.spawn` is the
|
|
577
|
+
line to spawn it with. For a new workspace it names `oats.framework`'s
|
|
578
|
+
`oats-setup-expert` with `--name <workspace>-oats-setup-expert`; when it
|
|
579
|
+
carries another name or no `--name`, the text output of `oats onboard` says
|
|
580
|
+
why. `S` is the soul it names.
|
|
501
581
|
- **On a machine found-list,** `S` is `oats.machine/steward`. An existing
|
|
502
582
|
workspace that doesn't offer it: stop, and say that its owner adds
|
|
503
583
|
`oats.machine` to its `packages:`.
|
|
504
|
-
- **An existing workspace with no
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
584
|
+
- **An existing workspace with no setup soul** (`next.spawn` is `null`): stop.
|
|
585
|
+
Say that its owner pins `oats.framework` 1.18.0 or later, which ships
|
|
586
|
+
`oats-setup-expert`. Once that is merged, run `oats sync --dir D` and look
|
|
587
|
+
again.
|
|
508
588
|
|
|
509
589
|
**The clone.** A soul with `work: worktree` needs a clone of its repository
|
|
510
|
-
at `D/<repo name>`.
|
|
511
|
-
|
|
590
|
+
at `D/<repo name>`. `oats-setup-expert` works in a directory of its own and
|
|
591
|
+
needs none. For an existing workspace whose setup soul is the workspace's
|
|
592
|
+
own, clone the repository that holds it with the `git clone` line
|
|
512
593
|
`oats onboard` printed for it, if that line says it is missing.
|
|
513
594
|
|
|
514
|
-
**
|
|
515
|
-
|
|
516
|
-
|
|
595
|
+
**Record the setup expert's harness** on this machine. A package soul names
|
|
596
|
+
none, and without this every later check (readiness, harness trust) and the
|
|
597
|
+
spawn would use the default, pi:
|
|
517
598
|
|
|
518
599
|
```bash
|
|
519
600
|
oats soul launch set S --harness <harness> --dir D --plan
|
|
520
601
|
oats soul launch set S --harness <harness> --dir D
|
|
521
602
|
```
|
|
522
603
|
|
|
523
|
-
##
|
|
604
|
+
## 9. Messaging on this machine
|
|
605
|
+
|
|
606
|
+
Read `oats inspect --soul S --dir D --json`. Its `result.layers.messaging.id`
|
|
607
|
+
names the soul's messaging capability; `null` means none, and then skip this
|
|
608
|
+
step. Otherwise the setup expert can't spawn on this machine until that
|
|
609
|
+
capability is set up here. That setup is the capability's own; its readiness
|
|
610
|
+
names what is missing:
|
|
611
|
+
|
|
612
|
+
```bash
|
|
613
|
+
oats readiness --soul S --dir D --json
|
|
614
|
+
```
|
|
524
615
|
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
pi: `pi install npm:@awebai/pi`; Codex: nothing). Then:
|
|
616
|
+
The messaging items must not report a problem. aweb, the default, is set up
|
|
617
|
+
as below. For another messaging capability, follow its own setup skill, and
|
|
618
|
+
stop if its readiness still reports a problem.
|
|
619
|
+
|
|
620
|
+
**With aweb (`oats.aweb`):**
|
|
621
|
+
1. **Check:**
|
|
532
622
|
|
|
533
623
|
```bash
|
|
534
|
-
cd "D" && oats aweb setup --soul S --
|
|
624
|
+
cd "D" && oats aweb setup --soul S --check-only --json
|
|
535
625
|
```
|
|
536
626
|
|
|
537
|
-
Its `aw.status` must be `ok
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
627
|
+
Its `aw.status` must be `ok`. If `aw` is missing, install it and the
|
|
628
|
+
harness's channel as step 4 says, then check again; stop on anything else
|
|
629
|
+
and tell the person why. Its `defaultTeam.label` is `L`, the setup expert's team.
|
|
630
|
+
- **A new workspace** expects `"member": true` here: step 5 installed the
|
|
631
|
+
root. Then this step is done. A machine found-list skipped step 5, so
|
|
632
|
+
its `"member": false` here is expected: go on to item 2.
|
|
633
|
+
- **`"member": false` on a new workspace, without a machine found-list:**
|
|
634
|
+
stop, spawn nothing, and tell the person which fix applies. With
|
|
635
|
+
`"root": null`, there is no root in `D/.aw`: step 5's team creation did
|
|
636
|
+
not finish there, so run its line for an interrupted run, then check
|
|
637
|
+
again. With a `root`, that root is not a member of `defaultTeam.team`:
|
|
638
|
+
the team id step 7 wrote must be step 5's `canonical_team_id` exactly,
|
|
639
|
+
so correct it in `oats-workspace.yaml`, commit and push it, run
|
|
640
|
+
`oats sync --dir D`, then check again.
|
|
641
|
+
2. **Machine found-list: sign up its aweb account and team,** with `N` and
|
|
642
|
+
`A` from step 1. No API key, no token and nothing for the person to type.
|
|
541
643
|
Preview first, then run it:
|
|
542
644
|
|
|
543
645
|
```bash
|
|
@@ -547,12 +649,7 @@ can't spawn on this machine until it has messaging too. Set it up now:
|
|
|
547
649
|
|
|
548
650
|
The preview does not contact aweb, so it can't tell whether `N` is free.
|
|
549
651
|
If the run fails with `E_SETUP_NATIVE` (most likely the username is
|
|
550
|
-
taken; aw's output is withheld), don't rerun
|
|
551
|
-
`test -e "D/.aw" && echo HAS_AW`. If it prints `HAS_AW`, stop and tell the
|
|
552
|
-
person what you saw. Otherwise ask the person for another `N`, then in
|
|
553
|
-
`D/<repo>` change the team id in `oats-workspace.yaml` to
|
|
554
|
-
`default:N.aweb.ai`, commit and push it, run `oats sync --dir D`, and run
|
|
555
|
-
both lines again. Then skip items 3 and 4 and go to the check (item 5).
|
|
652
|
+
taken; aw's output is withheld), don't rerun.
|
|
556
653
|
On a machine found-list, ask nothing: tell the person that the run
|
|
557
654
|
failed, most likely because `N` is taken, and stop.
|
|
558
655
|
3. **Existing workspace: the person gets an invite token** from a member of `L`, who runs
|
|
@@ -570,11 +667,10 @@ can't spawn on this machine until it has messaging too. Set it up now:
|
|
|
570
667
|
```text
|
|
571
668
|
cd "D" && sh -c 'stty -echo; printf "Invite token: "; read -r T; stty echo; echo; printf "%s\n" "$T" | oats aweb setup --soul S --join L --invite-stdin --name A --service U'
|
|
572
669
|
```
|
|
573
|
-
5. **
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
```
|
|
670
|
+
5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
|
|
671
|
+
On `"member": false`, stop and spawn nothing: tell the person the run
|
|
672
|
+
left this machine's root outside `L`, with what the check shows, and
|
|
673
|
+
don't rerun the signup or the join.
|
|
578
674
|
|
|
579
675
|
The setup expert does the rest of this machine's messaging
|
|
580
676
|
(`/oats-host-delivery`).
|
|
@@ -589,9 +685,9 @@ Without messaging there is no address to make: skip this. Otherwise it
|
|
|
589
685
|
needs every one of these, and when one fails, take the fallback below:
|
|
590
686
|
- a new workspace: a root that joined by invite (items 3 and 4) does not own
|
|
591
687
|
the namespace, so aweb would refuse the create;
|
|
592
|
-
- `oats.aweb` 1.
|
|
688
|
+
- `oats.aweb` 1.34.0 or later: the `oats.aweb` row of the
|
|
593
689
|
`oats inspect` you read above, `result.capabilities[].version`;
|
|
594
|
-
- aw 1.36.48 or later: `aw.version` in the check (item
|
|
690
|
+
- aw 1.36.48 or later: `aw.version` in the check (item 1).
|
|
595
691
|
|
|
596
692
|
Plan, then create, both from `D` and with no `AWEB_API_KEY`:
|
|
597
693
|
|
|
@@ -621,13 +717,16 @@ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
|
|
|
621
717
|
global address because of <the reason>, and the GLOBAL residents and grant
|
|
622
718
|
seats section of `/oats-aweb` moves it to one later. Never ask for a key.
|
|
623
719
|
|
|
720
|
+
## 10. Spawn the setup expert, then show it
|
|
721
|
+
|
|
624
722
|
**Write the hand-over** to `D/.oats-handover.md`. It holds no secret.
|
|
625
723
|
|
|
626
724
|
```markdown
|
|
627
725
|
# Onboarding hand-over from the getting-started skill
|
|
628
726
|
|
|
629
727
|
- Workspace: <workspace> (W), new | existing; deployment directory: D
|
|
630
|
-
-
|
|
728
|
+
- Host: <owner>/<repo>, a monorepo | a dedicated host | the first repository
|
|
729
|
+
- Setup expert: S, instance <name>, harness <harness>
|
|
631
730
|
- Machine found-list only: steward R, address N.aweb.ai/R | local team
|
|
632
731
|
identity (<the fallback's reason>)
|
|
633
732
|
|
|
@@ -638,9 +737,13 @@ are cloned, knowledge tools, messaging wanted or not>
|
|
|
638
737
|
## Done by the getting-started skill
|
|
639
738
|
- Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
|
|
640
739
|
- GitHub: gh logged in over https as <login>; no SSH key or signing set up
|
|
641
|
-
- New workspace only:
|
|
642
|
-
|
|
643
|
-
|
|
740
|
+
- New workspace only: host <owner>/<repo>, skeleton committed (pushed | in
|
|
741
|
+
pull request <url>)
|
|
742
|
+
- Messaging: <capability>, aw <version>, <harness> channel installed;
|
|
743
|
+
team T owned by aweb account <handle> (new workspace), or new account N
|
|
744
|
+
signed up (machine found-list), or joined L by invite (existing) | not set
|
|
745
|
+
up (the setup expert has no messaging)
|
|
746
|
+
- Harness channel mode: development, confirmed by OATS at each start
|
|
644
747
|
|
|
645
748
|
## Left to you
|
|
646
749
|
Everything else, starting with /oats-setup-expert.
|
|
@@ -662,15 +765,23 @@ oats harness trust --dir D --harness claude
|
|
|
662
765
|
- **Then check** that the `harness-trust` item of
|
|
663
766
|
`oats readiness --soul S --dir D --json` passes.
|
|
664
767
|
|
|
665
|
-
**
|
|
768
|
+
**The channel mode.** With Claude and aweb, the setup expert starts in the
|
|
769
|
+
development channel mode, the default: Claude asks once at each start
|
|
770
|
+
whether to load the aweb channel, and OATS confirms it for you. Leave it so.
|
|
771
|
+
Don't set `delivery: session`. The setup expert offers the approved route,
|
|
772
|
+
which needs no confirmation, later (it needs `sudo`).
|
|
773
|
+
|
|
774
|
+
**Preview the spawn, read it, then spawn,** with step 8's `next.spawn` line
|
|
775
|
+
plus the hand-over:
|
|
666
776
|
|
|
667
777
|
```bash
|
|
668
|
-
|
|
669
|
-
|
|
778
|
+
<next.spawn> --task-file D/.oats-handover.md --preview
|
|
779
|
+
<next.spawn> --task-file D/.oats-handover.md
|
|
670
780
|
```
|
|
671
781
|
|
|
672
|
-
|
|
673
|
-
|
|
782
|
+
For example, `oats spawn oats-setup-expert --dir D --name acme-oats-setup-expert --task-file D/.oats-handover.md`.
|
|
783
|
+
|
|
784
|
+
**On a machine found-list,** name the steward `R`. With its global address:
|
|
674
785
|
|
|
675
786
|
```bash
|
|
676
787
|
oats spawn S --dir D --task-file D/.oats-handover.md --name R --provider oats.aweb identity.mode=global --provider oats.aweb identity.resident=R --preview
|
|
@@ -681,30 +792,42 @@ In the fallback, or without messaging, leave out both `--provider` options.
|
|
|
681
792
|
|
|
682
793
|
- **The preview** shows what the spawn would create. If it reports a
|
|
683
794
|
problem, stop and tell the person what it says.
|
|
684
|
-
- **The spawn** prints the instance's home `H
|
|
685
|
-
file: the home has its copy as `TASK.md`.
|
|
795
|
+
- **The spawn** prints the instance's home `H` and its name. Then delete the
|
|
796
|
+
hand-over file: the home has its copy as `TASK.md`.
|
|
686
797
|
- **`E_SPAWN_INCOMPLETE`:** don't spawn again. Run `oats session inspect
|
|
687
798
|
--home H --json` and tell the person what it shows.
|
|
799
|
+
- **`E_INSTANCE_NAME_TAKEN`** (the preview or the spawn): the setup expert
|
|
800
|
+
already exists, so don't spawn another. Its home `H` is in the error. It
|
|
801
|
+
is opened in the Desktop below; if it is stopped, start it with
|
|
802
|
+
`oats session start --home H`.
|
|
803
|
+
|
|
804
|
+
**The Desktop**, if installed, opens on the new deployment with the setup
|
|
805
|
+
expert selected. `I` is its instance name: the one the spawn printed, which is
|
|
806
|
+
`next.spawn`'s `--name` when it has one (after `E_INSTANCE_NAME_TAKEN`, that
|
|
807
|
+
`--name`). A Desktop that does not know `--instance` ignores it and opens the
|
|
808
|
+
deployment, so pass it always.
|
|
809
|
+
- **macOS:**
|
|
688
810
|
|
|
689
|
-
|
|
811
|
+
```bash
|
|
812
|
+
open -n -a "OATS Desktop" --args --dir "D" --instance "I"
|
|
813
|
+
```
|
|
690
814
|
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
already running, the new launch hands `--dir` to it and exits.
|
|
815
|
+
If the Desktop is already running, the new launch hands `--dir` and
|
|
816
|
+
`--instance` to it and exits.
|
|
694
817
|
- **Linux:** start it yourself through their session manager, so it gets
|
|
695
818
|
their desktop session's environment, not yours (yours may carry your
|
|
696
819
|
harness's variables and sandbox, and the Desktop passes its environment to
|
|
697
820
|
every agent it starts):
|
|
698
821
|
|
|
699
822
|
```bash
|
|
700
|
-
U="oats-desktop-$(date +%s)"; LOG="$(mktemp)"; systemd-run --user --collect --quiet --unit "$U" -p KillMode=process -p StandardOutput="file:$LOG" -p StandardError="file:$LOG" -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY "$HOME/.local/opt/oats-desktop/OATS-Desktop.AppImage" --dir "D" && for i in $(seq 30); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null && break; sleep 1; done; sleep 3; if pgrep -u "$(id -u)" -x oats-desktop >/dev/null; then echo STARTED; else echo FAILED; tail -n 20 "$LOG"; fi
|
|
823
|
+
U="oats-desktop-$(date +%s)"; LOG="$(mktemp)"; systemd-run --user --collect --quiet --unit "$U" -p KillMode=process -p StandardOutput="file:$LOG" -p StandardError="file:$LOG" -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY "$HOME/.local/opt/oats-desktop/OATS-Desktop.AppImage" --dir "D" --instance "I" && for i in $(seq 30); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null && break; sleep 1; done; sleep 3; if pgrep -u "$(id -u)" -x oats-desktop >/dev/null; then echo STARTED; else echo FAILED; tail -n 20 "$LOG"; fi
|
|
701
824
|
```
|
|
702
825
|
|
|
703
|
-
- **`STARTED`:** it shows `D
|
|
826
|
+
- **`STARTED`:** it shows `D`, with `I` selected.
|
|
704
827
|
- **A FUSE message:** see step 4, then start it again.
|
|
705
828
|
- **Anything else,** or no `systemd-run`: tell the person what it printed.
|
|
706
829
|
They open **OATS Desktop** from their app launcher, and it lists `D` in
|
|
707
|
-
its switcher
|
|
830
|
+
its switcher.
|
|
708
831
|
- **Never start it with an emptied environment** (`env -i`): it then loses
|
|
709
832
|
HOME, and Git loses the person's login.
|
|
710
833
|
|
|
@@ -712,10 +835,10 @@ In the fallback, or without messaging, leave out both `--provider` options.
|
|
|
712
835
|
their own terminal, as "How to work" says, with the command
|
|
713
836
|
`oats tui --dir "D"`.
|
|
714
837
|
|
|
715
|
-
**Tell the person where the setup expert is** (
|
|
716
|
-
steward, and its address), and that it continues
|
|
717
|
-
here: in the Desktop or the TUI you started. Without either, they reach
|
|
718
|
-
with `oats session attach --home H` in a terminal.
|
|
838
|
+
**Tell the person where the setup expert is** (its instance name; on a
|
|
839
|
+
machine found-list, the steward, and its address), and that it continues
|
|
840
|
+
from here: in the Desktop or the TUI you started. Without either, they reach
|
|
841
|
+
it with `oats session attach --home H` in a terminal.
|
|
719
842
|
|
|
720
843
|
It will ask them only what the hand-over leaves open, and it opens a pane in
|
|
721
844
|
its own window when they need to type a secret. You are done.
|
|
@@ -725,11 +848,13 @@ its own window when they need to type a secret. You are done.
|
|
|
725
848
|
- **Ask for, read, print or store a secret,** or suggest `!` for one. If the
|
|
726
849
|
person pastes one into the conversation anyway, don't repeat it, and tell
|
|
727
850
|
them to rotate it.
|
|
728
|
-
- **Overwrite or re-onboard** a deployment, or push to a
|
|
729
|
-
person did not create in step
|
|
851
|
+
- **Overwrite or re-onboard** a deployment, touch `D/.aw`, or push to a
|
|
852
|
+
repository the person did not create or name as the host in step 6.
|
|
853
|
+
- **Guess the team id:** it comes from step 5's answer.
|
|
854
|
+
- **Write a setup soul into the workspace:** the setup expert is
|
|
855
|
+
`oats.framework`'s.
|
|
730
856
|
- **The Desktop:** never download it through a browser, skip a verification
|
|
731
857
|
step, strip quarantine without asking, or start it with `env -i`.
|
|
732
858
|
- **Put an absolute path or a credential** in `oats-workspace.yaml`,
|
|
733
|
-
`oats-membership.yaml` or a soul (the
|
|
734
|
-
a secret).
|
|
859
|
+
`oats-membership.yaml` or a soul (the team id is not a secret).
|
|
735
860
|
- **Spawn** before `oats onboard` confirmed the host.
|