@awebai/oats 0.25.9 → 0.26.0

package/skills/oats-getting-started/SKILL.md

@@ -1,18 +1,27 @@
 ---
 name: oats-getting-started
 description: >-
-  How to set up OATS (Open Agent Team Specification) in a workspace from scratch —
-  install the CLI/pi adapter, choose fundamental-layer integrations and shared
-  capabilities, create oats-config.yaml, and create/spawn the first specialized
-  agent. Use for "get started with OATS", "set up/install/adopt OATS", "create
-  my first agent", or "how do I start using OATS".
+  How to start with OATS (Open Agent Team Specification) from nothing — install
+  the CLI and pi adapter, decide which repository hosts the organisation's
+  workspace, write the three shared declarations (oats-workspace.yaml,
+  oats-membership.yaml, souls/<name>/soul.yaml), realize the workspace on this
+  machine with `oats onboard` and spawn the first soul. Use
+  for "get started with OATS", "set up/install/adopt OATS", "create my first
+  agent", or "how do I start using OATS".
 ---
 
 # Getting started with OATS
 
-OATS gives a workspace durable specialized **souls**, disposable **instances**,
-and targetable **capability packages**. Do not run setup blindly: present each
-default and ask the user before writing config or spawning agents.
+OATS gives an organisation durable **souls** (role definitions kept in Git),
+disposable **instances** (a soul at work, in its own home) and **capabilities**
+(skills, instructions and hooks copied whole into each instance at spawn). One
+**workspace** per organisation lists the repositories that belong to it. Do not
+run setup blindly: explain each decision and ask before writing a file,
+declaring a package or spawning.
+
+This skill is the one pre-workspace bootstrap. Once the first instance exists,
+the `oats.setup` capability's skills (and the `oats-operator-expert` soul, where
+the workspace offers it) carry the rest; spawned instances get their own skills.
 
 ## 1. Install
 
@@ -21,139 +30,125 @@ npm install -g @awebai/oats
 pi install npm:@awebai/oats-pi
 ```
 
-The CLI/kernel is runtime-neutral. The pi adapter supplies only minimal runtime
-glue. Install matching versions and upgrade both packages together. Exact pi
-isolation needs the kernel's launch flags and the changed adapter's
-instance-only discovery. Reload pi after installing or upgrading the adapter.
-
-This skill is the one pre-workspace ambient bootstrap. Spawned instances
-receive exact local skills.
-
-## 2. Choose scope
-
-`oats-config.yaml` can live at:
+Install matching versions and upgrade both together (`oats update`). Reload pi
+after installing or upgrading the adapter. Check with `oats version`.
 
-- laptop (`~/oats-config.yaml`): defaults for governed workspaces;
-- workspace: shared multi-repo policy; or
-- repository: repo-specific policy.
+## 2. Decide where the workspace is hosted — first
 
-Ask which scope the user intends. `oats init` detects home as laptop, a `.git`
-root as repository, and another directory as workspace.
+The workspace file names every member repository, so whoever can read it sees
+the member list. Ask:
 
-## 3. Present fundamental-layer defaults
+- **Does the organisation already have an OATS workspace?** Then skip to step 4
+  with its repository reference.
+- **Is any repository that will join private?** Then the workspace file lives
+  in a private repository that is not itself a public member (a dedicated
+  `<org>/workspace` repository is the honest shape). Otherwise any member,
+  often a dedicated `agents` repository, can host it.
 
-Knowledge, messaging, and tasks remain formal, exclusive slots. Their
-implementations are capability packages called integrations.
+Every member runs its capabilities' hooks on every operator's machine, gated
+only by membership. In a mixed public/private organisation keep executable
+capabilities in packages or private members, and only souls in public members.
 
-| Layer | Default | Gives | Needs |
-|---|---|---|---|
-| knowledge | `oats.okf` | soul OKF bundle, instance memory, harvest | nothing |
-| messaging | `oats.aweb` | instance identity and team messaging | `aw` CLI |
-| tasks | none | choose Jira, Linear, or another integration | provider-specific |
+## 3. Write the shared declarations (in Git, reviewed like code)
 
-Present these defaults to the user and ask before creating config. Common
-choices: disable messaging for a solo repo; choose `oats.linear`/`oats.jira` for
-tasks; use `--raw` for all layers off. Official integrations are acquired like
-any other package; `oats init` acquires the selected ones into this scope's
-installed/ store (locked). Executable surfaces (like OKF's harvest) need
-`oats trust` before use — acquisition never grants executable trust. In an
-interactive terminal with no layer flags, bare `oats init` prompts per layer;
-through an agent, always pass explicit flags.
+In the host repository, `oats-workspace.yaml`:
 
-If the user keeps aweb messaging: declare the team in the deployment scope's
-config (`team:` with a name; see the oats-config skill), then run
-`oats aweb setup` — it checks the `aw` CLI, the aweb workspace at the team
-scope, and team membership, and prints exactly the one next step each time
-(including first-ever aweb account creation via `aw init`). Users who have
-never used aweb just follow its prompts; nothing else is required.
-
-Also ask whether they want normal mouse/trackpad scrolling in tmux agent
-windows. Pass the answer explicitly when commands run through an agent, because
-that shell is non-interactive:
-
-```bash
-oats init --tmux-mouse
-oats init --messaging none --tmux-mouse
-oats init --raw --knowledge oats.okf --no-tmux-mouse
-oats init --tasks oats.linear --tmux-mouse
+```yaml
+schemaVersion: 2
+name: acme
+members:
+  - git:github.com/acme/agents          # the host is a member too
+  - git:github.com/acme/platform
+packages:
+  oats.framework: v1.1.3                # bare versions resolve through the official catalog
+  oats.okf: v2.1.5
+teams:
+  global: { description: Org-wide souls }
+defaults:
+  capabilities: { oats.core: { from: package } }
+  knowledge: { oats.okf: { from: package } }
 ```
 
