@olegkoval/agent-skills 1.34.0 → 1.35.0

package/.grok-plugin/index.json

@@ -2,239 +2,59 @@
   "name": "agent-skills",
   "plugins": [
     {
-      "name": "olko:self-critique",
-      "source": "./packages/software-development/self-critique/adapters/grok",
-      "description": "Adversarially critique your own last answer: spawn a critic agent that verifies claims against live sources, finds the related issue or pattern you missed, then loop until satisfied and report where you were wrong, iterations-to-satisfy, the numeric improvement, and a final score."
+      "name": "olko-github-pr",
+      "source": "./adapters/grok/olko-github-pr",
+      "description": "Drive GitHub pull requests to merge-ready: review-bot loops, CI fixes, descriptions, dependency triage."
     },
     {
-      "name": "olko:docs-index-keeper",
-      "source": "./packages/software-development/docs-index-keeper/adapters/grok",
-      "description": "Keep a Markdown docs index in sync through pre-commit, CI, or one-off maintenance flows."
+      "name": "olko-git-tools",
+      "source": "./adapters/grok/olko-git-tools",
+      "description": "Everyday git and GitHub CLI operations: conventional commits, branch hygiene."
     },
     {
-      "name": "olko:semantic-release-beta",
-      "source": "./packages/software-development/semantic-release-beta/adapters/grok",
-      "description": "Set up semantic-release-npm-github-publish with stable main releases and prerelease beta releases on a beta branch."
+      "name": "olko-release",
+      "source": "./adapters/grok/olko-release",
+      "description": "Ship a release: semantic-release setup, changelogs, store listing copy, release-day routine."
     },
     {
-      "name": "olko:gh-cli",
-      "source": "./packages/software-development/gh-cli/adapters/grok",
-      "description": "Use the GitHub CLI effectively for repositories, PRs, Actions, releases, and more."
+      "name": "olko-product",
+      "source": "./adapters/grok/olko-product",
+      "description": "Take a product idea to a shippable build: MVP passes, full-stack scaffolds, launch plans."
     },
     {
-      "name": "olko:git-commit",
-      "source": "./packages/software-development/git-commit/adapters/grok",
-      "description": "Create conventional commits with diff-aware staging and message generation."
+      "name": "olko-skill-meta",
+      "source": "./adapters/grok/olko-skill-meta",
+      "description": "Author and maintain agent skills and the AI toolchain itself."
     },
     {
-      "name": "olko:gallery",
-      "source": "./packages/photography/gallery/adapters/grok",
-      "description": "Create photo galleries with AI-assisted layout curation and sequencing."
+      "name": "olko-reflection",
+      "source": "./adapters/grok/olko-reflection",
+      "description": "Look back and improve: self-critique, retrospectives, performance review, rapid learning."
     },
     {
-      "name": "olko:promptctl",
-      "source": "./packages/software-development/promptctl/adapters/grok",
-      "description": "Use promptctl for template-based prompt engineering, scoring, and workflow automation."
+      "name": "olko-obsidian",
+      "source": "./adapters/grok/olko-obsidian",
+      "description": "Keep an Obsidian vault in sync with work: PR sync, task rollover, morning routine."
     },
     {
-      "name": "olko:fill-music-player",
-      "source": "./packages/music/fill-music-player/adapters/grok",
-      "description": "Fill a portable music player with a curated random selection from a source music library while balancing formats, artists, albums, and capacity."
+      "name": "olko-apple-kit",
+      "source": "./adapters/grok/olko-apple-kit",
+      "description": "Build and ship Apple platform apps: macOS menubar apps, App Store submissions."
     },
     {
-      "name": "olko:product-builder",
-      "source": "./packages/software-development/product-builder/adapters/grok",
-      "description": "Build a full-stack web application or SaaS product from a user description using production-oriented defaults."
+      "name": "olko-garmin-kit",
+      "source": "./adapters/grok/olko-garmin-kit",
+      "description": "Build, test and publish Garmin Connect IQ watch faces."
     },
     {
-      "name": "olko:mvp-oneshot",
-      "source": "./packages/software-development/mvp-oneshot/adapters/grok",
-      "description": "Turn a rough product idea into a shippable one-week MVP in one pass via a four-role prompt chain: scope a build prompt, ruthlessly trim it, plan the build, and self-review the vertical slice."
+      "name": "olko-creative",
+      "source": "./adapters/grok/olko-creative",
+      "description": "Creative and personal projects: photo galleries, music players, listings, wiki editing."
     },
     {
-      "name": "olko:starter-rules",
-      "source": "./packages/software-development/starter-rules/adapters/grok",
-      "description": "Load and enforce hard rules for every oleg-koval/* starter: 300-line files, E2E tests, pre-commit hooks, Vertical Slice architecture, no comments, KISS/DRY/SOLID."
-    },
-    {
-      "name": "olko:review-past-performance",
-      "source": "./packages/software-development/review-past-performance/adapters/grok",
-      "description": "Self-improvement loop that pulls the last 24h of ICM memories, git history, and skill analytics to detect repeated mistakes, slow workflows, and missing coverage, then proposes 1-3 concrete improvements."
-    },
-    {
-      "name": "olko:relay",
-      "source": "./packages/software-development/relay/adapters/grok",
-      "description": "Use claude-relay to run long or rate-limit-prone tasks autonomously across subscription accounts."
-    },
-    {
-      "name": "olko:open-source-publisher",
-      "source": "./packages/software-development/open-source-publisher/adapters/grok",
-      "description": "Prepare an open-source repository for public publishing with a minimal icon, social preview image, GitHub Pages site, README standardization, CI/CD checks, release hygiene, optional donation setup, and optional motion previews for generated static images."
-    },
-    {
-      "name": "olko:viral-launch",
-      "source": "./packages/marketing/viral-launch/adapters/grok",
-      "description": "Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops."
-    },
-    {
-      "name": "olko:search-console-indexing-audit",
-      "source": "./packages/marketing/search-console-indexing-audit/adapters/grok",
-      "description": "Analyze Google Search Console Coverage CSV exports and correlate them with sitemap, robots, canonical, redirect, and noindex signals."
-    },
-    {
-      "name": "olko:website-analytics-bootstrap",
-      "source": "./packages/marketing/website-analytics-bootstrap/adapters/grok",
-      "description": "Set up a website's first SEO analytics loop with persistent SerpBear rank tracking, Google Search Console, seeded keywords, read-only technical audits, and Telegram alerts on a local host or NAS."
-    },
-    {
-      "name": "olko:cloudflare-block-countries",
-      "source": "./packages/software-development/cloudflare-block-countries/adapters/grok",
-      "description": "Block specific countries via Cloudflare WAF Custom Rules using the Cloudflare API. Handles creating new rulesets and updating existing ones across single or multiple zones."
-    },
-    {
-      "name": "olko:obsidian-pr-sync",
-      "source": "./packages/software-development/obsidian-pr-sync/adapters/grok",
-      "description": "Fetch open GitHub PRs assigned to you or requesting your review, and write a grouped, age-sorted '## PRs to review' section into today's Obsidian daily note. Idempotent — re-running replaces the section."
-    },
-    {
-      "name": "olko:obsidian-task-rollover",
-      "source": "./packages/software-development/obsidian-task-rollover/adapters/grok",
-      "description": "Bullet-journal end-of-day task migration: copy unchecked tasks from today's Obsidian daily note to the next workday's note under '## Carried over', and mark them [>] in the source. Skips weekends, idempotent."
-    },
-    {
-      "name": "olko:apple-store-submit",
-      "source": "./packages/software-development/apple-store-submit/adapters/grok",
-      "description": "Handle Apple App Store rejection emails end-to-end: parse rejection reasons, plan fixes, implement code changes, navigate App Store Connect, and resubmit."
-    },
-    {
-      "name": "olko:macos-menubar-app",
-      "source": "./packages/software-development/macos-menubar-app/adapters/grok",
-      "description": "Build a production-quality macOS menubar or notch app in SwiftUI — MenuBarExtra, sandbox entitlements, keyboard shortcuts, sound effects, accessibility permissions, and App Store preparation."
-    },
-    {
-      "name": "olko:skill-budget-audit",
-      "source": "./packages/software-development/skill-budget-audit/adapters/grok",
-      "description": "Diagnose and fix Claude Code skill context budget overflow — identify heavy plugin bundles, remove domain-specific ones, and restore skill discoverability."
-    },
-    {
-      "name": "olko:crash-course",
-      "source": "./packages/software-development/crash-course/adapters/grok",
-      "description": "Expert tutor for rapid, source-grounded learning of any topic: a timed 4-hour sprint plus cheat-sheet, learning-ladder, quiz-me, Feynman, and resource-curation modes."
-    },
-    {
-      "name": "olko:pr-finalize",
-      "source": "./packages/software-development/pr-finalize/adapters/grok",
-      "description": "Drives one GitHub PR to genuinely merge-ready: rebases and resolves conflicts, sweeps every review bot and human comment to zero unaddressed findings, verifies unit and E2E coverage actually exists, runs the repo's real lint/format/test gates before pushing, and reports what still needs a human."
-    },
-    {
-      "name": "olko:pr-finalize-complete",
-      "source": "./packages/software-development/pr-finalize-complete/adapters/grok",
-      "description": "Confirms a PR is genuinely merge-ready when the work is already believed done: re-checks every review-bot and human finding against the current code, separates stale comments from fixed ones, runs the repo's real lint and test gates, and reports the evidence rather than the assumption."
-    },
-    {
-      "name": "olko:qodoloop",
-      "source": "./packages/software-development/qodoloop/adapters/grok",
-      "description": "Iteratively drives a GitHub PR to zero unresolved Qodo findings — reads each finding's own Agent Prompt, applies the fix, replies to the thread, resolves it, pushes, and waits for Qodo's next pass."
-    },
-    {
-      "name": "olko:garmin-watchface",
-      "source": "./packages/wearables/garmin-watchface/adapters/grok",
-      "description": "Design, build, test, screenshot and publish Garmin Connect IQ watch faces in Monkey C."
-    },
-    {
-      "name": "olko:coderabbitloop",
-      "source": "./packages/software-development/coderabbitloop/adapters/grok",
-      "description": "Iteratively drives a GitHub PR to zero unresolved CodeRabbit findings — reads each inline comment's own Prompt for AI Agents block, applies the fix, replies to the thread, resolves it, pushes, and re-triggers CodeRabbit."
-    },
-    {
-      "name": "olko:codexloop",
-      "source": "./packages/software-development/codexloop/adapters/grok",
-      "description": "Iteratively drives a GitHub PR to zero unresolved OpenAI Codex review comments — but verifies every finding against the real code first, fixes only the correct ones, and rebuts false positives without changing correct code."
-    },
-    {
-      "name": "olko:geminiloop",
-      "source": "./packages/software-development/geminiloop/adapters/grok",
-      "description": "Iteratively drives a GitHub PR to zero unresolved Gemini Code Assist comments — treats each one as a claim to verify, fixes only the genuinely-correct findings, and rebuts the rest with evidence instead of editing correct code."
-    },
-    {
-      "name": "olko:add-to-my-skills",
-      "source": "./packages/software-development/add-to-my-skills/adapters/grok",
-      "description": "Copy a newly created skill from another repo into this catalog, refresh the README and generated manifests, then commit and push."
-    },
-    {
-      "name": "olko:wrap-up",
-      "source": "./packages/software-development/wrap-up/adapters/grok",
-      "description": "Verify a completed task against its original objective, confirm applicable checks, and safely tidy task-owned artifacts, worktrees, and local branches."
-    },
-    {
-      "name": "olko:retro-analysis",
-      "source": "./packages/software-development/retro-analysis/adapters/grok",
-      "description": "Produce repository, comparison, and cross-project engineering retrospectives from delivery, code-quality, work-pattern, and trend evidence."
-    },
-    {
-      "name": "olko:ai-tools-setup",
-      "source": "./packages/software-development/ai-tools-setup/adapters/grok",
-      "description": "Set up, repair, and report on the RTK+ICM+Vox AI development toolkit, including hooks and MCP configuration."
-    },
-    {
-      "name": "olko:changelog-generator",
-      "source": "./packages/software-development/changelog-generator/adapters/grok",
-      "description": "Create user-facing changelogs from git history by categorising commits and rewriting them for readers rather than developers."
-    },
-    {
-      "name": "olko:wikipedia-uk-editor",
-      "source": "./packages/software-development/wikipedia-uk-editor/adapters/grok",
-      "description": "Draft policy-compliant Ukrainian Wikipedia edits — translate an English article into uk, expand or source an existing uk article, or fix a maintenance backlog item — and return ready-to-paste wikitext plus an edit summary."
-    },
-    {
-      "name": "olko:pr-description-writer",
-      "source": "./packages/software-development/pr-description-writer/adapters/grok",
-      "description": "Draft and post a GitHub PR title and body from git diff and commit history. Chains after git-commit and before qodoloop / coderabbitloop."
-    },
-    {
-      "name": "olko:ci-fix-loop",
-      "source": "./packages/software-development/ci-fix-loop/adapters/grok",
-      "description": "Diagnose GitHub Actions CI failures in a loop: fetch failing check logs, fix, push, and repeat until green. Direct analog of qodoloop / coderabbitloop for test and lint failures."
-    },
-    {
-      "name": "olko:pr-to-green",
-      "source": "./packages/software-development/pr-to-green/adapters/grok",
-      "description": "Orchestrate a GitHub PR from first push to merge-ready: run ci-fix-loop until checks are green, detect active AI review bots, run qodoloop and coderabbitloop in sequence, and confirm zero unresolved threads."
-    },
-    {
-      "name": "olko:dependabot-triage",
-      "source": "./packages/software-development/dependabot-triage/adapters/grok",
-      "description": "Triage open Dependabot and Renovate PRs in bulk: classify by risk tier, auto-approve and merge safe patch bumps, flag breaking major upgrades for human review, and post a digest."
-    },
-    {
-      "name": "olko:store-listing-copy",
-      "source": "./packages/software-development/store-listing-copy/adapters/grok",
-      "description": "Generate platform-validated App Store, Google Play, and Connect IQ store listing copy (title, subtitle, description, what's new, keywords) from a git changelog or release notes."
-    },
-    {
-      "name": "olko:pr-finalize-complete",
-      "source": "./packages/software-development/pr-finalize-complete/adapters/grok",
-      "description": "Comprehensive PR finalization workflow for PRs that may already be partially addressed: checks each review comment's actual current status in code, distinguishes fixed vs. stale vs. still-present findings, verifies test coverage, runs real lint/test gates, and reports what still needs a human."
-    },
-    {
-      "name": "olko:morning-routine",
-      "source": "./packages/software-development/morning-routine/adapters/grok",
-      "description": "Run the complete start-of-day setup in one pass: roll over unfinished Obsidian tasks to today's daily note, sync open GitHub PRs that need your attention, and sweep Dependabot patch bumps. Chains obsidian-task-rollover, obsidian-pr-sync, and dependabot-triage."
-    },
-    {
-      "name": "olko:release-day",
-      "source": "./packages/software-development/release-day/adapters/grok",
-      "description": "Orchestrate a full release-day workflow for iOS, Android, or Garmin apps: verify main branch CI is green, generate changelog, draft platform-ready store listing copy, trigger semantic-release or tag manually, wait for the build, and queue the App Store submission."
-    },
-    {
-      "name": "olko:branch-cleanup",
-      "source": "./packages/software-development/branch-cleanup/adapters/grok",
-      "description": "Prune stale git branches after a merge wave: delete closed/merged remote branches, remove local tracking refs that no longer exist on the remote, and optionally clean up merged local branches. Natural follow-up to dependabot-triage."
-    },
-    {
-      "name": "olko:vinted-listing",
-      "source": "./packages/software-development/vinted-listing/adapters/grok",
-      "description": "Create, edit, and safely publish Vinted listings through the signed-in browser, using verified item details and the owner’s original photos."
+      "name": "olko-web-ops",
+      "source": "./adapters/grok/olko-web-ops",
+      "description": "Operate a website: WAF rules, search console audits, analytics bootstrap, docs indexes."
     }
   ]
 }

