@ketecode/loom 0.0.0-stage → 0.1.0

package/scripts/lib/skills.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter } = require('./frontmatter');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const SKILLS_DIR = path.join(REPO_ROOT, 'skills');
+const AGENTS_DIR = path.join(REPO_ROOT, 'agents');
+const COMMANDS_DIR = path.join(REPO_ROOT, 'commands');
+const HOOKS_DIR = path.join(REPO_ROOT, 'hooks');
+const RULES_DIR = path.join(REPO_ROOT, 'rules');
+
+const csv = (s) => (s || '').split(',').map((x) => x.trim()).filter(Boolean);
+
+// Reads one markdown item (SKILL.md, AGENT.md or a command file). `dir` is the item's name.
+function loadDoc(file, extra) {
+  const text = fs.readFileSync(file, 'utf8');
+  const { data, body, errors } = parseFrontmatter(text);
+  const meta = (data && data.metadata) || {};
+  return {
+    file,
+    text,
+    body,
+    data: data || {},
+    parseErrors: errors,
+    name: data && data.name,
+    description: data && data.description,
+    version: meta['kete-loom/version'],
+    category: meta['kete-loom/category'],
+    risk: meta['kete-loom/risk'],
+    requires: csv(meta['kete-loom/requires']),
+    tools: meta['kete-loom/tools'] === undefined ? null : csv(meta['kete-loom/tools']),
+    argumentHint: meta['kete-loom/argument-hint'],
+    event: meta['kete-loom/event'],
+    paths: csv(meta['kete-loom/paths']),
+    ...extra,
+  };
+}
+
+function listFolders(root, file, load) {
+  if (!fs.existsSync(root)) return [];
+  return fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(root, d.name, file)))
+    .map((d) => load(path.join(root, d.name)))
+    .sort((a, b) => a.dir.localeCompare(b.dir));
+}
+
+function loadSkill(skillPath) {
+  return loadDoc(path.join(skillPath, 'SKILL.md'), { kind: 'skill', dir: path.basename(skillPath), path: skillPath });
+}
+
+function loadAgent(agentPath) {
+  return loadDoc(path.join(agentPath, 'AGENT.md'), { kind: 'agent', dir: path.basename(agentPath), path: agentPath });
+}
+
+function loadHook(hookPath) {
+  return loadDoc(path.join(hookPath, 'HOOK.md'), { kind: 'hook', dir: path.basename(hookPath), path: hookPath });
+}
+
+function loadCommand(file) {
+  return loadDoc(file, { kind: 'command', dir: path.basename(file, '.md'), path: file });
+}
+
+function loadRule(file) {
+  return loadDoc(file, { kind: 'rule', dir: path.basename(file, '.md'), path: file });
+}
+
+const listSkills = (root = SKILLS_DIR) => listFolders(root, 'SKILL.md', loadSkill);
+const listAgents = (root = AGENTS_DIR) => listFolders(root, 'AGENT.md', loadAgent);
+const listHooks = (root = HOOKS_DIR) => listFolders(root, 'HOOK.md', loadHook);
+
+function listFiles(root, load) {
+  if (!fs.existsSync(root)) return [];
+  return fs
+    .readdirSync(root)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => load(path.join(root, f)))
+    .sort((a, b) => a.dir.localeCompare(b.dir));
+}
+
+const listCommands = (root = COMMANDS_DIR) => listFiles(root, loadCommand);
+const listRules = (root = RULES_DIR) => listFiles(root, loadRule);
+
+module.exports = { REPO_ROOT, SKILLS_DIR, AGENTS_DIR, COMMANDS_DIR, HOOKS_DIR, RULES_DIR, listSkills, listAgents, listCommands, listHooks, listRules, loadSkill, loadAgent, loadCommand, loadHook, loadRule };

