@zenrick/zenkit 0.0.0-stage → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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/avaliar-vigilancia-mandato.mjs +38 -0
- package/scripts/bundle.mjs +158 -0
- package/scripts/check-deps.mjs +178 -0
- package/scripts/check-models.mjs +150 -0
- package/scripts/cli.mjs +295 -0
- package/scripts/continuidade-mandato.mjs +47 -0
- package/scripts/discriminar-turno.mjs +191 -0
- package/scripts/doctor.mjs +615 -0
- package/scripts/generate.mjs +676 -0
- package/scripts/install.mjs +11 -0
- package/scripts/layer-remote.mjs +344 -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,213 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: plan-writing
|
|
3
|
+
description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
|
|
4
|
+
when_to_use: "When creating structured task plans, breaking down features into tasks, or defining verification criteria. Use with /plan workflow."
|
|
5
|
+
allowed-tools: Read, Glob, Grep
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Plan Writing
|
|
9
|
+
|
|
10
|
+
> Source: obra/superpowers
|
|
11
|
+
|
|
12
|
+
## Overview
|
|
13
|
+
This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
|
|
14
|
+
|
|
15
|
+
## Task Breakdown Principles
|
|
16
|
+
|
|
17
|
+
### 1. Small, Focused Tasks
|
|
18
|
+
- Each task should take 2-5 minutes
|
|
19
|
+
- One clear outcome per task
|
|
20
|
+
- Independently verifiable
|
|
21
|
+
|
|
22
|
+
### 2. Clear Verification
|
|
23
|
+
- How do you know it's done?
|
|
24
|
+
- What can you check/test?
|
|
25
|
+
- What's the expected output?
|
|
26
|
+
|
|
27
|
+
### 3. Logical Ordering
|
|
28
|
+
- Dependencies identified
|
|
29
|
+
- Parallel work where possible
|
|
30
|
+
- Critical path highlighted
|
|
31
|
+
- **Phase X: Verification is always LAST**
|
|
32
|
+
|
|
33
|
+
### 4. Dynamic Naming in Project Root
|
|
34
|
+
- Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
|
|
35
|
+
- Name derived from task (e.g., "add auth" → `auth-feature.md`)
|
|
36
|
+
- **NEVER** inside `.claude/`, `docs/`, or temp folders
|
|
37
|
+
|
|
38
|
+
## Planning Principles (NOT Templates!)
|
|
39
|
+
|
|
40
|
+
> 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
|
|
41
|
+
|
|
42
|
+
### Principle 1: Keep It SHORT
|
|
43
|
+
|
|
44
|
+
| ❌ Wrong | ✅ Right |
|
|
45
|
+
|----------|----------|
|
|
46
|
+
| 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
|
|
47
|
+
| Every micro-step listed | Only actionable items |
|
|
48
|
+
| Verbose descriptions | One-line per task |
|
|
49
|
+
|
|
50
|
+
> **Rule:** If plan is longer than 1 page, it's too long. Simplify.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
### Principle 2: Be SPECIFIC, Not Generic
|
|
55
|
+
|
|
56
|
+
| ❌ Wrong | ✅ Right |
|
|
57
|
+
|----------|----------|
|
|
58
|
+
| "Set up project" | "Run `npx create-next-app`" |
|
|
59
|
+
| "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
|
|
60
|
+
| "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
|
|
61
|
+
|
|
62
|
+
> **Rule:** Each task should have a clear, verifiable outcome.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
### Principle 3: Dynamic Content Based on Project Type
|
|
67
|
+
|
|
68
|
+
**For NEW PROJECT:**
|
|
69
|
+
- What tech stack? (decide first)
|
|
70
|
+
- What's the MVP? (minimal features)
|
|
71
|
+
- What's the file structure?
|
|
72
|
+
|
|
73
|
+
**For FEATURE ADDITION:**
|
|
74
|
+
- Which files are affected?
|
|
75
|
+
- What dependencies needed?
|
|
76
|
+
- How to verify it works?
|
|
77
|
+
|
|
78
|
+
**For BUG FIX:**
|
|
79
|
+
- What's the root cause?
|
|
80
|
+
- What file/line to change?
|
|
81
|
+
- How to test the fix?
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
### Principle 4: Scripts Are Project-Specific
|
|
86
|
+
|
|
87
|
+
> 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
|
|
88
|
+
|
|
89
|
+
| Project Type | Relevant Scripts |
|
|
90
|
+
|--------------|------------------|
|
|
91
|
+
| Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
|
|
92
|
+
| Backend/API | `api_validator.py`, `security_scan.py` |
|
|
93
|
+
| Mobile | `mobile_audit.py` |
|
|
94
|
+
| Database | `schema_validator.py` |
|
|
95
|
+
| Full-stack | Mix of above based on what you touched |
|
|
96
|
+
|
|
97
|
+
**Wrong:** Adding all scripts to every plan
|
|
98
|
+
**Right:** Only scripts relevant to THIS task
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
### Principle 5: Verification is Simple
|
|
103
|
+
|
|
104
|
+
| ❌ Wrong | ✅ Right |
|
|
105
|
+
|----------|----------|
|
|
106
|
+
| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
|
|
107
|
+
| "Test the API" | "curl localhost:3000/api/users returns 200" |
|
|
108
|
+
| "Check styles" | "Open browser, verify dark mode toggle works" |
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
### Principle 6: At Least One Criterion a MACHINE Can Run
|
|
113
|
+
|
|
114
|
+
Specific is not the same as **runnable**. Both of these are specific:
|
|
115
|
+
|
|
116
|
+
| Criterion | Who can check it |
|
|
117
|
+
|-----------|------------------|
|
|
118
|
+
| "Open browser, verify dark mode toggle works" | a human, with eyes |
|
|
119
|
+
| `npm test -- theme.spec.ts` | a machine, exit code 0 |
|
|
120
|
+
|
|
121
|
+
Both belong in a plan. But a plan whose criteria are **all** of the first kind
|
|
122
|
+
has no gate — it has an opinion. Whoever reviews the diff has to re-derive
|
|
123
|
+
whether the work is done by reading it, and that judgement is exactly where a
|
|
124
|
+
review says "looks right" to code that isn't.
|
|
125
|
+
|
|
126
|
+
> **Rule:** every plan carries a `## Gate` block with **at least one command**
|
|
127
|
+
> that exits 0 when the work is done and non-zero when it is not. Not prose about
|
|
128
|
+
> testing — the command, copy-pasteable.
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
## Gate
|
|
132
|
+
Runnable (must exit 0):
|
|
133
|
+
- `npm test -- src/theme.spec.ts`
|
|
134
|
+
- `npm run typecheck`
|
|
135
|
+
|
|
136
|
+
By eye (human, after the gate is green):
|
|
137
|
+
- Dark mode toggle animates smoothly
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
**Why this ordering:** the machine checks run FIRST and gate the human's
|
|
141
|
+
attention. Reviewing pixels on a diff that does not compile wastes the scarcest
|
|
142
|
+
thing in the loop.
|
|
143
|
+
|
|
144
|
+
**If you cannot write a runnable command, the plan is not ready.** That is the
|
|
145
|
+
useful signal, not an obstacle: it means "done" is still undefined, and no
|
|
146
|
+
executor — human, cheap model or expensive one — can hit a target nobody can
|
|
147
|
+
measure. Go back and define it. Common escapes:
|
|
148
|
+
|
|
149
|
+
| Feels unmeasurable | Runnable form |
|
|
150
|
+
|--------------------|---------------|
|
|
151
|
+
| "the bug is fixed" | a test that fails today and passes after |
|
|
152
|
+
| "nothing else broke" | the existing suite, named explicitly |
|
|
153
|
+
| "the config is right" | a command that reads it back and asserts |
|
|
154
|
+
| "it deploys" | the build command |
|
|
155
|
+
|
|
156
|
+
**Do not accept the toolchain's generic health as the gate.** `npm run build`
|
|
157
|
+
passing proves the project still compiles; it does not prove *this task* was
|
|
158
|
+
done. A generic suite is the floor, never the whole gate — name the check that
|
|
159
|
+
would fail if this specific change were absent or wrong.
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Plan Structure (Flexible, Not Fixed!)
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
# [Task Name]
|
|
167
|
+
|
|
168
|
+
## Goal
|
|
169
|
+
One sentence: What are we building/fixing?
|
|
170
|
+
|
|
171
|
+
## Tasks
|
|
172
|
+
- [ ] Task 1: [Specific action] → Verify: [How to check]
|
|
173
|
+
- [ ] Task 2: [Specific action] → Verify: [How to check]
|
|
174
|
+
- [ ] Task 3: [Specific action] → Verify: [How to check]
|
|
175
|
+
|
|
176
|
+
## Gate
|
|
177
|
+
Runnable (must exit 0):
|
|
178
|
+
- `[command]`
|
|
179
|
+
|
|
180
|
+
By eye (after the gate is green):
|
|
181
|
+
- [what a human still has to look at, if anything]
|
|
182
|
+
|
|
183
|
+
## Done When
|
|
184
|
+
- [ ] Gate is green
|
|
185
|
+
- [ ] [Main success criteria]
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
> **That's it.** No phases, no sub-sections unless truly needed.
|
|
189
|
+
> Keep it minimal. Add complexity only when required.
|
|
190
|
+
|
|
191
|
+
## Notes
|
|
192
|
+
[Any important considerations]
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Best Practices (Quick Reference)
|
|
198
|
+
|
|
199
|
+
1. **Start with goal** - What are we building/fixing?
|
|
200
|
+
2. **Max 10 tasks** - If more, break into multiple plans
|
|
201
|
+
3. **Each task verifiable** - Clear "done" criteria
|
|
202
|
+
4. **Project-specific** - No copy-paste templates
|
|
203
|
+
5. **Update as you go** - Mark `[x]` when complete
|
|
204
|
+
6. **One runnable command in `## Gate`** - if you can't write it, the plan isn't ready (Principle 6)
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## When to Use
|
|
209
|
+
|
|
210
|
+
- New project from scratch
|
|
211
|
+
- Adding a feature
|
|
212
|
+
- Fixing a bug (if complex)
|
|
213
|
+
- Refactoring multiple files
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: powershell-windows
|
|
3
|
+
description: PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling.
|
|
4
|
+
when_to_use: "When working on Windows systems, writing PowerShell scripts, or using Windows-specific commands. NOT for macOS/Linux."
|
|
5
|
+
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# PowerShell Windows Patterns
|
|
9
|
+
|
|
10
|
+
> Critical patterns and pitfalls for Windows PowerShell.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 1. Operator Syntax Rules
|
|
15
|
+
|
|
16
|
+
### CRITICAL: Parentheses Required
|
|
17
|
+
|
|
18
|
+
| ❌ Wrong | ✅ Correct |
|
|
19
|
+
|----------|-----------|
|
|
20
|
+
| `if (Test-Path "a" -or Test-Path "b")` | `if ((Test-Path "a") -or (Test-Path "b"))` |
|
|
21
|
+
| `if (Get-Item $x -and $y -eq 5)` | `if ((Get-Item $x) -and ($y -eq 5))` |
|
|
22
|
+
|
|
23
|
+
**Rule:** Each cmdlet call MUST be in parentheses when using logical operators.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 2. Unicode/Emoji Restriction
|
|
28
|
+
|
|
29
|
+
### CRITICAL: No Unicode in Scripts
|
|
30
|
+
|
|
31
|
+
| Purpose | ❌ Don't Use | ✅ Use |
|
|
32
|
+
|---------|-------------|--------|
|
|
33
|
+
| Success | ✅ ✓ | [OK] [+] |
|
|
34
|
+
| Error | ❌ ✗ 🔴 | [!] [X] |
|
|
35
|
+
| Warning | ⚠️ 🟡 | [*] [WARN] |
|
|
36
|
+
| Info | ℹ️ 🔵 | [i] [INFO] |
|
|
37
|
+
| Progress | ⏳ | [...] |
|
|
38
|
+
|
|
39
|
+
**Rule:** Use ASCII characters only in PowerShell scripts.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## 3. Null Check Patterns
|
|
44
|
+
|
|
45
|
+
### Always Check Before Access
|
|
46
|
+
|
|
47
|
+
| ❌ Wrong | ✅ Correct |
|
|
48
|
+
|----------|-----------|
|
|
49
|
+
| `$array.Count -gt 0` | `$array -and $array.Count -gt 0` |
|
|
50
|
+
| `$text.Length` | `if ($text) { $text.Length }` |
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 4. String Interpolation
|
|
55
|
+
|
|
56
|
+
### Complex Expressions
|
|
57
|
+
|
|
58
|
+
| ❌ Wrong | ✅ Correct |
|
|
59
|
+
|----------|-----------|
|
|
60
|
+
| `"Value: $($obj.prop.sub)"` | Store in variable first |
|
|
61
|
+
|
|
62
|
+
**Pattern:**
|
|
63
|
+
```
|
|
64
|
+
$value = $obj.prop.sub
|
|
65
|
+
Write-Output "Value: $value"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## 5. Error Handling
|
|
71
|
+
|
|
72
|
+
### ErrorActionPreference
|
|
73
|
+
|
|
74
|
+
| Value | Use |
|
|
75
|
+
|-------|-----|
|
|
76
|
+
| Stop | Production & automation scripts (fail fast, allows try/catch to catch non-terminating errors) |
|
|
77
|
+
| Continue | Interactive terminal session default only |
|
|
78
|
+
| SilentlyContinue | Suppress expected non-critical noise on specific cmdlets with `-ErrorAction` |
|
|
79
|
+
|
|
80
|
+
### Try/Catch Pattern
|
|
81
|
+
|
|
82
|
+
- Don't return inside try block
|
|
83
|
+
- Use finally for cleanup
|
|
84
|
+
- Return after try/catch
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 6. File Paths
|
|
89
|
+
|
|
90
|
+
### Windows Path Rules
|
|
91
|
+
|
|
92
|
+
| Pattern | Use |
|
|
93
|
+
|---------|-----|
|
|
94
|
+
| Literal path | `C:\Users\User\file.txt` |
|
|
95
|
+
| Variable path | `Join-Path $env:USERPROFILE "file.txt"` |
|
|
96
|
+
| Relative | `Join-Path $ScriptDir "data"` |
|
|
97
|
+
|
|
98
|
+
**Rule:** Use Join-Path for cross-platform safety.
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 7. Array Operations
|
|
103
|
+
|
|
104
|
+
### Correct Patterns
|
|
105
|
+
|
|
106
|
+
| Operation | Syntax |
|
|
107
|
+
|-----------|--------|
|
|
108
|
+
| Empty array | `$array = @()` |
|
|
109
|
+
| Add item | `$array += $item` |
|
|
110
|
+
| ArrayList add | `$list.Add($item) | Out-Null` |
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## 8. JSON Operations
|
|
115
|
+
|
|
116
|
+
### CRITICAL: Depth Parameter
|
|
117
|
+
|
|
118
|
+
| ❌ Wrong | ✅ Correct |
|
|
119
|
+
|----------|-----------|
|
|
120
|
+
| `ConvertTo-Json` | `ConvertTo-Json -Depth 10` |
|
|
121
|
+
|
|
122
|
+
**Rule:** Always specify `-Depth` for nested objects.
|
|
123
|
+
|
|
124
|
+
### File Operations
|
|
125
|
+
|
|
126
|
+
| Operation | Pattern |
|
|
127
|
+
|-----------|---------|
|
|
128
|
+
| Read | `Get-Content "file.json" -Raw | ConvertFrom-Json` |
|
|
129
|
+
| Write | `$data | ConvertTo-Json -Depth 10 | Out-File "file.json" -Encoding UTF8` |
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 9. Common Errors
|
|
134
|
+
|
|
135
|
+
| Error Message | Cause | Fix |
|
|
136
|
+
|---------------|-------|-----|
|
|
137
|
+
| "parameter 'or'" | Missing parentheses | Wrap cmdlets in () |
|
|
138
|
+
| "Unexpected token" | Unicode character | Use ASCII only |
|
|
139
|
+
| "Cannot find property" | Null object | Check null first |
|
|
140
|
+
| "Cannot convert" | Type mismatch | Use .ToString() |
|
|
141
|
+
| `Start-Process: Cannot validate argument on parameter 'FilePath'` | cmd syntax `start "" app.exe` in PowerShell | `Start-Process 'app.exe' -ArgumentList '--a','--b'` |
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## 9b. Background Processes and Stray Console Windows
|
|
146
|
+
|
|
147
|
+
A console program (`ssh.exe`, `node.exe`, `nvm.exe`) started by a parent that has **no
|
|
148
|
+
console** (`pythonw`, a scheduled task, a GUI app, an agent's hidden shell) gets a new
|
|
149
|
+
visible window. Repeated launches mean a window popping up every few seconds.
|
|
150
|
+
|
|
151
|
+
| Symptom | Cause | Fix |
|
|
152
|
+
| --- | --- | --- |
|
|
153
|
+
| Empty terminal titled `...\OpenSSH\ssh.exe` keeps appearing | `pythonw` script respawning `ssh` | `subprocess.call(..., creationflags=subprocess.CREATE_NO_WINDOW)` |
|
|
154
|
+
| Dialog "Terminal Only: NVM for Windows should be run from a terminal" | `nvm` called without a TTY (npm `preinstall`, agents, CI) | Skip version switching when `!process.stdin.isTTY \|\| process.env.CI`; print the command for the human instead |
|
|
155
|
+
| Window flashes from a scheduled task | Task runs `powershell.exe` without hiding | `-WindowStyle Hidden`, or `conhost.exe --headless <exe>` |
|
|
156
|
+
|
|
157
|
+
Find who spawns it (parent chain of the process):
|
|
158
|
+
|
|
159
|
+
```powershell
|
|
160
|
+
$all = Get-CimInstance Win32_Process
|
|
161
|
+
$all | Where-Object Name -eq 'ssh.exe' | ForEach-Object {
|
|
162
|
+
$parent = $all | Where-Object ProcessId -eq $_.ParentProcessId
|
|
163
|
+
'{0} <- {1}: {2}' -f $_.ProcessId, $parent.Name, $parent.CommandLine
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
A respawn loop also needs **backoff**: double the wait while the child dies fast, so a
|
|
168
|
+
persistent failure does not reconnect every few seconds.
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## 10. Script Template
|
|
173
|
+
|
|
174
|
+
```powershell
|
|
175
|
+
# Strict mode
|
|
176
|
+
Set-StrictMode -Version Latest
|
|
177
|
+
$ErrorActionPreference = "Stop"
|
|
178
|
+
|
|
179
|
+
# Paths
|
|
180
|
+
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
|
|
181
|
+
|
|
182
|
+
# Main
|
|
183
|
+
try {
|
|
184
|
+
# Logic here
|
|
185
|
+
Write-Output "[OK] Done"
|
|
186
|
+
exit 0
|
|
187
|
+
}
|
|
188
|
+
catch {
|
|
189
|
+
Write-Warning "Error: $_"
|
|
190
|
+
exit 1
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
> **Remember:** PowerShell has unique syntax rules. Parentheses, ASCII-only, and null checks are non-negotiable.
|
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: provider-orchestration
|
|
3
|
+
description: Split plan / execute / review across coding-agent CLIs (Cursor, Claude Code, Codex, and others when present). Executors are writers and investigators on cheap/fast models — never flagship unless the human operator named that model this turn. Nobody merges but the conductor.
|
|
4
|
+
when_to_use: "When the user asks to run work on another provider, pass execution to Cursor/composer, Claude Code, Codex, or Gemini CLI, orchestrate multi-provider jobs, or keep planning/review on the current session while a cheaper CLI types or probes. NOT for same-runtime subagents (use coordinator-mode / parallel-agents), NOT for a single small edit you should just make, NOT for spawning a flagship model unless the human named it this turn."
|
|
5
|
+
allowed-tools: Read, Glob, Grep, Bash
|
|
6
|
+
effort: high
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Provider orchestration — plan dear, type cheap, review dear
|
|
10
|
+
|
|
11
|
+
> One agent that plans, types, and reviews on the same expensive meter is how
|
|
12
|
+
> a subscription dies. Split the roles. Isolation is Git, not a warning.
|
|
13
|
+
|
|
14
|
+
## Política obrigatória de executores
|
|
15
|
+
|
|
16
|
+
Únicas combinações permitidas para tarefas executadas ou investigadas por CLI: Codex `gpt-6-luna` com esforço `low`; Claude `claude-haiku-5-5` com `--effort low`; Cursor `composer-2.5`; OpenCode Go `opencode-go/deepseek-v4.1-flash`. Não trocar modelo por variável, fallback, tier ou preço. Se o modelo não estiver disponível, falhar e informar; não substituir. Esta política prevalece sobre exemplos anteriores neste documento.
|
|
17
|
+
|
|
18
|
+
This skill is the **conductor**. The per-CLI recipes live in `cursor-exec`,
|
|
19
|
+
`claude-exec`, `codex-exec`, and `gemini-exec`. Load those when you are about
|
|
20
|
+
to spawn. Do not paste their argv from memory — flags drift.
|
|
21
|
+
|
|
22
|
+
**Exec is writer + investigator, not flagship.** The spawned CLI types and
|
|
23
|
+
looks. It does not architect. Cheap/fast model is the default on every
|
|
24
|
+
executor. A flagship id (Opus, Fable, frontier GPT, Gemini Pro, vendor
|
|
25
|
+
"best" default) is allowed **only when the human operator named that model
|
|
26
|
+
in this turn**. The conductor agent is not the operator — "this looks hard,
|
|
27
|
+
I'll spawn Opus" is a violation. If the job needs flagship judgement, keep
|
|
28
|
+
it here on the conductor.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## 1. What this is (and what it is not)
|
|
33
|
+
|
|
34
|
+
**This is:** one interactive agent (you) decomposes work, writes an unambiguous
|
|
35
|
+
plan, dispatches a **different** coding-agent CLI headless in an isolated
|
|
36
|
+
worktree, then reviews the real diff and delivers.
|
|
37
|
+
|
|
38
|
+
**This is not:**
|
|
39
|
+
|
|
40
|
+
| Pattern | Where it lives | Why it is a different job |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| Subagents in the same runtime (`Task`, native Agent tool) | `coordinator-mode`, `parallel-agents` | Same provider, same bill, same tree unless you isolate |
|
|
43
|
+
| The ZenKit bridge router (`execute-claude` / `execute-cursor`) | `zenkit-bridge` | Classifies a request; it does not run the ritual below |
|
|
44
|
+
| Selling access to someone else's Claude / Cursor / Codex | — | **Forbidden.** The buyer brings their own subscription. This kit teaches the method. Pooling keys and reselling the CLI is how you inherit the provider's terms. |
|
|
45
|
+
|
|
46
|
+
If the user said "spin two reviewers", that is `coordinator-mode`. If they said
|
|
47
|
+
"you plan, composer types, you review", that is this skill.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 2. The three roles (never collapse them)
|
|
52
|
+
|
|
53
|
+
| Role | Who | Pays for | Allowed to |
|
|
54
|
+
|---|---|---|---|
|
|
55
|
+
| **Conductor** | The interactive agent talking to the human | Planning + review tokens | Write the plan, pick the executor, isolate, read the diff, iterate, open the PR, merge only with a human when the repo requires it |
|
|
56
|
+
| **Executor** | A headless CLI in a worktree | Cheap / fast model (writer + investigator) | Type the planned diff, or probe (read-only). **Never pick a flagship model unless the human named it this turn. Never merge. Never push to a protected branch. Never touch a second tree.** |
|
|
57
|
+
| **Human** | The operator | The subscriptions | Keys, merge-to-prod, anything destructive |
|
|
58
|
+
|
|
59
|
+
Collapsing conductor and executor onto one premium model is the default, and
|
|
60
|
+
it is the expensive default. Collapsing executor and merger is how autonomous
|
|
61
|
+
codegen ships unreviewed.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## 3. Probe before you promise
|
|
66
|
+
|
|
67
|
+
Do not assume the buyer's machine looks like yours. Before dispatching:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
command -v cursor-agent; command -v agent; command -v cursor
|
|
71
|
+
command -v claude
|
|
72
|
+
command -v codex
|
|
73
|
+
command -v gemini
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
A missing binary is not a failure of this skill — it is a missing
|
|
77
|
+
subscription. Say which role you can cover with what is installed, and ask
|
|
78
|
+
before inventing a fallback that burns the conductor's meter typing.
|
|
79
|
+
|
|
80
|
+
Auth is the buyer's. Typical env vars (never log, never commit):
|
|
81
|
+
|
|
82
|
+
| CLI | Auth |
|
|
83
|
+
|---|---|
|
|
84
|
+
| Cursor | `CURSOR_API_KEY` |
|
|
85
|
+
| Claude Code | `ANTHROPIC_API_KEY` or a subscription login / `claude setup-token` |
|
|
86
|
+
| Codex | `CODEX_API_KEY` (exec-only) or saved CLI login |
|
|
87
|
+
| Gemini CLI | `GEMINI_API_KEY` |
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## 4. The ritual
|
|
92
|
+
|
|
93
|
+
### Step 1 — Plan (conductor, expensive)
|
|
94
|
+
|
|
95
|
+
Write a `PLAN.md` the executor cannot misread:
|
|
96
|
+
|
|
97
|
+
- Files to touch, and files **not** to touch
|
|
98
|
+
- Contracts / signatures that must stay
|
|
99
|
+
- Acceptance: commands that must go green
|
|
100
|
+
- What "done" looks like in `git status`
|
|
101
|
+
|
|
102
|
+
Vague plans produce vague diffs. The executor is a typist with a compiler, not
|
|
103
|
+
an architect. `plan-writing` applies.
|
|
104
|
+
|
|
105
|
+
### Step 2 — Isolate (`git-worktrees`)
|
|
106
|
+
|
|
107
|
+
Every executor run happens in a **dedicated worktree**, never in the shared
|
|
108
|
+
tree. Advisory locks warn; they do not isolate. Load `git-worktrees` and
|
|
109
|
+
create from the main tree, not from inside another worktree.
|
|
110
|
+
|
|
111
|
+
Two executors on the same worktree is the same incident as two humans on the
|
|
112
|
+
same checkout.
|
|
113
|
+
|
|
114
|
+
### Step 3 — Dispatch (one executor, one tree)
|
|
115
|
+
|
|
116
|
+
Pick **one** CLI per worktree. Parallel dispatch is allowed across *different*
|
|
117
|
+
worktrees with *disjoint* file sets. Sequential is mandatory when the second
|
|
118
|
+
diff depends on the first.
|
|
119
|
+
|
|
120
|
+
| Job shape | Default executor | Default model |
|
|
121
|
+
|---|---|---|
|
|
122
|
+
| Implementation / UI / mechanical refactor | Cursor (`cursor-exec`) | `composer-2.5` |
|
|
123
|
+
| Type or probe with a Claude subscription | Claude Code (`claude-exec`) | `haiku` |
|
|
124
|
+
| Type or probe with a Codex subscription | Codex (`codex-exec`) | the CLI's **mini/fast** id (pin it; omit = often flagship) |
|
|
125
|
+
| Type or probe with a Gemini subscription | Gemini CLI (`gemini-exec`) | Flash (`gemini-2.5-flash`); never Pro unless the human named it |
|
|
126
|
+
|
|
127
|
+
Judgement that needs a flagship stays on the **conductor**. Do not promote
|
|
128
|
+
the typist because the plan was hard.
|
|
129
|
+
|
|
130
|
+
Exact argv: the matching `*-exec` skill. Do not copy from an old session.
|
|
131
|
+
|
|
132
|
+
### Step 4 — Supervise (conductor)
|
|
133
|
+
|
|
134
|
+
When the process exits:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
git -C <worktree> status --short
|
|
138
|
+
git -C <worktree> diff
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Read the diff. Run the acceptance commands from the plan. A green executor
|
|
142
|
+
exit is not a green change — it means the CLI finished, not that the change
|
|
143
|
+
is right.
|
|
144
|
+
|
|
145
|
+
**Continuidade do mandatário:** o condutor permanece
|
|
146
|
+
responsável até diff revisável ou bloqueio humano verdadeiro. Monte um snapshot
|
|
147
|
+
JSON (`executor`, `revisao`, `demanda`, `reserva`, `handoff`, `sessao`) e rode:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
node scripts/avaliar-vigilancia-mandato.mjs snapshot.json
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Ou `avaliar_vigilancia_mandato` no bridge; em `dispatch_handoff` com `rerun:true`,
|
|
154
|
+
passe `mandatoSnapshot` só quando `podeIniciarExecutor` for true. Fail-closed no
|
|
155
|
+
runtime (`dispatch-mandato-gate.ts` em `server.ts`, sem alterar `dispatch.ts`).
|
|
156
|
+
|
|
157
|
+
If the diff is wrong, **do not fix it as the conductor unless the fix is
|
|
158
|
+
smaller than the round-trip**. Write a tighter plan and dispatch again on the
|
|
159
|
+
same worktree (idempotent). The conductor typing "just this one file" is how
|
|
160
|
+
the split collapses.
|
|
161
|
+
|
|
162
|
+
### Step 5 — Deliver (conductor)
|
|
163
|
+
|
|
164
|
+
Commit on the worktree branch, open the review. The executor does not open
|
|
165
|
+
the PR unless the plan explicitly says so **and** the conductor still reads
|
|
166
|
+
it. Merge to production stays human when the repo says so.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## 5. Cost policy (hard)
|
|
171
|
+
|
|
172
|
+
Executors are **writers and investigators**. Flagship is not a default, not
|
|
173
|
+
a "just this once" the conductor grants itself, and not whatever the CLI
|
|
174
|
+
picks when you omit `--model`.
|
|
175
|
+
|
|
176
|
+
| CLI | Default for exec | Flagship (Opus, Fable, frontier GPT, Pro, …) |
|
|
177
|
+
|---|---|---|
|
|
178
|
+
| Cursor | `composer-2.5` | Only if the **human** named the id this turn. Fable on Cursor burns included quota unusually fast — still requires the name, plus a warning |
|
|
179
|
+
| Claude Code | `haiku` | Only if the **human** named `sonnet` / `opus` / Fable / a full flagship id this turn |
|
|
180
|
+
| Codex | mini/fast id, **pinned** | Only if the **human** named it. Omitting `-m` is how you get the vendor flagship by accident |
|
|
181
|
+
| Gemini | Flash / cheap | Pro only if the **human** named it |
|
|
182
|
+
|
|
183
|
+
- House cap: per-token typist models must cost ≤ $2 per 1M tokens (in+out, models.dev
|
|
184
|
+
prices). Claude Haiku (~$6) is **not** cheap on that cap. The default typist/investigator
|
|
185
|
+
is Cursor `composer-2.5` (`cursor-exec` / `dispatch_handoff`); `opencode-go-exec` is
|
|
186
|
+
an optional provider.
|
|
187
|
+
- The human operator is the person at the keyboard. A parent agent, a
|
|
188
|
+
subagent, a plan file, or "the other CLI used Opus last time" does not
|
|
189
|
+
authorize flagship.
|
|
190
|
+
- Cap Claude with `--max-budget-usd` even on haiku.
|
|
191
|
+
- Do not silently fall back to another provider if the chosen CLI is
|
|
192
|
+
missing — that is a cost surprise.
|
|
193
|
+
- Never start a second executor to "try the other provider" on the same
|
|
194
|
+
tree. That is two writers, plus two bills.
|
|
195
|
+
- See `model-routing`.
|
|
196
|
+
|
|
197
|
+
### 5.1 Anatomia do executor e política de fallback
|
|
198
|
+
|
|
199
|
+
Um executor é a soma de cinco partes. Quando uma falha, só uma delas muda, e a mudança
|
|
200
|
+
é explícita:
|
|
201
|
+
|
|
202
|
+
```text
|
|
203
|
+
┌──────────────────────────────────────────────┐
|
|
204
|
+
│ objetivo (plano do condutor, critérios) │
|
|
205
|
+
├──────────────────────────────────────────────┤
|
|
206
|
+
executor = │ reasoning (modelo + esforço do papel) │
|
|
207
|
+
│ tools (CLI do provider, worktree, MCPs) │
|
|
208
|
+
│ memória (projeto: demanda, quadro, fatos) │
|
|
209
|
+
│ fallback (o que fazer quando algo cai) │
|
|
210
|
+
└──────────────────────────────────────────────┘
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Modelo e esforço vêm do papel (triagem, desenvolvimento, teste, revisão), configurados no
|
|
214
|
+
bridge e sempre dentro da lista permitida acima (`ZENKIT_EXECUTOR_CONFIG`).
|
|
215
|
+
|
|
216
|
+
Regra de fallback quando um provider cai:
|
|
217
|
+
|
|
218
|
+
| Falha | O que o executor faz | O que o condutor pode fazer |
|
|
219
|
+
|---|---|---|
|
|
220
|
+
| Modelo indisponível ou recusado | Falha e informa o erro real. Não troca de modelo sozinho | Redespachar com outro executor **da lista**, nomeado no `dispatch_handoff` |
|
|
221
|
+
| CLI ausente ou sem login | Falha antes de criar worktree ou reserva | Pedir ao humano o login, ou redespachar para outro executor da lista |
|
|
222
|
+
| Falha transitória de rede | O bridge repete até 3 vezes | Nada, se recuperou; senão, tratar como as linhas acima |
|
|
223
|
+
| Executor termina sem alteração | Handoff fecha como `no-changes` | Revisar a saída e decidir: plano mais claro ou encerrar |
|
|
224
|
+
|
|
225
|
+
Nunca é fallback: subir para um modelo fora da lista, trocar de provider em silêncio,
|
|
226
|
+
ou abrir um segundo executor na mesma worktree. Toda troca fica registrada no handoff
|
|
227
|
+
(papel, executor, modelo, esforço).
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## 6. Traps (each one has already cost a session somewhere)
|
|
232
|
+
|
|
233
|
+
**`--force` / `--sandbox workspace-write` / `--permission-mode dontAsk` without
|
|
234
|
+
a worktree.** Those flags exist so the CLI does not stop for a TTY. They are
|
|
235
|
+
not a safety story. Isolation is the safety story.
|
|
236
|
+
|
|
237
|
+
**Codex `exec` is read-only until you say otherwise.** Forgetting
|
|
238
|
+
`--sandbox workspace-write` looks like a hung or no-op run.
|
|
239
|
+
|
|
240
|
+
**Three names for the Cursor CLI.** Official docs say `agent`; some installs
|
|
241
|
+
expose `cursor-agent`; the IDE binary also has `cursor agent`. Probe. Do not
|
|
242
|
+
hardcode.
|
|
243
|
+
|
|
244
|
+
**Same-runtime `Task` is not a second provider.** It inherits the parent's
|
|
245
|
+
model pin. On Cursor, a subagent with a premium pin in its frontmatter will
|
|
246
|
+
bill premium even if the parent is `composer-2.5`. That is a flagship call
|
|
247
|
+
the human did not make.
|
|
248
|
+
|
|
249
|
+
**Omitting `--model` / `-m`.** Vendor default is often flagship. Exec must
|
|
250
|
+
pin the cheap id. Silence is not a default.
|
|
251
|
+
|
|
252
|
+
**Sharing API keys across customers.** Each buyer uses their own
|
|
253
|
+
subscription. The kit must still work if the memory service / any other piece of the
|
|
254
|
+
seller's stack is absent.
|
|
255
|
+
|
|
256
|
+
**Executor commit on the conductor's branch.** If you skipped the worktree,
|
|
257
|
+
the commit lands wherever the shared tree was. Check `git branch --show-current`
|
|
258
|
+
in the worktree before commit.
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## 7. When not to use this
|
|
263
|
+
|
|
264
|
+
- The edit is smaller than the plan file you would write.
|
|
265
|
+
- No second CLI is installed and the user did not ask to go get one.
|
|
266
|
+
- You would be dispatching a write into the tree you are currently editing.
|
|
267
|
+
- The user asked for a second *opinion*, not a second *typist* — that is
|
|
268
|
+
`coordinator-mode`.
|
|
269
|
+
---
|