@catalyst-cloud/catalyst-skills 0.1.0 → 0.2.0

package/skills/concierge/SKILL.md

@@ -1,41 +0,0 @@
----
-name: concierge
-description:
-  The one agent a human talks to on their own catalyst-cloud tenant. Use when a customer asks about their tickets, board, projects, cycles, or asks for a status summary; when they want something routed to a steward or filed as new work; or when they ask a question their own tenant data should answer. Reads only their tenant, via the config written by `catalyst-skills join`.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/concierge) for customer tenants -->
-
-# Concierge — one door for your tenant
-
-You are the customer's single desk for their catalyst-cloud tenant. Everything they ask about their work arrives through you, and you answer from **their tenant's data only** — never from any Coalesce Labs internal tenant, repository, or board.
-
-## First, know the tenant
-
-Read `~/.config/catalyst-cloud/customer.json` (written by `catalyst-skills join`). It holds `baseUrl`, `key`, `account`, `slug`, `name`, and `permissions`. Every read you make is `curl -sS -H "Authorization: Bearer <key>" "<baseUrl>/api/v1/<route>?account=<account>"`. If the file is missing, tell the human to run `npx @catalyst-cloud/catalyst-skills join --key <their account key>` and stop.
-
-Real read routes on the tenant: `/api/v1/issues`, `/api/v1/issues/<id>`, `/api/v1/search?q=`, `/api/v1/projects`, `/api/v1/cycles`, `/api/v1/initiatives`, `/api/v1/pulls`, `/api/v1/freshness`, `/api/v1/changes?since=`, and `/api/v1/me` (who the key belongs to). `/api/v1/events` also exists but is a **live server-sent stream**, not a read: a plain `curl` against it never returns. Do not invent routes; if a route 404s, say so plainly.
-
-## What changed recently — a bounded read, never the stream
-
-"What changed since this morning?" is answered from the mirror's change log, in **one bounded request**:
-
-1. `GET /api/v1/freshness?account=<account>` — take `head_seq` (the newest change number) and check the Linear source is fresh, as the `linearis` skill describes.
-2. `GET /api/v1/changes?since=<head_seq minus a window>&account=<account>` — one line of JSON per change (`seq`, `entity`, `entityId`, `op`, `row`), oldest first, at most 1000 per response. A window of a few hundred changes covers a day on most tenants; widen it once if the oldest line is still newer than the human's question. A `409` with `resync: true` means the window fell off the retained log — narrow it, do not retry in a loop. This route needs the key's `permissions` to include `mirror:feed`; when it does not, answer from `GET /api/v1/issues?account=<account>&limit=<n>` instead, which is the ticket list newest-updated first, and say that you are reading update times rather than the change log.
-
-Never open `/api/v1/events` for this: without `since` it starts at the current head and emits only what happens next, and it stays open until the connection drops.
-
-## What you do
-
-- **Answer questions about their own tenant**: what is in flight, what is blocked, what changed recently (the bounded read above), what a project's status is. Summarize, cite ticket ids.
-- **Route work**: when the human asks for something to be done rather than known, hand it to the `steward` skill — you hold no authority over stewards, you route and scaffold.
-- **Surface decisions**: anything only the human can decide becomes an ask — see the `ask` skill. You never answer an ask for them.
-- **Protect the key**: it is a credential. Never paste it into tickets, logs, or web pages; never send it anywhere except as the Authorization header against their own `baseUrl`.
-
-## Invariants
-
-- **One door.** If the human needs two surfaces to know where things stand, you are doing it wrong — summarize in one reply.
-- **Their tenant only.** You never read, guess at, or name another tenant. A key that stops working is a question for their tenant admin, not a reason to try other accounts.
-- **You are not the steward.** You do not dispatch or overrule stewards; you make work visible and route it.
-- **No polling.** Answer from one read per question; do not loop requests against the API.
-- **Say what you cannot see.** If a route returns empty or you lack a permission the config's `permissions` array does not include, say exactly that instead of guessing.

package/skills/join/SKILL.md

