@zenrick/zenkit 0.0.0-stage → 0.5.1

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 (355) hide show
  1. package/.claude-plugin/marketplace.json +19 -0
  2. package/.cursor-plugin/marketplace.json +22 -0
  3. package/INSTALL.md +73 -0
  4. package/LICENSE +202 -0
  5. package/NOTICE +5 -0
  6. package/README.md +69 -3
  7. package/TERMS.md +48 -0
  8. package/THIRD-PARTY-NOTICES.md +109 -0
  9. package/kit/agents/backend-specialist.md +263 -0
  10. package/kit/agents/code-archaeologist.md +106 -0
  11. package/kit/agents/database-architect.md +226 -0
  12. package/kit/agents/debugger.md +226 -0
  13. package/kit/agents/devops-engineer.md +242 -0
  14. package/kit/agents/documentation-writer.md +104 -0
  15. package/kit/agents/explorer-agent.md +73 -0
  16. package/kit/agents/frontend-specialist.md +593 -0
  17. package/kit/agents/game-developer.md +162 -0
  18. package/kit/agents/mobile-developer.md +377 -0
  19. package/kit/agents/orchestrator.md +489 -0
  20. package/kit/agents/penetration-tester.md +188 -0
  21. package/kit/agents/performance-optimizer.md +187 -0
  22. package/kit/agents/product-manager.md +112 -0
  23. package/kit/agents/product-owner.md +95 -0
  24. package/kit/agents/project-planner.md +409 -0
  25. package/kit/agents/qa-automation-engineer.md +103 -0
  26. package/kit/agents/security-auditor.md +170 -0
  27. package/kit/agents/seo-specialist.md +111 -0
  28. package/kit/agents/test-engineer.md +158 -0
  29. package/kit/bundles/agent-building.yaml +26 -0
  30. package/kit/bundles/backend-data.yaml +14 -0
  31. package/kit/bundles/base.yaml +10 -0
  32. package/kit/bundles/core.yaml +21 -0
  33. package/kit/bundles/kit-engenharia.yaml +8 -0
  34. package/kit/bundles/kit-lite.yaml +9 -0
  35. package/kit/bundles/security.yaml +11 -0
  36. package/kit/bundles/ship-run.yaml +16 -0
  37. package/kit/bundles/web-ui.yaml +18 -0
  38. package/kit/commands/docs.md +33 -0
  39. package/kit/commands/explain.md +41 -0
  40. package/kit/commands/fix.md +65 -0
  41. package/kit/commands/implement.md +35 -0
  42. package/kit/commands/refactor.md +59 -0
  43. package/kit/commands/review.md +55 -0
  44. package/kit/commands/test.md +63 -0
  45. package/kit/modules/bridge/rules/cross-ide-bridge.mdc +73 -0
  46. package/kit/modules/bridge/zenkit-layer.yaml +1 -0
  47. package/kit/modules/nexuscore/sections/convivencia.md +12 -0
  48. package/kit/modules/nexuscore/sections/memoria.md +9 -0
  49. package/kit/modules/nexuscore/skills/quadro-agentes/SKILL.md +186 -0
  50. package/kit/modules/nexuscore/zenkit-layer.yaml +1 -0
  51. package/kit/rules/ZENKIT.mdc +294 -0
  52. package/kit/rules/git.mdc +51 -0
  53. package/kit/rules/karpathy-guidelines.mdc +70 -0
  54. package/kit/rules/model-routing.mdc +89 -0
  55. package/kit/rules/security-headers.mdc +41 -0
  56. package/kit/rules/social-automation.mdc +69 -0
  57. package/kit/rules/toc.mdc +40 -0
  58. package/kit/skills/api-patterns/SKILL.md +95 -0
  59. package/kit/skills/api-patterns/api-style.md +42 -0
  60. package/kit/skills/api-patterns/auth.md +24 -0
  61. package/kit/skills/api-patterns/documentation.md +26 -0
  62. package/kit/skills/api-patterns/graphql.md +41 -0
  63. package/kit/skills/api-patterns/rate-limiting.md +31 -0
  64. package/kit/skills/api-patterns/references/backend/backend-api-design.md +495 -0
  65. package/kit/skills/api-patterns/references/backend/backend-architecture.md +454 -0
  66. package/kit/skills/api-patterns/references/backend/backend-authentication.md +338 -0
  67. package/kit/skills/api-patterns/references/backend/backend-code-quality.md +659 -0
  68. package/kit/skills/api-patterns/references/backend/backend-debugging.md +904 -0
  69. package/kit/skills/api-patterns/references/backend/backend-devops.md +494 -0
  70. package/kit/skills/api-patterns/references/backend/backend-mindset.md +387 -0
  71. package/kit/skills/api-patterns/references/backend/backend-performance.md +397 -0
  72. package/kit/skills/api-patterns/references/backend/backend-security.md +290 -0
  73. package/kit/skills/api-patterns/references/backend/backend-technologies.md +256 -0
  74. package/kit/skills/api-patterns/references/backend/backend-testing.md +429 -0
  75. package/kit/skills/api-patterns/response.md +37 -0
  76. package/kit/skills/api-patterns/rest.md +40 -0
  77. package/kit/skills/api-patterns/scripts/api_validator.py +211 -0
  78. package/kit/skills/api-patterns/security-testing.md +122 -0
  79. package/kit/skills/api-patterns/trpc.md +41 -0
  80. package/kit/skills/api-patterns/versioning.md +22 -0
  81. package/kit/skills/app-builder/SKILL.md +76 -0
  82. package/kit/skills/app-builder/agent-coordination.md +71 -0
  83. package/kit/skills/app-builder/feature-building.md +53 -0
  84. package/kit/skills/app-builder/project-detection.md +34 -0
  85. package/kit/skills/app-builder/scaffolding.md +118 -0
  86. package/kit/skills/app-builder/tech-stack.md +41 -0
  87. package/kit/skills/app-builder/templates/SKILL.md +39 -0
  88. package/kit/skills/app-builder/templates/astro-static/TEMPLATE.md +76 -0
  89. package/kit/skills/app-builder/templates/chrome-extension/TEMPLATE.md +92 -0
  90. package/kit/skills/app-builder/templates/cli-tool/TEMPLATE.md +88 -0
  91. package/kit/skills/app-builder/templates/electron-desktop/TEMPLATE.md +88 -0
  92. package/kit/skills/app-builder/templates/express-api/TEMPLATE.md +83 -0
  93. package/kit/skills/app-builder/templates/flutter-app/TEMPLATE.md +90 -0
  94. package/kit/skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md +90 -0
  95. package/kit/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +122 -0
  96. package/kit/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +122 -0
  97. package/kit/skills/app-builder/templates/nextjs-static/TEMPLATE.md +169 -0
  98. package/kit/skills/app-builder/templates/nuxt-app/TEMPLATE.md +134 -0
  99. package/kit/skills/app-builder/templates/python-fastapi/TEMPLATE.md +83 -0
  100. package/kit/skills/app-builder/templates/react-native-app/TEMPLATE.md +119 -0
  101. package/kit/skills/architecture/SKILL.md +56 -0
  102. package/kit/skills/architecture/context-discovery.md +43 -0
  103. package/kit/skills/architecture/examples.md +94 -0
  104. package/kit/skills/architecture/pattern-selection.md +68 -0
  105. package/kit/skills/architecture/patterns-reference.md +50 -0
  106. package/kit/skills/architecture/trade-off-analysis.md +77 -0
  107. package/kit/skills/bash-linux/SKILL.md +203 -0
  108. package/kit/skills/batch-operations/SKILL.md +112 -0
  109. package/kit/skills/behavioral-modes/SKILL.md +255 -0
  110. package/kit/skills/brainstorming/SKILL.md +189 -0
  111. package/kit/skills/brainstorming/dynamic-questioning.md +350 -0
  112. package/kit/skills/brainstorming/references/problem-solving/attribution.md +69 -0
  113. package/kit/skills/brainstorming/references/problem-solving/collision-zone-thinking.md +79 -0
  114. package/kit/skills/brainstorming/references/problem-solving/inversion-exercise.md +91 -0
  115. package/kit/skills/brainstorming/references/problem-solving/meta-pattern-recognition.md +87 -0
  116. package/kit/skills/brainstorming/references/problem-solving/scale-game.md +95 -0
  117. package/kit/skills/brainstorming/references/problem-solving/simplification-cascades.md +80 -0
  118. package/kit/skills/brainstorming/references/problem-solving/when-stuck.md +72 -0
  119. package/kit/skills/claude-exec/SKILL.md +185 -0
  120. package/kit/skills/clean-code/SKILL.md +210 -0
  121. package/kit/skills/code-review-checklist/SKILL.md +115 -0
  122. package/kit/skills/code-review-graph/SKILL.md +50 -0
  123. package/kit/skills/code-review-graph/references/alternatives-comparison.md +12 -0
  124. package/kit/skills/code-review-graph/references/best-practices.md +9 -0
  125. package/kit/skills/code-review-graph/references/configuration.md +43 -0
  126. package/kit/skills/code-review-graph/references/core-workflows.md +61 -0
  127. package/kit/skills/code-review-graph/references/how-it-works-4-layers.md +20 -0
  128. package/kit/skills/code-review-graph/references/installation.md +67 -0
  129. package/kit/skills/code-review-graph/references/integration-with-zenkit.md +23 -0
  130. package/kit/skills/code-review-graph/references/known-limitations.md +13 -0
  131. package/kit/skills/code-review-graph/references/when-to-use-vs-when-to-skip.md +21 -0
  132. package/kit/skills/codex-exec/SKILL.md +161 -0
  133. package/kit/skills/context-compression/SKILL.md +145 -0
  134. package/kit/skills/coordinator-mode/SKILL.md +215 -0
  135. package/kit/skills/cursor-exec/SKILL.md +152 -0
  136. package/kit/skills/database-design/SKILL.md +53 -0
  137. package/kit/skills/database-design/database-selection.md +43 -0
  138. package/kit/skills/database-design/indexing.md +39 -0
  139. package/kit/skills/database-design/migrations.md +48 -0
  140. package/kit/skills/database-design/optimization.md +36 -0
  141. package/kit/skills/database-design/orm-selection.md +30 -0
  142. package/kit/skills/database-design/schema-design.md +56 -0
  143. package/kit/skills/database-design/scripts/schema_validator.py +172 -0
  144. package/kit/skills/deployment-procedures/SKILL.md +242 -0
  145. package/kit/skills/deprecation-and-migration/SKILL.md +149 -0
  146. package/kit/skills/documentation-templates/SKILL.md +195 -0
  147. package/kit/skills/entrega-com-agentes/SKILL.md +177 -0
  148. package/kit/skills/frontend-design/NOTICE.md +6 -0
  149. package/kit/skills/frontend-design/SKILL.md +456 -0
  150. package/kit/skills/frontend-design/animation-guide.md +331 -0
  151. package/kit/skills/frontend-design/color-system.md +311 -0
  152. package/kit/skills/frontend-design/decision-trees.md +418 -0
  153. package/kit/skills/frontend-design/motion-graphics.md +306 -0
  154. package/kit/skills/frontend-design/references/aesthetic/design-guideline-template.md +163 -0
  155. package/kit/skills/frontend-design/references/aesthetic/design-principles.md +62 -0
  156. package/kit/skills/frontend-design/references/aesthetic/design-resources.md +75 -0
  157. package/kit/skills/frontend-design/references/aesthetic/design-story-template.md +135 -0
  158. package/kit/skills/frontend-design/references/aesthetic/micro-interactions.md +53 -0
  159. package/kit/skills/frontend-design/references/aesthetic/storytelling-design.md +50 -0
  160. package/kit/skills/frontend-design/scripts/accessibility_checker.py +183 -0
  161. package/kit/skills/frontend-design/scripts/ux_audit.py +722 -0
  162. package/kit/skills/frontend-design/typography-system.md +345 -0
  163. package/kit/skills/frontend-design/ux-psychology.md +1116 -0
  164. package/kit/skills/frontend-design/visual-effects.md +383 -0
  165. package/kit/skills/game-development/2d-games/SKILL.md +119 -0
  166. package/kit/skills/game-development/3d-games/SKILL.md +135 -0
  167. package/kit/skills/game-development/SKILL.md +168 -0
  168. package/kit/skills/game-development/game-art/SKILL.md +185 -0
  169. package/kit/skills/game-development/game-audio/SKILL.md +190 -0
  170. package/kit/skills/game-development/game-design/SKILL.md +129 -0
  171. package/kit/skills/game-development/mobile-games/SKILL.md +108 -0
  172. package/kit/skills/game-development/multiplayer/SKILL.md +132 -0
  173. package/kit/skills/game-development/pc-games/SKILL.md +144 -0
  174. package/kit/skills/game-development/vr-ar/SKILL.md +123 -0
  175. package/kit/skills/game-development/web-games/SKILL.md +150 -0
  176. package/kit/skills/gemini-exec/SKILL.md +80 -0
  177. package/kit/skills/geo-fundamentals/SKILL.md +157 -0
  178. package/kit/skills/geo-fundamentals/scripts/geo_checker.py +289 -0
  179. package/kit/skills/git-worktrees/SKILL.md +107 -0
  180. package/kit/skills/i18n-localization/SKILL.md +145 -0
  181. package/kit/skills/i18n-localization/scripts/i18n_checker.py +241 -0
  182. package/kit/skills/intelligent-routing/SKILL.md +128 -0
  183. package/kit/skills/intelligent-routing/references/4-response-format.md +16 -0
  184. package/kit/skills/intelligent-routing/references/complexity-assessment.md +29 -0
  185. package/kit/skills/intelligent-routing/references/debug-intelligent-routing.md +9 -0
  186. package/kit/skills/intelligent-routing/references/debugging-agent-selection.md +7 -0
  187. package/kit/skills/intelligent-routing/references/domain-detection-rules.md +29 -0
  188. package/kit/skills/intelligent-routing/references/edge-cases.md +29 -0
  189. package/kit/skills/intelligent-routing/references/implementation-rules.md +35 -0
  190. package/kit/skills/intelligent-routing/references/integration-with-existing-workflows.md +21 -0
  191. package/kit/skills/intelligent-routing/references/performance-considerations.md +14 -0
  192. package/kit/skills/intelligent-routing/references/summary.md +16 -0
  193. package/kit/skills/intelligent-routing/references/testing-the-system.md +36 -0
  194. package/kit/skills/intelligent-routing/references/tier-0-automatic-analysis-always-active.md +27 -0
  195. package/kit/skills/intelligent-routing/references/user-education.md +12 -0
  196. package/kit/skills/karpathy-guidelines/SKILL.md +67 -0
  197. package/kit/skills/karpathy-guidelines/references/EXAMPLES.md +522 -0
  198. package/kit/skills/lint-and-validate/SKILL.md +46 -0
  199. package/kit/skills/lint-and-validate/scripts/lint_runner.py +184 -0
  200. package/kit/skills/lint-and-validate/scripts/type_coverage.py +173 -0
  201. package/kit/skills/mcp-atuacao/SKILL.md +238 -0
  202. package/kit/skills/mcp-builder/NOTICE.md +6 -0
  203. package/kit/skills/mcp-builder/SKILL.md +259 -0
  204. package/kit/skills/memory-system/SKILL.md +181 -0
  205. package/kit/skills/mobile-design/SKILL.md +395 -0
  206. package/kit/skills/mobile-design/decision-trees.md +516 -0
  207. package/kit/skills/mobile-design/mobile-backend.md +491 -0
  208. package/kit/skills/mobile-design/mobile-color-system.md +420 -0
  209. package/kit/skills/mobile-design/mobile-debugging.md +122 -0
  210. package/kit/skills/mobile-design/mobile-design-thinking.md +357 -0
  211. package/kit/skills/mobile-design/mobile-navigation.md +458 -0
  212. package/kit/skills/mobile-design/mobile-performance.md +767 -0
  213. package/kit/skills/mobile-design/mobile-testing.md +356 -0
  214. package/kit/skills/mobile-design/mobile-typography.md +433 -0
  215. package/kit/skills/mobile-design/platform-android.md +666 -0
  216. package/kit/skills/mobile-design/platform-ios.md +561 -0
  217. package/kit/skills/mobile-design/scripts/mobile_audit.py +670 -0
  218. package/kit/skills/mobile-design/touch-psychology.md +537 -0
  219. package/kit/skills/negocio-agente-conversa/SKILL.md +168 -0
  220. package/kit/skills/negocio-atendimento/SKILL.md +134 -0
  221. package/kit/skills/negocio-linguagem/SKILL.md +166 -0
  222. package/kit/skills/negocio-preco/SKILL.md +174 -0
  223. package/kit/skills/negocio-preco/scripts/preco.mjs +160 -0
  224. package/kit/skills/negocio-qualificacao/SKILL.md +140 -0
  225. package/kit/skills/nextjs-react-expert/1-async-eliminating-waterfalls.md +351 -0
  226. package/kit/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md +240 -0
  227. package/kit/skills/nextjs-react-expert/3-server-server-side-performance.md +490 -0
  228. package/kit/skills/nextjs-react-expert/4-client-client-side-data-fetching.md +264 -0
  229. package/kit/skills/nextjs-react-expert/5-rerender-re-render-optimization.md +581 -0
  230. package/kit/skills/nextjs-react-expert/6-rendering-rendering-performance.md +432 -0
  231. package/kit/skills/nextjs-react-expert/7-js-javascript-performance.md +684 -0
  232. package/kit/skills/nextjs-react-expert/8-advanced-advanced-patterns.md +150 -0
  233. package/kit/skills/nextjs-react-expert/9-cache-components.md +103 -0
  234. package/kit/skills/nextjs-react-expert/SKILL.md +308 -0
  235. package/kit/skills/nextjs-react-expert/resources/app-patterns/common-patterns.md +331 -0
  236. package/kit/skills/nextjs-react-expert/resources/app-patterns/complete-examples.md +872 -0
  237. package/kit/skills/nextjs-react-expert/resources/app-patterns/component-patterns.md +502 -0
  238. package/kit/skills/nextjs-react-expert/resources/app-patterns/data-fetching.md +767 -0
  239. package/kit/skills/nextjs-react-expert/resources/app-patterns/file-organization.md +502 -0
  240. package/kit/skills/nextjs-react-expert/resources/app-patterns/loading-and-error-states.md +501 -0
  241. package/kit/skills/nextjs-react-expert/resources/app-patterns/performance.md +406 -0
  242. package/kit/skills/nextjs-react-expert/resources/app-patterns/routing-guide.md +364 -0
  243. package/kit/skills/nextjs-react-expert/resources/app-patterns/styling-guide.md +428 -0
  244. package/kit/skills/nextjs-react-expert/resources/app-patterns/typescript-standards.md +418 -0
  245. package/kit/skills/nextjs-react-expert/scripts/convert_rules.py +222 -0
  246. package/kit/skills/nextjs-react-expert/scripts/react_performance_checker.py +252 -0
  247. package/kit/skills/nodejs-best-practices/SKILL.md +78 -0
  248. package/kit/skills/nodejs-best-practices/references/10-anti-patterns-to-avoid.md +21 -0
  249. package/kit/skills/nodejs-best-practices/references/11-decision-checklist.md +14 -0
  250. package/kit/skills/nodejs-best-practices/references/2-runtime-considerations-2025.md +36 -0
  251. package/kit/skills/nodejs-best-practices/references/3-architecture-principles.md +35 -0
  252. package/kit/skills/nodejs-best-practices/references/4-error-handling-principles.md +42 -0
  253. package/kit/skills/nodejs-best-practices/references/5-async-patterns-principles.md +35 -0
  254. package/kit/skills/nodejs-best-practices/references/6-validation-principles.md +29 -0
  255. package/kit/skills/nodejs-best-practices/references/7-security-principles.md +29 -0
  256. package/kit/skills/nodejs-best-practices/references/8-testing-principles.md +28 -0
  257. package/kit/skills/observability-and-instrumentation/SKILL.md +150 -0
  258. package/kit/skills/opencode-go-exec/SKILL.md +101 -0
  259. package/kit/skills/parallel-agents/SKILL.md +184 -0
  260. package/kit/skills/performance-profiling/SKILL.md +145 -0
  261. package/kit/skills/performance-profiling/scripts/lighthouse_audit.py +76 -0
  262. package/kit/skills/plan-writing/SKILL.md +213 -0
  263. package/kit/skills/powershell-windows/SKILL.md +196 -0
  264. package/kit/skills/provider-orchestration/SKILL.md +269 -0
  265. package/kit/skills/python-patterns/SKILL.md +80 -0
  266. package/kit/skills/python-patterns/references/10-decision-checklist.md +14 -0
  267. package/kit/skills/python-patterns/references/11-anti-patterns-to-avoid.md +20 -0
  268. package/kit/skills/python-patterns/references/2-async-vs-sync-decision.md +44 -0
  269. package/kit/skills/python-patterns/references/3-type-hints-strategy.md +56 -0
  270. package/kit/skills/python-patterns/references/4-project-structure-principles.md +56 -0
  271. package/kit/skills/python-patterns/references/5-django-principles-2025.md +40 -0
  272. package/kit/skills/python-patterns/references/6-fastapi-principles.md +50 -0
  273. package/kit/skills/python-patterns/references/7-background-tasks.md +31 -0
  274. package/kit/skills/python-patterns/references/8-error-handling-principles.md +29 -0
  275. package/kit/skills/python-patterns/references/9-testing-principles.md +37 -0
  276. package/kit/skills/red-team-tactics/SKILL.md +201 -0
  277. package/kit/skills/research/SKILL.md +166 -0
  278. package/kit/skills/rust-pro/SKILL.md +177 -0
  279. package/kit/skills/seo-fundamentals/SKILL.md +130 -0
  280. package/kit/skills/seo-fundamentals/scripts/seo_checker.py +219 -0
  281. package/kit/skills/sequential-thinking/.env.example +8 -0
  282. package/kit/skills/sequential-thinking/README.md +183 -0
  283. package/kit/skills/sequential-thinking/SKILL.md +95 -0
  284. package/kit/skills/sequential-thinking/package.json +31 -0
  285. package/kit/skills/sequential-thinking/references/advanced-strategies.md +79 -0
  286. package/kit/skills/sequential-thinking/references/advanced-techniques.md +76 -0
  287. package/kit/skills/sequential-thinking/references/core-patterns.md +95 -0
  288. package/kit/skills/sequential-thinking/references/examples-api.md +88 -0
  289. package/kit/skills/sequential-thinking/references/examples-architecture.md +94 -0
  290. package/kit/skills/sequential-thinking/references/examples-debug.md +90 -0
  291. package/kit/skills/sequential-thinking/scripts/format-thought.js +159 -0
  292. package/kit/skills/sequential-thinking/scripts/process-thought.js +236 -0
  293. package/kit/skills/server-management/SKILL.md +162 -0
  294. package/kit/skills/simplify-code/SKILL.md +133 -0
  295. package/kit/skills/skillify/SKILL.md +116 -0
  296. package/kit/skills/system-design-interview/SKILL.md +268 -0
  297. package/kit/skills/systematic-debugging/SKILL.md +110 -0
  298. package/kit/skills/tailwind-patterns/SKILL.md +283 -0
  299. package/kit/skills/tailwind-patterns/references/shadcn-ui/canvas-design-system.md +320 -0
  300. package/kit/skills/tailwind-patterns/references/shadcn-ui/shadcn-accessibility.md +471 -0
  301. package/kit/skills/tailwind-patterns/references/shadcn-ui/shadcn-components.md +424 -0
  302. package/kit/skills/tailwind-patterns/references/shadcn-ui/shadcn-theming.md +373 -0
  303. package/kit/skills/tailwind-patterns/references/shadcn-ui/tailwind-customization.md +483 -0
  304. package/kit/skills/tailwind-patterns/references/shadcn-ui/tailwind-responsive.md +382 -0
  305. package/kit/skills/tailwind-patterns/references/shadcn-ui/tailwind-utilities.md +455 -0
  306. package/kit/skills/tdd-workflow/SKILL.md +150 -0
  307. package/kit/skills/testing-patterns/SKILL.md +196 -0
  308. package/kit/skills/testing-patterns/scripts/test_runner.py +219 -0
  309. package/kit/skills/ui-ux-pro-max/SKILL.md +135 -0
  310. package/kit/skills/verify-changes/SKILL.md +125 -0
  311. package/kit/skills/vulnerability-scanner/SKILL.md +278 -0
  312. package/kit/skills/vulnerability-scanner/checklists.md +121 -0
  313. package/kit/skills/vulnerability-scanner/scripts/security_scan.py +458 -0
  314. package/kit/skills/web-design-guidelines/SKILL.md +58 -0
  315. package/kit/skills/webapp-testing/NOTICE.md +6 -0
  316. package/kit/skills/webapp-testing/SKILL.md +188 -0
  317. package/kit/skills/webapp-testing/scripts/playwright_runner.py +173 -0
  318. package/kit/workflows/brainstorm.md +113 -0
  319. package/kit/workflows/coordinate.md +72 -0
  320. package/kit/workflows/create.md +59 -0
  321. package/kit/workflows/debug.md +103 -0
  322. package/kit/workflows/deploy.md +176 -0
  323. package/kit/workflows/enhance.md +63 -0
  324. package/kit/workflows/orchestrate.md +237 -0
  325. package/kit/workflows/plan.md +89 -0
  326. package/kit/workflows/preview.md +81 -0
  327. package/kit/workflows/remember.md +67 -0
  328. package/kit/workflows/status.md +86 -0
  329. package/kit/workflows/test.md +144 -0
  330. package/kit/workflows/ui-ux-pro-max.md +296 -0
  331. package/kit/workflows/verify.md +72 -0
  332. package/licenses/Apache-2.0.txt +202 -0
  333. package/package.json +60 -6
  334. package/scripts/archive-codex-rollouts.ps1 +35 -0
  335. package/scripts/avaliar-vigilancia-mandato.mjs +38 -0
  336. package/scripts/bundle.mjs +170 -0
  337. package/scripts/check-deps.mjs +178 -0
  338. package/scripts/check-models.mjs +150 -0
  339. package/scripts/cli.mjs +313 -0
  340. package/scripts/content-checks.mjs +18 -0
  341. package/scripts/continuidade-mandato.mjs +47 -0
  342. package/scripts/discriminar-turno.mjs +191 -0
  343. package/scripts/doctor.mjs +611 -0
  344. package/scripts/generate.mjs +688 -0
  345. package/scripts/install.mjs +11 -0
  346. package/scripts/layer-remote.mjs +407 -0
  347. package/scripts/layers.mjs +208 -0
  348. package/scripts/marketplace.mjs +77 -0
  349. package/scripts/product.mjs +32 -0
  350. package/scripts/ruleset-core.mjs +68 -0
  351. package/scripts/social-hooks.mjs +293 -0
  352. package/scripts/social-pacer.mjs +219 -0
  353. package/scripts/validate-bundles.mjs +14 -0
  354. package/scripts/validate-skills.mjs +174 -0
  355. package/scripts/zenkit-daemon-task.cmd +3 -0