package/scripts/lib/targets.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Where each host looks for skills, agents and commands (verified against host docs, Oct 2026).
+// `agents` is the shared open-standard folder: Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot
+// and Kete Code all read its skills. It defines nothing for agents or commands.
+// Claude Code reads only its own folders; Cursor and VS Code Copilot also read `.claude/agents`.
+// So the default install is `agents` + `claude`, plus agents and commands for hosts that need their
+// own copy (`auto`, including Kete Code) when that host is detected. The other targets exist for people who want one host only.
+// Kinds a target doesn't list are not supported there: Codex prompts are deprecated, Copilot CLI has
+// no prompt files and Cursor commands are beta, so commands go to Claude, OpenCode and Gemini only.
+const TARGETS = {
+  agents: {
+    label: 'Shared .agents folder (Codex, OpenCode, Cursor, Gemini CLI, Copilot, Kete Code)',
+    user: { skills: ['.agents', 'skills'] },
+    project: { skills: ['.agents', 'skills'] },
+    default: true,
+  },
+  claude: {
+    label: 'Claude Code (its agents are also read by Cursor and VS Code Copilot)',
+    // Rules go in a kete-loom subfolder (Claude Code scans .claude/rules recursively), so ours stay apart.
+    user: { skills: ['.claude', 'skills'], agents: ['.claude', 'agents'], commands: ['.claude', 'commands'], rules: ['.claude', 'rules', 'kete-loom'] },
+    project: { skills: ['.claude', 'skills'], agents: ['.claude', 'agents'], commands: ['.claude', 'commands'], rules: ['.claude', 'rules', 'kete-loom'] },
+    default: true,
+    hooks: true,
+  },
+  codex: {
+    label: 'Codex (agents only; skills come from .agents)',
+    user: { agents: ['.codex', 'agents'] },
+    project: { agents: ['.codex', 'agents'] },
+    detect: { user: ['.codex'], project: ['.codex'] },
+    auto: true,
+    hooks: true,
+  },
+  opencode: {
+    label: 'OpenCode',
+    user: { skills: ['.config', 'opencode', 'skills'], agents: ['.config', 'opencode', 'agents'], commands: ['.config', 'opencode', 'commands'] },
+    project: { skills: ['.opencode', 'skills'], agents: ['.opencode', 'agents'], commands: ['.opencode', 'commands'] },
+    detect: { user: ['.config', 'opencode'], project: ['.opencode'] },
+    auto: true,
+    hooks: true,
+  },
+  // Kete Code (an OpenCode fork) reads skills from .agents and .claude, but agents and commands only from its own folders.
+  // shortcut: user paths assume XDG_CONFIG_HOME is ~/.config (as for opencode); honour it if users report custom roots.
+  kete: {
+    label: 'Kete Code',
+    user: { skills: ['.config', 'kete', 'skills'], agents: ['.config', 'kete', 'agents'], commands: ['.config', 'kete', 'commands'] },
+    project: { skills: ['.kete', 'skills'], agents: ['.kete', 'agents'], commands: ['.kete', 'commands'] },
+    detect: { user: ['.config', 'kete'], project: ['.kete'] },
+    auto: true,
+    hooks: true,
+  },
+  cursor: {
+    label: 'Cursor only',
+    user: { skills: ['.cursor', 'skills'], agents: ['.cursor', 'agents'] },
+    // Cursor reads rule files only per project (user rules live in its settings UI).
+    project: { skills: ['.cursor', 'skills'], agents: ['.cursor', 'agents'], rules: ['.cursor', 'rules', 'kete-loom'] },
+    // Detected only for hooks: Cursor already reads agents from .claude.
+    detect: { user: ['.cursor'], project: ['.cursor'] },
+    hooks: true,
+  },
+  gemini: {
+    label: 'Gemini CLI',
+    user: { skills: ['.gemini', 'skills'], agents: ['.gemini', 'agents'], commands: ['.gemini', 'commands'] },
+    project: { skills: ['.gemini', 'skills'], agents: ['.gemini', 'agents'], commands: ['.gemini', 'commands'] },
+    detect: { user: ['.gemini'], project: ['.gemini'] },
+    auto: true,
+    hooks: true,
+  },
+  copilot: {
+    label: 'GitHub Copilot only',
+    user: { skills: ['.copilot', 'skills'], agents: ['.copilot', 'agents'], rules: ['.copilot', 'instructions', 'kete-loom'] },
+    project: { skills: ['.github', 'skills'], agents: ['.github', 'agents'], rules: ['.github', 'instructions', 'kete-loom'] },
+    detect: { user: ['.copilot'], project: ['.github'] },
+    hooks: true,
+  },
+};
+
+const KINDS = ['skills', 'agents', 'commands', 'rules'];
+
+// Which folders each host reads skills from, used by `doctor` to show where a skill is visible.
+const HOST_READS = {
+  'Claude Code': ['claude'],
+  Codex: ['agents'],
+  OpenCode: ['agents', 'claude', 'opencode'],
+  Cursor: ['agents', 'claude', 'cursor'],
+  'Gemini CLI': ['agents', 'gemini'],
+  'GitHub Copilot': ['agents', 'claude', 'copilot'],
+  'Kete Code': ['agents', 'claude', 'kete'],
+};
+
+function baseDir({ scope = 'user', home = os.homedir(), cwd = process.cwd() } = {}) {
+  return scope === 'project' ? cwd : home;
+}
+
+// Returns the folder for one kind, or null when the target doesn't support that kind.
+function resolveTarget(name, { scope = 'user', home = os.homedir(), cwd = process.cwd(), kind = 'skills' } = {}) {
+  const t = TARGETS[name];
+  if (!t) throw new Error(`unknown target "${name}". Known: ${Object.keys(TARGETS).join(', ')}`);
+  const segments = t[scope === 'project' ? 'project' : 'user'][kind];
+  return segments ? path.join(baseDir({ scope, home, cwd }), ...segments) : null;
+}
+
+function detected(name, opts = {}) {
+  const t = TARGETS[name];
+  const segments = t.detect && t.detect[opts.scope === 'project' ? 'project' : 'user'];
+  return Boolean(segments) && fs.existsSync(path.join(baseDir(opts), ...segments));
+}
+
+module.exports = { TARGETS, KINDS, HOST_READS, resolveTarget, detected };

