ada-agent 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (339) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +256 -0
  3. package/bench/README.md +88 -0
  4. package/bench/swebench.mjs +242 -0
  5. package/bin/ada-server.mjs +6 -0
  6. package/bin/ada.mjs +7 -0
  7. package/docs/agent-loop.svg +66 -0
  8. package/docs/architecture.md +139 -0
  9. package/docs/architecture.svg +73 -0
  10. package/docs/connectors.md +48 -0
  11. package/docs/integrations.md +59 -0
  12. package/docs/login-flow.svg +56 -0
  13. package/docs/orchestration.md +45 -0
  14. package/package.json +64 -0
  15. package/skills/accessibility/SKILL.md +23 -0
  16. package/skills/add-logging/SKILL.md +23 -0
  17. package/skills/add-metrics/SKILL.md +23 -0
  18. package/skills/adr/SKILL.md +24 -0
  19. package/skills/aesthetic-direction/SKILL.md +24 -0
  20. package/skills/agent-loop/SKILL.md +23 -0
  21. package/skills/alerting/SKILL.md +23 -0
  22. package/skills/alpha-compositing/SKILL.md +23 -0
  23. package/skills/android-compose/SKILL.md +23 -0
  24. package/skills/angular-module/SKILL.md +23 -0
  25. package/skills/ansible-playbook/SKILL.md +24 -0
  26. package/skills/api-docs/SKILL.md +24 -0
  27. package/skills/app-store-prep/SKILL.md +23 -0
  28. package/skills/architecture-diagram/SKILL.md +21 -0
  29. package/skills/architecture-doc/SKILL.md +24 -0
  30. package/skills/audit-log/SKILL.md +23 -0
  31. package/skills/authz-review/SKILL.md +23 -0
  32. package/skills/aws-lambda/SKILL.md +24 -0
  33. package/skills/bash-script/SKILL.md +23 -0
  34. package/skills/batch/SKILL.md +23 -0
  35. package/skills/bisect/SKILL.md +23 -0
  36. package/skills/bounding-box/SKILL.md +24 -0
  37. package/skills/branch-cleanup/SKILL.md +23 -0
  38. package/skills/bundle-analyze/SKILL.md +23 -0
  39. package/skills/cache/SKILL.md +23 -0
  40. package/skills/call-graph/SKILL.md +23 -0
  41. package/skills/canvas-debug/SKILL.md +23 -0
  42. package/skills/cdn-setup/SKILL.md +23 -0
  43. package/skills/changelog/SKILL.md +24 -0
  44. package/skills/cherry-pick/SKILL.md +23 -0
  45. package/skills/ci-setup/SKILL.md +23 -0
  46. package/skills/cleanup/SKILL.md +23 -0
  47. package/skills/cli-tool/SKILL.md +23 -0
  48. package/skills/cloudformation/SKILL.md +23 -0
  49. package/skills/code-examples/SKILL.md +24 -0
  50. package/skills/code-review/SKILL.md +23 -0
  51. package/skills/color-palette/SKILL.md +24 -0
  52. package/skills/color-space/SKILL.md +24 -0
  53. package/skills/comment-why/SKILL.md +23 -0
  54. package/skills/commit/SKILL.md +26 -0
  55. package/skills/complexity-audit/SKILL.md +23 -0
  56. package/skills/component/SKILL.md +23 -0
  57. package/skills/component-library/SKILL.md +23 -0
  58. package/skills/connect-github/SKILL.md +20 -0
  59. package/skills/connect-mcp/SKILL.md +21 -0
  60. package/skills/connect-postgres/SKILL.md +20 -0
  61. package/skills/connect-remote/SKILL.md +23 -0
  62. package/skills/connect-slack/SKILL.md +20 -0
  63. package/skills/contract-audit/SKILL.md +25 -0
  64. package/skills/contributing/SKILL.md +23 -0
  65. package/skills/cpp-raii/SKILL.md +23 -0
  66. package/skills/cron-job/SKILL.md +23 -0
  67. package/skills/cv-preprocess/SKILL.md +24 -0
  68. package/skills/dark-mode/SKILL.md +24 -0
  69. package/skills/dashboard/SKILL.md +23 -0
  70. package/skills/dashboard-ui/SKILL.md +23 -0
  71. package/skills/data-export/SKILL.md +23 -0
  72. package/skills/data-validation/SKILL.md +23 -0
  73. package/skills/dataframe/SKILL.md +23 -0
  74. package/skills/db-index/SKILL.md +24 -0
  75. package/skills/dead-code/SKILL.md +23 -0
  76. package/skills/debug/SKILL.md +24 -0
  77. package/skills/deck-review/SKILL.md +24 -0
  78. package/skills/dedupe/SKILL.md +23 -0
  79. package/skills/dedupe-deps/SKILL.md +23 -0
  80. package/skills/dependency-audit/SKILL.md +23 -0
  81. package/skills/dependency-update/SKILL.md +23 -0
  82. package/skills/deploy/SKILL.md +23 -0
  83. package/skills/design-system/SKILL.md +24 -0
  84. package/skills/design-tokens/SKILL.md +24 -0
  85. package/skills/diagram-as-code/SKILL.md +24 -0
  86. package/skills/diff-explain/SKILL.md +23 -0
  87. package/skills/django-view/SKILL.md +23 -0
  88. package/skills/doc-lint/SKILL.md +24 -0
  89. package/skills/docker-compose/SKILL.md +23 -0
  90. package/skills/dockerize/SKILL.md +23 -0
  91. package/skills/docstrings/SKILL.md +23 -0
  92. package/skills/dotfiles/SKILL.md +23 -0
  93. package/skills/dpi-scaling/SKILL.md +23 -0
  94. package/skills/e2e-test/SKILL.md +23 -0
  95. package/skills/embeddings/SKILL.md +23 -0
  96. package/skills/empty-states/SKILL.md +23 -0
  97. package/skills/env-setup/SKILL.md +23 -0
  98. package/skills/erc20/SKILL.md +24 -0
  99. package/skills/error-tracking/SKILL.md +23 -0
  100. package/skills/estimate/SKILL.md +23 -0
  101. package/skills/etl-pipeline/SKILL.md +24 -0
  102. package/skills/eval-harness/SKILL.md +23 -0
  103. package/skills/exif-orientation/SKILL.md +23 -0
  104. package/skills/explain-code/SKILL.md +23 -0
  105. package/skills/express-middleware/SKILL.md +23 -0
  106. package/skills/extract-function/SKILL.md +23 -0
  107. package/skills/faq/SKILL.md +24 -0
  108. package/skills/fastapi-endpoint/SKILL.md +23 -0
  109. package/skills/favicon/SKILL.md +23 -0
  110. package/skills/feature-engineering/SKILL.md +23 -0
  111. package/skills/few-shot/SKILL.md +23 -0
  112. package/skills/find-owner/SKILL.md +23 -0
  113. package/skills/firmware-driver/SKILL.md +23 -0
  114. package/skills/fix-flaky-tests/SKILL.md +23 -0
  115. package/skills/flutter-widget/SKILL.md +23 -0
  116. package/skills/font-rendering/SKILL.md +23 -0
  117. package/skills/form-validation/SKILL.md +23 -0
  118. package/skills/format/SKILL.md +23 -0
  119. package/skills/game-loop/SKILL.md +23 -0
  120. package/skills/gas-optimize/SKILL.md +25 -0
  121. package/skills/gdpr-review/SKILL.md +24 -0
  122. package/skills/github-actions/SKILL.md +23 -0
  123. package/skills/glossary/SKILL.md +24 -0
  124. package/skills/go-idioms/SKILL.md +23 -0
  125. package/skills/gpu-profile/SKILL.md +23 -0
  126. package/skills/graphify/SKILL.md +21 -0
  127. package/skills/graphql-resolver/SKILL.md +23 -0
  128. package/skills/grpc-service/SKILL.md +23 -0
  129. package/skills/guardrails/SKILL.md +23 -0
  130. package/skills/healthcheck/SKILL.md +23 -0
  131. package/skills/heisenbug/SKILL.md +23 -0
  132. package/skills/helm-chart/SKILL.md +24 -0
  133. package/skills/hero-section/SKILL.md +23 -0
  134. package/skills/html-email/SKILL.md +24 -0
  135. package/skills/html-form/SKILL.md +23 -0
  136. package/skills/html-sanitize/SKILL.md +23 -0
  137. package/skills/html-table/SKILL.md +23 -0
  138. package/skills/html-to-pdf/SKILL.md +23 -0
  139. package/skills/http-client/SKILL.md +23 -0
  140. package/skills/i18n/SKILL.md +23 -0
  141. package/skills/i2c-spi/SKILL.md +23 -0
  142. package/skills/image-decode/SKILL.md +24 -0
  143. package/skills/image-memory/SKILL.md +24 -0
  144. package/skills/image-perf/SKILL.md +24 -0
  145. package/skills/image-pipeline/SKILL.md +24 -0
  146. package/skills/image-upload/SKILL.md +24 -0
  147. package/skills/infra-cost/SKILL.md +24 -0
  148. package/skills/input-validation/SKILL.md +23 -0
  149. package/skills/issue-template/SKILL.md +23 -0
  150. package/skills/java-streams/SKILL.md +23 -0
  151. package/skills/k8s-manifest/SKILL.md +23 -0
  152. package/skills/kotlin-coroutines/SKILL.md +23 -0
  153. package/skills/landing-page/SKILL.md +24 -0
  154. package/skills/laravel-controller/SKILL.md +23 -0
  155. package/skills/lazy-load/SKILL.md +23 -0
  156. package/skills/license-check/SKILL.md +23 -0
  157. package/skills/license-header/SKILL.md +23 -0
  158. package/skills/lint-fix/SKILL.md +23 -0
  159. package/skills/llm-cost/SKILL.md +23 -0
  160. package/skills/lockfile-fix/SKILL.md +23 -0
  161. package/skills/low-power/SKILL.md +23 -0
  162. package/skills/makefile/SKILL.md +23 -0
  163. package/skills/man-page/SKILL.md +24 -0
  164. package/skills/mcp-server/SKILL.md +23 -0
  165. package/skills/memory-leak/SKILL.md +23 -0
  166. package/skills/mermaid-diagram/SKILL.md +23 -0
  167. package/skills/meta-tags/SKILL.md +23 -0
  168. package/skills/micro-interactions/SKILL.md +23 -0
  169. package/skills/migration/SKILL.md +23 -0
  170. package/skills/migration-guide/SKILL.md +24 -0
  171. package/skills/mkdocs-setup/SKILL.md +24 -0
  172. package/skills/mobile-permissions/SKILL.md +23 -0
  173. package/skills/mock-api/SKILL.md +23 -0
  174. package/skills/modernize/SKILL.md +23 -0
  175. package/skills/monorepo-setup/SKILL.md +23 -0
  176. package/skills/motion-design/SKILL.md +23 -0
  177. package/skills/n-plus-one/SKILL.md +23 -0
  178. package/skills/naming-review/SKILL.md +23 -0
  179. package/skills/nextjs-route/SKILL.md +23 -0
  180. package/skills/nginx-config/SKILL.md +23 -0
  181. package/skills/ocr-debug/SKILL.md +24 -0
  182. package/skills/onboard/SKILL.md +23 -0
  183. package/skills/onboarding-map/SKILL.md +23 -0
  184. package/skills/open-pr/SKILL.md +24 -0
  185. package/skills/openapi/SKILL.md +23 -0
  186. package/skills/opencv-debug/SKILL.md +24 -0
  187. package/skills/orm-model/SKILL.md +23 -0
  188. package/skills/owasp-check/SKILL.md +24 -0
  189. package/skills/page-transitions/SKILL.md +23 -0
  190. package/skills/pagination/SKILL.md +23 -0
  191. package/skills/perf-optimize/SKILL.md +23 -0
  192. package/skills/perf-profile/SKILL.md +23 -0
  193. package/skills/physics/SKILL.md +23 -0
  194. package/skills/pitch-deck/SKILL.md +24 -0
  195. package/skills/pixel-diff/SKILL.md +23 -0
  196. package/skills/ponytail/SKILL.md +46 -0
  197. package/skills/postmortem/SKILL.md +24 -0
  198. package/skills/pptx-deck/SKILL.md +23 -0
  199. package/skills/pptx-export/SKILL.md +23 -0
  200. package/skills/pptx-from-markdown/SKILL.md +23 -0
  201. package/skills/pptx-template/SKILL.md +24 -0
  202. package/skills/pr-review/SKILL.md +24 -0
  203. package/skills/precommit/SKILL.md +23 -0
  204. package/skills/pricing-page/SKILL.md +23 -0
  205. package/skills/project-overview/SKILL.md +22 -0
  206. package/skills/prompt-template/SKILL.md +23 -0
  207. package/skills/property-test/SKILL.md +23 -0
  208. package/skills/protobuf/SKILL.md +23 -0
  209. package/skills/py-async/SKILL.md +23 -0
  210. package/skills/py-typing/SKILL.md +23 -0
  211. package/skills/query-optimize/SKILL.md +23 -0
  212. package/skills/rag-pipeline/SKILL.md +23 -0
  213. package/skills/rails-resource/SKILL.md +23 -0
  214. package/skills/rate-limit/SKILL.md +23 -0
  215. package/skills/react-hooks/SKILL.md +23 -0
  216. package/skills/react-native-screen/SKILL.md +23 -0
  217. package/skills/react-perf/SKILL.md +23 -0
  218. package/skills/readme/SKILL.md +24 -0
  219. package/skills/rebase/SKILL.md +24 -0
  220. package/skills/refactor/SKILL.md +23 -0
  221. package/skills/regression-test/SKILL.md +23 -0
  222. package/skills/release-notes/SKILL.md +24 -0
  223. package/skills/rename-symbol/SKILL.md +23 -0
  224. package/skills/repro/SKILL.md +23 -0
  225. package/skills/resolve-conflicts/SKILL.md +23 -0
  226. package/skills/responsive/SKILL.md +23 -0
  227. package/skills/rest-endpoint/SKILL.md +23 -0
  228. package/skills/retro/SKILL.md +23 -0
  229. package/skills/rtos-task/SKILL.md +23 -0
  230. package/skills/runbook/SKILL.md +25 -0
  231. package/skills/rust-borrow/SKILL.md +23 -0
  232. package/skills/rust-unsafe-audit/SKILL.md +23 -0
  233. package/skills/sanitize/SKILL.md +23 -0
  234. package/skills/schema-design/SKILL.md +23 -0
  235. package/skills/screenshot-debug/SKILL.md +22 -0
  236. package/skills/scroll-animation/SKILL.md +23 -0
  237. package/skills/secret-scan/SKILL.md +23 -0
  238. package/skills/security-audit/SKILL.md +23 -0
  239. package/skills/security-review/SKILL.md +23 -0
  240. package/skills/seed-data/SKILL.md +23 -0
  241. package/skills/self-review/SKILL.md +23 -0
  242. package/skills/semantic-html/SKILL.md +23 -0
  243. package/skills/semver-bump/SKILL.md +24 -0
  244. package/skills/shader/SKILL.md +23 -0
  245. package/skills/shader-debug/SKILL.md +23 -0
  246. package/skills/simplify-conditionals/SKILL.md +23 -0
  247. package/skills/sitemap/SKILL.md +23 -0
  248. package/skills/skeleton-loader/SKILL.md +23 -0
  249. package/skills/slide-charts/SKILL.md +24 -0
  250. package/skills/slide-outline/SKILL.md +23 -0
  251. package/skills/snapshot-update/SKILL.md +23 -0
  252. package/skills/solidity-contract/SKILL.md +25 -0
  253. package/skills/speaker-notes/SKILL.md +23 -0
  254. package/skills/spike/SKILL.md +23 -0
  255. package/skills/split-file/SKILL.md +23 -0
  256. package/skills/spring-controller/SKILL.md +23 -0
  257. package/skills/sprite-anim/SKILL.md +23 -0
  258. package/skills/sql-report/SKILL.md +23 -0
  259. package/skills/squash/SKILL.md +24 -0
  260. package/skills/ssl-setup/SKILL.md +23 -0
  261. package/skills/stacktrace/SKILL.md +23 -0
  262. package/skills/static-site/SKILL.md +24 -0
  263. package/skills/structured-logging/SKILL.md +23 -0
  264. package/skills/svelte-store/SKILL.md +23 -0
  265. package/skills/swiftui-view/SKILL.md +23 -0
  266. package/skills/tailwind-theme/SKILL.md +24 -0
  267. package/skills/tcp-server/SKILL.md +23 -0
  268. package/skills/tdd/SKILL.md +23 -0
  269. package/skills/terraform-module/SKILL.md +24 -0
  270. package/skills/test-coverage/SKILL.md +23 -0
  271. package/skills/texture-debug/SKILL.md +23 -0
  272. package/skills/threat-model/SKILL.md +23 -0
  273. package/skills/thumbnail/SKILL.md +24 -0
  274. package/skills/todo-scan/SKILL.md +23 -0
  275. package/skills/tool-definition/SKILL.md +23 -0
  276. package/skills/trace-flow/SKILL.md +23 -0
  277. package/skills/tracing/SKILL.md +23 -0
  278. package/skills/train-model/SKILL.md +24 -0
  279. package/skills/tree-shake/SKILL.md +23 -0
  280. package/skills/ts-generics/SKILL.md +23 -0
  281. package/skills/ts-strict/SKILL.md +23 -0
  282. package/skills/tui-app/SKILL.md +23 -0
  283. package/skills/tutorial/SKILL.md +24 -0
  284. package/skills/type-tighten/SKILL.md +23 -0
  285. package/skills/typography/SKILL.md +24 -0
  286. package/skills/ui-bug-repro/SKILL.md +23 -0
  287. package/skills/ui-polish/SKILL.md +24 -0
  288. package/skills/ui-review/SKILL.md +24 -0
  289. package/skills/vendor/SKILL.md +23 -0
  290. package/skills/visual-diff-ci/SKILL.md +24 -0
  291. package/skills/visual-regression/SKILL.md +23 -0
  292. package/skills/vue-composition/SKILL.md +23 -0
  293. package/skills/web-component/SKILL.md +23 -0
  294. package/skills/web-fonts/SKILL.md +24 -0
  295. package/skills/web3-frontend/SKILL.md +25 -0
  296. package/skills/webgl-debug/SKILL.md +23 -0
  297. package/skills/webhook/SKILL.md +23 -0
  298. package/skills/websocket/SKILL.md +23 -0
  299. package/skills/write-tests/SKILL.md +19 -0
  300. package/src/client/agent.ts +803 -0
  301. package/src/client/background.ts +39 -0
  302. package/src/client/checkpoint.ts +48 -0
  303. package/src/client/cli.ts +1253 -0
  304. package/src/client/compaction.ts +86 -0
  305. package/src/client/extensions.ts +83 -0
  306. package/src/client/hooks.ts +40 -0
  307. package/src/client/image.ts +26 -0
  308. package/src/client/lsp.ts +0 -0
  309. package/src/client/mcp.ts +276 -0
  310. package/src/client/models-dev.ts +52 -0
  311. package/src/client/pkg.ts +41 -0
  312. package/src/client/platform.ts +94 -0
  313. package/src/client/prompts.ts +47 -0
  314. package/src/client/render.ts +138 -0
  315. package/src/client/session.ts +107 -0
  316. package/src/client/settings.ts +86 -0
  317. package/src/client/skill-router.ts +79 -0
  318. package/src/client/skills.ts +199 -0
  319. package/src/client/snapshot.ts +56 -0
  320. package/src/client/telemetry.ts +24 -0
  321. package/src/client/todos.ts +23 -0
  322. package/src/client/tools.ts +756 -0
  323. package/src/client/tui-mode.ts +41 -0
  324. package/src/client/tui.ts +224 -0
  325. package/src/sdk/index.ts +36 -0
  326. package/src/selfcheck.ts +364 -0
  327. package/src/server/config.ts +58 -0
  328. package/src/server/credentials.ts +89 -0
  329. package/src/server/identity.ts +58 -0
  330. package/src/server/index.ts +113 -0
  331. package/src/server/oauth.ts +93 -0
  332. package/src/server/providers/adapter.ts +25 -0
  333. package/src/server/providers/anthropic.ts +189 -0
  334. package/src/server/providers/openai-compat.ts +76 -0
  335. package/src/server/providers/registry.ts +31 -0
  336. package/src/server/router.ts +29 -0
  337. package/src/server/sse.ts +20 -0
  338. package/src/shared/types.ts +20 -0
  339. package/tsconfig.json +15 -0
