@awebai/oats 0.22.0 → 0.22.1

package/capabilities/oats-linear/README.md

@@ -1,234 +0,0 @@
-# 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/package.json

@@ -1,29 +0,0 @@
-{
-  "name": "@awebai/oats-linear",
-  "version": "0.1.0",
-  "description": "OATS tasks provider: Linear via its GraphQL API, with JSON-first commands and label-based agent identity",
-  "keywords": [
-    "pi-package",
-    "oats",
-    "linear",
-    "tasks"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/awebai/oats",
-    "directory": "capabilities/oats-linear"
-  },
-  "license": "MIT",
-  "type": "module",
-  "scripts": {
-    "test": "node --test"
-  },
-  "bin": {
-    "oats-linear": "./bin/oats-linear.mjs"
-  },
-  "pi": {
-    "skills": [
-      "./skills"
-    ]
-  }
-}

package/capabilities/oats-linear/test/oats-linear.test.mjs

@@ -1,168 +0,0 @@
-import assert from "node:assert/strict";
-import { spawn } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { createServer } from "node:http";
-import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
-import test from "node:test";
-import { fileURLToPath } from "node:url";
-
-const DIR = resolve(fileURLToPath(new URL("..", import.meta.url)));
-const CLI = join(DIR, "bin", "oats-linear.mjs");
-const HOOK = join(DIR, "bin", "oats-linear-hook.mjs");
-
-function run(script, args = [], env = {}) {
-  return new Promise((done) => {
-    const child = spawn(process.execPath, [script, ...args], {
-      env: { ...process.env, ...env },
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (chunk) => { stdout += chunk; });
-    child.stderr.on("data", (chunk) => { stderr += chunk; });
-    child.on("close", (code) => done({ code, stdout, stderr }));
-  });
-}
-
-async function mockApi(responder, fn) {
-  const requests = [];
-  const server = createServer(async (request, response) => {
-    let body = "";
-    for await (const chunk of request) body += chunk;
-    const parsed = JSON.parse(body);
-    requests.push({ headers: request.headers, ...parsed });
-    const payload = await responder(parsed, requests);
-    response.writeHead(payload.status || 200, { "content-type": "application/json" });
-    response.end(JSON.stringify(payload.body || payload));
-  });
-  await new Promise((ready) => server.listen(0, "127.0.0.1", ready));
-  const url = `http://127.0.0.1:${server.address().port}/graphql`;
-  try { await fn({ url, requests }); }
-  finally { await new Promise((closed) => server.close(closed)); }
-}
-
-const team = { id: "team-1", key: "ENG", name: "Engineering" };
-const issue = {
-  id: "issue-1", identifier: "ENG-1", title: "Test issue", description: "body",
-  url: "https://linear.app/issue/ENG-1", priority: 0, priorityLabel: "No priority",
-  team, state: { id: "started-1", name: "In Progress", type: "started" },
-  project: null, parent: null, assignee: { id: "human-1", name: "Human", email: "human@example.com" },
-  labels: { nodes: [] },
-};
-
-function operation(query) { return query.match(/(?:query|mutation)\s+(\w+)/)?.[1]; }
-
-test("missing API key fails once with setup guidance", async () => {
-  const result = await run(CLI, ["auth"], { LINEAR_API_KEY: "" });
-  assert.equal(result.code, 1);
-  assert.match(result.stderr, /LINEAR_API_KEY is not set/);
-  assert.match(result.stderr, /Security & access/);
-});
-
-test("auth uses the personal-key Authorization header", async () => {
-  await mockApi(() => ({ data: {
-    viewer: { id: "user-1", name: "Human", email: "human@example.com" },
-    organization: { id: "org-1", name: "Acme", urlKey: "acme" },
-  } }), async ({ url, requests }) => {
-    const result = await run(CLI, ["auth"], { LINEAR_API_KEY: "secret-key", LINEAR_API_URL: url });
-    assert.equal(result.code, 0, result.stderr);
-    assert.equal(JSON.parse(result.stdout).authenticated, true);
-    assert.equal(requests[0].headers.authorization, "secret-key");
-    assert.equal(operation(requests[0].query), "OatsLinearAuth");
-  });
-});
-
-test("issue list builds an open agent/project filter", async () => {
-  await mockApi(({ query }) => {
-    if (operation(query) === "OatsLinearTeam") return { data: { teams: { nodes: [team] } } };
-    if (operation(query) === "OatsLinearProjects") return { data: { projects: { nodes: [
-      { id: "project-1", name: "Agent Platform", slugId: "agent-platform", status: { id: "ps-1", name: "Started", type: "started" }, teams: { nodes: [team] } },
-    ] } } };
-    if (operation(query) === "OatsLinearIssues") return { data: { issues: { nodes: [issue], pageInfo: { hasNextPage: false, endCursor: null } } } };
-    throw new Error(`unexpected operation ${operation(query)}`);
-  }, async ({ url, requests }) => {
-    const result = await run(CLI, ["issue", "list", "--team", "ENG", "--agent", "worker-1", "--project", "Agent Platform"], {
-      LINEAR_API_KEY: "key", LINEAR_API_URL: url,
-    });
-    assert.equal(result.code, 0, result.stderr);
-    const listRequest = requests.find((request) => operation(request.query) === "OatsLinearIssues");
-    assert.deepEqual(listRequest.variables.filter, {
-      team: { id: { eq: "team-1" } },
-      state: { type: { nin: ["completed", "canceled", "duplicate"] } },
-      labels: { some: { name: { eqIgnoreCase: "agent-worker-1" } } },
-      project: { id: { eq: "project-1" } },
-    });
-  });
-});
-
-test("issue create provisions the agent label and records identity", async () => {
-  await mockApi(({ query, variables }) => {
-    const op = operation(query);
-    if (op === "OatsLinearTeam") return { data: { teams: { nodes: [team] } } };
-    if (op === "OatsLinearLabels") return { data: { issueLabels: { nodes: [] } } };
-    if (op === "OatsLinearCreateLabel") return { data: { issueLabelCreate: {
-      success: true, issueLabel: { id: "label-1", name: variables.input.name, color: "#5E6AD2", team },
-    } } };
-    if (op === "OatsLinearIssueCreate") return { data: { issueCreate: { success: true, issue } } };
-    throw new Error(`unexpected operation ${op}`);
-  }, async ({ url, requests }) => {
-    const result = await run(CLI, ["issue", "create", "--team", "ENG", "--title", "Bounded work", "--description", "Acceptance", "--agent", "worker-1"], {
-      LINEAR_API_KEY: "key", LINEAR_API_URL: url,
-    });
-    assert.equal(result.code, 0, result.stderr);
-    const create = requests.find((request) => operation(request.query) === "OatsLinearIssueCreate");
-    assert.equal(create.variables.input.teamId, "team-1");
-    assert.deepEqual(create.variables.input.labelIds, ["label-1"]);
-    assert.match(create.variables.input.description, /Acceptance\n\n---\nAgent: worker-1/);
-  });
-});
-
-test("terminal transitions require explicit authorization", async () => {
-  await mockApi(({ query }) => {
-    const op = operation(query);
-    if (op === "OatsLinearIssue") return { data: { issue } };
-    if (op === "OatsLinearStates") return { data: { team: { states: { nodes: [
-      { id: "done-1", name: "Done", type: "completed", position: 1 },
-    ] } } } };
-    throw new Error(`unexpected operation ${op}`);
-  }, async ({ url, requests }) => {
-    const result = await run(CLI, ["issue", "update", "ENG-1", "--state", "Done"], {
-      LINEAR_API_KEY: "key", LINEAR_API_URL: url,
-    });
-    assert.equal(result.code, 1);
-    assert.match(result.stderr, /refusing terminal state/);
-    assert.equal(requests.some((request) => operation(request.query) === "OatsLinearIssueUpdate"), false);
-  });
-});
-
-test("comment accepts multiline markdown from a file", async () => {
-  const temp = mkdtempSync(join(tmpdir(), "oats-linear-test-"));
-  const bodyFile = join(temp, "comment.md");
-  writeFileSync(bodyFile, "[worker-1] handoff: details\n\n- tests pass\n");
-  try {
-    await mockApi(({ query }) => {
-      assert.equal(operation(query), "OatsLinearComment");
-      return { data: { commentCreate: { success: true, comment: { id: "comment-1", body: "ok", createdAt: "2026-07-10", url: "https://linear.app/c/1", user: { id: "user-1", name: "Human" } } } } };
-    }, async ({ url, requests }) => {
-      const result = await run(CLI, ["issue", "comment", "ENG-1", "--body-file", bodyFile], {
-        LINEAR_API_KEY: "key", LINEAR_API_URL: url,
-      });
-      assert.equal(result.code, 0, result.stderr);
-      assert.equal(requests[0].variables.input.body, "[worker-1] handoff: details\n\n- tests pass");
-    });
-  } finally { rmSync(temp, { recursive: true, force: true }); }
-});
-
-test("spawn hook briefs settings and warns without auth", async () => {
-  const result = await run(HOOK, ["spawn"], {
-    OATS_EVENT: "spawn", OATS_INSTANCE: "worker-1",
-    OATS_SETTINGS: JSON.stringify({ team: "ENG", project: "Agent Platform" }),
-    LINEAR_API_KEY: "",
-  });
-  assert.equal(result.code, 0, result.stderr);
-  const payload = JSON.parse(result.stdout);
-  assert.deepEqual(payload.meta, { label: "agent-worker-1", team: "ENG", project: "Agent Platform" });
-  assert.match(payload.brief, /team ENG, default project Agent Platform/);
-  assert.match(payload.warning, /LINEAR_API_KEY/);
-});

package/capabilities/oats-okf/package.json

@@ -1,22 +0,0 @@
-{
-  "name": "@awebai/oats-okf",
-  "version": "0.1.0",
-  "description": "OATS knowledge provider: Open Knowledge Format (OKF) craft skill, bundle validator, and agents-md injection",
-  "keywords": [
-    "pi-package",
-    "oats",
-    "okf"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/awebai/oats",
-    "directory": "capabilities/oats-okf"
-  },
-  "license": "MIT",
-  "type": "module",
-  "pi": {
-    "skills": [
-      "./skills"
-    ]
-  }
-}