@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.
- package/.claude-plugin/marketplace.json +53 -0
- package/.claude-plugin/plugin.json +40 -0
- package/.cursor-plugin/plugin.json +38 -0
- package/.mcp.json +28 -0
- package/CHANGELOG.md +1790 -0
- package/LICENSE +21 -0
- package/LICENSE-APACHE +62 -0
- package/NOTICE +13 -0
- package/README.md +821 -2
- package/SECURITY.md +55 -0
- package/agents/code-reviewer.md +60 -0
- package/agents/completion-judge.md +89 -0
- package/agents/db-migrator.md +125 -0
- package/agents/debugger.md +47 -0
- package/agents/deploy-checker.md +100 -0
- package/agents/perf-monitor.md +74 -0
- package/assets/favicon.png +0 -0
- package/assets/logo-light.png +0 -0
- package/assets/logo.png +0 -0
- package/assets/logo.svg +6 -0
- package/assets/og.png +0 -0
- package/bin/install.mjs +1127 -0
- package/bin/kenji.js +2 -0
- package/commands/adr.md +17 -0
- package/commands/aeo-plan.md +18 -0
- package/commands/arch-boundaries.md +17 -0
- package/commands/aso-plan.md +18 -0
- package/commands/auth-flows.md +19 -0
- package/commands/backup-plan.md +17 -0
- package/commands/burndown-full.md +25 -0
- package/commands/capacitor-plan.md +18 -0
- package/commands/codemod-safety.md +22 -0
- package/commands/commit.md +18 -0
- package/commands/complete-everything.md +40 -0
- package/commands/cost-plan.md +19 -0
- package/commands/deadcode-plan.md +26 -0
- package/commands/deadcode.md +32 -0
- package/commands/debug-issue.md +17 -0
- package/commands/deps-plan.md +18 -0
- package/commands/docs-plan.md +17 -0
- package/commands/doctrine.md +19 -0
- package/commands/error-plan.md +19 -0
- package/commands/feedback-to-closure.md +36 -0
- package/commands/fix-issue.md +76 -0
- package/commands/gate-logic.md +26 -0
- package/commands/green-repo.md +36 -0
- package/commands/grill-me.md +19 -0
- package/commands/gtm-plan.md +21 -0
- package/commands/gtm-weekly.md +17 -0
- package/commands/gtm.md +22 -0
- package/commands/handoff.md +15 -0
- package/commands/housekeep-backlog.md +18 -0
- package/commands/housekeep-files.md +22 -0
- package/commands/housekeep-gates.md +18 -0
- package/commands/instant-nav.md +11 -0
- package/commands/integrity-plan.md +19 -0
- package/commands/launch-kit.md +16 -0
- package/commands/mcp-guide.md +40 -0
- package/commands/mobile-plan.md +19 -0
- package/commands/native-rn-monorepo/README.md +78 -0
- package/commands/native-rn-monorepo/android-build.md +26 -0
- package/commands/native-rn-monorepo/android-install.md +32 -0
- package/commands/native-rn-monorepo/android-logcat.md +37 -0
- package/commands/native-rn-monorepo/ios-ci-logs.md +56 -0
- package/commands/native-rn-monorepo/ios-ci-status.md +52 -0
- package/commands/native-rn-monorepo/ios-ci-trigger.md +59 -0
- package/commands/native-rn-monorepo/rn-reset.md +50 -0
- package/commands/native-rn-monorepo/rn-ship-ios.md +67 -0
- package/commands/native-rn-monorepo/rn-verify.md +53 -0
- package/commands/perf-plan.md +18 -0
- package/commands/plan-mode.md +74 -0
- package/commands/pr.md +16 -0
- package/commands/pricing-plan.md +20 -0
- package/commands/privacy-plan.md +18 -0
- package/commands/readability.md +12 -0
- package/commands/readme.md +15 -0
- package/commands/refactor.md +15 -0
- package/commands/release-prep.md +17 -0
- package/commands/research.md +25 -0
- package/commands/responsive-audit.md +21 -0
- package/commands/review-code.md +18 -0
- package/commands/rls-plan.md +18 -0
- package/commands/secrets-plan.md +18 -0
- package/commands/security-plan.md +19 -0
- package/commands/ship-and-observe.md +36 -0
- package/commands/skill-conflicts.md +19 -0
- package/commands/slop-plan.md +18 -0
- package/commands/stub-plan.md +18 -0
- package/commands/test-mutation.md +16 -0
- package/commands/test-plan.md +17 -0
- package/commands/test.md +29 -0
- package/commands/thirdparty-web-interface-guidelines.md +185 -0
- package/commands/uiux-plan.md +18 -0
- package/commands/uiux.md +45 -0
- package/commands/update-deps.md +21 -0
- package/commands/validation-plan.md +19 -0
- package/commands-portable/fix-issue.md +72 -0
- package/commands-portable/plan-mode.md +92 -0
- package/commands-portable/research.md +91 -0
- package/docs/screenshots/README.md +5 -0
- package/docs/screenshots/audit-dark.png +0 -0
- package/docs/screenshots/build-dark.png +0 -0
- package/docs/screenshots/grill-dark.png +0 -0
- package/docs/screenshots/hero-dark.png +0 -0
- package/docs/screenshots/hero-light.png +0 -0
- package/docs/screenshots/ship-dark.png +0 -0
- package/docs/screenshots/src/showcase.html +320 -0
- package/hooks/completion-gate.mjs +258 -0
- package/hooks/cursor-hooks.json +13 -0
- package/hooks/hooks.json +15 -0
- package/install.sh +21 -0
- package/llms.txt +40 -0
- package/mcp/README.md +266 -0
- package/mcp/VERSIONS.md +41 -0
- package/mcp/mcp-full.json.template +124 -0
- package/mcp/mcp.json.template +29 -0
- package/mcp/pinned-versions.json +27 -0
- package/package.json +94 -4
- package/rules/approved-plan-execution.mdc +65 -0
- package/rules/full-stack-ship-discipline.mdc +37 -0
- package/rules/native-rn-monorepo/README.md +63 -0
- package/rules/native-rn-monorepo/_project.mdc +69 -0
- package/rules/native-rn-monorepo/native-android.mdc +72 -0
- package/rules/native-rn-monorepo/native-ios.mdc +61 -0
- package/rules/native-rn-monorepo/react-native-js.mdc +78 -0
- package/rules/native-rn-monorepo/web.mdc +60 -0
- package/rules/project-starter/components.mdc +54 -0
- package/rules/project-starter/data-fetching.mdc +77 -0
- package/rules/project-starter/git.mdc +41 -0
- package/rules/project-starter/supabase.mdc +37 -0
- package/rules/project-starter/tailwind.mdc +48 -0
- package/rules/project-starter/typescript.mdc +36 -0
- package/rules/project-starter/web-performance.mdc +42 -0
- package/rules/senior-engineer.mdc +30 -0
- package/rules/shell-first-search.mdc +19 -0
- package/rules/skill-workflows.mdc +35 -0
- package/rules/verification-before-completion.mdc +57 -0
- package/skills/audit-accessibility/SKILL.md +441 -0
- package/skills/audit-agent-speed/SKILL.md +181 -0
- package/skills/audit-agent-speed/scripts/stop-typecheck.mjs +151 -0
- package/skills/audit-analytics/SKILL.md +138 -0
- package/skills/audit-auth-flows/SKILL.md +267 -0
- package/skills/audit-backend-architecture/SKILL.md +266 -0
- package/skills/audit-backend-architecture/references/patterns.md +386 -0
- package/skills/audit-bundle-size/SKILL.md +295 -0
- package/skills/audit-cicd/SKILL.md +218 -0
- package/skills/audit-code-quality/SKILL.md +314 -0
- package/skills/audit-code-review/SKILL.md +289 -0
- package/skills/audit-codemod-safety/SKILL.md +159 -0
- package/skills/audit-db-schema/SKILL.md +465 -0
- package/skills/audit-db-schema/references/details.md +110 -0
- package/skills/audit-doctrine/SKILL.md +189 -0
- package/skills/audit-env-parity/SKILL.md +133 -0
- package/skills/audit-fe-api/SKILL.md +458 -0
- package/skills/audit-gate-logic/SKILL.md +219 -0
- package/skills/audit-i18n/SKILL.md +339 -0
- package/skills/audit-infra-cost/SKILL.md +142 -0
- package/skills/audit-langfuse-llm/SKILL.md +468 -0
- package/skills/audit-langfuse-llm/references/details.md +226 -0
- package/skills/audit-llm-security/SKILL.md +147 -0
- package/skills/audit-monetization-iap/SKILL.md +137 -0
- package/skills/audit-payment-system/SKILL.md +268 -0
- package/skills/audit-payment-system/references/checklist.md +283 -0
- package/skills/audit-performance/SKILL.md +383 -0
- package/skills/audit-performance/references/loading-priority-2026.md +81 -0
- package/skills/audit-realworld/SKILL.md +287 -0
- package/skills/audit-registry-listing/SKILL.md +122 -0
- package/skills/audit-resilience/SKILL.md +153 -0
- package/skills/audit-responsive/SKILL.md +221 -0
- package/skills/audit-responsive/references/checklist.md +166 -0
- package/skills/audit-security/SKILL.md +289 -0
- package/skills/audit-skill-conflicts/SKILL.md +178 -0
- package/skills/audit-ui-states/SKILL.md +146 -0
- package/skills/audit-uiux-design-system/SKILL.md +475 -0
- package/skills/audit-uiux-design-system/references/details.md +71 -0
- package/skills/audit-ux/SKILL.md +381 -0
- package/skills/audit-ux/references/details.md +245 -0
- package/skills/audit-ux-journeys/SKILL.md +215 -0
- package/skills/audit-ux-journeys/references/checklist.md +179 -0
- package/skills/backend-db-performance/SKILL.md +441 -0
- package/skills/backend-error-handling/SKILL.md +489 -0
- package/skills/backend-error-handling/references/details.md +58 -0
- package/skills/backend-observability/SKILL.md +88 -0
- package/skills/backend-patterns/SKILL.md +499 -0
- package/skills/backend-patterns/references/architecture-patterns.md +298 -0
- package/skills/backend-realtime/SKILL.md +403 -0
- package/skills/backend-realtime/references/patterns.md +74 -0
- package/skills/burndown-full/SKILL.md +174 -0
- package/skills/complete-everything/SKILL.md +295 -0
- package/skills/data-pipeline/SKILL.md +109 -0
- package/skills/data-visualization/SKILL.md +488 -0
- package/skills/debug-error/SKILL.md +322 -0
- package/skills/debug-fe-be-integration/SKILL.md +459 -0
- package/skills/debug-sentry-monitor/SKILL.md +497 -0
- package/skills/debug-sentry-monitor/references/details.md +165 -0
- package/skills/deploy-npm/SKILL.md +394 -0
- package/skills/deploy-npm/references/example-mushi-mushi.md +52 -0
- package/skills/deploy-verify/SKILL.md +489 -0
- package/skills/design-api/SKILL.md +379 -0
- package/skills/design-canvas/SKILL.md +155 -0
- package/skills/design-email/SKILL.md +370 -0
- package/skills/design-frontend/SKILL.md +143 -0
- package/skills/design-generative-art/SKILL.md +474 -0
- package/skills/design-mobile-first/SKILL.md +506 -0
- package/skills/design-motion/SKILL.md +333 -0
- package/skills/design-motion/references/delight-interactions.md +191 -0
- package/skills/design-prd/SKILL.md +443 -0
- package/skills/design-system/SKILL.md +457 -0
- package/skills/design-theme/SKILL.md +226 -0
- package/skills/design-theme/themes/tsumagoi-ranch.md +150 -0
- package/skills/docs-adr/SKILL.md +168 -0
- package/skills/docs-coauthor/SKILL.md +368 -0
- package/skills/docs-comparison-pages/SKILL.md +117 -0
- package/skills/docs-domain-modeling/SKILL.md +97 -0
- package/skills/docs-launch-kit/SKILL.md +139 -0
- package/skills/docs-writer/SKILL.md +469 -0
- package/skills/enhance-agent-guardrails/SKILL.md +164 -0
- package/skills/enhance-arch-boundaries/SKILL.md +154 -0
- package/skills/enhance-capacitor-ui/SKILL.md +463 -0
- package/skills/enhance-capacitor-ui/references/details.md +750 -0
- package/skills/enhance-email-deliverability/SKILL.md +143 -0
- package/skills/enhance-growth-loops/SKILL.md +122 -0
- package/skills/enhance-lifecycle-email/SKILL.md +130 -0
- package/skills/enhance-motion/SKILL.md +193 -0
- package/skills/enhance-onboarding/SKILL.md +148 -0
- package/skills/enhance-pwa/SKILL.md +303 -0
- package/skills/enhance-readability/SKILL.md +146 -0
- package/skills/enhance-readme/SKILL.md +496 -0
- package/skills/enhance-readme/package-lock.json +187 -0
- package/skills/enhance-readme/package.json +17 -0
- package/skills/enhance-readme/scripts/generate-readme-blocks.mjs +199 -0
- package/skills/enhance-readme/scripts/record-readme-tour.mjs +442 -0
- package/skills/enhance-skill-prompts/SKILL.md +167 -0
- package/skills/enhance-skill-prompts/references/exemplar-audit-auth-flows.md +311 -0
- package/skills/enhance-ux-laws/SKILL.md +409 -0
- package/skills/enhance-web-conversion/SKILL.md +155 -0
- package/skills/enhance-web-forms/SKILL.md +154 -0
- package/skills/enhance-web-instant-nav/SKILL.md +138 -0
- package/skills/enhance-web-instant-nav/references/bfcache-blockers.md +23 -0
- package/skills/enhance-web-instant-nav/references/early-hints.md +33 -0
- package/skills/enhance-web-instant-nav/references/speculation-rules.md +44 -0
- package/skills/enhance-web-landing/SKILL.md +459 -0
- package/skills/enhance-web-landing/references/details.md +773 -0
- package/skills/enhance-web-redesign/SKILL.md +228 -0
- package/skills/enhance-web-seo/SKILL.md +276 -0
- package/skills/enhance-web-ui/SKILL.md +473 -0
- package/skills/enhance-web-ui/references/details.md +674 -0
- package/skills/enhance-web-ux/HEURISTICS.md +248 -0
- package/skills/enhance-web-ux/PATTERNS.md +375 -0
- package/skills/enhance-web-ux/SKILL.md +464 -0
- package/skills/enhance-web-ux/examples.md +222 -0
- package/skills/enhance-web-ux/references/details.md +406 -0
- package/skills/enhance-web-web3d/SKILL.md +397 -0
- package/skills/enhance-web-web3d/references/css-canvas-effects.md +180 -0
- package/skills/handoff/SKILL.md +66 -0
- package/skills/housekeep-backlog/SKILL.md +149 -0
- package/skills/housekeep-dead-code/SKILL.md +387 -0
- package/skills/housekeep-dead-code/references/ratchet-ci.md +205 -0
- package/skills/housekeep-dead-code/references/supabase-hygiene.md +152 -0
- package/skills/housekeep-design/SKILL.md +207 -0
- package/skills/housekeep-files/SKILL.md +220 -0
- package/skills/housekeep-files/references/naming-and-catalog.md +86 -0
- package/skills/housekeep-files/scripts/housekeep-files.ps1 +360 -0
- package/skills/housekeep-files/scripts/housekeep-files.sh +238 -0
- package/skills/housekeep-gates/SKILL.md +174 -0
- package/skills/iterate-agent-harness/SKILL.md +137 -0
- package/skills/iterate-gtm-weekly/SKILL.md +103 -0
- package/skills/iterate-post-launch/SKILL.md +292 -0
- package/skills/meta-mcp-builder/SKILL.md +313 -0
- package/skills/meta-skill-creator/SKILL.md +304 -0
- package/skills/mobile-capacitor-platform/SKILL.md +103 -0
- package/skills/mobile-emulator-start/SKILL.md +296 -0
- package/skills/mobile-emulator-test/SKILL.md +491 -0
- package/skills/mobile-emulator-test/references/details.md +478 -0
- package/skills/mobile-rn-performance/SKILL.md +107 -0
- package/skills/mobile-rn-screen/SKILL.md +476 -0
- package/skills/mobile-rn-screen/references/details.md +785 -0
- package/skills/mushi-health/SKILL.md +206 -0
- package/skills/mushi-integration/SKILL.md +257 -0
- package/skills/plan-aeo-readiness/SKILL.md +166 -0
- package/skills/plan-antislop/SKILL.md +281 -0
- package/skills/plan-aso/SKILL.md +149 -0
- package/skills/plan-backup-dr/SKILL.md +131 -0
- package/skills/plan-capacitor-hardening/SKILL.md +217 -0
- package/skills/plan-data-integrity/SKILL.md +187 -0
- package/skills/plan-dead-code/SKILL.md +386 -0
- package/skills/plan-dead-code/references/knip-config.md +214 -0
- package/skills/plan-dead-code/references/output-templates.md +133 -0
- package/skills/plan-dead-code/references/preservation-contract.md +50 -0
- package/skills/plan-dead-code/references/residue-greps.md +84 -0
- package/skills/plan-dependency-provenance/SKILL.md +200 -0
- package/skills/plan-docs-sync/SKILL.md +143 -0
- package/skills/plan-docs-sync/references/drift-taxonomy.md +43 -0
- package/skills/plan-docs-sync/references/output-templates.md +33 -0
- package/skills/plan-docs-sync/references/preservation-contract.md +17 -0
- package/skills/plan-error-handling/SKILL.md +205 -0
- package/skills/plan-gtm/SKILL.md +276 -0
- package/skills/plan-gtm/references/benchmarks-2026.md +183 -0
- package/skills/plan-input-validation/SKILL.md +179 -0
- package/skills/plan-llm-cost-guardrails/SKILL.md +176 -0
- package/skills/plan-mobile-readiness/SKILL.md +171 -0
- package/skills/plan-perf-audit/SKILL.md +145 -0
- package/skills/plan-perf-audit/references/audit-scope.md +51 -0
- package/skills/plan-perf-audit/references/output-templates.md +33 -0
- package/skills/plan-perf-audit/references/preservation-contract.md +13 -0
- package/skills/plan-pricing/SKILL.md +173 -0
- package/skills/plan-privacy-compliance/SKILL.md +148 -0
- package/skills/plan-rls-audit/SKILL.md +231 -0
- package/skills/plan-secrets-audit/SKILL.md +181 -0
- package/skills/plan-security-audit/SKILL.md +168 -0
- package/skills/plan-security-audit/references/output-templates.md +36 -0
- package/skills/plan-security-audit/references/owasp-supabase-scope.md +55 -0
- package/skills/plan-security-audit/references/preservation-contract.md +18 -0
- package/skills/plan-stub-checker/SKILL.md +216 -0
- package/skills/plan-stub-checker/references/detection-methodology.md +75 -0
- package/skills/plan-stub-checker/references/detection-taxonomy.md +34 -0
- package/skills/plan-stub-checker/references/output-templates.md +63 -0
- package/skills/plan-stub-checker/references/preservation-contract.md +24 -0
- package/skills/plan-test-coverage/SKILL.md +170 -0
- package/skills/plan-test-coverage/references/methodology.md +54 -0
- package/skills/plan-test-coverage/references/output-templates.md +34 -0
- package/skills/plan-test-coverage/references/preservation-contract.md +15 -0
- package/skills/plan-uiux-unification/SKILL.md +230 -0
- package/skills/plan-uiux-unification/references/output-templates.md +67 -0
- package/skills/plan-uiux-unification/references/phase-workbook.md +85 -0
- package/skills/plan-uiux-unification/references/preservation-contract.md +24 -0
- package/skills/protocol-browser-anti-stall/SKILL.md +211 -0
- package/skills/protocol-browser-anti-stall/references/mcp-to-cli-map.md +113 -0
- package/skills/protocol-browser-anti-stall/references/playwright-session-coordination.md +170 -0
- package/skills/research/SKILL.md +422 -0
- package/skills/test-exploratory/SKILL.md +165 -0
- package/skills/test-exploratory/references/charter-template.md +29 -0
- package/skills/test-load/SKILL.md +126 -0
- package/skills/test-mutation/SKILL.md +160 -0
- package/skills/test-playwright/SKILL.md +354 -0
- package/skills/test-qa/SKILL.md +364 -0
- package/skills/test-qa/references/details.md +268 -0
- package/skills/test-red-team/SKILL.md +386 -0
- package/skills/test-red-team/references/owasp-attack-checklist.md +193 -0
- package/skills/test-unit/SKILL.md +259 -0
- package/skills/test-unit/references/details.md +267 -0
- package/skills/test-visual-regression/SKILL.md +132 -0
- package/skills/thirdparty-emil-design-eng/ATTRIBUTION.md +20 -0
- package/skills/thirdparty-emil-design-eng/SKILL.md +21 -0
- package/skills/thirdparty-emil-design-eng/references/emil-design-eng.md +676 -0
- package/skills/thirdparty-ui-ux-pro-max/ATTRIBUTION.md +22 -0
- package/skills/thirdparty-ui-ux-pro-max/SKILL.md +304 -0
- package/skills/thirdparty-ui-ux-pro-max/data/charts.csv +26 -0
- package/skills/thirdparty-ui-ux-pro-max/data/colors.csv +97 -0
- package/skills/thirdparty-ui-ux-pro-max/data/icons.csv +101 -0
- package/skills/thirdparty-ui-ux-pro-max/data/landing.csv +31 -0
- package/skills/thirdparty-ui-ux-pro-max/data/products.csv +97 -0
- package/skills/thirdparty-ui-ux-pro-max/data/react-performance.csv +45 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/astro.csv +54 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/flutter.csv +53 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/html-tailwind.csv +56 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/jetpack-compose.csv +53 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/nextjs.csv +53 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/nuxt-ui.csv +51 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/nuxtjs.csv +59 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/react-native.csv +52 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/react.csv +54 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/shadcn.csv +61 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/svelte.csv +54 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/swiftui.csv +51 -0
- package/skills/thirdparty-ui-ux-pro-max/data/stacks/vue.csv +50 -0
- package/skills/thirdparty-ui-ux-pro-max/data/styles.csv +68 -0
- package/skills/thirdparty-ui-ux-pro-max/data/typography.csv +58 -0
- package/skills/thirdparty-ui-ux-pro-max/data/ui-reasoning.csv +101 -0
- package/skills/thirdparty-ui-ux-pro-max/data/ux-guidelines.csv +100 -0
- package/skills/thirdparty-ui-ux-pro-max/data/web-interface.csv +31 -0
- package/skills/thirdparty-ui-ux-pro-max/scripts/core.py +253 -0
- package/skills/thirdparty-ui-ux-pro-max/scripts/design_system.py +1067 -0
- package/skills/thirdparty-ui-ux-pro-max/scripts/search.py +114 -0
- package/skills/thirdparty-web-interface-guidelines/ATTRIBUTION.md +23 -0
- package/skills/thirdparty-web-interface-guidelines/SKILL.md +190 -0
- package/skills/workflow-build-feature/SKILL.md +118 -0
- package/skills/workflow-coding-discipline/SKILL.md +140 -0
- package/skills/workflow-environment-ready/SKILL.md +128 -0
- package/skills/workflow-feature-flag/SKILL.md +262 -0
- package/skills/workflow-feedback-to-closure/SKILL.md +165 -0
- package/skills/workflow-fix-and-ship/SKILL.md +136 -0
- package/skills/workflow-git-commit/SKILL.md +200 -0
- package/skills/workflow-green-repo/SKILL.md +166 -0
- package/skills/workflow-grilling/SKILL.md +73 -0
- package/skills/workflow-gtm/SKILL.md +153 -0
- package/skills/workflow-housekeep/SKILL.md +453 -0
- package/skills/workflow-housekeep/references/templates.md +109 -0
- package/skills/workflow-launch-ready/SKILL.md +145 -0
- package/skills/workflow-merge-conflicts/SKILL.md +62 -0
- package/skills/workflow-onboard/SKILL.md +99 -0
- package/skills/workflow-parallel-agents/SKILL.md +164 -0
- package/skills/workflow-pr/SKILL.md +197 -0
- package/skills/workflow-quality-gate/SKILL.md +147 -0
- package/skills/workflow-refactor/SKILL.md +274 -0
- package/skills/workflow-release-prep/SKILL.md +207 -0
- package/skills/workflow-ship-and-observe/SKILL.md +164 -0
- package/skills/workflow-spec-tdd/SKILL.md +141 -0
- package/skills/workflow-spec-tdd/references/spec-template.md +126 -0
- package/skills/workflow-spec-tdd/references/tdd-patterns.md +167 -0
- package/skills-cursor/babysit/SKILL.md +17 -0
- package/skills-cursor/canvas/SKILL.md +142 -0
- package/skills-cursor/canvas/sdk/canvas-tokens.d.ts +235 -0
- package/skills-cursor/canvas/sdk/chart-primitives.d.ts +200 -0
- package/skills-cursor/canvas/sdk/dag-layout.d.ts +102 -0
- package/skills-cursor/canvas/sdk/diff-view.d.ts +130 -0
- package/skills-cursor/canvas/sdk/form-primitives.d.ts +194 -0
- package/skills-cursor/canvas/sdk/hooks.d.ts +117 -0
- package/skills-cursor/canvas/sdk/index.d.ts +47 -0
- package/skills-cursor/canvas/sdk/theme.d.ts +61 -0
- package/skills-cursor/canvas/sdk/todo-list.d.ts +49 -0
- package/skills-cursor/canvas/sdk/ui-primitives.d.ts +549 -0
- package/skills-cursor/canvas/sdk/ui-primitives.test.d.ts +2 -0
- package/skills-cursor/create-hook/SKILL.md +238 -0
- package/skills-cursor/create-rule/SKILL.md +185 -0
- package/skills-cursor/create-skill/SKILL.md +269 -0
- package/skills-cursor/create-skill/references/authoring-guide.md +182 -0
- package/skills-cursor/create-subagent/SKILL.md +228 -0
- package/skills-cursor/migrate-to-skills/SKILL.md +121 -0
- package/skills-cursor/shell/SKILL.md +22 -0
- package/skills-cursor/split-to-prs/SKILL.md +47 -0
- package/skills-cursor/statusline/SKILL.md +193 -0
- package/skills-cursor/update-cli-config/SKILL.md +85 -0
- package/skills-cursor/update-cursor-settings/SKILL.md +137 -0
- 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.
|