@olegkoval/agent-skills 1.6.0 → 1.7.0

package/.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/.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/.windsurf/rules/search-console-indexing-audit.md

@@ -0,0 +1,56 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Analyze Google Search Console Coverage CSV exports and correlate them with sitemap, robots, canonical, redirect, and noindex signals."
+---
+
+
+# search-console-indexing-audit
+
+Use this skill to turn Google Search Console Coverage exports into a concrete indexing fix plan.
+
+## Workflow
+
+1. Read the export directory first:
+   - `Chart.csv` for indexed/not-indexed trend and impressions
+   - `Metadata.csv` for property context such as sitemap scope
+   - `Critical issues.csv` and `Non-critical issues.csv` for issue buckets
+2. Run the summarizer when the standard CSV files are present:
+
+```bash
+python3 <skill-dir>/scripts/summarize_gsc_coverage.py <export-dir>
+python3 <skill-dir>/scripts/summarize_gsc_coverage.py <export-dir> --json
+```
+
+3. Inspect the target repo for SEO sources of truth:
+   - sitemap generation and whether listed URLs are canonical, indexable HTML pages
+   - robots rules, sitemap URL, and host hints
+   - canonical metadata, `metadataBase`, Open Graph URL base, and per-route `noindex`
+   - redirects across apex/www, http/https, trailing slash, moved routes, and legacy paths
+4. Check live URLs when network access is available:
+
+```bash
+curl -sS -I https://example.com/sitemap.xml
+curl -sS https://example.com/sitemap.xml
+curl -sS https://example.com/robots.txt
+curl -sS https://example.com/page | rg -o '<link rel="canonical"[^>]*>|<meta name="robots"[^>]*>'
+curl -sS -I -L --max-redirs 5 https://example.com/page
+```
+
+5. Map GSC buckets to fixes:
+   - `Page with redirect`: remove redirected URLs from sitemap and canonicals; submit only final 200 URLs.
+   - `Redirect error`: inspect redirect chains, protocol/host loops, blocked destinations, and non-200 final responses.
+   - `Alternate page with proper canonical tag`: usually acceptable; verify sitemap does not include alternates.
+   - `Discovered - currently not indexed`: improve crawl signals first: clean sitemap, canonical consistency, internal links, content quality, stable 200 responses, and lastmod accuracy.
+   - `Excluded by noindex`: verify it is intentional and keep those URLs out of sitemap.
+
+## Output
+
+Report:
+
+- Export summary: date range, indexed/not-indexed trend, issue buckets, and limitations.
+- Likely root cause, with evidence from files or live HTTP responses.
+- Prioritized fixes, smallest reliable change first.
+- Verification steps for local tests, build, live sitemap/robots/canonical checks, and Search Console validation.
+
+Call out when the export is aggregate-only and does not contain affected URL examples. Do not infer exact URLs unless the CSVs or live sitemap provide them.

package/.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/.windsurf/rules/starter-rules.md

@@ -0,0 +1,61 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+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

package/.windsurf/rules/viral-launch.md

@@ -0,0 +1,91 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops."
+---
+
+
+# viral-launch
+
+Use this skill when a user wants to launch a project, make a repo marketable, improve discoverability, or build shareable launch assets.
+
+This skill is opinionated: virality is not a promise. The goal is to make the project easy to understand, easy to share, and easy to act on.
+
+## Trigger phrases
+
+- make this repo launch-ready
+- set this up to go viral
+- prepare a product launch
+- create marketing assets for this project
+- improve the README for launch
+- prepare Product Hunt / Hacker News / X / LinkedIn launch copy
+- set up an open-source repo for growth
+
+## Workflow
+
+1. Inspect the project first:
+  - product purpose
+  - target user
+  - core use case
+  - current README and docs
+  - install or demo path
+  - screenshots, videos, or visual proof
+  - analytics or waitlist capture if present
+2. Define the launch angle in one sentence:
+  - who it is for
+  - what painful job it solves
+  - why now
+  - what makes it different
+3. Make the repo launch-ready:
+  - clear README headline and first paragraph
+  - demo or quickstart within the first screen
+  - installation steps that work from a clean checkout
+  - screenshots, GIF, or demo link where possible
+  - feature list based on outcomes, not implementation trivia
+  - examples for the highest-intent use cases
+  - badges only when they add trust
+  - license, contributing notes, and issue templates when useful
+4. Create launch assets:
+  - short tagline
+  - 1-paragraph announcement
+  - 5 social post variants
+  - Product Hunt tagline and description when relevant
+  - Hacker News title candidates when relevant
+  - launch email or DM when relevant
+  - creator/influencer outreach list criteria, not spam copy
+5. Design share loops:
+  - a reason users would show the output to someone else
+  - a public artifact worth linking
+  - a before/after demo
+  - a template, benchmark, checklist, or gallery that can travel
+  - referral or waitlist loop only if it fits the product
+6. Define proof and metrics:
+  - activation event
+  - share event
+  - conversion event
+  - retention proxy
+  - launch-day dashboard or simple tracking checklist
+7. Keep claims grounded:
+  - do not invent traction, logos, benchmarks, testimonials, or user counts
+  - mark assumptions explicitly
+  - prefer specific proof over hype
+  - avoid dark patterns and spam
+
+## Output format
+
+When planning, produce:
+
+- Launch angle
+- Repo changes
+- Launch assets
+- Share loops
+- Metrics
+- Risks and assumptions
+- Next actions
+
+When editing a repository, make the smallest useful set of changes first, then validate by reading the README from a new user's perspective.
+
+## References
+
+- `references/launch-checklist.md`
+- `references/external-skills.md`