@olegkoval/agent-skills 1.19.0 → 1.20.0

package/packages/software-development/qodoloop/adapters/windsurf/rules/qodoloop.md

@@ -34,7 +34,19 @@ Qodo has **no check run to poll** — there is nothing in `gh pr checks` to wait
 gh pr view --json number,headRefName,headRefOid -q '{number, branch: .headRefName, sha: .headRefOid}'
 ```
 
-Check out the branch if not already on it.
+Check out the branch if not already on it, **then require a clean working
+tree** (`git status --porcelain` empty) before touching anything:
+
+```bash
+[ -z "$(git status --porcelain)" ] || { echo "working tree not clean — refusing to start, would risk committing unrelated changes"; exit 1; }
+```
+
+This is the precondition step E's scoped `git add <file>` depends on: staging
+only the files a fix touched is safe *because* the tree started clean, so
+nothing else could be sitting in those files. Skip this check and a file
+with pre-existing local edits will have those edits swept into the fix
+commit right along with it — the exact failure `git add -A` had, just
+narrower.
 
 ### 2. Loop (max 5 iterations)
 

package/packages/software-development/semantic-release-beta/adapters/claude/skills/semantic-release-beta/references/github-actions.md

@@ -0,0 +1,16 @@
+# GitHub Actions layout
+
+Recommended jobs:
+
+- `test`
+- `release-readiness`
+- `release`
+
+Core behavior:
+
+- run on `push` and `pull_request` for `main` and `beta`
+- use `fetch-depth: 0` for semantic-release jobs
+- validate `NPM_TOKEN`
+- run `npm run release:dry-run` before the real release
+- run the real release with `npm run semantic-release` or the repository's equivalent semantic-release script
+- use a Node version compatible with `semantic-release-npm-github-publish` and its semantic-release peer dependencies

package/packages/software-development/semantic-release-beta/adapters/claude/skills/semantic-release-beta/references/node-semantic-release.md

@@ -0,0 +1,13 @@
+# Node semantic-release config
+
+Use this pattern when a Node package should publish stable releases from `main` and prereleases from `beta`.
+
+Prefer the `semantic-release-npm-github-publish` shareable config for the plugin chain. Keep branch policy in repo-local config because the preset is intentionally branch-agnostic for consumers.
+
+## Core points
+
+- add `release:dry-run` as `semantic-release --dry-run --no-ci`
+- add `semantic-release` as `semantic-release` if the repository does not already have a release script
+- configure branches for `main` and `{ name: "beta", channel: "beta", prerelease: "beta" }`
+- extend `semantic-release-npm-github-publish` unless the project requires a different plugin composition
+- preserve existing custom plugins only when they represent intentional behavior not covered by the preset

package/packages/software-development/semantic-release-beta/adapters/claude/skills/semantic-release-beta/references/preset.md

@@ -0,0 +1,47 @@
+# semantic-release-npm-github-publish preset
+
+Use `semantic-release-npm-github-publish` as the default release preset for npm + GitHub packages.
+
+## What it provides
+
+- a maintained semantic-release shareable configuration
+- changelog generation
+- npm publishing
+- GitHub release publishing
+- release commits for `package.json`, `package-lock.json`, and `CHANGELOG.md`
+- extra patch release rules for maintenance commit types such as `build`, `ci`, `chore`, `docs`, `refactor`, `style`, and `test`
+- tested support for current semantic-release plugin majors on Node 22 and 24
+
+## Install
+
+Install the preset plus semantic-release and its peer plugins:
+
+```bash
+npm install --save-dev \
+  semantic-release \
+  semantic-release-npm-github-publish \
+  @semantic-release/changelog \
+  @semantic-release/commit-analyzer \
+  @semantic-release/git \
+  @semantic-release/github \
+  @semantic-release/npm \
+  @semantic-release/release-notes-generator
+```
+
+## Repo-local config
+
+The preset does not hardcode consumer release branches. Keep branch policy in the target repository:
+
+```yaml
+branches:
+  - main
+  - name: beta
+    channel: beta
+    prerelease: beta
+extends: semantic-release-npm-github-publish
+ci: false
+dryRun: false
+debug: false
+```
+
+Use a different local config only when the target repository intentionally needs a different plugin chain, release rules, or upgrade policy.

package/packages/software-development/semantic-release-beta/adapters/claude/skills/semantic-release-beta/references/validation.md

@@ -0,0 +1,17 @@
+# Validation
+
+Prefer these checks:
+
+```bash
+npm test
+npm run build
+npm run release:dry-run
+```
+
+Common failure points:
+
+- missing `fetch-depth: 0`
+- invalid or missing `NPM_TOKEN`
+- missing `beta` branch config
+- missing `semantic-release-npm-github-publish` or one of its peer plugins
+- plugin config drifting from actual repo files

package/packages/software-development/semantic-release-beta/adapters/cursor/skills/semantic-release-beta/references/github-actions.md

@@ -0,0 +1,16 @@
+# GitHub Actions layout
+
+Recommended jobs:
+
+- `test`
+- `release-readiness`
+- `release`
+
+Core behavior:
+
+- run on `push` and `pull_request` for `main` and `beta`
+- use `fetch-depth: 0` for semantic-release jobs
+- validate `NPM_TOKEN`
+- run `npm run release:dry-run` before the real release
+- run the real release with `npm run semantic-release` or the repository's equivalent semantic-release script
+- use a Node version compatible with `semantic-release-npm-github-publish` and its semantic-release peer dependencies

package/packages/software-development/semantic-release-beta/adapters/cursor/skills/semantic-release-beta/references/node-semantic-release.md

@@ -0,0 +1,13 @@
+# Node semantic-release config
+
+Use this pattern when a Node package should publish stable releases from `main` and prereleases from `beta`.
+
+Prefer the `semantic-release-npm-github-publish` shareable config for the plugin chain. Keep branch policy in repo-local config because the preset is intentionally branch-agnostic for consumers.
+
+## Core points
+
+- add `release:dry-run` as `semantic-release --dry-run --no-ci`
+- add `semantic-release` as `semantic-release` if the repository does not already have a release script
+- configure branches for `main` and `{ name: "beta", channel: "beta", prerelease: "beta" }`
+- extend `semantic-release-npm-github-publish` unless the project requires a different plugin composition
+- preserve existing custom plugins only when they represent intentional behavior not covered by the preset

package/packages/software-development/semantic-release-beta/adapters/cursor/skills/semantic-release-beta/references/preset.md

@@ -0,0 +1,47 @@
+# semantic-release-npm-github-publish preset
+
+Use `semantic-release-npm-github-publish` as the default release preset for npm + GitHub packages.
+
+## What it provides
+
+- a maintained semantic-release shareable configuration
+- changelog generation
+- npm publishing
+- GitHub release publishing
+- release commits for `package.json`, `package-lock.json`, and `CHANGELOG.md`
+- extra patch release rules for maintenance commit types such as `build`, `ci`, `chore`, `docs`, `refactor`, `style`, and `test`
+- tested support for current semantic-release plugin majors on Node 22 and 24
+
+## Install
+
+Install the preset plus semantic-release and its peer plugins:
+
+```bash
+npm install --save-dev \
+  semantic-release \
+  semantic-release-npm-github-publish \
+  @semantic-release/changelog \
+  @semantic-release/commit-analyzer \
+  @semantic-release/git \
+  @semantic-release/github \
+  @semantic-release/npm \
+  @semantic-release/release-notes-generator
+```
+
+## Repo-local config
+
+The preset does not hardcode consumer release branches. Keep branch policy in the target repository:
+
+```yaml
+branches:
+  - main
+  - name: beta
+    channel: beta
+    prerelease: beta
+extends: semantic-release-npm-github-publish
+ci: false
+dryRun: false
+debug: false
+```
+
+Use a different local config only when the target repository intentionally needs a different plugin chain, release rules, or upgrade policy.

package/packages/software-development/semantic-release-beta/adapters/cursor/skills/semantic-release-beta/references/validation.md

@@ -0,0 +1,17 @@
+# Validation
+
+Prefer these checks:
+
+```bash
+npm test
+npm run build
+npm run release:dry-run
+```
+
+Common failure points:
+
+- missing `fetch-depth: 0`
+- invalid or missing `NPM_TOKEN`
+- missing `beta` branch config
+- missing `semantic-release-npm-github-publish` or one of its peer plugins
+- plugin config drifting from actual repo files

package/packages/software-development/semantic-release-beta/adapters/grok/skills/semantic-release-beta/references/github-actions.md

@@ -0,0 +1,16 @@
+# GitHub Actions layout
+
+Recommended jobs:
+
+- `test`
+- `release-readiness`
+- `release`
+
+Core behavior:
+
+- run on `push` and `pull_request` for `main` and `beta`
+- use `fetch-depth: 0` for semantic-release jobs
+- validate `NPM_TOKEN`
+- run `npm run release:dry-run` before the real release
+- run the real release with `npm run semantic-release` or the repository's equivalent semantic-release script
+- use a Node version compatible with `semantic-release-npm-github-publish` and its semantic-release peer dependencies

package/packages/software-development/semantic-release-beta/adapters/grok/skills/semantic-release-beta/references/node-semantic-release.md

@@ -0,0 +1,13 @@
+# Node semantic-release config
+
+Use this pattern when a Node package should publish stable releases from `main` and prereleases from `beta`.
+
+Prefer the `semantic-release-npm-github-publish` shareable config for the plugin chain. Keep branch policy in repo-local config because the preset is intentionally branch-agnostic for consumers.
+
+## Core points
+
+- add `release:dry-run` as `semantic-release --dry-run --no-ci`
+- add `semantic-release` as `semantic-release` if the repository does not already have a release script
+- configure branches for `main` and `{ name: "beta", channel: "beta", prerelease: "beta" }`
+- extend `semantic-release-npm-github-publish` unless the project requires a different plugin composition
+- preserve existing custom plugins only when they represent intentional behavior not covered by the preset

package/packages/software-development/semantic-release-beta/adapters/grok/skills/semantic-release-beta/references/preset.md

@@ -0,0 +1,47 @@
+# semantic-release-npm-github-publish preset
+
+Use `semantic-release-npm-github-publish` as the default release preset for npm + GitHub packages.
+
+## What it provides
+
+- a maintained semantic-release shareable configuration
+- changelog generation
+- npm publishing
+- GitHub release publishing
+- release commits for `package.json`, `package-lock.json`, and `CHANGELOG.md`
+- extra patch release rules for maintenance commit types such as `build`, `ci`, `chore`, `docs`, `refactor`, `style`, and `test`
+- tested support for current semantic-release plugin majors on Node 22 and 24
+
+## Install
+
+Install the preset plus semantic-release and its peer plugins:
+
+```bash
+npm install --save-dev \
+  semantic-release \
+  semantic-release-npm-github-publish \
+  @semantic-release/changelog \
+  @semantic-release/commit-analyzer \
+  @semantic-release/git \
+  @semantic-release/github \
+  @semantic-release/npm \
+  @semantic-release/release-notes-generator
+```
+
+## Repo-local config
+
+The preset does not hardcode consumer release branches. Keep branch policy in the target repository:
+
+```yaml
+branches:
+  - main
+  - name: beta
+    channel: beta
+    prerelease: beta
+extends: semantic-release-npm-github-publish
+ci: false
+dryRun: false
+debug: false
+```
+
+Use a different local config only when the target repository intentionally needs a different plugin chain, release rules, or upgrade policy.

package/packages/software-development/semantic-release-beta/adapters/grok/skills/semantic-release-beta/references/validation.md

@@ -0,0 +1,17 @@
+# Validation
+
+Prefer these checks:
+
+```bash
+npm test
+npm run build
+npm run release:dry-run
+```
+
+Common failure points:
+
+- missing `fetch-depth: 0`
+- invalid or missing `NPM_TOKEN`
+- missing `beta` branch config
+- missing `semantic-release-npm-github-publish` or one of its peer plugins
+- plugin config drifting from actual repo files

package/packages/wearables/garmin-watchface/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: garmin-watchface
+description: Build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C. Use when working on a Connect IQ watch face or app - creating one, fixing layout that clips or overlaps, capturing simulator screenshots, adding app settings, widening device support, or preparing a Connect IQ Store submission. Encodes the traps that silently produce a passing build and a broken face.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires macOS, the Connect IQ SDK, a JDK, and Python 3 (Pillow for screenshot cropping).
+metadata:
+  targets: [_source-only]
+---
+
+# Garmin Connect IQ watch faces
+
+Monkey C gives you almost no safety net. The compiler is happy to build a face
+that draws off the bottom of the screen, a test suite that contains no tests, and
+a colour that is not the colour you get. Everything below is a failure mode that
+looked like success first.
+
+**Read `references/` files as needed — do not read them all up front.**
+
+| File | When |
+| --- | --- |
+| `references/display.md` | Choosing colours, anything about brightness or legibility |
+| `references/layout.md` | Positioning anything; content clipped, overlapping, or off-screen |
+| `references/testing.md` | Writing tests; a suspiciously clean test run |
+| `references/simulator.md` | Screenshots, settings not applying, monkeydo hanging |
+| `references/devices.md` | Adding device support, launcher icons, API levels |
+| `references/store.md` | Publishing, listing copy, IP questions |
+
+## Tools
+
+Run these rather than reinventing them. All are standalone.
+
+```bash
+<skill-dir>/scripts/ciq-doctor                    # toolchain check: SDK, JDK, key, devices
+<skill-dir>/scripts/ciq-devices                   # survey installed devices by resolution
+<skill-dir>/scripts/ciq-devices --same-as fenix6pro   # products you can add with no code change
+<skill-dir>/scripts/ciq-capture out.png           # calibrated simulator screenshot
+<skill-dir>/scripts/ciq-capture out.png --face --size 260   # cropped + masked to the round display
+<skill-dir>/scripts/ciq-calibrate                 # re-derive the display rect if capture looks wrong
+```
+
+`<skill-dir>/scripts/ciq-capture` exists because `screencapture -R` grabs a screen *region*, not
+a window: without a frontmost check it silently photographs whatever is on top,
+and the window moves between simulator restarts. Both failure modes produce a
+plausible PNG of the wrong thing.
+
+## The five things that will bite you
+
+### 1. `make test` can compile zero tests and report success
+
+If `monkey.jungle` sets `base.excludeAnnotations = test`, every `(:test)`
+function is stripped from **every** target, including the unit-test build. You
+get `BUILD SUCCESSFUL` and a green run with nothing compiled — even when the test
+files reference symbols that no longer exist.
+
+Fix: a second jungle passed as an additional `-f`. See
+`<skill-dir>/templates/monkey.test.jungle` and the `test` target in `<skill-dir>/templates/Makefile`.
+
+**Prove it before you trust it.** Put a deliberately unresolvable symbol in one
+test and confirm the build fails:
+
+```monkeyc
+return ThisDoesNotExist.definitelyNotAFunction();
+```
+
+### 2. Never hardcode a Y coordinate or assume a font height
+
+`dc.getFontHeight()` is the only source of truth, and the numbers are larger than
+they look. Measured on fenix 6 Pro:
+
+| Font | Height |
+| --- | --- |
+| `FONT_XTINY` | 19 |
+| `FONT_TINY` | 29 |
+| `FONT_SMALL` | 32 |
+| `FONT_NUMBER_MEDIUM` | 74 |
+
+Content drawn past the screen height is simply invisible — no error, no warning,
+no clipping indicator. A two-line `FONT_NUMBER_MEDIUM` block is 148px of a 260px
+face.
+
+Derive every Y at draw time, and **clamp** so a bottom row cannot be pushed off:
+
+```monkeyc
+function clampRuleY(derived as Number, footerH as Number) as Number {
+    var reserved = (footerH * 2) + GAP_BELOW_RULE + GAP_BETWEEN_ROWS;
+    var maxRuleY = SCREEN - BOTTOM_MARGIN - reserved;
+    return derived > maxRuleY ? maxRuleY : derived;
+}
+```
+
+See `references/layout.md`.
+
+### 3. The screen is round; your layout is not
+
+Check content against the bezel curve, not the bounding square. A rectangle
+inscribed in a circle fails at its **corners** long before its sides.
+
+```monkeyc
+function halfWidthAt(y as Number) as Number {
+    var dy = y - CENTER;
+    var inside = (CENTER * CENTER) - (dy * dy);
+    return inside <= 0 ? 0 : Math.sqrt(inside).toNumber();
+}
+```
+
+### 4. Colours are quantised, and brightness is reflectance
+
+Many devices snap to a 4×4×4 lattice: `0x00 / 0x55 / 0xAA / 0xFF` per channel. A
+colour not already on it is not the colour that ships.
+
+More important: MIP screens are **transflective with no backlight**. A colour's
+brightness *is* how much ambient light it returns. Grey reflects about two-thirds
+of what white does. Choosing a photographically accurate grey for a large area
+makes the whole face read as dim on the wrist while looking fine in the
+simulator's backlit LCD.
+
+Corollary: a saturated colour on a glyph reflects only its own channel, making
+the thing you want to read the *dimmest* thing on screen.
+
+See `references/display.md`.
+
+### 5. The simulator lies about settings
+
+It persists app settings and **ignores changed defaults in `properties.xml`**
+until you do File → Reset All App Data. A property will keep reading its old
+value while the XML plainly says otherwise. This looks exactly like broken
+settings code.
+
+Reset also drops the loaded device, so relaunch and re-push afterwards.
+
+See `references/simulator.md`.
+
+## Workflow
+
+### Starting a face
+
+1. `<skill-dir>/scripts/ciq-doctor` — confirm SDK, JDK, developer key, target device installed.
+2. Copy `<skill-dir>/templates/Makefile`, `<skill-dir>/templates/monkey.jungle`, `<skill-dir>/templates/monkey.test.jungle`.
+3. Generate a fresh app id: `python3 -c "import uuid;print(uuid.uuid4().hex)"`.
+4. Split source by responsibility. This structure has held up well:
+
+| Module | Holds |
+| --- | --- |
+| `Palette.mc` | Colours only, all lattice-exact |
+| `Layout.mc` | Geometry, derivations, bezel maths — no drawing |
+| `<Widget>.mc` | Drawing primitives (rows, bars, segments) |
+| `Fields.mc` | Formatting and thresholds — pure, easy to test |
+| `Sensors.mc` | Sensor reads with null handling |
+| `<Name>View.mc` | Composition only |
+
+Keeping `Layout` free of `Dc` calls is what makes geometry unit-testable.
+
+### Every change
+
+```bash
+make build && make test && make lint
+```
+
+`make lint` is level 3 and catches real problems the level 2 build allows.
+
+### Before committing
+
+Capture and *look at it*. Layout bugs are invisible in a passing test run:
+
+```bash
+make build && make sim
+<skill-dir>/scripts/ciq-capture /tmp/face.png --face --size 260
+```
+
+Then Read the PNG. Every layout bug in this skill's history was found by looking,
+not by testing.
+
+## Monkey C gotchas
+
+- Module-level functions take **no** visibility modifier. `private` and `hidden`
+  are class-only; at module scope they are syntax errors.
+- `dc.fillPolygon` wants `Array<[Numeric, Numeric]>`. Cast the literal:
+  `[[x, y], ...] as Array<[Numeric, Numeric]>`.
+- `getInitialView()` returns
+  `[WatchUi.Views] or [WatchUi.Views, WatchUi.InputDelegates]`.
+- `Application.Properties.getValue()` **throws** when a key is absent, which
+  happens on a fresh install before settings have ever been written. Wrap every
+  read with a default.
+- Integer division everywhere. Centring an odd width leaves a 1px skew — write
+  tests that allow it rather than forcing constants to stay even.
+
+## Reference watches and homages
+
+If reproducing a real object, get these right before anything else, because they
+are what makes it recognisable:
+
+- **Display polarity.** A 1970s LCD is *positive*: dark segments on a pale panel,
+  the inverse of every modern face. Getting this backwards turns a crystal into a
+  screen.
+- **Proportion.** Bezels on vintage digitals are thick; the window is smaller
+  than memory suggests.
+- **Where the legends sit** — maker's name on the bezel, not the glass.
+
+No system font is a segment display. If you need one, draw it: see
+`references/layout.md` for a working seven-segment renderer, including the ghost
+(unlit) segments that are most of what sells the effect.
+
+**Do not print a real brand on the face.** See `references/store.md`.

package/packages/wearables/garmin-watchface/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-garmin-watchface",
+  "description": "Build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C.",
+  "skills": "./skills"
+}