@awebai/oats 0.22.0

package/skills/oats-config/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: oats-config
+description: >-
+  How to configure OATS deployments with oats-config.yaml and the oats CLI.
+  Use for capability activation, fundamental-layer integrations, agent
+  types, targeting souls, binding settings, injection overrides, config
+  scopes, or adopting a package config template. Triggers: "bind a layer",
+  "target these souls", "agent type", "override an injection", "oats use",
+  "oats init", "configure OATS", "oats-config.yaml", "adopt a config template".
+  Package acquisition/update/remove, locks, restore, and trust mechanics
+  belong to the oats-packages skill.
+---
+
+# Configuring OATS
+
+Config lives in `oats-config.yaml` at laptop (`~`), workspace, and repository
+levels; resolution walks from a soul's repository outward, closest scope wins.
+Prefer the CLI for config edits (`oats init`, `oats use`, `oats type`,
+`oats inject eject`, `oats create --type`); hand-editing is valid but the CLI
+writes the canonical shape.
+
+## Shape
+
+```yaml
+team:                          # deployment boundary (typically workspace scope)
+  name: lfx-engineering
+  # id: lfx-engineering:example.com   # provider team id (aweb <name>:<namespace>)
+agent-types:
+  developers:
+    description: Agents that build the service
+capabilities:
+  layers:                      # exclusive fundamental slots
+    knowledge:
+      capability: oats.okf
+      from: installed            # enforced provenance: installed|owned|path:<dir>
+      # injection-override: .agents/injections/capabilities/oats.okf.md
+    messaging: none            # explicit none suppresses inherited integrations
+    tasks: none
+  additive:                    # non-exclusive packages
+    vendor.review:
+      from: installed
+      agent-types:
+        developers:
+          enabled: true
+          settings: {depth: normal}
+      souls:
+        api-expert:
+          enabled: true
+          settings: {depth: exhaustive}
+```
+
+`global` means every soul governed by the declaring level. Bindings can also
+target **agent types** (families — declared in config via `oats type add`,
+joined via `type: <name>` in each soul.yaml) and individual souls. Matching
+global + agent-type + soul bindings compose. Settings precedence is
+soul > agent-type > global, then closer config. Equal-specificity conflicts
+error. `false`/`enabled: false` is an explicit exclusion and follows the same
+precedence. V1 does not target instances or use tags/selectors.
+
+The closest `team:` declaration marks the deployment boundary: all repos
+under it share one team (identity + `oats status --team` discovery + the
+messaging provider's team). Declare it once at the workspace scope. With
+aweb messaging active, `oats aweb setup` walks the onboarding (aw CLI →
+workspace init → team create/join) and `oats aweb roster` shows the
+cross-machine member directory.
+
+```bash
+oats type add <name> [--description <d>] [--dir <level>]
+oats type list
+```
+
+## Injection overrides
+
+Capability entries and the `oats:` kernel block take an
+`injection-override: <path>|none|default`. Work-mode briefings are packaged
+and NOT overridable; the only work-mode key is `setup:` (env bootstrap run in
+each new worktree). The clean path is ejecting:
+
+```bash
+oats inject eject <capability-id|oats> [--dir <level>]
+```
+
+It copies the packaged default to the conventional
+`.agents/injections/{capabilities/<id>.md, oats-defaults/oats.md}` path and
+sets the override — the file then stops
+tracking package updates, deliberately. Overrides are **not allowed** on
+`from: owned`/`path:` capabilities: the scope owns the package source, so
+edit `.agents/capabilities/owned/<id>/injects/` directly.
+
+## Activate
+
+Acquisition, trust, and package lifecycle → the **oats-packages** skill. The
+config side is activation and targeting of already-acquired capabilities
+(acquired or catalog availability never implies activation):
+
+```bash
+oats use <capability> --global [--dir <level>]
+oats use <capability> --type <agent-type> [--disable]
+oats use <capability> --soul <name> [--settings k=v [k2=v2 ...]]
+```
+
+`oats init` creates config and activates only explicit defaults.
+
+## Package config templates
+
+A distribution package can ship reference **config templates**. Adopting one
+writes it as this scope's ordinary `oats-config.yaml` and records the exact
+template as a commit-safe **adopted base** — provenance, never live inheritance.
+Installing the package alone adopts no template.
+
+```bash
+oats init --package <id|path|git-url> [--config <name>]   # acquire + adopt one template
+oats config diff                                          # report drift; never merges
+oats config sync [--accept <regionId>=local|package]      # apply upstream; keep local edits
+oats config sync --reset --yes                            # discard local; take the template verbatim
+oats config adopt <package> [--config <name>]             # switch to a different base
+```
+
+The config is yours: retarget, disable, re-set, or replace anything the template
+enabled; nested repository configs override it per the normal cascade; package
+updates never rewrite it or the adopted base. `oats config sync` preserves your
+untouched bytes, comments, and formatting, and a region changed both locally and
+upstream is a conflict you must resolve explicitly. See docs/packages.md for the
+full adoption and sync UX.
+
+## Fundamental layers
+
+Knowledge, messaging, and tasks are formal exclusive contracts. A package
+manifest declaring one `layer` is an integration. Two active integrations for
+the same layer error; a closer scope's entry (or `none`) overrides outer ones.
+
+| Layer | Bundled | Requirement |
+|---|---|---|
+| knowledge | `oats.okf` | none |
+| messaging | `oats.aweb` | `aw` CLI |
+| tasks | none by default; `oats.jira` or `oats.linear` available | provider-specific |
+
+Activation uses the manifest-declared layer — `oats use` writes the entry
+under `capabilities.layers.<layer>` automatically:
+
+```bash
+oats use <capability> --global|--type <agent-type>|--soul <name>
+oats use none --layer <layer>
+```
+
+`capabilities` is the only activation map: fundamental integrations under
+`capabilities.layers.<layer>` (entry or explicit `none`), everything else
+under `capabilities.additive`.
+
+Rare hand-edited keys: `skill-overrides:` (names the winning source on
+duplicate skill names), the top-level `agents-md-injection:` map (extra
+unconditional instruction blocks), `templates:` (named init seeds).
+
+## Verify
+
+```bash
+oats doctor [context] [--soul <name>] [--json]
+```
+
+Doctor shows config chain, acquired/active packages, layer selection, target
+and settings provenance, requirements, trust, skill sources, instruction
+blocks, and — with `--soul` — the final composed AGENTS.md.

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

@@ -0,0 +1,159 @@
+---
+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".
+---
+
+# 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.
+
+## 1. Install
+
+```bash
+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:
+
+- laptop (`~/oats-config.yaml`): defaults for governed workspaces;
+- workspace: shared multi-repo policy; or
+- repository: repo-specific policy.
+
+Ask which scope the user intends. `oats init` detects home as laptop, a `.git`
+root as repository, and another directory as workspace.
+
+## 3. Present fundamental-layer defaults
+
+Knowledge, messaging, and tasks remain formal, exclusive slots. Their
+implementations are capability packages called integrations.
+
+| 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 |
+
+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.
+
+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
+```
+
+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.
+
+`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.
+
+## 4. Decide shared capability targets
+
+Ask whether reusable non-layer capabilities should apply to:
+
+- every soul governed by this config (`global`);
+- an explicit agent type (family — souls opt in via `type:` in soul.yaml); or
+- one soul.
+
+Do not invent agent types before the souls are known. Example after agents exist:
+
+```yaml
+agent-types:
+  developers:
+    description: Agents that build the product
+capabilities:
+  additive:
+    vendor.code-review:
+      from: installed
+      agent-types:
+        developers: true
+```
+
+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:
+
+```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
+```
+
+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.
+
+## 5. Verify
+
+```bash
+oats doctor /path/to/context --json
+```
+
+After creating a soul, use `--soul <name>` to inspect its exact capabilities,
+skills, trust, and final generated `AGENTS.md` before spawn.
+
+## 6. Create and spawn the first specialist
+
+```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 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`.

package/skills/oats-packages/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: oats-packages
+description: >-
+  How to acquire, lock, restore, trust, update, remove, and migrate OATS
+  distribution packages with the oats CLI. Use for package sources (git/local/
+  official catalog), oats-lock.json v2, all-or-nothing scope migration, exact restore,
+  per-capability executable trust, runtime dependency closures, or package
+  doctor failures. Triggers: "install a package", "oats install", "oats list",
+  "oats update", "oats remove", "oats migrate", "oats trust", "lockfileVersion",
+  "integrity drift", "package won't restore".
+---
+
+# OATS distribution packages
+
+A **package** is the install/update/review unit: one git repo (or local dir)
+with an `oats-package.json` exporting one or more **capabilities** (the
+activation unit) and optional config templates. Acquiring a package activates
+NOTHING — activation stays in `oats-config.yaml` (see the oats-config skill).
+Never hand-edit `oats-lock.json` or the stores; every operation below is a CLI
+command, and all of them take `--json` (one stdout envelope, stable error
+codes) and `--dir <scope>`.
+
+## Sources
+
+```
+oats install git:github.com/org/repo@v1.0.0    # git shorthand (ref optional; resolved once, exact-locked)
+oats install https://host/org/repo.git@v1.0.0  # raw HTTPS/SSH git URL
+oats install ../my-package                     # local path (dev escape hatch)
+oats install <catalog-id>                      # official catalog short id (identity only — no auto-trust)
+```
+
+### Which directory in the repo is the package?
+
+A git repository CONTAINS a package; it is not one. The package root is the
+directory carrying `oats-package.json`, and a git source selects it with a
+`#<path>` fragment after any `@ref`:
+
+```
+oats install git:github.com/org/repo@v1.0.0            # → repo's oats-package/   (the DEFAULT)
+oats install git:github.com/org/repo@v1.0.0#dist/oats   # → repo's dist/oats/
+oats install git:github.com/org/repo@v1.0.0#.          # → the repository ROOT
+```
+
+- **Omit it and you get `oats-package/`.** Every official example, scaffold and
+  convention uses `oats-package/` — never a generic `package/`. A repo whose
+  manifest sits at the root needs `#.`; the error message says so.
+- **Only the selected subtree is installed and hashed.** Repository docs, CI
+  config, owner souls and sibling packages never become installed bytes and
+  never affect `integrity` — so editing them cannot invalidate approvals, and
+  editing the payload (including a nested capability-agent soul) always does.
+- **One repo can ship several packages** at different paths; install each by
+  its own source. Two contained roots claiming the SAME package identity still
+  fail with `duplicate-package-identity`.
+- **Catalog ids take no fragment** — the catalog entry carries `path` itself.
+- **Local paths take no fragment either**: `oats install /repo/custom-root`
+  treats that exact directory as the package root whatever it is named. There
+  is no `oats-package` default for local sources.
+
+The lock records the selected root in its own `path` field, in canonical form
+(`.` for a root selection). A bare `oats install` restores the locked
+source + commit + **path** + integrity even if upstream moved the directory or
+the catalog repointed; only `oats update <package>` may adopt a new path, and it
+reports the move. Attempting to move it with a plain `oats install` is refused
+with `integrity-drift`.
+
+Local capability development is untouched by all of this:
+`.agents/capabilities/owned/<id>` (`from: owned`) and `from: path:<dir>` are
+not package sources and are never routed through package paths.
+
+Installing a package MATERIALIZES each capability it exports into
+`<scope>/.agents/capabilities/installed/<id>/` (gitignored). There is no
+persistent package store. Dependencies declared in `oats-package.json` must be
+pinnable (official selector, tag/commit, or path). The whole closure is
+exact-locked in the scope's `oats-lock.json` (`lockfileVersion: 2`), which
+records two maps: `packages` (source, exact commit, selected path, payload
+integrity, dependencies) and `capabilities` (each artifact's version, provider
+package, path, integrity, trust).
+
+## Everyday operations
+
+```
+oats install                    # bare: EXACT restore of this chain's locks (never advances refs)
+oats list [--json]              # packages, exported capabilities, scopes, trust state
+oats update <package>           # transactional: temp fetch, closure validation, diff,
+                               # artifact+lock replaced together; approvals of every
+                               # CHANGED-integrity package are invalidated (unchanged
+                               # packages in the closure keep theirs)
+oats remove <package>           # refuses while config or dependent packages reference it
+```
+
+## Trust
+
+Executable surfaces (commands/hooks) are blocked until approved at each
+capability artifact's EXACT integrity:
+
+```
+oats trust <capability>                     # approve only that capability
+oats trust <package> --all-capabilities     # explicit bulk; prints the full executable surface first
+```
+
+Any artifact integrity change (update, drift) resets that capability's trust —
+re-review, then re-trust. Skill/instruction/config-only capabilities need lock
+integrity but no approval. Official-catalog identity is NOT executable trust.
+
+## Runtime dependencies
+
+A capability may check in `package.json` + `package-lock.json`; OATS materializes
+it with `npm ci --omit=dev --omit=peer --ignore-scripts` — production tree only,
+no lifecycle scripts. The package payload hash EXCLUDES `node_modules`. The
+materialized `node_modules` is instead part of that capability's own artifact
+integrity, so tampering with materialized deps resets the capability's trust
+just like source drift, and restore re-verifies it. Closures must be
+platform-invariant. Host peer APIs are reached only through the supported
+runtime boundary, never auto-installed.
+
+## Migration from v1 locks
+
+```
+oats migrate --dry-run          # plan: which v1 capability locks map to packages
+oats migrate                    # convert this scope to revised v2 — all-or-nothing
+```
+
+`oats migrate` is all-or-nothing per scope. It converts a scope to the revised v2
+lock only when EVERY entry maps to a package. If any entry cannot be mapped yet
+(a marketplace id the catalog does not resolve, an unknown source), the whole
+scope stays byte-identical v1 and keeps working — re-run when it can map. A
+successful run writes a fresh v2 lock for the scope. There is NO residue
+container: a converted lock never carries leftover v1 entries. Approvals never
+carry over — re-trust after migrating.
+
+### Upgrading a 0.18 deployment (bundled official capabilities → packages)
+
+```
+oats migrate --official --recursive --dry-run --dir <team-root>   # plan every scope
+oats migrate --official --recursive --dir <team-root>             # apply, scope by scope
+```
+
+Guided mode for existing users. It plans every visible lock-owning scope first
+(ancestor chain incl. outer/laptop locks, team boundary, pruned descendants;
+path order, ancestors first), then applies each scope transactionally.
+
+- Which package supplies a legacy capability is CATALOG data: identity by
+  default, plus aliases (`oats.review` → package `oats.dev`). Never a hardcoded
+  URL or tag, and no ref is guessed from the v1 capability version.
+- Config files are never rewritten — exported ids are unchanged, so activation,
+  layers, targets, settings and exclusions stay valid.
+- No mapping yet at a scope → that scope is HELD and left byte-identical v1
+  (nonzero exit, `--dry-run` included); legacy capabilities keep working. A
+  converting scope moves whole to revised v2 — there is no residue container, so
+  a converted lock never carries leftover v1 entries.
+- `git:`/`path:`/unknown entries are never acquired by guided mode. A scope
+  containing only those entries is skipped with their IDs under `retained`; a
+  scope mixing them with official capabilities is blocked whole and stays v1.
+  Plain `oats migrate` can convert custom sources only when every entry maps.
+- After it runs: `oats trust <capability> --dir <scope>` for each executable
+  surface it names (approvals never transfer), then `oats install --dir <scope>`
+  — already-installed host requirements verify, nothing is reinstalled.
+- `--json` emits one envelope; an aggregate failure is `ok:false` with
+  `error.code = E_MIGRATE_FAILED` and the complete per-scope report (including
+  the scopes that DID migrate) under `error.details`.
+
+`oats doctor` detects the upgradeable state and prints the exact command
+(`officialMigration` in `--json`), or says migration is not available yet while
+confirming the legacy capabilities remain supported.
+
+## Troubleshooting
+
+`oats doctor [dir] [--json]` distinguishes: missing locked package (run
+`oats install`), integrity drift (reacquire/update explicitly — approvals are
+already invalid), a capability whose `.oats-installation.json` disagrees with
+the lock, untrusted executable surface (`oats trust <capability>`), and a legacy
+v1 lock pending migration (`legacyLockFiles[]` plus `officialMigration`
+readiness). A refused lock — including the superseded transitional v2 shape —
+is reported as the single `lockError` diagnosis and is never partially
+interpreted.
+
+Source of truth beyond this skill: `oats --help` output,
+`docs/oats-package.schema.json`, `docs/oats-lock.schema.json`, and
+`docs/design/package-engine-contract.md` (+ `package-runtime-api.md`) in the
+framework repo; `docs/capabilities.md` for the user-level walkthrough.

package/skills/oats-support/SKILL.md

@@ -0,0 +1,79 @@
+---
+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
+  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
+  the OATS experts", "why does OATS do X", "is this an OATS bug", "OATS
+  architecture question", "who maintains this framework".
+---
+
+# OATS support — delegate to the framework's expert
+
+The OATS framework repo carries its own agents. The **oats-expert** soul holds
+the framework's architecture record, decisions, and roadmap — knowledge no
+generic session has. For deep questions, instantiate it and let the user
+talk to it directly. Do not guess at framework internals yourself.
+
+## 1. Find the OATS framework repo locally
+
+Check in this order. Verify a hit by remote URL — it must point at
+`awebai/oats`:
+
+```bash
+# a) an existing pi install from a local path IS the repo
+python3 -c "import json,os; [print(p if isinstance(p,str) else p.get('source','')) for p in json.load(open(os.path.expanduser('~/.pi/agent/settings.json'))).get('packages',[])]"
+# b) common spots
+ls -d ~/oats ~/oats-framework 2>/dev/null
+# c) verify any candidate
+git -C <candidate> remote get-url origin   # expect awebai/oats
+```
+
+**Do not use a pi-managed git clone** (`~/.pi/agent/git/...`) as the home
+for agent instantiation. `pi update` resets and cleans those clones, which
+would wipe the souls' accumulated knowledge.
+
+## 2. If not found, ask the user where to clone
+
+Never pick a location silently. Suggest `~/oats` or a sibling of
+their workspace, then:
+
+```bash
+git clone https://github.com/awebai/oats <chosen-path>
+```
+
+## 3. Instantiate the oats-expert soul
+
+Spawn from the repo's own agents root (`--dir` targets it regardless of
+where your session runs):
+
+```bash
+oats spawn oats-expert --dir <repo> --purpose <short-slug> \
+  --task "<the user question, plus their workspace path and any config context>"
+```
+
+Do NOT pass `--parent` here: `--dir <repo>` targets a DIFFERENT deployment's
+agents root, and lineage is deployment-local — your instance is not
+discoverable (or renderable) in the target's hierarchy, so the spawn is
+correctly operator-origin/top-level there. Pass `--parent "$OATS_INSTANCE"`
+only when spawning within your own deployment.
+
+Include in the task briefing: the user's actual question, their workspace
+path, and relevant `oats doctor` output. The expert reads its soul knowledge
+and answers with citations.
+
+## 4. Hand off
+
+Tell the user the instance is running and how to reach it:
+`tmux attach -t pi-agents`, then pick the window. Report the window name.
+Retirement is the user's call (or yours if they delegate it) — retiring
+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
+architecture, design rationale, roadmap, and anything you would otherwise
+guess about.