@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/thirdparty-ui-ux-pro-max/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/skills/thirdparty-web-interface-guidelines/ATTRIBUTION.md

@@ -0,0 +1,23 @@
+# Attribution — thirdparty-web-interface-guidelines
+
+| Field | Value |
+|-------|-------|
+| **Upstream** | [vercel-labs/web-interface-guidelines](https://github.com/vercel-labs/web-interface-guidelines) |
+| **Guidelines** | [vercel.com/design/guidelines](https://vercel.com/design/guidelines) |
+| **Install script** | `curl -fsSL https://vercel.com/design/guidelines/install \| bash` |
+| **Author** | Vercel Design Engineering |
+| **License** | [MIT](https://github.com/vercel-labs/web-interface-guidelines/blob/main/LICENSE) — Copyright (c) 2025 Vercel Labs |
+| **Local name** | `thirdparty-web-interface-guidelines` |
+| **Curated in** | [kensaurus/skills](https://github.com/kensaurus/skills) |
+
+## Companion command
+
+Slash command template: `commands/thirdparty-web-interface-guidelines.md`  
+Copy to `.cursor/commands/` in a project (or `~/.cursor/commands/` globally) for `/thirdparty-web-interface-guidelines`.
+
+## Update policy
+
+1. Fetch latest from `https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md`.
+2. Update both `SKILL.md` and `commands/thirdparty-web-interface-guidelines.md`.
+3. Preserve `thirdparty-` prefix and attribution blocks.
+4. Run `./install.sh` or `cursor-sync`.

package/skills/thirdparty-web-interface-guidelines/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: thirdparty-web-interface-guidelines
+description: >
+  Third-party skill — Vercel Web Interface Guidelines compliance (focus,
+  forms, animation, copy). Use when the user names Vercel or web interface
+  guidelines. Generic a11y → audit-accessibility.
+---
+
+# Web Interface Guidelines
+
+> **Third-party skill** (upstream-maintained). See [ATTRIBUTION.md](ATTRIBUTION.md).  
+> Upstream: [vercel-labs/web-interface-guidelines](https://github.com/vercel-labs/web-interface-guidelines) · [vercel.com/design/guidelines](https://vercel.com/design/guidelines) · Local name: `thirdparty-web-interface-guidelines`
+
+Review target files for compliance. Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.
+
+When the user provides specific files or patterns, review those. Otherwise ask which files to review.
+
+## Rules
+
+### Accessibility
+
+- Icon-only buttons need `aria-label`
+- Form controls need `<label>` or `aria-label`
+- Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
+- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
+- Images need `alt` (or `alt=""` if decorative)
+- Decorative icons need `aria-hidden="true"`
+- Async updates (toasts, validation) need `aria-live="polite"`
+- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
+- Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
+- `scroll-margin-top` on heading anchors
+
+### Focus States
+
+- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
+- Never `outline-none` / `outline: none` without focus replacement
+- Use `:focus-visible` over `:focus` (avoid focus ring on click)
+- Group focus with `:focus-within` for compound controls
+
+### Forms
+
+- Inputs need `autocomplete` and meaningful `name`
+- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
+- Never block paste (`onPaste` + `preventDefault`)
+- Labels clickable (`htmlFor` or wrapping control)
+- Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
+- Checkboxes/radios: label + control share single hit target (no dead zones)
+- Submit button stays enabled until request starts; spinner during request
+- Errors inline next to fields; focus first error on submit
+- Placeholders end with `…` and show example pattern
+- `autocomplete="off"` on non-auth fields to avoid password manager triggers
+- Warn before navigation with unsaved changes (`beforeunload` or router guard)
+
+### Animation
+
+- Honor `prefers-reduced-motion` (provide reduced variant or disable)
+- Animate `transform`/`opacity` only (compositor-friendly)
+- Never `transition: all`—list properties explicitly
+- Set correct `transform-origin`
+- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
+- Animations interruptible—respond to user input mid-animation
+
+### Typography
+
+- `…` not `...`
+- Curly quotes `"` `"` not straight `"`
+- Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+- Loading states end with `…`: `"Loading…"`, `"Saving…"`
+- `font-variant-numeric: tabular-nums` for number columns/comparisons
+- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
+
+### Content Handling
+
+- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
+- Flex children need `min-w-0` to allow text truncation
+- Handle empty states—don't render broken UI for empty strings/arrays
+- User-generated content: anticipate short, average, and very long inputs
+
+### Images
+
+- `<img>` needs explicit `width` and `height` (prevents CLS)
+- Below-fold images: `loading="lazy"`
+- Above-fold critical images: `priority` or `fetchpriority="high"`
+
+### Performance
+
+- Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
+- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
+- Batch DOM reads/writes; avoid interleaving
+- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
+- Add `<link rel="preconnect">` for CDN/asset domains
+- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
+
+### Navigation & State
+
+- URL reflects state—filters, tabs, pagination, expanded panels in query params
+- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
+- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar)
+- Destructive actions need confirmation modal or undo window—never immediate
+
+### Touch & Interaction
+
+- `touch-action: manipulation` (prevents double-tap zoom delay)
+- `-webkit-tap-highlight-color` set intentionally
+- `overscroll-behavior: contain` in modals/drawers/sheets
+- During drag: disable text selection, `inert` on dragged elements
+- `autoFocus` sparingly—desktop only, single primary input; avoid on mobile
+
+### Safe Areas & Layout
+
+- Full-bleed layouts need `env(safe-area-inset-*)` for notches
+- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
+- Flex/grid over JS measurement for layout
+
+### Dark Mode & Theming
+
+- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
+- `<meta name="theme-color">` matches page background
+- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
+
+### Locale & i18n
+
+- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
+- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
+- Detect language via `Accept-Language` / `navigator.languages`, not IP
+- Brand names, code tokens, identifiers: wrap with `translate="no"` to prevent garbled auto-translation
+
+### Hydration Safety
+
+- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
+- Date/time rendering: guard against hydration mismatch (server vs client)
+- `suppressHydrationWarning` only where truly needed
+
+### Hover & Interactive States
+
+- Buttons/links need `hover:` state (visual feedback)
+- Interactive states increase contrast: hover/active/focus more prominent than rest
+
+### Content & Copy
+
+- Active voice: "Install the CLI" not "The CLI will be installed"
+- Title Case for headings/buttons (Chicago style)
+- Numerals for counts: "8 deployments" not "eight"
+- Specific button labels: "Save API Key" not "Continue"
+- Error messages include fix/next step, not just problem
+- Second person; avoid first person
+- `&` over "and" where space-constrained
+
+### Anti-patterns (flag these)
+
+- `user-scalable=no` or `maximum-scale=1` disabling zoom
+- `onPaste` with `preventDefault`
+- `transition: all`
+- `outline-none` without focus-visible replacement
+- Inline `onClick` navigation without `<a>`
+- `<div>` or `<span>` with click handlers (should be `<button>`)
+- Images without dimensions
+- Large arrays `.map()` without virtualization
+- Form inputs without labels
+- Icon buttons without `aria-label`
+- Hardcoded date/number formats (use `Intl.*`)
+- `autoFocus` without clear justification
+
+## Output Format
+
+Group by file. Use `file:line` format (VS Code clickable). Terse findings.
+
+```text
+## src/Button.tsx
+
+src/Button.tsx:42 - icon button missing aria-label
+src/Button.tsx:18 - input lacks label
+src/Button.tsx:55 - animation missing prefers-reduced-motion
+src/Button.tsx:67 - transition: all → list properties
+
+## src/Modal.tsx
+
+src/Modal.tsx:12 - missing overscroll-behavior: contain
+src/Modal.tsx:34 - "..." → "…"
+
+## src/Card.tsx
+
+✓ pass
+```
+
+State issue + location. Skip explanation unless fix non-obvious. No preamble.
+
+---
+
+**Source:** [vercel-labs/web-interface-guidelines](https://github.com/vercel-labs/web-interface-guidelines) · [Vercel Web Interface Guidelines](https://vercel.com/design/guidelines). Installed in kenji as `thirdparty-web-interface-guidelines`. See [ATTRIBUTION.md](ATTRIBUTION.md).

package/skills/workflow-build-feature/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: workflow-build-feature
+description: >
+  Build a feature end to end: spec and TDD, implement, unit tests, Playwright
+  check, PR. Use when "build a feature" or "implement this end-to-end".
+  Spec/TDD loop only → workflow-spec-tdd. One bug → workflow-fix-and-ship.
+license: MIT
+---
+
+# workflow-build-feature — End-to-End Feature Build
+
+**Degree of freedom: MIXED.** How to implement Phase 2 `[HIGH freedom]`;
+phase order and "no implementation before RED" `[LOW freedom — run exactly]`.
+
+One command that runs the full feature loop. Don't skip phases — each gate
+catches a class of defects the next phase can't.
+
+## How to reason
+
+1. **Contract** — what observable behavior is in / out of scope?
+2. **Sequence** — which phase is next, and what would skipping it hide?
+3. **Prove** — RED was real; GREEN and smoke cover the contract
+4. **Handoff** — PR evidence is complete; no silent "looks done"
+
+## Worked example
+
+> **Contract:** "add a forgot-password link" — email reset, not a magic-link login rewrite.
+> **Sequence:** spec + RED on the request-reset handler before any UI.
+> **Prove:** RED failed on missing route; GREEN + Playwright submits the form and sees the check-email state.
+> **Handoff:** PR links the spec, the RED/GREEN commands, and the smoke screenshot.
+
+## Self-critique before reporting
+
+- **Phases intact** — none of spec / RED / unit / smoke / PR were skipped
+- **RED was real** — the failing test existed before implementation
+- **Full-stack** — if data was touched, the migration was applied and verified
+- **Right owner** — one named bug → `workflow-fix-and-ship`; spec loop only → `workflow-spec-tdd`
+
+---
+
+## Phase sequence  [LOW freedom — run exactly]
+
+```
+1. SPEC        → workflow-spec-tdd (contract, plan, RED test)
+2. BUILD       → implement against the spec (GREEN)
+3. UNIT TEST   → test-unit (edge cases, mocks, coverage)
+4. SMOKE       → test-playwright (drive the live app as a real user, fix pain points)
+5. PR          → workflow-pr (create PR with test evidence)
+```
+The turn ends at the Done criteria or at a real gate — a decision only the user can make, a missing credential, a failing service. A phase summary is a progress note, not a stopping point.
+
+---
+
+## Phase 1: Spec (read workflow-spec-tdd)  [LOW freedom — run exactly]
+
+> Read the `workflow-spec-tdd` skill and follow it.
+
+Key outputs:
+- Written spec (what it does, what it doesn't do, acceptance criteria)
+- File-mapped implementation plan (which files to create/edit)
+- A RED failing test that encodes the acceptance criteria
+
+When the ask is loosely specified, read the relevant routes, schema, tests, and sibling features broadly before writing the spec, so it is grounded in what the repo does rather than the first plausible reading.
+
+**Do not write implementation code until the spec and RED test exist.**
+
+---
+
+## Phase 2: Build  [HIGH freedom]
+
+Implement against the spec. Rules:
+- One logical change per commit
+- Match the file patterns already in the repo — no new abstractions unless the spec calls for them
+- Full-stack: if the feature reads/writes data, verify the DB migration is applied before the frontend ships (see full-stack-ship-discipline rule)
+- Scope stays where the spec put it. A pre-existing bug you find on the way is a follow-up in the PR description, not part of this change. Scratch scripts and one-off checks stay out of the repo. Edit files surgically — change the lines the feature needs, do not rewrite the file around them.
+
+---
+
+## Phase 3: Unit tests (read test-unit)  [LOW freedom — hand off]
+
+> Read the `test-unit` skill and follow it.
+
+Focus on:
+- The new code's happy path, error paths, and edge cases
+- Any shared utility functions introduced
+
+---
+
+## Phase 4: Smoke test (read test-playwright)  [LOW freedom — hand off]
+
+> Read the `test-playwright` skill and follow it.
+
+Drive the live app through the new feature as a real user. Fix pain points inline (full-stack: UI + API + DB). Capture screenshots as evidence.
+
+Before any browser action, apply `protocol-browser-anti-stall` rules.
+
+---
+
+## Phase 5: PR (read workflow-pr)  [LOW freedom — hand off]
+
+> Read the `workflow-pr` skill and follow it.
+
+Include in the PR description:
+- Link to the spec / acceptance criteria
+- Screenshots or screen recording from Phase 4
+- Migration notes if schema changed
+
+---
+
+## Done criteria  [LOW freedom — do not skip]
+
+- [ ] Spec written and agreed
+- [ ] RED test exists and was failing before implementation
+- [ ] Implementation makes test GREEN
+- [ ] Unit tests cover happy path + at least one error path
+- [ ] Smoke test drove the live app and found no blockers
+- [ ] DB migration applied and verified (if applicable)
+- [ ] PR open with description and evidence

package/skills/workflow-coding-discipline/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: workflow-coding-discipline
+description: >
+  Guardrails for writing, editing, refactoring, or debugging code: surface
+  assumptions, simplicity first, surgical changes. Use when vibe-coding keeps
+  producing wrong results, or for "think before coding" or "surgical changes".
+license: MIT
+---
+
+# Karpathy Behavioral Guidelines
+
+**Degree of freedom: HIGH.** How strictly to apply each guardrail is judgment.
+Trivial one-liners may skip the full loop; a wrong architectural guess may not.
+
+## How to reason
+
+1. **Observe** — what is already in the repo vs what you are about to invent
+2. **Interpret** — is this a one-liner or a tradeoff that needs a question?
+3. **Classify** — proceed / ask / simplify
+4. **Severity** — a silent assumption that changes public behavior is a fail
+
+## Worked example
+
+> **Observe:** user said "just add caching"; repo already has TanStack Query on the same endpoint.
+> **Interpret:** a second cache would duplicate, not simplify.
+> **Classify:** ask, then reuse Query — do not add Redis.
+> **Check:** surgical edit; no new abstraction.
+
+## Self-critique before reporting
+
+- **Thought first** — confusion was surfaced, not coded through
+- **Simpler option** — no extra layer without a repeating pattern
+- **Surgical** — unrelated files untouched
+- **Right owner** — scoped refactor → `workflow-refactor`; repo-wide pattern → `audit-code-quality`
+
+Four guardrails to apply on every non-trivial coding task. Bias toward caution over speed. For trivial one-liners (typo fixes, obvious renames), use judgment — not every change needs full rigor.
+
+If a project's own rules contradict any guideline below, the project rules win.
+
+---
+
+## 1. Think Before Coding  [HIGH freedom]
+
+**State your assumptions. Say when you're confused. Surface tradeoffs.**
+
+Before writing code:
+
+- State your assumptions explicitly. If uncertain, ask instead of guessing.
+- If multiple interpretations exist, present them — don't silently pick one.
+- If a simpler approach exists than what was requested, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+**Anti-pattern:** Reading an ambiguous request, picking one interpretation, building 200 lines, then discovering the user meant something else.
+
+---
+
+## 2. Simplicity First  [HIGH freedom]
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- No premature `try/catch`, `?.` chains, or `Array.isArray()` guards as the *primary* fix — those are symptom suppressors. Fix the root cause first; harden second.
+- If you wrote 200 lines and it could be 50, rewrite it before showing the user.
+
+**The test:** Would a senior engineer reading this say it's overcomplicated? If yes, simplify.
+
+---
+
+## 3. Surgical Changes  [HIGH freedom]
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting that's outside the task.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code or smells, **mention them** — don't delete or fix them in the same change.
+- Add tests where the task asks for them or where the repo already keeps that kind of test; scratch scripts and one-off checks stay out of the repo.
+- Edit in place — change the lines the task needs, don't rewrite the file around them.
+
+When your changes create orphans:
+
+- Remove imports, variables, or functions that *your* changes made unused.
+- Don't remove pre-existing dead code unless explicitly asked.
+
+**The test:** Every changed line in the diff should trace directly to the user's request. If a reviewer asks "why is this line different?" you should have an answer rooted in the task.
+
+---
+
+## 4. Goal-Driven Execution  [HIGH freedom]
+
+**Define success criteria. Loop until verified.**
+
+Transform imperative tasks into verifiable goals:
+
+| Instead of... | Transform to... |
+|---|---|
+| "Add validation" | "Write tests for invalid inputs, then make them pass" |
+| "Fix the bug" | "Write a test that reproduces it, then make it pass" |
+| "Refactor X" | "Ensure tests pass before and after" |
+| "Make it work" | "Define what 'work' means as a verifiable check, then verify" |
+
+For multi-step tasks, say in one line what you are about to do before the first tool call, then list the steps with the check that proves each:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") force the user back into the loop to clarify.
+
+---
+
+## Self-Check Before Returning a Result  [LOW freedom — do not skip]
+
+Before saying "done", confirm:
+
+- [ ] Every diff line traces to the user's request (Surgical Changes)
+- [ ] No unrequested features, abstractions, or configurability (Simplicity First)
+- [ ] Assumptions stated, ambiguities surfaced, not silently picked (Think Before Coding)
+- [ ] Success criteria defined and verified — not just "the code compiles" (Goal-Driven Execution)
+- [ ] Adjacent code, comments, and formatting left alone unless touching them was the task
+
+---
+
+## When These Guidelines Are Working
+
+- Diffs are minimal — no unrelated changes
+- Code is simple the first time — fewer rewrites
+- Clarifying questions appear *before* implementation, not after mistakes
+- PRs feel hand-crafted, not AI-sprawled
+
+---
+
+**Source:** Adapted from [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills), distilled from Andrej Karpathy's observations on LLM coding pitfalls. MIT licensed.