@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,210 @@
1
+ ---
2
+ name: clean-code
3
+ description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
4
+ when_to_use: "Always active for ALL code writing. Enforces concise, direct coding standards, testing pyramid, and performance best practices."
5
+ allowed-tools: Read, Write, Edit
6
+ version: 2.0
7
+ priority: CRITICAL
8
+ ---
9
+
10
+ # Clean Code - Pragmatic AI Coding Standards
11
+
12
+ > **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.
13
+
14
+ ---
15
+
16
+ ## Core Principles
17
+
18
+ | Principle | Rule |
19
+ |-----------|------|
20
+ | **SRP** | Single Responsibility - each function/class does ONE thing |
21
+ | **DRY** | Don't Repeat Yourself - extract duplicates, reuse |
22
+ | **KISS** | Keep It Simple - simplest solution that works |
23
+ | **YAGNI** | You Aren't Gonna Need It - don't build unused features |
24
+ | **Boy Scout** | Leave code cleaner than you found it (aplica-se apenas a código órfão *causado pela sua própria mudança*; não refatorar código adjacente não relacionado — ver karpathy-guidelines §3 Surgical Changes) |
25
+
26
+ ---
27
+
28
+ ## Naming Rules
29
+
30
+ | Element | Convention |
31
+ |---------|------------|
32
+ | **Variables** | Reveal intent: `userCount` not `n` |
33
+ | **Functions** | Verb + noun: `getUserById()` not `user()` |
34
+ | **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |
35
+ | **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
36
+ | **Event handlers** | `handle` prefix: `handleClick`, `handleKeyDown` |
37
+ | **TypeScript** | Explicit types on public APIs; avoid `any` |
38
+
39
+ > **Rule:** If you need a comment to explain a name, rename it.
40
+
41
+ ### Control flow
42
+
43
+ - Prefer **guard clauses** and early returns over deep nesting.
44
+ - Keep branches short; group related logic in `hooks/`, `utils/`, `components/`.
45
+ - Small, pure units; push side effects (API, logging) to the edges.
46
+
47
+ ---
48
+
49
+ ## Function Rules
50
+
51
+ | Rule | Description |
52
+ |------|-------------|
53
+ | **Focused** | One clear responsibility; length fits the problem without artificial slicing |
54
+ | **One Thing** | Does one thing, does it well |
55
+ | **One Level** | One level of abstraction per function |
56
+ | **Few Args** | Max 3 arguments, prefer 0-2 (or options object) |
57
+ | **No Unexpected Mutation** | Pure by default; mutate in-place only when designing explicit buffers/hot loops |
58
+
59
+ ---
60
+
61
+ ## Code Structure
62
+
63
+ | Pattern | Apply |
64
+ |---------|-------|
65
+ | **Guard Clauses** | Early returns for edge cases |
66
+ | **Flat > Nested** | Avoid deep nesting (max 2 levels) |
67
+ | **Composition** | Small functions composed together |
68
+ | **Colocation** | Keep related code close |
69
+
70
+ ---
71
+
72
+ ## AI Coding Style
73
+
74
+ | Situation | Action |
75
+ |-----------|--------|
76
+ | User asks for feature | Write it directly |
77
+ | User reports bug | Fix it, don't explain |
78
+ | No clear requirement | Ask, don't assume |
79
+
80
+ ---
81
+
82
+ ## Anti-Patterns (DON'T)
83
+
84
+ | ❌ Pattern | ✅ Fix |
85
+ |-----------|-------|
86
+ | Comment every line | Delete obvious comments |
87
+ | Helper for one-liner | Inline the code |
88
+ | Factory for 2 objects | Direct instantiation |
89
+ | utils.ts with 1 function | Put code where used |
90
+ | "First we import..." | Just write code |
91
+ | Deep nesting | Guard clauses |
92
+ | Magic numbers | Named constants |
93
+ | God functions | Split by responsibility |
94
+
95
+ ---
96
+
97
+ ## 🔴 Before Editing ANY File (THINK FIRST!)
98
+
99
+ **Before changing a file, ask yourself:**
100
+
101
+ | Question | Why |
102
+ |----------|-----|
103
+ | **What imports this file?** | They might break |
104
+ | **What does this file import?** | Interface changes |
105
+ | **What tests cover this?** | Tests might fail |
106
+ | **Is this a shared component?** | Multiple places affected |
107
+
108
+ **Quick Check:**
109
+ ```
110
+ File to edit: UserService.ts
111
+ └── Who imports this? → UserController.ts, AuthController.ts
112
+ └── Do they need changes too? → Check function signatures
113
+ ```
114
+
115
+ > 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
116
+ > 🔴 **Never leave broken imports or missing updates.**
117
+
118
+ ---
119
+
120
+ ## Summary
121
+
122
+ | Do | Don't |
123
+ |----|-------|
124
+ | Write code directly | Write tutorials |
125
+ | Let code self-document | Add obvious comments |
126
+ | Fix bugs immediately | Explain the fix first |
127
+ | Inline small things | Create unnecessary files |
128
+ | Name things clearly | Use abbreviations |
129
+ | Keep functions small | Write 100+ line functions |
130
+
131
+ > **Remember: The user wants working code, not a programming lesson.**
132
+
133
+ ---
134
+
135
+ ## 🔴 Self-Check Before Completing (MANDATORY)
136
+
137
+ **Before saying "task complete", verify:**
138
+
139
+ | Check | Question |
140
+ |-------|----------|
141
+ | ✅ **Goal met?** | Did I do exactly what user asked? |
142
+ | ✅ **Files edited?** | Did I modify all necessary files? |
143
+ | ✅ **Code works?** | Did I test/verify the change? |
144
+ | ✅ **No errors?** | Lint and TypeScript pass? |
145
+ | ✅ **Nothing forgotten?** | Any edge cases missed? |
146
+
147
+ > 🔴 **Rule:** If ANY check fails, fix it before completing.
148
+
149
+ ---
150
+
151
+ ## Verification Scripts (MANDATORY)
152
+
153
+ > 🔴 **CRITICAL:** Each agent runs ONLY their own skill's scripts after completing work.
154
+
155
+ ### Agent → Script Mapping
156
+
157
+ | Agent | Script | Command |
158
+ |-------|--------|---------|
159
+ | **frontend-specialist** | UX Audit | `python .cursor/skills/frontend-design/scripts/ux_audit.py .` |
160
+ | **frontend-specialist** | A11y Check | `python .cursor/skills/frontend-design/scripts/accessibility_checker.py .` |
161
+ | **backend-specialist** | API Validator | `python .cursor/skills/api-patterns/scripts/api_validator.py .` |
162
+ | **mobile-developer** | Mobile Audit | `python .cursor/skills/mobile-design/scripts/mobile_audit.py .` |
163
+ | **database-architect** | Schema Validate | `python .cursor/skills/database-design/scripts/schema_validator.py .` |
164
+ | **security-auditor** | Security Scan | `python .cursor/skills/vulnerability-scanner/scripts/security_scan.py .` |
165
+ | **seo-specialist** | SEO Check | `python .cursor/skills/seo-fundamentals/scripts/seo_checker.py .` |
166
+ | **seo-specialist** | GEO Check | `python .cursor/skills/geo-fundamentals/scripts/geo_checker.py .` |
167
+ | **performance-optimizer** | Lighthouse | `python .cursor/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
168
+ | **test-engineer** | Test Runner | `python .cursor/skills/testing-patterns/scripts/test_runner.py .` |
169
+ | **test-engineer** | Playwright | `python .cursor/skills/webapp-testing/scripts/playwright_runner.py <url>` |
170
+ | **Any agent** | Lint Check | `python .cursor/skills/lint-and-validate/scripts/lint_runner.py .` |
171
+ | **Any agent** | Type Coverage | `python .cursor/skills/lint-and-validate/scripts/type_coverage.py .` |
172
+ | **Any agent** | i18n Check | `python .cursor/skills/i18n-localization/scripts/i18n_checker.py .` |
173
+
174
+ > ❌ **WRONG:** `test-engineer` running `ux_audit.py`
175
+ > ✅ **CORRECT:** `frontend-specialist` running `ux_audit.py`
176
+
177
+ ---
178
+
179
+ ### 🔴 Script Output Handling (READ → SUMMARIZE → ASK)
180
+
181
+ **When running a validation script, you MUST:**
182
+
183
+ 1. **Run the script** and capture ALL output
184
+ 2. **Parse the output** - identify errors, warnings, and passes
185
+ 3. **Summarize to user** in this format:
186
+
187
+ ```markdown
188
+ ## Script Results: [script_name.py]
189
+
190
+ ### ❌ Errors Found (X items)
191
+ - [File:Line] Error description 1
192
+ - [File:Line] Error description 2
193
+
194
+ ### ⚠️ Warnings (Y items)
195
+ - [File:Line] Warning description
196
+
197
+ ### ✅ Passed (Z items)
198
+ - Check 1 passed
199
+ - Check 2 passed
200
+
201
+ **Should I fix the X errors?**
202
+ ```
203
+
204
+ 4. **Wait for user confirmation** before fixing
205
+ 5. **After fixing** → Re-run script to confirm
206
+
207
+ > 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
208
+ > 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
209
+ > 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.
210
+
@@ -0,0 +1,115 @@
1
+ ---
2
+ name: code-review-checklist
3
+ description: Code review guidelines covering code quality, security, and best practices.
4
+ when_to_use: "When reviewing code for quality, security, and best practices. When the user says 'review my code' or 'check this PR'."
5
+ allowed-tools: Read, Glob, Grep
6
+ ---
7
+
8
+ # Code Review Checklist
9
+
10
+ ## Quick Review Checklist
11
+
12
+ > **Scope Rule:** Linters/compilers enforce syntax, types and formatting (`const vs let`, semicolons, imports). Reviewers focus on invariants, security, data integrity and system behavior.
13
+
14
+ ### Correctness & Invariants
15
+ - [ ] Code satisfies the stated business requirement
16
+ - [ ] Invariants and state transitions are explicitly maintained
17
+ - [ ] Error conditions and partial failures handle rollback / graceful cleanup
18
+ - [ ] Idempotency ensured for retryable operations
19
+
20
+ ### Security & Tenancy
21
+ - [ ] Authorization & Access Control: BOLA/IDOR protected; user owns the requested resource
22
+ - [ ] Multi-tenancy: Tenant isolation / RLS filters enforced across queries
23
+ - [ ] Input validated at trust boundaries (sanitization, schema validation)
24
+ - [ ] No hardcoded secrets, API keys or sensitive data leaks in logs/errors
25
+ - [ ] **AI-Specific:** Protection against prompt injection & tainted external inputs
26
+
27
+ ### Data Integrity & Persistence
28
+ - [ ] Database mutations execute in atomic transactions where multiple tables/rows are touched
29
+ - [ ] Concurrency: Race conditions mitigated (locks, versioning, unique constraints)
30
+ - [ ] Backward compatibility: DB migrations do not break running instances during rolling deploys
31
+
32
+ ### Performance & Resource Safety
33
+ - [ ] No N+1 queries or unindexed scans in high-frequency paths
34
+ - [ ] Bounded resource usage: timeouts on external calls, limits on collections/payloads
35
+ - [ ] No leaks in streams, event emitters or long-lived subscriptions
36
+
37
+ ### Code Quality
38
+ - [ ] Clear naming
39
+ - [ ] DRY - no duplicate code
40
+ - [ ] SOLID principles followed
41
+ - [ ] Appropriate abstraction level
42
+
43
+ ### Testing
44
+ - [ ] Unit tests for new code
45
+ - [ ] Edge cases tested
46
+ - [ ] Tests readable and maintainable
47
+
48
+ ### Documentation
49
+ - [ ] Complex logic commented
50
+ - [ ] Public APIs documented
51
+ - [ ] README updated if needed
52
+
53
+ ## AI & LLM Review Patterns (2025)
54
+
55
+ ### Logic & Hallucinations
56
+ - [ ] **Chain of Thought:** Does the logic follow a verifiable path?
57
+ - [ ] **Edge Cases:** Did the AI account for empty states, timeouts, and partial failures?
58
+ - [ ] **External State:** Is the code making safe assumptions about file systems or networks?
59
+
60
+ ### Prompt Engineering Review
61
+ ```markdown
62
+ // ❌ Vague prompt in code
63
+ const response = await ai.generate(userInput);
64
+
65
+ // ✅ Structured & Safe prompt
66
+ const response = await ai.generate({
67
+ system: "You are a specialized parser...",
68
+ input: sanitize(userInput),
69
+ schema: ResponseSchema
70
+ });
71
+ ```
72
+
73
+ ## Anti-Patterns to Flag
74
+
75
+ ```typescript
76
+ // ❌ Magic numbers
77
+ if (status === 3) { ... }
78
+
79
+ // ✅ Named constants
80
+ if (status === Status.ACTIVE) { ... }
81
+
82
+ // ❌ Deep nesting
83
+ if (a) { if (b) { if (c) { ... } } }
84
+
85
+ // ✅ Early returns
86
+ if (!a) return;
87
+ if (!b) return;
88
+ if (!c) return;
89
+ // do work
90
+
91
+ // ❌ Long functions (100+ lines)
92
+ // ✅ Small, focused functions
93
+
94
+ // ❌ any type
95
+ const data: any = ...
96
+
97
+ // ✅ Proper types
98
+ const data: UserData = ...
99
+ ```
100
+
101
+ ## Review Comments Guide
102
+
103
+ ```
104
+ // Blocking issues use 🔴
105
+ 🔴 BLOCKING: SQL injection vulnerability here
106
+
107
+ // Important suggestions use 🟡
108
+ 🟡 SUGGESTION: Consider using useMemo for performance
109
+
110
+ // Minor nits use 🟢 (reserve for non-linter observations)
111
+ 🟢 NIT: Method name could better express domain intent (e.g. `markFulfilled` vs `setComplete`)
112
+
113
+ // Questions use ❓
114
+ ❓ QUESTION: What happens if user is null here?
115
+ ```
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: code-review-graph
3
+ description: Token-efficient code review using Tree-sitter AST graphs and MCP. Reduces AI assistant token usage by 6.8–49x by computing blast radius of changes instead of reading entire codebases. Uses SQLite graph database for structural analysis.
4
+ when_to_use: "When reviewing code in large codebases (500+ files), when token costs are high, when making multi-file changes with cross-module dependencies, or when working with monorepos. Also for dead code detection, architecture visualization, and refactoring previews. NOT for small projects under 200 files with isolated single-file changes."
5
+ allowed-tools: Read, Grep, Glob, Bash
6
+ effort: medium
7
+ ---
8
+
9
+ # Code Review Graph — Token-Efficient Codebase Context via MCP
10
+
11
+ > Reduce AI token usage by **6.8x average** (up to **49x** on monorepos) by giving the AI a structural map of your codebase instead of letting it read everything.
12
+
13
+ ## Overview
14
+
15
+ `code-review-graph` is an MCP server that uses **Tree-sitter** to parse your codebase into an AST graph stored in **SQLite**. When your AI assistant needs context for a task, it queries the graph first — getting only the files in the **blast radius** of your change — instead of reading every file in the directory.
16
+
17
+ **Token Impact:**
18
+
19
+ | Codebase Type | Without Graph | With Graph | Reduction |
20
+ |---------------|---------------|------------|-----------|
21
+ | FastAPI (3K files) | 138,585 tokens | 37,217 tokens | **3.7x** |
22
+ | httpx | 64,666 tokens | 14,090 tokens | **4.6x** |
23
+ | Next.js monorepo (27K files) | 739,352 tokens | 15,049 tokens | **49.1x** |
24
+ | Express.js (small) | Less benefit | Graph overhead > savings | **~1x** |
25
+ | **Average across 6 repos** | — | — | **8.2x** |
26
+
27
+ > **Quality also improves:** Graph-assisted reviews score **8.8/10** vs **7.2/10** for naive reviews. Less noise = better signal = more accurate output.
28
+
29
+ ## 🛑 Graph Evaluation Protocol
30
+
31
+ When analyzing complex multi-file architectural changes or deep refactoring:
32
+ 1. **Check Availability:** Verify if `.code-review-graph/` already exists or if `code-review-graph` CLI is available.
33
+ 2. **Opt-in Indexing:** NEVER auto-execute heavy indexing (`build`) silently in the middle of a command without user context. If the index is missing on a large codebase, inform the user or confirm before running an expensive build.
34
+ 3. **Fallback to Direct Tools:** If the graph tool is not present, use standard exploration tools (`Grep`, `Glob`, `ast-grep`, `lsp_find_references`) instead of nagging the user with install prompts.
35
+
36
+ **Recusa:** não monte o grafo em projeto pequeno (<200 arquivos, mudança isolada). O overhead perde da leitura direta — ver [When to Use vs When to Skip](references/when-to-use-vs-when-to-skip.md).
37
+
38
+ ## Load on demand
39
+
40
+ Read only the file that matches the task:
41
+
42
+ - [When to Use vs When to Skip](references/when-to-use-vs-when-to-skip.md)
43
+ - [How It Works (4 Layers)](references/how-it-works-4-layers.md)
44
+ - [Installation](references/installation.md)
45
+ - [Configuration](references/configuration.md)
46
+ - [Core Workflows](references/core-workflows.md)
47
+ - [Known Limitations](references/known-limitations.md)
48
+ - [Alternatives Comparison](references/alternatives-comparison.md)
49
+ - [Integration with ZenKit](references/integration-with-zenkit.md)
50
+ - [Best Practices](references/best-practices.md)
@@ -0,0 +1,12 @@
1
+ ## Alternatives Comparison
2
+
3
+ | Tool | Approach | Pros | Cons | Best For |
4
+ |------|----------|------|------|----------|
5
+ | **code-review-graph** | Tree-sitter + SQLite | Fast, 19 languages, local, no deps | Static analysis only | General use, large codebases |
6
+ | **Claudette** | Go rewrite | Single binary, no Python | Fewer languages, simpler | Python-averse teams |
7
+ | **Serena** | LSP-based | Deep semantic precision, type resolution | Heavy setup, slower | Polymorphism-heavy codebases |
8
+ | **code-graph-rag** | RAG + vector search | Natural language queries | Complex setup | Codebase exploration |
9
+ | **Native IDE context** | Editor built-in | Zero setup | No explicit blast radius | Simple projects |
10
+
11
+ ---
12
+
@@ -0,0 +1,9 @@
1
+ ## Best Practices
2
+
3
+ 1. **Always run watch mode** in development — stale graphs produce stale context
4
+ 2. **Exclude generated files** — they inflate the graph with noise
5
+ 3. **Benchmark first** — measure token usage for 1 week without, 1 week with
6
+ 4. **Combine with output constraints** — graph reduces input, prompt engineering reduces output
7
+ 5. **Use `.code-review-graphignore`** for build artifacts, `node_modules`, `dist/`
8
+ 6. **Keep sessions short** — fresh sessions + graph = optimal token efficiency
9
+ 7. **Multi-repo registration** for microservice architectures
@@ -0,0 +1,43 @@
1
+ ## Configuration
2
+
3
+ ### Ignore File
4
+
5
+ Create `.code-review-graphignore` at project root (uses `.gitignore` syntax):
6
+
7
+ ```
8
+ # Build artifacts
9
+ dist/**
10
+ .next/**
11
+ build/**
12
+
13
+ # Dependencies
14
+ node_modules/**
15
+ vendor/**
16
+
17
+ # Generated files
18
+ generated/**
19
+ *.generated.ts
20
+ *.min.js
21
+
22
+ # Test fixtures (if large)
23
+ __fixtures__/**
24
+ ```
25
+
26
+ > Excluding generated files and build artifacts is critical — they inflate the graph with meaningless nodes.
27
+
28
+ ### Multi-Repo Setup
29
+
30
+ For microservice architectures:
31
+
32
+ ```bash
33
+ # Register additional repos
34
+ code-review-graph register /path/to/other/repo
35
+
36
+ # List all registered repos
37
+ code-review-graph repos
38
+ ```
39
+
40
+ The MCP server serves context across all registered repositories.
41
+
42
+ ---
43
+
@@ -0,0 +1,61 @@
1
+ ## Core Workflows
2
+
3
+ ### 1. Blast Radius Analysis (Primary Use)
4
+
5
+ This is automatic when the MCP server is active. Your AI assistant queries the graph before reading files, getting only the impacted files instead of everything.
6
+
7
+ ```
8
+ Without graph: Changed auth/middleware.py → AI reads 200+ files → 8,200 tokens
9
+ With graph: Changed auth/middleware.py → Graph returns 12 impacted files → 1,000 tokens
10
+ ```
11
+
12
+ ### 2. Risk-Scored Change Analysis
13
+
14
+ ```bash
15
+ code-review-graph detect-changes
16
+ ```
17
+
18
+ Scores each uncommitted change by risk level:
19
+ - Number of dependents
20
+ - Test coverage gaps
21
+ - Whether changed functions are on critical paths
22
+ - High-risk changes flagged **before** you ask for review
23
+
24
+ ### 3. Dead Code Detection
25
+
26
+ The graph finds nodes with **no incoming edges** — no callers, no importers, no test coverage:
27
+
28
+ ```bash
29
+ # Surfaces functions/classes that are candidates for removal
30
+ # Useful on mature codebases to reduce cruft
31
+ ```
32
+
33
+ ### 4. Refactoring Preview
34
+
35
+ ```bash
36
+ code-review-graph rename preview --from OldClassName --to NewClassName
37
+ ```
38
+
39
+ Shows every file affected by a rename, and flags edge cases (dynamic string references that static analysis can't catch).
40
+
41
+ ### 5. Architecture Visualization
42
+
43
+ ```bash
44
+ code-review-graph visualize
45
+ ```
46
+
47
+ Generates interactive visualization showing module clusters using community detection (Leiden algorithm). Useful for:
48
+ - Onboarding new contributors
49
+ - Identifying architectural drift
50
+ - Spotting overly-coupled modules
51
+
52
+ ### 6. Wiki Generation
53
+
54
+ ```bash
55
+ code-review-graph wiki
56
+ ```
57
+
58
+ Generates markdown wiki of codebase structure — every module, its public API, dependencies, and test coverage.
59
+
60
+ ---
61
+
@@ -0,0 +1,20 @@
1
+ ## How It Works (4 Layers)
2
+
3
+ ```
4
+ Layer 1: PARSE → Tree-sitter builds ASTs from 19 languages
5
+ Layer 2: STORE → Nodes + edges saved in SQLite graph
6
+ Layer 3: TRACE → BFS computes blast radius of changes
7
+ Layer 4: SERVE → MCP exposes graph to AI assistants
8
+ ```
9
+
10
+ ### What the Graph Contains
11
+ - **Nodes:** Files, functions, methods, classes, imports, tests
12
+ - **Edges:** "A calls B", "X imports Y", "TestZ covers FunctionW", "ClassA extends ClassB"
13
+ - **Metadata:** Name, type, file path, line range per node
14
+ - **Privacy:** Structural metadata only — NO source code content in the graph
15
+
16
+ ### Supported Languages (19)
17
+ Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++, Vue SFC, Solidity, Dart, R, Perl, Lua, Jupyter/Databricks notebooks.
18
+
19
+ ---
20
+
@@ -0,0 +1,67 @@
1
+ ## Installation
2
+
3
+ ### Prerequisites
4
+ - Python 3.9+ (`python3 --version`)
5
+ - pip or pipx installed
6
+ - An MCP-compatible AI client (ZenKit, Claude Code, Cursor, Windsurf, Zed)
7
+ - Git-tracked codebase (for incremental updates)
8
+
9
+ ### Step 1: Install the Package
10
+
11
+ ```bash
12
+ # Recommended: isolated environment
13
+ pipx install code-review-graph
14
+
15
+ # Alternative: fastest, no permanent install
16
+ uvx code-review-graph install
17
+
18
+ # Alternative: global pip
19
+ pip install code-review-graph
20
+ ```
21
+
22
+ ### Step 2: Configure MCP Client
23
+
24
+ ```bash
25
+ # Auto-detect all supported tools
26
+ code-review-graph install
27
+
28
+ # Or target a specific platform
29
+ code-review-graph install --platform claude-code
30
+ code-review-graph install --platform cursor
31
+ code-review-graph install --platform windsurf
32
+ ```
33
+
34
+ > **Restart your editor** after this step. The MCP server activates on restart.
35
+
36
+ ### Step 3: Build the Initial Graph
37
+
38
+ ```bash
39
+ cd /your/project
40
+ code-review-graph build
41
+ ```
42
+
43
+ | Codebase Size | Expected Build Time |
44
+ |---------------|---------------------|
45
+ | 500 files | 10–30 seconds |
46
+ | 5,000 files | 2–5 minutes |
47
+ | 27,000 files | 5–10 minutes |
48
+
49
+ ### Step 4: Enable Watch Mode (Recommended)
50
+
51
+ ```bash
52
+ # Keep graph current as you work
53
+ code-review-graph watch
54
+ ```
55
+
56
+ Incremental updates complete in **under 2 seconds**. If you prefer manual updates:
57
+
58
+ ```bash
59
+ code-review-graph update
60
+ ```
61
+
62
+ ### Step 5: Verify Integration
63
+
64
+ Open your AI client and check MCP connection. For Claude Code: run `/mcp` and confirm `code-review-graph` appears.
65
+
66
+ ---
67
+
@@ -0,0 +1,23 @@
1
+ ## Integration with ZenKit
2
+
3
+ ### Complementary Skills
4
+
5
+ | ZenKit Skill | How It Complements |
6
+ |-------------------|--------------------|
7
+ | `context-compression` | Graph reduces input context; compression reduces output verbosity |
8
+ | `coordinator-mode` | Graph-aware workers can be dispatched with precise file lists |
9
+ | `verify-changes` | After graph-informed review, verify changes via execution |
10
+ | `batch-operations` | Graph's blast radius informs which files need batch updates |
11
+
12
+ ### Recommended Session Architecture
13
+
14
+ ```
15
+ 1. Start fresh session for each distinct task
16
+ 2. Graph pre-filters context → AI reads only blast radius
17
+ 3. Context compression summarizes completed phases
18
+ 4. Memory system saves key decisions for next session
19
+ 5. Result: minimum tokens, maximum quality
20
+ ```
21
+
22
+ ---
23
+
@@ -0,0 +1,13 @@
1
+ ## Known Limitations
2
+
3
+ | Limitation | Impact | Mitigation |
4
+ |-----------|--------|------------|
5
+ | **Dynamic imports** (`require(variable)`, `import(buildPath())`) | Dependencies invisible to parser | Manually note in `.code-review-graphignore` or accept over-prediction |
6
+ | **Reflection-based calls** (Django signals, `getattr()`, Java reflection) | Missed edges in graph | Serena (LSP-based) is better for these codebases |
7
+ | **Runtime-generated code** (`eval`, template engines) | Not parseable at static time | Accept limitation or exclude from graph |
8
+ | **Cross-language boundaries** (Python calling TypeScript API) | No edges between language runtimes | Use multi-repo registration as partial workaround |
9
+ | **Stale graph** (without watch mode) | Claude queries outdated relationships | Always run `code-review-graph update` before tasks, or use watch mode |
10
+ | **TypeScript path aliases** (`@/components/...`) | May require tsconfig resolution config | Check `tsconfig_resolver.py` handles your setup |
11
+
12
+ ---
13
+
@@ -0,0 +1,21 @@
1
+ ## When to Use vs When to Skip
2
+
3
+ ### ✅ Install it if:
4
+ - Codebase is **500+ files**
5
+ - You make **multi-file changes** with cross-module dependencies
6
+ - You spend **$20+/month** on AI assistant tokens
7
+ - You work with **monorepos**, microservices, or cross-package TypeScript
8
+ - You want **better review quality** in addition to cost savings
9
+
10
+ ### ❌ Skip it if:
11
+ - Codebase is **under ~200 files** with isolated single-file changes
12
+ - Heavy use of **dynamic patterns** (reflection, runtime code gen, dynamic imports)
13
+ - You want **zero-maintenance** — the graph needs to stay in sync
14
+ - Team hasn't standardized on an AI coding tool yet
15
+
16
+ ### ⚠️ Evaluate first if:
17
+ - Codebase is **200–500 files** — benchmark before committing
18
+ - Mix of **static and dynamic patterns** — test on representative commits
19
+
20
+ ---
21
+