package/.kiro/steering/retro-analysis.md

@@ -141,7 +141,25 @@ For `compare` or any window with a prior snapshot:
 
 Store a JSON snapshot with stable keys, UTC timestamps, resolved window, scope, repository identity, commit/PR identifiers, metric values, evidence limitations, and a short list of findings. Keep narrative prose out of fields intended for machine comparison. A snapshot is an aid to future analysis, not a source of truth that overrides current evidence.
 
-## 5. Produce the report
+## 5. Optionally promote durable lessons
+
+This phase is opt-in. A retrospective remains read-only unless the user or the surrounding workflow explicitly requests promotion to the shared ledger. Do not silently turn analysis into a write operation.
+
+Before adding any finding:
+
+1. Locate and read the current shared ledger. When a Git-backed repository ledger exists, read that repository file directly and treat it as authoritative. If it is absent or inaccessible, report `NOT_AVAILABLE` and do not claim that the ledger was checked.
+2. Classify the finding as one of:
+   - `local action` — a project- or task-specific follow-up that belongs in the report or backlog, not the shared ledger.
+   - `lesson` — a durable practice that generalizes across projects.
+   - `trap` — a non-obvious failure mode that can silently produce incorrect work.
+   - `preference` — a stable way the operator wants agents to work.
+3. Promote only non-obvious, durable, cross-project lessons, traps, or preferences. Keep local actions in the retrospective or project task system.
+4. Attach evidence to every promoted finding: a source path, commit, check, or other redacted reference, or the concrete failure that caused the rule. Do not promote an unsupported impression.
+5. Do not duplicate existing project instructions, shared-ledger notes, or behavior already enforced by an automated check. A thin ledger is more useful than a repetitive one.
+
+When promotion is authorized, append new notes using the current ledger schema; never rewrite, reorder, or overwrite existing entries. If no note is justified, append nothing. Report each added note ID, or `NOT_WRITTEN` when no note was added, promotion was not requested, or the ledger could not be safely updated.
+
+## 6. Produce the report
 
 Lead with a concise, shareable summary of the period. Then use this order:
 
