@zenrick/zenkit 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (353) 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/avaliar-vigilancia-mandato.mjs +38 -0
  335. package/scripts/bundle.mjs +158 -0
  336. package/scripts/check-deps.mjs +178 -0
  337. package/scripts/check-models.mjs +150 -0
  338. package/scripts/cli.mjs +295 -0
  339. package/scripts/continuidade-mandato.mjs +47 -0
  340. package/scripts/discriminar-turno.mjs +191 -0
  341. package/scripts/doctor.mjs +615 -0
  342. package/scripts/generate.mjs +676 -0
  343. package/scripts/install.mjs +11 -0
  344. package/scripts/layer-remote.mjs +344 -0
  345. package/scripts/layers.mjs +208 -0
  346. package/scripts/marketplace.mjs +77 -0
  347. package/scripts/product.mjs +32 -0
  348. package/scripts/ruleset-core.mjs +68 -0
  349. package/scripts/social-hooks.mjs +293 -0
  350. package/scripts/social-pacer.mjs +219 -0
  351. package/scripts/validate-bundles.mjs +14 -0
  352. package/scripts/validate-skills.mjs +174 -0
  353. package/scripts/zenkit-daemon-task.cmd +3 -0
@@ -0,0 +1,537 @@
1
+ # Touch Psychology Reference
2
+
3
+ > Deep dive into mobile touch interaction, Fitts' Law for touch, thumb zone anatomy, gesture psychology, and haptic feedback.
4
+ > **This is the mobile equivalent of ux-psychology.md - CRITICAL for all mobile work.**
5
+
6
+ ---
7
+
8
+ ## 1. Fitts' Law for Touch
9
+
10
+ ### The Fundamental Difference
11
+
12
+ ```
13
+ DESKTOP (Mouse/Trackpad):
14
+ ├── Cursor size: 1 pixel (precision)
15
+ ├── Visual feedback: Hover states
16
+ ├── Error cost: Low (easy to retry)
17
+ └── Target acquisition: Fast, precise
18
+
19
+ MOBILE (Finger):
20
+ ├── Contact area: ~7mm diameter (imprecise)
21
+ ├── Visual feedback: No hover, only tap
22
+ ├── Error cost: High (frustrating retries)
23
+ ├── Occlusion: Finger covers the target
24
+ └── Target acquisition: Slower, needs larger targets
25
+ ```
26
+
27
+ ### Fitts' Law Formula Adapted
28
+
29
+ ```
30
+ Touch acquisition time = a + b × log₂(1 + D/W)
31
+
32
+ Where:
33
+ ├── D = Distance to target
34
+ ├── W = Width of target
35
+ └── For touch: W must be MUCH larger than desktop
36
+ ```
37
+
38
+ ### Minimum Touch Target Sizes
39
+
40
+ | Platform | Minimum | Recommended | Use For |
41
+ |----------|---------|-------------|---------|
42
+ | **iOS (HIG)** | 44pt × 44pt | 48pt+ | All tappable elements |
43
+ | **Android (Material)** | 48dp × 48dp | 56dp+ | All tappable elements |
44
+ | **WCAG 2.2** | 44px × 44px | - | Accessibility compliance |
45
+ | **Critical Actions** | - | 56-64px | Primary CTAs, destructive actions |
46
+
47
+ ### Visual Size vs Hit Area
48
+
49
+ ```
50
+ ┌─────────────────────────────────────┐
51
+ │ │
52
+ │ ┌─────────────────────────┐ │
53
+ │ │ │ │
54
+ │ │ [ BUTTON ] │ ← Visual: 36px
55
+ │ │ │ │
56
+ │ └─────────────────────────┘ │
57
+ │ │ ← Hit area: 48px (padding extends)
58
+ └─────────────────────────────────────┘
59
+
60
+ ✅ CORRECT: Visual can be smaller if hit area is minimum 44-48px
61
+ ❌ WRONG: Making hit area same as small visual element
62
+ ```
63
+
64
+ ### Application Rules
65
+
66
+ | Element | Visual Size | Hit Area |
67
+ |---------|-------------|----------|
68
+ | Icon buttons | 24-32px | 44-48px (padding) |
69
+ | Text links | Any | 44px height minimum |
70
+ | List items | Full width | 48-56px height |
71
+ | Checkboxes/Radio | 20-24px | 44-48px tap area |
72
+ | Close/X buttons | 24px | 44px minimum |
73
+ | Tab bar items | Icon 24-28px | Full tab width, 49px height (iOS) |
74
+
75
+ ---
76
+
77
+ ## 2. Thumb Zone Anatomy
78
+
79
+ ### One-Handed Phone Usage
80
+
81
+ ```
82
+ Research shows: 49% of users hold phone one-handed.
83
+
84
+ ┌─────────────────────────────────────┐
85
+ │ │
86
+ │ ┌─────────────────────────────┐ │
87
+ │ │ HARD TO REACH │ │ ← Status bar, top nav
88
+ │ │ (requires stretch) │ │ Put: Back, menu, settings
89
+ │ │ │ │
90
+ │ ├─────────────────────────────┤ │
91
+ │ │ │ │
92
+ │ │ OK TO REACH │ │ ← Content area
93
+ │ │ (comfortable) │ │ Put: Secondary actions, content
94
+ │ │ │ │
95
+ │ ├─────────────────────────────┤ │
96
+ │ │ │ │
97
+ │ │ EASY TO REACH │ │ ← Tab bar, FAB zone
98
+ │ │ (thumb's arc) │ │ Put: PRIMARY CTAs!
99
+ │ │ │ │
100
+ │ └─────────────────────────────┘ │
101
+ │ │
102
+ │ [ HOME ] │
103
+ └─────────────────────────────────────┘
104
+ ```
105
+
106
+ ### Thumb Arc (Right-Handed User)
107
+
108
+ ```
109
+ Right hand holding phone:
110
+
111
+ ┌───────────────────────────────┐
112
+ │ STRETCH STRETCH OK │
113
+ │ │
114
+ │ STRETCH OK EASY │
115
+ │ │
116
+ │ OK EASY EASY │
117
+ │ │
118
+ │ EASY EASY EASY │
119
+ └───────────────────────────────┘
120
+
121
+ Left hand is mirrored.
122
+ → Design for BOTH hands or assume right-dominant
123
+ ```
124
+
125
+ ### Placement Guidelines
126
+
127
+ | Element Type | Ideal Position | Reason |
128
+ |--------------|----------------|--------|
129
+ | **Primary CTA** | Bottom center/right | Easy thumb reach |
130
+ | **Tab bar** | Bottom | Natural thumb position |
131
+ | **FAB** | Bottom right | Easy for right hand |
132
+ | **Navigation** | Top (stretch) | Less frequent use |
133
+ | **Destructive actions** | Top left | Hard to reach = harder to accidentally tap |
134
+ | **Dismiss/Cancel** | Top left | Convention + safety |
135
+ | **Confirm/Done** | Top right or bottom | Convention |
136
+
137
+ ### Large Phone Considerations (>6")
138
+
139
+ ```
140
+ On large phones, top 40% becomes "dead zone" for one-handed use.
141
+
142
+ Solutions:
143
+ ├── Reachability features (iOS)
144
+ ├── Pull-down interfaces (drawer pulls content down)
145
+ ├── Bottom sheet navigation
146
+ ├── Floating action buttons
147
+ └── Gesture-based alternatives to top actions
148
+ ```
149
+
150
+ ---
151
+
152
+ ## 3. Touch vs Click Psychology
153
+
154
+ ### Expectation Differences
155
+
156
+ | Aspect | Click (Desktop) | Touch (Mobile) |
157
+ |--------|-----------------|----------------|
158
+ | **Feedback timing** | Can wait 100ms | Expect instant (<50ms) |
159
+ | **Visual feedback** | Hover → Click | Immediate tap response |
160
+ | **Error tolerance** | Easy retry | Frustrating, feels broken |
161
+ | **Precision** | High | Low |
162
+ | **Context menu** | Right-click | Long press |
163
+ | **Cancel action** | ESC key | Swipe away, outside tap |
164
+
165
+ ### Touch Feedback Requirements
166
+
167
+ ```
168
+ Tap → Immediate visual change (< 50ms)
169
+ ├── Highlight state (background color change)
170
+ ├── Scale down slightly (0.95-0.98)
171
+ ├── Ripple effect (Android Material)
172
+ ├── Haptic feedback for confirmation
173
+ └── Never nothing!
174
+
175
+ Loading → Show within 100ms
176
+ ├── If action takes > 100ms
177
+ ├── Show spinner/progress
178
+ ├── Disable button (prevent double tap)
179
+ └── Optimistic UI when possible
180
+ ```
181
+
182
+ ### The "Fat Finger" Problem
183
+
184
+ ```
185
+ Problem: Finger occludes target during tap
186
+ ├── User can't see exactly where they're tapping
187
+ ├── Visual feedback appears UNDER finger
188
+ └── Increases error rate
189
+
190
+ Solutions:
191
+ ├── Show feedback ABOVE touch point (tooltips)
192
+ ├── Use cursor-like offset for precision tasks
193
+ ├── Magnification loupe for text selection
194
+ └── Large enough targets that precision doesn't matter
195
+ ```
196
+
197
+ ---
198
+
199
+ ## 4. Gesture Psychology
200
+
201
+ ### Gesture Discoverability Problem
202
+
203
+ ```
204
+ Problem: Gestures are INVISIBLE.
205
+ ├── User must discover/remember them
206
+ ├── No hover/visual hint
207
+ ├── Different mental model than tap
208
+ └── Many users never discover gestures
209
+
210
+ Solution: Always provide visible alternative
211
+ ├── Swipe to delete → Also show delete button or menu
212
+ ├── Pull to refresh → Also show refresh button
213
+ ├── Pinch to zoom → Also show zoom controls
214
+ └── Gestures as shortcuts, not only way
215
+ ```
216
+
217
+ ### Common Gesture Conventions
218
+
219
+ | Gesture | Universal Meaning | Usage |
220
+ |---------|-------------------|-------|
221
+ | **Tap** | Select, activate | Primary action |
222
+ | **Double tap** | Zoom in, like/favorite | Quick action |
223
+ | **Long press** | Context menu, selection mode | Secondary options |
224
+ | **Swipe horizontal** | Navigation, delete, actions | List actions |
225
+ | **Swipe down** | Refresh, dismiss | Pull to refresh |
226
+ | **Pinch** | Zoom in/out | Maps, images |
227
+ | **Two-finger scroll** | Scroll within scroll | Nested scrolls |
228
+
229
+ ### Gesture Affordance Design
230
+
231
+ ```
232
+ Swipe actions need visual hints:
233
+
234
+ ┌─────────────────────────────────────────┐
235
+ │ ┌───┐ │
236
+ │ │ ≡ │ Item with hidden actions... → │ ← Edge hint (partial color)
237
+ │ └───┘ │
238
+ └─────────────────────────────────────────┘
239
+
240
+ ✅ Good: Slight color peek at edge suggesting swipe
241
+ ✅ Good: Drag handle icon ( ≡ ) suggesting reorder
242
+ ✅ Good: Onboarding tooltip explaining gesture
243
+ ❌ Bad: Hidden gestures with no visual affordance
244
+ ```
245
+
246
+ ### Platform Gesture Differences
247
+
248
+ | Gesture | iOS | Android |
249
+ |---------|-----|---------|
250
+ | **Back** | Edge swipe from left | System back button/gesture |
251
+ | **Share** | Action sheet | Share sheet |
252
+ | **Context menu** | Long press / Force touch | Long press |
253
+ | **Dismiss modal** | Swipe down | Back button or swipe |
254
+ | **Delete in list** | Swipe left, tap delete | Swipe left, immediate or undo |
255
+
256
+ ---
257
+
258
+ ## 5. Haptic Feedback Patterns
259
+
260
+ ### Why Haptics Matter
261
+
262
+ ```
263
+ Haptics provide:
264
+ ├── Confirmation without looking
265
+ ├── Richer, more premium feel
266
+ ├── Accessibility (blind users)
267
+ ├── Reduced error rate
268
+ └── Emotional satisfaction
269
+
270
+ Without haptics:
271
+ ├── Feels "cheap" or web-like
272
+ ├── User unsure if action registered
273
+ └── Missed opportunity for delight
274
+ ```
275
+
276
+ ### iOS Haptic Types
277
+
278
+ | Type | Intensity | Use Case |
279
+ |------|-----------|----------|
280
+ | `selection` | Light | Picker scroll, toggle, selection |
281
+ | `light` | Light | Minor actions, hover equivalent |
282
+ | `medium` | Medium | Standard tap confirmation |
283
+ | `heavy` | Strong | Important completed, drop |
284
+ | `success` | Pattern | Task completed successfully |
285
+ | `warning` | Pattern | Warning, attention needed |
286
+ | `error` | Pattern | Error occurred |
287
+
288
+ ### Android Haptic Types
289
+
290
+ | Type | Use Case |
291
+ |------|----------|
292
+ | `CLICK` | Standard tap feedback |
293
+ | `HEAVY_CLICK` | Important actions |
294
+ | `DOUBLE_CLICK` | Confirm actions |
295
+ | `TICK` | Scroll/scrub feedback |
296
+ | `LONG_PRESS` | Long press activation |
297
+ | `REJECT` | Error/invalid action |
298
+
299
+ ### Haptic Usage Guidelines
300
+
301
+ ```
302
+ ✅ DO use haptics for:
303
+ ├── Button taps
304
+ ├── Toggle switches
305
+ ├── Picker/slider values
306
+ ├── Pull to refresh trigger
307
+ ├── Successful action completion
308
+ ├── Errors and warnings
309
+ ├── Swipe action thresholds
310
+ └── Important state changes
311
+
312
+ ❌ DON'T use haptics for:
313
+ ├── Every scroll position
314
+ ├── Every list item
315
+ ├── Background events
316
+ ├── Passive displays
317
+ └── Too frequently (haptic fatigue)
318
+ ```
319
+
320
+ ### Haptic Intensity Mapping
321
+
322
+ | Action Importance | Haptic Level | Example |
323
+ |-------------------|--------------|---------|
324
+ | Minor/Browsing | Light / None | Scrolling, hovering |
325
+ | Standard Action | Medium / Selection | Tap, toggle |
326
+ | Significant Action | Heavy / Success | Complete, confirm |
327
+ | Critical/Destructive | Heavy / Warning | Delete, payment |
328
+ | Error | Error pattern | Failed action |
329
+
330
+ ---
331
+
332
+ ## 6. Mobile Cognitive Load
333
+
334
+ ### How Mobile Differs from Desktop
335
+
336
+ | Factor | Desktop | Mobile | Implication |
337
+ |--------|---------|--------|-------------|
338
+ | **Attention** | Focused sessions | Interrupted constantly | Design for micro-sessions |
339
+ | **Context** | Controlled environment | Anywhere, any condition | Handle bad lighting, noise |
340
+ | **Multitasking** | Multiple windows | One app visible | Complete task in-app |
341
+ | **Input speed** | Fast (keyboard) | Slow (touch typing) | Minimize input, smart defaults |
342
+ | **Error recovery** | Easy (undo, back) | Harder (no keyboard shortcuts) | Prevent errors, easy recovery |
343
+
344
+ ### Reducing Mobile Cognitive Load
345
+
346
+ ```
347
+ 1. ONE PRIMARY ACTION per screen
348
+ └── Clear what to do next
349
+
350
+ 2. PROGRESSIVE DISCLOSURE
351
+ └── Show only what's needed now
352
+
353
+ 3. SMART DEFAULTS
354
+ └── Pre-fill what you can
355
+
356
+ 4. CHUNKING
357
+ └── Break long forms into steps
358
+
359
+ 5. RECOGNITION over RECALL
360
+ └── Show options, don't make user remember
361
+
362
+ 6. CONTEXT PERSISTENCE
363
+ └── Save state on interrupt/background
364
+ ```
365
+
366
+ ### Miller's Law for Mobile
367
+
368
+ ```
369
+ Desktop: 7±2 items in working memory
370
+ Mobile: Reduce to 5±1 (more distractions)
371
+
372
+ Navigation: Max 5 tab bar items
373
+ Options: Max 5 per menu level
374
+ Steps: Max 5 visible steps in progress
375
+ ```
376
+
377
+ ### Hick's Law for Mobile
378
+
379
+ ```
380
+ More choices = slower decisions
381
+
382
+ Mobile impact: Even worse than desktop
383
+ ├── Smaller screen = less overview
384
+ ├── Scrolling required = items forgotten
385
+ ├── Interruptions = lost context
386
+ └── Decision fatigue faster
387
+
388
+ Solution: Progressive disclosure
389
+ ├── Start with 3-5 options
390
+ ├── "More" for additional
391
+ ├── Smart ordering (most used first)
392
+ └── Previous selections remembered
393
+ ```
394
+
395
+ ---
396
+
397
+ ## 7. Touch Accessibility
398
+
399
+ ### Motor Impairment Considerations
400
+
401
+ ```
402
+ Users with motor impairments may:
403
+ ├── Have tremors (need larger targets)
404
+ ├── Use assistive devices (different input method)
405
+ ├── Have limited reach (one-handed necessity)
406
+ ├── Need more time (avoid timeouts)
407
+ └── Make accidental touches (need confirmation)
408
+
409
+ Design responses:
410
+ ├── Generous touch targets (48dp+)
411
+ ├── Adjustable timing for gestures
412
+ ├── Undo for destructive actions
413
+ ├── Switch control support
414
+ └── Voice control support
415
+ ```
416
+
417
+ ### Touch Target Spacing (A11y)
418
+
419
+ ```
420
+ WCAG 2.2 Success Criterion 2.5.8:
421
+
422
+ Touch targets MUST have:
423
+ ├── Width: ≥ 44px
424
+ ├── Height: ≥ 44px
425
+ ├── Spacing: ≥ 8px from adjacent targets
426
+
427
+ OR the target is:
428
+ ├── Inline (within text)
429
+ ├── User-controlled (user can resize)
430
+ ├── Essential (no alternative design)
431
+ ```
432
+
433
+ ### Accessible Touch Patterns
434
+
435
+ | Pattern | Accessible Implementation |
436
+ |---------|---------------------------|
437
+ | Swipe actions | Provide menu alternative |
438
+ | Drag and drop | Provide select + move option |
439
+ | Pinch zoom | Provide zoom buttons |
440
+ | Force touch | Provide long press alternative |
441
+ | Shake gesture | Provide button alternative |
442
+
443
+ ---
444
+
445
+ ## 8. Emotion in Touch
446
+
447
+ ### The Premium Feel
448
+
449
+ ```
450
+ What makes touch feel "premium":
451
+ ├── Instant response (< 50ms)
452
+ ├── Appropriate haptic feedback
453
+ ├── Smooth 60fps animations
454
+ ├── Correct resistance/physics
455
+ ├── Sound feedback (when appropriate)
456
+ └── Attention to spring physics
457
+ ```
458
+
459
+ ### Emotional Touch Feedback
460
+
461
+ | Emotion | Touch Response |
462
+ |---------|----------------|
463
+ | Success | Haptic success + confetti/check |
464
+ | Error | Haptic error + shake animation |
465
+ | Warning | Haptic warning + attention color |
466
+ | Delight | Unexpected smooth animation |
467
+ | Power | Heavy haptic on significant action |
468
+
469
+ ### Trust Building Through Touch
470
+
471
+ ```
472
+ Trust signals in touch interactions:
473
+ ├── Consistent behavior (same action = same response)
474
+ ├── Reliable feedback (never fails silently)
475
+ ├── Secure feel for sensitive actions
476
+ ├── Professional animations (not janky)
477
+ └── No accidental actions (confirmation for destructive)
478
+ ```
479
+
480
+ ---
481
+
482
+ ## 9. Touch Psychology Checklist
483
+
484
+ ### Before Every Screen
485
+
486
+ - [ ] **All touch targets ≥ 44-48px?**
487
+ - [ ] **Primary CTA in thumb zone?**
488
+ - [ ] **Destructive actions require confirmation?**
489
+ - [ ] **Gesture alternatives exist (visible buttons)?**
490
+ - [ ] **Haptic feedback on important actions?**
491
+ - [ ] **Immediate visual feedback on tap?**
492
+ - [ ] **Loading states for actions > 100ms?**
493
+
494
+ ### Before Release
495
+
496
+ - [ ] **Tested on smallest supported device?**
497
+ - [ ] **Tested one-handed on large phone?**
498
+ - [ ] **All gestures have visible alternatives?**
499
+ - [ ] **Haptics work correctly (test on device)?**
500
+ - [ ] **Touch targets tested with accessibility settings?**
501
+ - [ ] **No tiny close buttons or icons?**
502
+
503
+ ---
504
+
505
+ ## 10. Quick Reference Card
506
+
507
+ ### Touch Target Sizes
508
+
509
+ ```
510
+ iOS Android WCAG
511
+ Minimum: 44pt 48dp 44px
512
+ Recommended: 48pt+ 56dp+ -
513
+ Spacing: 8pt+ 8dp+ 8px+
514
+ ```
515
+
516
+ ### Thumb Zone Actions
517
+
518
+ ```
519
+ TOP: Navigation, settings, back (infrequent)
520
+ MIDDLE: Content, secondary actions
521
+ BOTTOM: Primary CTA, tab bar, FAB (frequent)
522
+ ```
523
+
524
+ ### Haptic Selection
525
+
526
+ ```
527
+ Light: Selection, toggle, minor
528
+ Medium: Tap, standard action
529
+ Heavy: Confirm, complete, drop
530
+ Success: Task done
531
+ Error: Failed action
532
+ Warning: Attention needed
533
+ ```
534
+
535
+ ---
536
+
537
+ > **Remember:** Every touch is a conversation between user and device. Make it feel natural, responsive, and respectful of human fingers—not precise cursor points.
@@ -0,0 +1,168 @@
1
+ ---
2
+ name: negocio-agente-conversa
3
+ description: Escreve as instruções de um agente que atende cliente por WhatsApp — como máquina de estágios com condição de entrada, não como personagem. Inclui as regras duras do canal e como testar antes de soltar em cliente real.
4
+ when_to_use: "Quando alguém pede para criar, revisar ou consertar um agente/robô de atendimento — 'monta o prompt do atendimento', 'o robô tá respondendo estranho', 'ele responde longo demais', 'ele inventa informação', 'quero um atendente de IA para minha clínica/loja'."
5
+ allowed-tools: Read, Glob, Grep
6
+ ---
7
+
8
+ # Negócio — Agente de conversa
9
+
10
+ > Carregue **negocio-linguagem** antes, e **negocio-qualificacao** junto: o agente
11
+ > precisa ler em que ponto o cliente está, senão trata todo mundo igual.
12
+
13
+ ---
14
+
15
+ ## Recusa
16
+
17
+ Não escreva persona ('você é a Ana'). Escreva máquina de estágios. Não invente informação do negócio. Não solte em cliente real sem o teste do canal.
18
+
19
+ ---
20
+
21
+ ## 1. Estágio, não personagem
22
+
23
+ O jeito comum de escrever isso é uma persona: *"você é a Ana, secretária há 10
24
+ anos, simpática e acolhedora"*. Isso produz um agente com muita personalidade e
25
+ nenhum comportamento previsível — ele improvisa, e quando erra ninguém sabe qual
26
+ frase corrigir.
27
+
28
+ **Escreva como máquina de estágios.** Cada estágio tem três partes:
29
+
30
+ ```
31
+ ESTÁGIO N — <nome curto>
32
+ Entra quando: <condição verificável sobre o que já se sabe da conversa>
33
+ Já tenho: <dados coletados até aqui>
34
+ Faça: <uma ação, e a próxima pergunta>
35
+ ```
36
+
37
+ A condição de entrada é o que torna o agente testável: dá para colar uma conversa
38
+ e apontar em qual estágio ele deveria estar. Persona não dá para testar.
39
+
40
+ **Esqueleto que serve para quase todo atendimento comercial:**
41
+
42
+ 1. **Identificar** — entra no início ou quando não se sabe o nome nem o motivo.
43
+ Pergunta o nome e o que a pessoa procura.
44
+ 2. **Entender** — entra quando já se sabe nome e motivo, mas não a dificuldade
45
+ concreta. Aprofunda em uma pergunta, e reconhece o que ouviu.
46
+ 3. **Apresentar** — entra quando o motivo está claro *ou* após qualificação mínima.
47
+ Traz o que resolve, com preço e o que está incluso. Se perguntam preço sem contexto,
48
+ **volta para Entender** — uma pergunta para saber o caso; não despeja tabela para
49
+ curioso.
50
+ 4. **Fechar** — entra quando a pessoa demonstrou interesse. Marca, dentro dos
51
+ horários reais, ou passa para o humano.
52
+ 5. **Fora de escopo** — entra quando pedem o que a empresa não faz. Diz que não
53
+ faz, em uma frase, sem inventar alternativa.
54
+
55
+ Adapte os nomes ao negócio; mantenha a forma. **Todo estágio precisa de uma saída
56
+ para o humano** — sem isso, o cliente encalhado fica preso no robô, que é o pior
57
+ resultado possível.
58
+
59
+ **Handoff para o humano** — gatilhos verificáveis:
60
+
61
+ - cliente pediu humano explicitamente;
62
+ - agente não soube responder **duas vezes** seguidas no mesmo assunto;
63
+ - cliente irritado ou reclamando;
64
+ - fora do horário de atendimento humano;
65
+ - caso fora do escopo que exige decisão da equipe.
66
+
67
+ **O que transferir:** nome, motivo, estágio atual, dados já coletados e resumo em uma
68
+ frase do que ficou pendente.
69
+
70
+ **Mensagem ao cliente** com expectativa de tempo: *"Vou passar pra [nome/equipe] que
71
+ confirma isso com você — costuma responder em [prazo real do negócio]."*
72
+
73
+ ---
74
+
75
+ ## 2. Regras duras do canal
76
+
77
+ Não são preferências. Quebrar qualquer uma delas é visível para o cliente:
78
+
79
+ - **Negrito no WhatsApp é um asterisco só** — `*assim*`. Modelo treinado em
80
+ Markdown tende a mandar `**assim**`, que aparece com os asteriscos na tela.
81
+ Instrução explícita no prompt, e verifique no teste real.
82
+ - **Curto.** Ninguém lê parágrafo no WhatsApp. Um teto declarado — algo como
83
+ duas frases ou ~130 caracteres — e só passa disso quando for inevitável.
84
+ - **Uma pergunta por mensagem.** Duas perguntas juntas viram zero respostas.
85
+ - **Agrupar a rajada.** Cliente real manda *"oi"* / *"tudo bem?"* / *"queria
86
+ saber"* / *"se atende convênio"* em quatro mensagens. Responder quatro vezes
87
+ denuncia o robô na primeira tela. O agente espera alguns segundos depois da
88
+ última mensagem e responde uma vez só, considerando tudo.
89
+ Isto é **do canal, não do prompt** — nenhuma instrução conserta; se a plataforma
90
+ não agrupa, é defeito a corrigir lá.
91
+ - **Só português-BR**, salvo se o negócio atender outra língua.
92
+ - **Emoji segue o negócio**, não o gosto de quem escreve o prompt: clínica e
93
+ advocacia quase nunca; loja e academia, à vontade.
94
+ - **Janela de 24h do WhatsApp Business.** Depois desse prazo sem mensagem do cliente,
95
+ mensagem ativa exige **template aprovado** para reabrir. Planeje retomada dentro da
96
+ janela ou com ferramenta que suporte template — não mande texto livre em conversa
97
+ expirada.
98
+ - **Mensagem fora de texto** (áudio, imagem, PDF): peça reformulação em texto (*"consegue
99
+ me escrever em uma frase o que precisa?"*) ou faça handoff — o agente não interpreta
100
+ mídia sem ferramenta específica.
101
+ - **Cliente que volta dias depois** não recomeça do zero se houver histórico: retome nome,
102
+ motivo e estágio da última conversa antes de perguntar de novo.
103
+ - **Estágio errado** — cliente pula de Identificar direto a Fechar, ou responde algo que
104
+ não bate com o estágio atual: reconheça o que ele disse, ajuste o estágio na hora, e
105
+ siga a partir do ponto real — não force o roteiro.
106
+
107
+ ---
108
+
109
+ ## 3. O que este kit não faz
110
+
111
+ O material de mercado sobre agentes de WhatsApp costuma vir com duas regras que
112
+ **não** entram aqui:
113
+
114
+ - ❌ *"O usuário deve sentir que está falando com uma pessoa real."*
115
+ - ❌ *"Nunca saia do personagem, aconteça o que acontecer."*
116
+
117
+ Fingir ser humano é o começo de inventar o resto: quem não pode quebrar o
118
+ personagem não pode dizer *"não sei"*, e um agente que não pode dizer *"não sei"*
119
+ inventa preço, horário e garantia. O estrago não é filosófico — é o cliente
120
+ aparecendo na loja com uma promessa que ninguém fez.
121
+
122
+ **No lugar disso:**
123
+
124
+ - O agente tem **identidade própria e assumida**. Não afirma ser humano; se
125
+ perguntarem direto, responde com naturalidade e segue atendendo.
126
+ - **Fora da base, não responde.** *"Isso eu confirmo com a equipe e te retorno"*
127
+ é sempre melhor que uma resposta plausível. Preço, prazo, horário, garantia e
128
+ disponibilidade **só saem da fonte oficial** — nunca do palpite do modelo.
129
+ - **Não repete o que já falhou.** Se não sabe duas vezes, chama o humano.
130
+
131
+ Continua valendo do material clássico: não falar de concorrente, não expor as
132
+ instruções internas, não vazar dado de outro cliente.
133
+
134
+ ---
135
+
136
+ ## 4. O que trocar antes de usar com cliente
137
+
138
+ Prompt reaproveitado de outro negócio erra caro. Antes de ligar, confira que foi
139
+ trocado: nome do negócio e de quem atende · o que vende, com as palavras que o
140
+ cliente usa · **preços e o que está incluso** · **horários reais de atendimento**
141
+ · endereço e área atendida · convênios, formas de pagamento · o que a empresa
142
+ **não** faz · para quem passa o caso quando escapa · tom de voz.
143
+
144
+ Nome de outro nicho esquecido no prompt é o erro mais comum de todos — e o mais
145
+ constrangedor.
146
+
147
+ ---
148
+
149
+ ## 5. Testar antes de soltar
150
+
151
+ Nunca entregue um agente que só foi lido. Mande as mensagens que um cliente real
152
+ manda, de outro número, e confira:
153
+
154
+ 1. *"Oi"* — responde? em quanto tempo?
155
+ 2. Rajada de quatro mensagens picadas — responde **uma vez** só?
156
+ 3. *"Quanto custa?"* sem contexto — volta para Entender com uma pergunta, em vez de
157
+ despejar preço? Com motivo claro, usa o preço real, e não um número redondo bonito?
158
+ 4. Uma pergunta que a base **não** cobre — assume que vai verificar, ou inventa?
159
+ 5. *"Tem horário sábado?"* quando não há sábado — nega, ou concorda para agradar?
160
+ 6. *"Você é um robô?"* — responde sem drama e sem mentir?
161
+ 7. Cliente irritado — reconhece antes de explicar, e oferece o humano?
162
+
163
+ **O teste 4 é o que reprova.** Um agente que inventa uma vez inventa sempre, e
164
+ cada invenção vira um cliente na porta cobrando o que não existe.
165
+
166
+ Ajuste, salve, teste de novo. Dois a cinco ciclos deixam o agente redondo — e
167
+ cada ajuste é uma frase específica no estágio específico, não uma reescrita do
168
+ prompt inteiro.