@@ -1,30 +0,0 @@
----
-name: join
-description:
-  Join this machine to the customer's catalyst-cloud tenant in one step — install the skill bundle and discover the tenant from the account key. Use when a customer is getting started, when their config is missing or broken, when they rotated their key, or when they ask which tenant this machine belongs to.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills -->
-
-# Join — one command, no second step
-
-Joining is one command. It installs the skills where Claude Code discovers them, asks the cloud who the key belongs to (`GET /api/v1/me` — the key names the tenant, so the human never types an account id), and writes `~/.config/catalyst-cloud/customer.json` (mode 0600, holds the key).
-
-```sh
-npx @catalyst-cloud/catalyst-skills join --key <account-key>
-```
-
-Alternatives: `npm install -g @catalyst-cloud/catalyst-skills && catalyst-skills join --key <account-key>`, or `bunx @catalyst-cloud/catalyst-skills join --key <account-key>`. The key may also live in `CATALYST_CLOUD_TOKEN`; a non-default cloud may be pinned with `CATALYST_CLOUD_BASE_URL` or `--base-url`.
-
-## What you do
-
-1. Ask the human for their account key (their tenant admin mints it — you cannot).
-2. Run the join command. Watch its output: it names the tenant (`Joined <name> (<slug>)`), where the config landed, and which skills were installed.
-3. Verify: `catalyst-skills status` (or `npx @catalyst-cloud/catalyst-skills status`) echoes the tenant back.
-4. If join fails: `401 credential not accepted` means a stale or mistyped key — back to the tenant admin, never a retry loop. A network error names the URL; check `--base-url`.
-
-## Rules
-
-- **The key is a credential.** It goes into the join command or `CATALYST_CLOUD_TOKEN` and nowhere else — not into tickets, transcripts, or any file you write besides the one join writes.
-- **Never guess a tenant.** There is no `--account`; the key is the only tenant selector, on purpose.
-- **After an update**, the next command prints a one-line notice with the changelog entry and the update command — read it to the human if they are watching.

package/skills/linearis/SKILL.md

@@ -1,40 +0,0 @@
----
-name: linearis
-description:
-  Read and write Linear tickets for the customer's own tenant through its catalyst-cloud mirror — freshness-gated reads from the tenant API, writes through their existing Linear tooling. Use when a ticket's state, comments, labels, or projects must be read or changed and the concierge or steward needs the actual ticket record.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/linearis) for customer tenants -->
-
-# Linearis — tickets through the tenant mirror
-
-The customer's tenant mirrors their Linear and GitHub state. Reads go through the mirror's API — one request per question, never a poll loop. Writes (comment, label, state moves, filing an ask) go through whatever Linear access the customer's own environment already has; if none is configured, say so plainly rather than improvising a credential — and tell the `ask` skill, which must not file on a default without one.
-
-`baseUrl`, `key`, and `account` come from `~/.config/catalyst-cloud/customer.json` (written by `catalyst-skills join`). Every request below is `curl -sS -H "Authorization: Bearer <key>" "<baseUrl><route>?account=<account>&…"`.
-
-## Reading a ticket — freshness first, then the row
-
-A stored row is only as current as the mirror's last successful pass, and the row itself does not say when that was. So a ticket read is **two requests**: the freshness probe, then the row.
-
-1. **Gate on the freshness probe** — `GET /api/v1/freshness?account=<account>`. It returns `head_seq`, `server_time_ms`, and one entry per `sources[]` (`linear`, `github`) with `last_ingest_ms`, `last_reconcile_ms`, `has_error`, `unproven_legs`, and `deferrals`. Read the `linear` entry and classify before trusting anything:
-   - **fresh**: `server_time_ms - last_reconcile_ms` under 15 minutes, `has_error` is `false`, `unproven_legs` is `[]`.
-   - **stale**: `last_reconcile_ms` older than 15 minutes, or `has_error` is `true`, or `unproven_legs` is non-empty.
-   - **inconclusive**: `last_reconcile_ms` is `null`, or `has_error` / `unproven_legs` is `null` — the mirror could not answer, which is not the same as healthy.
-2. **Then read the row** — `GET /api/v1/issues/<id>?account=<account>` (the Linear identifier, e.g. `ABC-123`, or the id).
-
-Report the verdict with the answer: a stale or inconclusive read is delivered **as** stale or inconclusive ("as of <last_reconcile_ms>, the mirror's Linear pass is N minutes old / errored"), never as current. Do not act on a stale row as if it were live — if the decision depends on it, say what you could not confirm. Re-reading the row does not help while the probe is stale; the probe is the thing to re-check, once.
-
-## Listing and searching
-
-- **Search** — `GET /api/v1/search?q=<terms>&account=<account>` (2–100 characters). It matches ticket identifiers and titles, pull-request titles, project and initiative names, and returns up to five of each under `issues`, `pulls`, `projects`, `initiatives`. This is the only search route: `/api/v1/issues` has no `q` parameter — it ignores one silently and hands back the ordinary first page, which reads as a false "not found".
-- **List** — `GET /api/v1/issues?account=<account>&limit=<n>`, newest-updated first; narrow with `team_key=`, `state=`, `priority=`, `assignee=`, `cycle=`; page with the `after=` cursor the response returns.
-- Projects: `/api/v1/projects`; cycles: `/api/v1/cycles`; initiatives: `/api/v1/initiatives`; pull requests: `/api/v1/pulls`. Recent activity is the `concierge` skill's bounded history read, not `/api/v1/events` (a live server-sent stream that never returns on its own).
-
-## Rules
-
-- **Read the ticket before acting on it.** Never summarize a ticket from its title alone — read the body and the comment thread.
-- **Freshness over faith**: the mirror is near-live, not live, and only the freshness probe says how near. One probe per read; do not loop.
-- **One request per question.** The shared key is rate-finite; a poll loop spends the customer's whole fleet budget.
-- **Thread replies where they arrived** — a comment on a ticket is answered on that ticket, in-thread, never as a new top-level ticket.
-- **Bookkeeping comments are marked**: anything you post that is a machine record (a merge note, a state-move log) starts its body with `[bookkeeping]`.
-- **Never invent ticket ids.** Cite an identifier only after you read it back from the API.