@@ -160,7 +178,7 @@ Lead with a concise, shareable summary of the period. Then use this order:
 
 Use compact tables for exact metrics and prose for interpretation. Label inference as inference. Link or name evidence paths/commit IDs where useful, but never paste private content.
 
-## 6. End-of-task handoff
+## 7. End-of-task handoff
 
 If this run is explicitly closing a completed implementation, continue with `olko:wrap-up`:
 

package/.kiro/steering/wrap-up.md

@@ -57,20 +57,40 @@ Clean only paths created by this task or explicitly named for cleanup.
 
 ## 6. Report the result
 
-Lead with the outcome. Include concise evidence, cleanup performed, items intentionally preserved, and the smallest next action for any blocker. Always finish with this receipt, using `NOT_APPLICABLE` for out-of-scope gates and `NOT_RUN` for applicable checks that were not executed:
+Lead with the outcome. Use a short `DELIVERY RECEIPT` heading and a one- or
+two-sentence summary before the fields. Add `STATUS`, `NEXT_PHASE`, and
+`NEXT_STEP` near the top when follow-up work remains. Keep the required fields
+flush-left and grouped with one blank line between logical groups, not between
+every field. Keep each value concise and avoid repeating the same prose. Do
+not use Markdown tables, decorative separators, bullets, emojis, or indented
+continuation lines inside the canonical field block. Put `FINAL_STATUS` last.
+Add `LOCAL_COMMIT` when a local commit exists. Always finish with this receipt,
+using `NOT_APPLICABLE` for out-of-scope gates and `NOT_RUN` for applicable
+checks that were not executed:
 
 ```text
+DELIVERY RECEIPT
+
+<short outcome summary>
+STATUS: <DELIVERED | BLOCKED | INTENTIONALLY_UNCHANGED>
+NEXT_PHASE: <next phase or NOT_APPLICABLE>
+NEXT_STEP: <single smallest next action or NOT_APPLICABLE>
+
 OBJECTIVE:
 CHANGED:
 NOT_CHANGED:
+
 TESTS:
 BUILD:
+
 REMOTE:
 PR:
 CI:
 DEPLOYMENT:
 DEVICE_OR_HUMAN_QA:
+
 KNOWN_LIMITATIONS:
+LOCAL_COMMIT: <hash and subject, or NOT_APPLICABLE>
 FINAL_STATUS:
 ```
 

