@olegkoval/agent-skills 1.3.2 → 1.5.0

package/packages/software-development/ai-tools-setup/adapters/cursor/skills/ai-tools-setup/SKILL.md

@@ -0,0 +1,276 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+name: ai-tools-setup
+description: 'Set up, repair, and report on the RTK+ICM+Vox AI development toolkit. Installs missing tools, fixes broken hooks and MCP config, and shows an effectiveness digest — token savings, memory accumulation, voice health — on demand or as a scheduled weekly report.'
+license: MIT
+allowed-tools: Bash, Read, Edit, Write
+compatibility: Claude Code on macOS (Homebrew required)
+metadata:
+  author: Oleg Koval
+  tags:
+    - rtk
+    - icm
+    - vox
+    - setup
+    - hooks
+    - digest
+    - ai-tools
+    - productivity
+---
+
+# AI Tools Setup — RTK + ICM + Vox
+
+Install, repair, and measure the RTK+ICM+Vox toolkit for Claude Code.
+
+## What This Skill Does
+
+| Mode | When to use |
+|------|-------------|
+| **Setup** | First install on a new machine |
+| **Repair** | Something broke — hooks missing, MCP not loading |
+| **Digest** | Weekly check: token savings, memory health, voice stats |
+
+## Tools in the Bundle
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| **RTK** | latest | Compresses CLI output by ~89% before it reaches the model |
+| **ICM** | latest | Persistent SQLite memory across sessions (knowledge graph + hybrid search) |
+| **Vox** | latest | Spoken task notifications via local TTS — zero API calls |
+
+---
+
+## Step 1: Detect Current State
+
+Run this to see what is installed and what is missing:
+
+```bash
+echo "=== Binary check ===" && \
+  (rtk --version 2>/dev/null && echo "RTK: ok") || echo "RTK: MISSING" && \
+  (icm --version 2>/dev/null && echo "ICM: ok") || echo "ICM: MISSING" && \
+  (vox --version 2>/dev/null && echo "Vox: ok") || echo "Vox: MISSING"
+
+echo "=== RTK hook ===" && \
+  grep -c '"rtk hook claude"' ~/.claude/settings.json 2>/dev/null \
+    && echo "RTK hook: ok" || echo "RTK hook: MISSING"
+
+echo "=== ICM hooks ===" && \
+  grep -c '"icm hook' ~/.claude/settings.json 2>/dev/null \
+    && echo "ICM hooks: ok" || echo "ICM hooks: MISSING"
+
+echo "=== ICM MCP ===" && \
+  python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('ICM MCP: ok' if 'icm' in d.get('mcpServers',{}) else 'ICM MCP: MISSING')" 2>/dev/null || echo "ICM MCP: MISSING"
+
+echo "=== Vox MCP ===" && \
+  python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('Vox MCP: ok' if 'vox' in d.get('mcpServers',{}) else 'Vox MCP: MISSING')" 2>/dev/null || echo "Vox MCP: MISSING"
+
+echo "=== ICM CLAUDE.md ===" && \
+  grep -c 'icm:start' ~/.claude/CLAUDE.md 2>/dev/null \
+    && echo "ICM CLAUDE.md: ok" || echo "ICM CLAUDE.md: MISSING"
+```
+
+Read the output and determine which of the following repair steps are needed.
+
+---
+
+## Step 2: Install Missing Binaries
+
+Only run for tools that showed MISSING above.
+
+**RTK:**
+```bash
+brew install rtk
+rtk --version
+```
+
+**ICM:**
+```bash
+brew install rtk-ai/tap/icm
+icm --version
+```
+
+**Vox:**
+```bash
+brew install rtk-ai/tap/vox
+vox --version
+```
+
+---
+
+## Step 3: Repair Hooks
+
+### RTK hook missing
+
+Add the `PreToolUse` RTK hook to `~/.claude/settings.json`. Read the file first, then add inside the existing `"hooks"` block (or create one):
+
+```json
+"PreToolUse": [
+  {
+    "matcher": "Bash",
+    "hooks": [{ "type": "command", "command": "rtk hook claude" }]
+  }
+]
+```
+
+Then verify: `grep -c '"rtk hook claude"' ~/.claude/settings.json`
+
+### ICM hooks missing
+
+Run:
+```bash
+icm init --mode hook
+```
+
+This adds `PreToolUse`, `PostToolUse`, `PreCompact`, `UserPromptSubmit`, `SessionStart`, `SessionEnd` hooks automatically.
+
+### Vox Stop hook missing
+
+Run:
+```bash
+vox init --mode cli
+```
+
+---
+
+## Step 4: Repair MCP Servers
+
+### ICM MCP missing
+
+```bash
+icm init --mode mcp
+```
+
+### Vox MCP missing
+
+```bash
+vox init --mode mcp
+```
+
+Verify both by checking `~/.claude.json`:
+```bash
+python3 -c "import json; d=json.load(open('$HOME/.claude.json')); print(list(d.get('mcpServers',{}).keys()))"
+```
+
+---
+
+## Step 5: Repair CLAUDE.md Instructions
+
+If ICM instructions are missing from `~/.claude/CLAUDE.md`:
+
+```bash
+icm init --mode cli
+```
+
+Then move the block from wherever `icm init` placed it into `~/.claude/CLAUDE.md` (the global file), and remove it from any project-local files.
+
+---
+
+## Step 6: Effectiveness Digest
+
+Run this report to see how the toolkit is performing. Good to run weekly.
+
+```bash
+echo "=============================="
+echo "  AI TOOLS EFFECTIVENESS"
+echo "=============================="
+echo ""
+echo "--- RTK: Token Savings ---"
+rtk gain 2>/dev/null || echo "No data yet (run some commands first)"
+echo ""
+echo "--- ICM: Memory Health ---"
+icm health 2>/dev/null || echo "No memories yet"
+echo ""
+echo "--- ICM: Topics ---"
+icm topics 2>/dev/null || echo "No topics yet"
+echo ""
+echo "--- Vox: Usage ---"
+vox stats 2>/dev/null || echo "No stats yet"
+echo ""
+echo "=============================="
+```
+
+### What healthy output looks like
+
+- **RTK**: `Tokens saved: 5M+ (85%+)` across `500+ commands` — if savings are low, run `rtk discover` to find uncovered commands
+- **ICM**: Topics like `decisions-*`, `errors-resolved`, `preferences` with recent timestamps — if empty, start storing manually with `icm store`
+- **Vox**: Non-zero speak count means the Stop hook fired
+
+---
+
+## Step 7 (Optional): Schedule a Weekly Digest
+
+To get a weekly automated report without having to remember to run this skill:
+
+```bash
+# Create a weekly digest script
+cat > ~/ai-tools-digest.sh << 'EOF'
+#!/bin/bash
+echo "=== Weekly AI Tools Digest — $(date) ===" | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+rtk gain 2>/dev/null | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+icm health 2>/dev/null | tee -a ~/ai-tools-digest.log
+echo "" | tee -a ~/ai-tools-digest.log
+icm topics 2>/dev/null | tee -a ~/ai-tools-digest.log
+# Speak the summary if Vox is available
+vox "Weekly digest complete. Check your log." 2>/dev/null || true
+EOF
+chmod +x ~/ai-tools-digest.sh
+```
+
+Then set up a weekly launchd job (macOS):
+
+```bash
+cat > ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.oleg.ai-tools-digest</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>/Users/oleg.koval/ai-tools-digest.sh</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Weekday</key>
+    <integer>1</integer>
+    <key>Hour</key>
+    <integer>9</integer>
+    <key>Minute</key>
+    <integer>0</integer>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/ai-tools-digest.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/ai-tools-digest.err</string>
+</dict>
+</plist>
+EOF
+
+launchctl load ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist
+echo "Weekly digest scheduled for Mondays at 9am"
+```
+
+To view the digest log anytime: `cat ~/ai-tools-digest.log`
+
+To unload: `launchctl unload ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist`
+
+---
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| `rtk gain` | Total tokens saved to date |
+| `rtk discover` | Find commands not yet covered by RTK |
+| `icm topics` | List all memory topic buckets |
+| `icm health` | Memory hygiene — stale, redundant, decay stats |
+| `icm recall "query"` | Search memories semantically |
+| `icm store -t topic -c "content" -i high` | Store a memory manually |
+| `vox "text"` | Speak text immediately |
+| `vox stats` | Usage stats for the Vox backend |
+| `cat ~/ai-tools-digest.log` | View scheduled digest history |