-The scrolling option appends `set -g mouse on` to the existing `~/.tmux.conf`
-or XDG tmux config and reloads a running server; it never changes terminal
-keyboard mappings. An interactive terminal prompts when neither tmux flag is
-provided.
+Take the current package versions from the official catalog
+(`package-catalog.json` in the OATS repository); ask which slots the user wants
+filled (knowledge, messaging, tasks) instead of copying the example. No absolute
+paths, accounts or team ids go in this file.
 
-`init` activates only packages explicitly represented by the layer choices;
-it acquires the chosen layer capabilities into this scope's installed/ store, and does not activate anything else.
+Declaring a package in `packages:` is the decision to trust it: its commands
+and hooks run on every machine that spawns a soul using it. Show the user what
+each package runs (its capability manifests' `commands` and `hooks`) before
+adding its pin.
 
-## 4. Decide shared capability targets
+In **every** member repository, including the host, `oats-membership.yaml`:
 
-Ask whether reusable non-layer capabilities should apply to:
+```yaml
+schemaVersion: 2
+workspace: git:github.com/acme/agents
+team: global
+```
 
-- every soul governed by this config (`global`);
-- an explicit agent type (family — souls opt in via `type:` in soul.yaml); or
-- one soul.
+Membership is reciprocal: the workspace lists the repository and the
+repository names the workspace back. Neither alone is membership.
 
-Do not invent agent types before the souls are known. Example after agents exist:
+A soul lives at `souls/<name>/` in a member repository: `soul.yaml`,
+`AGENTS.md` (its canonical instructions) and `CLAUDE.md -> AGENTS.md`.
 
 ```yaml
-agent-types:
-  developers:
-    description: Agents that build the product
-capabilities:
-  additive:
-    vendor.code-review:
-      from: installed
-      agent-types:
-        developers: true
+schemaVersion: 2
+name: backend-expert
+description: Owns backend architecture and implementation.
+work: worktree            # worktree | checkout | directory | workspace
 ```
 
-External packages must be acquired/locked before activation; executable
-commands, hooks, and launch-environment authority need explicit trust. The
-minimal first-time sequence — this skill is the only one available before the
-first spawn, so it carries the bootstrap commands directly:
+A soul says where each extra capability comes from (`{ from: package }`,
+`{ from: here }` or `{ from: <member repo key> }`), never a version. A soul
+whose knowledge slot is filled by `oats.okf` also needs `okf.json` beside
+`soul.yaml`; `docs/knowledge.md` in the OATS repository shows its shape.
+Commit and push; OATS reads members over their remotes, not from local clones.
+
+## 4. Realize the workspace on this machine
+
+Ask the user **which directory** holds this machine's deployment — usually the
+folder that already holds their clones. There is no required name.
 
 ```bash
-oats install <git-url|path> --dir /path/to/workspace   # acquire + exact-lock; inactive
-oats trust vendor.code-review --dir /path/to/workspace # approve executable surfaces
-oats use vendor.code-review --type developers --dir /path/to/workspace
+oats onboard <dir> --workspace git:github.com/acme/agents
 ```
 
-Acquisition never means activation and never silently updates a lock. Never
-hand-edit `oats-lock.json` or installed stores — the CLI owns them. Anything
-beyond this bootstrap (updates, removal, lock restore/migration,
-requirements, package diagnosis) belongs to the `oats-packages` skill — part
-of the kernel baseline inside spawned instances; in this pre-workspace
-context use docs/packages.md and the top-level `oats help` output.
+It writes `<dir>/oats-local.yaml` (the one per-machine file, never committed)
+and `agents/`, confirms each member, resolves and locks the packages, and prints
+the next steps. Fix any member that is not confirmed (`oats workspace status` says why) before going on.
 
-## 5. Verify
+Host-owned settings a package asks for (absolute paths, state directories) go
+under `settings:` in `oats-local.yaml`, never in the workspace file. For
+`oats.okf` that is `bindings-file` and `state-dir`; its own skill explains the
+bindings file.
+
+## 5. Sync after any change
 
 ```bash
-oats doctor /path/to/context --json
+oats sync --dir <dir>          # resolve every pin to a commit, fetch, verify integrity, write oats-lock.json
 ```
 
-After creating a soul, use `--soul <name>` to inspect its exact capabilities,
-skills, trust, and final generated `AGENTS.md` before spawn.
+Run it after any change to the workspace file. It asks nothing; the lock pins
+each package to an exact commit and integrity, and content that no longer
+matches is refused (`E_PACKAGE_INTEGRITY`). Member capabilities come from
+membership.
+
+## 6. Spawn the first soul
 
-## 6. Create and spawn the first specialist
+A soul with `work: worktree | checkout` needs a clone of its repository at
+`<dir>/<repo name>` (or named in `oats-local.yaml` `clones:`).
 
 ```bash
-mkdir -p agents
-oats create backend-expert --description "Owns backend architecture and implementation" --work worktree
-# Optional: --type <agent-type> joins a declared family so typed config targets apply.
-# Edit agents/backend-expert/soul/AGENTS.md: durable role, boundaries, workflow.
-oats doctor . --soul backend-expert
+oats souls --dir <dir>                                  # what the workspace offers, with origin and team
+oats spawn backend-expert --preview                     # modules, commits, merged provider settings — nothing created
 oats spawn backend-expert --task "First concrete task"
 oats status
 ```
 
-The committed soul stays config-independent. Spawn generates instance
-instructions and materializes only kernel + soul + active capability skills in
-that instance. Do not put deployment-specific package prose into the soul.
-
-Create/spawn only when asked. Suggest a team shape, then let the user decide.
-For operations load the `oats` skill; for local deployment policy and
-config-template adoption use `oats-config`; package acquisition/locks/trust beyond the
-bootstrap above belong to `oats-packages` (kernel baseline inside spawned
-instances); for custom layer/package work use `integration-authoring`; for
-deep architecture or bugs use `oats-support`.
+Create and spawn only when asked. After the first spawn, load the `oats.setup`
+skills for the rest of the deployment (messaging, more souls, rebuilds). For
+custom capabilities and integrations, use `integration-authoring`; for deep
+architecture questions or bugs, use `oats-support`. The model in full is
+`docs/workspaces.md` in the OATS repository.

package/skills/oats-support/SKILL.md

@@ -2,7 +2,7 @@
 name: oats-support
 description: >-
   Route deep OATS framework questions to the framework's own expert agent.
-  Use when a user asks how OATS works beyond the basics in the oats skill, why
+  Use when a user asks how OATS works beyond the basics in the oats-operate skill, why
   the framework behaves a certain way, wants framework changes or roadmap
   context, or hits framework bugs — the answer is to instantiate the
   oats-expert soul from the OATS framework repo and delegate. Triggers: "ask
@@ -74,6 +74,6 @@ harvests the instance's notes back into the expert's soul.
 ## Scope note
 
 Quick questions (home layout, roster, lifecycle, doctor) are already
-answered by the **oats** skill — use that first. Delegate to the expert for
+answered by the **oats-operate** skill (the `oats.core` capability) — use that first. Delegate to the expert for
 architecture, design rationale, roadmap, and anything you would otherwise
 guess about.

package/skills/soul-craft/SKILL.md

@@ -28,7 +28,7 @@ real CLAUDE.md file diverging from AGENTS.md, that's a defect: merge and relink)
 |---|---|---|
 | **AGENTS.md** | always | Role, boundaries, the default workflow, memory pointers — only what applies to *every* session |
 | **skills/** | on demand (description match) | Domain workflows, repeatable procedures ("how") — see `skill-craft` |
-| **knowledge/** | on demand (index-first) | Facts, decisions, lessons ("what/why") — format per the knowledge integration (default okf) |
+| **knowledge/** | on demand (index-first) | Facts, decisions, lessons ("what/why") — format per the knowledge capability (default okf) |
 
 The test for every AGENTS.md line: **"would removing this cause mistakes in
 most sessions?"** No → move it to a skill or a knowledge concept, or cut it.
@@ -53,7 +53,7 @@ Structure that works (keep the whole thing short — a screen or two):
    "run the tests").
 4. **Memory pointers.** Where its knowledge and state live (knowledge base
    index, STATE.md discipline). Point, don't duplicate — the protocol lives
-   with your knowledge integration (default okf: the memory-harvest skill).
+   with your knowledge capability (default okf: the memory-harvest skill).
 5. **Escalation.** When to stop and ask the human or coordinator: the
    human-gate triggers (security, authz, migrations, contract breaks),
    plus "report to your spawner, don't self-fix" for infrastructure faults.
@@ -73,10 +73,17 @@ Style rules (from the agents.md standard + field experience):
 
 ## soul.yaml
 
-Keep honest: `repo` (what it works on), `work` (worktree for builders,
-checkout for reviewers/coordinators), `runtime`, `model` (only pin when the
-role needs a specific one — reviewers on a different model than authors),
-`description` (one line; shows in rosters and pickers).
+Keep honest: `description` (one line; shows in rosters and pickers), `work`
+(`worktree` for builders, `checkout` for reviewers/coordinators, `directory`
+or `workspace` where the role needs them), and the capabilities the role
+actually uses (`capabilities: { <cap>: { from: package | here | <repo key> } }`,
+plus `knowledge` / `messaging` / `tasks` slots; `none` empties one). The
+soul lives in its member repository, which is also what it works on.
+
+Runtime, model and permission bypass are not soul fields: they are chosen at
+spawn (`--runtime`, `--model`, `--yolo`) or by a host's named launch
+configuration, so the same soul runs on any harness a host provides. Check a
+soul with `oats spawn <soul> --preview` before committing it.
 
 ## Maintaining a soul
 

package/bin/oats-pi-sdk-host.mjs

@@ -1,17 +0,0 @@
-#!/usr/bin/env node
-/** Explicit kernel-owned print adapter; not an alternate interpretation of Pi CLI. */
-import { recordCapturedPiExit, runCapturedPiSdkHost } from "../lib/captured-pi-host.mjs";
-
-try {
-  const argv = process.argv.slice(2);
-  process.exitCode = argv[0] === "--oats-pi-record-exit" ? recordCapturedPiExit(argv) : await runCapturedPiSdkHost(argv);
-} catch (error) {
-  // Never echo arbitrary SDK/helper/provider error objects: those can contain
-  // native auth material. Native print mode owns its ordinary safe diagnostics.
-  const known = new Set(["E_PI_HOST_ARGS", "E_PI_HOST_SELECTION", "E_PI_HOST_MODEL", "E_PI_HOST_TASK", "E_PI_HOST_SDK", "E_PI_HOST_CURRICULUM", "E_PI_HOST_HISTORY", "E_PI_HOST_CUSTODY", "E_PI_HOST_RECORD_UNAVAILABLE", "E_PI_HOST_OUTCOME"]);
-  const code = known.has(error?.code) ? error.code : "E_PI_HOST_FAILED";
-  console.error(process.argv[2] === "--oats-pi-record-exit"
-    ? `${code}: captured Pi process observation refused or failed; completion evidence remains held`
-    : `${code}: captured Pi host refused or failed; use the selected harness's native setup for model/auth prerequisites`);
-  process.exitCode = 1;
-}