package/skills/meta-tags/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: meta-tags
3
+ description: Add SEO, OpenGraph, and Twitter Card meta tags plus canonical and structured data for rich link previews.
4
+ category: html
5
+ ---
6
+
7
+ # Meta Tags
8
+
9
+ Use when a page needs to rank and to unfurl well when shared on social/chat. Covers the core `<head>` tags search engines and link-preview crawlers read.
10
+
11
+ 1. Set the basics: unique `<title>` (~50-60 chars), `<meta name="description">` (~150-160 chars), `<meta charset="utf-8">`, and `<meta name="viewport">`.
12
+ 2. Add `<link rel="canonical" href="https://...">` (absolute URL) to prevent duplicate-content splits across query strings and trailing slashes.
13
+ 3. Add OpenGraph: `og:title`, `og:description`, `og:type`, `og:url`, `og:image` (absolute URL, 1200x630), and `og:site_name`.
14
+ 4. Add Twitter Card: `twitter:card` = `summary_large_image`, `twitter:title`, `twitter:description`, `twitter:image`.
15
+ 5. Add JSON-LD structured data (`<script type="application/ld+json">`) for the page type (Article, Product, Organization, BreadcrumbList) to enable rich results.
16
+ 6. Set `<meta name="robots">` intentionally (`index,follow` or `noindex`) and verify with a link-preview debugger (Facebook Sharing Debugger, Twitter Card Validator) and Google Rich Results test.
17
+
18
+ ## Rules
19
+ - Every URL in meta tags (canonical, og:image, og:url) must be absolute with scheme; relative URLs break crawlers.
20
+ - `og:image` must be a real, publicly reachable file at 1200x630 (~under 5MB); social crawlers don't run JS.
21
+ - One canonical per page; don't point canonical at a redirect or a noindexed URL.
22
+ - Keep title/description unique per page — don't template the same description sitewide.
23
+ - Validate JSON-LD; a syntax error silently disables the rich result.
package/skills/micro-interactions/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: micro-interactions
3
+ description: Add tasteful hover/press/focus micro-interactions and feedback that feel responsive without distracting.
4
+ category: ui-design
5
+ ---
6
+
7
+ # Micro-Interactions
8
+
9
+ Reach for this when a UI feels static or unresponsive — buttons, toggles, cards, and inputs should acknowledge every interaction within ~100ms.
10
+
11
+ 1. Map the three states for each interactive element: rest, hover, active/press, plus a `:focus-visible` ring for keyboard users — never style all four identically.
12
+ 2. Set durations by intent: 80–120ms for press/feedback, 150–200ms for hover, and pair with `transition-timing-function: cubic-bezier(0.2, 0, 0, 1)` (ease-out) so motion settles fast.
13
+ 3. On press, apply a subtle `transform: scale(0.97)` or 1px translate — physical, not bouncy. Reserve a gentle overshoot spring only for playful toggles/likes.
14
+ 4. Telegraph intent with secondary cues: shift `background`, lift with `box-shadow`, or nudge an icon — change 2 properties max so it reads as one motion.
15
+ 5. Confirm async actions inline: swap label → spinner → checkmark, then settle. Use optimistic UI where the success rate is high.
16
+ 6. Respect `@media (prefers-reduced-motion: reduce)` — drop transforms, keep instant color/opacity feedback so the cue survives.
17
+
18
+ ## Rules
19
+ - Hover effects are progressive enhancement; the element must be fully usable and legible without them (touch + keyboard).
20
+ - Animate `transform` and `opacity` only on the hot path — never `width`, `top`, or `box-shadow` in tight loops (they trigger layout/paint).
21
+ - Keep focus rings visible and ≥3:1 contrast against the adjacent surface; never `outline: none` without a replacement.
22
+ - One signature interaction per surface — if everything wiggles, nothing reads as special.
23
+ - Feedback latency budget is 100ms; beyond that, show a loading state instead of a delayed jump.
package/skills/migration/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: migration
3
+ description: Write a forward/backward database migration that applies and rolls back cleanly
4
+ category: database
5
+ ---
6
+
7
+ # Migration
8
+
9
+ Reach for this when you need to change a database schema (add/alter/drop columns, tables, indexes, constraints) in a way that is versioned, reviewable, and reversible.
10
+
11
+ 1. Inspect the current schema and existing migrations to match naming, ordering, and the tool in use (e.g. Alembic, Prisma, Knex, Rails, raw SQL).
12
+ 2. Write the `up` step: the smallest set of DDL/DML that achieves the change; split risky data backfills into their own step.
13
+ 3. Write the `down` step that exactly reverses `up` (drop what you created, restore what you altered); never leave it as a no-op if `up` is reversible.
14
+ 4. For non-trivial column changes, use the expand/contract pattern: add new, backfill, switch reads/writes, then drop old in a later migration.
15
+ 5. Apply the migration on a scratch/dev database, then roll it back, then re-apply to prove both directions work.
16
+ 6. Wrap each migration in a transaction where the engine allows it; flag operations that can't run transactionally (e.g. Postgres `CREATE INDEX CONCURRENTLY`).
17
+
18
+ ## Rules
19
+ - One logical change per migration; never edit a migration that has already shipped — add a new one.
20
+ - Make column adds nullable or defaulted so they don't lock/fail on populated tables.
21
+ - Backfill large tables in batches, not a single `UPDATE`, to avoid long locks.
22
+ - Test `down` for real; an irreversible migration must say so explicitly and explain the recovery path.
23
+ - Keep migrations free of app code/ORM model imports so they still run after the models change.
package/skills/migration-guide/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: migration-guide
3
+ description: Write an upgrade/migration guide between versions with breaking changes, before/after diffs, and a checklist.
4
+ category: docs
5
+ ---
6
+
7
+ # Migration Guide
8
+
9
+ Use when a release breaks compatibility and users need a clear path from version X to Y — the difference between a smooth upgrade and a flood of issues.
10
+
11
+ 1. Open with scope: which versions this covers (`v2 → v3`), who is affected, and rough effort/risk.
12
+ 2. List breaking changes as a scannable table: what changed, why, and what to do — ordered by how likely each is to bite.
13
+ 3. For each change, show a concrete before/after diff (old API call → new API call), not just prose.
14
+ 4. Provide a step-by-step migration checklist the reader can follow top to bottom, including how to run things in compat mode if available.
15
+ 5. Document automated help: codemods, `--fix` flags, or scripts that do the mechanical edits.
16
+ 6. Note deprecations (still works, will be removed in Z) separately from hard breaks.
17
+ 7. Add a rollback path and a "verify the upgrade" step so users can confirm success.
18
+
19
+ ## Rules
20
+ - Lead with breaking changes; nice-to-have features go at the bottom or in the changelog.
21
+ - Every break needs a before/after code example — telling someone "the API changed" isn't a migration guide.
22
+ - Separate "must change now" (breaks) from "should change soon" (deprecations).
23
+ - Ship a codemod/script for mechanical changes when feasible; don't make humans do find-replace at scale.
24
+ - Test the guide by actually upgrading a sample project against it before publishing.
package/skills/mkdocs-setup/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: mkdocs-setup
3
+ description: Stand up a docs site (MkDocs or Docusaurus) with navigation, search, and a working local preview.
4
+ category: docs
5
+ ---
6
+
7
+ # MkDocs Setup
8
+
9
+ Reach for this when a project needs a real documentation site, not just a README — versioned pages, a nav tree, and full-text search.
10
+
11
+ 1. Pick the stack: MkDocs + Material for Python/simple sites; Docusaurus for React/versioned/i18n-heavy docs. Default to MkDocs Material.
12
+ 2. Scaffold: `pip install mkdocs-material` then `mkdocs new .` (or `npx create-docusaurus@latest docs classic`).
13
+ 3. Create `docs/index.md` plus a page per top-level topic; keep one `<h1>` per file and use relative links between pages.
14
+ 4. Define the nav explicitly in `mkdocs.yml` (`nav:`) so order is deterministic; don't rely on filesystem ordering.
15
+ 5. Enable search and theme features in config (`theme: name: material`, `plugins: [search]`, `features: [navigation.sections, search.suggest]`).
16
+ 6. Preview with `mkdocs serve` (or `npm start`) and watch for broken-link / missing-nav warnings in the console.
17
+ 7. Build static output with `mkdocs build --strict` and deploy via CI (GitHub Pages: `mkdocs gh-deploy`).
18
+
19
+ ## Rules
20
+ - `--strict` in CI so broken links and orphaned pages fail the build instead of shipping.
21
+ - Keep `docs/` flat-ish; deep folder nesting makes relative links fragile and nav noisy.
22
+ - Pin the docs toolchain version (requirements.txt / package.json) so builds are reproducible.
23
+ - Don't hand-edit generated `site/`; it's output — commit only sources.
24
+ - Add a `site_url` so search, canonical links, and sitemap generation work correctly.
package/skills/mobile-permissions/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: mobile-permissions
3
+ description: Request and handle runtime permissions correctly across iOS and Android
4
+ category: mobile
5
+ ---
6
+
7
+ # Mobile Permissions
8
+
9
+ Use this when a feature needs a sensitive capability (camera, location, mic, notifications, photos) and you must request, check, and gracefully handle the runtime permission.
10
+
11
+ 1. Declare the permission up front: add it to `AndroidManifest.xml` and the matching `NSUsageDescription` (purpose string) keys in iOS `Info.plist` — both are required or the OS denies/rejects.
12
+ 2. Check current status before requesting; if already granted, proceed without prompting again.
13
+ 3. Request just-in-time, tied to the user action that needs it, and show a brief rationale first when the platform reports the user previously denied.
14
+ 4. Handle every branch: granted, denied, and permanently-denied/"don't ask again" — for the last case route the user to system Settings.
15
+ 5. Re-check status on screen resume (the user may have toggled it in Settings) and update the UI accordingly.
16
+ 6. Gate the actual capability call behind a confirmed grant, and provide a degraded but functional fallback when denied.
17
+
18
+ ## Rules
19
+ - Never request a permission at app launch with no context — request at the moment of use.
20
+ - A missing iOS usage-description string causes an immediate crash on request; always add the purpose key.
21
+ - Android 13+ needs runtime `POST_NOTIFICATIONS`; older targets don't — branch on API level.
22
+ - Treat permanent denial as terminal in-app: you cannot re-prompt, only deep-link to Settings.
23
+ - Request the narrowest scope that works (e.g. "while in use" location, not "always"); over-asking gets review rejections.
package/skills/mock-api/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: mock-api
3
+ description: Stub or mock external services in tests so they run fast, offline, and deterministically
4
+ category: testing
5
+ ---
6
+
7
+ # Mock API
8
+
9
+ Use when a test depends on an external service (HTTP API, third-party SDK) and you need it isolated and deterministic.
10
+
11
+ 1. Identify the boundary to mock — the HTTP call or client method — and intercept at that seam, not deep inside your logic.
12
+ 2. Choose the level: network-level interception (e.g. nock/MSW) for HTTP, or dependency injection/stubbing for client objects.
13
+ 3. Define realistic responses for the cases under test: success payload, the error/4xx/5xx paths, and timeouts.
14
+ 4. Wire the mock in setup and assert the request was made as expected (URL, method, body, headers) where it matters.
15
+ 5. Reset or restore mocks between tests so stubs don't leak across cases.
16
+ 6. Keep one real integration/contract test (or recorded fixture check) so the mock can't silently drift from the real API.
17
+
18
+ ## Rules
19
+ - Mock at the network or client boundary, never by monkey-patching your own business logic.
20
+ - Base mock payloads on the real API's actual shape; an invented response that the real service never returns tests nothing.
21
+ - Always cover failure modes — non-2xx, malformed body, timeout — not just the happy response.
22
+ - Restore/reset all mocks in teardown so global state doesn't bleed between tests.
23
+ - Guard against drift with a contract or recorded-fixture test against the real service, run less often if needed.
package/skills/modernize/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: modernize
3
+ description: Update code to current language idioms, APIs, and syntax without changing behavior
4
+ category: refactoring
5
+ ---
6
+
7
+ # Modernize
8
+
9
+ Use when code relies on dated patterns, deprecated APIs, or verbose syntax that a newer language/runtime version expresses better. Improve readability and remove deprecation warnings.
10
+
11
+ 1. Check the project's actual language/runtime version and lint/compiler target — don't use syntax it can't run.
12
+ 2. Inventory the dated patterns (callbacks→async/await, var→const/let, manual loops→map/filter, format strings, optional chaining).
13
+ 3. Replace deprecated APIs with their supported equivalents, checking semantics (some replacements differ on edge cases).
14
+ 4. Apply changes incrementally by pattern; lean on codemods or autofixers where they exist.
15
+ 5. Run the linter and full test suite after each pattern batch.
16
+ 6. Update any related config (compiler target, polyfills, engine field) so the modernized code is actually supported.
17
+
18
+ ## Rules
19
+ - Match the project's existing style and version; modernizing past what CI supports breaks the build.
20
+ - Some "equivalents" aren't exact (e.g. `Promise.all` vs sequential awaits, `==` vs `===`) — verify behavior, not just shape.
21
+ - Don't bundle dependency upgrades into the same change unless required; keep concerns separate.
22
+ - Prefer mechanical, reviewable batches over a single sweeping rewrite.
23
+ - Leave intentionally-old patterns alone if a comment or constraint explains them.
package/skills/monorepo-setup/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: monorepo-setup
3
+ description: Set up a workspace monorepo (pnpm/turbo/nx) with shared deps and a working task graph
4
+ category: dependencies
5
+ ---
6
+
7
+ # Monorepo Setup
8
+
9
+ Use when consolidating multiple packages into one repo with shared tooling and a single dependency graph.
10
+
11
+ 1. Pick the workspace manager (pnpm workspaces, npm/yarn workspaces) and declare package globs (`pnpm-workspace.yaml` or `"workspaces"`).
12
+ 2. Lay out `packages/*` and `apps/*`, give each a package.json with a scoped name, and reference siblings via `workspace:*`.
13
+ 3. Hoist shared config (tsconfig base, eslint, prettier) to the root and extend it per package.
14
+ 4. Add a task runner (Turborepo or Nx) and define the build/test/lint pipeline with correct `dependsOn` ordering and caching.
15
+ 5. Wire a single root lockfile and install once at the root so cross-package versions stay consistent.
16
+ 6. Verify with a clean install plus a from-scratch `build`/`test` across the graph, then enable remote/CI caching.
17
+
18
+ ## Rules
19
+ - One lockfile at the repo root — never per-package lockfiles in a workspace.
20
+ - Reference internal packages with `workspace:` protocol, not a published version, so local changes resolve.
21
+ - Declare task `dependsOn` so the runner builds dependencies before dependents.
22
+ - Keep each package's dependencies in its own package.json; don't dump everything in the root.
23
+ - Make the cache key include inputs (source + config) so stale cache hits don't ship wrong output.
package/skills/motion-design/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: motion-design
3
+ description: Define a coherent motion system — duration tokens, easing curves, and clear rules for when to animate.
4
+ category: ui-design
5
+ ---
6
+
7
+ # Motion Design
8
+
9
+ Reach for this before adding any animation to a product, so motion is a designed system with tokens rather than one-off magic numbers scattered across components.
10
+
11
+ 1. Define a duration scale as CSS custom properties: `--dur-1: 100ms` (micro), `--dur-2: 200ms` (UI), `--dur-3: 320ms` (entrances), `--dur-4: 500ms` (large/page). Scale duration with travel distance and element size.
12
+ 2. Define an easing token set: `--ease-out: cubic-bezier(0.2, 0, 0, 1)` for enters, `--ease-in: cubic-bezier(0.4, 0, 1, 1)` for exits, `--ease-spring` for emphasis. Default to ease-out — elements decelerate into place.
13
+ 3. Assign each animation a role: arrival (fade+rise), exit (fade+fall), state change, or attention. Different roles get different curves/durations — don't reuse one transition everywhere.
14
+ 4. Orchestrate groups with a stagger of 30–60ms per item so lists cascade; cap total sequence length near 500ms so it never feels slow.
15
+ 5. Prefer transform-driven motion (translate/scale) and physics-based springs (Framer Motion `type: "spring"`, sensible stiffness/damping) over linear tweens for anything interactive.
16
+ 6. Provide a global `prefers-reduced-motion` fallback that collapses movement to opacity-only, and document the tokens so the team reuses them.
17
+
18
+ ## Rules
19
+ - Motion must communicate (where did this come from, what changed), never decorate for its own sake.
20
+ - Never use `ease-in-out` for entrances — it starts slow and feels sluggish; reserve it for looping/ambient motion.
21
+ - Exits are faster than entrances (~0.7×); users have already decided, so get out of the way.
22
+ - No transition longer than ~500ms on an interaction the user is waiting on.
23
+ - One token set, imported everywhere — a stray `transition: all 0.3s` is a bug, not a shortcut.
package/skills/n-plus-one/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: n-plus-one
3
+ description: Find and fix N+1 query problems by eager-loading or batching the per-row queries
4
+ category: performance
5
+ ---
6
+
7
+ # N Plus One
8
+
9
+ Reach for this when an endpoint fires one query per row of a result set — the classic N+1 that scales linearly with data.
10
+
11
+ 1. Spot the pattern: a query returns N rows, then a loop (or lazy relation access) issues one more query per row to fetch related data.
12
+ 2. Confirm it in query logs or APM — look for the same statement repeated N times with only the id parameter changing.
13
+ 3. Replace per-row loads with a single batched fetch: ORM eager loading (`includes`/`joinedload`/`prefetch_related`/`with`) or one `WHERE id IN (...)`.
14
+ 4. For nested relations, eager-load the whole chain so child loops don't reintroduce N+1 at the next level.
15
+ 5. Re-run and verify the query count collapses from N+1 to a small constant (1-3).
16
+ 6. Add a test or dev-time assertion that fails on excessive query counts to prevent regressions.
17
+
18
+ ## Rules
19
+ - Diagnose by query count, not wall time — N+1 hides on small datasets and explodes in production.
20
+ - Prefer the ORM's eager-load over hand-rolled loops; reach for `IN (...)` batching when the ORM can't.
21
+ - Watch serializers and view templates — lazily accessing a relation inside a render loop is a common hidden source.
22
+ - Don't fix N+1 by pulling the whole table into memory; batch by the ids you actually need.
23
+ - Cap or paginate the `IN (...)` list so a huge result set doesn't create one giant query.
package/skills/naming-review/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: naming-review
3
+ description: Flag unclear names in the diff and suggest sharper replacements
4
+ category: review
5
+ ---
6
+
7
+ # Naming Review
8
+
9
+ Reach for this when reviewing a change where names carry the meaning — new functions, variables, types, flags, or files — and you want them to read clearly at the call site.
10
+
11
+ 1. Run `git diff` and collect every newly introduced or renamed identifier (functions, variables, types, params, files, config keys).
12
+ 2. For each, ask whether the name says what it is or does without needing the implementation — flag vague ones (`data`, `tmp`, `handle`, `doStuff`, `flag2`).
13
+ 3. Check booleans read as predicates (`isReady`, `hasItems`), and that functions are verbs while values are nouns.
14
+ 4. Watch for misleading names (a `list` that's a map), inconsistent vocabulary for the same concept, and unexplained abbreviations.
15
+ 5. Propose a concrete better name for each flagged identifier and note where it's used so the rename is mechanical.
16
+ 6. Apply low-risk renames in the working tree; leave wide-blast-radius ones as suggestions for the author to confirm.
17
+
18
+ ## Rules
19
+ - Judge a name by how it reads at the call site, not at the definition.
20
+ - Match the codebase's existing conventions — don't introduce a competing vocabulary for the same idea.
21
+ - Prefer clear and slightly longer over clever and cryptic; avoid single letters outside tight loops.
22
+ - Don't bikeshed already-fine names; only flag ones that genuinely cost a reader time.
23
+ - Flag misleading names as higher priority than merely-vague ones — wrong is worse than fuzzy.
package/skills/nextjs-route/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: nextjs-route
3
+ description: Add a Next.js App Router page or route handler with the right runtime
4
+ category: frameworks
5
+ ---
6
+
7
+ # Next.js Route
8
+
9
+ Use to add a new page or API endpoint under the Next.js App Router (`app/`), choosing server vs client and the correct file convention.
10
+
11
+ 1. Pick the segment path under `app/` (e.g. `app/dashboard/`); use `[param]` for dynamic and `(group)` for layout grouping without a URL segment.
12
+ 2. For UI, add `page.tsx` (a Server Component by default); add `loading.tsx`, `error.tsx`, or `layout.tsx` siblings as needed.
13
+ 3. For an API endpoint, add `route.ts` and export async functions named after HTTP verbs (`GET`, `POST`, …) taking `(req: Request, { params })`.
14
+ 4. Fetch data directly in async Server Components or in the handler; return `Response`/`NextResponse.json()` from route handlers.
15
+ 5. Add `'use client'` at the top only for components needing state, effects, or browser APIs; keep data-fetching on the server.
16
+ 6. Run `next dev`, hit the route, and confirm the rendered/JSON output and status codes.
17
+
18
+ ## Rules
19
+ - A folder can't have both `page.tsx` and `route.ts` at the same segment — pick one.
20
+ - Server Components can't use hooks, event handlers, or `window`; push those into a `'use client'` child.
21
+ - Set `export const dynamic`/`revalidate` deliberately when you need caching or always-fresh data.
22
+ - Read dynamic params from the function args, not from `useParams`, inside Server Components and handlers.
23
+ - Don't leak secrets to the client — env vars without `NEXT_PUBLIC_` stay server-only; keep them out of client components.
package/skills/nginx-config/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: nginx-config
3
+ description: Write or optimize an nginx config for a reverse proxy or static site
4
+ category: cloud
5
+ ---
6
+
7
+ # Nginx Config
8
+
9
+ Reach for this when configuring nginx as a reverse proxy, static file server, or TLS terminator — and when tightening an existing config for performance or security.
10
+
11
+ 1. Define one `server` block per virtual host with `server_name` and the correct `listen` (80 and 443).
12
+ 2. For proxying, set `proxy_pass` plus the standard forwarded headers (`Host`, `X-Real-IP`, `X-Forwarded-For`, `X-Forwarded-Proto`).
13
+ 3. For TLS, point `ssl_certificate`/`ssl_certificate_key` at the certs and redirect `:80` to `:443`.
14
+ 4. Enable `gzip` (or brotli) and set cache headers / `expires` for static assets.
15
+ 5. Add security headers (`Strict-Transport-Security`, `X-Content-Type-Options`, `X-Frame-Options`) and hide `server_tokens off`.
16
+ 6. Test with `nginx -t`, then reload with `nginx -s reload` — never a hard restart for a config change.
17
+
18
+ ## Rules
19
+ - Always `nginx -t` before reloading; a syntax error on restart takes the site down.
20
+ - Set `client_max_body_size` to match real upload needs — the 1MB default silently rejects larger requests.
21
+ - Tune `proxy_read_timeout`/`proxy_connect_timeout` for slow upstreams instead of leaving defaults.
22
+ - Don't terminate TLS with weak protocols; set `ssl_protocols TLSv1.2 TLSv1.3` and a modern cipher list.
23
+ - Use `upstream` blocks with health-aware load balancing rather than hardcoding a single backend when you have several.
package/skills/ocr-debug/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: ocr-debug
3
+ description: Improve OCR accuracy — binarize, deskew, raise DPI, set language, fix contrast and noise
4
+ category: image
5
+ ---
6
+
7
+ # OCR Debug
8
+
9
+ Reach for this when OCR output is garbled, missing text, or has frequent character errors, and you need to improve the input image rather than the engine.
10
+
11
+ 1. Reproduce on the specific failing image and save the EXACT bitmap handed to the OCR engine (post-preprocessing) — OCR errors are usually caused by the preprocessed image, not the original.
12
+ 2. Check effective resolution: OCR engines want ~300 DPI for body text. Upscale small/low-DPI scans before recognition; tiny text is the most common cause of garbage output.
13
+ 3. Deskew and de-rotate: even a few degrees of skew wrecks line segmentation. Detect skew angle and rotate to horizontal; fix upside-down pages (orientation detection) too.
14
+ 4. Improve contrast and binarize thoughtfully: convert to grayscale, then adaptive/Otsu threshold to clean black-on-white. Over-aggressive global thresholding erases faint strokes — compare adaptive vs Otsu on the sample.
15
+ 5. Remove noise and background: despeckle, drop background gradients/watermarks, and crop to the text region so the engine isn't distracted by borders, photos, or table rules.
16
+ 6. Set the right language and character set: wrong language model, or not restricting to a digit/uppercase whitelist when appropriate, causes systematic substitutions (O/0, l/1).
17
+ 7. Measure: compare recognized text to ground truth (character error rate) before and after each change so you keep only steps that help.
18
+
19
+ ## Rules
20
+ - Inspect the post-preprocessing bitmap the engine actually sees; that's where the accuracy is decided.
21
+ - Aim for ~300 DPI of text height; upscaling beats feeding tiny glyphs.
22
+ - Deskew and fix orientation before binarizing — skewed lines defeat segmentation.
23
+ - Over-binarizing erases thin strokes; tune threshold on the real sample, prefer adaptive for uneven lighting.
24
+ - Always set the correct language; constrain the charset when the domain allows (digits-only, etc.).
package/skills/onboard/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: onboard
3
+ description: Generate a dev-setup and onboarding guide for the repo from its actual config and entry points
4
+ category: meta
5
+ ---
6
+
7
+ # Onboard
8
+
9
+ Reach for this when a repo lacks a clear "get started" path and a new contributor would have to reverse-engineer setup. Produces a concrete, verified onboarding guide grounded in the repo's real files.
10
+
11
+ 1. Detect the stack: read manifests and lockfiles (`package.json`, `pyproject.toml`/`requirements.txt`, `go.mod`, `Cargo.toml`, `Gemfile`) plus version pins (`.nvmrc`, `.tool-versions`, `.python-version`) and container files (`Dockerfile`, `compose.yaml`).
12
+ 2. Extract the real commands from scripts/targets (npm `scripts`, `Makefile`, `Justfile`, `Taskfile`) rather than inventing them — note install, build, run, test, lint.
13
+ 3. Find required config: scan for `.env.example`, secret/config templates, and CI workflows (`.github/workflows`) to learn what env vars and services (DB, cache, queues) the app expects.
14
+ 4. Map entry points: identify how to start the app and where the codebase begins (main/server file, top-level packages) and how to run a single test.
15
+ 5. Verify the happy path by running install + build + test (or a fast subset); record any step that fails and the fix.
16
+ 6. Write `ONBOARDING.md` (or `CONTRIBUTING.md`) with prerequisites, exact copy-paste setup steps, run/test commands, env vars table, and a "first PR" pointer.
17
+
18
+ ## Rules
19
+ - Only document commands that exist in the repo or that you actually ran — never guess invocations.
20
+ - Pin tool versions you observed; flag when none is specified instead of assuming "latest".
21
+ - List env vars as a table (name, required?, example/default) sourced from `.env.example` and code, never real secret values.
22
+ - Keep steps copy-pasteable and OS-aware; call out platform-specific commands (bash vs PowerShell) when they differ.
23
+ - If a setup step fails, fix or clearly mark it as broken — do not ship an untested guide.
package/skills/onboarding-map/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: onboarding-map
3
+ description: Map a repo's structure for a newcomer — layout, entry points, key modules, and how to build and run it
4
+ category: code-understanding
5
+ ---
6
+
7
+ # Onboarding Map
8
+
9
+ Use when someone is new to a repo and needs a mental model: where things live, what matters, and how to run it.
10
+
11
+ 1. Read the top-level signals first: README, CONTRIBUTING, package/build manifests, and any docs or ARCHITECTURE files.
12
+ 2. Map the directory layout — name each top-level folder's role (source, tests, config, scripts, infra) in a line each.
13
+ 3. Identify entry points: main/index files, server bootstrap, CLI commands, or the app's `start` script.
14
+ 4. Pick out the core modules that carry the domain logic, distinguishing them from glue, vendored code, and generated output.
15
+ 5. Extract the workflow from the manifest/scripts: how to install, build, test, run, and lint.
16
+ 6. Summarize as a short orientation — "start here, then read these" — pointing to a handful of files worth reading first.
17
+
18
+ ## Rules
19
+ - Lead with the few files that explain the most; do not enumerate every directory.
20
+ - Prefer documented commands (package scripts, Makefile, CI config) over inferred ones.
21
+ - Flag generated, vendored, or build-output directories so the newcomer does not read them as source.
22
+ - Note the primary language(s), framework, and any monorepo/workspace boundaries up front.
23
+ - Keep it a map, not a tutorial — point to where to learn, do not re-teach the framework.
package/skills/open-pr/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: open-pr
3
+ description: Push the current branch and open a GitHub PR with a structured title and body.
4
+ category: git
5
+ ---
6
+
7
+ # Open a PR
8
+
9
+ Requires `gh` authenticated (`gh auth status`) and a GitHub remote.
10
+
11
+ 1. **Sanity-check.** `git status` should be clean — commit first if not. Confirm you're on a feature branch, not the repo's default branch. If on the default branch, create one: `git checkout -b <type>/<short-desc>`.
12
+ 2. **Push.** `git push -u origin HEAD`.
13
+ 3. **Summarize the change.** `git diff <base>...HEAD --stat` and the commit log since the base branch.
14
+ 4. **Open the PR.** `gh pr create` with:
15
+ - **Title** — a clear one-line summary (Conventional-Commits style is fine).
16
+ - **Body** — three sections: **Summary** (what & why), **Changes** (bullets), **Test plan** (how it was verified).
17
+ 5. **Return the PR URL** from `gh`.
18
+
19
+ ## Rules
20
+
21
+ - Never merge as part of this — opening the PR is the end state.
22
+ - Confirm the base branch if there's any doubt; don't target the wrong one.
23
+ - Don't force-push over a shared branch.
24
+ - Keep the body honest: if something wasn't tested, say so in the test plan.
package/skills/openapi/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: openapi
3
+ description: Write or update an OpenAPI spec so it matches the actual API behavior
4
+ category: api
5
+ ---
6
+
7
+ # Openapi
8
+
9
+ Reach for this when documenting an API in OpenAPI/Swagger, or keeping an existing spec in sync after an endpoint changes.
10
+
11
+ 1. Locate the existing spec (`openapi.yaml`/`.json`) and confirm the version (3.0 vs 3.1) before editing — syntax differs.
12
+ 2. Define or update the `paths` entry: method, parameters, `requestBody`, and every response status the handler can return.
13
+ 3. Factor request/response shapes into `components/schemas` and reference with `$ref` instead of inlining duplicates.
14
+ 4. Document auth via `securitySchemes` and apply `security` at the operation or root level to match real enforcement.
15
+ 5. Add realistic `examples` and mark required fields and formats (`date-time`, `uuid`, `email`) so consumers and mocks behave.
16
+ 6. Validate the spec with a linter (e.g. `spectral lint`/`swagger-cli validate`) and, if codegen is used, regenerate clients/types.
17
+
18
+ ## Rules
19
+ - The spec must describe what the code does, not what you wish it did — verify against the handler.
20
+ - Document error responses (4xx/5xx), not just the 200 — consumers need the failure shapes.
21
+ - Reuse `$ref` schemas; duplicated inline objects drift apart over time.
22
+ - Match the OpenAPI version already in the file; 3.1 uses JSON Schema `type` arrays for nullable, 3.0 uses `nullable: true`.
23
+ - Lint before committing; an invalid spec breaks downstream codegen and mock servers.
package/skills/opencv-debug/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: opencv-debug
3
+ description: Debug OpenCV pipelines — dtype mismatch, BGR channel order, ROI/bounds errors, in-place op surprises
4
+ category: image
5
+ ---
6
+
7
+ # OpenCV Debug
8
+
9
+ Reach for this when an OpenCV (`cv2`) pipeline throws on a function, returns black/empty arrays, or produces wrong colors or crops.
10
+
11
+ 1. Reproduce and at the failing line print `img.shape`, `img.dtype`, and `img.min()/max()` — most cv2 bugs are a wrong dtype or unexpected channel count, and these three lines reveal it.
12
+ 2. Confirm channel order: `cv2.imread` returns BGR. If you mixed it with PIL/matplotlib/Torch (RGB), colors swap. Convert explicitly with `cv2.cvtColor(img, cv2.COLOR_BGR2RGB)` at the boundary, not ad hoc.
13
+ 3. Check dtype expectations: many ops need `uint8` (0–255) or `float32` (0–1); passing float images where uint8 is expected (or vice versa) gives black output or assertion errors. Cast deliberately, never rely on implicit promotion.
14
+ 4. Audit ROI and slicing: numpy slices are `img[y0:y1, x0:x1]` (row=y first), but most cv2 point/rect APIs take `(x, y)`. Swapping these crops the wrong region or throws on out-of-bounds. Clamp coordinates to `[0, w)` / `[0, h)`.
15
+ 5. Watch in-place / shared-buffer ops: a slice is a VIEW, and functions like `cv2.rectangle` mutate in place. Unexpected modifications to "another" image mean you aliased a buffer — `.copy()` to isolate.
16
+ 6. Validate empty/None returns: `imread` returns `None` for a missing/unreadable path (no exception). Check for `None` before the next op, which otherwise fails cryptically.
17
+ 7. Visualize the intermediate (`cv2.imwrite`) at the suspect stage to confirm geometry and color before continuing.
18
+
19
+ ## Rules
20
+ - numpy indexing is `[row=y, col=x]`; cv2 geometry APIs are `(x, y)` — the swap causes most ROI bugs.
21
+ - `cv2.imread` is BGR and returns `None` (not an error) on failure; handle both explicitly.
22
+ - Know each op's required dtype/range; float vs uint8 mismatches silently yield black images.
23
+ - Slices are views and many cv2 calls mutate in place — `.copy()` when you need an independent buffer.
24
+ - Print `shape`, `dtype`, `min/max` at the failure point before theorizing.
package/skills/orm-model/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: orm-model
3
+ description: Add or modify an ORM model and its relations, keeping schema and code in sync
4
+ category: database
5
+ ---
6
+
7
+ # ORM Model
8
+
9
+ Use when adding a new model/entity or changing fields and relationships in an ORM (e.g. SQLAlchemy, Prisma, Django, ActiveRecord, TypeORM, Sequelize).
10
+
11
+ 1. Read existing models to match the project's conventions: base class, naming, type mappings, and how relations are declared.
12
+ 2. Define fields with explicit types, nullability, defaults, and constraints (unique, length, indexed) that mirror the intended schema.
13
+ 3. Declare relations on both sides where the ORM supports it (e.g. `belongsTo`/`hasMany`), and set the cascade/`on_delete` behavior deliberately.
14
+ 4. Generate or hand-write the migration that the model change implies, then review the generated DDL — don't trust autogen blindly.
15
+ 5. Apply the migration to a dev database and confirm the model loads, relations traverse, and queries work.
16
+ 6. Update serializers, validators, factories/seeds, and any type definitions that reference the changed fields.
17
+
18
+ ## Rules
19
+ - Keep the model and the migration consistent; a model change without a matching migration is a silent drift bug.
20
+ - Set relation loading explicitly (eager vs lazy) and watch for N+1 queries on collections.
21
+ - Define cascade/`on_delete` intentionally rather than accepting the ORM default.
22
+ - Add DB-level constraints (unique, FK), not just app-level validation, for anything that must hold true.
23
+ - Review autogenerated migrations before applying — they can miss renames or produce destructive drops.
package/skills/owasp-check/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: owasp-check
3
+ description: Check a web app against the OWASP Top 10 and report concrete gaps per category
4
+ category: security
5
+ ---
6
+
7
+ # OWASP Check
8
+
9
+ Use this for a structured web-app review walking each OWASP Top 10 category and producing concrete, located findings.
10
+
11
+ 1. A01 Broken Access Control: check object-level authz, IDOR, missing server-side checks, and forced browsing to admin routes.
12
+ 2. A02/A04/A05 Crypto, Insecure Design, Misconfig: verify TLS, password hashing (bcrypt/argon2 not MD5/SHA1), secure headers, disabled debug, no default creds.
13
+ 3. A03 Injection: trace user input to SQL/NoSQL/OS/LDAP/template sinks; confirm parameterization and output encoding.
14
+ 4. A06/A08 Vulnerable Components & Integrity: run dependency audit, check for unsigned/untrusted updates and unsafe deserialization.
15
+ 5. A07 Auth Failures: review session expiry/rotation, brute-force throttling, MFA, and credential-stuffing protections.
16
+ 6. A09/A10 Logging & SSRF: confirm security events are logged (without secrets) and that server-side fetches validate/allowlist destinations.
17
+ 7. Summarize per category as Pass / Gap / N-A with file:line evidence and a fix for each gap.
18
+
19
+ ## Rules
20
+ - Walk all ten categories explicitly so nothing is silently skipped; mark N/A where it genuinely does not apply.
21
+ - Back every "Gap" with a concrete location and, where possible, a repro — avoid generic advice.
22
+ - Lean on existing skills (authz-review, dependency-audit, sanitize) rather than re-deriving them here.
23
+ - Distinguish exploitable findings from hardening recommendations.
24
+ - Reference the current OWASP Top 10 list version you are checking against.
package/skills/page-transitions/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: page-transitions
3
+ description: Add smooth route/page transitions with the View Transitions API or Framer that preserve context.
4
+ category: ui-design
5
+ ---
6
+
7
+ # Page Transitions
8
+
9
+ Reach for this when route changes feel abrupt — a well-crafted transition maintains spatial continuity so users keep their place between views.
10
+
11
+ 1. Pick the mechanism: native View Transitions API (`document.startViewTransition`, or `@view-transition { navigation: auto }` for MPAs) where supported; Framer Motion `AnimatePresence` with `mode="wait"` for React SPAs.
12
+ 2. Default to a fast crossfade (~200–300ms) for unrelated routes; it's invisible-but-smooth and the safest baseline.
13
+ 3. For shared elements (a card → its detail page), give both a matching `view-transition-name` (or Framer `layoutId`) so the element morphs in place — this is the high-value move.
14
+ 4. Tune the generated pseudo-elements: style `::view-transition-old(root)` / `::view-transition-new(root)` with your easing tokens; clip-path or slide for directional hierarchy (forward = in from right, back = out to right).
15
+ 5. Avoid layout shift mid-transition: hold scroll position or restore it explicitly, and ensure the incoming page's above-fold content is ready (Suspense/loaded data) before revealing.
16
+ 6. Always ship a no-transition fallback for unsupported browsers (feature-detect `startViewTransition`) and honor `prefers-reduced-motion` with an instant swap.
17
+
18
+ ## Rules
19
+ - A transition must orient the user, not entertain — if it makes navigation feel slower, shorten or cut it.
20
+ - Keep durations ≤300ms; users navigate constantly and a flashy 600ms transition becomes friction by the tenth click.
21
+ - Shared-element transitions need stable, unique names — duplicated `view-transition-name` on one page throws and breaks the animation.
22
+ - Never animate during the transition something that also triggers data fetching — wait for the new view's critical content first.
23
+ - Test back/forward and rapid navigation; transitions must be interruptible and not queue/stack.
package/skills/pagination/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: pagination
3
+ description: Add pagination to a list endpoint with a stable order and total/next signal
4
+ category: api
5
+ ---
6
+
7
+ # Pagination
8
+
9
+ Reach for this when a list endpoint returns an unbounded collection and needs to page results predictably.
10
+
11
+ 1. Pick a strategy: cursor-based for large/real-time data and infinite scroll, offset/limit for small or page-numbered UIs.
12
+ 2. Define a deterministic sort with a tiebreaker (e.g. `created_at, id`) — pagination over a non-stable order skips or repeats rows.
13
+ 3. Parse and clamp page params (`limit` with a sane max, `cursor` or `offset`); reject invalid values with 400.
14
+ 4. Query for `limit + 1` rows (or a count) so you can tell whether a next page exists without a second round trip.
15
+ 5. Return data plus metadata: `nextCursor`/`hasMore` for cursor, or `total`/`page`/`pageSize` for offset.
16
+ 6. Add tests: first page, a middle page, the last page (no next), and an out-of-range/empty result.
17
+
18
+ ## Rules
19
+ - Always enforce a maximum page size; an unbounded `limit` lets a client pull the whole table.
20
+ - Sort must be stable and total — include a unique tiebreaker or rows drift between pages on inserts/deletes.
21
+ - Cursors should encode the sort key, not a raw offset; opaque (base64) cursors discourage clients depending on internals.
22
+ - Avoid `COUNT(*)` on huge tables for every request if you only need "has more" — fetch `limit + 1` instead.
23
+ - Keep the response envelope consistent with other list endpoints in the codebase.
package/skills/perf-optimize/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: perf-optimize
3
+ description: Optimize a measured hot path — profile first, fix the real bottleneck, prove the speedup
4
+ category: performance
5
+ ---
6
+
7
+ # Perf Optimize
8
+
9
+ Reach for this when something is measurably slow and you need to speed it up without guessing.
10
+
11
+ 1. Reproduce the slow path with a stable, repeatable benchmark or input and record a baseline number (wall time, p95, throughput).
12
+ 2. Profile it (sampling/CPU profiler, `perf`, flamegraph, language profiler) to find where time actually goes — never optimize from intuition.
13
+ 3. Confirm the top one or two hotspots account for most of the cost; ignore the long tail of cheap functions.
14
+ 4. Apply the smallest change that attacks the dominant cost: better algorithm/complexity, fewer allocations, avoid redundant work, or move work out of the loop.
15
+ 5. Re-run the same benchmark and compare against baseline; keep the change only if the win is real and worth the complexity.
16
+ 6. Add a regression guard (benchmark in CI or a perf assertion) so the gain doesn't silently erode.
17
+
18
+ ## Rules
19
+ - Measure before and after with the same inputs and a warm/steady state — one cold run is noise.
20
+ - Optimize the actual bottleneck the profiler shows, not the code that "looks slow".
21
+ - Algorithmic wins (O(n^2) -> O(n log n)) beat micro-optimizations; check complexity before tuning constants.
22
+ - Don't sacrifice correctness or readability for a speedup you can't measure.
23
+ - State the numbers in the result: "X ms -> Y ms (Nx)" so the win is auditable.