@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.
- package/.claude-plugin/marketplace.json +19 -0
- package/.cursor-plugin/marketplace.json +22 -0
- package/INSTALL.md +73 -0
- package/LICENSE +202 -0
- package/NOTICE +5 -0
- package/README.md +69 -3
- package/TERMS.md +48 -0
- package/THIRD-PARTY-NOTICES.md +109 -0
- package/kit/agents/backend-specialist.md +263 -0
- package/kit/agents/code-archaeologist.md +106 -0
- package/kit/agents/database-architect.md +226 -0
- package/kit/agents/debugger.md +226 -0
- package/kit/agents/devops-engineer.md +242 -0
- package/kit/agents/documentation-writer.md +104 -0
- package/kit/agents/explorer-agent.md +73 -0
- package/kit/agents/frontend-specialist.md +593 -0
- package/kit/agents/game-developer.md +162 -0
- package/kit/agents/mobile-developer.md +377 -0
- package/kit/agents/orchestrator.md +489 -0
- package/kit/agents/penetration-tester.md +188 -0
- package/kit/agents/performance-optimizer.md +187 -0
- package/kit/agents/product-manager.md +112 -0
- package/kit/agents/product-owner.md +95 -0
- package/kit/agents/project-planner.md +409 -0
- package/kit/agents/qa-automation-engineer.md +103 -0
- package/kit/agents/security-auditor.md +170 -0
- package/kit/agents/seo-specialist.md +111 -0
- package/kit/agents/test-engineer.md +158 -0
- package/kit/bundles/agent-building.yaml +26 -0
- package/kit/bundles/backend-data.yaml +14 -0
- package/kit/bundles/base.yaml +10 -0
- package/kit/bundles/core.yaml +21 -0
- package/kit/bundles/kit-engenharia.yaml +8 -0
- package/kit/bundles/kit-lite.yaml +9 -0
- package/kit/bundles/security.yaml +11 -0
- package/kit/bundles/ship-run.yaml +16 -0
- package/kit/bundles/web-ui.yaml +18 -0
- package/kit/commands/docs.md +33 -0
- package/kit/commands/explain.md +41 -0
- package/kit/commands/fix.md +65 -0
- package/kit/commands/implement.md +35 -0
- package/kit/commands/refactor.md +59 -0
- package/kit/commands/review.md +55 -0
- package/kit/commands/test.md +63 -0
- package/kit/modules/bridge/rules/cross-ide-bridge.mdc +73 -0
- package/kit/modules/bridge/zenkit-layer.yaml +1 -0
- package/kit/modules/nexuscore/sections/convivencia.md +12 -0
- package/kit/modules/nexuscore/sections/memoria.md +9 -0
- package/kit/modules/nexuscore/skills/quadro-agentes/SKILL.md +186 -0
- package/kit/modules/nexuscore/zenkit-layer.yaml +1 -0
- package/kit/rules/ZENKIT.mdc +294 -0
- package/kit/rules/git.mdc +51 -0
- package/kit/rules/karpathy-guidelines.mdc +70 -0
- package/kit/rules/model-routing.mdc +89 -0
- package/kit/rules/security-headers.mdc +41 -0
- package/kit/rules/social-automation.mdc +69 -0
- package/kit/rules/toc.mdc +40 -0
- package/kit/skills/api-patterns/SKILL.md +95 -0
- package/kit/skills/api-patterns/api-style.md +42 -0
- package/kit/skills/api-patterns/auth.md +24 -0
- package/kit/skills/api-patterns/documentation.md +26 -0
- package/kit/skills/api-patterns/graphql.md +41 -0
- package/kit/skills/api-patterns/rate-limiting.md +31 -0
- package/kit/skills/api-patterns/references/backend/backend-api-design.md +495 -0
- package/kit/skills/api-patterns/references/backend/backend-architecture.md +454 -0
- package/kit/skills/api-patterns/references/backend/backend-authentication.md +338 -0
- package/kit/skills/api-patterns/references/backend/backend-code-quality.md +659 -0
- package/kit/skills/api-patterns/references/backend/backend-debugging.md +904 -0
- package/kit/skills/api-patterns/references/backend/backend-devops.md +494 -0
- package/kit/skills/api-patterns/references/backend/backend-mindset.md +387 -0
- package/kit/skills/api-patterns/references/backend/backend-performance.md +397 -0
- package/kit/skills/api-patterns/references/backend/backend-security.md +290 -0
- package/kit/skills/api-patterns/references/backend/backend-technologies.md +256 -0
- package/kit/skills/api-patterns/references/backend/backend-testing.md +429 -0
- package/kit/skills/api-patterns/response.md +37 -0
- package/kit/skills/api-patterns/rest.md +40 -0
- package/kit/skills/api-patterns/scripts/api_validator.py +211 -0
- package/kit/skills/api-patterns/security-testing.md +122 -0
- package/kit/skills/api-patterns/trpc.md +41 -0
- package/kit/skills/api-patterns/versioning.md +22 -0
- package/kit/skills/app-builder/SKILL.md +76 -0
- package/kit/skills/app-builder/agent-coordination.md +71 -0
- package/kit/skills/app-builder/feature-building.md +53 -0
- package/kit/skills/app-builder/project-detection.md +34 -0
- package/kit/skills/app-builder/scaffolding.md +118 -0
- package/kit/skills/app-builder/tech-stack.md +41 -0
- package/kit/skills/app-builder/templates/SKILL.md +39 -0
- package/kit/skills/app-builder/templates/astro-static/TEMPLATE.md +76 -0
- package/kit/skills/app-builder/templates/chrome-extension/TEMPLATE.md +92 -0
- package/kit/skills/app-builder/templates/cli-tool/TEMPLATE.md +88 -0
- package/kit/skills/app-builder/templates/electron-desktop/TEMPLATE.md +88 -0
- package/kit/skills/app-builder/templates/express-api/TEMPLATE.md +83 -0
- package/kit/skills/app-builder/templates/flutter-app/TEMPLATE.md +90 -0
- package/kit/skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md +90 -0
- package/kit/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +122 -0
- package/kit/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +122 -0
- package/kit/skills/app-builder/templates/nextjs-static/TEMPLATE.md +169 -0
- package/kit/skills/app-builder/templates/nuxt-app/TEMPLATE.md +134 -0
- package/kit/skills/app-builder/templates/python-fastapi/TEMPLATE.md +83 -0
- package/kit/skills/app-builder/templates/react-native-app/TEMPLATE.md +119 -0
- package/kit/skills/architecture/SKILL.md +56 -0
- package/kit/skills/architecture/context-discovery.md +43 -0
- package/kit/skills/architecture/examples.md +94 -0
- package/kit/skills/architecture/pattern-selection.md +68 -0
- package/kit/skills/architecture/patterns-reference.md +50 -0
- package/kit/skills/architecture/trade-off-analysis.md +77 -0
- package/kit/skills/bash-linux/SKILL.md +203 -0
- package/kit/skills/batch-operations/SKILL.md +112 -0
- package/kit/skills/behavioral-modes/SKILL.md +255 -0
- package/kit/skills/brainstorming/SKILL.md +189 -0
- package/kit/skills/brainstorming/dynamic-questioning.md +350 -0
- package/kit/skills/brainstorming/references/problem-solving/attribution.md +69 -0
- package/kit/skills/brainstorming/references/problem-solving/collision-zone-thinking.md +79 -0
- package/kit/skills/brainstorming/references/problem-solving/inversion-exercise.md +91 -0
- package/kit/skills/brainstorming/references/problem-solving/meta-pattern-recognition.md +87 -0
- package/kit/skills/brainstorming/references/problem-solving/scale-game.md +95 -0
- package/kit/skills/brainstorming/references/problem-solving/simplification-cascades.md +80 -0
- package/kit/skills/brainstorming/references/problem-solving/when-stuck.md +72 -0
- package/kit/skills/claude-exec/SKILL.md +185 -0
- package/kit/skills/clean-code/SKILL.md +210 -0
- package/kit/skills/code-review-checklist/SKILL.md +115 -0
- package/kit/skills/code-review-graph/SKILL.md +50 -0
- package/kit/skills/code-review-graph/references/alternatives-comparison.md +12 -0
- package/kit/skills/code-review-graph/references/best-practices.md +9 -0
- package/kit/skills/code-review-graph/references/configuration.md +43 -0
- package/kit/skills/code-review-graph/references/core-workflows.md +61 -0
- package/kit/skills/code-review-graph/references/how-it-works-4-layers.md +20 -0
- package/kit/skills/code-review-graph/references/installation.md +67 -0
- package/kit/skills/code-review-graph/references/integration-with-zenkit.md +23 -0
- package/kit/skills/code-review-graph/references/known-limitations.md +13 -0
- package/kit/skills/code-review-graph/references/when-to-use-vs-when-to-skip.md +21 -0
- package/kit/skills/codex-exec/SKILL.md +161 -0
- package/kit/skills/context-compression/SKILL.md +145 -0
- package/kit/skills/coordinator-mode/SKILL.md +215 -0
- package/kit/skills/cursor-exec/SKILL.md +152 -0
- package/kit/skills/database-design/SKILL.md +53 -0
- package/kit/skills/database-design/database-selection.md +43 -0
- package/kit/skills/database-design/indexing.md +39 -0
- package/kit/skills/database-design/migrations.md +48 -0
- package/kit/skills/database-design/optimization.md +36 -0
- package/kit/skills/database-design/orm-selection.md +30 -0
- package/kit/skills/database-design/schema-design.md +56 -0
- package/kit/skills/database-design/scripts/schema_validator.py +172 -0
- package/kit/skills/deployment-procedures/SKILL.md +242 -0
- package/kit/skills/deprecation-and-migration/SKILL.md +149 -0
- package/kit/skills/documentation-templates/SKILL.md +195 -0
- package/kit/skills/entrega-com-agentes/SKILL.md +177 -0
- package/kit/skills/frontend-design/NOTICE.md +6 -0
- package/kit/skills/frontend-design/SKILL.md +456 -0
- package/kit/skills/frontend-design/animation-guide.md +331 -0
- package/kit/skills/frontend-design/color-system.md +311 -0
- package/kit/skills/frontend-design/decision-trees.md +418 -0
- package/kit/skills/frontend-design/motion-graphics.md +306 -0
- package/kit/skills/frontend-design/references/aesthetic/design-guideline-template.md +163 -0
- package/kit/skills/frontend-design/references/aesthetic/design-principles.md +62 -0
- package/kit/skills/frontend-design/references/aesthetic/design-resources.md +75 -0
- package/kit/skills/frontend-design/references/aesthetic/design-story-template.md +135 -0
- package/kit/skills/frontend-design/references/aesthetic/micro-interactions.md +53 -0
- package/kit/skills/frontend-design/references/aesthetic/storytelling-design.md +50 -0
- package/kit/skills/frontend-design/scripts/accessibility_checker.py +183 -0
- package/kit/skills/frontend-design/scripts/ux_audit.py +722 -0
- package/kit/skills/frontend-design/typography-system.md +345 -0
- package/kit/skills/frontend-design/ux-psychology.md +1116 -0
- package/kit/skills/frontend-design/visual-effects.md +383 -0
- package/kit/skills/game-development/2d-games/SKILL.md +119 -0
- package/kit/skills/game-development/3d-games/SKILL.md +135 -0
- package/kit/skills/game-development/SKILL.md +168 -0
- package/kit/skills/game-development/game-art/SKILL.md +185 -0
- package/kit/skills/game-development/game-audio/SKILL.md +190 -0
- package/kit/skills/game-development/game-design/SKILL.md +129 -0
- package/kit/skills/game-development/mobile-games/SKILL.md +108 -0
- package/kit/skills/game-development/multiplayer/SKILL.md +132 -0
- package/kit/skills/game-development/pc-games/SKILL.md +144 -0
- package/kit/skills/game-development/vr-ar/SKILL.md +123 -0
- package/kit/skills/game-development/web-games/SKILL.md +150 -0
- package/kit/skills/gemini-exec/SKILL.md +80 -0
- package/kit/skills/geo-fundamentals/SKILL.md +157 -0
- package/kit/skills/geo-fundamentals/scripts/geo_checker.py +289 -0
- package/kit/skills/git-worktrees/SKILL.md +107 -0
- package/kit/skills/i18n-localization/SKILL.md +145 -0
- package/kit/skills/i18n-localization/scripts/i18n_checker.py +241 -0
- package/kit/skills/intelligent-routing/SKILL.md +128 -0
- package/kit/skills/intelligent-routing/references/4-response-format.md +16 -0
- package/kit/skills/intelligent-routing/references/complexity-assessment.md +29 -0
- package/kit/skills/intelligent-routing/references/debug-intelligent-routing.md +9 -0
- package/kit/skills/intelligent-routing/references/debugging-agent-selection.md +7 -0
- package/kit/skills/intelligent-routing/references/domain-detection-rules.md +29 -0
- package/kit/skills/intelligent-routing/references/edge-cases.md +29 -0
- package/kit/skills/intelligent-routing/references/implementation-rules.md +35 -0
- package/kit/skills/intelligent-routing/references/integration-with-existing-workflows.md +21 -0
- package/kit/skills/intelligent-routing/references/performance-considerations.md +14 -0
- package/kit/skills/intelligent-routing/references/summary.md +16 -0
- package/kit/skills/intelligent-routing/references/testing-the-system.md +36 -0
- package/kit/skills/intelligent-routing/references/tier-0-automatic-analysis-always-active.md +27 -0
- package/kit/skills/intelligent-routing/references/user-education.md +12 -0
- package/kit/skills/karpathy-guidelines/SKILL.md +67 -0
- package/kit/skills/karpathy-guidelines/references/EXAMPLES.md +522 -0
- package/kit/skills/lint-and-validate/SKILL.md +46 -0
- package/kit/skills/lint-and-validate/scripts/lint_runner.py +184 -0
- package/kit/skills/lint-and-validate/scripts/type_coverage.py +173 -0
- package/kit/skills/mcp-atuacao/SKILL.md +238 -0
- package/kit/skills/mcp-builder/NOTICE.md +6 -0
- package/kit/skills/mcp-builder/SKILL.md +259 -0
- package/kit/skills/memory-system/SKILL.md +181 -0
- package/kit/skills/mobile-design/SKILL.md +395 -0
- package/kit/skills/mobile-design/decision-trees.md +516 -0
- package/kit/skills/mobile-design/mobile-backend.md +491 -0
- package/kit/skills/mobile-design/mobile-color-system.md +420 -0
- package/kit/skills/mobile-design/mobile-debugging.md +122 -0
- package/kit/skills/mobile-design/mobile-design-thinking.md +357 -0
- package/kit/skills/mobile-design/mobile-navigation.md +458 -0
- package/kit/skills/mobile-design/mobile-performance.md +767 -0
- package/kit/skills/mobile-design/mobile-testing.md +356 -0
- package/kit/skills/mobile-design/mobile-typography.md +433 -0
- package/kit/skills/mobile-design/platform-android.md +666 -0
- package/kit/skills/mobile-design/platform-ios.md +561 -0
- package/kit/skills/mobile-design/scripts/mobile_audit.py +670 -0
- package/kit/skills/mobile-design/touch-psychology.md +537 -0
- package/kit/skills/negocio-agente-conversa/SKILL.md +168 -0
- package/kit/skills/negocio-atendimento/SKILL.md +134 -0
- package/kit/skills/negocio-linguagem/SKILL.md +166 -0
- package/kit/skills/negocio-preco/SKILL.md +174 -0
- package/kit/skills/negocio-preco/scripts/preco.mjs +160 -0
- package/kit/skills/negocio-qualificacao/SKILL.md +140 -0
- package/kit/skills/nextjs-react-expert/1-async-eliminating-waterfalls.md +351 -0
- package/kit/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md +240 -0
- package/kit/skills/nextjs-react-expert/3-server-server-side-performance.md +490 -0
- package/kit/skills/nextjs-react-expert/4-client-client-side-data-fetching.md +264 -0
- package/kit/skills/nextjs-react-expert/5-rerender-re-render-optimization.md +581 -0
- package/kit/skills/nextjs-react-expert/6-rendering-rendering-performance.md +432 -0
- package/kit/skills/nextjs-react-expert/7-js-javascript-performance.md +684 -0
- package/kit/skills/nextjs-react-expert/8-advanced-advanced-patterns.md +150 -0
- package/kit/skills/nextjs-react-expert/9-cache-components.md +103 -0
- package/kit/skills/nextjs-react-expert/SKILL.md +308 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/common-patterns.md +331 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/complete-examples.md +872 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/component-patterns.md +502 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/data-fetching.md +767 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/file-organization.md +502 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/loading-and-error-states.md +501 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/performance.md +406 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/routing-guide.md +364 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/styling-guide.md +428 -0
- package/kit/skills/nextjs-react-expert/resources/app-patterns/typescript-standards.md +418 -0
- package/kit/skills/nextjs-react-expert/scripts/convert_rules.py +222 -0
- package/kit/skills/nextjs-react-expert/scripts/react_performance_checker.py +252 -0
- package/kit/skills/nodejs-best-practices/SKILL.md +78 -0
- package/kit/skills/nodejs-best-practices/references/10-anti-patterns-to-avoid.md +21 -0
- package/kit/skills/nodejs-best-practices/references/11-decision-checklist.md +14 -0
- package/kit/skills/nodejs-best-practices/references/2-runtime-considerations-2025.md +36 -0
- package/kit/skills/nodejs-best-practices/references/3-architecture-principles.md +35 -0
- package/kit/skills/nodejs-best-practices/references/4-error-handling-principles.md +42 -0
- package/kit/skills/nodejs-best-practices/references/5-async-patterns-principles.md +35 -0
- package/kit/skills/nodejs-best-practices/references/6-validation-principles.md +29 -0
- package/kit/skills/nodejs-best-practices/references/7-security-principles.md +29 -0
- package/kit/skills/nodejs-best-practices/references/8-testing-principles.md +28 -0
- package/kit/skills/observability-and-instrumentation/SKILL.md +150 -0
- package/kit/skills/opencode-go-exec/SKILL.md +101 -0
- package/kit/skills/parallel-agents/SKILL.md +184 -0
- package/kit/skills/performance-profiling/SKILL.md +145 -0
- package/kit/skills/performance-profiling/scripts/lighthouse_audit.py +76 -0
- package/kit/skills/plan-writing/SKILL.md +213 -0
- package/kit/skills/powershell-windows/SKILL.md +196 -0
- package/kit/skills/provider-orchestration/SKILL.md +269 -0
- package/kit/skills/python-patterns/SKILL.md +80 -0
- package/kit/skills/python-patterns/references/10-decision-checklist.md +14 -0
- package/kit/skills/python-patterns/references/11-anti-patterns-to-avoid.md +20 -0
- package/kit/skills/python-patterns/references/2-async-vs-sync-decision.md +44 -0
- package/kit/skills/python-patterns/references/3-type-hints-strategy.md +56 -0
- package/kit/skills/python-patterns/references/4-project-structure-principles.md +56 -0
- package/kit/skills/python-patterns/references/5-django-principles-2025.md +40 -0
- package/kit/skills/python-patterns/references/6-fastapi-principles.md +50 -0
- package/kit/skills/python-patterns/references/7-background-tasks.md +31 -0
- package/kit/skills/python-patterns/references/8-error-handling-principles.md +29 -0
- package/kit/skills/python-patterns/references/9-testing-principles.md +37 -0
- package/kit/skills/red-team-tactics/SKILL.md +201 -0
- package/kit/skills/research/SKILL.md +166 -0
- package/kit/skills/rust-pro/SKILL.md +177 -0
- package/kit/skills/seo-fundamentals/SKILL.md +130 -0
- package/kit/skills/seo-fundamentals/scripts/seo_checker.py +219 -0
- package/kit/skills/sequential-thinking/.env.example +8 -0
- package/kit/skills/sequential-thinking/README.md +183 -0
- package/kit/skills/sequential-thinking/SKILL.md +95 -0
- package/kit/skills/sequential-thinking/package.json +31 -0
- package/kit/skills/sequential-thinking/references/advanced-strategies.md +79 -0
- package/kit/skills/sequential-thinking/references/advanced-techniques.md +76 -0
- package/kit/skills/sequential-thinking/references/core-patterns.md +95 -0
- package/kit/skills/sequential-thinking/references/examples-api.md +88 -0
- package/kit/skills/sequential-thinking/references/examples-architecture.md +94 -0
- package/kit/skills/sequential-thinking/references/examples-debug.md +90 -0
- package/kit/skills/sequential-thinking/scripts/format-thought.js +159 -0
- package/kit/skills/sequential-thinking/scripts/process-thought.js +236 -0
- package/kit/skills/server-management/SKILL.md +162 -0
- package/kit/skills/simplify-code/SKILL.md +133 -0
- package/kit/skills/skillify/SKILL.md +116 -0
- package/kit/skills/system-design-interview/SKILL.md +268 -0
- package/kit/skills/systematic-debugging/SKILL.md +110 -0
- package/kit/skills/tailwind-patterns/SKILL.md +283 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/canvas-design-system.md +320 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/shadcn-accessibility.md +471 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/shadcn-components.md +424 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/shadcn-theming.md +373 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/tailwind-customization.md +483 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/tailwind-responsive.md +382 -0
- package/kit/skills/tailwind-patterns/references/shadcn-ui/tailwind-utilities.md +455 -0
- package/kit/skills/tdd-workflow/SKILL.md +150 -0
- package/kit/skills/testing-patterns/SKILL.md +196 -0
- package/kit/skills/testing-patterns/scripts/test_runner.py +219 -0
- package/kit/skills/ui-ux-pro-max/SKILL.md +135 -0
- package/kit/skills/verify-changes/SKILL.md +125 -0
- package/kit/skills/vulnerability-scanner/SKILL.md +278 -0
- package/kit/skills/vulnerability-scanner/checklists.md +121 -0
- package/kit/skills/vulnerability-scanner/scripts/security_scan.py +458 -0
- package/kit/skills/web-design-guidelines/SKILL.md +58 -0
- package/kit/skills/webapp-testing/NOTICE.md +6 -0
- package/kit/skills/webapp-testing/SKILL.md +188 -0
- package/kit/skills/webapp-testing/scripts/playwright_runner.py +173 -0
- package/kit/workflows/brainstorm.md +113 -0
- package/kit/workflows/coordinate.md +72 -0
- package/kit/workflows/create.md +59 -0
- package/kit/workflows/debug.md +103 -0
- package/kit/workflows/deploy.md +176 -0
- package/kit/workflows/enhance.md +63 -0
- package/kit/workflows/orchestrate.md +237 -0
- package/kit/workflows/plan.md +89 -0
- package/kit/workflows/preview.md +81 -0
- package/kit/workflows/remember.md +67 -0
- package/kit/workflows/status.md +86 -0
- package/kit/workflows/test.md +144 -0
- package/kit/workflows/ui-ux-pro-max.md +296 -0
- package/kit/workflows/verify.md +72 -0
- package/licenses/Apache-2.0.txt +202 -0
- package/package.json +60 -6
- package/scripts/archive-codex-rollouts.ps1 +35 -0
- package/scripts/avaliar-vigilancia-mandato.mjs +38 -0
- package/scripts/bundle.mjs +170 -0
- package/scripts/check-deps.mjs +178 -0
- package/scripts/check-models.mjs +150 -0
- package/scripts/cli.mjs +313 -0
- package/scripts/content-checks.mjs +18 -0
- package/scripts/continuidade-mandato.mjs +47 -0
- package/scripts/discriminar-turno.mjs +191 -0
- package/scripts/doctor.mjs +611 -0
- package/scripts/generate.mjs +688 -0
- package/scripts/install.mjs +11 -0
- package/scripts/layer-remote.mjs +407 -0
- package/scripts/layers.mjs +208 -0
- package/scripts/marketplace.mjs +77 -0
- package/scripts/product.mjs +32 -0
- package/scripts/ruleset-core.mjs +68 -0
- package/scripts/social-hooks.mjs +293 -0
- package/scripts/social-pacer.mjs +219 -0
- package/scripts/validate-bundles.mjs +14 -0
- package/scripts/validate-skills.mjs +174 -0
- package/scripts/zenkit-daemon-task.cmd +3 -0
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: observability-and-instrumentation
|
|
3
|
+
description: Instrument production systems with structured logging, meaningful metrics, real health checks, and actionable alerts — without leaking secrets or drowning on-call in noise.
|
|
4
|
+
when_to_use: "When adding logging, metrics, health checks, or alerts to a service. When the user says 'add observability', 'instrument this', 'set up monitoring', 'what should we log?', or when preparing a service for production. NOT for writing business logic — for making runtime behavior visible and debuggable."
|
|
5
|
+
allowed-tools: Read, Glob, Grep
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Observability and Instrumentation
|
|
9
|
+
|
|
10
|
+
> Logs are written on deploy day but read at 3 AM during an outage. If a log line cannot answer *what broke, where, and for which request*, it is decoration.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 1. The 3 AM Test
|
|
15
|
+
|
|
16
|
+
At 3 AM, with the service down and a pager firing, nobody reads your source code. They read logs, metrics, and traces.
|
|
17
|
+
|
|
18
|
+
| Question every log line must answer | Bad | Good |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| What happened? | `"something went wrong"` | `"payment_capture_failed"` |
|
|
21
|
+
| Where? | `"error in handler"` | `"service=payments handler=capture"` |
|
|
22
|
+
| For whom? | *(missing)* | `"request_id=req_8f2a user_id=usr_42"` |
|
|
23
|
+
|
|
24
|
+
Interpolated prose (`User ${id} failed to pay`) is useless to a log aggregator. **Structured fields** are queryable at 3 AM.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 2. Structured Logging and Correlation
|
|
29
|
+
|
|
30
|
+
```json
|
|
31
|
+
{
|
|
32
|
+
"level": "error",
|
|
33
|
+
"event": "payment_capture_failed",
|
|
34
|
+
"request_id": "req_8f2a",
|
|
35
|
+
"trace_id": "tr_9c1b",
|
|
36
|
+
"user_id": "usr_42",
|
|
37
|
+
"error": "card_declined",
|
|
38
|
+
"latency_ms": 842
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
**Distributed Tracing (W3C TraceContext & OpenTelemetry):**
|
|
43
|
+
Propagate standard W3C headers (`traceparent`, `tracestate`) across all HTTP calls, queues, and background jobs. In high-throughput systems, apply **head-based or tail-based sampling** (e.g. 1-10% of successful traces, 100% of errors) to prevent CPU and telemetry storage saturation. Keep high-cardinality IDs (`user_id`, `request_id`) in structured logs and span attributes, never as raw metric dimensions.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 3. Never Log This
|
|
48
|
+
|
|
49
|
+
Logs are copied to third parties, indexed indefinitely, and read by people who should not see the data.
|
|
50
|
+
|
|
51
|
+
| Never log | Why |
|
|
52
|
+
|---|---|
|
|
53
|
+
| Passwords, tokens, API keys | Credential leak via log pipeline |
|
|
54
|
+
| Full request/response bodies | May contain PII or secrets |
|
|
55
|
+
| Credit card numbers, SSN, health data | Compliance violation |
|
|
56
|
+
| Session cookies | Session hijack vector |
|
|
57
|
+
|
|
58
|
+
Log **identifiers and outcomes**, not payloads. `user_id=42 payment_status=declined` — not the full Stripe response.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 4. Log Levels With Real Meaning
|
|
63
|
+
|
|
64
|
+
| Level | Meaning | Example |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| `error` | Someone must act — request failed, data lost | DB connection refused |
|
|
67
|
+
| `warn` | Degraded but continued — retry succeeded, fallback used | Cache miss, served from DB |
|
|
68
|
+
| `info` | Normal business events worth auditing | Order placed, user signed up |
|
|
69
|
+
| `debug` | Development detail — off in production | SQL query text |
|
|
70
|
+
|
|
71
|
+
If everything is `error`, nothing is. On-call learns to ignore all alerts — including the real ones.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 5. The Four Metrics That Almost Always Suffice
|
|
76
|
+
|
|
77
|
+
Start here before building custom dashboards:
|
|
78
|
+
|
|
79
|
+
| Metric | What it tells you | Trap |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| **Request rate** | Traffic volume, capacity planning | Spikes without error context mislead |
|
|
82
|
+
| **Error rate** | % of requests failing | Averaging hides partial outages |
|
|
83
|
+
| **Latency** (p50 / p95 / p99) | User experience | **Mean hides tail latency** — p99 at 5s while mean is 200ms means real users suffer |
|
|
84
|
+
| **Saturation** | CPU, memory, connections, queue depth | 100% CPU with low latency is fine; 60% with high latency is not |
|
|
85
|
+
|
|
86
|
+
**Percentiles show the problem averages hide.** Alert on p95/p99, not mean.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 6. Health Checks That Actually Check
|
|
91
|
+
|
|
92
|
+
| Type | Purpose | Must verify |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| **Liveness** | Process alive — restart if dead | Process responds (cheap) |
|
|
95
|
+
| **Readiness** | Can serve traffic — remove from load balancer if not | DB connection, cache, critical dependencies |
|
|
96
|
+
|
|
97
|
+
An endpoint returning `200 OK` without touching the database is a **decoration**, not a health check. Readiness that passes while the DB is down sends traffic to a broken instance.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## 7. Alerts Only Where There Is Action
|
|
102
|
+
|
|
103
|
+
Every alert needs three parts:
|
|
104
|
+
|
|
105
|
+
1. **What broke** — `payment_error_rate > 5% for 5m`
|
|
106
|
+
2. **Impact** — `~200 users/min cannot complete checkout`
|
|
107
|
+
3. **What to do** — `check Stripe status page, rollback if deploy < 30m ago`
|
|
108
|
+
|
|
109
|
+
| Anti-pattern | Result |
|
|
110
|
+
|---|---|
|
|
111
|
+
| Alert on CPU > 80% with no runbook | On-call ignores it |
|
|
112
|
+
| Alert on every `error` log line | Alert fatigue |
|
|
113
|
+
| Alert with no owner or escalation | Incident rots |
|
|
114
|
+
|
|
115
|
+
An alert nobody acts on trains the team to ignore **all** alerts.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 8. Silence Is Not Success
|
|
120
|
+
|
|
121
|
+
No logs can mean "everything is fine" or "the process died and nothing is running." You cannot tell which without a **heartbeat** or **liveness probe**.
|
|
122
|
+
|
|
123
|
+
| Signal | Detects |
|
|
124
|
+
|---|---|
|
|
125
|
+
| Heartbeat metric every N seconds | Process stopped writing |
|
|
126
|
+
| Liveness probe | Container/process dead |
|
|
127
|
+
| Absence-of-data alert | Log pipeline or exporter broken |
|
|
128
|
+
|
|
129
|
+
Absence of errors is not proof of health — it may be proof of blindness.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 9. Instrument Before You Need It
|
|
134
|
+
|
|
135
|
+
After an incident, the data you wish you had **does not exist retroactively**. Add logging, metrics, and tracing when you write the code — not in the postmortem ticket.
|
|
136
|
+
|
|
137
|
+
```
|
|
138
|
+
❌ "We'll add metrics after launch" ✅ Structured fields + correlation ID on day one
|
|
139
|
+
❌ "Debug logging for now, clean up later" (never cleaned up)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Anti-Patterns
|
|
143
|
+
|
|
144
|
+
| Anti-pattern | Why it fails | Fix |
|
|
145
|
+
|---|---|---|
|
|
146
|
+
| `console.log("error:", err)` | Unqueryable, no correlation | Structured JSON with `request_id` |
|
|
147
|
+
| Mean latency in dashboards | Hides tail pain | p50/p95/p99 histograms |
|
|
148
|
+
| `/health` returns 200 always | Load balancer sends traffic to dead instances | Readiness checks real dependencies |
|
|
149
|
+
| Logging full request bodies | PII leak, compliance risk | Log IDs and status codes only |
|
|
150
|
+
| Alert on every threshold | Fatigue → ignored pages | Alert on SLO breach with runbook |
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: opencode-go-exec
|
|
3
|
+
description: Run OpenCode Go headless as an optional writer or investigator. Pin opencode-go/deepseek-v4-flash. Isolate in a worktree. --auto only for writes. Never merge. Not the default executor — Cursor composer-2.5 is.
|
|
4
|
+
when_to_use: "When the human operator explicitly asks for OpenCode Go or ZENKIT_EXECUTOR=opencode-go; when dispatch_handoff is called with executor opencode-go. NOT the default typist (use cursor-exec / dispatch_handoff). NOT for planning, NOT for merge."
|
|
5
|
+
allowed-tools: Read, Glob, Grep, Bash
|
|
6
|
+
effort: medium
|
|
7
|
+
---
|
|
8
|
+
## Política obrigatória de executores — DEM-ZEN-SEC-35
|
|
9
|
+
|
|
10
|
+
Únicas combinações permitidas para tarefas executadas ou investigadas por CLI: Codex `gpt-6-luna` com esforço `low`; Claude `claude-haiku-5-5` com `--effort low`; Cursor `composer-2.5`; OpenCode Go `opencode-go/deepseek-v4.1-flash`. Não trocar modelo por variável, fallback, tier ou preço. Se o modelo não estiver disponível, falhar e informar; não substituir. Esta política prevalece sobre exemplos anteriores neste documento.
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
# opencode-go-exec — OpenCode Go CLI as optional writer / investigator
|
|
14
|
+
|
|
15
|
+
> OpenCode Go in print mode types and looks when the operator opts in. Default
|
|
16
|
+
> bulk execution is Cursor `composer-2.5` (`cursor-exec` / `dispatch_handoff`).
|
|
17
|
+
> This skill is the **OpenCode argv and traps**. Load `git-worktrees` before the
|
|
18
|
+
> first write and `provider-orchestration` for the ritual.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 1. Binary and model (pin, do not drift)
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
OPENCODE_BIN="${OPENCODE_BIN:-opencode}"
|
|
26
|
+
MODEL="opencode-go/deepseek-v4-flash" # house cheap model; must pass $2/1M cap
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Probe the binary; fail honestly if missing. Never omit `--model`.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 2. Headless write recipe
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
cd "$WORKTREE"
|
|
37
|
+
"$OPENCODE_BIN" run "$(cat PLAN.md)" \
|
|
38
|
+
--format json \
|
|
39
|
+
--auto \
|
|
40
|
+
--model opencode-go/deepseek-v4-flash \
|
|
41
|
+
--dir "$WORKTREE"
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
| Flag | Why |
|
|
45
|
+
|---|---|
|
|
46
|
+
| `run` | Non-interactive one-shot |
|
|
47
|
+
| `--format json` | Machine-readable result |
|
|
48
|
+
| `--auto` | Apply edits for **write** jobs only — omit for read/investigate |
|
|
49
|
+
| `--model` | Pinned cheap model (cap-checked in zenkit-bridge) |
|
|
50
|
+
| `--dir` | Working tree root (same as `cd`) |
|
|
51
|
+
|
|
52
|
+
Read / investigate (no file changes intended):
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
"$OPENCODE_BIN" run "$(cat PLAN.md)" \
|
|
56
|
+
--format json \
|
|
57
|
+
--model opencode-go/deepseek-v4-flash \
|
|
58
|
+
--dir "$WORKTREE"
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
No `--auto` in read mode.
|
|
62
|
+
|
|
63
|
+
Contain the process: process group + wall-clock timeout (see bridge
|
|
64
|
+
`ZENKIT_DISPATCH_TIMEOUT_SECONDS`, default 1800s).
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 3. What you review afterwards
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
git -C "$WORKTREE" status --short
|
|
72
|
+
git -C "$WORKTREE" diff
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Trust the diff over CLI narrative JSON.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## 4. Cost pin (hard)
|
|
80
|
+
|
|
81
|
+
- Default executor for the kit is **not** OpenCode Go — it is Cursor `composer-2.5`.
|
|
82
|
+
- Use this skill only when the human asked or `ZENKIT_EXECUTOR=opencode-go`.
|
|
83
|
+
- Model must stay within the house $2/1M (in+out) cap for per-token providers.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## 5. Traps
|
|
88
|
+
|
|
89
|
+
**`--auto` on a read job** — can mutate files when you only wanted investigation.
|
|
90
|
+
|
|
91
|
+
**Shared working tree** — always isolate in a git worktree; never type on the conductor tree.
|
|
92
|
+
|
|
93
|
+
**Assuming OpenCode is installed** — `command -v opencode` (or `OPENCODE_BIN`) before dispatch.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 6. When not to use this
|
|
98
|
+
|
|
99
|
+
- Default plan execution — use `dispatch_handoff` / `cursor-exec` with `composer-2.5`.
|
|
100
|
+
- Judgement the plan did not already encode — conductor or plan first.
|
|
101
|
+
- Human did not opt into OpenCode Go this turn.
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: parallel-agents
|
|
3
|
+
description: Multi-agent orchestration patterns. Use when multiple independent tasks can run with different domain expertise or when comprehensive analysis requires multiple perspectives.
|
|
4
|
+
when_to_use: "When a task requires 2+ specialist agents, comprehensive multi-domain analysis, or coordinated parallel execution. Use with /orchestrate or /coordinate workflows. NOT for single-domain tasks where one agent suffices."
|
|
5
|
+
allowed-tools: Read, Glob, Grep
|
|
6
|
+
effort: medium
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Native Parallel Agents
|
|
10
|
+
|
|
11
|
+
> Orchestration through ZenKit's built-in Agent Tool
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
This skill enables coordinating multiple specialized agents through ZenKit's native agent system. Unlike external scripts, this approach keeps all orchestration within ZenKit's control.
|
|
16
|
+
|
|
17
|
+
**Same runtime.** If the second worker is another CLI (`cursor-agent`, `claude -p`, `codex exec`), that is `provider-orchestration`, not this skill.
|
|
18
|
+
|
|
19
|
+
## When to Use Orchestration
|
|
20
|
+
|
|
21
|
+
✅ **Good for:**
|
|
22
|
+
- Complex tasks requiring multiple expertise domains
|
|
23
|
+
- Code analysis from security, performance, and quality perspectives
|
|
24
|
+
- Comprehensive reviews (architecture + security + testing)
|
|
25
|
+
- Feature implementation needing backend + frontend + database work
|
|
26
|
+
|
|
27
|
+
❌ **Not for:**
|
|
28
|
+
- Simple, single-domain tasks
|
|
29
|
+
- Quick fixes or small changes
|
|
30
|
+
- Tasks where one agent suffices
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Native Agent Invocation
|
|
35
|
+
|
|
36
|
+
### Single Agent
|
|
37
|
+
```
|
|
38
|
+
Use the security-auditor agent to review authentication
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Sequential Chain
|
|
42
|
+
```
|
|
43
|
+
First, use the explorer-agent to discover project structure.
|
|
44
|
+
Then, use the backend-specialist to review API endpoints.
|
|
45
|
+
Finally, use the test-engineer to identify test gaps.
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### With Context Passing
|
|
49
|
+
```
|
|
50
|
+
Use the frontend-specialist to analyze React components.
|
|
51
|
+
Based on those findings, have the test-engineer generate component tests.
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Resume Previous Work
|
|
55
|
+
```
|
|
56
|
+
Resume agent [agentId] and continue with additional requirements.
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Orchestration Patterns
|
|
62
|
+
|
|
63
|
+
### Pattern 1: Comprehensive Analysis
|
|
64
|
+
```
|
|
65
|
+
Agents: explorer-agent → [domain-agents] → synthesis
|
|
66
|
+
|
|
67
|
+
1. explorer-agent: Map codebase structure
|
|
68
|
+
2. security-auditor: Security posture
|
|
69
|
+
3. backend-specialist: API quality
|
|
70
|
+
4. frontend-specialist: UI/UX patterns
|
|
71
|
+
5. test-engineer: Test coverage
|
|
72
|
+
6. Synthesize all findings
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Pattern 2: Feature Review
|
|
76
|
+
```
|
|
77
|
+
Agents: affected-domain-agents → test-engineer
|
|
78
|
+
|
|
79
|
+
1. Identify affected domains (backend? frontend? both?)
|
|
80
|
+
2. Invoke relevant domain agents
|
|
81
|
+
3. test-engineer verifies changes
|
|
82
|
+
4. Synthesize recommendations
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Pattern 3: Security Audit
|
|
86
|
+
```
|
|
87
|
+
Agents: security-auditor → penetration-tester → synthesis
|
|
88
|
+
|
|
89
|
+
1. security-auditor: Configuration and code review
|
|
90
|
+
2. penetration-tester: Active vulnerability testing
|
|
91
|
+
3. Synthesize with prioritized remediation
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Available Agents
|
|
97
|
+
|
|
98
|
+
| Agent | Expertise | Trigger Phrases |
|
|
99
|
+
|-------|-----------|-----------------|
|
|
100
|
+
| `orchestrator` | Coordination | "comprehensive", "multi-perspective" |
|
|
101
|
+
| `security-auditor` | Security | "security", "auth", "vulnerabilities" |
|
|
102
|
+
| `penetration-tester` | Security Testing | "pentest", "red team", "exploit" |
|
|
103
|
+
| `backend-specialist` | Backend | "API", "server", "Node.js", "Express" |
|
|
104
|
+
| `frontend-specialist` | Frontend | "React", "UI", "components", "Next.js" |
|
|
105
|
+
| `test-engineer` | Testing | "tests", "coverage", "TDD" |
|
|
106
|
+
| `devops-engineer` | DevOps | "deploy", "CI/CD", "infrastructure" |
|
|
107
|
+
| `database-architect` | Database | "schema", "Prisma", "migrations" |
|
|
108
|
+
| `mobile-developer` | Mobile | "React Native", "Flutter", "mobile" |
|
|
109
|
+
| `api-designer` | API Design | "REST", "GraphQL", "OpenAPI" |
|
|
110
|
+
| `debugger` | Debugging | "bug", "error", "not working" |
|
|
111
|
+
| `explorer-agent` | Discovery | "explore", "map", "structure" |
|
|
112
|
+
| `documentation-writer` | Documentation | "write docs", "create README", "generate API docs" |
|
|
113
|
+
| `performance-optimizer` | Performance | "slow", "optimize", "profiling" |
|
|
114
|
+
| `project-planner` | Planning | "plan", "roadmap", "milestones" |
|
|
115
|
+
| `seo-specialist` | SEO | "SEO", "meta tags", "search ranking" |
|
|
116
|
+
| `game-developer` | Game Development | "game", "Unity", "Godot", "Phaser" |
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## ZenKit Built-in Agents
|
|
121
|
+
|
|
122
|
+
These work alongside custom agents:
|
|
123
|
+
|
|
124
|
+
| Agent | Model | Purpose |
|
|
125
|
+
|-------|-------|---------|
|
|
126
|
+
| **Explore** | Haiku | Fast read-only codebase search |
|
|
127
|
+
| **Plan** | Sonnet | Research during plan mode |
|
|
128
|
+
| **General-purpose** | Sonnet | Complex multi-step modifications |
|
|
129
|
+
|
|
130
|
+
Use **Explore** for quick searches, **custom agents** for domain expertise.
|
|
131
|
+
|
|
132
|
+
> Cost cap: a cheap/typist model must cost ≤ $2 per 1M tokens (in+out, models.dev).
|
|
133
|
+
> Haiku (~$6) is not cheap — prefer `opencode-go-exec` (`opencode-go/deepseek-v4-flash`)
|
|
134
|
+
> for cheap typing. See `model-routing.mdc`.
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## Synthesis Protocol
|
|
139
|
+
|
|
140
|
+
After all agents complete, synthesize:
|
|
141
|
+
|
|
142
|
+
```markdown
|
|
143
|
+
## Orchestration Synthesis
|
|
144
|
+
|
|
145
|
+
### Task Summary
|
|
146
|
+
[What was accomplished]
|
|
147
|
+
|
|
148
|
+
### Agent Contributions
|
|
149
|
+
| Agent | Finding |
|
|
150
|
+
|-------|---------|
|
|
151
|
+
| security-auditor | Found X |
|
|
152
|
+
| backend-specialist | Identified Y |
|
|
153
|
+
|
|
154
|
+
### Consolidated Recommendations
|
|
155
|
+
1. **Critical**: [Issue from Agent A]
|
|
156
|
+
2. **Important**: [Issue from Agent B]
|
|
157
|
+
3. **Nice-to-have**: [Enhancement from Agent C]
|
|
158
|
+
|
|
159
|
+
### Action Items
|
|
160
|
+
- [ ] Fix critical security issue
|
|
161
|
+
- [ ] Refactor API endpoint
|
|
162
|
+
- [ ] Add missing tests
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Best Practices & Concurrency Limits
|
|
168
|
+
|
|
169
|
+
1. **Max Concurrency Ceiling:** Limit simultaneous background agents to **2-4** (never dispatch 5+ concurrently to prevent rate-limit 429 cascades and host I/O saturation).
|
|
170
|
+
2. **Explicit Timeouts & Deadlines:** Set a per-agent timeout (default 300s). Do not block indefinitely waiting on a slow subagent.
|
|
171
|
+
3. **Structured Handoff:** Pass only necessary findings and explicit file paths to child agents, avoiding context bloat.
|
|
172
|
+
4. **Logical Order:** Discovery → Analysis → Implementation → Testing.
|
|
173
|
+
5. **Unified Synthesis:** One consolidated report with clear trade-offs and explicit recommendations.
|
|
174
|
+
6. **Workspace Isolation:** For tasks with code mutations, delegate to separate git worktrees (`git-worktrees`) rather than letting multiple writers modify the same working tree simultaneously.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Key Benefits
|
|
179
|
+
|
|
180
|
+
- ✅ **Single session** - All agents share context
|
|
181
|
+
- ✅ **AI-controlled** - Claude orchestrates autonomously
|
|
182
|
+
- ✅ **Native integration** - Works with built-in Explore, Plan agents
|
|
183
|
+
- ✅ **Resume support** - Can continue previous agent work
|
|
184
|
+
- ✅ **Context passing** - Findings flow between agents
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: performance-profiling
|
|
3
|
+
description: Performance profiling principles. Measurement, analysis, and optimization techniques.
|
|
4
|
+
when_to_use: "When diagnosing performance issues, running Lighthouse audits, analyzing bundle size, or optimizing Core Web Vitals."
|
|
5
|
+
allowed-tools: Read, Glob, Grep, Bash
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Performance Profiling
|
|
9
|
+
|
|
10
|
+
> Measure, analyze, optimize - in that order.
|
|
11
|
+
|
|
12
|
+
## 🔧 Runtime Scripts
|
|
13
|
+
|
|
14
|
+
**Execute these for automated profiling:**
|
|
15
|
+
|
|
16
|
+
| Script | Purpose | Usage |
|
|
17
|
+
|--------|---------|-------|
|
|
18
|
+
| `scripts/lighthouse_audit.py` | Lighthouse performance audit | `python scripts/lighthouse_audit.py https://example.com` |
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 1. Core Web Vitals
|
|
23
|
+
|
|
24
|
+
### Targets
|
|
25
|
+
|
|
26
|
+
| Metric | Good | Poor | Measures |
|
|
27
|
+
|--------|------|------|----------|
|
|
28
|
+
| **LCP** | < 2.5s | > 4.0s | Loading |
|
|
29
|
+
| **INP** | < 200ms | > 500ms | Interactivity |
|
|
30
|
+
| **CLS** | < 0.1 | > 0.25 | Stability |
|
|
31
|
+
|
|
32
|
+
### When to Measure
|
|
33
|
+
|
|
34
|
+
| Stage | Tool |
|
|
35
|
+
|-------|------|
|
|
36
|
+
| Development | Local Lighthouse |
|
|
37
|
+
| CI/CD | Lighthouse CI |
|
|
38
|
+
| Production | RUM (Real User Monitoring) |
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 2. Profiling Workflow
|
|
43
|
+
|
|
44
|
+
### The 4-Step Process
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
1. BASELINE → Measure current state
|
|
48
|
+
2. IDENTIFY → Find the bottleneck
|
|
49
|
+
3. FIX → Make targeted change
|
|
50
|
+
4. VALIDATE → Confirm improvement
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Profiling Tool Selection
|
|
54
|
+
|
|
55
|
+
| Domain | Problem | Tool |
|
|
56
|
+
|--------|---------|------|
|
|
57
|
+
| **Frontend** | Page load / CWV | Lighthouse / Web Vitals RUM |
|
|
58
|
+
| **Frontend** | Bundle size | Bundle analyzer / Source map explorer |
|
|
59
|
+
| **Frontend** | Browser runtime & frames | Chrome DevTools Performance / Memory |
|
|
60
|
+
| **Backend / Systems** | CPU hotspots / Off-CPU wait | Continuous profiler (pprof, async-profiler, py-spy, perf) |
|
|
61
|
+
| **Backend / Systems** | Heap leaks & GC pressure | Heap dumps / GC logs (trace GC pauses) |
|
|
62
|
+
| **Backend / Systems** | Database & I/O contention | Slow query log, `EXPLAIN (ANALYZE, BUFFERS)`, connection pool metrics |
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## 3. Bundle Analysis
|
|
67
|
+
|
|
68
|
+
### What to Look For
|
|
69
|
+
|
|
70
|
+
| Issue | Indicator |
|
|
71
|
+
|-------|-----------|
|
|
72
|
+
| Large dependencies | Top of bundle |
|
|
73
|
+
| Duplicate code | Multiple chunks |
|
|
74
|
+
| Unused code | Low coverage |
|
|
75
|
+
| Missing splits | Single large chunk |
|
|
76
|
+
|
|
77
|
+
### Optimization Actions
|
|
78
|
+
|
|
79
|
+
| Finding | Action |
|
|
80
|
+
|---------|--------|
|
|
81
|
+
| Big library | Import specific modules |
|
|
82
|
+
| Duplicate deps | Dedupe, update versions |
|
|
83
|
+
| Route in main | Code split |
|
|
84
|
+
| Unused exports | Tree shake |
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 4. Runtime Profiling
|
|
89
|
+
|
|
90
|
+
### Performance Tab Analysis
|
|
91
|
+
|
|
92
|
+
| Pattern | Meaning |
|
|
93
|
+
|---------|---------|
|
|
94
|
+
| Long tasks (>50ms) | UI blocking |
|
|
95
|
+
| Many small tasks | Possible batching opportunity |
|
|
96
|
+
| Layout/paint | Rendering bottleneck |
|
|
97
|
+
| Script | JavaScript execution |
|
|
98
|
+
|
|
99
|
+
### Memory Tab Analysis
|
|
100
|
+
|
|
101
|
+
| Pattern | Meaning |
|
|
102
|
+
|---------|---------|
|
|
103
|
+
| Growing heap | Possible leak |
|
|
104
|
+
| Large retained | Check references |
|
|
105
|
+
| Detached DOM | Not cleaned up |
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## 5. Common Bottlenecks
|
|
110
|
+
|
|
111
|
+
### By Symptom
|
|
112
|
+
|
|
113
|
+
| Symptom | Likely Cause |
|
|
114
|
+
|---------|--------------|
|
|
115
|
+
| Slow initial load | Large JS, render blocking |
|
|
116
|
+
| Slow interactions | Heavy event handlers |
|
|
117
|
+
| Jank during scroll | Layout thrashing |
|
|
118
|
+
| Growing memory | Leaks, retained refs |
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 6. Quick Win Priorities
|
|
123
|
+
|
|
124
|
+
| Priority | Action | Impact |
|
|
125
|
+
|----------|--------|--------|
|
|
126
|
+
| 1 | Enable compression | High |
|
|
127
|
+
| 2 | Lazy load images | High |
|
|
128
|
+
| 3 | Code split routes | High |
|
|
129
|
+
| 4 | Cache static assets | Medium |
|
|
130
|
+
| 5 | Optimize images | Medium |
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 7. Anti-Patterns
|
|
135
|
+
|
|
136
|
+
| ❌ Don't | ✅ Do |
|
|
137
|
+
|----------|-------|
|
|
138
|
+
| Guess at problems | Profile first |
|
|
139
|
+
| Micro-optimize | Fix biggest issue |
|
|
140
|
+
| Optimize early | Optimize when needed |
|
|
141
|
+
| Ignore real users | Use RUM data |
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
> **Remember:** The fastest code is code that doesn't run. Remove before optimizing.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
Skill: performance-profiling
|
|
4
|
+
Script: lighthouse_audit.py
|
|
5
|
+
Purpose: Run Lighthouse performance audit on a URL
|
|
6
|
+
Usage: python lighthouse_audit.py https://example.com
|
|
7
|
+
Output: JSON with performance scores
|
|
8
|
+
Note: Requires lighthouse CLI (npm install -g lighthouse)
|
|
9
|
+
"""
|
|
10
|
+
import subprocess
|
|
11
|
+
import json
|
|
12
|
+
import sys
|
|
13
|
+
import os
|
|
14
|
+
import tempfile
|
|
15
|
+
|
|
16
|
+
def run_lighthouse(url: str) -> dict:
|
|
17
|
+
"""Run Lighthouse audit on URL."""
|
|
18
|
+
try:
|
|
19
|
+
with tempfile.NamedTemporaryFile(suffix='.json', delete=False) as f:
|
|
20
|
+
output_path = f.name
|
|
21
|
+
|
|
22
|
+
result = subprocess.run(
|
|
23
|
+
[
|
|
24
|
+
"lighthouse",
|
|
25
|
+
url,
|
|
26
|
+
"--output=json",
|
|
27
|
+
f"--output-path={output_path}",
|
|
28
|
+
"--chrome-flags=--headless",
|
|
29
|
+
"--only-categories=performance,accessibility,best-practices,seo"
|
|
30
|
+
],
|
|
31
|
+
capture_output=True,
|
|
32
|
+
text=True,
|
|
33
|
+
timeout=120
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
if os.path.exists(output_path):
|
|
37
|
+
with open(output_path, 'r') as f:
|
|
38
|
+
report = json.load(f)
|
|
39
|
+
os.unlink(output_path)
|
|
40
|
+
|
|
41
|
+
categories = report.get("categories", {})
|
|
42
|
+
return {
|
|
43
|
+
"url": url,
|
|
44
|
+
"scores": {
|
|
45
|
+
"performance": int(categories.get("performance", {}).get("score", 0) * 100),
|
|
46
|
+
"accessibility": int(categories.get("accessibility", {}).get("score", 0) * 100),
|
|
47
|
+
"best_practices": int(categories.get("best-practices", {}).get("score", 0) * 100),
|
|
48
|
+
"seo": int(categories.get("seo", {}).get("score", 0) * 100)
|
|
49
|
+
},
|
|
50
|
+
"summary": get_summary(categories)
|
|
51
|
+
}
|
|
52
|
+
else:
|
|
53
|
+
return {"error": "Lighthouse failed to generate report", "stderr": result.stderr[:500]}
|
|
54
|
+
|
|
55
|
+
except subprocess.TimeoutExpired:
|
|
56
|
+
return {"error": "Lighthouse audit timed out"}
|
|
57
|
+
except FileNotFoundError:
|
|
58
|
+
return {"error": "Lighthouse CLI not found. Install with: npm install -g lighthouse"}
|
|
59
|
+
|
|
60
|
+
def get_summary(categories: dict) -> str:
|
|
61
|
+
"""Generate summary based on scores."""
|
|
62
|
+
perf = categories.get("performance", {}).get("score", 0) * 100
|
|
63
|
+
if perf >= 90:
|
|
64
|
+
return "[OK] Excellent performance"
|
|
65
|
+
elif perf >= 50:
|
|
66
|
+
return "[!] Needs improvement"
|
|
67
|
+
else:
|
|
68
|
+
return "[X] Poor performance"
|
|
69
|
+
|
|
70
|
+
if __name__ == "__main__":
|
|
71
|
+
if len(sys.argv) < 2:
|
|
72
|
+
print(json.dumps({"error": "Usage: python lighthouse_audit.py <url>"}))
|
|
73
|
+
sys.exit(1)
|
|
74
|
+
|
|
75
|
+
result = run_lighthouse(sys.argv[1])
|
|
76
|
+
print(json.dumps(result, indent=2))
|