@awebai/oats 0.30.0 → 0.30.1

package/capabilities/oats-engineering-expert/skills/plan-and-spec/SKILL.md

@@ -1,53 +0,0 @@
----
-name: plan-and-spec
-description: Turn a goal into a plan and one executable spec per surface (code area, package or service) for developers to implement. Use when starting a feature, fix or project in your domain, when a developer needs a spec, or when work must be split across developers.
----
-
-# Plan and spec
-
-A developer should be able to implement a spec without coming back to ask what you
-meant. If they would have to guess, the spec is not done.
-
-## 1. Frame the goal
-- **The problem**, in one or two sentences, and who has it.
-- **Done means:** observable outcomes, not activities ("`oats teams add` refuses a
-  duplicate label with E_TEAM_EXISTS", not "improve team handling").
-- **Constraints:** compatibility promises, contracts other parts rely on, security
-  boundaries, performance limits, deadlines.
-- **Out of scope:** what this work deliberately does not do.
-
-## 2. Design at your level
-- Choose the design. Record the alternatives you rejected and why, in one line each.
-- Name every contract the change touches (APIs, file formats, CLI output, env vars,
-  events) and whether it changes. A contract change needs its consumers named and an
-  order ("the consumer accepts the new shape first").
-- Prefer the smallest change that meets "done". If a simpler design meets 90% of the
-  goal, raise it with the requester before choosing the bigger one.
-
-## 3. Split by surface
-- A **surface** is a part of the system one developer can own: a package, a service, a
-  module group. Split so that each developer's work can be built and tested on its own.
-- Where surfaces meet, write the **interface first** (the shape, the error cases). Both
-  specs cite it.
-- Sequence the pieces: what can run in parallel, what must land first.
-
-## 4. Write each spec
-Use this shape, and keep it as short as the work allows:
-
-```
-# Spec: <title>
-Goal:            <one paragraph: the problem and the outcome>
-Done when:       <checkable outcomes>
-Design:          <the approach; the key decisions and why>
-Contracts:       <what must not break; what changes, and for whom>
-Edge cases:      <inputs, failures and states the code must handle>
-Tests:           <what proves it: unit, integration, a real run>
-Out of scope:    <what not to do>
-Surface / files: <where the work lives; what to leave alone>
-Delivery:        <branch, PR target, who reviews>
-```
-
-## 5. Check the plan before launching
-- Every "done when" is covered by some spec's tests.
-- No two developers edit the same files without an agreed order.
-- The riskiest assumption is tested first (a spike, a real run), not last.

package/capabilities/oats-engineering-expert/skills/verify-developer-work/SKILL.md

@@ -1,49 +0,0 @@
----
-name: verify-developer-work
-description: The expert's verification of work a developer hands back, after it has passed adversarial code review. Checks architecture, coherence, fit with the whole system, simplicity, and glaring bugs; does not redo the line-by-line review. Use when a developer reports work done, before accepting, merging or passing work on.
----
-
-# Verify developer work
-
-The work has been through an adversarial code review: line-level bugs, security and
-simplification were that reviewer's job. Yours is the view the reviewer doesn't have:
-does this belong in the system, the way it was built?
-
-## 0. Check the handover is complete
-It needs:
-- what was done, against the spec's "done when";
-- how it was verified (tests run, real runs, with results);
-- **the adversarial review's final verdict**, and the rounds it took;
-- anything deliberately left out.
-
-If the review didn't happen, or ended without the reviewer being satisfied, send it back:
-you don't do the reviewer's job for it.
-
-## 1. Architecture
-- Is it the design the spec asked for? If it deviates, is the deviation better, and
-  recorded?
-- Are the responsibilities in the right places, or did logic leak across a boundary to
-  make something easy?
-- Are contracts kept? A changed contract must have its consumers handled, in the right
-  order.
-
-## 2. Coherence and fit
-- Does it follow the system's existing patterns and names, or invent a parallel way?
-- Does it duplicate something that exists?
-- Will the next change in this area be easier or harder because of it?
-
-## 3. Simplicity
-- Is it the simplest solution that meets "done"? Look for layers, options, flags or
-  generality nobody asked for.
-- Could a piece be deleted with no loss?
-
-## 4. Glaring bugs
-- Read the main path and the failure paths once, as a user would hit them. You are
-  looking for what's obviously wrong, not auditing every line.
-- Check that the tests prove the "done when" items, not just that the code runs.
-
-## Verdict
-- **Accept**, or **return** with numbered reasons, each saying what's wrong and why it
-  matters. Keep matters of taste out of a return.
-- A return goes to the same developer. Architecture-level returns may need a spec change
-  first: make it, then return.

package/capabilities/oats-jira/bin/oats-jira.mjs

@@ -1,40 +0,0 @@
-#!/usr/bin/env node
-/**
- * oats-jira — OATS tasks-provider hook for Jira.
- *
- * Invoked by the OATS kernel at instance lifecycle events (hook contract):
- *   oats-jira spawn   surface the instance's Jira identity (label) and the
- *                    deployment's site/project in TASK.md — advisory only,
- *                    no Jira calls, nothing to mint or clean up.
- *
- * Env contract (set by the kernel):
- *   OATS_EVENT     spawn
- *   OATS_INSTANCE  instance name (its Jira label is agent-<instance>)
- *   OATS_SETTINGS  JSON of the provider's `settings:` block ({ site?, project? })
- *
- * Output (stdout JSON): { "meta": {...}, "brief": "...", "warning": "..." }
- * Exit code is advisory: the kernel treats hook failure as a warning, never a block.
- */
-const out = (o) => { process.stdout.write(JSON.stringify(o) + "\n"); process.exit(0); };
-const warn = (m) => out({ warning: `oats-jira: ${String(m).slice(0, 300)}` });
-
-const event = process.env.OATS_EVENT || process.argv[2];
-const instance = process.env.OATS_INSTANCE;
-const settings = JSON.parse(process.env.OATS_SETTINGS || "{}");
-
-if (event === "spawn") {
-  const label = `agent-${instance}`;
-  const site = settings.site;
-  const project = settings.project;
-  const where = site && project ? `project ${project} on ${site}`
-    : site ? `site ${site} (project unset — ask your human)`
-    : project ? `project ${project} (site unset — ask your human)`
-    : `your deployment's Jira (site/project not configured — ask your human to set tasks: { site, project } in the soul's soul.yaml, or settings.oats.jira.{site,project} in the deployment's oats-local.yaml)`;
-  out({
-    meta: { label, ...(site ? { site } : {}), ...(project ? { project } : {}) },
-    brief: `Tasks: Jira — ${where}. Your Jira identity is the label "${label}" (never the assignee field). Load the jira-tasks skill before touching tickets.`,
-    ...(site && project ? {} : { warning: `oats-jira: settings incomplete (site: ${site || "unset"}, project: ${project || "unset"}) — set tasks: { site, project } in the soul's soul.yaml, or settings.oats.jira.{site,project} in the deployment's oats-local.yaml` }),
-  });
-} else {
-  warn(`unknown event "${event}" (expected spawn)`);
-}

package/capabilities/oats-jira/injects/jira.md

@@ -1,10 +0,0 @@
-## Tasks: Jira
-
-Your tasks layer is **Jira** (via the `acli` CLI). Work traces up to epics;
-you are identified by the label `agent-<your-instance-alias>` and an `Agent:`
-line in descriptions — never by the assignee field. Load the **jira-tasks**
-skill before reading your work queue, joining an epic's roster, posting
-progress, transitioning status, or creating stories/tasks. Your Jira site and
-project come from your deployment's settings (see your TASK.md briefing or
-the skill). Tasks only: status and outcomes live in Jira; conversation lives
-in your deployment's messaging layer.