package/.windsurf/rules/retro-analysis.md

@@ -140,7 +140,25 @@ For `compare` or any window with a prior snapshot:
 
 Store a JSON snapshot with stable keys, UTC timestamps, resolved window, scope, repository identity, commit/PR identifiers, metric values, evidence limitations, and a short list of findings. Keep narrative prose out of fields intended for machine comparison. A snapshot is an aid to future analysis, not a source of truth that overrides current evidence.
 
-## 5. Produce the report
+## 5. Optionally promote durable lessons
+
+This phase is opt-in. A retrospective remains read-only unless the user or the surrounding workflow explicitly requests promotion to the shared ledger. Do not silently turn analysis into a write operation.
+
+Before adding any finding:
+
+1. Locate and read the current shared ledger. When a Git-backed repository ledger exists, read that repository file directly and treat it as authoritative. If it is absent or inaccessible, report `NOT_AVAILABLE` and do not claim that the ledger was checked.
+2. Classify the finding as one of:
+   - `local action` — a project- or task-specific follow-up that belongs in the report or backlog, not the shared ledger.
+   - `lesson` — a durable practice that generalizes across projects.
+   - `trap` — a non-obvious failure mode that can silently produce incorrect work.
+   - `preference` — a stable way the operator wants agents to work.
+3. Promote only non-obvious, durable, cross-project lessons, traps, or preferences. Keep local actions in the retrospective or project task system.
+4. Attach evidence to every promoted finding: a source path, commit, check, or other redacted reference, or the concrete failure that caused the rule. Do not promote an unsupported impression.
+5. Do not duplicate existing project instructions, shared-ledger notes, or behavior already enforced by an automated check. A thin ledger is more useful than a repetitive one.
+
+When promotion is authorized, append new notes using the current ledger schema; never rewrite, reorder, or overwrite existing entries. If no note is justified, append nothing. Report each added note ID, or `NOT_WRITTEN` when no note was added, promotion was not requested, or the ledger could not be safely updated.
+
+## 6. Produce the report
 
 Lead with a concise, shareable summary of the period. Then use this order:
 
