@awebai/oats 0.25.9 → 0.27.0

package/capabilities/oats-authoring/oats-package.json

@@ -1,9 +1,9 @@
 {
   "package": "oats.authoring",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Official additive OATS guidance for capability, skill, and soul authoring.",
   "compatibility": {
-    "oats": ">=0.19.0"
+    "oats": ">=0.25.0"
   },
   "capabilities": [
     "."

package/capabilities/oats-authoring/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.authoring",
-  "version": "1.0.0",
-  "compatibility": { "oats": ">=0.19.0" },
+  "version": "1.0.3",
+  "compatibility": { "oats": ">=0.25.0" },
   "description": "Additive framework-authoring guidance for capability packages, agent skills, and souls.",
   "requires": [],
   "skills": [

package/capabilities/oats-authoring/skills/integration-authoring/SKILL.md

@@ -3,7 +3,7 @@ name: integration-authoring
 description: >-
   Route custom OATS capability-package and integration work to the framework's
   integrations expert. Use when building, adapting, or debugging a reusable
-  capability, new task/messaging/knowledge integration, oats.json manifest,
+  capability, new tasks/messaging/knowledge core capability, oats.json manifest,
   lifecycle hook, or operational command—not merely activating an existing
   package. Triggers: "custom integration", "capability package", "integrate
   our tracker", "new messaging integration", "write an oats.json".
@@ -12,52 +12,73 @@ description: >-
 # Capability and integration authoring — delegate
 
 A capability package may ship skills, instance instructions, requirements,
-namespaced commands, and approved hooks. An integration is the constrained
-subtype implementing exactly one fundamental layer. Building either requires
+namespaced commands, and declared hooks. A core capability is the constrained
+kind that fills one of the knowledge, messaging or tasks positions (its
+manifest's `layer` field names which). Building either requires
 manifest, security, targeting-boundary, collision, and probe discipline; use
 the framework's **integrations-expert** soul rather than improvising.
 
-If the user only wants an existing package, use:
+If the user only wants an existing package, declare it and give it to souls;
+no build is needed:
 
-```bash
-oats install <source>            # external acquisition + exact lock; inactive
-oats trust <id>                  # only if commands/hooks exist
-oats use <id> --global|--type <t>|--soul <s>
+```yaml
+# oats-workspace.yaml (host repository): declaring the package is the trust decision
+packages:
+  vendor.review: git:github.com/vendor/review@v1.0.0
+# a soul's soul.yaml, or the workspace defaults: a capability the package exports
+# (a package may export several; the soul names each one it wants)
+capabilities:
+  vendor.review: { from: package }
 ```
 
+Then run `oats sync` (fetch, verify integrity, lock). The oats.setup
+capability's **oats-package-pins** skill has the procedure.
+
 ## 1. Verify the expert is available
 
-Run `oats status` and confirm the deployment can resolve the `integrations-expert` soul. If it is absent, ask the human which OATS framework deployment owns reusable package work; never locate or import private kernel files.
+Run `oats souls` in the deployment and confirm it resolves the
+`integrations-expert` soul (a member repository or package provides it). If it
+is absent, ask the human which OATS deployment owns reusable package work;
+never locate or import private kernel files.
+
+## 2. Spawn the expert against the package's repository
 
-## 2. Spawn the expert against the user's repository
+The package lives in its own repository. Make that repository a member of the
+workspace (or use the member that already holds it), then spawn the expert on
+it:
 
 ```bash
-oats spawn integrations-expert \
+oats spawn integrations-expert --preview \
   --purpose <package-slug> \
-  --repo <users-workspace-or-repo> \
-  --work checkout \
-  --task '<capability intent; layer if any; skills/instructions/commands/hooks; external tools; desired global/type/soul targets; distribution path>'
+  --repo <member clone of the package repository> \
+  --work worktree \
+  --task '<capability intent; layer if any; skills/instructions/commands/hooks; external tools; which souls should get it; distribution path>'
+# review the preview, then run the same command without --preview
 ```
 
-Use `--relation child --relative-to <your-instance>` only when the documented workflow makes the expert your child; otherwise leave the operator-origin spawn unrelated. The work tree is the user's repository, where a config-owned local package belongs under `.agents/capabilities/owned/<name>/`. A framework contribution belongs under `capabilities/<name>/` in the framework worktree; an independently published package uses its own repository.
+Use `--relation child --relative-to <your-instance>` only when the documented
+workflow makes the expert your child; otherwise leave the spawn unrelated. A
+package is distributed from its own repository as `oats-package/` with a
+version tag; a framework contribution belongs in the framework's repository.
 
 ## 3. Brief the design boundary
 
 Tell the expert:
 
 - whether it is additive or implements exactly one of knowledge/messaging/tasks;
-- external requirements and executable surfaces;
+- external requirements and executable surfaces (commands, hooks);
 - intended distribution and version/compatibility;
-- desired config-owned targets and settings; and
-- expected skill/instruction/scaffold collisions.
+- which souls or workspace defaults should receive it, and its settings; and
+- expected skill/instruction collisions (a duplicate skill name fails the spawn).
 
-Targets never belong in the manifest. The expert must test exact pi/Claude
-instance materialization, generated instructions, lock/trust behavior,
-command gating, deterministic hooks, and scaffold ownership as applicable.
+Which souls get a capability is declared by the workspace (`defaults`) and the
+souls (`soul.yaml` `capabilities`), never in the manifest. The expert must
+test exact pi/Claude/Codex instance materialization, generated instructions,
+command gating, deterministic hooks, and the lock's integrity check as
+applicable.
 
 ## 4. Hand off
 
-Report the tmux window (`tmux attach -t pi-agents`). The expert follows its
-package/integration craft, runs a scaffold-only probe, and leaves acquisition
-and activation commands for the user. Its durable lessons harvest back into
-its soul.
+Report the new instance (`oats status`). The expert follows its
+package/integration craft, runs a preview-only probe, and leaves the
+`packages:` pin and the `oats sync` for the user.

package/capabilities/oats-authoring/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