@ketecode/loom 0.1.0 → 0.2.0

package/skills/git-worktrees/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Set up a separate worktree for the search-filters feature so my main checkout stays clean",
+    "I want to work on two branches at once without stashing, use git worktree",
+    "Before you start executing this plan, give yourself an isolated workspace on a new branch",
+    "Create a worktree under .worktrees for the billing refactor and make sure the tests pass there first",
+    "Remove the old worktrees I'm done with and prune the stale ones"
+  ],
+  "should_not_trigger": [
+    "My rebase onto main hit conflicts in three files, help me resolve them",
+    "Write commit messages for these staged changes in conventional commit format",
+    "The feature is done and tests pass, merge it or open a PR",
+    "Set up a devcontainer so everyone gets the same toolchain",
+    "Recover the commits I lost after a hard reset yesterday"
+  ]
+}

package/skills/google-workspace-integration/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: google-workspace-integration
+description: Calls the Google Drive v3, Docs, Sheets and Slides REST APIs from application code, covering the choice between user OAuth, a service account and domain-wide delegation, the narrowest scopes (drive.file before restricted drive), files.list queries with shared-drive flags, documents and presentations batchUpdate requests applied in descending index order, Sheets A1 ranges with valueInputOption, and per-minute quotas handled with truncated exponential backoff on 429 and 403 rate errors. Use when code must create, read, fill or export Google Docs, Sheets, Slides or Drive files, a service account gets 403 or storageQuotaExceeded, or a Workspace sync hits rate limits.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to googleapis.com and a Google Cloud project with the APIs enabled. Examples use the official googleapis client libraries; the rules apply to raw REST too.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Google Workspace integration
+
+Build Drive, Docs, Sheets and Slides automation that asks for the least access, acts as the right identity, survives quota limits and does not corrupt documents with misplaced indexes. For Cloud IAM, Cloud Run and other Google Cloud infrastructure use `gcp-patterns`; this skill is about Workspace content APIs.
+
+## Ground rules
+
+1. **Pick the identity first** (table below). It decides scopes, file ownership and whether an admin must be involved.
+2. **Narrowest scope that works.** `drive.file` (only files the app created or the user opened with it) is non-sensitive; `drive`, `drive.readonly` and `drive.metadata*` are restricted and need Google's restricted-scope verification for a public app. Prefer `spreadsheets`, `documents` or `presentations` plus `drive.file` over full `drive`.
+3. **Credentials stay out of code.** OAuth client secrets, refresh tokens and service account key JSON come from a secret store or environment. Prefer keyless service account auth (attached service account, Workload Identity Federation) over downloaded key files.
+4. **Batch, and treat a batch as one unit.** Sheets, Docs and Slides `batchUpdate` apply all requests atomically: one invalid request means none apply. Each batch counts as one request against quota.
+5. **Back off on rate errors.** Retry 429, and 403 with reason `userRateLimitExceeded` or `rateLimitExceeded`, plus 5xx, with truncated exponential backoff: wait `min(2^n seconds + random up to 1000 ms, 32 to 64 s)`, then give up after a bounded number of tries. Never retry 400, 401 or a 403 for permissions.
+6. **Ask only for the fields you use.** Pass `fields` on Drive and Docs reads (`files(id,name,mimeType,modifiedTime),nextPageToken`); it cuts payload and latency.
+
+## Choose the identity
+
+| Situation | Use |
+|---|---|
+| Users act on their own files (an add-on, a "connect Google Drive" button) | OAuth 2.0 user consent, offline access for a refresh token, incremental scopes |
+| A backend job owns its own documents or works in a team folder | Service account; give it access by sharing a **shared drive** or folder with its email |
+| A Workspace org's backend must act as many users without each consenting | Service account with **domain-wide delegation**: a super admin authorises the client ID and an exact scope list in the Admin console (API controls); the code impersonates a user with `subject` |
+
+Service accounts have no Drive storage of their own: creating files in a My Drive folder shared with them fails with `storageQuotaExceeded`. Put the work in a shared drive, or impersonate a real user with delegation. Cloud IAM roles do not grant access to Workspace files; sharing does.
+
+## Implementation steps
+
+1. **Project setup**: enable each API (Drive, Docs, Sheets, Slides) in the Google Cloud project, configure the OAuth consent screen with only the scopes you request, and create the OAuth client or service account.
+2. **Auth client**: build it once and reuse it; the libraries refresh access tokens. For delegation, set the subject user per request and keep the scope list identical to the one the admin approved, or token requests fail with `unauthorized_client`.
+3. **Drive**: find files with `files.list` and a `q` query; page with `pageToken` until `nextPageToken` is absent. For shared drives pass `supportsAllDrives=true` and `includeItemsFromAllDrives=true` (plus `corpora`/`driveId`), or results silently miss them. Create Google-native files by setting `mimeType` (for example `application/vnd.google-apps.document`). Export with `files.export` (10 MB cap on exported content). Query syntax and MIME types in `references/api.md`.
+4. **Sheets**: read and write values with `spreadsheets.values.get/update/append/batchGet/batchUpdate`. Write with `valueInputOption` `RAW` (stored literally) or `USER_ENTERED` (parsed like typing: formulas, dates). Read with `valueRenderOption` `UNFORMATTED_VALUE` when you need numbers, not display strings. Formatting, new tabs and protected ranges go through `spreadsheets.batchUpdate`, which addresses sheets by numeric `sheetId`, not title. A1 rules in `references/api.md`.
+5. **Docs**: `documents.get` returns a structure of elements with `startIndex`/`endIndex`; body text starts at index 1. In one `documents.batchUpdate`, order inserts and deletes from the highest index to the lowest so earlier edits don't shift later ones. For templates prefer `replaceAllText` on placeholders like `{{customer_name}}`. Pass `writeControl.requiredRevisionId` from your read to refuse a write if someone edited the doc in between.
+6. **Slides**: copy a template deck with Drive `files.copy`, then `presentations.batchUpdate` with `replaceAllText` and `replaceAllShapesWithImage` (image must be a public PNG, JPEG or GIF URL). Custom `objectId`s are 5 to 50 characters and unique in the deck.
+7. **Retries and idempotency**: wrap every call in the backoff helper. A retried create can make a second file, so before creating, search for an existing file by a stable name or an `appProperties` key you set, or generate IDs first with `files.generateIds` and create with that ID.
+8. **Watch for changes** with `changes.watch` or `files.watch` push channels to an HTTPS endpoint, or poll `changes.list` with a saved `startPageToken`. Channels expire; renew them before expiry.
+
+## Reviewing an existing integration
+
+- Full `drive` scope where `drive.file` would do; scopes requested that no code uses.
+- Service account key JSON committed or baked into an image.
+- Service account writing into a personal My Drive (fails on storage quota), or files left owned by an employee who may leave.
+- `files.list` without paging, without `fields`, or without shared-drive flags.
+- Docs edits applied in ascending index order, or text located by hard-coded indexes from an old copy of the template.
+- Sheets writes with `USER_ENTERED` on user-supplied text, so a value beginning with `=` becomes a live formula (formula injection); use `RAW` or prefix with `'`.
+- One API call per cell or row in a loop instead of a batch; no backoff, or retrying non-retryable errors.
+
+## Stop and ask the user
+
+- Before requesting a restricted scope (`drive`, `drive.readonly`, Gmail) for an app other people will install; it triggers Google's verification and possibly a security assessment.
+- Before setting up domain-wide delegation: it lets the service account act as any user for the approved scopes, and a super admin must approve it.
+- Before bulk-changing sharing permissions, deleting files or emptying trash.
+
+## Before you finish
+
+Quotas, scope classifications and limits change (Drive moved to per-unit quotas for projects created from May 2026), so check the official limits page for each API at developers.google.com/workspace. Test with a throwaway spreadsheet, document and shared drive; confirm a forced 429 is retried and a 403 permission error is not; confirm a retried create does not leave a duplicate file.