@@ -159,7 +177,7 @@ Lead with a concise, shareable summary of the period. Then use this order:
 
 Use compact tables for exact metrics and prose for interpretation. Label inference as inference. Link or name evidence paths/commit IDs where useful, but never paste private content.
 
-## 6. End-of-task handoff
+## 7. End-of-task handoff
 
 If this run is explicitly closing a completed implementation, continue with `olko:wrap-up`:
 

package/.windsurf/rules/wrap-up.md

@@ -56,20 +56,40 @@ Clean only paths created by this task or explicitly named for cleanup.
 
 ## 6. Report the result
 
-Lead with the outcome. Include concise evidence, cleanup performed, items intentionally preserved, and the smallest next action for any blocker. Always finish with this receipt, using `NOT_APPLICABLE` for out-of-scope gates and `NOT_RUN` for applicable checks that were not executed:
+Lead with the outcome. Use a short `DELIVERY RECEIPT` heading and a one- or
+two-sentence summary before the fields. Add `STATUS`, `NEXT_PHASE`, and
+`NEXT_STEP` near the top when follow-up work remains. Keep the required fields
+flush-left and grouped with one blank line between logical groups, not between
+every field. Keep each value concise and avoid repeating the same prose. Do
+not use Markdown tables, decorative separators, bullets, emojis, or indented
+continuation lines inside the canonical field block. Put `FINAL_STATUS` last.
+Add `LOCAL_COMMIT` when a local commit exists. Always finish with this receipt,
+using `NOT_APPLICABLE` for out-of-scope gates and `NOT_RUN` for applicable
+checks that were not executed:
 
 ```text
+DELIVERY RECEIPT
+
+<short outcome summary>
+STATUS: <DELIVERED | BLOCKED | INTENTIONALLY_UNCHANGED>
+NEXT_PHASE: <next phase or NOT_APPLICABLE>
+NEXT_STEP: <single smallest next action or NOT_APPLICABLE>
+
 OBJECTIVE:
 CHANGED:
 NOT_CHANGED:
+
 TESTS:
 BUILD:
+
 REMOTE:
 PR:
 CI:
 DEPLOYMENT:
 DEVICE_OR_HUMAN_QA:
+
 KNOWN_LIMITATIONS:
+LOCAL_COMMIT: <hash and subject, or NOT_APPLICABLE>
 FINAL_STATUS:
 ```
 