package/skills/accounting-api-integration/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: accounting-api-integration
+description: Connects an application's sales and payments to QuickBooks Online and Xero through their accounting APIs, handling the OAuth 2.0 authorisation code flow with rotating refresh tokens, per-company realm or tenant IDs, chart of accounts and tax code mapping, posting customers, invoices, payments and credit notes, safe retries with requestid or Idempotency-Key, HMAC-verified webhooks, 429 rate-limit backoff, and nightly reconciliation against the ledger. Use when building a QuickBooks or Xero sync, fixing duplicate or missing invoices in the books, debugging invalid_grant or token expiry, mapping products to income accounts, or reconciling app revenue with what the accountant sees.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to quickbooks.api.intuit.com (or the sandbox) and api.xero.com. Examples are HTTP and TypeScript-like pseudocode; official SDKs exist for most languages.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Accounting API integration (QuickBooks Online, Xero)
+
+Push your app's financial events into the customer's books exactly once, mapped to accounts their accountant chose, and prove it with a reconciliation. Your app stays the source of truth for what was sold; the ledger is the source of truth for the books. API detail: `references/quickbooks.md` and `references/xero.md`.
+
+## Ground rules
+
+1. **One connection per company.** QuickBooks identifies a company by `realmId`; Xero by tenant ID (send `xero-tenant-id` on every call). Store tokens per connection, encrypted at rest, never in logs.
+2. **Refresh tokens rotate.** Each refresh can return a new refresh token; store it atomically before using the new access token, and serialise refreshes per connection (a lock), or two workers will race and one gets `invalid_grant`. Treat `invalid_grant` as "reconnect needed": mark the connection, alert the user, stop syncing it.
+3. **Accounts are mapped, never guessed.** The customer (or their accountant) maps each of your product types, discounts, fees, tax rates and payment methods to an account, item and tax code in their ledger. Store the mapping by remote ID, not name. Block syncing until it is complete.
+4. **Every write is idempotent.** QuickBooks: a unique `requestid` query parameter per logical operation. Xero: an `Idempotency-Key` header. Derive the key from your own record (`invoice:<id>:create`), never a fresh random value per retry. Also store the remote ID on your record and check it before creating.
+5. **Your record links to the remote record.** Keep `remote_id`, `remote_type`, last sync status and error per record, so you can resume, update and reconcile.
+6. **Don't post what the ledger already has.** If the customer's payment provider has its own QuickBooks or Xero feed, agree with the user which system posts what, or invoices and payments appear twice.
+7. **Rate limits are mostly per company.** Queue writes per connection, back off on `429` (honour `Retry-After` where Xero sends it; QuickBooks says wait 60 seconds), and batch where the API supports it. Xero also has an app-wide per-minute limit across all tenants.
+8. **Sandbox first.** QuickBooks sandbox companies and a Xero demo company; never test against a customer's live books.
+
+## Workflow
+
+1. **Confirm scope with the user**: which provider(s), which objects flow (customers, invoices, payments, credit notes, refunds, fees, payouts), one-way or two-way, and start date for the backfill. Stop and ask if two-way: conflict rules are a product decision.
+2. **OAuth 2.0 authorisation code flow** with a `state` value bound to the user's session, the minimum scopes, and a callback that stores tokens and the realm or tenant. Endpoints and scopes in the references.
+3. **Read the chart of accounts and tax codes** and present a mapping screen. Validate mapped accounts are active and of the right type (income for sales lines, bank or undeposited funds for payments).
+4. **Sync customers** (look up by your external ID or email first; create if absent).
+5. **Post invoices** with lines carrying the mapped item/account and tax code, your invoice number, dates and currency. Amounts must match your invoice exactly; send line amounts and tax as computed by your billing or tax system rather than letting the ledger recompute them when the API allows it, and verify the total on the response.
+6. **Post payments** linked to the invoice, into the mapped deposit account, on the actual payment date. Post refunds and credit notes as their own objects linked to the original.
+7. **Webhooks** (optional, for changes made in the ledger): verify the HMAC signature on the raw body, respond fast, then fetch the changed records by ID. Payloads carry IDs, not trusted data.
+8. **Reconcile nightly** (below), and surface failures to the user with the remote error message.
+
+## Updates and conflicts
+
+- QuickBooks updates need the current `SyncToken`; read, modify, write, and on a stale-object error re-read and retry once.
+- Don't update invoices that are paid, or in a locked period: QuickBooks and Xero both support closing dates/lock dates and will reject or warn. Stop and ask the user how to handle changes to a closed period; usually a credit note in the current period.
+- Deleting or voiding in the ledger is the accountant's call. Never auto-delete remote records.
+
+## Reconciliation
+
+For each connection, for a date range:
+
+1. Count and sum your invoices, payments and credit notes by currency.
+2. Query the same in the ledger (QuickBooks query endpoint; CDC only looks back 30 days; Xero list endpoints with `where` filters, paging and `If-Modified-Since`).
+3. Match by stored remote ID; list missing-remote, missing-local, and amount or status mismatches.
+4. Retry missing-remote ones idempotently; report the rest to the user. Don't "fix" amounts in the ledger automatically.
+
+## Errors to recognise
+
+| Symptom | Likely cause |
+|---|---|
+| `invalid_grant` on refresh | Refresh token already used (race), revoked, or expired; reconnect |
+| `401` or `403` with a fresh token (Xero) | Missing scope (`401`, `WWW-Authenticate` names `insufficient_scope`), or `xero-tenant-id` missing, wrong or no longer authorised (`403 AuthenticationUnsuccessful`); call `/connections` to check |
+| Duplicate invoices | Retry without idempotency key, or key regenerated per attempt; or the payment provider's own feed also posts |
+| Total differs by a cent | Ledger recomputed tax with its own rounding; send tax explicitly or align rounding rules |
+| Stale object (QuickBooks) | Old `SyncToken`; re-read and retry |
+| `429` | Per-company rate limit; slow the queue for that connection |
+
+## Never
+
+- Never log access or refresh tokens, or webhook verifier keys.
+- Never post to a ledger without a completed account mapping.
+- Never create a record without first checking for an existing remote ID or idempotency key.
+- Never write to a closed period or delete accountant-entered data.
+
+## Report format
+
+```
+Connection: <provider, realm/tenant, scopes>
+Objects synced: <type: direction, trigger>
+Mapping: <complete | gaps listed>
+Idempotency: <how keys are derived>
+Reconciliation <range>: local <count/sum> vs ledger <count/sum>; mismatches <list>
+Needs user/accountant decision: <list>
+```