package/packages/software-development/open-source-publisher/SKILL.md

@@ -52,6 +52,7 @@ Use this skill to audit whether an OSS repository is ready to publish, then help
    - social preview image
    - README standard
    - GitHub Pages landing page
+   - GitHub Pages analytics setup, if requested
    - CI/CD and release audit/fixes
    - donation wiring, if requested
 8. Validate locally and with browser/screenshots when possible.
@@ -73,6 +74,7 @@ Publish-critical checklist:
 - icon: simple SVG mark plus rendered PNG, both committed in predictable paths
 - social image: 1200x630 image with matching metadata, with both SVG source and rendered PNG committed when practical
 - GitHub Pages or docs site: essential install/examples/links/SEO/Open Graph metadata
+- GitHub Pages analytics: optional setup to track visitor patterns and engagement
 - CI quality gates: formatter, linter/static analysis, tests, build/package check
 - release automation: tags/releases/artifacts/package update flow, docs-only changes excluded where needed
 - security posture: license, security notes or policy, OpenSSF Scorecard or equivalent when appropriate
@@ -304,6 +306,49 @@ Implementation defaults:
 - Avoid marketing fluff and oversized hero sections for developer tools. Make the first viewport useful.
 - Use system UI fonts for body text and monospace only for commands, labels, or terminal-specific elements.
 