package/CLAUDE.md

@@ -0,0 +1,39 @@
+# agent-skills
+
+An agent-agnostic skill catalog published to Claude Code, Codex, Cursor, Grok,
+Copilot, Windsurf and Kiro.
+
+## Hard rules
+
+- `catalog/skills.json` is the ONLY source of truth for plugin and skill
+  metadata. Everything else is generated.
+- NEVER hand-edit a generated file. Generated files carry
+  `<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->`.
+  Generated: every `plugins/*/.claude-plugin/plugin.json`,
+  `.claude-plugin/marketplace.json`, `.cursor-plugin/`, `.grok-plugin/`,
+  `adapters/`, `.windsurf/rules/`, `.kiro/steering/`, `.github/prompts/`,
+  `.github/copilot-instructions.md`.
+- Canonical skill content lives at `plugins/olko-<plugin>/skills/<skill>/SKILL.md`
+  and nowhere else.
+- After ANY catalog or skill change, run `./scripts/build-adapters.sh` and commit
+  the result. CI fails if the generated tree is stale.
+- Plugin names are kebab-case and prefixed `olko-`. Skill `name:` frontmatter is
+  unprefixed and must match its directory name.
+- Every skill belongs to exactly one plugin. Every plugin has at least one skill.
+- No em dashes in skill content or generated text.
+- Commit messages are conventional (`feat:`, `fix:`, `refactor:`, `docs:`,
+  `test:`, `chore:`); semantic-release parses them. Never mention an assistant.
+
+## Adding a skill
+
+1. Create `plugins/olko-<plugin>/skills/<skill>/SKILL.md` with valid frontmatter.
+2. Register it under that plugin's `skills` array in `catalog/skills.json`.
+3. Add it to `PLUGIN_ASSIGNMENT` in `scripts/lib/catalog.mjs`.
+4. Add its row to the README table.
+5. Run `./scripts/build-adapters.sh && npm test`.
+
+## Commands
+
+- `npm run build` regenerates every manifest and adapter.
+- `npm run validate` checks frontmatter and catalog integrity.
+- `npm test` runs the validators plus the bash tests in `tests/`.