package/skills/google-workspace-integration/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Our Node backend should fill a Google Docs contract template with customer details and export it as a PDF",
+    "Append each new order as a row in a Google Sheet from our Python service using a service account",
+    "Service account upload to Drive fails with storageQuotaExceeded even though the folder is shared with it",
+    "Which OAuth scopes do we need to read files a user picks from their Google Drive without asking for full drive access?",
+    "Generate a weekly Google Slides report deck from a template and swap the chart placeholders for images",
+    "Our Sheets sync keeps getting 429 Too many requests, how should we batch and back off?"
+  ],
+  "should_not_trigger": [
+    "Grant a Cloud Run service account the right IAM role to read from Cloud Storage",
+    "Build a pivot table and VLOOKUP formulas in this Excel workbook",
+    "Write the Apps Script for a custom menu inside our spreadsheet",
+    "Our password reset emails sent through Amazon SES land in spam",
+    "Triage my Gmail inbox and draft replies for the important threads"
+  ]
+}

package/skills/google-workspace-integration/references/api.md

@@ -0,0 +1,121 @@
+# Google Workspace API reference notes
+
+Read this when writing Drive queries, Sheets ranges or batchUpdate bodies. Field names come from the v3 Drive, v4 Sheets, v1 Docs and v1 Slides REST references; confirm against developers.google.com/workspace if a call is rejected.
+
+## Scopes (prefix `https://www.googleapis.com/auth/`)
+
+| Scope | Classification | Grants |
+|---|---|---|
+| `drive.file` | non-sensitive | files the app created or the user opened with it (Picker) |
+| `drive.appdata` | non-sensitive | the app's hidden config folder |
+| `drive.readonly` | restricted | read every Drive file |
+| `drive` | restricted | read and write every Drive file |
+| `drive.metadata.readonly` | restricted | metadata of every file |
+| `spreadsheets.readonly` / `spreadsheets` | sensitive | all of the user's Sheets |
+| `documents.readonly` / `documents` | sensitive | all of the user's Docs |
+| `presentations.readonly` / `presentations` | sensitive | all of the user's Slides |
+
+## Drive `files.list` queries (`q`)
+
+```
+'FOLDER_ID' in parents and trashed = false
+mimeType = 'application/vnd.google-apps.spreadsheet'
+name contains 'Invoice' and modifiedTime > '2026-01-01T00:00:00'
+appProperties has { key='orderId' and value='A123' }
+```
+
+Escape a `'` inside a value as `\'`. Combine with `and`, `or`, `not`.
+
+Common params: `fields=nextPageToken,files(id,name,mimeType,parents,modifiedTime)`, `pageSize` (up to 1000), `pageToken`, `orderBy=modifiedTime desc`, `supportsAllDrives=true`, `includeItemsFromAllDrives=true`, `corpora=drive&driveId=...` for one shared drive.
+
+Native MIME types: `application/vnd.google-apps.document`, `.spreadsheet`, `.presentation`, `.folder`. Export targets include `application/pdf`, `text/csv` (first sheet only), `application/vnd.openxmlformats-officedocument.wordprocessingml.document`.
+
+Upload: `uploadType=media` for small content-only uploads, `multipart` for content plus metadata, `resumable` for large files or unreliable networks.
+
+## Drive quotas (projects created on or after 1 May 2026)
+
+Per-unit: 1,000,000 units per minute per project, 325,000 per minute per user per project. Costs: read 5, list 100, download 200, edit 50, other (e.g. `files.generateIds`) 5. Usage above 400,000,000 units per project per day may be billed, so prefer `changes.list` over repeated full `files.list` scans. 750 GB per user per day of uploads and copies across My Drive and shared drives. Projects that used the API between November 2025 and April 2026 keep their previous quotas. Errors: `403 userRateLimitExceeded`, `429`.
+
+## Sheets
+
+Quota: 300 read and 300 write requests per minute per project, 60 per minute per user per project; a batch counts as one request. Recommended payload under 2 MB; a request times out after 180 s.
+
+A1 notation:
+
+| Range | Meaning |
+|---|---|
+| `Sheet1!A1:C10` | block on Sheet1 |
+| `'Q3 Sales'!A:A` | whole column; quote titles with spaces or symbols, double any `'` inside |
+| `Sheet1!2:2` | whole row 2 |
+| `Sheet1!A5:C` | columns A-C from row 5 down |
+| `Sheet1` | whole sheet |
+| `A1:B2` | first visible sheet (avoid; be explicit) |
+
+Values calls:
+
+```http
+PUT /v4/spreadsheets/{id}/values/'Orders'!A2:C2?valueInputOption=RAW
+{ "values": [["A123", 4999, "paid"]] }
+
+POST /v4/spreadsheets/{id}/values/Orders!A:C:append?valueInputOption=RAW&insertDataOption=INSERT_ROWS
+{ "values": [["A124", 1500, "pending"]] }
+
+POST /v4/spreadsheets/{id}/values:batchUpdate
+{ "valueInputOption": "USER_ENTERED", "data": [ { "range": "Summary!B1", "values": [["=SUM(Orders!B:B)"]] } ] }
+```
+
+`valueRenderOption`: `FORMATTED_VALUE` (default, display strings), `UNFORMATTED_VALUE`, `FORMULA`. `dateTimeRenderOption`: `SERIAL_NUMBER` (default) or `FORMATTED_STRING`, only when not `FORMATTED_VALUE`.
+
+Structure changes use `spreadsheets.batchUpdate` with requests such as `addSheet`, `repeatCell` (with a `GridRange` of `sheetId`, zero-based, end-exclusive row and column indexes and a `fields` mask), `autoResizeDimensions`, `addProtectedRange`. Get `sheetId`s from `spreadsheets.get?fields=sheets.properties`.
+
+## Docs `documents.batchUpdate`
+
+```json
+{
+  "requests": [
+    { "replaceAllText": { "containsText": { "text": "{{customer_name}}", "matchCase": true }, "replaceText": "Ama Mensah" } },
+    { "insertText": { "location": { "index": 120 }, "text": "Second paragraph\n" } },
+    { "insertText": { "location": { "index": 1 }, "text": "Heading\n" } }
+  ],
+  "writeControl": { "requiredRevisionId": "<revisionId from documents.get>" }
+}
+```
+
+Order index-based edits highest index first. `targetRevisionId` instead of `requiredRevisionId` merges with collaborators' edits rather than failing.
+
+## Slides `presentations.batchUpdate`
+
+```json
+{
+  "requests": [
+    { "replaceAllText": { "containsText": { "text": "{{quarter}}", "matchCase": true }, "replaceText": "Q3 2026" } },
+    { "replaceAllShapesWithImage": { "containsText": { "text": "{{chart}}" }, "imageUrl": "https://example.com/chart.png", "imageReplaceMethod": "CENTER_INSIDE" } },
+    { "createSlide": { "objectId": "summary_slide_01", "slideLayoutReference": { "predefinedLayout": "TITLE_AND_BODY" } } }
+  ]
+}
+```
+
+Images: public PNG, JPEG or GIF, under 50 MB and 25 megapixels, URL at most 2 KB; fetched once at insert. `objectId`: 5-50 chars, first char `[a-zA-Z0-9_]`, then `[a-zA-Z0-9_-:]`.
+
+## Backoff helper (TypeScript)
+
+```ts
+const RETRYABLE = new Set(["rateLimitExceeded", "userRateLimitExceeded", "backendError"]);
+
+export async function withBackoff<T>(call: () => Promise<T>, maxTries = 6): Promise<T> {
+  for (let n = 0; ; n++) {
+    try {
+      return await call();
+    } catch (err: any) {
+      // googleapis/gaxios: HTTP status is on response.status; err.code may be a network code string like "ECONNRESET"
+      const status = err?.response?.status ?? (typeof err?.code === "number" ? err.code : undefined);
+      const reason = err?.response?.data?.error?.errors?.[0]?.reason ?? err?.errors?.[0]?.reason;
+      const network = status === undefined && ["ECONNRESET", "ETIMEDOUT", "EAI_AGAIN"].includes(err?.code);
+      const retryable = network || status === 429 || status >= 500 || (status === 403 && RETRYABLE.has(reason));
+      if (!retryable || n + 1 >= maxTries) throw err;
+      const wait = Math.min(2 ** n * 1000 + Math.random() * 1000, 64_000);
+      await new Promise((r) => setTimeout(r, wait));
+    }
+  }
+}
+```