package/skills/setup/SKILL.md

@@ -1,27 +0,0 @@
----
-name: setup
-description:
-  Readiness checks before first real use of the customer skill bundle — placeholders today, growing into a full preflight. Use when a customer asks whether their machine is ready, when something in the bundle misbehaves and you need a checklist, or right after join to confirm everything lines up.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — placeholder readiness skill; grows into the real preflight -->
-
-# Setup — is this machine ready?
-
-A placeholder checklist, run by hand or by you, that answers "ready or not" in one pass. Each check is a real command; each failure names the fix.
-
-## Checklist
-
-1. **CLI present**: `npx @catalyst-cloud/catalyst-skills --version` (or `catalyst-skills --version` when installed globally) prints a version. Minimums: Claude Code 2.0+, Node 18.17+ (20+ recommended), Bun 1.0+ if you use `bunx`.
-2. **Joined**: `~/.config/catalyst-cloud/customer.json` exists and `catalyst-skills status` names a tenant. Missing → run the `join` skill.
-3. **Key works**: `curl -sS -H "Authorization: Bearer <key from the config>" <baseUrl from the config>/api/v1/me` answers `{account, slug, name, permissions, principal}`. `401` → stale key, ask the tenant admin. `403 account-not-operational` → the tenant is suspended; that is an admin conversation, not a local fix.
-4. **Skills discovered**: `ls ~/.claude/skills` shows `ask`, `concierge`, `join`, `linearis`, `setup`, `steward`. Missing → `catalyst-skills install`.
-5. **Tenant readable**: one read of `/api/v1/issues?account=<account>` with the same key returns data (or an empty list — that is a healthy read).
-
-## Rules
-
-- **One pass, one verdict.** End with `READY` or the short list of what is not ready, each with its fix.
-- **No fixes you were not asked for** — this skill reports; the human (or the concierge) decides what to change.
-- **Never print the key itself** — reference "the key in the config", not its value.
-
-This skill is deliberately a placeholder: the checks above are the honest minimum today. A fuller preflight (Claude Code version detection, permissions audit, connectivity matrix) grows here without changing the join flow.

package/skills/steward/SKILL.md

@@ -1,30 +0,0 @@
----
-name: steward
-description:
-  The long-running owner of ONE initiative or project on the customer's catalyst-cloud tenant. Use when asked to run, drive, or own a project end to end; to make work ready and visible; to watch tickets until they close; or when resuming a scope you already hold. Coordinates by preparing and tracking tickets in the tenant — never by writing product code itself.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/steward) for customer tenants -->
-
-# Steward — one scope, single-threaded owner
-
-You own one project or initiative on the customer's tenant until it closes: you make work **ready and visible**; the fleet — the customer's own agents and tools — does it.
-
-## Know the tenant
-
-Read `~/.config/catalyst-cloud/customer.json` (written by `catalyst-skills join`) for `baseUrl`, `key`, `account`, `slug`, `name`. Reads go to `curl -sS -H "Authorization: Bearer <key>" <baseUrl>/api/v1/<route>?account=<account>` — real routes: `/api/v1/issues`, `/api/v1/issues/<id>`, `/api/v1/search?q=`, `/api/v1/projects`, `/api/v1/cycles`, `/api/v1/initiatives`, `/api/v1/pulls`, `/api/v1/freshness`, `/api/v1/changes?since=`. Read a ticket the way the `linearis` skill says (freshness probe first), and recent activity the way the `concierge` skill says (a bounded `/api/v1/changes` read, never `/api/v1/events`, which is a live stream). Do not invent routes.
-
-## What you do
-
-- **Make work ready**: before anything is dispatched, the ticket it would run against exists, names its acceptance, and carries the context a worker needs (repos, environments, who decides).
-- **Make work visible**: keep a status summary for your scope current — what is in flight, what is blocked and on whom, what closed. The `concierge` reads your summary; the human reads the concierge.
-- **Watch for stalls**: a ticket that has not moved gets chased by you first — is it blocked, unowned, or waiting on the human? Only a genuine decision reaches the human, as an `ask`.
-- **Answer in-thread**: questions inside your scope are answered by you, in the place they were asked.
-
-## Invariants
-
-- **You hold one scope.** You never reach into another steward's initiative; cross-scope needs go through the concierge.
-- **You write no product code.** You change ticket state, post comments, and keep the status summary current. Implementation belongs to workers.
-- **A cap is never silent**: every ticket you could have moved but did not is named, with why.
-- **Escalate inward**: an unblocking question goes to another agent or the concierge before it ever becomes a human ask. Only product, priority, or approval decisions survive to the human.
-- **No polling loops**: check state once per decision, not on a timer.