@kensaurus/skills 0.0.0-stage → 2.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 (425) hide show
  1. package/.claude-plugin/marketplace.json +53 -0
  2. package/.claude-plugin/plugin.json +40 -0
  3. package/.cursor-plugin/plugin.json +38 -0
  4. package/.mcp.json +28 -0
  5. package/CHANGELOG.md +1790 -0
  6. package/LICENSE +21 -0
  7. package/LICENSE-APACHE +62 -0
  8. package/NOTICE +13 -0
  9. package/README.md +821 -2
  10. package/SECURITY.md +55 -0
  11. package/agents/code-reviewer.md +60 -0
  12. package/agents/completion-judge.md +89 -0
  13. package/agents/db-migrator.md +125 -0
  14. package/agents/debugger.md +47 -0
  15. package/agents/deploy-checker.md +100 -0
  16. package/agents/perf-monitor.md +74 -0
  17. package/assets/favicon.png +0 -0
  18. package/assets/logo-light.png +0 -0
  19. package/assets/logo.png +0 -0
  20. package/assets/logo.svg +6 -0
  21. package/assets/og.png +0 -0
  22. package/bin/install.mjs +1127 -0
  23. package/bin/kenji.js +2 -0
  24. package/commands/adr.md +17 -0
  25. package/commands/aeo-plan.md +18 -0
  26. package/commands/arch-boundaries.md +17 -0
  27. package/commands/aso-plan.md +18 -0
  28. package/commands/auth-flows.md +19 -0
  29. package/commands/backup-plan.md +17 -0
  30. package/commands/burndown-full.md +25 -0
  31. package/commands/capacitor-plan.md +18 -0
  32. package/commands/codemod-safety.md +22 -0
  33. package/commands/commit.md +18 -0
  34. package/commands/complete-everything.md +40 -0
  35. package/commands/cost-plan.md +19 -0
  36. package/commands/deadcode-plan.md +26 -0
  37. package/commands/deadcode.md +32 -0
  38. package/commands/debug-issue.md +17 -0
  39. package/commands/deps-plan.md +18 -0
  40. package/commands/docs-plan.md +17 -0
  41. package/commands/doctrine.md +19 -0
  42. package/commands/error-plan.md +19 -0
  43. package/commands/feedback-to-closure.md +36 -0
  44. package/commands/fix-issue.md +76 -0
  45. package/commands/gate-logic.md +26 -0
  46. package/commands/green-repo.md +36 -0
  47. package/commands/grill-me.md +19 -0
  48. package/commands/gtm-plan.md +21 -0
  49. package/commands/gtm-weekly.md +17 -0
  50. package/commands/gtm.md +22 -0
  51. package/commands/handoff.md +15 -0
  52. package/commands/housekeep-backlog.md +18 -0
  53. package/commands/housekeep-files.md +22 -0
  54. package/commands/housekeep-gates.md +18 -0
  55. package/commands/instant-nav.md +11 -0
  56. package/commands/integrity-plan.md +19 -0
  57. package/commands/launch-kit.md +16 -0
  58. package/commands/mcp-guide.md +40 -0
  59. package/commands/mobile-plan.md +19 -0
  60. package/commands/native-rn-monorepo/README.md +78 -0
  61. package/commands/native-rn-monorepo/android-build.md +26 -0
  62. package/commands/native-rn-monorepo/android-install.md +32 -0
  63. package/commands/native-rn-monorepo/android-logcat.md +37 -0
  64. package/commands/native-rn-monorepo/ios-ci-logs.md +56 -0
  65. package/commands/native-rn-monorepo/ios-ci-status.md +52 -0
  66. package/commands/native-rn-monorepo/ios-ci-trigger.md +59 -0
  67. package/commands/native-rn-monorepo/rn-reset.md +50 -0
  68. package/commands/native-rn-monorepo/rn-ship-ios.md +67 -0
  69. package/commands/native-rn-monorepo/rn-verify.md +53 -0
  70. package/commands/perf-plan.md +18 -0
  71. package/commands/plan-mode.md +74 -0
  72. package/commands/pr.md +16 -0
  73. package/commands/pricing-plan.md +20 -0
  74. package/commands/privacy-plan.md +18 -0
  75. package/commands/readability.md +12 -0
  76. package/commands/readme.md +15 -0
  77. package/commands/refactor.md +15 -0
  78. package/commands/release-prep.md +17 -0
  79. package/commands/research.md +25 -0
  80. package/commands/responsive-audit.md +21 -0
  81. package/commands/review-code.md +18 -0
  82. package/commands/rls-plan.md +18 -0
  83. package/commands/secrets-plan.md +18 -0
  84. package/commands/security-plan.md +19 -0
  85. package/commands/ship-and-observe.md +36 -0
  86. package/commands/skill-conflicts.md +19 -0
  87. package/commands/slop-plan.md +18 -0
  88. package/commands/stub-plan.md +18 -0
  89. package/commands/test-mutation.md +16 -0
  90. package/commands/test-plan.md +17 -0
  91. package/commands/test.md +29 -0
  92. package/commands/thirdparty-web-interface-guidelines.md +185 -0
  93. package/commands/uiux-plan.md +18 -0
  94. package/commands/uiux.md +45 -0
  95. package/commands/update-deps.md +21 -0
  96. package/commands/validation-plan.md +19 -0
  97. package/commands-portable/fix-issue.md +72 -0
  98. package/commands-portable/plan-mode.md +92 -0
  99. package/commands-portable/research.md +91 -0
  100. package/docs/screenshots/README.md +5 -0
  101. package/docs/screenshots/audit-dark.png +0 -0
  102. package/docs/screenshots/build-dark.png +0 -0
  103. package/docs/screenshots/grill-dark.png +0 -0
  104. package/docs/screenshots/hero-dark.png +0 -0
  105. package/docs/screenshots/hero-light.png +0 -0
  106. package/docs/screenshots/ship-dark.png +0 -0
  107. package/docs/screenshots/src/showcase.html +320 -0
  108. package/hooks/completion-gate.mjs +258 -0
  109. package/hooks/cursor-hooks.json +13 -0
  110. package/hooks/hooks.json +15 -0
  111. package/install.sh +21 -0
  112. package/llms.txt +40 -0
  113. package/mcp/README.md +266 -0
  114. package/mcp/VERSIONS.md +41 -0
  115. package/mcp/mcp-full.json.template +124 -0
  116. package/mcp/mcp.json.template +29 -0
  117. package/mcp/pinned-versions.json +27 -0
  118. package/package.json +94 -4
  119. package/rules/approved-plan-execution.mdc +65 -0
  120. package/rules/full-stack-ship-discipline.mdc +37 -0
  121. package/rules/native-rn-monorepo/README.md +63 -0
  122. package/rules/native-rn-monorepo/_project.mdc +69 -0
  123. package/rules/native-rn-monorepo/native-android.mdc +72 -0
  124. package/rules/native-rn-monorepo/native-ios.mdc +61 -0
  125. package/rules/native-rn-monorepo/react-native-js.mdc +78 -0
  126. package/rules/native-rn-monorepo/web.mdc +60 -0
  127. package/rules/project-starter/components.mdc +54 -0
  128. package/rules/project-starter/data-fetching.mdc +77 -0
  129. package/rules/project-starter/git.mdc +41 -0
  130. package/rules/project-starter/supabase.mdc +37 -0
  131. package/rules/project-starter/tailwind.mdc +48 -0
  132. package/rules/project-starter/typescript.mdc +36 -0
  133. package/rules/project-starter/web-performance.mdc +42 -0
  134. package/rules/senior-engineer.mdc +30 -0
  135. package/rules/shell-first-search.mdc +19 -0
  136. package/rules/skill-workflows.mdc +35 -0
  137. package/rules/verification-before-completion.mdc +57 -0
  138. package/skills/audit-accessibility/SKILL.md +441 -0
  139. package/skills/audit-agent-speed/SKILL.md +181 -0
  140. package/skills/audit-agent-speed/scripts/stop-typecheck.mjs +151 -0
  141. package/skills/audit-analytics/SKILL.md +138 -0
  142. package/skills/audit-auth-flows/SKILL.md +267 -0
  143. package/skills/audit-backend-architecture/SKILL.md +266 -0
  144. package/skills/audit-backend-architecture/references/patterns.md +386 -0
  145. package/skills/audit-bundle-size/SKILL.md +295 -0
  146. package/skills/audit-cicd/SKILL.md +218 -0
  147. package/skills/audit-code-quality/SKILL.md +314 -0
  148. package/skills/audit-code-review/SKILL.md +289 -0
  149. package/skills/audit-codemod-safety/SKILL.md +159 -0
  150. package/skills/audit-db-schema/SKILL.md +465 -0
  151. package/skills/audit-db-schema/references/details.md +110 -0
  152. package/skills/audit-doctrine/SKILL.md +189 -0
  153. package/skills/audit-env-parity/SKILL.md +133 -0
  154. package/skills/audit-fe-api/SKILL.md +458 -0
  155. package/skills/audit-gate-logic/SKILL.md +219 -0
  156. package/skills/audit-i18n/SKILL.md +339 -0
  157. package/skills/audit-infra-cost/SKILL.md +142 -0
  158. package/skills/audit-langfuse-llm/SKILL.md +468 -0
  159. package/skills/audit-langfuse-llm/references/details.md +226 -0
  160. package/skills/audit-llm-security/SKILL.md +147 -0
  161. package/skills/audit-monetization-iap/SKILL.md +137 -0
  162. package/skills/audit-payment-system/SKILL.md +268 -0
  163. package/skills/audit-payment-system/references/checklist.md +283 -0
  164. package/skills/audit-performance/SKILL.md +383 -0
  165. package/skills/audit-performance/references/loading-priority-2026.md +81 -0
  166. package/skills/audit-realworld/SKILL.md +287 -0
  167. package/skills/audit-registry-listing/SKILL.md +122 -0
  168. package/skills/audit-resilience/SKILL.md +153 -0
  169. package/skills/audit-responsive/SKILL.md +221 -0
  170. package/skills/audit-responsive/references/checklist.md +166 -0
  171. package/skills/audit-security/SKILL.md +289 -0
  172. package/skills/audit-skill-conflicts/SKILL.md +178 -0
  173. package/skills/audit-ui-states/SKILL.md +146 -0
  174. package/skills/audit-uiux-design-system/SKILL.md +475 -0
  175. package/skills/audit-uiux-design-system/references/details.md +71 -0
  176. package/skills/audit-ux/SKILL.md +381 -0
  177. package/skills/audit-ux/references/details.md +245 -0
  178. package/skills/audit-ux-journeys/SKILL.md +215 -0
  179. package/skills/audit-ux-journeys/references/checklist.md +179 -0
  180. package/skills/backend-db-performance/SKILL.md +441 -0
  181. package/skills/backend-error-handling/SKILL.md +489 -0
  182. package/skills/backend-error-handling/references/details.md +58 -0
  183. package/skills/backend-observability/SKILL.md +88 -0
  184. package/skills/backend-patterns/SKILL.md +499 -0
  185. package/skills/backend-patterns/references/architecture-patterns.md +298 -0
  186. package/skills/backend-realtime/SKILL.md +403 -0
  187. package/skills/backend-realtime/references/patterns.md +74 -0
  188. package/skills/burndown-full/SKILL.md +174 -0
  189. package/skills/complete-everything/SKILL.md +295 -0
  190. package/skills/data-pipeline/SKILL.md +109 -0
  191. package/skills/data-visualization/SKILL.md +488 -0
  192. package/skills/debug-error/SKILL.md +322 -0
  193. package/skills/debug-fe-be-integration/SKILL.md +459 -0
  194. package/skills/debug-sentry-monitor/SKILL.md +497 -0
  195. package/skills/debug-sentry-monitor/references/details.md +165 -0
  196. package/skills/deploy-npm/SKILL.md +394 -0
  197. package/skills/deploy-npm/references/example-mushi-mushi.md +52 -0
  198. package/skills/deploy-verify/SKILL.md +489 -0
  199. package/skills/design-api/SKILL.md +379 -0
  200. package/skills/design-canvas/SKILL.md +155 -0
  201. package/skills/design-email/SKILL.md +370 -0
  202. package/skills/design-frontend/SKILL.md +143 -0
  203. package/skills/design-generative-art/SKILL.md +474 -0
  204. package/skills/design-mobile-first/SKILL.md +506 -0
  205. package/skills/design-motion/SKILL.md +333 -0
  206. package/skills/design-motion/references/delight-interactions.md +191 -0
  207. package/skills/design-prd/SKILL.md +443 -0
  208. package/skills/design-system/SKILL.md +457 -0
  209. package/skills/design-theme/SKILL.md +226 -0
  210. package/skills/design-theme/themes/tsumagoi-ranch.md +150 -0
  211. package/skills/docs-adr/SKILL.md +168 -0
  212. package/skills/docs-coauthor/SKILL.md +368 -0
  213. package/skills/docs-comparison-pages/SKILL.md +117 -0
  214. package/skills/docs-domain-modeling/SKILL.md +97 -0
  215. package/skills/docs-launch-kit/SKILL.md +139 -0
  216. package/skills/docs-writer/SKILL.md +469 -0
  217. package/skills/enhance-agent-guardrails/SKILL.md +164 -0
  218. package/skills/enhance-arch-boundaries/SKILL.md +154 -0
  219. package/skills/enhance-capacitor-ui/SKILL.md +463 -0
  220. package/skills/enhance-capacitor-ui/references/details.md +750 -0
  221. package/skills/enhance-email-deliverability/SKILL.md +143 -0
  222. package/skills/enhance-growth-loops/SKILL.md +122 -0
  223. package/skills/enhance-lifecycle-email/SKILL.md +130 -0
  224. package/skills/enhance-motion/SKILL.md +193 -0
  225. package/skills/enhance-onboarding/SKILL.md +148 -0
  226. package/skills/enhance-pwa/SKILL.md +303 -0
  227. package/skills/enhance-readability/SKILL.md +146 -0
  228. package/skills/enhance-readme/SKILL.md +496 -0
  229. package/skills/enhance-readme/package-lock.json +187 -0
  230. package/skills/enhance-readme/package.json +17 -0
  231. package/skills/enhance-readme/scripts/generate-readme-blocks.mjs +199 -0
  232. package/skills/enhance-readme/scripts/record-readme-tour.mjs +442 -0
  233. package/skills/enhance-skill-prompts/SKILL.md +167 -0
  234. package/skills/enhance-skill-prompts/references/exemplar-audit-auth-flows.md +311 -0
  235. package/skills/enhance-ux-laws/SKILL.md +409 -0
  236. package/skills/enhance-web-conversion/SKILL.md +155 -0
  237. package/skills/enhance-web-forms/SKILL.md +154 -0
  238. package/skills/enhance-web-instant-nav/SKILL.md +138 -0
  239. package/skills/enhance-web-instant-nav/references/bfcache-blockers.md +23 -0
  240. package/skills/enhance-web-instant-nav/references/early-hints.md +33 -0
  241. package/skills/enhance-web-instant-nav/references/speculation-rules.md +44 -0
  242. package/skills/enhance-web-landing/SKILL.md +459 -0
  243. package/skills/enhance-web-landing/references/details.md +773 -0
  244. package/skills/enhance-web-redesign/SKILL.md +228 -0
  245. package/skills/enhance-web-seo/SKILL.md +276 -0
  246. package/skills/enhance-web-ui/SKILL.md +473 -0
  247. package/skills/enhance-web-ui/references/details.md +674 -0
  248. package/skills/enhance-web-ux/HEURISTICS.md +248 -0
  249. package/skills/enhance-web-ux/PATTERNS.md +375 -0
  250. package/skills/enhance-web-ux/SKILL.md +464 -0
  251. package/skills/enhance-web-ux/examples.md +222 -0
  252. package/skills/enhance-web-ux/references/details.md +406 -0
  253. package/skills/enhance-web-web3d/SKILL.md +397 -0
  254. package/skills/enhance-web-web3d/references/css-canvas-effects.md +180 -0
  255. package/skills/handoff/SKILL.md +66 -0
  256. package/skills/housekeep-backlog/SKILL.md +149 -0
  257. package/skills/housekeep-dead-code/SKILL.md +387 -0
  258. package/skills/housekeep-dead-code/references/ratchet-ci.md +205 -0
  259. package/skills/housekeep-dead-code/references/supabase-hygiene.md +152 -0
  260. package/skills/housekeep-design/SKILL.md +207 -0
  261. package/skills/housekeep-files/SKILL.md +220 -0
  262. package/skills/housekeep-files/references/naming-and-catalog.md +86 -0
  263. package/skills/housekeep-files/scripts/housekeep-files.ps1 +360 -0
  264. package/skills/housekeep-files/scripts/housekeep-files.sh +238 -0
  265. package/skills/housekeep-gates/SKILL.md +174 -0
  266. package/skills/iterate-agent-harness/SKILL.md +137 -0
  267. package/skills/iterate-gtm-weekly/SKILL.md +103 -0
  268. package/skills/iterate-post-launch/SKILL.md +292 -0
  269. package/skills/meta-mcp-builder/SKILL.md +313 -0
  270. package/skills/meta-skill-creator/SKILL.md +304 -0
  271. package/skills/mobile-capacitor-platform/SKILL.md +103 -0
  272. package/skills/mobile-emulator-start/SKILL.md +296 -0
  273. package/skills/mobile-emulator-test/SKILL.md +491 -0
  274. package/skills/mobile-emulator-test/references/details.md +478 -0
  275. package/skills/mobile-rn-performance/SKILL.md +107 -0
  276. package/skills/mobile-rn-screen/SKILL.md +476 -0
  277. package/skills/mobile-rn-screen/references/details.md +785 -0
  278. package/skills/mushi-health/SKILL.md +206 -0
  279. package/skills/mushi-integration/SKILL.md +257 -0
  280. package/skills/plan-aeo-readiness/SKILL.md +166 -0
  281. package/skills/plan-antislop/SKILL.md +281 -0
  282. package/skills/plan-aso/SKILL.md +149 -0
  283. package/skills/plan-backup-dr/SKILL.md +131 -0
  284. package/skills/plan-capacitor-hardening/SKILL.md +217 -0
  285. package/skills/plan-data-integrity/SKILL.md +187 -0
  286. package/skills/plan-dead-code/SKILL.md +386 -0
  287. package/skills/plan-dead-code/references/knip-config.md +214 -0
  288. package/skills/plan-dead-code/references/output-templates.md +133 -0
  289. package/skills/plan-dead-code/references/preservation-contract.md +50 -0
  290. package/skills/plan-dead-code/references/residue-greps.md +84 -0
  291. package/skills/plan-dependency-provenance/SKILL.md +200 -0
  292. package/skills/plan-docs-sync/SKILL.md +143 -0
  293. package/skills/plan-docs-sync/references/drift-taxonomy.md +43 -0
  294. package/skills/plan-docs-sync/references/output-templates.md +33 -0
  295. package/skills/plan-docs-sync/references/preservation-contract.md +17 -0
  296. package/skills/plan-error-handling/SKILL.md +205 -0
  297. package/skills/plan-gtm/SKILL.md +276 -0
  298. package/skills/plan-gtm/references/benchmarks-2026.md +183 -0
  299. package/skills/plan-input-validation/SKILL.md +179 -0
  300. package/skills/plan-llm-cost-guardrails/SKILL.md +176 -0
  301. package/skills/plan-mobile-readiness/SKILL.md +171 -0
  302. package/skills/plan-perf-audit/SKILL.md +145 -0
  303. package/skills/plan-perf-audit/references/audit-scope.md +51 -0
  304. package/skills/plan-perf-audit/references/output-templates.md +33 -0
  305. package/skills/plan-perf-audit/references/preservation-contract.md +13 -0
  306. package/skills/plan-pricing/SKILL.md +173 -0
  307. package/skills/plan-privacy-compliance/SKILL.md +148 -0
  308. package/skills/plan-rls-audit/SKILL.md +231 -0
  309. package/skills/plan-secrets-audit/SKILL.md +181 -0
  310. package/skills/plan-security-audit/SKILL.md +168 -0
  311. package/skills/plan-security-audit/references/output-templates.md +36 -0
  312. package/skills/plan-security-audit/references/owasp-supabase-scope.md +55 -0
  313. package/skills/plan-security-audit/references/preservation-contract.md +18 -0
  314. package/skills/plan-stub-checker/SKILL.md +216 -0
  315. package/skills/plan-stub-checker/references/detection-methodology.md +75 -0
  316. package/skills/plan-stub-checker/references/detection-taxonomy.md +34 -0
  317. package/skills/plan-stub-checker/references/output-templates.md +63 -0
  318. package/skills/plan-stub-checker/references/preservation-contract.md +24 -0
  319. package/skills/plan-test-coverage/SKILL.md +170 -0
  320. package/skills/plan-test-coverage/references/methodology.md +54 -0
  321. package/skills/plan-test-coverage/references/output-templates.md +34 -0
  322. package/skills/plan-test-coverage/references/preservation-contract.md +15 -0
  323. package/skills/plan-uiux-unification/SKILL.md +230 -0
  324. package/skills/plan-uiux-unification/references/output-templates.md +67 -0
  325. package/skills/plan-uiux-unification/references/phase-workbook.md +85 -0
  326. package/skills/plan-uiux-unification/references/preservation-contract.md +24 -0
  327. package/skills/protocol-browser-anti-stall/SKILL.md +211 -0
  328. package/skills/protocol-browser-anti-stall/references/mcp-to-cli-map.md +113 -0
  329. package/skills/protocol-browser-anti-stall/references/playwright-session-coordination.md +170 -0
  330. package/skills/research/SKILL.md +422 -0
  331. package/skills/test-exploratory/SKILL.md +165 -0
  332. package/skills/test-exploratory/references/charter-template.md +29 -0
  333. package/skills/test-load/SKILL.md +126 -0
  334. package/skills/test-mutation/SKILL.md +160 -0
  335. package/skills/test-playwright/SKILL.md +354 -0
  336. package/skills/test-qa/SKILL.md +364 -0
  337. package/skills/test-qa/references/details.md +268 -0
  338. package/skills/test-red-team/SKILL.md +386 -0
  339. package/skills/test-red-team/references/owasp-attack-checklist.md +193 -0
  340. package/skills/test-unit/SKILL.md +259 -0
  341. package/skills/test-unit/references/details.md +267 -0
  342. package/skills/test-visual-regression/SKILL.md +132 -0
  343. package/skills/thirdparty-emil-design-eng/ATTRIBUTION.md +20 -0
  344. package/skills/thirdparty-emil-design-eng/SKILL.md +21 -0
  345. package/skills/thirdparty-emil-design-eng/references/emil-design-eng.md +676 -0
  346. package/skills/thirdparty-ui-ux-pro-max/ATTRIBUTION.md +22 -0
  347. package/skills/thirdparty-ui-ux-pro-max/SKILL.md +304 -0
  348. package/skills/thirdparty-ui-ux-pro-max/data/charts.csv +26 -0
  349. package/skills/thirdparty-ui-ux-pro-max/data/colors.csv +97 -0
  350. package/skills/thirdparty-ui-ux-pro-max/data/icons.csv +101 -0
  351. package/skills/thirdparty-ui-ux-pro-max/data/landing.csv +31 -0
  352. package/skills/thirdparty-ui-ux-pro-max/data/products.csv +97 -0
  353. package/skills/thirdparty-ui-ux-pro-max/data/react-performance.csv +45 -0
  354. package/skills/thirdparty-ui-ux-pro-max/data/stacks/astro.csv +54 -0
  355. package/skills/thirdparty-ui-ux-pro-max/data/stacks/flutter.csv +53 -0
  356. package/skills/thirdparty-ui-ux-pro-max/data/stacks/html-tailwind.csv +56 -0
  357. package/skills/thirdparty-ui-ux-pro-max/data/stacks/jetpack-compose.csv +53 -0
  358. package/skills/thirdparty-ui-ux-pro-max/data/stacks/nextjs.csv +53 -0
  359. package/skills/thirdparty-ui-ux-pro-max/data/stacks/nuxt-ui.csv +51 -0
  360. package/skills/thirdparty-ui-ux-pro-max/data/stacks/nuxtjs.csv +59 -0
  361. package/skills/thirdparty-ui-ux-pro-max/data/stacks/react-native.csv +52 -0
  362. package/skills/thirdparty-ui-ux-pro-max/data/stacks/react.csv +54 -0
  363. package/skills/thirdparty-ui-ux-pro-max/data/stacks/shadcn.csv +61 -0
  364. package/skills/thirdparty-ui-ux-pro-max/data/stacks/svelte.csv +54 -0
  365. package/skills/thirdparty-ui-ux-pro-max/data/stacks/swiftui.csv +51 -0
  366. package/skills/thirdparty-ui-ux-pro-max/data/stacks/vue.csv +50 -0
  367. package/skills/thirdparty-ui-ux-pro-max/data/styles.csv +68 -0
  368. package/skills/thirdparty-ui-ux-pro-max/data/typography.csv +58 -0
  369. package/skills/thirdparty-ui-ux-pro-max/data/ui-reasoning.csv +101 -0
  370. package/skills/thirdparty-ui-ux-pro-max/data/ux-guidelines.csv +100 -0
  371. package/skills/thirdparty-ui-ux-pro-max/data/web-interface.csv +31 -0
  372. package/skills/thirdparty-ui-ux-pro-max/scripts/core.py +253 -0
  373. package/skills/thirdparty-ui-ux-pro-max/scripts/design_system.py +1067 -0
  374. package/skills/thirdparty-ui-ux-pro-max/scripts/search.py +114 -0
  375. package/skills/thirdparty-web-interface-guidelines/ATTRIBUTION.md +23 -0
  376. package/skills/thirdparty-web-interface-guidelines/SKILL.md +190 -0
  377. package/skills/workflow-build-feature/SKILL.md +118 -0
  378. package/skills/workflow-coding-discipline/SKILL.md +140 -0
  379. package/skills/workflow-environment-ready/SKILL.md +128 -0
  380. package/skills/workflow-feature-flag/SKILL.md +262 -0
  381. package/skills/workflow-feedback-to-closure/SKILL.md +165 -0
  382. package/skills/workflow-fix-and-ship/SKILL.md +136 -0
  383. package/skills/workflow-git-commit/SKILL.md +200 -0
  384. package/skills/workflow-green-repo/SKILL.md +166 -0
  385. package/skills/workflow-grilling/SKILL.md +73 -0
  386. package/skills/workflow-gtm/SKILL.md +153 -0
  387. package/skills/workflow-housekeep/SKILL.md +453 -0
  388. package/skills/workflow-housekeep/references/templates.md +109 -0
  389. package/skills/workflow-launch-ready/SKILL.md +145 -0
  390. package/skills/workflow-merge-conflicts/SKILL.md +62 -0
  391. package/skills/workflow-onboard/SKILL.md +99 -0
  392. package/skills/workflow-parallel-agents/SKILL.md +164 -0
  393. package/skills/workflow-pr/SKILL.md +197 -0
  394. package/skills/workflow-quality-gate/SKILL.md +147 -0
  395. package/skills/workflow-refactor/SKILL.md +274 -0
  396. package/skills/workflow-release-prep/SKILL.md +207 -0
  397. package/skills/workflow-ship-and-observe/SKILL.md +164 -0
  398. package/skills/workflow-spec-tdd/SKILL.md +141 -0
  399. package/skills/workflow-spec-tdd/references/spec-template.md +126 -0
  400. package/skills/workflow-spec-tdd/references/tdd-patterns.md +167 -0
  401. package/skills-cursor/babysit/SKILL.md +17 -0
  402. package/skills-cursor/canvas/SKILL.md +142 -0
  403. package/skills-cursor/canvas/sdk/canvas-tokens.d.ts +235 -0
  404. package/skills-cursor/canvas/sdk/chart-primitives.d.ts +200 -0
  405. package/skills-cursor/canvas/sdk/dag-layout.d.ts +102 -0
  406. package/skills-cursor/canvas/sdk/diff-view.d.ts +130 -0
  407. package/skills-cursor/canvas/sdk/form-primitives.d.ts +194 -0
  408. package/skills-cursor/canvas/sdk/hooks.d.ts +117 -0
  409. package/skills-cursor/canvas/sdk/index.d.ts +47 -0
  410. package/skills-cursor/canvas/sdk/theme.d.ts +61 -0
  411. package/skills-cursor/canvas/sdk/todo-list.d.ts +49 -0
  412. package/skills-cursor/canvas/sdk/ui-primitives.d.ts +549 -0
  413. package/skills-cursor/canvas/sdk/ui-primitives.test.d.ts +2 -0
  414. package/skills-cursor/create-hook/SKILL.md +238 -0
  415. package/skills-cursor/create-rule/SKILL.md +185 -0
  416. package/skills-cursor/create-skill/SKILL.md +269 -0
  417. package/skills-cursor/create-skill/references/authoring-guide.md +182 -0
  418. package/skills-cursor/create-subagent/SKILL.md +228 -0
  419. package/skills-cursor/migrate-to-skills/SKILL.md +121 -0
  420. package/skills-cursor/shell/SKILL.md +22 -0
  421. package/skills-cursor/split-to-prs/SKILL.md +47 -0
  422. package/skills-cursor/statusline/SKILL.md +193 -0
  423. package/skills-cursor/update-cli-config/SKILL.md +85 -0
  424. package/skills-cursor/update-cursor-settings/SKILL.md +137 -0
  425. package/skills.sh.json +297 -0
