@awebai/oats 0.63.0 → 0.65.0
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 +14 -1
- package/bin/oats.mjs +158 -26
- package/docs/desktop-cli-api.md +127 -3
- package/docs/desktop.md +14 -5
- package/docs/execution-targets.md +9 -5
- package/docs/first-team.md +6 -0
- package/docs/implementation.md +17 -3
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.64.0.md +105 -0
- package/docs/release-notes/v0.65.0.md +187 -0
- package/docs/souls-and-instances.md +26 -6
- package/docs/tui.md +416 -238
- package/docs/upgrading.md +2 -1
- package/docs/workspaces.md +125 -1
- package/lib/core.mjs +43 -11
- package/lib/deployments.mjs +325 -0
- package/lib/resolved-deployment.mjs +37 -0
- package/lib/session-input.mjs +12 -2
- package/lib/workspace.mjs +2 -0
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-label.mjs +2 -2
- package/packages/client/deployment-list-cli.mjs +98 -0
- package/packages/client/deployment-list.mjs +91 -0
- package/packages/client/instance-tree.mjs +53 -3
- package/packages/client/keymap.mjs +106 -0
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/panel-views.mjs +1 -1
- package/packages/client/roster-sections.mjs +22 -6
- package/packages/client/workspace-admission.mjs +2 -1
- package/packages/tui/README.md +4 -4
- package/packages/tui/lib/actions.mjs +29 -5
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/config.mjs +21 -14
- package/packages/tui/lib/main.mjs +108 -31
- package/packages/tui/lib/model.mjs +71 -41
- package/packages/tui/lib/read.mjs +15 -45
- package/packages/tui/lib/store.mjs +158 -39
- package/packages/tui/lib/term/through.mjs +40 -18
- package/packages/tui/lib/views/act.mjs +17 -13
- package/packages/tui/lib/views/frame.mjs +418 -421
- package/packages/tui/lib/views/help.mjs +41 -19
- package/packages/tui/lib/views/instances.mjs +38 -9
- package/packages/tui/lib/views/switcher.mjs +65 -21
- package/skills/oats-getting-started/SKILL.md +440 -170
|
@@ -1,230 +1,500 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: oats-getting-started
|
|
3
3
|
description: >-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
workspace
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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 and OATS Desktop,
|
|
6
|
+
then either creates a new workspace with its own setup expert soul or joins
|
|
7
|
+
this machine to an existing workspace, and ends by spawning the workspace's
|
|
8
|
+
setup expert, which does the rest. Offers the TUI. Use for "get started
|
|
9
|
+
with OATS", "set up / install / adopt OATS", "join our OATS workspace", or
|
|
10
|
+
when someone gives you this file or its URL.
|
|
11
11
|
---
|
|
12
12
|
|
|
13
13
|
# Getting started with OATS
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
15
|
+
You are the person's own coding agent. This skill takes them from nothing to
|
|
16
|
+
a running **setup expert**: an OATS agent of their workspace that does the
|
|
17
|
+
rest of the setup with them (Git, their repositories, knowledge, messaging,
|
|
18
|
+
their first agents). You install, ask, write a few files and spawn it. Then
|
|
19
|
+
you are done.
|
|
20
|
+
|
|
21
|
+
OATS in one paragraph: a **workspace** is one Git repository declaring which
|
|
22
|
+
repositories belong to an organisation and which packages it trusts. A
|
|
23
|
+
**soul** is a durable agent role defined in Git; an **instance** is a soul at
|
|
24
|
+
work, in its own home and terminal. Each workspace has a setup expert soul,
|
|
25
|
+
`<workspace>-oats-setup-expert`, which holds the `oats.setup` capability.
|
|
26
|
+
|
|
27
|
+
**How to work.**
|
|
28
|
+
- **Ask first, then run.** Ask everything in one round (step 1), then run the
|
|
29
|
+
steps yourself and read back what each did.
|
|
30
|
+
- **Secrets.** The person types only what you must never hold: passwords,
|
|
31
|
+
tokens and logins. Before the spawn there are two ways for that: a browser
|
|
32
|
+
device flow you start (the GitHub login, step 3), and the exact command
|
|
33
|
+
for their own terminal (a `sudo` or Homebrew password, an aweb invite
|
|
34
|
+
token).
|
|
35
|
+
- Never ask for a secret in the conversation, and never write one to a file.
|
|
36
|
+
- Never suggest Claude Code's `! <command>` for one: its command and output
|
|
37
|
+
enter your context.
|
|
38
|
+
- **Your shell may keep nothing between commands.** Many harnesses start each
|
|
39
|
+
command in a new shell, in the same starting folder.
|
|
40
|
+
- Run each fenced block below as one command.
|
|
41
|
+
- When a later block needs a value an earlier one found (`V`, `ARCH`, a
|
|
42
|
+
path), write that value in literally.
|
|
43
|
+
- **Sandboxes.** If your harness sandboxes commands, these steps need network
|
|
44
|
+
access and writes in the home folder: ask the person to approve them.
|
|
45
|
+
- **Touch nothing you were not asked to.** Don't edit an existing
|
|
46
|
+
deployment's files (`oats-local.yaml`, `oats-lock.json`, `agents/`), and
|
|
47
|
+
don't push to a repository the person did not create in step 5.
|
|
48
|
+
|
|
49
|
+
## 1. Ask, in one round
|
|
50
|
+
|
|
51
|
+
- **The use case:** what they want agents to do.
|
|
52
|
+
- **Their repositories and project:** which repositories agents should work
|
|
53
|
+
in, where they are cloned on this machine, and which are private.
|
|
54
|
+
- **Their knowledge tools:** where their team's knowledge lives today (a docs
|
|
55
|
+
repository, a wiki, Notion, Confluence, none).
|
|
56
|
+
- **A new workspace, or an existing one?**
|
|
57
|
+
- Existing: its repository reference, for example
|
|
58
|
+
`git:github.com/acme/acme-oats`. They get it from whoever runs that
|
|
59
|
+
workspace.
|
|
60
|
+
- New: the **workspace name**: lowercase letters and digits, words joined
|
|
61
|
+
by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`. Also
|
|
62
|
+
the GitHub **owner** of its repository (their user, or an organisation
|
|
63
|
+
they can create repositories in) and the repository's name. Suggest
|
|
64
|
+
`<workspace>-oats`. Refuse `agents`: OATS keeps instance homes in a
|
|
65
|
+
folder of that name.
|
|
66
|
+
- **Messaging between agents (aweb):** wanted or not. The setup expert sets it
|
|
67
|
+
up later. An existing workspace that already has it needs it on this
|
|
68
|
+
machine before the setup expert can spawn (step 7).
|
|
69
|
+
- **The harness for the setup expert:** `claude`, `codex` or `pi`. Default:
|
|
70
|
+
the one you are, if it is one of these.
|
|
71
|
+
- **The deployment directory `D`:** where OATS lives on this machine. Any
|
|
72
|
+
folder but their home folder itself works: ask for it, and suggest none.
|
|
73
|
+
From OATS 0.65.0, `oats onboard` adds `D` to this computer's list of
|
|
74
|
+
deployments (`~/.oats/config/deployments.json`, which `oats deployments`
|
|
75
|
+
reads), so the Desktop and the TUI find it wherever it is. Write `D` everywhere
|
|
76
|
+
below as an absolute path, with the home folder spelled out: never `~`,
|
|
77
|
+
which the shell does not expand inside quotes.
|
|
78
|
+
- **OATS Desktop:** installed and started unless they decline. **The TUI**
|
|
79
|
+
(`oats tui`, a terminal client, preview): opened for them or not.
|
|
80
|
+
|
|
81
|
+
## 2. Check, and install what is missing
|
|
21
82
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
83
|
+
```bash
|
|
84
|
+
uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- **Versions:** Node 22 or later; Git 2.45 or later is best (older works,
|
|
88
|
+
fetching more); `gh` 2.49 or later (step 4 uses `gh attestation`).
|
|
89
|
+
- **The harness** they chose must be installed and logged in (`claude
|
|
90
|
+
--version`, `codex --version` or `pi --version`).
|
|
91
|
+
- **macOS:** with Homebrew (`brew --version`), `brew install node git tmux gh`.
|
|
92
|
+
- **Without Homebrew,** they install it in their own Terminal, since it asks
|
|
93
|
+
for their password: from <https://brew.sh>, the command under “Install
|
|
94
|
+
Homebrew”, then the “Next steps” lines it prints.
|
|
95
|
+
- Your running process does not see their new PATH. Start each later
|
|
96
|
+
command with `eval "$(/opt/homebrew/bin/brew shellenv)"`
|
|
97
|
+
(`/usr/local/bin/brew` on Intel), or ask them to restart you.
|
|
98
|
+
- **Linux:**
|
|
99
|
+
- **Packages:** the distribution's, for git and tmux.
|
|
100
|
+
- **gh:** from GitHub's own apt or rpm repository
|
|
101
|
+
(<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>), because
|
|
102
|
+
distributions ship versions too old for step 4.
|
|
103
|
+
- **Node 22:** from NodeSource or a version manager when the distribution's
|
|
104
|
+
is older.
|
|
105
|
+
- **Passwords:** a line that needs `sudo` goes to their own terminal,
|
|
106
|
+
unless `sudo -n true` succeeds.
|
|
107
|
+
- **npm's global folder** (`npm prefix -g`) must be writable for step 4's
|
|
108
|
+
install (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node
|
|
109
|
+
under `/usr`), either they run that install with `sudo` in their own
|
|
110
|
+
terminal, or set a per-user prefix (`npm config set prefix ~/.local`, with
|
|
111
|
+
`~/.local/bin` on their PATH).
|
|
112
|
+
- **Windows** is not supported.
|
|
113
|
+
|
|
114
|
+
## 3. Log in to GitHub
|
|
115
|
+
|
|
116
|
+
OATS reads the workspace and its repositories with Git, using the person's
|
|
117
|
+
GitHub access. Check first:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
gh auth status
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
If it is not logged in, start the login yourself, detached and without a
|
|
124
|
+
terminal (use your harness's background mode if it has one). gh then prints
|
|
125
|
+
a one-time code and a URL instead of opening a browser, and waits:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
nohup gh auth login --web --hostname github.com --git-protocol https --skip-ssh-key </dev/null >"$HOME/.oats-gh-login.txt" 2>&1 &
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
In a separate command, a few seconds later, read the code and the URL:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
cat "$HOME/.oats-gh-login.txt"
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
- **Give the person the code and the URL** (`https://github.com/login/device`).
|
|
138
|
+
The code is not a secret: only their own signed-in browser can use it. They
|
|
139
|
+
open the URL, enter the code and approve. A code expires after about 15
|
|
140
|
+
minutes; then start again.
|
|
141
|
+
- **Once they say they approved,** check the login and let Git use it:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
gh auth status && gh auth setup-git && rm -f "$HOME/.oats-gh-login.txt"
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The token stays in gh's store and never reaches you. SSH keys, commit
|
|
148
|
+
signing and the DCO sign-off come later, from the setup expert.
|
|
149
|
+
|
|
150
|
+
## 4. Install OATS Desktop, then the CLI, at the same version
|
|
151
|
+
|
|
152
|
+
The Desktop accepts a band of CLI versions around its own, so install it
|
|
153
|
+
first, then the CLI of the same version `V`. Find `V`, and on macOS `ARCH`:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
npm view @awebai/oats version
|
|
157
|
+
sysctl -n hw.optional.arm64 2>/dev/null # macOS: 1 means ARCH=arm64, otherwise ARCH=x64
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**Every step verifies before it installs.** If a download or a check fails
|
|
161
|
+
(the release's Desktop assets can lag its npm package), skip the Desktop,
|
|
162
|
+
say so, and go on with the CLI. Never skip a check to make it install.
|
|
163
|
+
|
|
164
|
+
**macOS.** In one block, with `V` and `ARCH` written in. Install into
|
|
165
|
+
`/Applications`, which needs an administrator; for a standard user, use
|
|
166
|
+
`$HOME/Applications` (`mkdir -p "$HOME/Applications"`) in its place in every
|
|
167
|
+
line below:
|
|
25
168
|
|
|
26
|
-
|
|
169
|
+
```bash
|
|
170
|
+
cd "$(mktemp -d)" && pwd &&
|
|
171
|
+
gh release download "vV" -R awebai/oats -p "oats-desktop-V-mac-ARCH.zip" -p SHA256SUMS.txt &&
|
|
172
|
+
grep " oats-desktop-V-mac-ARCH.zip\$" SHA256SUMS.txt | shasum -a 256 -c - &&
|
|
173
|
+
gh attestation verify "oats-desktop-V-mac-ARCH.zip" --repo awebai/oats &&
|
|
174
|
+
ditto -x -k "oats-desktop-V-mac-ARCH.zip" . &&
|
|
175
|
+
codesign --verify --deep --strict "OATS Desktop.app" &&
|
|
176
|
+
defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleIdentifier &&
|
|
177
|
+
defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
- **Expected:** `ai.oats.desktop` and `V`. The app is ad-hoc signed and not
|
|
181
|
+
notarized; `codesign --verify` passing is what to expect.
|
|
182
|
+
- **Download with `gh`, never through a browser.** `gh` sets no quarantine
|
|
183
|
+
on what it downloads, and that copy starts from Finder. A browser download
|
|
184
|
+
would be quarantined.
|
|
185
|
+
- **Install it.** If the Desktop is running, ask the person to quit it. Then,
|
|
186
|
+
with the folder `pwd` printed:
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
cd "<that folder>" && rm -rf "/Applications/OATS Desktop.app" && ditto "OATS Desktop.app" "/Applications/OATS Desktop.app" && defaults read "/Applications/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
|
|
190
|
+
xattr -p com.apple.quarantine "/Applications/OATS Desktop.app" 2>/dev/null && echo QUARANTINED
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
- **If it prints `QUARANTINED`,** tell the person. Remove the attribute only
|
|
194
|
+
if they agree (`xattr -dr com.apple.quarantine "/Applications/OATS
|
|
195
|
+
Desktop.app"`): never silently.
|
|
196
|
+
|
|
197
|
+
**Linux x64.** It needs glibc 2.34 or later (`ldd --version`). It installs
|
|
198
|
+
per user, without sudo, and shows in the app launcher:
|
|
27
199
|
|
|
28
200
|
```bash
|
|
29
|
-
|
|
30
|
-
|
|
201
|
+
cd "$(mktemp -d)" &&
|
|
202
|
+
gh release download "vV" -R awebai/oats -p "oats-desktop-V-linux-x86_64.AppImage" -p SHA256SUMS.txt &&
|
|
203
|
+
grep " oats-desktop-V-linux-x86_64.AppImage\$" SHA256SUMS.txt | sha256sum -c - &&
|
|
204
|
+
gh attestation verify "oats-desktop-V-linux-x86_64.AppImage" --repo awebai/oats &&
|
|
205
|
+
mkdir -p ~/.local/opt/oats-desktop ~/.local/share/applications &&
|
|
206
|
+
install -m 755 "oats-desktop-V-linux-x86_64.AppImage" ~/.local/opt/oats-desktop/OATS-Desktop.AppImage
|
|
31
207
|
```
|
|
32
208
|
|
|
33
|
-
|
|
34
|
-
|
|
209
|
+
Then write `~/.local/share/applications/oats-desktop.desktop`, with `<home>`
|
|
210
|
+
their home directory's absolute path:
|
|
35
211
|
|
|
36
|
-
|
|
212
|
+
```text
|
|
213
|
+
[Desktop Entry]
|
|
214
|
+
Type=Application
|
|
215
|
+
Name=OATS Desktop
|
|
216
|
+
Exec=<home>/.local/opt/oats-desktop/OATS-Desktop.AppImage %U
|
|
217
|
+
Terminal=false
|
|
218
|
+
Categories=Development;
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
- **Without FUSE** (the AppImage fails with a FUSE message), add
|
|
222
|
+
` --appimage-extract-and-run` after the AppImage's path in `Exec=` and
|
|
223
|
+
wherever you start it.
|
|
224
|
+
- **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
|
|
225
|
+
download, say so and go on.
|
|
226
|
+
|
|
227
|
+
**Don't start the Desktop yet;** step 8 starts it on the new deployment.
|
|
228
|
+
|
|
229
|
+
**Then the CLI, and for pi its bridge:**
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
npm install -g "@awebai/oats@V" && oats version
|
|
233
|
+
pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
|
|
234
|
+
```
|
|
37
235
|
|
|
38
|
-
The workspace
|
|
39
|
-
the member list. Ask:
|
|
236
|
+
## 5. The workspace
|
|
40
237
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
- **
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
238
|
+
**New workspace.** Create its repository, private, inside the deployment
|
|
239
|
+
directory `D`, then write four files in it.
|
|
240
|
+
- **Private** is the safe default: the workspace file names every member, so
|
|
241
|
+
whoever reads it sees the list.
|
|
242
|
+
- **`D/<repo>` must not exist yet:** an existing folder's files would end up
|
|
243
|
+
in the first commit.
|
|
47
244
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
245
|
+
```bash
|
|
246
|
+
mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
|
|
247
|
+
```
|
|
51
248
|
|
|
52
|
-
|
|
249
|
+
Then write the four files below in `D/<repo>`. They show a workspace named
|
|
250
|
+
`acme`, in the repository `acme/acme-oats`, with Claude as the harness:
|
|
251
|
+
write the person's own workspace name, repository and harness in their
|
|
252
|
+
place.
|
|
53
253
|
|
|
54
|
-
|
|
254
|
+
`oats-workspace.yaml`:
|
|
55
255
|
|
|
56
256
|
```yaml
|
|
57
257
|
schemaVersion: 2
|
|
58
258
|
name: acme
|
|
59
259
|
members:
|
|
60
|
-
- git:github.com/acme/
|
|
61
|
-
- git:github.com/acme/platform
|
|
260
|
+
- git:github.com/acme/acme-oats # the host is a member too
|
|
62
261
|
packages:
|
|
63
|
-
oats.framework: v1.13.
|
|
64
|
-
oats.okf: v5.2.1
|
|
262
|
+
oats.framework: v1.13.3 # the installed CLI's catalog version (below)
|
|
65
263
|
defaults:
|
|
66
|
-
capabilities:
|
|
67
|
-
|
|
264
|
+
capabilities:
|
|
265
|
+
oats.core: { from: package }
|
|
68
266
|
```
|
|
69
267
|
|
|
70
|
-
|
|
71
|
-
(
|
|
72
|
-
|
|
73
|
-
|
|
268
|
+
- **The `oats.framework` version** is the installed CLI's catalog's:
|
|
269
|
+
`"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`,
|
|
270
|
+
for example `oats-framework/v1.13.3`. Write the part after the `/`.
|
|
271
|
+
- **Add nothing else:** knowledge, messaging and teams come with the setup
|
|
272
|
+
expert.
|
|
74
273
|
|
|
75
|
-
|
|
76
|
-
and hooks run on every machine that spawns a soul using it. Show the user what
|
|
77
|
-
each package runs (its capability manifests' `commands` and `hooks`) before
|
|
78
|
-
adding its pin.
|
|
79
|
-
|
|
80
|
-
In **every** member repository, including the host, `oats-membership.yaml`:
|
|
274
|
+
`oats-membership.yaml`:
|
|
81
275
|
|
|
82
276
|
```yaml
|
|
83
277
|
schemaVersion: 2
|
|
84
|
-
workspace: git:github.com/acme/
|
|
278
|
+
workspace: git:github.com/acme/acme-oats
|
|
85
279
|
```
|
|
86
280
|
|
|
87
|
-
|
|
88
|
-
repository names the workspace back. Neither alone is membership.
|
|
89
|
-
|
|
90
|
-
A soul lives at `souls/<name>/` in a member repository: `soul.yaml`,
|
|
91
|
-
`AGENTS.md` (its canonical instructions) and `CLAUDE.md -> AGENTS.md`.
|
|
281
|
+
`souls/acme-oats-setup-expert/soul.yaml`:
|
|
92
282
|
|
|
93
283
|
```yaml
|
|
94
284
|
schemaVersion: 2
|
|
95
|
-
name:
|
|
96
|
-
description:
|
|
97
|
-
work: worktree
|
|
285
|
+
name: acme-oats-setup-expert
|
|
286
|
+
description: The OATS setup expert for the acme workspace — onboards machines and people, and keeps this workspace's OATS setup working.
|
|
287
|
+
work: worktree # it changes this repository by pull request, on its own branch
|
|
288
|
+
capabilities:
|
|
289
|
+
oats.setup: { from: package }
|
|
290
|
+
knowledge: none # so it spawns on a machine before knowledge is set up there
|
|
291
|
+
launch: { harness: claude } # the harness the person chose: claude, codex or pi
|
|
98
292
|
```
|
|
99
293
|
|
|
100
|
-
|
|
101
|
-
`
|
|
102
|
-
whose knowledge slot is filled by `oats.okf` also needs `okf.json` beside
|
|
103
|
-
`soul.yaml`; `docs/knowledge.md` in the OATS repository shows its shape.
|
|
104
|
-
Commit and push; OATS reads members over their remotes, not from local clones.
|
|
294
|
+
`souls/acme-oats-setup-expert/AGENTS.md`, and beside it the symlink
|
|
295
|
+
`CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`):
|
|
105
296
|
|
|
106
|
-
|
|
297
|
+
```markdown
|
|
298
|
+
# acme-oats-setup-expert
|
|
107
299
|
|
|
108
|
-
|
|
109
|
-
|
|
300
|
+
You are the OATS setup expert for the acme workspace. You set up and keep
|
|
301
|
+
working this workspace's OATS: its machines, members, souls, packages,
|
|
302
|
+
knowledge, messaging and automations. The `oats.setup` capability is your
|
|
303
|
+
toolkit: its briefing says what the person types and what you run, and its
|
|
304
|
+
skills hold every procedure. Start with `/oats-setup-model`. When your task
|
|
305
|
+
is a hand-over from the getting-started skill, follow `/oats-setup-expert`,
|
|
306
|
+
or `/oats-onboarding` if your `oats.setup` is older than 2.8.0 and lacks it.
|
|
307
|
+
Change shared files only by pull request; the person reviews and merges them.
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
**Keep the soul this thin.** Everything it knows comes from `oats.setup`, so
|
|
311
|
+
it improves when the workspace's `oats.framework` pin moves. It has no
|
|
312
|
+
knowledge of its own, so it can be spawned on a machine before knowledge is
|
|
313
|
+
set up there. It takes the workspace's messaging and doesn't empty that
|
|
314
|
+
slot: a setup soul that empties the messaging slot the workspace fills is
|
|
315
|
+
not the workspace's operator, and gets no mail. A new workspace has no
|
|
316
|
+
messaging yet; the setup expert adds it.
|
|
317
|
+
|
|
318
|
+
**Commit and push.**
|
|
319
|
+
- This first commit goes straight to the new repository's default branch: it
|
|
320
|
+
is the person's own, just created. Every later change is a pull request
|
|
321
|
+
from the setup expert.
|
|
322
|
+
- If `git config user.email` prints nothing, the person's Git identity is not
|
|
323
|
+
set up yet. After they confirm their name, commit with
|
|
324
|
+
`-c user.name="<their name>" -c user.email="<their noreply address>"`. The
|
|
325
|
+
noreply address comes from
|
|
326
|
+
`gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`. The
|
|
327
|
+
setup expert sets up their identity properly later.
|
|
110
328
|
|
|
111
329
|
```bash
|
|
112
|
-
|
|
330
|
+
cd "D/<repo>" && git add -A && git commit -m "OATS workspace acme: workspace, membership, setup expert" && git push -u origin HEAD
|
|
113
331
|
```
|
|
114
332
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
the next steps. Fix any member that is not confirmed (`oats workspace status` says why) before going on.
|
|
333
|
+
The workspace reference `W` is then `git:github.com/<owner>/<repo>`, here
|
|
334
|
+
`git:github.com/acme/acme-oats`.
|
|
118
335
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
`oats.okf` that is `bindings-file` and `state-dir`; its own skill explains the
|
|
122
|
-
bindings file.
|
|
336
|
+
**Existing workspace.** `W` is the reference they gave. Write nothing in its
|
|
337
|
+
repositories.
|
|
123
338
|
|
|
124
|
-
##
|
|
339
|
+
## 6. Onboard this machine
|
|
125
340
|
|
|
126
341
|
```bash
|
|
127
|
-
oats
|
|
342
|
+
oats onboard D --workspace W
|
|
128
343
|
```
|
|
129
344
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
345
|
+
- **Effects:** it writes `D/oats-local.yaml` and `D/agents/`, reads every
|
|
346
|
+
member over Git and locks the packages.
|
|
347
|
+
- **The host must be `confirmed`.** Another member with `cannot-read` is an
|
|
348
|
+
access question for the setup expert, not a reason to stop. A host that
|
|
349
|
+
can't be read is a GitHub access problem (step 3).
|
|
350
|
+
- **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
|
|
351
|
+
person whether to use it as it is or to choose another directory.
|
|
352
|
+
|
|
353
|
+
**Find the setup expert soul, `S`.**
|
|
354
|
+
- **From OATS 0.61.0,** the next step `oats onboard` prints names the soul
|
|
355
|
+
that holds `oats.setup`, the workspace's setup expert (`--json`:
|
|
356
|
+
`next.spawn`).
|
|
357
|
+
- **Before 0.61.0,** read `oats souls --dir D --json`: the soul named
|
|
358
|
+
`<workspace>-oats-setup-expert`, else one whose definition declares
|
|
359
|
+
`oats.setup`.
|
|
360
|
+
- **An existing workspace with no such soul:** stop. Show the person the soul
|
|
361
|
+
files from step 5 and say that the workspace's owner adds them by pull
|
|
362
|
+
request to its host repository. Once that is merged, run
|
|
363
|
+
`oats sync --dir D` and look for `S` again.
|
|
364
|
+
|
|
365
|
+
**The clone.** A soul with `work: worktree` needs a clone of its repository
|
|
366
|
+
at `D/<repo name>`. A new workspace already has it (step 5). For an existing
|
|
367
|
+
one, clone the repository that holds `S` with the `git clone` line
|
|
368
|
+
`oats onboard` printed for it, if that line says it is missing.
|
|
369
|
+
|
|
370
|
+
## 7. Hand over to the setup expert
|
|
371
|
+
|
|
372
|
+
**Messaging on this machine first, when the setup expert takes it.** Read
|
|
373
|
+
`oats inspect --soul S --dir D --json`. If its `result.layers.messaging.id`
|
|
374
|
+
is `oats.aweb`, the workspace has messaging, and the setup expert
|
|
375
|
+
can't spawn on this machine until it has messaging too. Set it up now:
|
|
376
|
+
1. **Install `aw`, and the harness's aweb channel** (Claude:
|
|
377
|
+
`claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
|
|
378
|
+
pi: `pi install npm:@awebai/pi`; Codex: nothing). Then:
|
|
379
|
+
|
|
380
|
+
```bash
|
|
381
|
+
cd "D" && oats aweb setup --soul S --install-aw --check-only --json
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
Its `aw.status` must be `ok` or `done`; stop on `failed` and tell the
|
|
385
|
+
person why. Its `defaultTeam.label` is `L`, the setup expert's team.
|
|
386
|
+
2. **The person gets an invite token** from a member of `L`, who runs
|
|
387
|
+
`oats aweb invite --soul <their soul> --label L --json` in their own
|
|
388
|
+
deployment and passes the token to the person privately, never by
|
|
389
|
+
ordinary mail. They also give the aweb service URL `U`. Choose with the
|
|
390
|
+
person a name `A` for this machine's messaging root, such as
|
|
391
|
+
`<workspace>-<their machine>`. This works for a hosted team only: if the
|
|
392
|
+
invite is refused, or the join says the team is not hosted, stop, and
|
|
393
|
+
the workspace's owner decides.
|
|
394
|
+
3. **The person joins in their own terminal,** typing the token at the
|
|
395
|
+
hidden prompt. Give them the line with `D`, `S`, `L`, `A` and `U` filled
|
|
396
|
+
in:
|
|
397
|
+
|
|
398
|
+
```text
|
|
399
|
+
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'
|
|
400
|
+
```
|
|
401
|
+
4. **Check,** and expect `"member": true`:
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
cd "D" && oats aweb setup --soul S --check-only --json
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
The setup expert does the rest of this machine's messaging
|
|
408
|
+
(`/oats-host-delivery`).
|
|
409
|
+
|
|
410
|
+
**Write the hand-over** to `D/.oats-handover.md`. It holds no secret.
|
|
411
|
+
|
|
412
|
+
```markdown
|
|
413
|
+
# Onboarding hand-over from the getting-started skill
|
|
414
|
+
|
|
415
|
+
- Workspace: <workspace> (W), new | existing; deployment directory: D
|
|
416
|
+
- Setup expert: S, harness <harness>
|
|
417
|
+
|
|
418
|
+
## The person's answers
|
|
419
|
+
<step 1's answers, in their words: use case, repositories and where they
|
|
420
|
+
are cloned, knowledge tools, messaging wanted or not>
|
|
421
|
+
|
|
422
|
+
## Done by the getting-started skill
|
|
423
|
+
- Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
|
|
424
|
+
- GitHub: gh logged in over https as <login>; no SSH key or signing set up
|
|
425
|
+
- New workspace only: repository <owner>/<repo> created, first commit pushed
|
|
426
|
+
- Messaging: this machine joined L as root A (aw <version>, <harness>
|
|
427
|
+
channel installed) | not set up (the setup expert has no messaging)
|
|
428
|
+
|
|
429
|
+
## Left to you
|
|
430
|
+
Everything else, starting with /oats-setup-expert.
|
|
147
431
|
```
|
|
148
432
|
|
|
149
|
-
|
|
433
|
+
**Claude and Codex only: trust the deployment directory first,** so the first
|
|
434
|
+
start doesn't stop at the harness's folder-trust question. pi needs
|
|
435
|
+
nothing. Use `codex` for Codex:
|
|
150
436
|
|
|
151
437
|
```bash
|
|
152
|
-
oats
|
|
153
|
-
oats
|
|
438
|
+
oats harness trust --dir D --harness claude --plan
|
|
439
|
+
oats harness trust --dir D --harness claude
|
|
154
440
|
```
|
|
155
441
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
442
|
+
- **If either refuses a file** (on macOS, `~/.claude.json` can carry a mark
|
|
443
|
+
the writer refuses), don't edit the file or its attributes. The person
|
|
444
|
+
runs `cd D && claude` (or `codex`) in their own terminal, accepts the
|
|
445
|
+
harness's folder-trust question and exits.
|
|
446
|
+
- **Then check** that the `harness-trust` item of
|
|
447
|
+
`oats readiness --soul S --dir D --json` passes.
|
|
161
448
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
A soul with `work: worktree | checkout` needs a clone of its repository at
|
|
165
|
-
`<dir>/<repo name>` (or named in `oats-local.yaml` `clones:`).
|
|
449
|
+
**Preview the spawn, read it, then spawn:**
|
|
166
450
|
|
|
167
451
|
```bash
|
|
168
|
-
oats
|
|
169
|
-
oats spawn
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
Unknown dialogs without a marker may be reported completed. Completion closes
|
|
218
|
-
input authority, not a readiness or idle-state promise.
|
|
219
|
-
|
|
220
|
-
Create and spawn only when asked. After the first spawn, the `oats.setup`
|
|
221
|
-
skills carry the rest of the deployment (messaging, more souls, rebuilds); the
|
|
222
|
-
`oats.authoring` package teaches writing capabilities, skills and souls. The
|
|
223
|
-
model in full is `docs/workspaces.md` in the OATS repository.
|
|
224
|
-
|
|
225
|
-
For a retained launch-prompt block after a submitted answer, inspect the existing
|
|
226
|
-
launch event and private frame receipt as described in
|
|
227
|
-
`docs/execution-targets.md#private-unmatched-launch-evidence`. Do not transmit raw
|
|
228
|
-
screen text or treat a saved frame as a new accepted signature. A completed frame is also saved privately. A saved artifact alone
|
|
229
|
-
does not establish completion: verify the final checked launch outcome. Missing
|
|
230
|
-
effort or unsupported footer shapes can block while the pane is active.
|
|
452
|
+
oats spawn S --dir D --task-file D/.oats-handover.md --preview
|
|
453
|
+
oats spawn S --dir D --task-file D/.oats-handover.md
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
- **The preview** shows what the spawn would create. If it reports a
|
|
457
|
+
problem, stop and tell the person what it says.
|
|
458
|
+
- **The spawn** prints the instance's home `H`. Then delete the hand-over
|
|
459
|
+
file: the home has its copy as `TASK.md`.
|
|
460
|
+
- **`E_SPAWN_INCOMPLETE`:** don't spawn again. Run `oats session inspect
|
|
461
|
+
--home H --json` and tell the person what it shows.
|
|
462
|
+
|
|
463
|
+
## 8. Start the Desktop and the TUI, then hand over
|
|
464
|
+
|
|
465
|
+
**The Desktop**, if installed, starts on the new deployment:
|
|
466
|
+
- **macOS:** `open -n -a "OATS Desktop" --args --dir D`. If the Desktop is
|
|
467
|
+
already running, the new launch hands `--dir` to it and exits.
|
|
468
|
+
- **Linux:** the person opens **OATS Desktop** from their app launcher, so it
|
|
469
|
+
starts with their own session's environment, not yours. Then they pick `D`
|
|
470
|
+
in its switcher (listed there from OATS 0.65.0). If it isn't listed, they
|
|
471
|
+
add it with **Add local workspace… → Browse**.
|
|
472
|
+
- **Never start it with an emptied environment** (`env -i`): it then loses
|
|
473
|
+
HOME, and Git loses the person's login.
|
|
474
|
+
|
|
475
|
+
**The TUI**, if they wanted it, runs in a terminal of its own:
|
|
476
|
+
- **macOS:** open a Terminal window with
|
|
477
|
+
`osascript -e 'tell application "Terminal" to do script "oats tui --dir D"'`.
|
|
478
|
+
- **Linux:** give them `oats tui --dir D` for their terminal.
|
|
479
|
+
|
|
480
|
+
**Tell the person how to reach the setup expert**, and that it continues
|
|
481
|
+
from here:
|
|
482
|
+
- the Desktop;
|
|
483
|
+
- `oats tui --dir D`;
|
|
484
|
+
- `oats session attach --home H` in a terminal.
|
|
485
|
+
|
|
486
|
+
It will ask them only what the hand-over leaves open, and it opens a pane in
|
|
487
|
+
its own window when they need to type a secret. You are done.
|
|
488
|
+
|
|
489
|
+
## Never
|
|
490
|
+
|
|
491
|
+
- **Ask for, read, print or store a secret,** or suggest `!` for one. If the
|
|
492
|
+
person pastes one into the conversation anyway, don't repeat it, and tell
|
|
493
|
+
them to rotate it.
|
|
494
|
+
- **Overwrite or re-onboard** a deployment, or push to a repository the
|
|
495
|
+
person did not create in step 5.
|
|
496
|
+
- **The Desktop:** never download it through a browser, skip a verification
|
|
497
|
+
step, strip quarantine without asking, or start it with `env -i`.
|
|
498
|
+
- **Put an absolute path, an account or a credential** in
|
|
499
|
+
`oats-workspace.yaml`, `oats-membership.yaml` or a soul.
|
|
500
|
+
- **Spawn** before `oats onboard` confirmed the host.
|