@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,80 @@
1
+ ---
2
+ name: gemini-exec
3
+ description: Run Gemini CLI headless (`gemini -p`) as a writer or investigator. Pin Flash (cheap), never Pro unless the human operator named that model this turn. Isolate in a worktree. Never merge.
4
+ when_to_use: "When the conductor needs Gemini CLI to type or probe a planned diff, or the user asks for gemini -p / Gemini headless. NOT for the interactive TUI, NOT for merge, NOT for Gemini Pro unless the human named that model this turn."
5
+ allowed-tools: Read, Glob, Grep, Bash
6
+ effort: medium
7
+ ---
8
+
9
+ # gemini-exec — Gemini CLI as writer / investigator
10
+
11
+ > `gemini -p` types and looks. Default **Flash**. Omitting `-m` can land on
12
+ > Auto/Pro. Flagship (Pro, "best", vendor default) only if the **human
13
+ > operator** named that model **this turn**. `--yolo` applies edits without
14
+ > a TTY — required for a typist, not a substitute for a worktree.
15
+
16
+ Load `provider-orchestration` for the ritual. Load `git-worktrees` before a
17
+ write. This file is the **Gemini argv and its traps**.
18
+
19
+ Canonical: [Headless Mode](https://google-gemini.github.io/gemini-cli/docs/cli/headless.html).
20
+ Re-probe `gemini --help` — this CLI moves. Default pin below: `gemini-2.5-flash`.
21
+ If the installed CLI rejects that id, probe `--help` / `/model` and pick the
22
+ current **Flash** (not Pro). Do not silently upgrade.
23
+
24
+ ---
25
+
26
+ ## 1. Probe (fail honest)
27
+
28
+ ```bash
29
+ command -v gemini || { echo "Gemini CLI not installed — do not silently type this as another provider"; exit 1; }
30
+ gemini --version
31
+ ```
32
+
33
+ Auth: `GEMINI_API_KEY` on **that one invocation**, or the buyer's saved CLI
34
+ login. Never log the key. If the binary is missing, **stop**.
35
+
36
+ ---
37
+
38
+ ## 2. Headless write recipe
39
+
40
+ ```bash
41
+ cd "$WORKTREE"
42
+ gemini -p "$(cat PLAN.md)" \
43
+ --output-format json \
44
+ --yolo \
45
+ -m gemini-2.5-flash
46
+ ```
47
+
48
+ | Flag | Why |
49
+ |---|---|
50
+ | `-p` / `--prompt` | Non-interactive; skip the TUI |
51
+ | `--output-format json` | Machine-readable. `stream-json` is for progress UIs |
52
+ | `--yolo` / `-y` | Auto-approve edits (typist). Isolated worktree required |
53
+ | `-m gemini-2.5-flash` | Cheap writer. **Do not pass Pro unless the human named it this turn** |
54
+
55
+ `--approval-mode auto_edit` is an alternative to `--yolo` on some builds.
56
+ Prefer what `gemini --help` shows on that machine.
57
+
58
+ Contain the process: own process group + wall-clock timeout.
59
+
60
+ ```bash
61
+ setsid timeout --kill-after=10 --signal=TERM 1800 \
62
+ gemini -p "$(cat PLAN.md)" --output-format json --yolo -m gemini-2.5-flash
63
+ ```
64
+
65
+ ---
66
+
67
+ ## 3. Probe (read-only)
68
+
69
+ Omit `--yolo`. The CLI should not apply edits. If a build still writes
70
+ without `--yolo`, you are in the wrong tree — stop.
71
+
72
+ ---
73
+
74
+ ## 4. When not to use this
75
+
76
+ - `gemini` is not on `PATH` — ask, do not substitute Cursor/Claude/Codex.
77
+ - The cheap typist should be Cursor `composer-2.5` — `cursor-exec`.
78
+ - You wanted interactive Gemini. This skill is `-p` only.
79
+ - You were about to pass Pro / omit `-m` and the human did not name a
80
+ flagship this turn — stop, or ask.
@@ -0,0 +1,157 @@
1
+ ---
2
+ name: geo-fundamentals
3
+ description: Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity).
4
+ when_to_use: "When optimizing content for AI search engines like ChatGPT, Claude, or Perplexity. Generative Engine Optimization."
5
+ allowed-tools: Read, Glob, Grep
6
+ ---
7
+
8
+ # GEO Fundamentals
9
+
10
+ > Optimization for AI-powered search engines.
11
+
12
+ ---
13
+
14
+ ## 1. What is GEO?
15
+
16
+ **GEO** = Generative Engine Optimization
17
+
18
+ | Goal | Platform |
19
+ |------|----------|
20
+ | Be cited in AI responses | ChatGPT, Claude, Perplexity, Gemini |
21
+
22
+ ### SEO vs GEO
23
+
24
+ | Aspect | SEO | GEO |
25
+ |--------|-----|-----|
26
+ | Goal | #1 ranking | AI citations |
27
+ | Platform | Google | AI engines |
28
+ | Metrics | Rankings, CTR | Citation rate |
29
+ | Focus | Keywords | Entities, data |
30
+
31
+ ---
32
+
33
+ ## 2. AI Engine Landscape
34
+
35
+ | Engine | Citation Style | Opportunity |
36
+ |--------|----------------|-------------|
37
+ | **Perplexity** | Numbered [1][2] | Highest citation rate |
38
+ | **ChatGPT** | Inline/footnotes | Custom GPTs |
39
+ | **Claude** | Contextual | Long-form content |
40
+ | **Gemini** | Sources section | SEO crossover |
41
+
42
+ ---
43
+
44
+ ## 3. RAG Retrieval Factors
45
+
46
+ How AI engines select content to cite:
47
+
48
+ | Factor | Weight |
49
+ |--------|--------|
50
+ | Semantic relevance | ~40% |
51
+ | Keyword match | ~20% |
52
+ | Authority signals | ~15% |
53
+ | Freshness | ~10% |
54
+ | Source diversity | ~15% |
55
+
56
+ ---
57
+
58
+ ## 4. Content That Gets Cited
59
+
60
+ | Element | Why It Works |
61
+ |---------|--------------|
62
+ | **Original statistics** | Unique, citable data |
63
+ | **Expert quotes** | Authority transfer |
64
+ | **Clear definitions** | Easy to extract |
65
+ | **Step-by-step guides** | Actionable value |
66
+ | **Comparison tables** | Structured info |
67
+ | **FAQ sections** | Direct answers |
68
+
69
+ ---
70
+
71
+ ## 5. GEO Content Checklist
72
+
73
+ ### Content Elements
74
+
75
+ - [ ] Question-based titles
76
+ - [ ] Summary/TL;DR at top
77
+ - [ ] Original data with sources
78
+ - [ ] Expert quotes (name, title)
79
+ - [ ] FAQ section (3-5 Q&A)
80
+ - [ ] Clear definitions
81
+ - [ ] "Last updated" timestamp
82
+ - [ ] Author with credentials
83
+
84
+ ### Technical Elements
85
+
86
+ - [ ] Article schema with dates
87
+ - [ ] Person schema for author
88
+ - [ ] FAQPage schema
89
+ - [ ] Fast loading (< 2.5s)
90
+ - [ ] Clean HTML structure
91
+
92
+ ---
93
+
94
+ ## 6. Entity Building
95
+
96
+ | Action | Purpose |
97
+ |--------|---------|
98
+ | Google Knowledge Panel | Entity recognition |
99
+ | Wikipedia (if notable) | Authority source |
100
+ | Consistent info across web | Entity consolidation |
101
+ | Industry mentions | Authority signals |
102
+
103
+ ---
104
+
105
+ ## 7. AI Crawler Access
106
+
107
+ ### Key AI User-Agents
108
+
109
+ | Crawler | Engine |
110
+ |---------|--------|
111
+ | GPTBot | ChatGPT/OpenAI |
112
+ | Claude-Web | Claude |
113
+ | PerplexityBot | Perplexity |
114
+ | Googlebot | Gemini (shared) |
115
+
116
+ ### Access Decision
117
+
118
+ | Strategy | When |
119
+ |----------|------|
120
+ | Allow all | Want AI citations |
121
+ | Block GPTBot | Don't want OpenAI training |
122
+ | Selective | Allow some, block others |
123
+
124
+ ---
125
+
126
+ ## 8. Measurement
127
+
128
+ | Metric | How to Track |
129
+ |--------|--------------|
130
+ | AI citations | Manual monitoring |
131
+ | "According to [Brand]" mentions | Search in AI |
132
+ | Competitor citations | Compare share |
133
+ | AI-referred traffic | UTM parameters |
134
+
135
+ ---
136
+
137
+ ## 9. Anti-Patterns
138
+
139
+ | ❌ Don't | ✅ Do |
140
+ |----------|-------|
141
+ | Publish without dates | Add timestamps |
142
+ | Vague attributions | Name sources |
143
+ | Skip author info | Show credentials |
144
+ | Thin content | Comprehensive coverage |
145
+
146
+ ---
147
+
148
+ > **Remember:** AI cites content that's clear, authoritative, and easy to extract. Be the best answer.
149
+
150
+ ---
151
+
152
+ ## Script
153
+
154
+ | Script | Purpose | Command |
155
+ |--------|---------|---------|
156
+ | `scripts/geo_checker.py` | GEO audit (AI citation readiness) | `python scripts/geo_checker.py <project_path>` |
157
+
@@ -0,0 +1,289 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ GEO Checker - Generative Engine Optimization Audit
4
+ Checks PUBLIC WEB CONTENT for AI citation readiness.
5
+
6
+ PURPOSE:
7
+ - Analyze pages that will be INDEXED by AI engines (ChatGPT, Perplexity, etc.)
8
+ - Check for structured data, author info, dates, FAQ sections
9
+ - Help content rank in AI-generated answers
10
+
11
+ WHAT IT CHECKS:
12
+ - HTML files (actual web pages)
13
+ - JSX/TSX files (React page components)
14
+ - NOT markdown files (those are developer docs, not public content)
15
+
16
+ Usage:
17
+ python geo_checker.py <project_path>
18
+ """
19
+ import sys
20
+ import re
21
+ import json
22
+ from pathlib import Path
23
+
24
+ # Fix Windows console encoding
25
+ try:
26
+ sys.stdout.reconfigure(encoding='utf-8', errors='replace')
27
+ sys.stderr.reconfigure(encoding='utf-8', errors='replace')
28
+ except AttributeError:
29
+ pass
30
+
31
+
32
+ # Directories to skip (not public content)
33
+ SKIP_DIRS = {
34
+ 'node_modules', '.next', 'dist', 'build', '.git', '.github',
35
+ '__pycache__', '.vscode', '.idea', 'coverage', 'test', 'tests',
36
+ '__tests__', 'spec', 'docs', 'documentation'
37
+ }
38
+
39
+ # Files to skip (not public pages)
40
+ SKIP_FILES = {
41
+ 'jest.config', 'webpack.config', 'vite.config', 'tsconfig',
42
+ 'package.json', 'package-lock', 'yarn.lock', '.eslintrc',
43
+ 'tailwind.config', 'postcss.config', 'next.config'
44
+ }
45
+
46
+
47
+ def is_page_file(file_path: Path) -> bool:
48
+ """Check if this file is likely a public-facing page."""
49
+ name = file_path.stem.lower()
50
+
51
+ # Skip config/utility files
52
+ if any(skip in name for skip in SKIP_FILES):
53
+ return False
54
+
55
+ # Skip test files
56
+ if name.endswith('.test') or name.endswith('.spec'):
57
+ return False
58
+ if name.startswith('test_') or name.startswith('spec_'):
59
+ return False
60
+
61
+ # Likely page indicators
62
+ page_indicators = ['page', 'index', 'home', 'about', 'contact', 'blog',
63
+ 'post', 'article', 'product', 'service', 'landing']
64
+
65
+ # Check if it's in a pages/app directory (Next.js, etc.)
66
+ parts = [p.lower() for p in file_path.parts]
67
+ if 'pages' in parts or 'app' in parts or 'routes' in parts:
68
+ return True
69
+
70
+ # Check filename indicators
71
+ if any(ind in name for ind in page_indicators):
72
+ return True
73
+
74
+ # HTML files are usually pages
75
+ if file_path.suffix.lower() == '.html':
76
+ return True
77
+
78
+ return False
79
+
80
+
81
+ def find_web_pages(project_path: Path) -> list:
82
+ """Find public-facing web pages only."""
83
+ patterns = ['**/*.html', '**/*.htm', '**/*.jsx', '**/*.tsx']
84
+
85
+ files = []
86
+ for pattern in patterns:
87
+ for f in project_path.glob(pattern):
88
+ # Skip excluded directories
89
+ if any(skip in f.parts for skip in SKIP_DIRS):
90
+ continue
91
+
92
+ # Check if it's likely a page
93
+ if is_page_file(f):
94
+ files.append(f)
95
+
96
+ return files[:30] # Limit to 30 pages
97
+
98
+
99
+ def check_page(file_path: Path) -> dict:
100
+ """Check a single web page for GEO elements."""
101
+ try:
102
+ content = file_path.read_text(encoding='utf-8', errors='ignore')
103
+ except Exception as e:
104
+ return {'file': str(file_path.name), 'passed': [], 'issues': [f"Error: {e}"], 'score': 0}
105
+
106
+ issues = []
107
+ passed = []
108
+
109
+ # 1. JSON-LD Structured Data (Critical for AI)
110
+ if 'application/ld+json' in content:
111
+ passed.append("JSON-LD structured data found")
112
+ if '"@type"' in content:
113
+ if 'Article' in content:
114
+ passed.append("Article schema present")
115
+ if 'FAQPage' in content:
116
+ passed.append("FAQ schema present")
117
+ if 'Organization' in content or 'Person' in content:
118
+ passed.append("Entity schema present")
119
+ else:
120
+ issues.append("No JSON-LD structured data (AI engines prefer structured content)")
121
+
122
+ # 2. Heading Structure
123
+ h1_count = len(re.findall(r'<h1[^>]*>', content, re.I))
124
+ h2_count = len(re.findall(r'<h2[^>]*>', content, re.I))
125
+
126
+ if h1_count == 1:
127
+ passed.append("Single H1 heading (clear topic)")
128
+ elif h1_count == 0:
129
+ issues.append("No H1 heading - page topic unclear")
130
+ else:
131
+ issues.append(f"Multiple H1 headings ({h1_count}) - confusing for AI")
132
+
133
+ if h2_count >= 2:
134
+ passed.append(f"{h2_count} H2 subheadings (good structure)")
135
+ else:
136
+ issues.append("Add more H2 subheadings for scannable content")
137
+
138
+ # 3. Author Attribution (E-E-A-T signal)
139
+ author_patterns = ['author', 'byline', 'written-by', 'contributor', 'rel="author"']
140
+ has_author = any(p in content.lower() for p in author_patterns)
141
+ if has_author:
142
+ passed.append("Author attribution found")
143
+ else:
144
+ issues.append("No author info (AI prefers attributed content)")
145
+
146
+ # 4. Publication Date (Freshness signal)
147
+ date_patterns = ['datePublished', 'dateModified', 'datetime=', 'pubdate', 'article:published']
148
+ has_date = any(re.search(p, content, re.I) for p in date_patterns)
149
+ if has_date:
150
+ passed.append("Publication date found")
151
+ else:
152
+ issues.append("No publication date (freshness matters for AI)")
153
+
154
+ # 5. FAQ Section (Highly citable)
155
+ faq_patterns = [r'<details', r'faq', r'frequently.?asked', r'"FAQPage"']
156
+ has_faq = any(re.search(p, content, re.I) for p in faq_patterns)
157
+ if has_faq:
158
+ passed.append("FAQ section detected (highly citable)")
159
+
160
+ # 6. Lists (Structured content)
161
+ list_count = len(re.findall(r'<(ul|ol)[^>]*>', content, re.I))
162
+ if list_count >= 2:
163
+ passed.append(f"{list_count} lists (structured content)")
164
+
165
+ # 7. Tables (Comparison data)
166
+ table_count = len(re.findall(r'<table[^>]*>', content, re.I))
167
+ if table_count >= 1:
168
+ passed.append(f"{table_count} table(s) (comparison data)")
169
+
170
+ # 8. Entity Recognition (E-E-A-T signal) - NEW 2025
171
+ entity_patterns = [
172
+ r'"@type"\s*:\s*"Organization"',
173
+ r'"@type"\s*:\s*"LocalBusiness"',
174
+ r'"@type"\s*:\s*"Brand"',
175
+ r'itemtype.*schema\.org/(Organization|Person|Brand)',
176
+ r'rel="author"'
177
+ ]
178
+ has_entity = any(re.search(p, content, re.I) for p in entity_patterns)
179
+ if has_entity:
180
+ passed.append("Entity/Brand recognition (E-E-A-T)")
181
+
182
+ # 9. Original Statistics/Data (AI citation magnet) - NEW 2025
183
+ stat_patterns = [
184
+ r'\d+%', # Percentages
185
+ r'\$[\d,]+', # Dollar amounts
186
+ r'study\s+(shows|found)', # Research citations
187
+ r'according to', # Source attribution
188
+ r'data\s+(shows|reveals)', # Data-backed claims
189
+ r'\d+x\s+(faster|better|more)', # Comparison stats
190
+ r'(million|billion|trillion)', # Large numbers
191
+ ]
192
+ stat_matches = sum(1 for p in stat_patterns if re.search(p, content, re.I))
193
+ if stat_matches >= 2:
194
+ passed.append("Original statistics/data (citation magnet)")
195
+
196
+ # 10. Conversational/Direct answers - NEW 2025
197
+ direct_answer_patterns = [
198
+ r'is defined as',
199
+ r'refers to',
200
+ r'means that',
201
+ r'the answer is',
202
+ r'in short,',
203
+ r'simply put,',
204
+ r'<dfn'
205
+ ]
206
+ has_direct = any(re.search(p, content, re.I) for p in direct_answer_patterns)
207
+ if has_direct:
208
+ passed.append("Direct answer patterns (LLM-friendly)")
209
+
210
+ # Calculate score
211
+ total = len(passed) + len(issues)
212
+ score = (len(passed) / total * 100) if total > 0 else 0
213
+
214
+ return {
215
+ 'file': str(file_path.name),
216
+ 'passed': passed,
217
+ 'issues': issues,
218
+ 'score': round(score)
219
+ }
220
+
221
+
222
+ def main():
223
+ target = sys.argv[1] if len(sys.argv) > 1 else "."
224
+ target_path = Path(target).resolve()
225
+
226
+ print("\n" + "=" * 60)
227
+ print(" GEO CHECKER - AI Citation Readiness Audit")
228
+ print("=" * 60)
229
+ print(f"Project: {target_path}")
230
+ print("-" * 60)
231
+
232
+ # Find web pages only
233
+ pages = find_web_pages(target_path)
234
+
235
+ if not pages:
236
+ print("\n[!] No public web pages found.")
237
+ print(" Looking for: HTML, JSX, TSX files in pages/app directories")
238
+ print(" Skipping: docs, tests, config files, node_modules")
239
+ output = {"script": "geo_checker", "pages_found": 0, "passed": True}
240
+ print("\n" + json.dumps(output, indent=2))
241
+ sys.exit(0)
242
+
243
+ print(f"Found {len(pages)} public pages to analyze\n")
244
+
245
+ # Check each page
246
+ results = []
247
+ for page in pages:
248
+ result = check_page(page)
249
+ results.append(result)
250
+
251
+ # Print results
252
+ for result in results:
253
+ status = "[OK]" if result['score'] >= 60 else "[!]"
254
+ print(f"{status} {result['file']}: {result['score']}%")
255
+ if result['issues'] and result['score'] < 60:
256
+ for issue in result['issues'][:2]: # Show max 2 issues
257
+ print(f" - {issue}")
258
+
259
+ # Average score
260
+ avg_score = sum(r['score'] for r in results) / len(results) if results else 0
261
+
262
+ print("\n" + "=" * 60)
263
+ print(f"AVERAGE GEO SCORE: {avg_score:.0f}%")
264
+ print("=" * 60)
265
+
266
+ if avg_score >= 80:
267
+ print("[OK] Excellent - Content well-optimized for AI citations")
268
+ elif avg_score >= 60:
269
+ print("[OK] Good - Some improvements recommended")
270
+ elif avg_score >= 40:
271
+ print("[!] Needs work - Add structured elements")
272
+ else:
273
+ print("[X] Poor - Content needs GEO optimization")
274
+
275
+ # JSON output
276
+ output = {
277
+ "script": "geo_checker",
278
+ "project": str(target_path),
279
+ "pages_checked": len(results),
280
+ "average_score": round(avg_score),
281
+ "passed": avg_score >= 60
282
+ }
283
+ print("\n" + json.dumps(output, indent=2))
284
+
285
+ sys.exit(0 if avg_score >= 60 else 1)
286
+
287
+
288
+ if __name__ == "__main__":
289
+ main()
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: git-worktrees
3
+ description: Work on a parallel branch in a dedicated working tree, instead of switching branches in the shared tree. Real isolation when more than one agent (or more than one task) is working in the same repository.
4
+ when_to_use: "Before starting any work in a repository that another agent, another session, or a background process may be using; when touching shared scope; when you need two versions of the code at the same time (compare, test, review PR without dropping what you're doing). Don't use for single-owner repos, one task at a time."
5
+ allowed-tools: Read, Glob, Grep, Bash
6
+ ---
7
+
8
+ # Git — worktrees
9
+
10
+ > The classic mistake isn't using the wrong worktree. It's **not using one** and
11
+ > finding out later that the commit went to someone else's branch.
12
+
13
+ ---
14
+
15
+ ## 1. The problem this solves
16
+
17
+ A repository has **one** working tree, and `git checkout` moves the whole thing.
18
+ If two pieces of work happen in parallel — two agents, two sessions, you and a
19
+ background script — the second `checkout` hijacks the first one's tree.
20
+
21
+ The typical damage isn't losing a file. It's worse, because it goes unnoticed:
22
+
23
+ - One job's commit lands **on the other job's branch**.
24
+ - Unsaved changes from another task end up in your `git add .`.
25
+ - The test runs against the wrong branch's code and passes — or fails — for the
26
+ wrong reason.
27
+
28
+ **Advisory locks warn, they do not isolate.** Any "who's working on what" system
29
+ is advisory: it warns, it doesn't prevent. What prevents it is Git, giving each
30
+ job its own tree.
31
+
32
+ ---
33
+
34
+ ## 2. How to do it
35
+
36
+ Always use absolute or dedicated directory paths (e.g. `.agent-worktrees/<task>` or `/tmp/worktrees/...`) rather than polluting parent folders:
37
+
38
+ ```bash
39
+ # Create worktree in a dedicated directory
40
+ WORKTREE_PATH="$HOME/.agent-worktrees/$(basename $(git rev-parse --show-toplevel))--feat-minha-tarefa"
41
+ git worktree add "$WORKTREE_PATH" -b feat/minha-tarefa origin/main
42
+ cd "$WORKTREE_PATH" || exit 1
43
+ ```
44
+
45
+ Work there like it's a clone: same history, same remotes, **independent files**.
46
+ When done and merged:
47
+
48
+ ```bash
49
+ # Clean removal with prune to clear locks and stale references
50
+ git worktree remove "$WORKTREE_PATH" --force
51
+ git worktree prune
52
+ ```
53
+
54
+ `git worktree list` shows what's open. For automated agents, script creation with lock checks to avoid concurrent collisions on the same branch.
55
+
56
+ ---
57
+
58
+ ## 3. The traps (all cost a lost session)
59
+
60
+ **Creating a worktree from inside a worktree.** Running the command from inside
61
+ `repo-feat-a` creates the new one *nested* there, and you end up with a tree
62
+ inside another and commits in unpredictable places. **Always create from the
63
+ main tree.**
64
+
65
+ **The environment is per worktree, not per repository.** Dependencies installed in
66
+ editable/linked mode (`pip install -e`, `npm link`, PYTHONPATH) point to the path
67
+ **where they were installed** — the main tree. Running the worktree's test with
68
+ the main tree's environment **tests the wrong code** and goes green while your
69
+ change isn't even loaded. Create the environment inside the worktree, or confirm
70
+ which path the module is being imported from before trusting the result.
71
+
72
+ **Hooks don't come for free.** Depending on how the repository configures hooks,
73
+ a new worktree may be born **without** the pre-commit/pre-push gate. Check before
74
+ trusting the gate, and don't discover that on push.
75
+
76
+ **Check the branch before committing.** `git branch --show-current`. It's one
77
+ line, and it's the difference between the right commit and the incident from
78
+ section 1.
79
+
80
+ **Removing the worktree doesn't delete the branch** — and it shouldn't. Delivered
81
+ work lives on the branch and in the PR; the worktree is just where it was done.
82
+
83
+ ---
84
+
85
+ ## 4. When NOT to use
86
+
87
+ Single-owner repo, one task at a time, no background process: worktree is
88
+ ceremony. Switching branches is enough, and one fewer tree is one fewer thing to
89
+ forget open.
90
+
91
+ The signal that it's past time to use one is simple: **you hesitated before
92
+ running `git checkout` because you weren't sure what was in the tree.** That
93
+ hesitation is the answer.
94
+
95
+ ---
96
+
97
+ ## 5. Never
98
+
99
+ - **Never** discard unsaved changes you didn't make (`git restore`,
100
+ `git checkout <arquivo>`, blind `git stash`) to "clean the tree". That's
101
+ someone else's uncommitted work until proven otherwise — open a worktree and
102
+ leave it where it is.
103
+ - **Never** switch branches on the main tree to do parallel work. That's exactly
104
+ the move section 1 describes.
105
+ - **Never** undo your own edit with `git checkout <arquivo>` when there were
106
+ other uncommitted changes in the same file — the command takes everything with
107
+ it. Make a backup copy before experimenting.