@olegkoval/agent-skills 1.5.1 → 1.7.0

package/packages/software-development/product-builder/adapters/windsurf/rules/product-builder.md

@@ -0,0 +1,212 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Build a full-stack web application or SaaS product from a user description using production-oriented defaults."
+---
+
+
+# Product Builder
+
+You are a full-stack product builder. Your goal: **build real, working products — not prototypes**.
+
+## Core Philosophy
+
+- **Ship immediately** — No explanations, no questions about architecture. Code first.
+- **Full-stack defaults** — Every product includes auth, database, APIs, and UI.
+- **Real code patterns** — Use production-ready patterns, not toy examples.
+- **Minimal diffs** — Change only what's necessary. Respect existing code.
+
+## When a user asks to "build X"
+
+You MUST:
+1. Generate a working product, not a skeleton
+2. Include authentication
+3. Include database schema with migrations
+4. Include API routes with input validation
+5. Include a polished, responsive UI
+6. Include tests
+
+You MUST NOT:
+- Ask "what framework do you want?"
+- Ask "should we use a database?"
+- Ask "how many features?"
+- Create TODO comments for later implementation
+
+## Default Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **Framework** | Next.js 14 (App Router) |
+| **Language** | TypeScript (strict) |
+| **Styling** | Tailwind CSS + shadcn/ui |
+| **Database** | Prisma + PostgreSQL |
+| **Auth** | NextAuth.js |
+| **Validation** | Zod |
+| **State** | React Query + Zustand |
+| **Testing** | Vitest + React Testing Library + Playwright |
+
+The user can override any of these. If the project already uses a different stack, follow the existing stack.
+
+## Specialist Domains
+
+When building a product, apply expertise from these domains as needed:
+
+### UI Design
+- Tailwind CSS utility-first, mobile-first responsive
+- shadcn/ui components over custom solutions
+- Dark mode support with `class` strategy
+- Accessibility: semantic HTML, ARIA labels, keyboard nav, WCAG AA contrast
+- Animations with Framer Motion or CSS transitions
+- Component pattern: `cn()` utility for conditional classes
+
+### Database Architecture
+- Prisma schema with proper indexes and relations
+- Multi-tenant patterns when applicable (org-scoped data)
+- Referential integrity and cascade rules
+- Query optimization: use `select` and `include` deliberately
+- Migration strategy: always generate and review migrations
+- Audit fields: `createdAt`, `updatedAt` on every model
+
+### API Design
+- Consistent response format: `{ success: true, data }` / `{ success: false, error: { code, message } }`
+- Zod validation schemas for all inputs
+- Proper HTTP status codes (201 for creation, 400 for validation, 401/403 for auth)
+- Pagination: `page`, `limit`, `total`, `totalPages`
+- Rate limiting for public endpoints
+- Server Actions for form submissions
+
+### Testing
+- Vitest for unit and integration tests
+- React Testing Library for component tests
+- Playwright for E2E tests
+- Test critical paths: auth flows, CRUD operations, edge cases
+- Mock external services, not internal code
+- Factories/fixtures for test data
+
+## Code Quality Standards
+
+- TypeScript strict mode, no `any` types without justification
+- Error boundaries and proper error handling at every layer
+- Security-first: validate inputs, sanitize outputs, check permissions
+- Performance: memoize expensive renders, optimize queries, pagination
+- Accessibility: semantic HTML, ARIA labels, keyboard navigation
+
+## File Organization
+
+```
+app/
+  (auth)/              # Auth routes group
+    login/page.tsx
+    register/page.tsx
+  (app)/               # Protected routes group
+    dashboard/page.tsx
+    settings/page.tsx
+  api/                 # API routes
+    auth/route.ts
+    [resource]/route.ts
+  actions/             # Server actions
+lib/
+  db.ts                # Database client
+  auth.ts              # Auth config
+  api-response.ts      # Response helpers
+  validation.ts        # Zod schemas
+components/
+  ui/                  # shadcn/ui components
+  forms/               # Form components
+  layouts/             # Layout components
+prisma/
+  schema.prisma
+  migrations/
+__tests__/
+  unit/
+  integration/
+  e2e/
+```
+
+## API Response Pattern
+
+```typescript
+// lib/api-response.ts
+export type ApiResponse<T = unknown> =
+  | { success: true; data: T }
+  | { success: false; error: { code: string; message: string; details?: Record<string, string[]> } };
+
+export function successResponse<T>(data: T): ApiResponse<T> {
+  return { success: true, data };
+}
+
+export function errorResponse(code: string, message: string, details?: Record<string, string[]>): ApiResponse<never> {
+  return { success: false, error: { code, message, details } };
+}
+```
+
+## Route Handler Pattern
+
+```typescript
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { z } from 'zod';
+import { prisma } from '@/lib/db';
+import { auth } from '@/lib/auth';
+import { successResponse, errorResponse } from '@/lib/api';
+
+const createPostSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+  status: z.enum(['DRAFT', 'PUBLISHED']).default('DRAFT'),
+});
+
+export async function POST(request: NextRequest) {
+  const session = await auth();
+  if (!session?.user) {
+    return NextResponse.json(errorResponse('UNAUTHORIZED', 'Authentication required'), { status: 401 });
+  }
+
+  const body = await request.json();
+  const result = createPostSchema.safeParse(body);
+
+  if (!result.success) {
+    return NextResponse.json(
+      errorResponse('VALIDATION_ERROR', 'Invalid input', result.error.flatten().fieldErrors),
+      { status: 400 },
+    );
+  }
+
+  const post = await prisma.post.create({
+    data: { ...result.data, authorId: session.user.id },
+  });
+
+  return NextResponse.json(successResponse(post), { status: 201 });
+}
+```
+
+## Component Pattern
+
+```typescript
+import { cn } from '@/lib/utils';
+
+interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export function Card({ className, ...props }: CardProps) {
+  return (
+    <div
+      className={cn(
+        'rounded-lg border border-slate-200 bg-white p-6 shadow-sm',
+        'dark:border-slate-800 dark:bg-slate-950',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+## When Stuck or Uncertain
+
+Do not ask the user. Execute using best practices from the relevant domain. Default to the simplest solution that works.
+
+## Example Prompts
+
+See [examples.md](examples.md) for ready-to-use prompts covering SaaS dashboards, e-commerce, project management, AI chat apps, and more.

package/packages/software-development/promptctl/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: promptctl
 description: Use promptctl for template-based prompt engineering, prompt scoring, prompt generation, and reusable prompt workflows across repositories and teams.
-compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires promptctl to be installed when the workflow depends on the CLI.
+license: MIT
+allowed-tools: Bash, Read, Write
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires promptctl to be installed when the workflow depends on the CLI.
 metadata:
   author: Oleg Koval
   tags:

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

@@ -3,7 +3,9 @@
 ---
 name: promptctl
 description: Use promptctl for template-based prompt engineering, prompt scoring, prompt generation, and reusable prompt workflows across repositories and teams.
-compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires promptctl to be installed when the workflow depends on the CLI.
+license: MIT
+allowed-tools: Bash, Read, Write
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires promptctl to be installed when the workflow depends on the CLI.
 metadata:
   author: Oleg Koval
   tags:

package/packages/software-development/promptctl/adapters/cursor/skills/promptctl/SKILL.md

@@ -3,7 +3,9 @@
 ---
 name: promptctl
 description: Use promptctl for template-based prompt engineering, prompt scoring, prompt generation, and reusable prompt workflows across repositories and teams.
-compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires promptctl to be installed when the workflow depends on the CLI.
+license: MIT
+allowed-tools: Bash, Read, Write
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires promptctl to be installed when the workflow depends on the CLI.
 metadata:
   author: Oleg Koval
   tags:

package/packages/software-development/promptctl/adapters/kiro/steering/promptctl.md

@@ -0,0 +1,81 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Use promptctl for template-based prompt engineering, scoring, and workflow automation."
+---
+
+
+# promptctl — Template-Based Prompt Engineering
+
+promptctl is a CLI for version control and testing of LLM prompt templates. It treats prompts like code: template them, version them, score them, and share them across your team.
+
+## When to suggest promptctl
+
+Suggest using promptctl when the user:
+- Repeatedly copies the same type of prompt (code review, debug analysis, architecture notes)
+- Wants to share prompt conventions across a team or repo
+- Needs CI/CD gates on prompt quality
+- Wants to improve prompt quality without an LLM (offline rule-based enhance)
+- Asks about structuring or scoring a prompt
+
+## Core commands
+
+```
+promptctl review --file=src/auth.ts          # Code review prompt
+promptctl debug --file=src/handler.go        # Systematic debug analysis
+promptctl arch --file=docs/design.md         # Architecture decision record
+promptctl commit                             # Conventional commit message
+promptctl explain --file=src/parser.ts       # Code explanation
+
+promptctl list                               # See all available templates
+promptctl score prompts/                     # Score prompt files 0-100
+promptctl fix prompts/                       # Auto-fix low-scoring prompts
+promptctl create "review auth for security"  # Create prompt from raw intent (offline)
+```
+
+## Pi integration commands
+
+When the user is inside pi:
+- `/promptctl review --file=src/auth.ts` — renders the review template and injects it as the next user message
+- `/quick-templates` — lists all available templates
+- `/cost-score <file>` — scores a prompt file on structure and clarity
+- The `promptctl_apply` tool can be called by the LLM directly to render a template
+
+## Key capabilities
+
+- Templates are YAML files with `{{.variable}}` substitution — stored in `~/.promptctl/templates/` or `.promptctl/templates/` in your project
+- `--file=path` auto-populates `{{.file_content}}`, `{{.file_name}}`, `{{.file_ext}}`
+- Prompt scoring (0–100) on: structure, clarity, constraints, persona
+- Offline rule-based enhance (`promptctl create`) — no API key or network needed
+- JSON output and exit codes for CI pipelines (`promptctl score --min-score=80`)
+- Direct LLM send (`promptctl send review --file=main.go`) with Anthropic/OpenAI support
+
+## Example workflows
+
+**Code review in pi:**
+```
+/promptctl review --file=src/payments.ts --focus=security
+```
+
+**Debug analysis:**
+```
+/promptctl debug --file=src/worker.go --error="context deadline exceeded"
+```
+
+**Improve a prompt file:**
+```
+promptctl score my-prompt.md
+promptctl fix my-prompt.md
+```
+
+**Create a new structured prompt from intent (offline):**
+```
+promptctl create "analyze this Go function for race conditions"
+```
+
+## Resources
+
+- GitHub: https://github.com/oleg-koval/promptctl
+- Website: https://prompt-ctl.com
+- Install: `brew tap oleg-koval/tap && brew install promptctl`

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

@@ -0,0 +1,80 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Use promptctl for template-based prompt engineering, scoring, and workflow automation."
+---
+
+
+# promptctl — Template-Based Prompt Engineering
+
+promptctl is a CLI for version control and testing of LLM prompt templates. It treats prompts like code: template them, version them, score them, and share them across your team.
+
+## When to suggest promptctl
+
+Suggest using promptctl when the user:
+- Repeatedly copies the same type of prompt (code review, debug analysis, architecture notes)
+- Wants to share prompt conventions across a team or repo
+- Needs CI/CD gates on prompt quality
+- Wants to improve prompt quality without an LLM (offline rule-based enhance)
+- Asks about structuring or scoring a prompt
+
+## Core commands
+
+```
+promptctl review --file=src/auth.ts          # Code review prompt
+promptctl debug --file=src/handler.go        # Systematic debug analysis
+promptctl arch --file=docs/design.md         # Architecture decision record
+promptctl commit                             # Conventional commit message
+promptctl explain --file=src/parser.ts       # Code explanation
+
+promptctl list                               # See all available templates
+promptctl score prompts/                     # Score prompt files 0-100
+promptctl fix prompts/                       # Auto-fix low-scoring prompts
+promptctl create "review auth for security"  # Create prompt from raw intent (offline)
+```
+
+## Pi integration commands
+
+When the user is inside pi:
+- `/promptctl review --file=src/auth.ts` — renders the review template and injects it as the next user message
+- `/quick-templates` — lists all available templates
+- `/cost-score <file>` — scores a prompt file on structure and clarity
+- The `promptctl_apply` tool can be called by the LLM directly to render a template
+
+## Key capabilities
+
+- Templates are YAML files with `{{.variable}}` substitution — stored in `~/.promptctl/templates/` or `.promptctl/templates/` in your project
+- `--file=path` auto-populates `{{.file_content}}`, `{{.file_name}}`, `{{.file_ext}}`
+- Prompt scoring (0–100) on: structure, clarity, constraints, persona
+- Offline rule-based enhance (`promptctl create`) — no API key or network needed
+- JSON output and exit codes for CI pipelines (`promptctl score --min-score=80`)
+- Direct LLM send (`promptctl send review --file=main.go`) with Anthropic/OpenAI support
+
+## Example workflows
+
+**Code review in pi:**
+```
+/promptctl review --file=src/payments.ts --focus=security
+```
+
+**Debug analysis:**
+```
+/promptctl debug --file=src/worker.go --error="context deadline exceeded"
+```
+
+**Improve a prompt file:**
+```
+promptctl score my-prompt.md
+promptctl fix my-prompt.md
+```
+
+**Create a new structured prompt from intent (offline):**
+```
+promptctl create "analyze this Go function for race conditions"
+```
+
+## Resources
+
+- GitHub: https://github.com/oleg-koval/promptctl
+- Website: https://prompt-ctl.com
+- Install: `brew tap oleg-koval/tap && brew install promptctl`

package/packages/software-development/semantic-release-beta/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: semantic-release-beta
 description: Set up or update a Node.js release pipeline that uses semantic-release-npm-github-publish with a stable main channel and a prerelease beta channel on a beta branch, including GitHub Actions validation and npm publishing behavior.
-compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires a Node.js package repository that uses git and GitHub Actions.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires a Node.js package repository that uses git and GitHub Actions.
 metadata:
   author: Oleg Koval
   tags:

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

@@ -3,7 +3,9 @@
 ---
 name: semantic-release-beta
 description: Set up or update a Node.js release pipeline that uses semantic-release-npm-github-publish with a stable main channel and a prerelease beta channel on a beta branch, including GitHub Actions validation and npm publishing behavior.
-compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires a Node.js package repository that uses git and GitHub Actions.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires a Node.js package repository that uses git and GitHub Actions.
 metadata:
   author: Oleg Koval
   tags:

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

@@ -3,7 +3,9 @@
 ---
 name: semantic-release-beta
 description: Set up or update a Node.js release pipeline that uses semantic-release-npm-github-publish with a stable main channel and a prerelease beta channel on a beta branch, including GitHub Actions validation and npm publishing behavior.
-compatibility: Codex, Claude Code, Cursor, and other Agent Skills compatible tools. Requires a Node.js package repository that uses git and GitHub Actions.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires a Node.js package repository that uses git and GitHub Actions.
 metadata:
   author: Oleg Koval
   tags:

package/packages/software-development/semantic-release-beta/adapters/kiro/steering/semantic-release-beta.md

@@ -0,0 +1,48 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+description: "Set up semantic-release-npm-github-publish with stable main releases and prerelease beta releases on a beta branch."
+---
+
+
+# semantic-release-beta
+
+Use this skill when a project needs a reusable beta prerelease workflow with:
+
+- `semantic-release`
+- `semantic-release-npm-github-publish`
+- GitHub Actions
+- a stable `main` branch
+- a prerelease `beta` branch
+- npm publishing with `beta` prerelease versions
+- changelog generation, GitHub releases, npm publishing, and release commits through the maintained preset
+
+## Trigger phrases
+
+- add a beta release workflow
+- publish prereleases from a `beta` branch
+- set up `semantic-release` with `main` and `beta`
+- use `semantic-release-npm-github-publish`
+- add release validation or dry-run checks in CI
+
+## Workflow
+
+1. Inspect the repository first.
+2. Install or update `semantic-release`, `semantic-release-npm-github-publish`, and the peer plugins expected by the preset.
+3. Configure the repo-local semantic-release file to extend `semantic-release-npm-github-publish` and set branches explicitly:
+   - `main` for stable releases
+   - `{ name: "beta", channel: "beta", prerelease: "beta" }` for prereleases
+4. Add scripts if missing:
+   - `semantic-release`: `semantic-release`
+   - `release:dry-run`: `semantic-release --dry-run --no-ci`
+5. Update GitHub Actions to test both `main` and `beta`, validate npm auth, and run release dry-run before real releases.
+6. Preserve existing package manager and Node version policy unless the repo needs the preset's supported Node range.
+7. Use repo-local plugin composition instead of this preset only when the project needs different plugins, different release rules, or full control over plugin upgrade timing.
+
+## References
+
+- `references/preset.md`
+- `references/node-semantic-release.md`
+- `references/github-actions.md`
+- `references/validation.md`

package/packages/software-development/semantic-release-beta/adapters/windsurf/rules/semantic-release-beta.md

@@ -0,0 +1,47 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Set up semantic-release-npm-github-publish with stable main releases and prerelease beta releases on a beta branch."
+---
+
+
+# semantic-release-beta
+
+Use this skill when a project needs a reusable beta prerelease workflow with:
+
+- `semantic-release`
+- `semantic-release-npm-github-publish`
+- GitHub Actions
+- a stable `main` branch
+- a prerelease `beta` branch
+- npm publishing with `beta` prerelease versions
+- changelog generation, GitHub releases, npm publishing, and release commits through the maintained preset
+
+## Trigger phrases
+
+- add a beta release workflow
+- publish prereleases from a `beta` branch
+- set up `semantic-release` with `main` and `beta`
+- use `semantic-release-npm-github-publish`
+- add release validation or dry-run checks in CI
+
+## Workflow
+
+1. Inspect the repository first.
+2. Install or update `semantic-release`, `semantic-release-npm-github-publish`, and the peer plugins expected by the preset.
+3. Configure the repo-local semantic-release file to extend `semantic-release-npm-github-publish` and set branches explicitly:
+   - `main` for stable releases
+   - `{ name: "beta", channel: "beta", prerelease: "beta" }` for prereleases
+4. Add scripts if missing:
+   - `semantic-release`: `semantic-release`
+   - `release:dry-run`: `semantic-release --dry-run --no-ci`
+5. Update GitHub Actions to test both `main` and `beta`, validate npm auth, and run release dry-run before real releases.
+6. Preserve existing package manager and Node version policy unless the repo needs the preset's supported Node range.
+7. Use repo-local plugin composition instead of this preset only when the project needs different plugins, different release rules, or full control over plugin upgrade timing.
+
+## References
+
+- `references/preset.md`
+- `references/node-semantic-release.md`
+- `references/github-actions.md`
+- `references/validation.md`

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

@@ -2,7 +2,8 @@
 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.
+allowed-tools: Read, Bash
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools.
 metadata:
   author: Oleg Koval
   tags:

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

@@ -4,7 +4,8 @@
 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.
+allowed-tools: Read, Bash
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools.
 metadata:
   author: Oleg Koval
   tags:

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

@@ -1,5 +1,6 @@
 {
-  "name": "starter-rules",
+  "name": "olko:starter-rules",
+  "version": "0.1.0",
   "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"]
+  "skills": "skills/"
 }

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

@@ -4,7 +4,8 @@
 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.
+allowed-tools: Read, Bash
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools.
 metadata:
   author: Oleg Koval
   tags:

package/packages/software-development/starter-rules/adapters/kiro/steering/starter-rules.md

@@ -0,0 +1,62 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+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."
+---
+
+
+# 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