+## GitHub Pages Analytics
+
+Add basic analytics to track site visitor patterns and user behavior when the project has a GitHub Pages site.
+
+Setup options:
+
+- **Google Analytics** (free, detailed): Add UA or GA4 tracking ID to site `<head>`
+- **Plausible** (simple, privacy-first, paid): Lightweight script alternative
+- **Simple counter** (basic): Visitor count badge using Shields.io or statically-generated endpoint
+
+Minimal Google Analytics setup for static sites:
+
+```html
+<script async src="https://www.googletagmanager.com/gtag/js?id=G-YOUR_ID"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('js', new Date());
+  gtag('config', 'G-YOUR_ID');
+</script>
+```
+
+Track these essential events:
+
+- **pageview** (automatic): Site visitors and page sections
+- **download_release**: Clicks on install/download links (track each platform/format)
+- **view_docs**: Navigation to documentation pages
+- **github_click**: Click through to GitHub repo
+- **copy_command**: Code snippet copies in examples
+
+Optional custom events for OSS projects:
+
+- **search_docs**: If docs site has search
+- **view_example**: Specific example/use-case sections viewed
+- **support_click**: Link clicks to issues, discussions, or support channels
+
+Rules:
+
+- Add analytics after publishing the site; do not gate site launch on analytics.
+- If the user prefers privacy-first or no analytics, skip this step.
+- Store analytics credentials as GitHub Pages environment secret or site config, never in git.
+- Review monthly to catch unusual patterns or broken tracking links.
+
 ## CI/CD And Release Audit
 
 Check whether the repository has:

package/packages/software-development/open-source-publisher/adapters/claude/skills/open-source-publisher/SKILL.md

@@ -54,6 +54,7 @@ Use this skill to audit whether an OSS repository is ready to publish, then help
    - social preview image
    - README standard
    - GitHub Pages landing page
+   - GitHub Pages analytics setup, if requested
    - CI/CD and release audit/fixes
    - donation wiring, if requested
 8. Validate locally and with browser/screenshots when possible.
@@ -75,6 +76,7 @@ Publish-critical checklist:
 - icon: simple SVG mark plus rendered PNG, both committed in predictable paths
 - social image: 1200x630 image with matching metadata, with both SVG source and rendered PNG committed when practical
 - GitHub Pages or docs site: essential install/examples/links/SEO/Open Graph metadata
+- GitHub Pages analytics: optional setup to track visitor patterns and engagement
 - CI quality gates: formatter, linter/static analysis, tests, build/package check
 - release automation: tags/releases/artifacts/package update flow, docs-only changes excluded where needed
 - security posture: license, security notes or policy, OpenSSF Scorecard or equivalent when appropriate