@@ -0,0 +1,24 @@
1
+ # Preservation Contract
2
+
3
+ Applies to **every phase**. Read before auditing or proposing anything.
4
+
5
+ ## Never do in this pass
6
+
7
+ - **Remove** features, routes, screens, states, props, or handlers. Redundant-looking code → list as a *proposal for approval*, never delete unilaterally.
8
+ - **Fabricate** data, content, copy, API fields, endpoints, or assets. No lorem ipsum, fake names/numbers/avatars. Missing content → tag `[NEEDS REAL CONTENT]`, leave existing values untouched.
9
+ - **Guess** codebase facts. Ground every claim in a file you read; cite path (and line when useful). Can't verify → say so.
10
+ - **Change I/O or business logic** silently: data contracts, API shapes, state, error handling, auth, side-effects, analytics, i18n keys, feature flags, a11y behavior stay functionally identical unless explicitly proposed + approved.
11
+ - **Break** public APIs, props, or routes without flagging as breaking + migration note.
12
+ - **Rewrite UI** in this pass. Visual/UX changes are **proposals**, not faits accomplis.
13
+
14
+ ## Before any file change proposal
15
+
16
+ State in one line **what currently works there that must keep working** (forces verification → fewer breakages).
17
+
18
+ ## Three finding buckets
19
+
20
+ Keep separate in the violation log:
21
+
22
+ 1. **Violates a documented rule** (token lint, STYLEGUIDE, CONTRIBUTING)
23
+ 2. **Subjective improvement** (better hierarchy, clearer copy — preserve meaning)
24
+ 3. **Needs design-system enhancement** (missing semantic token, no elevation scale)
@@ -0,0 +1,211 @@
1
+ ---
2
+ name: protocol-browser-anti-stall
3
+ description: >
4
+ Guardrail for Playwright CLI sessions: headed, named, isolated; prevents
5
+ parallel collisions and recovers stalls without scripted shortcuts. Read
6
+ before browser work or when automation freezes.
7
+ license: MIT
8
+ user-invocable: false
9
+ ---
10
+
11
+ # Browser Anti-Stall Protocol (playwright-cli)
12
+
13
+ **Degree of freedom: LOW.** Almost every step is exact. Only "why it
14
+ stalled" and the next hypothesis are `[HIGH freedom]`.
15
+
16
+ This repo drives browsers with **`playwright-cli`**, not the Playwright MCP. The MCP exposes one
17
+ browser per server and a persistent profile can only be locked by one process at a time, so
18
+ parallel agents on the same repo fight over tabs and profile locks. The CLI gives every agent its
19
+ own isolated browser via `-s=<session>`, costs far fewer tokens (no tool schemas or verbose trees
20
+ loaded into context), and runs natively in parallel shells.
21
+
22
+ **Read `references/mcp-to-cli-map.md`** if you encounter old `browser_*` MCP tool calls — it maps
23
+ every tool to its CLI command. **Read `references/playwright-session-coordination.md`** before your
24
+ first command — session naming, persistent logins (incl. the Google/CDP block), and cleanup.
25
+
26
+ ## How to reason
27
+
28
+ 1. **Observe** — snapshot, screenshot, console, requests, and the session name
29
+ 2. **Interpret** — stale ref, SPA hydration, pending request, or a real blocker
30
+ 3. **Classify** — one new-hypothesis retry / 2s sleep-cycle / BLOCKER report
31
+ 4. **Recover** — one real user action, then look; never `eval` to click
32
+
33
+ ## Worked example
34
+
35
+ > **Observe:** checkout `click`; URL still `/cart`; console hydration warning; `POST /api/checkout` pending; session `-s=qa-checkout`.
36
+ > **Interpret:** SPA not ready + possibly a stale ref — not "the button is missing".
37
+ > **Classify:** attempt 2 — `find`/`waitFor` a landmark, fresh `snapshot`, then click. Not `run-code` to submit.
38
+ > **Stop at 4:** still stuck → BLOCKER with console + requests + screenshot.
39
+
40
+ ## Self-critique before reporting
41
+
42
+ - **Headed + `-s=`** — every call; never a shared session name
43
+ - **Inspection-only eval** — `eval` / `run-code` never click, type, or submit
44
+ - **Evidence before retry** — max 4 attempts, then BLOCKER
45
+ - **Right owner** — product QA behavior stays with the calling test/audit skill
46
+
47
+ ---
48
+
49
+ ## Invocation — always this form [LOW freedom — run exactly]
50
+
51
+ ```bash
52
+ PW="npx --yes @playwright/cli@latest" # portable; survives fnm/nvm version switches
53
+ $PW -s=<session> <command> [args]
54
+ ```
55
+
56
+ - **`-s=<session>` is mandatory on every call.** Name it after your task or branch
57
+ (`-s=qa-checkout`, `-s=audit-ux-home`). Two agents must never share a session name.
58
+ - **Do not rely on a global `npm i -g` install.** Under `fnm`/`nvm` the global prefix is
59
+ per-shell and disappears; `npx` always resolves.
60
+ - `--json` / `--raw` are available when you need machine-readable output.
61
+
62
+ ## 0. Manual & headed — never scripted (read first) [LOW freedom — run exactly]
63
+
64
+ You are driving a **real, visible browser** to feel what a user feels. A green script proves
65
+ nothing about UX — *see the screen* and *watch the logs*.
66
+
67
+ 1. **Headed, always.** The CLI defaults to **headless** — you MUST pass `--headed` on `open`.
68
+ If you cannot see the window, say so rather than proceeding blind.
69
+ 2. **One real action at a time.** `click`, `type`, `fill`, `select`, `hover`, `press`, `drag`
70
+ exactly as a user would. Never chain a whole flow into one code snippet.
71
+ 3. **`eval` / `run-code` are inspection-only.** Use them ONLY to *read* state (DOM, computed
72
+ styles, storage, perf) or to wait for an element — never to click, type, navigate, or submit.
73
+ Driving the UI through code bypasses real events and hides the bug you are hunting.
74
+ 4. **No test files, no runner.** Do not write `*.spec.ts`, run `npx playwright test`, or use
75
+ codegen. You are here to *experience* the flow, not automate past it.
76
+ 5. **Look after every action.** Fresh `snapshot` + `screenshot` + `console` + `requests`, plus the
77
+ dev-server terminal. Real pain surfaces on screen and in logs, not in an assertion.
78
+
79
+ ## 1. Session lifecycle [LOW freedom — run exactly]
80
+
81
+ ```bash
82
+ $PW -s=qa-checkout open --headed http://localhost:3000 # start (once)
83
+ $PW -s=qa-checkout goto http://localhost:3000/cart # navigate within the session
84
+ $PW -s=qa-checkout snapshot # get refs
85
+ $PW -s=qa-checkout close # end YOUR session when done
86
+ $PW list # see all sessions (status, profile, headed)
87
+ $PW close-all # only when you own every session
88
+ $PW kill-all # last resort: stale/zombie processes
89
+ ```
90
+
91
+ - `open` starts a browser; `goto` navigates an already-open one. Calling `open` twice on the same
92
+ session is wasteful — use `goto`.
93
+ - **Close only your own session.** Never `close-all` while another agent may be mid-test.
94
+ - Add `--browser chrome|firefox|webkit|msedge`, `--device "iphone 15"`, or `--mobile` on `open`
95
+ when the task calls for it.
96
+
97
+ ## 2. Navigation guard [LOW freedom — run exactly]
98
+
99
+ After every `open` / `goto` / `reload`:
100
+
101
+ 1. `snapshot` — confirm the URL changed and the page has content.
102
+ 2. If blank or unchanged → `sleep 2` → `snapshot` again.
103
+ 3. **Max 3 cycles (~6s).** Still not loaded → report a blocker (§8) and move on.
104
+
105
+ Never assume navigation succeeded without a snapshot to confirm it.
106
+
107
+ ## 3. Waiting — there is no `wait` command [LOW freedom — run exactly]
108
+
109
+ Playwright **auto-waits** for actionability on `click`/`fill`/`select`, so most explicit waits are
110
+ unnecessary. When you genuinely must wait:
111
+
112
+ | Need | Do this |
113
+ |---|---|
114
+ | Fixed short pause | `sleep 2` in the shell — **never more than 3s per pause** |
115
+ | Wait for text/element | `run-code "async (page) => { await page.getByText('Dashboard').first().waitFor({ timeout: 5000 }); return 'ready'; }"` |
116
+ | Wait for something to disappear | `...waitFor({ state: 'hidden', timeout: 5000 })` |
117
+ | Poll for content | `find "<text>"` → if no match, `sleep 2` → retry (max 3) |
118
+
119
+ **Always set an explicit `timeout`** (milliseconds) in `waitFor` — the default 30s is far too long.
120
+ Use the incremental pattern instead of one long block:
121
+
122
+ ```
123
+ sleep 2 → snapshot → check ↓ not ready
124
+ sleep 2 → snapshot → check ↓ not ready
125
+ sleep 2 → snapshot → check ↓ still not ready
126
+ STOP → report blocker with evidence
127
+ ```
128
+
129
+ This handles cold starts, SPA hydration, and slow APIs without ever blocking blindly.
130
+
131
+ ## 4. SPA-specific rules [LOW freedom — run exactly]
132
+
133
+ SPAs (React, Next.js, Vue) fire `load` before hydration completes — never trust load events.
134
+
135
+ - Wait for a **specific UI landmark** that proves the app rendered (`run-code` + `waitFor`, or `find`).
136
+ - If a spinner is showing, wait for it to reach `state: 'hidden'` rather than sleeping.
137
+
138
+ ## 5. Anti-loop: max 4 attempts per goal [LOW freedom — run exactly]
139
+
140
+ | Attempt | Action |
141
+ |---|---|
142
+ | 1 | Try the action normally |
143
+ | 2 | Alternative approach — re-`snapshot` for a fresh ref, try a CSS selector instead, scroll into view, or `find` the element |
144
+ | 3 | Gather evidence: `console` + `requests` |
145
+ | 4 | **STOP.** Report what blocked progress, with evidence. |
146
+
147
+ Never repeat the exact same failing action without new evidence.
148
+
149
+ **Fresh refs after every state change.** Refs from a stale `snapshot` are invalid after any
150
+ navigate/click/fill/hover/key press. Re-`snapshot` before the next interaction. `click` also accepts
151
+ a unique CSS selector, which survives state changes better than a ref.
152
+
153
+ ## 6. Evidence before retry [LOW freedom — run exactly]
154
+
155
+ When something is not working, gather evidence FIRST, then form a hypothesis:
156
+
157
+ 1. `console` — JS errors, warnings (`console error` to filter by level)
158
+ 2. `requests` — pending/failed calls; `request <n>` / `response-body <n>` for detail
159
+ 3. `snapshot` — the actual DOM state, not what you assume
160
+ 4. `screenshot --filename .playwright-mcp/<name>.png` — visual state
161
+
162
+ Only retry once you have a new hypothesis grounded in that evidence.
163
+
164
+ ## 7. Timeout budget [LOW freedom — run exactly]
165
+
166
+ | Scope | Max time |
167
+ |---|---|
168
+ | Single interaction (click, fill, select) | 15 seconds |
169
+ | Navigation + verification | 30 seconds |
170
+ | Multi-page flow | 5 minutes |
171
+ | Full session | 15 minutes |
172
+
173
+ Exceeded? **Skip it** and log `[TIMEOUT] skipped: <step>`. One stuck step must not kill the session.
174
+
175
+ ## 8. Blocker reporting format [LOW freedom — this shape]
176
+
177
+ ```
178
+ BLOCKER:
179
+ - Session: [-s= name]
180
+ - Page: [current URL]
181
+ - Goal: [what I was trying to do]
182
+ - Blocked by: [what prevented it]
183
+ - Evidence: [console errors / failed requests / screenshot observation]
184
+ - Suggestion: [most likely next step or manual action needed]
185
+ ```
186
+
187
+ Actionable information beats a silent freeze.
188
+
189
+ ## 9. Artifacts [LOW freedom — run exactly]
190
+
191
+ - Screenshots, snapshots, and logs go under **`.playwright-mcp/`** (gitignored):
192
+ `screenshot --filename .playwright-mcp/home-390.png`. Name by route + viewport/step.
193
+ - The CLI also auto-writes snapshot `.yml` files to `.playwright-cli/` in the working directory —
194
+ also gitignored, never committed.
195
+ - Sweep any stray root-level `*.png` / `*.log` into `.playwright-mcp/` before ending the session.
196
+
197
+ ## 10. Parallel agents [LOW freedom — run exactly]
198
+
199
+ Each agent gets its own browser through session isolation:
200
+
201
+ ```bash
202
+ # agent A # agent B (simultaneously, no conflict)
203
+ $PW -s=audit-ux open --headed … $PW -s=qa-checkout open --headed …
204
+ ```
205
+
206
+ - Never reuse another agent's session name; never `close`/`kill-all` sessions you did not open.
207
+ - `list` shows every session with its status, profile, and headed flag — check it before assuming.
208
+ - Within one session, multiple tabs are still available (`tab-list`, `tab-new`, `tab-select`,
209
+ `tab-close`); the fresh-refs rule applies after every tab switch.
210
+ - Signed-in state is shared through **persistent profiles**, not shared tabs — see
211
+ `references/playwright-session-coordination.md`.
@@ -0,0 +1,113 @@
1
+ # Playwright MCP → playwright-cli command map
2
+
3
+ This repo migrated off the Playwright **MCP** (one browser per server, single profile lock, heavy
4
+ tool schemas in context) to the **CLI** (`npx --yes @playwright/cli@latest`), which gives every
5
+ agent its own isolated browser via `-s=<session>`.
6
+
7
+ Every command below assumes:
8
+
9
+ ```bash
10
+ PW="npx --yes @playwright/cli@latest"
11
+ $PW -s=<session> <command> [args]
12
+ ```
13
+
14
+ Verified against `@playwright/cli@0.1.17`.
15
+
16
+ ---
17
+
18
+ ## Core actions
19
+
20
+ | Old MCP tool | CLI command | Notes |
21
+ |---|---|---|
22
+ | `browser_navigate({ url })` | `open --headed <url>` (first) / `goto <url>` (after) | CLI is **headless by default** — pass `--headed` on `open` |
23
+ | `browser_navigate_back` | `go-back` | also `go-forward`, `reload` |
24
+ | `browser_snapshot` | `snapshot [target]` | returns refs; auto-saves a `.yml` under `.playwright-cli/` |
25
+ | `browser_find` | `find "<text>"` | `--regex` for patterns; returns matching nodes with refs |
26
+ | `browser_click({ ref })` | `click <target> [button]` | `<target>` = ref **or a unique CSS selector**; `--modifiers` supported |
27
+ | `browser_type({ text })` | `type <text>` | types into the focused editable element |
28
+ | `browser_fill_form` | `fill <target> <text>` | one field at a time (matches "one real action" rule) |
29
+ | `browser_select_option` | `select <target> <value>` | |
30
+ | `browser_hover` | `hover <target>` | |
31
+ | `browser_press_key` | `press <key>` | e.g. `press enter`, `press arrowleft`; also `keydown`/`keyup` |
32
+ | `browser_drag` | `drag <startTarget> <endTarget>` | |
33
+ | `browser_drop` | `drop <target>` | |
34
+ | `browser_file_upload` | `upload <file>` | |
35
+ | `browser_handle_dialog` | `dialog-accept [prompt]` / `dialog-dismiss` | |
36
+ | `browser_resize` | `resize <w> <h>` | or `open --device "iphone 15"` / `--mobile` |
37
+ | `browser_close` | `close` | closes **your** session only |
38
+ | *(no equivalent)* | `check` / `uncheck` | checkbox and radio helpers |
39
+ | *(no equivalent)* | `dblclick` | |
40
+
41
+ ## Waiting
42
+
43
+ | Old MCP tool | CLI replacement |
44
+ |---|---|
45
+ | `browser_wait_for({ time: 2 })` | `sleep 2` in the shell (**≤3s per pause**) |
46
+ | `browser_wait_for({ text, timeout })` | `run-code "async (page) => { await page.getByText('<text>').first().waitFor({ timeout: 5000 }); return 'ready'; }"` |
47
+ | `browser_wait_for({ textGone, timeout })` | same, with `waitFor({ state: 'hidden', timeout: 5000 })` |
48
+
49
+ There is **no `wait` command**. Playwright auto-waits for actionability on `click`/`fill`/`select`,
50
+ so most explicit waits are unnecessary. Always set an explicit `timeout` when you do wait.
51
+
52
+ ## Evidence & inspection
53
+
54
+ | Old MCP tool | CLI command | Notes |
55
+ |---|---|---|
56
+ | `browser_console_messages` | `console [min-level]` | e.g. `console error` |
57
+ | `browser_network_requests` | `requests` | numbered list |
58
+ | `browser_network_request` | `request <index>` | plus `request-headers`, `request-body`, `response-headers`, `response-body` |
59
+ | `browser_take_screenshot({ filename })` | `screenshot --filename .playwright-mcp/<name>.png` | `--full-page`, `--hires` available |
60
+ | `browser_evaluate` | `eval <func> [target]` | **read-only** per the protocol |
61
+ | `browser_run_code_unsafe` | `run-code "<code>"` | **read-only / waits only** per the protocol |
62
+ | *(no equivalent)* | `pdf` | save page as PDF |
63
+
64
+ ## Tabs
65
+
66
+ | Old MCP tool | CLI command |
67
+ |---|---|
68
+ | `browser_tabs({ action: "list" })` | `tab-list` |
69
+ | `browser_tabs({ action: "new" })` | `tab-new [url]` |
70
+ | `browser_tabs({ action: "select", index })` | `tab-select <index>` |
71
+ | `browser_tabs({ action: "close", index })` | `tab-close [index]` |
72
+
73
+ ## Storage, auth & network control
74
+
75
+ | Need | CLI command |
76
+ |---|---|
77
+ | Save auth state | `state-save [filename]` |
78
+ | Restore auth state | `state-load <filename>` |
79
+ | Cookies | `cookie-list`, `cookie-get`, `cookie-set`, `cookie-delete`, `cookie-clear` |
80
+ | localStorage | `localstorage-list/get/set/delete/clear` |
81
+ | sessionStorage | `sessionstorage-list/get/set/delete/clear` |
82
+ | Mock a request | `route <pattern>`, `route-list`, `unroute [pattern]` |
83
+ | Offline testing | `network-state-set offline` (or `online`) |
84
+
85
+ ## Session management (the parallelism fix)
86
+
87
+ | Need | CLI command |
88
+ |---|---|
89
+ | Isolated browser per agent | `-s=<unique-name>` on every call |
90
+ | See all sessions | `list` (`--all` across workspaces) |
91
+ | Close every session | `close-all` — only when you own them all |
92
+ | Kill zombies | `kill-all` |
93
+ | Persistent login profile | `open --persistent --profile <dir>` |
94
+ | Visual dashboard of live sessions | `show` |
95
+ | Attach to an already-running browser | `attach [name]` / `detach` |
96
+
97
+ ## Concepts that no longer apply
98
+
99
+ | Old concept | Why it's gone |
100
+ |---|---|
101
+ | `browser_lock` / unlock (cursor-ide-browser MCP) | No shared browser to lock — sessions are isolated |
102
+ | Tab-claiming etiquette across agents | Each agent opens its own session instead |
103
+ | `session.json` auth-tab pointer | Auth lives in a persistent **profile directory** |
104
+ | `--isolated` storage-state injection dance | Persistent profiles are the default path for auth |
105
+ | Headed-by-default assumption | CLI is headless by default — pass `--headed` explicitly |
106
+
107
+ ## Gotchas
108
+
109
+ - **`npm i -g` is unreliable under `fnm`/`nvm`** (per-shell global prefix). Always use `npx --yes @playwright/cli@latest`.
110
+ - **Never log into Google from a Playwright-launched browser** — it is blocked at the CDP layer.
111
+ See `playwright-session-coordination.md` for the real-Chrome workaround.
112
+ - Snapshot `.yml` artifacts land in `.playwright-cli/`; screenshots should be directed to
113
+ `.playwright-mcp/` with `--filename`. Both are gitignored.
@@ -0,0 +1,170 @@
1
+ # playwright-cli sessions, parallel agents & persisted logins
2
+
3
+ How to run many agents against browsers at once without collisions, and how to stay signed in
4
+ across turns — including the Google sign-in wall that blocks every Playwright-launched browser.
5
+
6
+ ```bash
7
+ PW="npx --yes @playwright/cli@latest"
8
+ ```
9
+
10
+ ---
11
+
12
+ ## 1. One session per agent
13
+
14
+ `-s=<name>` is the whole parallelism story. Each name gets its own browser process and its own
15
+ storage, so two agents never share tabs, cookies, or a profile lock.
16
+
17
+ ```bash
18
+ # agent A # agent B — simultaneously, zero conflict
19
+ $PW -s=audit-ux-home open --headed … $PW -s=qa-checkout open --headed …
20
+ ```
21
+
22
+ **Naming:** use the task or branch (`qa-checkout`, `audit-ux-home`, `feat-login-fix`). Never a
23
+ generic name like `test` or `default` — that is how two agents collide.
24
+
25
+ **Rules**
26
+
27
+ - Never issue commands against a session name you did not open.
28
+ - Never `close-all` / `kill-all` while another agent may be working — close only your own session.
29
+ - `$PW list` shows every session with status, `user-data-dir`, and headed flag. Check it before
30
+ assuming a session exists.
31
+ - `$PW show` opens a dashboard to watch/control live sessions — useful when agents run in the
32
+ background.
33
+
34
+ **Defaults worth knowing** (verified on `@playwright/cli@0.1.17`):
35
+
36
+ | Default | Value | Implication |
37
+ |---|---|---|
38
+ | `user-data-dir` | `<in-memory>` | Nothing persists unless you pass `--persistent --profile` |
39
+ | headed | `false` | Pass `--headed` — this repo's protocol requires a visible browser |
40
+ | browser | detected Chrome | Override with `--browser chrome\|firefox\|webkit\|msedge` |
41
+
42
+ ---
43
+
44
+ ## 2. Persistent profiles = persisted logins
45
+
46
+ Sessions are ephemeral by default. To stay signed in across turns and restarts, give the session a
47
+ profile directory on disk:
48
+
49
+ ```bash
50
+ $PW -s=work open --headed --browser chrome \
51
+ --persistent --profile "$HOME/.playwright-cli-profiles/<account>" \
52
+ https://app.example.com
53
+ ```
54
+
55
+ Everything a real browser stores (cookies, localStorage, device trust) survives `close` and
56
+ reopening with the same `--profile`.
57
+
58
+ **Convention:** one directory per account/environment under
59
+ `~/.playwright-cli-profiles/<account-or-env>`. Keep profiles **outside the repo** so every project
60
+ reuses one login, and so session cookies never land near version control.
61
+
62
+ **Never point `--profile` at your everyday Chrome profile**
63
+ (`%LOCALAPPDATA%\Google\Chrome\User Data`) — it causes lock conflicts, crashes, and policy errors.
64
+ Always use a dedicated automation directory.
65
+
66
+ ### Storage-state files (lighter alternative)
67
+
68
+ For simple cookie/localStorage auth, skip profiles and use state files:
69
+
70
+ ```bash
71
+ $PW -s=qa state-save .playwright-mcp/auth/localhost-3000.json # after logging in
72
+ $PW -s=qa state-load .playwright-mcp/auth/localhost-3000.json # next run
73
+ ```
74
+
75
+ Good for local/staging app logins. Weaker than a profile against modern anti-bot checks, and it
76
+ does not carry device-trust signals. Treat these files as secrets — `.playwright-mcp/` is gitignored.
77
+
78
+ ---
79
+
80
+ ## 3. Google sign-in: the one case that needs real Chrome
81
+
82
+ **You cannot log into a Google account from a Playwright-launched browser.** Google detects that
83
+ the browser is driven over the Chrome DevTools Protocol and returns:
84
+
85
+ > This browser or app may not be secure.
86
+
87
+ There is no user-agent, header, stealth plugin, or flag that gets past it. Do not waste attempts.
88
+
89
+ ### The working sequence (one time per account)
90
+
91
+ **Step 1 — log in with real Chrome, no automation, no CDP flags:**
92
+
93
+ ```bash
94
+ "/c/Program Files/Google/Chrome/Application/chrome.exe" \
95
+ --user-data-dir="C:\Users\<you>\.playwright-cli-profiles\<account>" \
96
+ --no-first-run --no-default-browser-check \
97
+ "https://accounts.google.com/"
98
+ ```
99
+
100
+ The **user** signs in by hand, including 2FA. Never ask for or type their password — hand them the
101
+ window. Then close Chrome completely so the profile is unlocked and flushed to disk.
102
+
103
+ **Step 2 — reuse that profile from playwright-cli forever after:**
104
+
105
+ ```bash
106
+ $PW -s=gmail open --headed --browser chrome \
107
+ --persistent --profile "$HOME/.playwright-cli-profiles/<account>" \
108
+ https://mail.google.com
109
+ $PW -s=gmail snapshot # already signed in
110
+ ```
111
+
112
+ ### Rules
113
+
114
+ - Omit `--remote-debugging-port` during Step 1 — an active CDP endpoint is the thing Google detects.
115
+ - Chrome must be **fully closed** before Step 2; two processes cannot hold one profile.
116
+ - Re-run Step 1 only if the session actually expires (rare — it persists for months).
117
+ - Same pattern works for any provider with aggressive bot detection, not just Google.
118
+
119
+ ---
120
+
121
+ ## 4. Reusing an app login (non-Google)
122
+
123
+ Goal: sign in once, by hand, and reuse it across `test-playwright`, `test-qa`, `test-red-team`,
124
+ `test-exploratory` (authed session only), and audit skills.
125
+
126
+ 1. **Check first.** Open the session on a **protected route** (`/dashboard`, not `/login`) and
127
+ `snapshot`. Already signed in? Skip the rest.
128
+ 2. **Log in like a user** in the headed window — click, type, submit. Credentials come from
129
+ `.env.test` / README; never paste secrets into chat.
130
+ 3. **Persist it** — with `--persistent --profile` you are already done. Otherwise `state-save` to
131
+ `.playwright-mcp/auth/<host>.json`.
132
+ 4. **Do not log out** at the end of a QA/audit run unless logout is the flow under test.
133
+
134
+ **Production URLs:** ask before saving auth state to disk; default to localhost/staging.
135
+
136
+ ---
137
+
138
+ ## 5. Cleanup & recovery
139
+
140
+ ```bash
141
+ $PW -s=<mine> close # end of your turn — always
142
+ $PW list # what is still running?
143
+ $PW close-all # only if you own every session
144
+ $PW kill-all # stale/zombie processes that `close` will not clear
145
+ ```
146
+
147
+ **If a session misbehaves:**
148
+
149
+ 1. `$PW list` — confirm it exists and check `user-data-dir` / headed flag.
150
+ 2. `snapshot` — see the real state before assuming.
151
+ 3. Still wedged → `close` that one session and reopen it (cheap, since profiles persist).
152
+ 4. Zombie processes after a crash → `kill-all`, then reopen.
153
+
154
+ **If auth is unexpectedly lost:** confirm you passed the same `--profile` path (a typo silently
155
+ creates a fresh in-memory session), then re-run the §4 interactive login (step 2) once.
156
+
157
+ ---
158
+
159
+ ## 6. Dual-identity exploratory sessions (`test-exploratory`)
160
+
161
+ Guest and authed must never share storage. Use three names, three browsers:
162
+
163
+ | Session | Storage | Do |
164
+ |:--------|:--------|:---|
165
+ | `-s=explore-guest` | default in-memory — **no** `--profile`, **no** `state-load` | anonymous wander |
166
+ | `-s=explore-authed` | `state-load` or dedicated `--profile` under `~/.playwright-cli-profiles/` | seeded test account |
167
+ | `-s=explore-post-logout` | fresh in-memory | prove logout cleared cookies / `localStorage` / `sessionStorage` |
168
+
169
+ `storageState` does **not** persist `sessionStorage` — inspect it in the page after logout. Never
170
+ open the guest session with a persistent profile.