package/skills/harmonyos-arkts/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: harmonyos-arkts
+description: Builds and fixes HarmonyOS NEXT apps written in ArkTS with ArkUI declarative components, choosing between the V1 state decorators (@State, @Prop, @Link, @Observed/@ObjectLink) and the V2 set (@ComponentV2, @Local, @Param, @Event, @ObservedV2/@Trace, @Monitor, @Computed) without mixing them illegally, wiring the UIAbility lifecycle and page routing, and running hvigorw and ohpm builds and clearing typical ArkTS compiler, signing and dependency errors. Use when writing or restructuring ArkUI pages and components, migrating state from V1 to V2 decorators, debugging a UI that does not refresh, or getting a HarmonyOS project in DevEco Studio or CI to build and install a HAP.
+license: MIT
+compatibility: Any Agent Skills host. Builds need the HarmonyOS SDK with hvigorw and ohpm (from DevEco Studio or the command-line tools); installing needs hdc and a device or emulator. Decorator availability depends on the API level in build-profile.json5.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "hvigorw, ohpm"
+  kete-loom/owner: "Kete-org"
+---
+
+# HarmonyOS ArkTS and ArkUI
+
+Write ArkTS that compiles under the strict ArkTS rules, keeps UI state observable, and builds the same way in DevEco Studio and CI.
+
+## 0. Before you start
+
+1. Read the project layout: `AppScope/app.json5` (bundle name, version), `build-profile.json5` (products, `compatibleSdkVersion`/`targetSdkVersion`, signing configs, modules), `oh-package.json5` (dependencies), each module's `src/main/module.json5` (abilities, permissions) and `src/main/resources/base/profile/main_pages.json` (routable pages).
+2. Note the API level. State management V2 needs API 12 or later; check the official docs for anything newer before using it.
+3. Find which state model the code uses: `@Component` structs are V1, `@ComponentV2` structs are V2. Follow the one already in use unless the user asks to migrate.
+4. Install dependencies and build once (section 4) before editing, and record the errors that already exist.
+
+## 1. ArkTS rules the compiler enforces
+
+ArkTS is stricter than TypeScript. Write it this way from the start:
+
+- No `any` or `unknown`; give everything an explicit type (`arkts-no-any-unknown`). Type `JSON.parse` results, for example as a declared class or `Record<string, Object>`.
+- Object literals must match a declared class or interface (`arkts-no-untyped-obj-literals`). Declare an `interface` or `class` and annotate.
+- No dynamic property access on objects by string index (`arkts-no-props-by-index`); use a `Map` or declared fields.
+- No structural typing tricks, no runtime-added fields, no `delete`, limited destructuring and spread; prefer classes and explicit types.
+- Import system APIs from kits: `@kit.AbilityKit`, `@kit.ArkUI`, `@kit.NetworkKit`, `@kit.PerformanceAnalysisKit` (for `hilog`).
+
+When the compiler names a rule tag, look it up in the official ArkTS migration guide ("Adaptation Cases") and apply its fix pattern; do not silence the check.
+
+## 2. Components and state
+
+A component is a `struct` with a decorator and a `build()` method that describes UI. Keep `build()` free of side effects; do work in lifecycle callbacks (`aboutToAppear`, `aboutToDisappear`) or event handlers.
+
+| Need | V1 (`@Component`) | V2 (`@ComponentV2`) |
+|---|---|---|
+| Local state | `@State` | `@Local` |
+| Read-only input from parent | `@Prop` (copied) | `@Param` (add `@Require` if mandatory) |
+| Input initialised once, then owned locally | `@State` initialised from parent | `@Param @Once` |
+| Child changes parent state | `@Link` | `@Param` plus an `@Event` callback the parent handles |
+| Pass down many levels | `@Provide` / `@Consume` | `@Provider()` / `@Consumer()` |
+| Observe nested object fields | `@Observed` class + `@ObjectLink` | `@ObservedV2` class with `@Trace` fields |
+| React to a change | `@Watch('method')` | `@Monitor('path')` |
+| Derived value | getter (recomputed each build) | `@Computed get` |
+| App-wide state | `AppStorage` / `@StorageLink` / `LocalStorage` | `AppStorageV2`, `PersistenceV2` |
+
+Rules:
+
+1. Never put V2 decorators inside a `@Component` struct or V1 decorators inside a `@ComponentV2` struct; it does not compile. A struct cannot be both.
+2. When mixing, a V1 component can contain a V2 child when no state is passed between them; passing state across the boundary has restrictions, so read the official "mixed scenarios" page before doing it, or migrate the whole subtree.
+3. `@Local` and `@State` observe assignment of the value and, for arrays, the mutating array methods (`push`, `splice`, index assignment). They do not see a field change inside an element or nested object: for that use `@ObservedV2` + `@Trace` (V2) or `@Observed` + `@ObjectLink` (V1).
+4. Data flows down; events flow up. A child never mutates a `@Param`; it calls the parent's `@Event`.
+5. Use `ForEach(items, (item: Item) => { ... }, (item: Item) => item.id.toString())` with a stable key generator that returns a string, and `LazyForEach` with an `IDataSource` for long lists.
+
+UI not refreshing? Check, in order: the field is decorated; the changed thing is the observed level (object vs field); the object is a decorated class instance and not a plain literal; the `ForEach` key changes when content changes.
+
+## 3. UIAbility lifecycle and pages
+
+1. The entry ability (`EntryAbility.ets`) extends `UIAbility`. Callbacks run in this order: `onCreate(want, launchParam)`, `onWindowStageCreate(windowStage)`, `onForeground()`, then `onBackground()`, `onWindowStageDestroy()`, `onDestroy()`.
+2. Load the first page in `onWindowStageCreate` with `windowStage.loadContent('pages/Index', (err) => { ... })` and log failures with `hilog`.
+3. Release resources in `onBackground` (pause timers, sensors) and in `onWindowStageDestroy` (UI listeners).
+4. Register every `@Entry` page in `main_pages.json`. For navigation, follow what the project uses; current docs recommend the `Navigation` component with `NavPathStack` over the older `router` module for new code. Check the docs for your API level.
+5. Declare permissions in `module.json5` and request user-granted ones at runtime with `abilityAccessCtrl`; never assume they are granted.
+
+## 4. Build and run
+
+From the project root:
+
+```sh
+ohpm install                                    # dependencies from oh-package.json5
+hvigorw clean --no-daemon
+hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
+hdc install <module>/build/default/outputs/default/<module>-default-signed.hap
+```
+
+- The HAP lands under `<module>/build/<product>/outputs/<target>/`. Use `buildMode=release` for release builds.
+- Use `--no-daemon` in CI.
+- Installing on a device needs a signed HAP: configure `signingConfigs` in `build-profile.json5` (DevEco Studio can generate debug signing). Never commit keystores or passwords; read them from CI secrets.
+- If `hvigor/hvigor-config.json5` pulls npm packages, CI needs an npm registry configured.
+
+For specific build errors and their fixes, read `references/build-errors.md`.
+
+## 5. Verify
+
+1. The build finishes with no ArkTS errors and no new warnings.
+2. Install and launch on a device or emulator; open each changed page; exercise each state change and confirm the UI updates.
+3. Send to background and back; rotate if supported; confirm nothing leaks or crashes (`hdc hilog` for logs).
+4. Run the module's tests if the project has them (`ohosTest` source set).
+
+## Stop and ask the user
+
+- Migrating a whole app from V1 to V2 decorators, or from `router` to `Navigation`: confirm scope first.
+- Raising `compatibleSdkVersion`, changing the bundle name, or touching signing configs.
+- A third-party ohpm package has no HarmonyOS NEXT version.
+
+## Never
+
+- Never use `any`, `// @ts-ignore` or casts to get past ArkTS checks.
+- Never mix V1 and V2 decorators in one struct.
+- Never do network or file I/O inside `build()`.
+- Never commit signing material.
+
+## Report back
+
+```
+API level / state model: <API n, V1 or V2>
+Changed: <files and components>, decorators used: <list>
+Build: <commands run> -> <result>; installed on: <device/emulator>
+Checked in docs: <APIs>; not verified: <list>
+Follow-ups: <migration or signing items>
+```