package/capabilities/oats-jira/oats.json

@@ -1,22 +0,0 @@
-{
-  "capability": "oats.jira",
-  "command": "jira",
-  "version": "1.0.1",
-  "compatibility": { "oats": ">=0.26.0" },
-  "layer": "tasks",
-  "description": "Tasks layer via Jira: acli-based epic/story/task protocol, agent roster in epic descriptions, label-based agent identity.",
-  "requires": [
-    {
-      "command": "acli",
-      "why": "all Jira operations (search, view, create, transition, comment)",
-      "install": "https://developer.atlassian.com/cloud/acli/guides/install-acli/"
-    }
-  ],
-  "skills": [
-    "skills"
-  ],
-  "inject": "injects/jira.md",
-  "hooks": {
-    "spawn": "bin/oats-jira.mjs spawn"
-  }
-}

package/capabilities/oats-jira/skills/jira-tasks/SKILL.md

@@ -1,179 +0,0 @@
----
-name: jira-tasks
-description: >-
-  Jira task tracking and agent roster protocol for OATS agents. Use when you
-  are an agent instance working an epic, story, or task in Jira: reading your
-  assignment, finding your work queue, joining or leaving an epic's Agent
-  Roster, posting progress or handoff comments, transitioning ticket status,
-  or creating stories/tasks under an epic. Also use when asked about "the
-  board", "the roster", "your ticket", "epic status", or task tracking
-  between agents. Uses the acli CLI (Atlassian CLI) from bash.
----
-
-# Agent task tracking (Jira)
-
-Jira is your deployment's **tasks layer** — the shared record for task
-tracking and the agent roster. Agents do not know about projects — you know
-**repos and epics**. The hierarchy:
-
-- **Epic** — the unit of work that kicks off, runs, and completes. May touch
-  one repo or several. Its description carries the **Agent Roster** — the
-  source of truth for who is on the epic and their role. Bugs/support run as
-  a standing epic.
-- **Story** — a **group of related tasks** covering one part of the epic's
-  work (often one repo's slice, one feature area). Not every task needs a
-  story.
-- **Task** — a small bounded item, the thing an agent actually works. Lives
-  **either directly under the epic** (standalone item) **or under a story**
-  (part of a grouped slice). Everything traces up to an epic.
-
-## Site and project (from your deployment, never hardcoded)
-
-Your Jira **site** and **project key** come from the tasks payload OATS merged
-for this instance: the soul's `soul.yaml` `tasks: { site, project }`, the
-deployment's `oats-local.yaml` `settings.oats.jira.{site,project}`, or a
-spawn's `--provider oats.jira key=value`. Find them, in order:
-
-1. Your `TASK.md` briefing — the spawn hook writes a
-   `Tasks: Jira — project <KEY> on <site>` line.
-2. `./instance.json` in your instance home — `providers["oats.jira"]` is the
-   merged payload this instance received.
-3. Ask your human.
-
-Below, `<PROJECT>` means that project key. If site or project are unset,
-STOP and ask your human to set them — do not guess.
-
-**First use**: run `acli jira auth status` — if unauthorized, STOP and tell
-the human to run `acli jira auth login --web`. Never attempt login yourself.
-
-## Identity rules (non-negotiable)
-
-- **The human assignee is always the owning engineer** (never change
-  assignee to yourself; agents are not Jira users). Do not touch assignee
-  unless told.
-- **You are identified by label and description**, not the assignee field:
-  - Label `agent-<your-instance-alias>` on any story/task you work.
-  - An `Agent:` line in the description (see templates).
-- **Never set or modify sprints.** Never delete tickets. Comment, don't
-  rewrite, other agents' descriptions (exception: coordinators maintain the
-  roster table).
-
-## Your work queue
-
-```bash
-acli jira workitem search --jql "project = <PROJECT> AND labels = agent-<alias> AND statusCategory != Done ORDER BY rank" --json
-acli jira workitem view <PROJECT>-1234 --json          # read one ticket (description, labels, status)
-acli jira workitem search --jql "project = <PROJECT> AND parent = <PROJECT>-<epic> AND statusCategory != Done" --json   # epic's direct children (stories + standalone tasks)
-acli jira workitem search --jql "project = <PROJECT> AND parent = <PROJECT>-<story> AND statusCategory != Done" --json  # a story's tasks
-```
-
-An epic's full open work = its direct children **plus** the tasks under each
-of its stories — walk one level down from stories when you need the complete
-picture.
-
-Record your epic and ticket keys in your instance memory (e.g. `STATE.md`
-`# Context`).
-
-## The Agent Roster (epics)
-
-The epic description contains a `## Agent Roster` markdown table — current
-truth for who is on the epic:
-
-```
-## Agent Roster
-
-| Agent (instance) | Soul / class | Repo | Role on epic | Status | Since |
-|---|---|---|---|---|---|
-| coordinator-digest | coordinator (newsletter) | newsletter-service | runs the epic | active | 2026-07-07 |
-| developer-digest-api | developer (newsletter) | newsletter-service | implements API | active | 2026-07-07 |
-```
-
-Protocol:
-- **Joining**: the coordinator (or the spawning agent) adds your row to the
-  table (`acli jira workitem edit <epic> --description ...` with the full
-  updated description — read it first, edit only the roster table) AND posts
-  a comment: `[roster] <alias> joined — role: <role>, repo: <repo>`.
-- **Leaving/retiring**: set the row's Status to `retired` (keep the row — it
-  is history) and comment `[roster] <alias> retired — <one-line outcome>`.
-- Only edit the roster table; never rewrite the rest of the epic description.
-- Comments are the event log; the table is current state. On conflict, fix
-  the table and note it in a comment.
-
-## Working a ticket
-
-1. Read your ticket and its epic (description + roster) before starting.
-2. **Milestones** → comment on your ticket, prefixed `[<alias>]`. Mirror the
-   entry you record in your instance memory — same events, two audiences.
-3. **Status transitions** — move your ticket as you work:
-   `acli jira workitem transition <PROJECT>-1234 --status "In Progress"`.
-   Discover valid statuses with `--help` or by trying; if a transition is
-   rejected, comment instead and let the coordinator move it.
-4. **Done** = your latest commit is review-clean and the branch is handed
-   off. Comment the outcome (branch, PR link, verification), then transition.
-5. **Handoff/blocked** → comment
-   `[<alias>] handoff → <next-alias>: <what+where>` or
-   `[<alias>] blocked: <what is needed, from whom>`.
-
-Tasks ≠ messaging: status and outcomes live here in Jira; conversation lives
-in your deployment's messaging layer. Mail nudges; Jira records.
-
-## Creating tickets (coordinators; developers file follow-ups as Tasks)
-
-House rules: summary ≤ 12 words, describe the requirement not the solution,
-bugs always include reproduction steps, keep descriptions to a few bullets.
-
-**Choosing the level:**
-- Small bounded item, no siblings needed → **Task directly under the epic**.
-- A part of the epic's work that breaks into several related tasks → **Story
-  under the epic, tasks under the story**. The story is the group, not the
-  work item — agents are assigned to its tasks (a story worked wholly by one
-  agent may carry that agent's label too).
-- Never create a story for a single task, and never nest stories.
-
-```bash
-acli jira workitem create --project <PROJECT> --type Task --summary "<summary>" \
-  --parent <PROJECT>-<epic-or-story> --label "agent-<alias>" --description "<see template>"
-acli jira workitem create --project <PROJECT> --type Story --summary "<summary>" \
-  --parent <PROJECT>-<epic> --description "<see template>"
-```
-
-### Story/Task description template
-
-```
-<What & why — 2-4 bullets. Acceptance criteria as a checklist.>
-
----
-Agent: <instance-alias>          (who works this — matches the agent-<alias> label; stories list it only when one agent works the whole story)
-Soul: <soul-name> · Repo: <repo>
-Parent: <PROJECT>-<epic-or-story-key> · Epic: <PROJECT>-<epic-key>
-```
-
-### Epic description template
-
-```
-<Intent — what this epic delivers and why. Walls — what is explicitly out.>
-
-Repos touched: <repo>, <repo>
-Human gates: <security/authz/migration/contract items needing sign-off, or "none">
-
-## Agent Roster
-
-| Agent (instance) | Soul / class | Repo | Role on epic | Status | Since |
-|---|---|---|---|---|---|
-```
-
-### Comment conventions (machine-greppable prefixes)
-
-- `[roster] <alias> joined|retired — …`
-- `[<alias>] milestone: …` · `[<alias>] handoff → <alias>: …` ·
-  `[<alias>] blocked: …` · `[<alias>] done: branch <name>, <verification>`
-
-## Verify-before-trusting
-
-Jira workflows differ per site. On first real use in a deployment: check the
-project's issue types (`Epic/Story/Task/Bug`), whether `--parent` links
-stories/tasks to epics, whether a **Task can take a Story as parent** (some
-Jira configs only allow that via the Sub-task type — if so, use Sub-tasks
-under stories and treat them as tasks), and the exact status names. If
-reality differs, note it in a comment on your ticket and tell your
-coordinator so your deployment's conventions get recorded.

package/capabilities/oats-linear/bin/oats-linear-hook.mjs

@@ -1,34 +0,0 @@
-#!/usr/bin/env node
-/** OATS spawn briefing for the Linear tasks integration. Makes no API calls. */
-const output = (value) => {
-  process.stdout.write(JSON.stringify(value) + "\n");
-  process.exit(0);
-};
-
-const event = process.env.OATS_EVENT || process.argv[2];
-if (event !== "spawn") output({ warning: `oats-linear: unknown event "${event}" (expected spawn)` });
-
-let settings = {};
-try { settings = JSON.parse(process.env.OATS_SETTINGS || "{}"); }
-catch { output({ warning: "oats-linear: the tasks settings payload (OATS_SETTINGS) is not valid JSON" }); }
-
-const instance = process.env.OATS_INSTANCE || "unknown-instance";
-const team = settings.team;
-const project = settings.project;
-const label = `agent-${instance}`;
-// Where team lives under the workspace model (0.26): the soul's tasks payload or this machine's settings.
-const TEAM_HOMES = "tasks: { team } in the soul's soul.yaml, or settings.oats.linear.team in the deployment's oats-local.yaml";
-const target = team
-  ? `team ${team}${project ? `, default project ${project}` : ""}`
-  : `team unset — ask your human to set ${TEAM_HOMES}`;
-const warnings = [];
-if (!team) warnings.push(`settings.team is unset (set ${TEAM_HOMES})`);
-if (!process.env.LINEAR_API_KEY) warnings.push("LINEAR_API_KEY is not in the spawn environment");
-
-output({
-  meta: { label, ...(team ? { team } : {}), ...(project ? { project } : {}) },
-  brief: `Tasks: Linear — ${target}. Your agent identity is label "${label}"; keep the human assignee unchanged. Load the linear-tasks skill before touching issues.`,
-  ...(warnings.length ? {
-    warning: `oats-linear: ${warnings.join("; ")} — see the linear-tasks skill`,
-  } : {}),
-});