@@ -0,0 +1,213 @@
1
+ ---
2
+ name: plan-writing
3
+ description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
4
+ when_to_use: "When creating structured task plans, breaking down features into tasks, or defining verification criteria. Use with /plan workflow."
5
+ allowed-tools: Read, Glob, Grep
6
+ ---
7
+
8
+ # Plan Writing
9
+
10
+ > Source: obra/superpowers
11
+
12
+ ## Overview
13
+ This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
14
+
15
+ ## Task Breakdown Principles
16
+
17
+ ### 1. Small, Focused Tasks
18
+ - Each task should take 2-5 minutes
19
+ - One clear outcome per task
20
+ - Independently verifiable
21
+
22
+ ### 2. Clear Verification
23
+ - How do you know it's done?
24
+ - What can you check/test?
25
+ - What's the expected output?
26
+
27
+ ### 3. Logical Ordering
28
+ - Dependencies identified
29
+ - Parallel work where possible
30
+ - Critical path highlighted
31
+ - **Phase X: Verification is always LAST**
32
+
33
+ ### 4. Dynamic Naming in Project Root
34
+ - Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
35
+ - Name derived from task (e.g., "add auth" → `auth-feature.md`)
36
+ - **NEVER** inside `.claude/`, `docs/`, or temp folders
37
+
38
+ ## Planning Principles (NOT Templates!)
39
+
40
+ > 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
41
+
42
+ ### Principle 1: Keep It SHORT
43
+
44
+ | ❌ Wrong | ✅ Right |
45
+ |----------|----------|
46
+ | 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
47
+ | Every micro-step listed | Only actionable items |
48
+ | Verbose descriptions | One-line per task |
49
+
50
+ > **Rule:** If plan is longer than 1 page, it's too long. Simplify.
51
+
52
+ ---
53
+
54
+ ### Principle 2: Be SPECIFIC, Not Generic
55
+
56
+ | ❌ Wrong | ✅ Right |
57
+ |----------|----------|
58
+ | "Set up project" | "Run `npx create-next-app`" |
59
+ | "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
60
+ | "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
61
+
62
+ > **Rule:** Each task should have a clear, verifiable outcome.
63
+
64
+ ---
65
+
66
+ ### Principle 3: Dynamic Content Based on Project Type
67
+
68
+ **For NEW PROJECT:**
69
+ - What tech stack? (decide first)
70
+ - What's the MVP? (minimal features)
71
+ - What's the file structure?
72
+
73
+ **For FEATURE ADDITION:**
74
+ - Which files are affected?
75
+ - What dependencies needed?
76
+ - How to verify it works?
77
+
78
+ **For BUG FIX:**
79
+ - What's the root cause?
80
+ - What file/line to change?
81
+ - How to test the fix?
82
+
83
+ ---
84
+
85
+ ### Principle 4: Scripts Are Project-Specific
86
+
87
+ > 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
88
+
89
+ | Project Type | Relevant Scripts |
90
+ |--------------|------------------|
91
+ | Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
92
+ | Backend/API | `api_validator.py`, `security_scan.py` |
93
+ | Mobile | `mobile_audit.py` |
94
+ | Database | `schema_validator.py` |
95
+ | Full-stack | Mix of above based on what you touched |
96
+
97
+ **Wrong:** Adding all scripts to every plan
98
+ **Right:** Only scripts relevant to THIS task
99
+
100
+ ---
101
+
102
+ ### Principle 5: Verification is Simple
103
+
104
+ | ❌ Wrong | ✅ Right |
105
+ |----------|----------|
106
+ | "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
107
+ | "Test the API" | "curl localhost:3000/api/users returns 200" |
108
+ | "Check styles" | "Open browser, verify dark mode toggle works" |
109
+
110
+ ---
111
+
112
+ ### Principle 6: At Least One Criterion a MACHINE Can Run
113
+
114
+ Specific is not the same as **runnable**. Both of these are specific:
115
+
116
+ | Criterion | Who can check it |
117
+ |-----------|------------------|
118
+ | "Open browser, verify dark mode toggle works" | a human, with eyes |
119
+ | `npm test -- theme.spec.ts` | a machine, exit code 0 |
120
+
121
+ Both belong in a plan. But a plan whose criteria are **all** of the first kind
122
+ has no gate — it has an opinion. Whoever reviews the diff has to re-derive
123
+ whether the work is done by reading it, and that judgement is exactly where a
124
+ review says "looks right" to code that isn't.
125
+
126
+ > **Rule:** every plan carries a `## Gate` block with **at least one command**
127
+ > that exits 0 when the work is done and non-zero when it is not. Not prose about
128
+ > testing — the command, copy-pasteable.
129
+
130
+ ```
131
+ ## Gate
132
+ Runnable (must exit 0):
133
+ - `npm test -- src/theme.spec.ts`
134
+ - `npm run typecheck`
135
+
136
+ By eye (human, after the gate is green):
137
+ - Dark mode toggle animates smoothly
138
+ ```
139
+
140
+ **Why this ordering:** the machine checks run FIRST and gate the human's
141
+ attention. Reviewing pixels on a diff that does not compile wastes the scarcest
142
+ thing in the loop.
143
+
144
+ **If you cannot write a runnable command, the plan is not ready.** That is the
145
+ useful signal, not an obstacle: it means "done" is still undefined, and no
146
+ executor — human, cheap model or expensive one — can hit a target nobody can
147
+ measure. Go back and define it. Common escapes:
148
+
149
+ | Feels unmeasurable | Runnable form |
150
+ |--------------------|---------------|
151
+ | "the bug is fixed" | a test that fails today and passes after |
152
+ | "nothing else broke" | the existing suite, named explicitly |
153
+ | "the config is right" | a command that reads it back and asserts |
154
+ | "it deploys" | the build command |
155
+
156
+ **Do not accept the toolchain's generic health as the gate.** `npm run build`
157
+ passing proves the project still compiles; it does not prove *this task* was
158
+ done. A generic suite is the floor, never the whole gate — name the check that
159
+ would fail if this specific change were absent or wrong.
160
+
161
+ ---
162
+
163
+ ## Plan Structure (Flexible, Not Fixed!)
164
+
165
+ ```
166
+ # [Task Name]
167
+
168
+ ## Goal
169
+ One sentence: What are we building/fixing?
170
+
171
+ ## Tasks
172
+ - [ ] Task 1: [Specific action] → Verify: [How to check]
173
+ - [ ] Task 2: [Specific action] → Verify: [How to check]
174
+ - [ ] Task 3: [Specific action] → Verify: [How to check]
175
+
176
+ ## Gate
177
+ Runnable (must exit 0):
178
+ - `[command]`
179
+
180
+ By eye (after the gate is green):
181
+ - [what a human still has to look at, if anything]
182
+
183
+ ## Done When
184
+ - [ ] Gate is green
185
+ - [ ] [Main success criteria]
186
+ ```
187
+
188
+ > **That's it.** No phases, no sub-sections unless truly needed.
189
+ > Keep it minimal. Add complexity only when required.
190
+
191
+ ## Notes
192
+ [Any important considerations]
193
+ ```
194
+
195
+ ---
196
+
197
+ ## Best Practices (Quick Reference)
198
+
199
+ 1. **Start with goal** - What are we building/fixing?
200
+ 2. **Max 10 tasks** - If more, break into multiple plans
201
+ 3. **Each task verifiable** - Clear "done" criteria
202
+ 4. **Project-specific** - No copy-paste templates
203
+ 5. **Update as you go** - Mark `[x]` when complete
204
+ 6. **One runnable command in `## Gate`** - if you can't write it, the plan isn't ready (Principle 6)
205
+
206
+ ---
207
+
208
+ ## When to Use
209
+
210
+ - New project from scratch
211
+ - Adding a feature
212
+ - Fixing a bug (if complex)
213
+ - Refactoring multiple files
@@ -0,0 +1,196 @@
1
+ ---
2
+ name: powershell-windows
3
+ description: PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling.
4
+ when_to_use: "When working on Windows systems, writing PowerShell scripts, or using Windows-specific commands. NOT for macOS/Linux."
5
+ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
6
+ ---
7
+
8
+ # PowerShell Windows Patterns
9
+
10
+ > Critical patterns and pitfalls for Windows PowerShell.
11
+
12
+ ---
13
+
14
+ ## 1. Operator Syntax Rules
15
+
16
+ ### CRITICAL: Parentheses Required
17
+
18
+ | ❌ Wrong | ✅ Correct |
19
+ |----------|-----------|
20
+ | `if (Test-Path "a" -or Test-Path "b")` | `if ((Test-Path "a") -or (Test-Path "b"))` |
21
+ | `if (Get-Item $x -and $y -eq 5)` | `if ((Get-Item $x) -and ($y -eq 5))` |
22
+
23
+ **Rule:** Each cmdlet call MUST be in parentheses when using logical operators.
24
+
25
+ ---
26
+
27
+ ## 2. Unicode/Emoji Restriction
28
+
29
+ ### CRITICAL: No Unicode in Scripts
30
+
31
+ | Purpose | ❌ Don't Use | ✅ Use |
32
+ |---------|-------------|--------|
33
+ | Success | ✅ ✓ | [OK] [+] |
34
+ | Error | ❌ ✗ 🔴 | [!] [X] |
35
+ | Warning | ⚠️ 🟡 | [*] [WARN] |
36
+ | Info | ℹ️ 🔵 | [i] [INFO] |
37
+ | Progress | ⏳ | [...] |
38
+
39
+ **Rule:** Use ASCII characters only in PowerShell scripts.
40
+
41
+ ---
42
+
43
+ ## 3. Null Check Patterns
44
+
45
+ ### Always Check Before Access
46
+
47
+ | ❌ Wrong | ✅ Correct |
48
+ |----------|-----------|
49
+ | `$array.Count -gt 0` | `$array -and $array.Count -gt 0` |
50
+ | `$text.Length` | `if ($text) { $text.Length }` |
51
+
52
+ ---
53
+
54
+ ## 4. String Interpolation
55
+
56
+ ### Complex Expressions
57
+
58
+ | ❌ Wrong | ✅ Correct |
59
+ |----------|-----------|
60
+ | `"Value: $($obj.prop.sub)"` | Store in variable first |
61
+
62
+ **Pattern:**
63
+ ```
64
+ $value = $obj.prop.sub
65
+ Write-Output "Value: $value"
66
+ ```
67
+
68
+ ---
69
+
70
+ ## 5. Error Handling
71
+
72
+ ### ErrorActionPreference
73
+
74
+ | Value | Use |
75
+ |-------|-----|
76
+ | Stop | Production & automation scripts (fail fast, allows try/catch to catch non-terminating errors) |
77
+ | Continue | Interactive terminal session default only |
78
+ | SilentlyContinue | Suppress expected non-critical noise on specific cmdlets with `-ErrorAction` |
79
+
80
+ ### Try/Catch Pattern
81
+
82
+ - Don't return inside try block
83
+ - Use finally for cleanup
84
+ - Return after try/catch
85
+
86
+ ---
87
+
88
+ ## 6. File Paths
89
+
90
+ ### Windows Path Rules
91
+
92
+ | Pattern | Use |
93
+ |---------|-----|
94
+ | Literal path | `C:\Users\User\file.txt` |
95
+ | Variable path | `Join-Path $env:USERPROFILE "file.txt"` |
96
+ | Relative | `Join-Path $ScriptDir "data"` |
97
+
98
+ **Rule:** Use Join-Path for cross-platform safety.
99
+
100
+ ---
101
+
102
+ ## 7. Array Operations
103
+
104
+ ### Correct Patterns
105
+
106
+ | Operation | Syntax |
107
+ |-----------|--------|
108
+ | Empty array | `$array = @()` |
109
+ | Add item | `$array += $item` |
110
+ | ArrayList add | `$list.Add($item) | Out-Null` |
111
+
112
+ ---
113
+
114
+ ## 8. JSON Operations
115
+
116
+ ### CRITICAL: Depth Parameter
117
+
118
+ | ❌ Wrong | ✅ Correct |
119
+ |----------|-----------|
120
+ | `ConvertTo-Json` | `ConvertTo-Json -Depth 10` |
121
+
122
+ **Rule:** Always specify `-Depth` for nested objects.
123
+
124
+ ### File Operations
125
+
126
+ | Operation | Pattern |
127
+ |-----------|---------|
128
+ | Read | `Get-Content "file.json" -Raw | ConvertFrom-Json` |
129
+ | Write | `$data | ConvertTo-Json -Depth 10 | Out-File "file.json" -Encoding UTF8` |
130
+
131
+ ---
132
+
133
+ ## 9. Common Errors
134
+
135
+ | Error Message | Cause | Fix |
136
+ |---------------|-------|-----|
137
+ | "parameter 'or'" | Missing parentheses | Wrap cmdlets in () |
138
+ | "Unexpected token" | Unicode character | Use ASCII only |
139
+ | "Cannot find property" | Null object | Check null first |
140
+ | "Cannot convert" | Type mismatch | Use .ToString() |
141
+ | `Start-Process: Cannot validate argument on parameter 'FilePath'` | cmd syntax `start "" app.exe` in PowerShell | `Start-Process 'app.exe' -ArgumentList '--a','--b'` |
142
+
143
+ ---
144
+
145
+ ## 9b. Background Processes and Stray Console Windows
146
+
147
+ A console program (`ssh.exe`, `node.exe`, `nvm.exe`) started by a parent that has **no
148
+ console** (`pythonw`, a scheduled task, a GUI app, an agent's hidden shell) gets a new
149
+ visible window. Repeated launches mean a window popping up every few seconds.
150
+
151
+ | Symptom | Cause | Fix |
152
+ | --- | --- | --- |
153
+ | Empty terminal titled `...\OpenSSH\ssh.exe` keeps appearing | `pythonw` script respawning `ssh` | `subprocess.call(..., creationflags=subprocess.CREATE_NO_WINDOW)` |
154
+ | Dialog "Terminal Only: NVM for Windows should be run from a terminal" | `nvm` called without a TTY (npm `preinstall`, agents, CI) | Skip version switching when `!process.stdin.isTTY \|\| process.env.CI`; print the command for the human instead |
155
+ | Window flashes from a scheduled task | Task runs `powershell.exe` without hiding | `-WindowStyle Hidden`, or `conhost.exe --headless <exe>` |
156
+
157
+ Find who spawns it (parent chain of the process):
158
+
159
+ ```powershell
160
+ $all = Get-CimInstance Win32_Process
161
+ $all | Where-Object Name -eq 'ssh.exe' | ForEach-Object {
162
+ $parent = $all | Where-Object ProcessId -eq $_.ParentProcessId
163
+ '{0} <- {1}: {2}' -f $_.ProcessId, $parent.Name, $parent.CommandLine
164
+ }
165
+ ```
166
+
167
+ A respawn loop also needs **backoff**: double the wait while the child dies fast, so a
168
+ persistent failure does not reconnect every few seconds.
169
+
170
+ ---
171
+
172
+ ## 10. Script Template
173
+
174
+ ```powershell
175
+ # Strict mode
176
+ Set-StrictMode -Version Latest
177
+ $ErrorActionPreference = "Stop"
178
+
179
+ # Paths
180
+ $ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
181
+
182
+ # Main
183
+ try {
184
+ # Logic here
185
+ Write-Output "[OK] Done"
186
+ exit 0
187
+ }
188
+ catch {
189
+ Write-Warning "Error: $_"
190
+ exit 1
191
+ }
192
+ ```
193
+
194
+ ---
195
+
196
+ > **Remember:** PowerShell has unique syntax rules. Parentheses, ASCII-only, and null checks are non-negotiable.
@@ -0,0 +1,269 @@
1
+ ---
2
+ name: provider-orchestration
3
+ description: Split plan / execute / review across coding-agent CLIs (Cursor, Claude Code, Codex, and others when present). Executors are writers and investigators on cheap/fast models — never flagship unless the human operator named that model this turn. Nobody merges but the conductor.
4
+ when_to_use: "When the user asks to run work on another provider, pass execution to Cursor/composer, Claude Code, Codex, or Gemini CLI, orchestrate multi-provider jobs, or keep planning/review on the current session while a cheaper CLI types or probes. NOT for same-runtime subagents (use coordinator-mode / parallel-agents), NOT for a single small edit you should just make, NOT for spawning a flagship model unless the human named it this turn."
5
+ allowed-tools: Read, Glob, Grep, Bash
6
+ effort: high
7
+ ---
8
+
9
+ # Provider orchestration — plan dear, type cheap, review dear
10
+
11
+ > One agent that plans, types, and reviews on the same expensive meter is how
12
+ > a subscription dies. Split the roles. Isolation is Git, not a warning.
13
+
14
+ ## Política obrigatória de executores
15
+
16
+ Únicas combinações permitidas para tarefas executadas ou investigadas por CLI: Codex `gpt-6-luna` com esforço `low`; Claude `claude-haiku-5-5` com `--effort low`; Cursor `composer-2.5`; OpenCode Go `opencode-go/deepseek-v4.1-flash`. Não trocar modelo por variável, fallback, tier ou preço. Se o modelo não estiver disponível, falhar e informar; não substituir. Esta política prevalece sobre exemplos anteriores neste documento.
17
+
18
+ This skill is the **conductor**. The per-CLI recipes live in `cursor-exec`,
19
+ `claude-exec`, `codex-exec`, and `gemini-exec`. Load those when you are about
20
+ to spawn. Do not paste their argv from memory — flags drift.
21
+
22
+ **Exec is writer + investigator, not flagship.** The spawned CLI types and
23
+ looks. It does not architect. Cheap/fast model is the default on every
24
+ executor. A flagship id (Opus, Fable, frontier GPT, Gemini Pro, vendor
25
+ "best" default) is allowed **only when the human operator named that model
26
+ in this turn**. The conductor agent is not the operator — "this looks hard,
27
+ I'll spawn Opus" is a violation. If the job needs flagship judgement, keep
28
+ it here on the conductor.
29
+
30
+ ---
31
+
32
+ ## 1. What this is (and what it is not)
33
+
34
+ **This is:** one interactive agent (you) decomposes work, writes an unambiguous
35
+ plan, dispatches a **different** coding-agent CLI headless in an isolated
36
+ worktree, then reviews the real diff and delivers.
37
+
38
+ **This is not:**
39
+
40
+ | Pattern | Where it lives | Why it is a different job |
41
+ |---|---|---|
42
+ | Subagents in the same runtime (`Task`, native Agent tool) | `coordinator-mode`, `parallel-agents` | Same provider, same bill, same tree unless you isolate |
43
+ | The ZenKit bridge router (`execute-claude` / `execute-cursor`) | `zenkit-bridge` | Classifies a request; it does not run the ritual below |
44
+ | Selling access to someone else's Claude / Cursor / Codex | — | **Forbidden.** The buyer brings their own subscription. This kit teaches the method. Pooling keys and reselling the CLI is how you inherit the provider's terms. |
45
+
46
+ If the user said "spin two reviewers", that is `coordinator-mode`. If they said
47
+ "you plan, composer types, you review", that is this skill.
48
+
49
+ ---
50
+
51
+ ## 2. The three roles (never collapse them)
52
+
53
+ | Role | Who | Pays for | Allowed to |
54
+ |---|---|---|---|
55
+ | **Conductor** | The interactive agent talking to the human | Planning + review tokens | Write the plan, pick the executor, isolate, read the diff, iterate, open the PR, merge only with a human when the repo requires it |
56
+ | **Executor** | A headless CLI in a worktree | Cheap / fast model (writer + investigator) | Type the planned diff, or probe (read-only). **Never pick a flagship model unless the human named it this turn. Never merge. Never push to a protected branch. Never touch a second tree.** |
57
+ | **Human** | The operator | The subscriptions | Keys, merge-to-prod, anything destructive |
58
+
59
+ Collapsing conductor and executor onto one premium model is the default, and
60
+ it is the expensive default. Collapsing executor and merger is how autonomous
61
+ codegen ships unreviewed.
62
+
63
+ ---
64
+
65
+ ## 3. Probe before you promise
66
+
67
+ Do not assume the buyer's machine looks like yours. Before dispatching:
68
+
69
+ ```bash
70
+ command -v cursor-agent; command -v agent; command -v cursor
71
+ command -v claude
72
+ command -v codex
73
+ command -v gemini
74
+ ```
75
+
76
+ A missing binary is not a failure of this skill — it is a missing
77
+ subscription. Say which role you can cover with what is installed, and ask
78
+ before inventing a fallback that burns the conductor's meter typing.
79
+
80
+ Auth is the buyer's. Typical env vars (never log, never commit):
81
+
82
+ | CLI | Auth |
83
+ |---|---|
84
+ | Cursor | `CURSOR_API_KEY` |
85
+ | Claude Code | `ANTHROPIC_API_KEY` or a subscription login / `claude setup-token` |
86
+ | Codex | `CODEX_API_KEY` (exec-only) or saved CLI login |
87
+ | Gemini CLI | `GEMINI_API_KEY` |
88
+
89
+ ---
90
+
91
+ ## 4. The ritual
92
+
93
+ ### Step 1 — Plan (conductor, expensive)
94
+
95
+ Write a `PLAN.md` the executor cannot misread:
96
+
97
+ - Files to touch, and files **not** to touch
98
+ - Contracts / signatures that must stay
99
+ - Acceptance: commands that must go green
100
+ - What "done" looks like in `git status`
101
+
102
+ Vague plans produce vague diffs. The executor is a typist with a compiler, not
103
+ an architect. `plan-writing` applies.
104
+
105
+ ### Step 2 — Isolate (`git-worktrees`)
106
+
107
+ Every executor run happens in a **dedicated worktree**, never in the shared
108
+ tree. Advisory locks warn; they do not isolate. Load `git-worktrees` and
109
+ create from the main tree, not from inside another worktree.
110
+
111
+ Two executors on the same worktree is the same incident as two humans on the
112
+ same checkout.
113
+
114
+ ### Step 3 — Dispatch (one executor, one tree)
115
+
116
+ Pick **one** CLI per worktree. Parallel dispatch is allowed across *different*
117
+ worktrees with *disjoint* file sets. Sequential is mandatory when the second
118
+ diff depends on the first.
119
+
120
+ | Job shape | Default executor | Default model |
121
+ |---|---|---|
122
+ | Implementation / UI / mechanical refactor | Cursor (`cursor-exec`) | `composer-2.5` |
123
+ | Type or probe with a Claude subscription | Claude Code (`claude-exec`) | `haiku` |
124
+ | Type or probe with a Codex subscription | Codex (`codex-exec`) | the CLI's **mini/fast** id (pin it; omit = often flagship) |
125
+ | Type or probe with a Gemini subscription | Gemini CLI (`gemini-exec`) | Flash (`gemini-2.5-flash`); never Pro unless the human named it |
126
+
127
+ Judgement that needs a flagship stays on the **conductor**. Do not promote
128
+ the typist because the plan was hard.
129
+
130
+ Exact argv: the matching `*-exec` skill. Do not copy from an old session.
131
+
132
+ ### Step 4 — Supervise (conductor)
133
+
134
+ When the process exits:
135
+
136
+ ```bash
137
+ git -C <worktree> status --short
138
+ git -C <worktree> diff
139
+ ```
140
+
141
+ Read the diff. Run the acceptance commands from the plan. A green executor
142
+ exit is not a green change — it means the CLI finished, not that the change
143
+ is right.
144
+
145
+ **Continuidade do mandatário:** o condutor permanece
146
+ responsável até diff revisável ou bloqueio humano verdadeiro. Monte um snapshot
147
+ JSON (`executor`, `revisao`, `demanda`, `reserva`, `handoff`, `sessao`) e rode:
148
+
149
+ ```bash
150
+ node scripts/avaliar-vigilancia-mandato.mjs snapshot.json
151
+ ```
152
+
153
+ Ou `avaliar_vigilancia_mandato` no bridge; em `dispatch_handoff` com `rerun:true`,
154
+ passe `mandatoSnapshot` só quando `podeIniciarExecutor` for true. Fail-closed no
155
+ runtime (`dispatch-mandato-gate.ts` em `server.ts`, sem alterar `dispatch.ts`).
156
+
157
+ If the diff is wrong, **do not fix it as the conductor unless the fix is
158
+ smaller than the round-trip**. Write a tighter plan and dispatch again on the
159
+ same worktree (idempotent). The conductor typing "just this one file" is how
160
+ the split collapses.
161
+
162
+ ### Step 5 — Deliver (conductor)
163
+
164
+ Commit on the worktree branch, open the review. The executor does not open
165
+ the PR unless the plan explicitly says so **and** the conductor still reads
166
+ it. Merge to production stays human when the repo says so.
167
+
168
+ ---
169
+
170
+ ## 5. Cost policy (hard)
171
+
172
+ Executors are **writers and investigators**. Flagship is not a default, not
173
+ a "just this once" the conductor grants itself, and not whatever the CLI
174
+ picks when you omit `--model`.
175
+
176
+ | CLI | Default for exec | Flagship (Opus, Fable, frontier GPT, Pro, …) |
177
+ |---|---|---|
178
+ | Cursor | `composer-2.5` | Only if the **human** named the id this turn. Fable on Cursor burns included quota unusually fast — still requires the name, plus a warning |
179
+ | Claude Code | `haiku` | Only if the **human** named `sonnet` / `opus` / Fable / a full flagship id this turn |
180
+ | Codex | mini/fast id, **pinned** | Only if the **human** named it. Omitting `-m` is how you get the vendor flagship by accident |
181
+ | Gemini | Flash / cheap | Pro only if the **human** named it |
182
+
183
+ - House cap: per-token typist models must cost ≤ $2 per 1M tokens (in+out, models.dev
184
+ prices). Claude Haiku (~$6) is **not** cheap on that cap. The default typist/investigator
185
+ is Cursor `composer-2.5` (`cursor-exec` / `dispatch_handoff`); `opencode-go-exec` is
186
+ an optional provider.
187
+ - The human operator is the person at the keyboard. A parent agent, a
188
+ subagent, a plan file, or "the other CLI used Opus last time" does not
189
+ authorize flagship.
190
+ - Cap Claude with `--max-budget-usd` even on haiku.
191
+ - Do not silently fall back to another provider if the chosen CLI is
192
+ missing — that is a cost surprise.
193
+ - Never start a second executor to "try the other provider" on the same
194
+ tree. That is two writers, plus two bills.
195
+ - See `model-routing`.
196
+
197
+ ### 5.1 Anatomia do executor e política de fallback
198
+
199
+ Um executor é a soma de cinco partes. Quando uma falha, só uma delas muda, e a mudança
200
+ é explícita:
201
+
202
+ ```text
203
+ ┌──────────────────────────────────────────────┐
204
+ │ objetivo (plano do condutor, critérios) │
205
+ ├──────────────────────────────────────────────┤
206
+ executor = │ reasoning (modelo + esforço do papel) │
207
+ │ tools (CLI do provider, worktree, MCPs) │
208
+ │ memória (projeto: demanda, quadro, fatos) │
209
+ │ fallback (o que fazer quando algo cai) │
210
+ └──────────────────────────────────────────────┘
211
+ ```
212
+
213
+ Modelo e esforço vêm do papel (triagem, desenvolvimento, teste, revisão), configurados no
214
+ bridge e sempre dentro da lista permitida acima (`ZENKIT_EXECUTOR_CONFIG`).
215
+
216
+ Regra de fallback quando um provider cai:
217
+
218
+ | Falha | O que o executor faz | O que o condutor pode fazer |
219
+ |---|---|---|
220
+ | Modelo indisponível ou recusado | Falha e informa o erro real. Não troca de modelo sozinho | Redespachar com outro executor **da lista**, nomeado no `dispatch_handoff` |
221
+ | CLI ausente ou sem login | Falha antes de criar worktree ou reserva | Pedir ao humano o login, ou redespachar para outro executor da lista |
222
+ | Falha transitória de rede | O bridge repete até 3 vezes | Nada, se recuperou; senão, tratar como as linhas acima |
223
+ | Executor termina sem alteração | Handoff fecha como `no-changes` | Revisar a saída e decidir: plano mais claro ou encerrar |
224
+
225
+ Nunca é fallback: subir para um modelo fora da lista, trocar de provider em silêncio,
226
+ ou abrir um segundo executor na mesma worktree. Toda troca fica registrada no handoff
227
+ (papel, executor, modelo, esforço).
228
+
229
+ ---
230
+
231
+ ## 6. Traps (each one has already cost a session somewhere)
232
+
233
+ **`--force` / `--sandbox workspace-write` / `--permission-mode dontAsk` without
234
+ a worktree.** Those flags exist so the CLI does not stop for a TTY. They are
235
+ not a safety story. Isolation is the safety story.
236
+
237
+ **Codex `exec` is read-only until you say otherwise.** Forgetting
238
+ `--sandbox workspace-write` looks like a hung or no-op run.
239
+
240
+ **Three names for the Cursor CLI.** Official docs say `agent`; some installs
241
+ expose `cursor-agent`; the IDE binary also has `cursor agent`. Probe. Do not
242
+ hardcode.
243
+
244
+ **Same-runtime `Task` is not a second provider.** It inherits the parent's
245
+ model pin. On Cursor, a subagent with a premium pin in its frontmatter will
246
+ bill premium even if the parent is `composer-2.5`. That is a flagship call
247
+ the human did not make.
248
+
249
+ **Omitting `--model` / `-m`.** Vendor default is often flagship. Exec must
250
+ pin the cheap id. Silence is not a default.
251
+
252
+ **Sharing API keys across customers.** Each buyer uses their own
253
+ subscription. The kit must still work if the memory service / any other piece of the
254
+ seller's stack is absent.
255
+
256
+ **Executor commit on the conductor's branch.** If you skipped the worktree,
257
+ the commit lands wherever the shared tree was. Check `git branch --show-current`
258
+ in the worktree before commit.
259
+
260
+ ---
261
+
262
+ ## 7. When not to use this
263
+
264
+ - The edit is smaller than the plan file you would write.
265
+ - No second CLI is installed and the user did not ask to go get one.
266
+ - You would be dispatching a write into the tree you are currently editing.
267
+ - The user asked for a second *opinion*, not a second *typist* — that is
268
+ `coordinator-mode`.
269
+ ---