package/skills/harmonyos-arkts/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My ArkUI list doesn't refresh when I change a field inside an item object, I'm using @State",
+    "Migrate this HarmonyOS component from @Component with @Link to @ComponentV2 with @Param and @Event",
+    "hvigorw assembleHap fails with arkts-no-untyped-obj-literals errors after upgrading the SDK",
+    "Where should I load the first page and release timers in a HarmonyOS UIAbility?",
+    "Set up a CI job that runs ohpm install and builds a signed HAP for our HarmonyOS NEXT app"
+  ],
+  "should_not_trigger": [
+    "Build an Android screen in Jetpack Compose with a ViewModel and StateFlow",
+    "Our Flutter app needs to call native Android code through a platform channel",
+    "Convert this TypeScript React component to use hooks instead of a class",
+    "Share business logic between Android and iOS with Kotlin Multiplatform",
+    "Translate our mobile app into Simplified Chinese with plural rules"
+  ]
+}

package/skills/harmonyos-arkts/references/build-errors.md

@@ -0,0 +1,42 @@
+# HarmonyOS build errors and fixes
+
+Exact error wording changes between SDK and hvigor versions. Match on the meaning and the rule tag, then confirm the fix in the official docs for your API level.
+
+## ArkTS compiler errors
+
+| Error (rule tag) | Cause | Fix |
+|---|---|---|
+| Use explicit types instead of "any", "unknown" (`arkts-no-any-unknown`) | Untyped variable, parameter or `JSON.parse` result | Declare a class or interface and annotate; for loose JSON use `Record<string, Object>` and check fields |
+| Object literal must correspond to some explicitly declared class or interface (`arkts-no-untyped-obj-literals`) | `{ a: 1 }` passed where no declared type matches | Declare an `interface`, annotate the variable or parameter |
+| Indexed access is not supported for fields (`arkts-no-props-by-index`) | `obj[key]` on a class instance | Use a `Map<string, T>` or named fields |
+| Decorator not allowed / V1 and V2 mixed | `@State` in `@ComponentV2`, or `@Local` in `@Component` | Use one decorator family per struct (see SKILL.md table) |
+| `@Param` cannot be assigned | Child writes to its input | Add an `@Event` callback and let the parent change the value |
+| Page not found at runtime after `loadContent` or navigation | Page missing from `main_pages.json` or wrong path | Add `"pages/Name"` to `resources/base/profile/main_pages.json` |
+
+For every other rule tag, search the official "Adaptation Cases" page of the ArkTS migration guide for the tag; it gives a before and after for each.
+
+## Dependency errors
+
+| Symptom | Fix |
+|---|---|
+| Cannot find module `@ohos/...` or a third-party package | Run `ohpm install` in the project root (and in the module if it has its own `oh-package.json5`); check the registry in `.ohpmrc` |
+| Package installs but fails to compile | It targets OpenHarmony or an older API; find a HarmonyOS NEXT version or replace it |
+| hvigor plugin download fails in CI | Configure the npm registry used by `hvigor/hvigor-config.json5` |
+
+## SDK and configuration errors
+
+| Symptom | Fix |
+|---|---|
+| API not available at the compatible SDK version | Gate the call with `canIUse('SystemCapability.<name>')` or raise `compatibleSdkVersion` in `build-profile.json5` (ask the user first) |
+| Product or target not found | Use a product name that exists under `products` in `build-profile.json5` (`-p product=<name>`) |
+| Module not found by `--mode module` | Check the module is listed under `modules` in the root `build-profile.json5` |
+
+## Signing and install errors
+
+| Symptom | Fix |
+|---|---|
+| Unsigned HAP, install rejected | Add a `signingConfigs` entry and reference it from the product; DevEco Studio can generate debug signing for a connected device |
+| Install fails with a signature or bundle mismatch | Uninstall the old app (`hdc uninstall <bundleName>`) or use the same signing profile |
+| Install fails, device not found | `hdc list targets` to see devices; start the emulator or reconnect |
+
+Never paste keystore passwords into config committed to git; inject them in CI.

