@awebai/oats 0.29.4 → 0.30.1

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

@@ -1,84 +0,0 @@
----
-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 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".
----
-
-# Capability and integration authoring — delegate
-
-A capability package may ship skills, instance instructions, requirements,
-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, declare it and give it to souls;
-no build is needed:
-
-```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 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
-
-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 --preview \
-  --purpose <package-slug> \
-  --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 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 (commands, hooks);
-- intended distribution and version/compatibility;
-- which souls or workspace defaults should receive it, and its settings; and
-- expected skill/instruction collisions (a duplicate skill name fails the spawn).
-
-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 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/skill-craft/SKILL.md

@@ -1,109 +0,0 @@
----
-name: skill-craft
-description: >-
-  How to create, evaluate, and maintain agent skills (SKILL.md files per the
-  Agent Skills standard). Use when writing a new skill, improving or debugging
-  an existing one (skill not triggering, agent ignoring instructions, skill too
-  long), turning a repeated procedure or correction into a skill, deciding
-  whether knowledge belongs in a skill versus the knowledge base versus
-  AGENTS.md, bundling scripts into skills, or evaluating whether a skill
-  actually helps. Based on the agentskills.io creator guides and Anthropic
-  best practices.
----
-
-# Skill craft — create, evaluate, maintain
-
-A skill is a directory with a `SKILL.md` (YAML frontmatter + markdown body),
-optionally `scripts/`, `references/`, `assets/`. Agents load only `name` +
-`description` at startup; the body loads **only when the description matches
-the task** — the description carries the entire burden of triggering.
-
-## Where does this knowledge belong? (decide first)
-
-- **Repeatable procedure** ("how to do X, again and again") → **skill**.
-- **Declarative fact/decision/lesson** ("what is true and why") → **OKF
-  concept** in the knowledge base (see `okf` skill). Skills may reference
-  concepts for the why.
-- **Applies to every session of this agent** (role, boundaries, core workflow)
-  → **AGENTS.md** (see `soul-craft`). Rule of thumb: AGENTS.md is loaded
-  always — keep it minimal; skills load on demand — put domain workflows there.
-
-## Creating a skill
-
-**Ground it in real expertise — never generate from thin air.** The valuable
-content is what a capable model *doesn't* already know: your APIs, your
-conventions, the corrections you had to make. Best sources: a hands-on task
-you just completed (extract the steps that worked, the corrections given, the
-formats used), runbooks, review comments, real failures and their fixes. A
-skill with generic content ("handle errors appropriately") is worthless — cut
-or ground it.
-
-**Frontmatter rules** (spec + hard-won):
-- `name`: lowercase alphanum + hyphens, ≤64 chars, **must match the directory
-  name**, no leading/trailing/double hyphens.
-- `description`: ≤1024 chars, non-empty. ⚠️ **Use a `>-` block scalar if it
-  contains any `: ` colon-space** — an unquoted colon breaks YAML parsing and
-  the skill silently fails to load. Verify new skills actually load.
-
-**Write the description for triggering** (it's the only thing the agent sees
-before deciding):
-- Imperative: "Use when..." not "This skill does...".
-- Name the **user intents** it serves, not the implementation. Include
-  trigger phrases users actually say, and cover cases where they don't name
-  the domain ("even if they don't mention X").
-- Precise beats broad: an over-broad description fires on near-miss tasks
-  and pollutes context.
-
-**Write the body for a loaded context window** — it competes with everything
-else once loaded:
-- **Only what the agent would get wrong without it.** For every line ask:
-  "would removing this cause mistakes?" No → cut.
-- ≤500 lines / ~5k tokens. Larger → move detail to `references/` and tell the
-  agent **when** to load each file ("read references/errors.md if the API
-  returns non-200"), not just that it exists.
-- **Defaults, not menus**: pick one tool/approach, mention alternatives in
-  one line. Match prescriptiveness to fragility: fragile sequences get exact
-  commands ("run exactly this"); judgment tasks get goals + why.
-- Procedures over answers: teach the approach that generalizes, with one
-  concrete worked example.
-- **Gotchas section** — often the highest-value part: concrete corrections to
-  mistakes the agent *will* make ("the /health endpoint lies; use /ready").
-- For multi-step workflows: an explicit checklist. For fragile output: a
-  template (agents pattern-match better than they follow prose). For
-  correctness-critical work: a validation loop (do → validate → fix → repeat)
-  or plan-validate-execute with a validator script.
-
-**Scripts**: when you see an agent reinventing the same logic across runs,
-write it once, test it, bundle it in `scripts/`, and reference it from the
-body with exact invocations. Prefer zero-dependency scripts; pin versions for
-`npx`/`uvx` one-offs. Scripts should print errors an agent can self-correct
-from ("field X not found — available: a, b, c").
-
-## Evaluating (before trusting)
-
-- **Trigger check**: draft ~10 realistic prompts that *should* fire the skill
-  (varied phrasing, some not naming the domain) and ~10 near-misses that
-  *shouldn't* (share keywords, need something else). Run them; the skill
-  triggered if its body was loaded. Fix the description, not the body, for
-  trigger failures.
-- **Output check**: run 2-3 real tasks **with and without** the skill. If
-  with-skill isn't clearly better, the skill isn't earning its context — cut
-  or sharpen it. Read execution traces, not just outputs: wasted steps mean
-  vague instructions, inapplicable instructions being followed, or menus
-  without defaults.
-
-## Maintaining
-
-- **Every correction is a candidate gotcha.** When a human (or reviewer)
-  corrects an agent following the skill, add the correction to the gotchas —
-  this is the single best maintenance loop.
-- Treat skills like code: prune on every edit; if the agent ignores a rule,
-  the skill is probably too long and the rule is drowning. Test behavior
-  changes by observing runs, not by rereading the text.
-- Never let a skill grow past one coherent unit of work — split like you'd
-  split a function.
-- Log skill changes in the soul's `knowledge/log.md` (`**Update**: skills/x —
-  added gotcha about …`) so knowledge history and skill history stay one
-  timeline. Knowledge maintenance and skill maintenance are the same duty:
-  declarative lessons go to OKF concepts, procedural lessons go to skills,
-  and each should link to the other.

package/capabilities/oats-authoring/skills/soul-craft/SKILL.md

@@ -1,116 +0,0 @@
----
-name: soul-craft
-description: >-
-  How to author and maintain an agent's soul — its AGENTS.md/CLAUDE.md
-  operating doc, soul.yaml config, and the balance between AGENTS.md, skills,
-  and the OKF knowledge base. Use when creating a new agent (writing its first
-  AGENTS.md), refining an existing soul that underperforms (agent ignores
-  instructions, drifts from its role, bloated operating doc), reviewing a
-  soul's setup, or deciding what goes in AGENTS.md versus a skill versus
-  knowledge. Based on the agents.md standard and Anthropic CLAUDE.md guidance.
----
-
-# Soul craft — author and maintain agent operating docs
-
-A soul's `AGENTS.md` is loaded **every session of
-every instance**. It is the most expensive real estate in the agent's context:
-everything in it taxes every task, relevant or not. The craft is keeping it
-minimal and pushing everything else to on-demand layers.
-
-**Canonical files:** `AGENTS.md` and `.agents/skills/` are the canonical
-sources; `CLAUDE.md` and `.claude/skills` must always be relative symlinks to
-them, never independent files (the spawner creates these links — if you find a
-real CLAUDE.md file diverging from AGENTS.md, that's a defect: merge and relink).
-
-## The three-layer rule
-
-| Layer | Loaded | Belongs there |
-|---|---|---|
-| **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 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.
-Bloated operating docs cause agents to ignore the rules that matter — a rule
-being ignored is usually a symptom of too many rules.
-
-## Writing a soul's AGENTS.md
-
-Structure that works (keep the whole thing short — a screen or two):
-
-1. **Role, one paragraph.** Who this agent is, what it owns, where it stops.
-   Boundaries beat capabilities: "you never merge", "you never modify the
-   assignee", "UI belongs to the ui agent" prevent more damage than feature
-   lists add value.
-2. **Operating loop.** The default shape of a work session — for a developer:
-   read ticket → plan in STATE.md → implement in ./work → verify → commit →
-   review loop → hand off. Concrete, not aspirational.
-3. **Verification.** How this agent checks its own work: the build/test/lint
-   commands that must pass, what "done" means. An agent with a check it can
-   run closes its own loop; without one, "looks done" is the only signal.
-   Include exact commands the agent can't guess (`make test-unit`, not
-   "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 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.
-
-Style rules (from the agents.md standard + field experience):
-- Write commands, not prose: `pnpm vitest run -t "<name>"` beats "run the
-  relevant test".
-- Include only what can't be inferred from the repo: conventions that differ
-  from defaults, env quirks, etiquette (branch naming, PR format).
-- Exclude: standard language conventions, file-by-file codebase tours, API
-  docs (link instead), anything that changes weekly (that's knowledge),
-  self-evident advice ("write clean code").
-- Emphasis (**IMPORTANT**, YOU MUST) sparingly — it works, and it stops
-  working when everything is emphasized.
-- The repo's own AGENTS.md (in ./work) covers repo mechanics — the soul doc
-  covers the *role*. Don't duplicate the repo doc; instruct reading it.
-
-## soul.yaml
-
-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
-
-- **Change AGENTS.md rarely and deliberately** — it defines the agent. The
-  bar: a change in how the agent fundamentally operates, proven by instance
-  experience. Day-to-day lessons go to knowledge; procedures to skills.
-- When an instance repeatedly misbehaves, diagnose in order: (1) is the rule
-  drowning in a bloated doc? → prune the doc; (2) is it ambiguous? → sharpen
-  with a command or example; (3) is it missing? → add it, minimally. Test by
-  observing the next instance's behavior, not by rereading.
-- **Prune on every edit.** Adding a line? Look for two to cut.
-- Log every soul change in `knowledge/log.md` (`**Update**: AGENTS.md — …`)
-  so the soul's evolution is reconstructible.
-- Agents never rewrite their own role or safety boundaries; soul changes that
-  alter behavior go through the human (or a documented review workflow).
-- Periodic review (worth doing when spawning feels off): does the role still
-  match reality? Do skills cover the recurring procedures? Is the knowledge
-  index current? Are the verification commands still correct?
-
-## Bootstrapping a new soul
-
-Fastest path to a *grounded* soul (never write one from imagination):
-1. Do (or supervise) the role's work once in a plain session, noting
-   corrections, commands, and conventions as you go.
-2. Distill: role/boundaries/loop/verification/escalation → AGENTS.md;
-   repeated procedures → first skills; facts and decisions → first knowledge
-   concepts.
-3. Spawn an instance on a real task; watch where it stumbles; fold the
-   corrections back (doc, skill gotcha, or concept — per the three-layer rule).
-Two rounds of this beat any amount of upfront authoring.

package/capabilities/oats-aweb/bin/oats-aweb-binding.mjs

@@ -1,11 +0,0 @@
-#!/usr/bin/env node
-import { runBindingWire } from '../lib/binding-wire.mjs';
-
-const args=process.argv.slice(2);
-if(args.includes('--help') || args.includes('-h')) {
-  process.stdout.write('oats aweb provider binding phase (manifest-owned JSON stdin/stdout)\n');
-} else {
-  const phase=args[0];
-  if(args.length!==1) await runBindingWire(phase,[],process.stdout);
-  else await runBindingWire(phase);
-}