package/skills/accounting-api-integration/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Sync our app's invoices and payments into QuickBooks Online for each customer company that connects",
+    "Our Xero refresh keeps failing with invalid_grant after a few days when two workers run at once",
+    "Build a screen where the accountant maps our product types to their Xero chart of accounts and tax rates",
+    "Retries are creating duplicate invoices in QuickBooks; how do we make the posting idempotent?",
+    "Verify the intuit-signature header on QuickBooks webhooks and fetch the changed invoices",
+    "We hit 429 errors from the Xero API during our nightly backfill of 20,000 invoices"
+  ],
+  "should_not_trigger": [
+    "Set up Stripe webhooks so we fulfil orders when checkout.session.completed arrives",
+    "How should VAT be shown on invoices to EU business customers under reverse charge?",
+    "Design our dunning emails and retry schedule for failed card renewals",
+    "Prepare the month-end close checklist and journal entries for our finance team",
+    "Review our billing code for proration and timezone bugs before release"
+  ]
+}

package/skills/accounting-api-integration/references/quickbooks.md

@@ -0,0 +1,48 @@
+# QuickBooks Online Accounting API
+
+Check developer.intuit.com for current details; Intuit changes OAuth policy and webhook formats from time to time. Facts below were checked against Intuit's docs in October 2026: [OAuth 2.0 setup](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0), [minor versions](https://developer.intuit.com/app/developer/qbo/docs/learn/explore-the-quickbooks-online-api/minor-versions), [limits and throttles](https://static.developer.intuit.com/output_html/qbo/docs/learn/limits-and-throttles.html), [change data capture](https://developer.intuit.com/app/developer/qbo/docs/learn/explore-the-quickbooks-online-api/change-data-capture), [configure webhooks](https://developer.intuit.com/app/developer/qbo/docs/develop/webhooks/configure-webhooks) and the [release notes](https://developer.intuit.com/app/developer/qbo/docs/release-notes/general-release-notes).
+
+## OAuth 2.0
+
+- Authorise: `https://appcenter.intuit.com/connect/oauth2` with `client_id`, `response_type=code`, `scope=com.intuit.quickbooks.accounting`, `redirect_uri`, `state`.
+- Token exchange and refresh: `POST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer` (Basic auth with client ID and secret).
+- The callback receives `code`, `state` and `realmId`. Store `realmId` with the tokens.
+- Access tokens last one hour (`expires_in` starts at 3600). Refresh tokens have a rolling 100-day expiry, the value can change on any refresh, and they now have a maximum lifetime of five years; the token response reports the remaining time in `x_refresh_token_expires_in` and `x_refresh_token_hard_expires_in` (seconds). Always store the refresh token returned by the latest refresh, and plan a reconnect before the hard expiry. The developer portal has a reconnect URL field for when users must re-authorise.
+
+## Base URLs
+
+- Production: `https://quickbooks.api.intuit.com/v3/company/{realmId}/...`
+- Sandbox: `https://sandbox-quickbooks.api.intuit.com/v3/company/{realmId}/...`
+- Send `Accept: application/json`. Support for minor versions 1–74 ended on 1 Aug 2025; a `minorversion` below 75, or none, is answered as minor version 75. Pin `minorversion` explicitly and test before raising it.
+
+## Core entities
+
+| Need | Entity / endpoint |
+|---|---|
+| Accounts | `Account` via `GET /query?query=select * from Account where Active = true` |
+| Products and services | `Item` (each links to an income account) |
+| Tax | `TaxCode`, `TaxRate` (behaviour differs between US and non-US companies) |
+| Customers | `Customer` |
+| Invoices | `POST /invoice` with `CustomerRef`, `Line[]` (`DetailType: SalesItemLineDetail`, `SalesItemLineDetail.ItemRef`, `Amount`), `DocNumber`, `TxnDate`, `CurrencyRef` |
+| Payments | `POST /payment` with `CustomerRef`, `TotalAmt`, `Line[].LinkedTxn[{ TxnId, TxnType: "Invoice" }]`, `DepositToAccountRef` |
+| Credit notes | `CreditMemo`; refunds `RefundReceipt` |
+| Changes since | `GET /cdc?entities=Invoice,Payment&changedSince=<ISO time>` (look-back limited to 30 days; use `/query` for older ranges) |
+| Batch | `POST /batch` with several operations in one request (Intuit's batch page says up to 10 payloads; its limits page recommends at most 30; keep batches small) |
+
+Updates: send `Id` and the current `SyncToken`; add `"sparse": true` to change only the fields you send. A stale `SyncToken` returns a stale object error.
+
+## Idempotency
+
+Add `?requestid=<unique id>` to write requests. A repeat with the same `requestid` for the same company returns the original response instead of creating a duplicate. Use a deterministic ID per logical operation, unique per company. Maximum length is 50 characters (36 for batch requests), so hash long keys. Intuit does not publish how long it remembers a request ID, so also check for the remote record before retrying a create.
+
+## Rate limits
+
+Intuit documents 500 requests per minute per realm ID and 10 requests per second per realm ID and app; batch calls are throttled at 40 per minute per realm ID and app. Requests taking over 120 seconds time out. On `429`, Intuit says to wait 60 seconds before retrying; retry with the same `requestid`.
+
+## Webhooks
+
+- Configure the endpoint and entities in the developer portal; it shows a verifier token per environment.
+- Verify: HMAC-SHA256 of the raw request body keyed with the verifier token, base64-encoded, compared in constant time to the `intuit-signature` header. Reject if the header is missing or the token is unset.
+- Payloads now use the CloudEvents format: a JSON array of events, each with `type` (for example `qbo.invoice.created.v1`), `intuitentityid` and `intuitaccountid` (the realm ID). One notification can carry events for several companies, so route each event by its realm. The legacy format's retirement date moved more than once; check Intuit's current webhook docs if you still receive the old shape.
+- Payloads carry entity types, IDs and operations, not the record. Fetch the entity, or use CDC, to get the data.
+- Respond quickly with `200` and process asynchronously; also run CDC periodically, because webhooks can be missed.

package/skills/accounting-api-integration/references/xero.md

@@ -0,0 +1,45 @@
+# Xero Accounting API
+
+Check developer.xero.com for current details, especially scopes, which changed in 2026. Facts below were checked in October 2026 against Xero's [token types](https://developer.xero.com/documentation/guides/oauth2/token-types/), [scopes](https://developer.xero.com/documentation/guides/oauth2/scopes/), [granular scopes FAQ](https://developer.xero.com/faq/granular-scopes), [limits](https://developer.xero.com/documentation/guides/oauth2/limits/), [idempotency](https://developer.xero.com/documentation/guides/idempotent-requests/idempotency/), [troubleshooting](https://developer.xero.com/documentation/guides/oauth2/troubleshooting/) and [webhooks](https://developer.xero.com/documentation/guides/webhooks/overview/) pages.
+
+## OAuth 2.0
+
+- Authorise: `https://login.xero.com/identity/connect/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state`.
+- Token exchange and refresh: `POST https://identity.xero.com/connect/token`.
+- Include `offline_access` to get a refresh token. Access tokens last up to 30 minutes. Refresh tokens are valid for up to 60 days and rotate on every use; always store the newest one. If you lose the response, the previous refresh token still works for a 30-minute grace period, then the user must re-authorise.
+- After authorising, `GET https://api.xero.com/connections` lists the tenants the user connected. Store each `tenantId`; send it as `xero-tenant-id` on every API call. A user can connect several organisations.
+- **Scopes**: apps created on or after 2 March 2026 use granular scopes (for example `accounting.invoices` instead of the broad `accounting.transactions`). Older apps can request granular scopes from April 2026 and can keep broad scopes until September 2027; existing tokens only gain new scopes when the user re-authorises. Calling an endpoint without the needed scope returns `401` with a `WWW-Authenticate` header naming `insufficient_scope`.
+
+## Base URL
+
+`https://api.xero.com/api.xro/2.0/...` with `Authorization: Bearer <token>`, `xero-tenant-id`, `Accept: application/json`.
+
+## Core endpoints
+
+| Need | Endpoint |
+|---|---|
+| Accounts | `GET /Accounts` (use `Code` or `AccountID`; check `Status` is `ACTIVE`) |
+| Tax rates | `GET /TaxRates` (`TaxType` values go on lines) |
+| Items | `GET/POST /Items` |
+| Contacts | `GET/POST /Contacts` (search by `ContactNumber` or email before creating) |
+| Invoices | `POST /Invoices` (create or update) with `Type: "ACCREC"`, `Contact.ContactID`, `Date`, `DueDate`, `InvoiceNumber`, `LineAmountTypes` (`Exclusive`, `Inclusive`, `NoTax`), `LineItems[]` (`Description`, `Quantity`, `UnitAmount`, `AccountCode`, `TaxType`, optionally `TaxAmount`), `Status` (`DRAFT`, `SUBMITTED`, `AUTHORISED`), `CurrencyCode` |
+| Payments | `PUT /Payments` with `Invoice.InvoiceID`, `Account.Code` or `AccountID` (a bank account or one with payments enabled), `Amount`, `Date` |
+| Credit notes | `POST /CreditNotes` with `Type: "ACCRECCREDIT"`; allocate to an invoice with `PUT /CreditNotes/{id}/Allocations` |
+| Changes since | `If-Modified-Since` header on list endpoints, plus `where` filters and paging |
+
+Send several records in one request where the endpoint accepts an array; add `?SummarizeErrors=false` to get a status and validation errors per record instead of failing the whole batch. List endpoints page with `?page=` and `pageSize` (default 100, maximum 1000). Some changes (for example `DueDate` or `SentToContact` on paid transactions) don't update `UpdatedDateUTC`, so `If-Modified-Since` can miss them.
+
+## Idempotency
+
+Send an `Idempotency-Key` header (at most 128 characters) on `POST`, `PUT` and `PATCH`; other methods ignore it. Use a deterministic key per logical operation and keep it for retries. Xero keeps keys for only 6 minutes, and reusing a key with a different request returns `400`, so for retries after that window rely on the stored remote ID check, not the key.
+
+## Rate limits
+
+Per tenant: 5 concurrent calls, 60 calls per minute, and a daily limit of 1,000 calls on the starter tier or 5,000 on higher tiers; plus an app-wide limit of 10,000 calls per minute across all tenants. Responses include `X-DayLimit-Remaining`, `X-MinLimit-Remaining` and `X-AppMinLimit-Remaining`. A `429` carries `X-Rate-Limit-Problem` naming the limit hit, and `Retry-After` (seconds) when the minute or daily limit was exceeded.
+
+## Webhooks
+
+- Configure in the developer portal; it gives a webhook key.
+- Verify: HMAC-SHA256 of the raw request body keyed with the webhook key, base64-encoded, compared in constant time to the `x-xero-signature` header. Return a `2xx` for a valid signature and `401` for an invalid one, over HTTPS on port 443, within 5 seconds, with no cookies in the response.
+- "Intent to receive": when you set up the endpoint, Xero sends test requests, some with bad signatures, and only activates the webhook if you answer correctly. Process events asynchronously. Xero retries failed deliveries and disables the webhook after 24 hours of failures.
+- Events carry `resourceId`, `eventCategory` (for example `INVOICE`, `CONTACT`), `eventType` and `tenantId`. Fetch the resource by ID; don't trust the payload as data.

package/skills/agent-harness-design/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: agent-harness-design
+description: Architecture for the loop around an LLM agent, covering which tools to give it, how to manage and compact its context window, plan-act-verify cycles, permission tiers and sandboxing, tracing and cost limits, and recovery when steps fail or the agent loops. Use when you are building or debugging the harness of a coding agent, task-automation agent or other tool-calling loop (not tuning your own session), or when the agent you built forgets earlier work, runs dangerous commands, or stops before the job is done.
+license: MIT
+compatibility: Any Agent Skills host. Framework-agnostic; examples are pseudocode.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Agent harness design
+
+The harness is everything except the model: the loop, the tools, what goes into context, what the agent may do, and how you know what it did. Most agent failures are harness failures. Fix the harness before swapping models or rewriting the prompt.
+
+## 0. Pin down the job first
+
+Write these down, and **stop and ask the user** for any you can't infer:
+
+1. The task family (fix failing tests, triage tickets, research and report) and one concrete example task.
+2. What "done" means in a way a program can check (tests pass, a file exists with fields X, a PR is open).
+3. What the agent must never do (push to main, spend money, email customers, touch production).
+4. Who watches: interactive with a human approving steps, or unattended.
+5. Budget: maximum steps, wall-clock time and token or dollar cost per task.
+
+## 1. The loop
+
+```
+context = system_prompt + task + tool_definitions
+for step in 1..max_steps:
+    response = model(context)
+    if response has no tool calls:
+        if verify(task) passes: return success
+        context += "Verification failed: <output>. Continue."; continue
+    for call in response.tool_calls:
+        if not permitted(call): result = denied_message(call)
+        else: result = run_with_timeout(call)
+        context += truncate(result)
+    if budget_exceeded or no_progress(last_n_steps): stop_and_report
+return stopped(reason="max_steps")
+```
+
+Rules:
+
+- The loop ends on **verified** success, a budget limit, or a stop condition. Never on the model merely saying it is done.
+- Every tool call has a timeout. A hung command must return an error result, not hang the loop.
+- Feed errors back as tool results so the model can recover. Don't crash the harness on a tool error.
+- Detect loops: the same tool call with the same arguments three times, or N steps with no new file change or new information, triggers a stop or a forced re-plan.
+
+## 2. Tools
+
+- Start with few, general, well-described tools: read file, search (by name and by content), edit file (by exact replacement or patch), run command, and optionally fetch URL. Add a specialised tool only when traces show the model repeatedly failing at a job a tool would make reliable.
+- Each tool returns compact, model-readable output with explicit truncation markers: `[output truncated: 4,812 more lines; use offset=200 to read on]`.
+- Edits should fail loudly when the target text isn't found or isn't unique, and should never silently rewrite a whole file the model hasn't read.
+- Prefer structured results (exit code, stdout, stderr separated) over a merged blob.
+- Tool descriptions say when to use the tool and when to use a sibling instead. Tool naming and schema rules for MCP-based tools are covered by the `mcp-server-patterns` skill.
+
+## 3. Context management
+
+The context window is the agent's working memory. Budget it.
+
+- Put stable material first (system prompt, tool definitions, project instructions) so provider prompt caching can reuse it; append the conversation after.
+- Load project knowledge on demand: a short index of available docs or skills in context, full text only when the model asks for it.
+- Truncate large tool outputs at the source and let the model page through. Never paste a whole log or file by default.
+- When the context nears its limit, compact: summarise completed steps (decisions, files changed, open questions, current plan) into a short state note, keep the last few turns verbatim, and drop the rest. Test that a compacted agent can still finish a task.
+- Keep durable state outside the context: a plan or todo file, a scratch notes file, git commits. The agent re-reads them after compaction or restart.
+- For large searches or research, run a sub-agent in its own context and return only its summary to the parent.
+
+## 4. Planning and verification
+
+- For tasks over a few steps, have the agent write a short plan (numbered steps, each with how it will be checked) before acting, and update it as it goes.
+- Verification is a command, not an opinion: run the tests, the type checker, the linter, a script that checks the output. The harness runs `verify` itself at the end; the model's claim of success is not enough.
+- Require the agent to reproduce a bug (a failing test or command) before fixing it, and re-run that same check after.
+- For unattended runs, add a final review step: a separate model call (or sub-agent) reads the diff against the task and lists gaps.
+
+## 5. Permissions and sandboxing
+
+Tier every action and enforce the tier in the harness, not in the prompt:
+
+| Tier | Examples | Default |
+|---|---|---|
+| Read | read files, search, list, `git status`, `git diff` | allow |
+| Local write | edit files in the workspace, run tests and builds | allow in a sandbox; ask when interactive and outside the sandbox |
+| External or irreversible | `git push`, deploys, package publish, network calls to new hosts, sending messages, payments, deleting outside the workspace | always ask a human, or deny when unattended |
+
+- Run commands in a sandbox: a container or VM, or an OS sandbox, with the workspace as the only writable directory and network off or restricted to an allowlist.
+- Keep secrets out of the sandbox. If a task needs a credential, inject a scoped, short-lived one, and never echo it into the context.
+- Allowlist commands by parsed program and arguments, not by string prefix (`git status; rm -rf ~` starts with `git status`).
+- Treat content the agent reads (web pages, issues, files from the repo, tool results) as untrusted. It can contain instructions. Permissions must hold even if the model is fully convinced by injected text.
+- Log every denial; frequent denials mean the tier rules or the tool set are wrong.
+
+## 6. Observability
+
+- Trace every step: model input size, output, each tool call with arguments, result size, duration, exit code, tokens and cost. Store traces per task with a run id.
+- Record the final outcome against the "done" check from step 0, so you can compute a success rate per task family.
+- Keep a small benchmark of real tasks with checkable outcomes and re-run it on every harness, prompt, tool or model change. Report success rate, median steps and cost, and the tasks that regressed. The `llm-evals` skill covers scoring in depth.
+
+## 7. Failure recovery
+
+- Retry transient tool and API failures (rate limits, timeouts, 5xx) with backoff and a cap. Do not retry the model's own wrong action unchanged.
+- Checkpoint progress (commit to a work branch, save the plan file) so a crashed run resumes instead of restarting.
+- On a stop condition, return a structured report: what was done, what was verified, what failed, what's left, and the last error. Never report partial work as success.
+- If the same task fails the same way across runs, read the traces before changing anything; the fix is usually a tool's output format, a missing tool, or a missing instruction.
+
+## Never
+
+- Never let the model's "I'm done" end the loop without the harness running verification.
+- Never enforce permissions only through the system prompt.
+- Never give an unattended agent push, deploy, payment or messaging rights without a human gate.
+- Never run agent commands on a host with the user's real credentials and home directory writable.
+- Never change harness, prompt and model at once; change one and re-run the benchmark.
+
+## Report format
+
+When you design or change a harness, report:
+
+```
+Task family: <...>   Done check: <command or rule>
+Tools: <list>   Max steps / time / cost: <...>
+Permission tiers: read=<allow> write=<...> external=<...>   Sandbox: <...>
+Context strategy: <truncation, compaction trigger, external state>
+Benchmark: <n tasks> success <before> → <after>, median cost <before> → <after>
+Known gaps: <...>
+```

package/skills/agent-harness-design/evals/triggers.json

@@ -0,0 +1,21 @@
+{
+  "should_trigger": [
+    "Design the tool set and agent loop for a coding agent that fixes failing CI builds",
+    "Our in-house agent framework loses track of finished steps after it compacts the context, how should the harness keep state?",
+    "How do I sandbox shell commands my task agent runs and decide which need human approval?",
+    "The agent says it's finished but the tests still fail, how do we add a verification loop?",
+    "Add tracing and cost limits to our tool-calling agent so runaway loops get stopped",
+    "We're building an autonomous ticket-triage agent, what should the harness look like?"
+  ],
+  "should_not_trigger": [
+    "Write an MCP server that exposes our Postgres database as tools",
+    "Build a RAG pipeline over our help center articles with citations",
+    "Score our agent's transcripts against a rubric and track pass rate over time",
+    "Run several sub-agents in parallel to refactor these five modules",
+    "Rewrite this system prompt so the model follows the output format",
+    "Plan the implementation of a new billing feature step by step",
+    "My Claude Code session is nearly out of context, what should I drop or summarise?",
+    "Set up a loop that keeps re-running the agent overnight until every test passes",
+    "Write a handoff note so the next session can pick up where I stopped"
+  ]
+}