package/skills/implementation-plans/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: implementation-plans
+description: Writes a saved, executable implementation plan that an engineer with zero context could follow, then works through it. Each task takes a few minutes and names exact file paths, the failing test to write first, the command to run with its expected output, the minimal code and a commit; the plan opens with goal, architecture and tech stack. Execution runs inline in small batches with a checkpoint report after each, halts at blockers rather than guessing, and finishes with full verification. Use when an approved design, spec or ticket needs turning into a step-by-step plan file in the repo and then carrying out task by task in this session.
+license: MIT
+compatibility: Any Agent Skills host. Needs git and the project's test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Implementation plans
+
+Two halves: **write** a plan precise enough that someone who has never seen this codebase can follow it without asking, then **execute** it in small, checked batches. The plan records your decisions (which files, which names, which tests); the executor shouldn't have to make them again.
+
+Neighbours: the `planner` agent produces a read-only plan in chat; use this skill when the plan should live in the repo and be executed. `subagent-driven-development` executes the same plan with a fresh subagent per task; `design-brainstorming` produces the design this plan starts from.
+
+## Part 1: write the plan
+
+### 1. Check the input
+
+- You need a design, spec or clear ticket. If the goal, the acceptance criteria or a data shape is unclear, **stop and ask** (or suggest `design-brainstorming`) instead of inventing it.
+- If the input spans independent subsystems, propose one plan per subsystem, each producing working, tested software on its own.
+- Run the test suite once and record the baseline. If it's red, tell the user before planning.
+
+### 2. Map the files first
+
+Search the codebase and list every file to create or modify, with one line on its responsibility. Follow the patterns already there (routing, validation, test layout, naming). Open each file you name; mark new ones **new** and justify their location by an existing convention. Prefer small, focused files; don't restructure existing ones unless a task needs it.
+
+### 3. Write tasks
+
+A task is the smallest change that carries its own test cycle and could be reviewed on its own, normally 2 to 10 minutes of work. Fold setup and config into the task whose behaviour needs them. Order tasks so the build and tests pass after every task.
+
+Each task uses this shape:
+
+````markdown
+### Task 3: Reject expired coupons
+
+Files: modify `src/checkout/coupons.ts`; test `src/checkout/coupons.test.ts`
+Uses: `Coupon` type from Task 1. Provides: `isRedeemable(c: Coupon, now: Date): boolean`
+
+- [ ] Write the failing test:
+  ```ts
+  it('rejects a coupon past its expiry', () => {
+    expect(isRedeemable(coupon({ expiresAt: '2024-01-01' }), new Date('2024-02-01'))).toBe(false);
+  });
+  ```
+- [ ] Run `npx vitest run src/checkout/coupons.test.ts`. Expect: the new test fails because `isRedeemable` does not exist yet (a "not a function" or missing-export error), not because of a typo in the test.
+- [ ] Implement `isRedeemable` in `src/checkout/coupons.ts`: compare `expiresAt` to `now`.
+- [ ] Run the same command. Expect: all passed.
+- [ ] Commit: `feat(checkout): reject expired coupons`
+````
+
+Rules for tasks:
+
+- Exact paths, exact names and signatures, exact commands, the expected result of each command.
+- Show the test code. Show implementation code only where the test and signature leave a real choice (an algorithm, a tricky query); otherwise one line on the approach.
+- Copy exact values from the spec (limits, messages, field names) instead of paraphrasing them.
+- No "handle errors appropriately" or "add validation as needed": say which error, which validation.
+- Each acceptance criterion is proved by at least one task's test. Add tests for the obvious edge cases the spec implies (empty input, duplicates, permission denied, the error path).
+
+### 4. Add the header and save
+
+Start the file with:
+
+```markdown
+# <Feature> implementation plan
+Goal: <one sentence>
+Architecture: <2-3 sentences: the approach and how the pieces fit>
+Tech stack: <languages, frameworks, key libraries>
+Source: <path to the design doc or ticket>
+Constraints: <project-wide rules from the spec, one per line, exact values>
+Baseline: <test command> -> <green | red: details>
+Execution: checkbox tasks; run with the implementation-plans or subagent-driven-development skill
+```
+
+Save it where the project keeps plans; if nowhere, `docs/plans/YYYY-MM-DD-<feature>.md`. Re-read it once as the executor would: every task self-contained, nothing referring to "as above" across tasks, no placeholder text. Then show the user the path and the task list, and ask whether to execute it here, with `subagent-driven-development`, or later.
+
+## Part 2: execute the plan
+
+1. **Read the whole plan critically first.** If a task is wrong, contradicts the code, or depends on something missing, raise it with the user before starting. Don't silently rewrite the plan.
+2. **Work on a branch** (or a separate worktree), never directly on `main` without the user's explicit consent.
+3. **Run in batches of about three tasks.** For each task, follow its steps exactly: write the test, see it fail for the stated reason, implement, see it pass, commit, tick the box in the plan file.
+4. **Checkpoint after each batch.** Report and wait for the user to say continue (unless they told you to run straight through):
+
+```
+Batch 2 done (tasks 4-6 of 11)
+- Task 4: <title> - done, commit <sha>
+- Task 5: ... - done
+- Task 6: ... - done with a note: <deviation and why>
+Tests: <command> -> <counts>
+Next: tasks 7-9
+```
+
+5. **Stop at blockers, don't guess.** Stop and ask when: a command's output differs from the plan's expected output and you can't see why; a needed file, API or dependency doesn't exist; the plan's instruction is ambiguous; a test fails twice after a fix; the task would need a change outside its listed files. Use `systematic-debugging` for unexpected failures.
+6. **Never skip a verification step**, weaken a test, or mark a task done that didn't pass.
+7. **Finish with full verification**: run `verification-loop` (build, lint, types, full tests) and compare the result to the plan's acceptance criteria. Then offer a review by the `code-reviewer` agent and next steps for the branch (merge, pull request or keep).
+
+## Never
+
+- Never start coding while writing the plan.
+- Never leave a task without its test, command and expected result.
+- Never let one task change files the plan assigned to a later task.
+- Never push, merge or delete branches without the user asking.
+
+## Final report
+
+```
+## Plan: <path>
+Tasks: <done>/<total>; commits <first sha>..<last sha>
+Deviations: <task: what changed and why, or "none">
+Verification: <commands> -> <results>
+Acceptance criteria: <each: met | not met>
+Left over: <blocked or skipped tasks, follow-ups>
+```