@@ -306,6 +308,49 @@ Implementation defaults:
 - Avoid marketing fluff and oversized hero sections for developer tools. Make the first viewport useful.
 - Use system UI fonts for body text and monospace only for commands, labels, or terminal-specific elements.
 
+## GitHub Pages Analytics
+
+Add basic analytics to track site visitor patterns and user behavior when the project has a GitHub Pages site.
+
+Setup options:
+
+- **Google Analytics** (free, detailed): Add UA or GA4 tracking ID to site `<head>`
+- **Plausible** (simple, privacy-first, paid): Lightweight script alternative
+- **Simple counter** (basic): Visitor count badge using Shields.io or statically-generated endpoint
+
+Minimal Google Analytics setup for static sites:
+
+```html
+<script async src="https://www.googletagmanager.com/gtag/js?id=G-YOUR_ID"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('js', new Date());
+  gtag('config', 'G-YOUR_ID');
+</script>
+```
+
+Track these essential events:
+
+- **pageview** (automatic): Site visitors and page sections
+- **download_release**: Clicks on install/download links (track each platform/format)
+- **view_docs**: Navigation to documentation pages
+- **github_click**: Click through to GitHub repo
+- **copy_command**: Code snippet copies in examples
+
+Optional custom events for OSS projects:
+
+- **search_docs**: If docs site has search
+- **view_example**: Specific example/use-case sections viewed
+- **support_click**: Link clicks to issues, discussions, or support channels
+
+Rules:
+
+- Add analytics after publishing the site; do not gate site launch on analytics.
+- If the user prefers privacy-first or no analytics, skip this step.
+- Store analytics credentials as GitHub Pages environment secret or site config, never in git.
+- Review monthly to catch unusual patterns or broken tracking links.
+
 ## CI/CD And Release Audit
 
 Check whether the repository has:

package/packages/software-development/open-source-publisher/adapters/cursor/skills/open-source-publisher/SKILL.md

@@ -54,6 +54,7 @@ Use this skill to audit whether an OSS repository is ready to publish, then help
    - social preview image
    - README standard
    - GitHub Pages landing page
+   - GitHub Pages analytics setup, if requested
    - CI/CD and release audit/fixes
    - donation wiring, if requested
 8. Validate locally and with browser/screenshots when possible.
@@ -75,6 +76,7 @@ Publish-critical checklist:
 - icon: simple SVG mark plus rendered PNG, both committed in predictable paths
 - social image: 1200x630 image with matching metadata, with both SVG source and rendered PNG committed when practical
 - GitHub Pages or docs site: essential install/examples/links/SEO/Open Graph metadata
+- GitHub Pages analytics: optional setup to track visitor patterns and engagement
 - CI quality gates: formatter, linter/static analysis, tests, build/package check
 - release automation: tags/releases/artifacts/package update flow, docs-only changes excluded where needed
 - security posture: license, security notes or policy, OpenSSF Scorecard or equivalent when appropriate
@@ -306,6 +308,49 @@ Implementation defaults:
 - Avoid marketing fluff and oversized hero sections for developer tools. Make the first viewport useful.
 - Use system UI fonts for body text and monospace only for commands, labels, or terminal-specific elements.
 
+## GitHub Pages Analytics
+
+Add basic analytics to track site visitor patterns and user behavior when the project has a GitHub Pages site.
+
+Setup options:
+
+- **Google Analytics** (free, detailed): Add UA or GA4 tracking ID to site `<head>`
+- **Plausible** (simple, privacy-first, paid): Lightweight script alternative
+- **Simple counter** (basic): Visitor count badge using Shields.io or statically-generated endpoint
+
+Minimal Google Analytics setup for static sites:
+
+```html
+<script async src="https://www.googletagmanager.com/gtag/js?id=G-YOUR_ID"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('js', new Date());
+  gtag('config', 'G-YOUR_ID');
+</script>
+```
+
+Track these essential events:
+
+- **pageview** (automatic): Site visitors and page sections
+- **download_release**: Clicks on install/download links (track each platform/format)
+- **view_docs**: Navigation to documentation pages
+- **github_click**: Click through to GitHub repo
+- **copy_command**: Code snippet copies in examples
+
+Optional custom events for OSS projects:
+
+- **search_docs**: If docs site has search
+- **view_example**: Specific example/use-case sections viewed
+- **support_click**: Link clicks to issues, discussions, or support channels
+
+Rules:
+
+- Add analytics after publishing the site; do not gate site launch on analytics.
+- If the user prefers privacy-first or no analytics, skip this step.
+- Store analytics credentials as GitHub Pages environment secret or site config, never in git.
+- Review monthly to catch unusual patterns or broken tracking links.
+
 ## CI/CD And Release Audit
 
 Check whether the repository has:

package/packages/software-development/starter-rules/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: starter-rules
+description: Load and enforce the hard rules every oleg-koval/* starter must obey. Use when starting or auditing work in saas-init, ts-npm-starter, go-starter, py-starter, or any future oleg-koval template repo. Covers functional style, 300-line file cap, E2E > unit tests, pre-commit hooks, no-comment policy, KISS/DRY/SOLID, and Vertical Slice as default architecture for SaaS/app starters.
+license: MIT
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools.
+metadata:
+  author: Oleg Koval
+  tags:
+    - starters
+    - rules
+    - architecture
+    - vertical-slice
+    - linting
+    - pre-commit
+---
+
+# Starter Rules
+
+## Overview
+
+Load the canonical hard rules for every `oleg-koval/*` starter repo and verify the current repo complies with them. Produces a compliance report and a list of gaps to fix.
+
+## When to Use
+
+- Starting a new coding session in any `oleg-koval/*` template repo
+- Auditing an existing starter for rule compliance before a release or PR merge
+- Onboarding a new contributor (human or AI) to a starter
+- After a large refactor, to verify rules have not been silently violated
+
+Do not use for repos outside the `oleg-koval` namespace unless they explicitly reference `RULES.md`.
+
+## Workflow
+
+1. **Load the rules** — read `RULES.md` from the repo root. If absent, fetch it from `https://github.com/oleg-koval/starters/blob/main/RULES.md` and note that the starter is missing a local copy.
+
+2. **Apply §2 hard rules** — for the current task or PR diff, verify:
+   - No file exceeds 300 lines (`find . -name '*.ts' -o -name '*.py' -o -name '*.go' | xargs wc -l | awk '$1 > 300 && $2 != "total"'`)
+   - No functions produce side effects outside of boundary layers
+   - New code has no WHAT-comments; WHY-comments are one line max
+   - Tests are E2E-first; unit tests only for pure logic with non-trivial branching
+
+3. **Verify hooks and lint** — check that pre-commit hooks are installed and configured:
+   - TypeScript: `cat .eslintrc* | grep max-lines` and `cat package.json | grep -A5 '"lint-staged"\|"husky"\|"lefthook"'`
+   - Python: `cat .pre-commit-config.yaml` and check for `ruff` + format hooks
+   - Go: `cat .golangci.yml` or `.pre-commit-config.yaml` and check for `golangci-lint` + `gofmt`
+
+4. **Check architecture** — for app/SaaS starters: confirm feature code is organized as vertical slices (feature directory contains handler + DTO + service + tests together). For library starters: skip.
+
+5. **Report gaps** — list any violations found in steps 2–4. For each gap:
+   - Name the rule (e.g., "§2.2 file length")
+   - Name the file and line count or violation
+   - Propose the minimal fix
+
+6. **Fix on request** — if the user asks to fix the gaps, apply them one at a time, smallest change first. Do not refactor beyond what the rule requires.
+
+## Reference
+
+Full rule details: [`RULES.md`](./RULES.md)
+
+Architecture options and future starters: `RULES.md §3`
+
+Unix principles: `RULES.md §4`
+
+## Verification
+
+- [ ] `RULES.md` was read from the repo root (or fetched and absence noted)
+- [ ] File length check ran with zero violations, or violations were listed
+- [ ] Pre-commit hooks verified as installed and configured
+- [ ] Compliance report produced listing passed checks and gaps
+- [ ] Any fixes applied do not exceed the scope of the violated rule

package/packages/software-development/starter-rules/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-starter-rules",
+  "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.",
+  "skills": "./skills"
+}

package/packages/software-development/starter-rules/adapters/claude/skills/starter-rules/SKILL.md

@@ -0,0 +1,72 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+name: starter-rules
+description: Load and enforce the hard rules every oleg-koval/* starter must obey. Use when starting or auditing work in saas-init, ts-npm-starter, go-starter, py-starter, or any future oleg-koval template repo. Covers functional style, 300-line file cap, E2E > unit tests, pre-commit hooks, no-comment policy, KISS/DRY/SOLID, and Vertical Slice as default architecture for SaaS/app starters.
+license: MIT
+compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools.
+metadata:
+  author: Oleg Koval
+  tags:
+    - starters
+    - rules
+    - architecture
+    - vertical-slice
+    - linting
+    - pre-commit
+---
+
+# Starter Rules
+
+## Overview
+
+Load the canonical hard rules for every `oleg-koval/*` starter repo and verify the current repo complies with them. Produces a compliance report and a list of gaps to fix.
+
+## When to Use
+
+- Starting a new coding session in any `oleg-koval/*` template repo
+- Auditing an existing starter for rule compliance before a release or PR merge
+- Onboarding a new contributor (human or AI) to a starter
+- After a large refactor, to verify rules have not been silently violated
+
+Do not use for repos outside the `oleg-koval` namespace unless they explicitly reference `RULES.md`.
+
+## Workflow
+
+1. **Load the rules** — read `RULES.md` from the repo root. If absent, fetch it from `https://github.com/oleg-koval/starters/blob/main/RULES.md` and note that the starter is missing a local copy.
+
+2. **Apply §2 hard rules** — for the current task or PR diff, verify:
+   - No file exceeds 300 lines (`find . -name '*.ts' -o -name '*.py' -o -name '*.go' | xargs wc -l | awk '$1 > 300 && $2 != "total"'`)
+   - No functions produce side effects outside of boundary layers
+   - New code has no WHAT-comments; WHY-comments are one line max
+   - Tests are E2E-first; unit tests only for pure logic with non-trivial branching
+
+3. **Verify hooks and lint** — check that pre-commit hooks are installed and configured:
+   - TypeScript: `cat .eslintrc* | grep max-lines` and `cat package.json | grep -A5 '"lint-staged"\|"husky"\|"lefthook"'`
+   - Python: `cat .pre-commit-config.yaml` and check for `ruff` + format hooks
+   - Go: `cat .golangci.yml` or `.pre-commit-config.yaml` and check for `golangci-lint` + `gofmt`
+
+4. **Check architecture** — for app/SaaS starters: confirm feature code is organized as vertical slices (feature directory contains handler + DTO + service + tests together). For library starters: skip.
+
+5. **Report gaps** — list any violations found in steps 2–4. For each gap:
+   - Name the rule (e.g., "§2.2 file length")
+   - Name the file and line count or violation
+   - Propose the minimal fix
+
+6. **Fix on request** — if the user asks to fix the gaps, apply them one at a time, smallest change first. Do not refactor beyond what the rule requires.
+
+## Reference
+
+Full rule details: [`RULES.md`](./RULES.md)
+
+Architecture options and future starters: `RULES.md §3`
+
+Unix principles: `RULES.md §4`
+
+## Verification
+
+- [ ] `RULES.md` was read from the repo root (or fetched and absence noted)
+- [ ] File length check ran with zero violations, or violations were listed
+- [ ] Pre-commit hooks verified as installed and configured
+- [ ] Compliance report produced listing passed checks and gaps
+- [ ] Any fixes applied do not exceed the scope of the violated rule

package/packages/software-development/starter-rules/adapters/codex/README.md

@@ -0,0 +1,16 @@
+# Codex Adapter for starter-rules
+
+This is a Codex-specific adapter for the `olko:starter-rules` skill.
+The canonical skill definition is in `../../../SKILL.md`.
+
+## Usage
+
+Invoke in a Codex session:
+
+```
+Use the olko:starter-rules skill to load and enforce hard rules in this starter repo.
+```
+
+## Workflow
+
+See `../../../SKILL.md` for the full workflow.

package/packages/software-development/starter-rules/adapters/cursor/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "starter-rules",
+  "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.",
+  "rules": ["packages/software-development/starter-rules/adapters/cursor/skills/starter-rules/SKILL.md"]
+}