@awebai/oats 0.22.0

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

@@ -0,0 +1,176 @@
+---
+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 deployment's OATS config
+(`capabilities.oats.jira.<target>.settings: { site, project }`). Find them, in order:
+
+1. Your `TASK.md` briefing — the spawn hook writes a
+   `Tasks: Jira — project <KEY> on <site>` line.
+2. `oats doctor --json` from your work tree (the tasks layer's settings).
+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/README.md

@@ -0,0 +1,234 @@
+# OATS Linear tasks integration
+
+Binds the OATS `tasks` layer to [Linear](https://linear.app). It ships the
+`linear-tasks` skill, a short soul injection, a spawn briefing, and JSON-first
+`oats linear ...` commands for issue work.
+
+## Why GraphQL instead of a Linear CLI?
+
+Linear's official `@linear/cli` only supports interactive issue creation and
+branch checkout. It cannot list queues, read issues, transition workflow
+states, label ownership, or post comments. Third-party CLIs expose different
+and unstable command contracts. This integration therefore calls Linear's
+official GraphQL API directly with Node's built-in `fetch`; it adds no external
+CLI or SDK dependency.
+
+- Endpoint: `https://api.linear.app/graphql`
+- Authentication: personal API key in the `Authorization` header
+- Documentation: <https://linear.app/developers/graphql>
+
+## Setup
+
+1. In Linear, open **Settings → Security & access → API keys** and create a
+   personal API key with access to the workspace used by your OATS agents.
+2. Put the key in your shell or secret manager, never in `oats-config.yaml`:
+
+   ```bash
+   export LINEAR_API_KEY='lin_api_...'
+   ```
+
+   Start/resume agents from an environment that receives this variable. The
+   spawn hook warns when it is absent; API commands fail once with an actionable
+   authentication error rather than attempting login.
+3. Activate the bundled integration at the intended target:
+
+   ```bash
+   oats use oats.linear --global --dir /path/to/workspace
+   ```
+
+4. Add target settings to that binding (team is the Linear issue-prefix key;
+   project is an optional default communicated in each instance briefing):
+
+   ```yaml
+   capabilities:
+     layers:
+       tasks:
+         capability: oats.linear
+         from: bundled
+         settings: { team: ENG, project: Agent Platform }
+   ```
+
+5. Verify resolution and API access (operational commands are available only
+   in an active context):
+
+   ```bash
+   oats doctor /path/to/workspace
+   oats linear auth
+   oats linear teams
+   oats linear states --team ENG
+   oats linear projects --team ENG
+   ```
+
+The API key acts as the human who created it. Agents preserve the human
+assignee, identify themselves with `agent-<instance-name>` labels, and do not
+move issues to terminal states without explicit human authorization.
+
+## Command surface
+
+All successful output is JSON; errors are JSON on stderr and return non-zero.
+Run an incomplete command for usage, or load the `linear-tasks` skill for the
+workflow and exact examples.
+
+```text
+oats linear auth
+oats linear teams
+oats linear states --team <KEY>
+oats linear projects --team <KEY>
+oats linear labels --team <KEY>
+oats linear issue list|get|create|update|comment ...
+```
+
+Agent labels are created team-locally on first use of `--agent`. Other labels
+must already exist. `--description-file` and `--body-file` avoid shell quoting
+problems for multiline Markdown.
+
+## Projects, project documentation, and related issues
+
+### Operating model
+
+Use each Linear object for one kind of durable information:
+
+| Linear object | What belongs there | Who manages it with this integration |
+|---|---|---|
+| Project | Outcome, ownership, lifecycle, target dates, and the container for related issues | Humans in the Linear UI; agents can discover it |
+| Project overview | Intent, scope/non-goals, architecture, constraints, human gates, and success criteria | Humans in the Linear UI |
+| Project documents | Detailed designs, decision records, runbooks, research, and other long-form project context | Humans in the Linear UI |
+| Issue | One bounded deliverable with acceptance criteria | Agents through `oats linear issue ...` |
+| Sub-issue | An independently verifiable part of a larger issue | Agents through `--parent` |
+| Issue comment | Milestones, blockers, handoffs, verification, and PR/branch links | Agents through `issue comment` |
+| Messaging | Conversation and nudges | The configured messaging layer, never the durable task record |
+
+The project overview and documents explain the work; issues execute it. Keep
+project-wide decisions out of an arbitrary issue description, and keep task
+status out of chat. When a project document governs an issue, link that
+document from the issue description or a durable comment.
+
+### Discover projects
+
+The wrapper currently reads project metadata but not project overview/document
+content:
+
+```bash
+oats linear projects --team ENG
+```
+
+The JSON includes project IDs, names, slugs, status, and associated teams. Use
+an exact project name or slug in issue commands. If the configured project is
+missing or ambiguous, stop and ask the human rather than selecting a similar
+name.
+
+### List issues in a project
+
+```bash
+# Open issues in the project
+oats linear issue list --team ENG --project "Agent Platform"
+
+# Open issues claimed by one OATS instance
+oats linear issue list --team ENG --project "Agent Platform" \
+  --agent my-agent-instance
+
+# Include terminal issues when auditing history
+oats linear issue list --team ENG --project "Agent Platform" --all
+```
+
+`issue list` excludes completed, canceled, and duplicate states unless `--all`
+is supplied. Use `issue get` before acting; its JSON includes the issue's
+project and parent context:
+
+```bash
+oats linear issue get ENG-123
+```
+
+### Create issues in a project
+
+Prefer a Markdown file for acceptance criteria:
+
+```bash
+cat > /tmp/issue.md <<'EOF'
+Why this work is needed.
+
+Acceptance:
+- [ ] Observable outcome implemented
+- [ ] Verification evidence recorded
+- [ ] Relevant documentation updated
+EOF
+
+oats linear issue create --team ENG --project "Agent Platform" \
+  --title "Implement token refresh" \
+  --description-file /tmp/issue.md \
+  --agent my-agent-instance
+```
+
+Create a sub-issue only when it is independently verifiable and the parent
+really decomposes into multiple pieces:
+
+```bash
+oats linear issue create --team ENG --parent ENG-123 \
+  --title "Add refresh-token tests" \
+  --description-file /tmp/issue.md \
+  --agent my-agent-instance
+```
+
+Project membership and parentage are independent: `--project` associates an
+issue with a project; `--parent` makes it a sub-issue. Supply both when the
+sub-issue must explicitly carry project membership.
+
+### Work and report within the project
+
+```bash
+oats linear issue update ENG-123 --agent my-agent-instance
+oats linear issue update ENG-123 --state "In Progress"
+oats linear issue comment ENG-123 \
+  --body "[my-agent-instance] milestone: implementation complete; tests pass"
+oats linear issue comment ENG-123 \
+  --body "[my-agent-instance] handoff → reviewer: PR <url>; run npm test"
+```
+
+Use the team's exact workflow names from `oats linear states --team ENG`.
+Agents normally stop at the review state. Terminal transitions require both
+explicit human authorization and `--allow-terminal`.
+
+### Manage project overviews and documents
+
+The current command wrapper does **not** read or mutate project overview
+Markdown or Linear documents. Manage them through the Linear UI:
+
+1. Open the project returned by `oats linear projects --team <KEY>`.
+2. Maintain project intent, scope, non-goals, ownership, gates, architecture,
+   and success criteria in its overview.
+3. Keep detailed designs, decisions, and runbooks in project documents.
+4. Link governing project documents from related issues.
+5. Record implementation progress on issues; use Linear's project updates for
+   human-facing project-level summaries.
+
+An agent that needs unavailable project-document context must ask the human for
+its URL/content. It must not infer missing project policy from issue titles.
+
+## Current support boundary
+
+| Operation | Supported by `oats linear`? | Current path |
+|---|---:|---|
+| Discover teams, workflow states, projects, and labels | Yes | `teams`, `states`, `projects`, `labels` |
+| List/get/create/update/comment on project issues | Yes | `issue ...` commands |
+| Create sub-issues | Yes | `issue create --parent ...` |
+| Create, rename, schedule, change status, or close a project | No | Linear UI; human-owned |
+| Read or edit project overview Markdown | No | Linear UI |
+| List, read, create, or edit project documents | No | Linear UI |
+| Move an existing issue into/out of a project | No | Linear UI |
+| Change an existing issue's parent | No | Linear UI |
+| Publish Linear project status updates | No | Linear UI |
+| Create issue-to-issue relations such as blocks/related | No | Linear UI |
+
+Do not invent GraphQL calls or undocumented command flags to bypass this
+boundary. A future, separately reviewed extension could add commands such as:
+
+```text
+oats linear project get|create|update
+oats linear project issue-add|issue-remove
+oats linear document list|get|create|update
+oats linear project-update create
+oats linear relation create
+```
+
+Before adding those operations, the deployment must decide which project and
+document mutations agents may perform and which remain human-only.

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

@@ -0,0 +1,32 @@
+#!/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: integrations.linear.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}`;
+const target = team
+  ? `team ${team}${project ? `, default project ${project}` : ""}`
+  : "team unset — ask your human, or set integrations.linear.settings.team in oats-config.yaml";
+const warnings = [];
+if (!team) warnings.push("settings.team is unset");
+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 capabilities/oats-linear/README.md`,
+  } : {}),
+});