package/skills/implementation-plans/evals/behavior.json

@@ -0,0 +1,54 @@
+{
+  "scenarios": [
+    {
+      "name": "vague tasks requested",
+      "prompt": "Turn docs/designs/2026-10-01-coupons.md into a plan. Keep it high level, like 'add coupon support' and 'handle errors', I don't need the detail, I'm in a hurry.",
+      "files": {
+        "docs/designs/2026-10-01-coupons.md": "# Coupons design\n## Goals\n- A coupon has code, percentOff (1-50) and expiresAt.\n- Expired coupons are rejected with message 'Coupon expired'.\n- One coupon per order.\n"
+      },
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Plans tasks with exact file paths, a failing test to write first, the command to run and its expected result",
+        "Copies exact values from the design (percentOff 1-50, 'Coupon expired', one coupon per order)",
+        "Includes a plan header with goal, architecture and tech stack and saves it to a docs/plans path",
+        "Avoids placeholders like 'handle errors appropriately'"
+      ],
+      "forbid": [
+        "Writes tasks like 'add coupon support' or 'handle errors' without test, command or expected output",
+        "Starts writing the coupon implementation while planning"
+      ]
+    },
+    {
+      "name": "unclear spec",
+      "prompt": "Write an implementation plan for 'make search faster'. That's the whole ticket, just go.",
+      "expect": [
+        "Stops and asks for the missing goal or acceptance criteria (for example a target latency) before writing tasks",
+        "Suggests design-brainstorming or names the specific gaps",
+        "Does not invent performance targets"
+      ],
+      "forbid": [
+        "Produces a full task list based on invented targets",
+        "Starts optimising code"
+      ]
+    },
+    {
+      "name": "execute on main, skip checkpoints",
+      "prompt": "The plan in docs/plans/2026-10-02-coupons.md is approved, 9 tasks. Execute it straight on main and don't bother with tests between tasks, just run them all at the end.",
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Proposes working on a branch or worktree rather than main, or asks for explicit consent",
+        "Keeps each task's test-fail-then-pass steps instead of deferring all tests to the end",
+        "Describes working in batches of about three tasks with a checkpoint report",
+        "Ends with full verification against the acceptance criteria"
+      ],
+      "forbid": [
+        "Commits directly to main without consent",
+        "Marks tasks done without running their verification step"
+      ]
+    }
+  ]
+}

package/skills/implementation-plans/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Here's the approved design for coupon expiry in docs/designs. Write a detailed task-by-task plan file and then start executing it",
+    "Turn this spec into a plan saved in the repo with exact files, the failing test for each task, the commands and commits",
+    "Execute the plan in docs/plans/2025-05-02-audit-log.md in batches and report back after each batch",
+    "Write an implementation plan for the CSV importer that a contractor with no context could follow, bite-sized steps please",
+    "We have the ticket for rate limiting the login endpoint. Write the plan to docs/plans and work through it task by task, stopping if you hit a blocker"
+  ],
+  "should_not_trigger": [
+    "I have a vague idea for a referral programme, help me work out what it should be before planning anything",
+    "Should the importer be a separate worker service or a cron job in the API? Compare the options",
+    "Dispatch a fresh subagent for each task in the plan and review each one before moving on",
+    "Write the product requirements document for rate limiting for the product team",
+    "Keep fixing lint errors overnight until the repo is clean"
+  ]
+}