@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,161 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: codex-exec
|
|
3
|
+
description: Run OpenAI Codex CLI non-interactively (`codex exec`) as a writer or investigator. Pin the mini/fast model. Sandbox is read-only until you pass workspace-write. Never a flagship model unless the human operator named it this turn. Never merge.
|
|
4
|
+
when_to_use: "When the conductor needs Codex to type or probe a planned diff, or the user asks for codex exec / Codex headless. NOT for the Codex TUI, NOT for merge, NOT as a silent fallback when the binary is missing, NOT for gpt-5.x full / Codex flagship unless the human named that model this turn."
|
|
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
|
+
# codex-exec — Codex CLI as writer / investigator
|
|
14
|
+
|
|
15
|
+
> `codex exec` types and looks. The default sandbox is **read-only**. A run
|
|
16
|
+
> that "succeeds" and changes nothing usually forgot `--sandbox workspace-write`.
|
|
17
|
+
> `--full-auto` is deprecated; do not teach it. **Pin a mini/fast model.**
|
|
18
|
+
> Omitting `-m` is how you get the vendor flagship. Flagship only if the
|
|
19
|
+
> **human operator** named that model **this turn**.
|
|
20
|
+
|
|
21
|
+
Load `provider-orchestration` for the ritual. Load `git-worktrees` before a
|
|
22
|
+
write. This file is the **Codex argv and its traps**.
|
|
23
|
+
|
|
24
|
+
Canonical docs: [Non-interactive mode](https://developers.openai.com/codex/noninteractive).
|
|
25
|
+
Re-probe `codex exec --help` when the binary exists — this file was written
|
|
26
|
+
from the published docs because the CLI is **not assumed installed**.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 1. Probe (fail honest)
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
command -v codex || { echo "Codex CLI not installed — do not silently type this as another provider"; exit 1; }
|
|
34
|
+
codex --version
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
If the binary is missing, **stop**. Falling back to `claude -p` or
|
|
38
|
+
`cursor-agent` without asking is a cost surprise and a different skill.
|
|
39
|
+
|
|
40
|
+
Auth:
|
|
41
|
+
|
|
42
|
+
- Interactive / laptop: saved CLI login (treat `~/.codex/auth.json` like a
|
|
43
|
+
password).
|
|
44
|
+
- Automation: `CODEX_API_KEY` on **that one invocation**. Docs: this
|
|
45
|
+
variable is supported in `codex exec`, and you should not export it for
|
|
46
|
+
the whole job if untrusted code (install scripts, tests) will inherit the
|
|
47
|
+
environment.
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
# Safe invocation via stdin (avoids ARG_MAX exhaustion and option injection)
|
|
51
|
+
cat PLAN.md | CODEX_API_KEY=… codex exec -c model_reasoning_effort=low --sandbox workspace-write -m gpt-6-luna -
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Never log the key. Never commit `auth.json`.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## 2. Headless write recipe
|
|
59
|
+
|
|
60
|
+
Progress goes to **stderr**. The final agent message goes to **stdout**.
|
|
61
|
+
That split is the point — you can pipe the result.
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
cd "$WORKTREE" || exit 1 # must be a git repo; Codex refuses otherwise
|
|
65
|
+
cat PLAN.md | codex exec -c model_reasoning_effort=low --sandbox workspace-write -m gpt-6-luna -
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
| Flag | Why |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `exec` | Non-interactive. Not the TUI. |
|
|
71
|
+
| `--sandbox workspace-write` | Allow edits. **Default is read-only.** |
|
|
72
|
+
| `-m` / `--model` | **Pin the mini/fast id.** Writer and investigator. As of 2026 the usual name is `gpt-6-luna` (probe `codex --help` / the model picker — names drift). **Do not omit.** Vendor default is often a flagship (`gpt-5.5` / current frontier). Flagship only if the **human** named that id this turn |
|
|
73
|
+
| `--sandbox danger-full-access` | Broader than the repo. Only in a throwaway container |
|
|
74
|
+
| `--json` | JSONL event stream on stdout (thread/turn/item/error). For monitors, not for "print the answer" |
|
|
75
|
+
| `-o` / `--output-last-message <path>` | Write the final message to a file (still prints it) |
|
|
76
|
+
| `--output-schema <file.json>` | Force the final message to match a JSON Schema |
|
|
77
|
+
| `--ephemeral` | Do not persist session files |
|
|
78
|
+
| `--ignore-user-config` | Do not load `$CODEX_HOME/config.toml` (CI) |
|
|
79
|
+
|
|
80
|
+
Deprecated: `--full-auto`. It still exists as compatibility and prints a
|
|
81
|
+
warning. New recipes use `--sandbox workspace-write`.
|
|
82
|
+
|
|
83
|
+
Resume a previous exec (two-stage pipeline, same tree):
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
cat PLAN.md | codex exec -c model_reasoning_effort=low --sandbox workspace-write -m gpt-6-luna -
|
|
87
|
+
codex exec resume --last -- "fix the failures from the previous run"
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Prefer a fresh plan over resume unless you intentionally want the prior
|
|
91
|
+
context. Resume is how leftover constraints leak into the next job.
|
|
92
|
+
|
|
93
|
+
Containment: `setsid` + `timeout --kill-after`, same as the other executors.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 3. Git repo required
|
|
98
|
+
|
|
99
|
+
Codex refuses to run outside a Git repository (destructive-change guard).
|
|
100
|
+
Override only with `--skip-git-repo-check` when you are sure. A worktree
|
|
101
|
+
**is** a git repo — create it first (`git-worktrees`), then `cd` into it.
|
|
102
|
+
Do not skip the check to avoid making a worktree.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 4. What you review afterwards
|
|
107
|
+
|
|
108
|
+
If you did not pass `--json`, stdout is the final message. Either way:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
git -C "$WORKTREE" status --short
|
|
112
|
+
git -C "$WORKTREE" diff
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The message can claim tests passed. The diff and a command you run yourself
|
|
116
|
+
are the ground truth.
|
|
117
|
+
|
|
118
|
+
With `--json`, do not `jq` the whole stream looking for a single object —
|
|
119
|
+
it is JSONL, one event per line (`thread.started`, `turn.completed`,
|
|
120
|
+
`item.*`, `error`).
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## 5. Traps
|
|
125
|
+
|
|
126
|
+
**Omitting `-m`.** The CLI then uses the account "recommended" model, which
|
|
127
|
+
in 2026 has been a flagship. Exec must pin mini/fast. Silence is a flagship
|
|
128
|
+
call the human did not make.
|
|
129
|
+
|
|
130
|
+
**`-m gpt-5.5` (or whatever the current frontier is) because the plan was
|
|
131
|
+
hard.** Judgement stays on the conductor. Flagship on this process requires
|
|
132
|
+
the human to type the id this turn.
|
|
133
|
+
|
|
134
|
+
**Read-only default.** The most expensive Codex bug in this skill is
|
|
135
|
+
silent: exec returns a reasonable summary and the worktree is clean. Always
|
|
136
|
+
pass `--sandbox workspace-write` when the plan says to edit.
|
|
137
|
+
|
|
138
|
+
**`--full-auto` in a copied snippet.** Deprecated. If you see it in an old
|
|
139
|
+
script, replace it.
|
|
140
|
+
|
|
141
|
+
**`OPENAI_API_KEY` vs `CODEX_API_KEY`.** Automation docs prefer
|
|
142
|
+
`CODEX_API_KEY` on the `exec` invocation. Do not scatter both and guess
|
|
143
|
+
which one won.
|
|
144
|
+
|
|
145
|
+
**Job-level env in CI that also runs `npm install`.** Install scripts can
|
|
146
|
+
read the key. Docs recommend not setting the key at job level when
|
|
147
|
+
repository-controlled code runs in the same environment.
|
|
148
|
+
|
|
149
|
+
**Two writers.** Codex in worktree A, Cursor in worktree A — same incident
|
|
150
|
+
as two checkouts. One executor per tree.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## 6. When not to use this
|
|
155
|
+
|
|
156
|
+
- `codex` is not on `PATH` — ask, do not substitute.
|
|
157
|
+
- The cheap typist should be Cursor `composer-2.5` — `cursor-exec`.
|
|
158
|
+
- You wanted the TUI. This skill is `exec` only.
|
|
159
|
+
- You were about to omit `-m` or pass a flagship id and the human did not
|
|
160
|
+
name it this turn — stop, or ask.
|
|
161
|
+
---
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: context-compression
|
|
3
|
+
description: Manage and compress conversation context in long sessions. Detect when context is growing large, summarize completed work phases, archive old findings while preserving key decisions. Prevents context degradation.
|
|
4
|
+
when_to_use: "When a session has 20+ turns, when context feels repetitive, when the agent is losing track of earlier work, or when the user says 'summarize what we've done'. NOT for short sessions."
|
|
5
|
+
allowed-tools: Read, Write, Grep
|
|
6
|
+
effort: low
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Context Compression — Long Session Management
|
|
10
|
+
|
|
11
|
+
> Keep sessions productive by compressing completed work while preserving key decisions.
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
Long sessions (30+ turns) cause context degradation — the AI loses track of earlier work, repeats itself, or forgets decisions. Context compression proactively summarizes completed phases so the context window stays focused on active work.
|
|
16
|
+
|
|
17
|
+
**Token Impact:** Recovers 5,000-15,000 tokens in long sessions by replacing verbose tool outputs with semantic summaries.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## When to Compress
|
|
22
|
+
|
|
23
|
+
| Signal | Action |
|
|
24
|
+
|---|---|
|
|
25
|
+
| Session has 20+ turns | Consider proactive compression |
|
|
26
|
+
| Agent repeats earlier suggestions | Context is saturated — compress now |
|
|
27
|
+
| User says "we already discussed this" | Compress immediately |
|
|
28
|
+
| Switching to a new phase of work | Compress the completed phase |
|
|
29
|
+
| Large tool output (500+ lines) | Micro-compact the output |
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Compression Levels
|
|
34
|
+
|
|
35
|
+
### Level 1: Micro-Compact (Tool Output)
|
|
36
|
+
|
|
37
|
+
Compress individual tool outputs while retaining semantic content:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
❌ Before (raw grep output — 200 lines, ~4,000 tokens):
|
|
41
|
+
src/auth/jwt.ts:15: import { verify } from 'jsonwebtoken'
|
|
42
|
+
src/auth/jwt.ts:23: export function validateToken(token: string) {
|
|
43
|
+
src/auth/jwt.ts:24: try {
|
|
44
|
+
src/auth/jwt.ts:25: const decoded = verify(token, SECRET)
|
|
45
|
+
... (195 more lines)
|
|
46
|
+
|
|
47
|
+
✅ After (micro-compact — 5 lines, ~100 tokens):
|
|
48
|
+
Grep results for "jwt": Found 8 files, 42 matches.
|
|
49
|
+
Key files: src/auth/jwt.ts (main JWT logic), src/middleware/auth.ts (middleware),
|
|
50
|
+
src/api/login.ts (token creation). Token validation at jwt.ts:23-40.
|
|
51
|
+
Error handling at jwt.ts:42-55. Secret loaded from env at jwt.ts:8.
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Level 2: Phase Summary
|
|
55
|
+
|
|
56
|
+
Replace a completed work phase with a summary:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
❌ Before (full research transcript — ~3,000 tokens):
|
|
60
|
+
[turn 1] Read package.json...
|
|
61
|
+
[turn 2] Read src/index.ts...
|
|
62
|
+
[turn 3] Grep for "auth"...
|
|
63
|
+
[turn 4] Found 8 files related to auth...
|
|
64
|
+
[turn 5] Read src/auth/jwt.ts...
|
|
65
|
+
... (10 more turns of exploration)
|
|
66
|
+
|
|
67
|
+
✅ After (phase summary — ~200 tokens):
|
|
68
|
+
## Research Phase Complete
|
|
69
|
+
- Project: Next.js 15 app with JWT auth
|
|
70
|
+
- Auth files: 8 files in src/auth/, src/middleware/, src/api/
|
|
71
|
+
- Token flow: login → create JWT → store in httpOnly cookie → validate in middleware
|
|
72
|
+
- Bug location: src/auth/jwt.ts:45 — expiry check uses `<` instead of `<=`
|
|
73
|
+
- Decision: Fix the comparison operator, add edge case test
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Level 3: Session Checkpoint
|
|
77
|
+
|
|
78
|
+
Full session summary for long-running work:
|
|
79
|
+
|
|
80
|
+
```markdown
|
|
81
|
+
## Session Checkpoint (Turn 35)
|
|
82
|
+
|
|
83
|
+
### Completed
|
|
84
|
+
- [x] Researched auth system (8 files, JWT flow mapped)
|
|
85
|
+
- [x] Fixed token expiry bug in jwt.ts:45
|
|
86
|
+
- [x] Added edge case test in jwt.test.ts
|
|
87
|
+
- [x] Verified: all 42 tests passing
|
|
88
|
+
|
|
89
|
+
### In Progress
|
|
90
|
+
- [ ] Update API documentation
|
|
91
|
+
- [ ] Review related middleware
|
|
92
|
+
|
|
93
|
+
### Key Decisions
|
|
94
|
+
1. Keep httpOnly cookies (not localStorage) for token storage
|
|
95
|
+
2. Use `<=` for expiry check to include exact-moment expiry
|
|
96
|
+
3. Add 5-minute grace period for clock skew
|
|
97
|
+
|
|
98
|
+
### Files Modified
|
|
99
|
+
- src/auth/jwt.ts (line 45: comparison fix)
|
|
100
|
+
- tests/auth/jwt.test.ts (added 3 edge case tests)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Compression Protocol
|
|
106
|
+
|
|
107
|
+
### Step 1: Identify Completed Phases
|
|
108
|
+
```
|
|
109
|
+
What work is DONE and won't be revisited?
|
|
110
|
+
→ Research findings already synthesized
|
|
111
|
+
→ Implementation already verified
|
|
112
|
+
→ Decisions already made and applied
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Step 2: Extract Key Information
|
|
116
|
+
```
|
|
117
|
+
From the completed phase, preserve:
|
|
118
|
+
✅ Decisions made and WHY
|
|
119
|
+
✅ File paths and line numbers of changes
|
|
120
|
+
✅ Key findings that inform ongoing work
|
|
121
|
+
✅ Error messages or test results (summarized)
|
|
122
|
+
|
|
123
|
+
Discard:
|
|
124
|
+
❌ Step-by-step tool invocation details
|
|
125
|
+
❌ Full file contents that were read
|
|
126
|
+
❌ Exploratory dead-ends that didn't lead anywhere
|
|
127
|
+
❌ Verbose error stack traces (keep the message only)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Step 3: Write Summary
|
|
131
|
+
```
|
|
132
|
+
Use the Phase Summary format above.
|
|
133
|
+
Keep to 100-300 tokens per completed phase.
|
|
134
|
+
Include enough detail to resume work without re-reading.
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Best Practices
|
|
140
|
+
|
|
141
|
+
1. **Compress phases, not facts** — Individual decisions should stay, full transcripts should go
|
|
142
|
+
2. **Preserve "why" over "what"** — Why a decision was made matters more than the exact commands run
|
|
143
|
+
3. **Never auto-compress** — Always tell the user "I'm summarizing the completed research phase to keep context focused"
|
|
144
|
+
4. **Keep file references** — Always preserve file paths and line numbers in summaries
|
|
145
|
+
5. **Checkpoint on phase transitions** — Natural compression point when switching from research to implementation
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: coordinator-mode
|
|
3
|
+
description: Advanced multi-agent orchestration with parallel workers, synthesis protocols, and coordinator lifecycle. Use when complex tasks require multiple agents working in parallel with intelligent result synthesis.
|
|
4
|
+
when_to_use: "When the user needs multi-agent coordination, parallel task execution, complex multi-domain work, or when /coordinate or /orchestrate is invoked. NOT for single-domain tasks."
|
|
5
|
+
allowed-tools: Read, Grep, Glob, Bash, Write, Edit, Agent
|
|
6
|
+
effort: high
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Coordinator Mode — Multi-Agent Orchestration
|
|
10
|
+
|
|
11
|
+
> Distilled from production-proven coordinator patterns. Transforms sequential agent chains into intelligent parallel orchestration.
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
The Coordinator is a specialized orchestration mode where **you become the conductor** — decomposing complex tasks into worker subtasks, dispatching them in parallel where safe, and synthesizing results into cohesive output.
|
|
16
|
+
|
|
17
|
+
**You are NOT a worker. You are the coordinator.** Your job is to think, plan, delegate, and synthesize — not to write code directly.
|
|
18
|
+
|
|
19
|
+
**This is not multi-provider.** Workers here are subagents in the **same** runtime. To dispatch a planned diff to another CLI (Cursor, Claude Code, Codex), load `provider-orchestration` and the matching `*-exec` skill. Mixing the two is how a "second agent" still bills the parent.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Coordinator Lifecycle
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
User Request
|
|
27
|
+
↓
|
|
28
|
+
1. DECOMPOSE — Break task into worker subtasks
|
|
29
|
+
↓
|
|
30
|
+
2. CLASSIFY — Mark each subtask: Research | Implementation | Verification
|
|
31
|
+
↓
|
|
32
|
+
3. DISPATCH — Launch workers (parallel for reads, sequential for writes)
|
|
33
|
+
↓
|
|
34
|
+
4. MONITOR — Track worker completion notifications
|
|
35
|
+
↓
|
|
36
|
+
5. SYNTHESIZE — Combine results into unified response
|
|
37
|
+
↓
|
|
38
|
+
6. VERIFY — Ensure completeness before reporting to user
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Phase-Based Workflow
|
|
44
|
+
|
|
45
|
+
| Phase | Purpose | Concurrency | Worker Type |
|
|
46
|
+
|-------|---------|-------------|-------------|
|
|
47
|
+
| **Research** | Gather information, explore codebase | ✅ Fully parallel | Read-only agents |
|
|
48
|
+
| **Synthesis** | Analyze findings, plan approach | ❌ Coordinator only | No workers |
|
|
49
|
+
| **Implementation** | Make changes to code/files | ⚠️ Sequential per file set | Write-capable agents |
|
|
50
|
+
| **Verification** | Test, lint, validate changes | ✅ Parallel (independent) | Test/security agents |
|
|
51
|
+
|
|
52
|
+
> 🔴 **Rule:** NEVER skip the Synthesis phase. Research → direct Implementation = poor results.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Concurrency Rules
|
|
57
|
+
|
|
58
|
+
### Safe to Parallelize
|
|
59
|
+
- ✅ Multiple agents reading different files
|
|
60
|
+
- ✅ Security audit + performance audit (read-only)
|
|
61
|
+
- ✅ Test runner + linter (independent)
|
|
62
|
+
- ✅ Exploring different directories
|
|
63
|
+
|
|
64
|
+
### Must Be Sequential
|
|
65
|
+
- ❌ Two agents writing to the same file
|
|
66
|
+
- ❌ Implementation that depends on another agent's output
|
|
67
|
+
- ❌ Database migration + code that uses the new schema
|
|
68
|
+
- ❌ API change + frontend that consumes the API
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Worker Prompt Writing Guide
|
|
73
|
+
|
|
74
|
+
### 🔴 The Golden Rule: Never Delegate Understanding
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
❌ WRONG: "Based on your findings, fix the bug"
|
|
78
|
+
❌ WRONG: "Based on the research, implement it"
|
|
79
|
+
❌ WRONG: "Look at the code and do what's needed"
|
|
80
|
+
|
|
81
|
+
✅ RIGHT: "The bug is in src/auth/jwt.ts line 45 — the token expiry
|
|
82
|
+
check uses `<` instead of `<=`, causing off-by-one failures
|
|
83
|
+
at exactly the expiry time. Change line 45 from
|
|
84
|
+
`if (now < expiry)` to `if (now <= expiry)`"
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
> **Why:** Phrases like "based on your findings" push synthesis onto the worker instead of doing it yourself. Write prompts that prove YOU understood — include file paths, line numbers, what specifically to change.
|
|
88
|
+
|
|
89
|
+
### Writing Effective Worker Prompts
|
|
90
|
+
|
|
91
|
+
Brief the worker like a **smart colleague who just walked into the room**:
|
|
92
|
+
|
|
93
|
+
1. **Explain what** you're trying to accomplish and why
|
|
94
|
+
2. **Describe what** you've already learned or ruled out
|
|
95
|
+
3. **Give enough context** about the surrounding problem for judgment calls
|
|
96
|
+
4. **Be specific** about scope: what's in, what's out, what another agent handles
|
|
97
|
+
5. **State the output format** you expect ("report in under 200 words")
|
|
98
|
+
|
|
99
|
+
### Prompt Templates
|
|
100
|
+
|
|
101
|
+
#### Research Worker
|
|
102
|
+
```
|
|
103
|
+
Investigate [specific question] in [file/directory scope].
|
|
104
|
+
Context: We're trying to [goal] because [reason].
|
|
105
|
+
I've already checked [what you checked] and found [what you found].
|
|
106
|
+
Report: List [specific deliverable]. Under 200 words.
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
#### Implementation Worker
|
|
110
|
+
```
|
|
111
|
+
Modify [specific file(s)] to [specific change].
|
|
112
|
+
Context: [Why this change is needed].
|
|
113
|
+
The current code at [file:line] does [X], change it to [Y].
|
|
114
|
+
Constraints: Don't touch [out-of-scope files]. Another agent handles [related area].
|
|
115
|
+
Verify: [How the worker should confirm success].
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
#### Verification Worker
|
|
119
|
+
```
|
|
120
|
+
Verify that [specific change] works correctly.
|
|
121
|
+
Run: [specific commands].
|
|
122
|
+
Check: [what success looks like].
|
|
123
|
+
Report: Pass/fail with details on any failures.
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Fork Semantics
|
|
129
|
+
|
|
130
|
+
### When to Fork (vs. Spawn Fresh Agent)
|
|
131
|
+
|
|
132
|
+
| Scenario | Action | Why |
|
|
133
|
+
|----------|--------|-----|
|
|
134
|
+
| Open-ended research question | **Fork** (omit agent type) | Fork inherits context, shorter prompt |
|
|
135
|
+
| Independent parallel research | **Fork** multiple in one message | Each fork shares cache |
|
|
136
|
+
| Specialized domain work | **Spawn** (specify agent type) | Fresh specialist starts clean |
|
|
137
|
+
| Second opinion on your work | **Spawn** | Independent perspective |
|
|
138
|
+
|
|
139
|
+
### Fork Rules
|
|
140
|
+
|
|
141
|
+
1. **Don't peek.** Don't read the fork's output file mid-flight. You'll get a completion notification. Reading the transcript pulls tool noise into your context.
|
|
142
|
+
|
|
143
|
+
2. **Don't race.** After launching, you know nothing about what the fork found. Never fabricate or predict fork results. If the user asks before notification lands, say "the fork is still running."
|
|
144
|
+
|
|
145
|
+
3. **Keep prompts focused.** Provide a specific goal and output schema. Bound context to avoid inflating child tokens.
|
|
146
|
+
|
|
147
|
+
4. **Depth limit & Circuit Breaker (Anti-Loop):**
|
|
148
|
+
- Maximum subagent nesting depth: **1** (subagents MUST NOT spawn or fork further subagents).
|
|
149
|
+
- Maximum retries per worker failure: **2**. After 2 failed attempts, STOP, summarize the blocker, and escalate to the human operator.
|
|
150
|
+
- Set execution timeouts on background operations; never wait indefinitely without progress signals.
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Anti-Patterns
|
|
155
|
+
|
|
156
|
+
| Anti-Pattern | Why It's Bad | Fix |
|
|
157
|
+
|---|---|---|
|
|
158
|
+
| "Look at the code and fix it" | Zero context = workers make wrong assumptions | Provide specific file paths, line numbers, and what to change |
|
|
159
|
+
| Skipping Research phase | Implementation without understanding = rework | Always research first, even briefly |
|
|
160
|
+
| Launching 10+ workers at once | Overwhelms synthesis, diminishing returns | 2-5 workers per round, synthesize, then more if needed |
|
|
161
|
+
| Fabricating worker results | User gets wrong information | Wait for actual notification, say "still running" if asked |
|
|
162
|
+
| Coordinator writes code directly | Loses orchestration benefits | Always delegate to appropriate specialist |
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Synthesis Protocol
|
|
167
|
+
|
|
168
|
+
After all workers complete:
|
|
169
|
+
|
|
170
|
+
```markdown
|
|
171
|
+
## Coordinator Synthesis
|
|
172
|
+
|
|
173
|
+
### Task: [Original Request]
|
|
174
|
+
|
|
175
|
+
### Workers Dispatched
|
|
176
|
+
| Worker | Type | Status | Key Finding |
|
|
177
|
+
|--------|------|--------|-------------|
|
|
178
|
+
| agent-1 | Research | ✅ | Found X in file Y |
|
|
179
|
+
| agent-2 | Research | ✅ | Identified Y pattern |
|
|
180
|
+
|
|
181
|
+
### Consolidated Analysis
|
|
182
|
+
[Your synthesis — not a copy-paste of worker output]
|
|
183
|
+
|
|
184
|
+
### Decision & Rationale
|
|
185
|
+
[What you decided based on ALL worker findings and why]
|
|
186
|
+
|
|
187
|
+
### Implementation Plan
|
|
188
|
+
1. [Specific change with file path]
|
|
189
|
+
2. [Specific change with file path]
|
|
190
|
+
|
|
191
|
+
### Remaining Risk
|
|
192
|
+
- [Anything workers flagged but couldn't resolve]
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Continue vs. Spawn Decision
|
|
198
|
+
|
|
199
|
+
| Situation | Action |
|
|
200
|
+
|-----------|--------|
|
|
201
|
+
| Worker completed, need follow-up on same topic | **Continue** (send message to worker ID) |
|
|
202
|
+
| Worker completed, need different domain work | **Spawn new** specialist |
|
|
203
|
+
| Worker failed, need retry with same context | **Continue** with corrected instructions |
|
|
204
|
+
| Worker failed, need fundamentally different approach | **Spawn new** |
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## Best Practices
|
|
209
|
+
|
|
210
|
+
1. **Start with 2-3 workers** — add more after synthesis if needed
|
|
211
|
+
2. **Research before implementation** — always, even for "simple" tasks
|
|
212
|
+
3. **Synthesize, don't copy** — your summary should add insight, not repeat
|
|
213
|
+
4. **Verify independently** — verification workers shouldn't trust implementation workers
|
|
214
|
+
5. **Track state** — note which workers are pending/completed/failed
|
|
215
|
+
6. **Share scratchpad** — use a known directory for cross-worker artifacts
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cursor-exec
|
|
3
|
+
description: Run Cursor's coding-agent CLI headless as a writer or investigator. Pin composer-2.5. Never a flagship model unless the human operator named that id this turn. Isolate in a worktree. --force only because there is no TTY. Never merge.
|
|
4
|
+
when_to_use: "When the conductor needs Cursor to type a planned diff or probe the tree; when the user asks to pass execution to Cursor / composer-2.5 / cursor-agent. NOT for interactive Cursor chat, NOT for planning, NOT for merge, NOT for Opus/Fable/Sonnet unless the human named that model this turn."
|
|
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
|
+
# cursor-exec — Cursor CLI as writer / investigator
|
|
14
|
+
|
|
15
|
+
> Cursor in print mode types and looks. It is not the architect, and it is
|
|
16
|
+
> not allowed to merge. Default `composer-2.5`. Flagship ids (Fable, Opus,
|
|
17
|
+
> Sonnet, any frontier pin) only if the **human operator** named that model
|
|
18
|
+
> **this turn** — the conductor does not get to decide.
|
|
19
|
+
|
|
20
|
+
Load `provider-orchestration` for the ritual (plan → isolate → dispatch →
|
|
21
|
+
review). This file is the **Cursor argv and its traps**. Load `git-worktrees`
|
|
22
|
+
before the first write.
|
|
23
|
+
|
|
24
|
+
Official headless reference: [Using Headless CLI](https://cursor.com/docs/cli/headless).
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 1. Binary names (probe, do not hardcode)
|
|
29
|
+
|
|
30
|
+
Installs disagree:
|
|
31
|
+
|
|
32
|
+
| Form | Where it shows up |
|
|
33
|
+
|---|---|
|
|
34
|
+
| `agent -p …` | Current Cursor CLI docs |
|
|
35
|
+
| `cursor-agent -p …` | Standalone binary (`cursor.com/install`) |
|
|
36
|
+
| `cursor agent -p …` | IDE CLI exposing `agent` as a subcommand |
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
if command -v cursor-agent >/dev/null; then BIN=cursor-agent
|
|
40
|
+
elif command -v agent >/dev/null; then BIN=agent
|
|
41
|
+
else echo "Cursor CLI not installed"; exit 1
|
|
42
|
+
fi
|
|
43
|
+
"$BIN" --version
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Auth: `CURSOR_API_KEY` in the environment (or `--api-key`). Never echo, log,
|
|
47
|
+
or commit it. Without a key, fail honestly — do not silently type the diff
|
|
48
|
+
as the conductor.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 2. Headless write recipe
|
|
53
|
+
|
|
54
|
+
Print mode (`-p` / `--print`) runs once and exits. **Without `--force` (alias
|
|
55
|
+
`--yolo`), file changes are proposed, not applied.** That is the documented
|
|
56
|
+
behaviour. `--force` is required for a typist; it is not a substitute for a
|
|
57
|
+
worktree.
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
cd "$WORKTREE" # already an isolated git worktree
|
|
61
|
+
"$BIN" -p "$(cat PLAN.md)" \
|
|
62
|
+
--output-format json \
|
|
63
|
+
--force \
|
|
64
|
+
--model composer-2.5 \
|
|
65
|
+
--trust
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
| Flag | Why |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `-p` | Non-interactive; skip the TTY |
|
|
71
|
+
| `--output-format json` | One object on success; machine-readable. `stream-json` is for progress UIs, not for "did it finish" |
|
|
72
|
+
| `--force` | Apply edits without confirmation |
|
|
73
|
+
| `--model composer-2.5` | Default. Writer/investigator. **Do not pass a flagship id unless the human named it this turn.** Fable on Cursor burns included quota unusually fast — warn, still require the name |
|
|
74
|
+
| `--trust` | Headless workspace trust prompt otherwise stalls |
|
|
75
|
+
|
|
76
|
+
`--workspace <dir>` is valid if you cannot `cd`. Prefer `cd` into the
|
|
77
|
+
worktree so relative paths in the plan match.
|
|
78
|
+
|
|
79
|
+
Contain the process: own process group + wall-clock timeout. An orphaned
|
|
80
|
+
child keeps billing after you think it died.
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
# pattern — adjust timeout to the job
|
|
84
|
+
setsid timeout --kill-after=10 --signal=TERM 1800 \
|
|
85
|
+
"$BIN" -p "$(cat PLAN.md)" --output-format json --force --model composer-2.5 --trust
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Capture stdout / stderr / exit code next to the worktree (and gitignore that
|
|
89
|
+
directory). A non-zero exit is a failed run, not a signal to retry on the
|
|
90
|
+
shared tree.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## 3. What you review afterwards
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
git -C "$WORKTREE" status --short
|
|
98
|
+
git -C "$WORKTREE" diff
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
JSON on stdout is the CLI's story. The diff is the ground truth. If they
|
|
102
|
+
disagree, believe the diff.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 4. Cost pin (hard) — writer and investigator
|
|
107
|
+
|
|
108
|
+
This process **types and looks**. It does not architect.
|
|
109
|
+
|
|
110
|
+
- Default `--model composer-2.5`.
|
|
111
|
+
- Agent frontmatter emitted for Cursor is forced to `composer-2.5` by the
|
|
112
|
+
generator. A premium pin in `kit/agents/` is a generator failure, not a
|
|
113
|
+
warning — that path has no human in the loop.
|
|
114
|
+
- Subagents inherit that pin. A `Task` whose agent file says Fable will bill
|
|
115
|
+
Fable even if the parent was `composer-2.5`. That is a flagship call the
|
|
116
|
+
human did not make.
|
|
117
|
+
- **Flagship override:** only the human operator, by model id, this turn.
|
|
118
|
+
"The plan is hard" / "the conductor is Opus" / `ZENKIT_CURSOR_MODEL` in
|
|
119
|
+
the environment of a parent agent does **not** count. Fable still gets a
|
|
120
|
+
warning (known quota burner) even when named.
|
|
121
|
+
- Omit `--model` is not a default — pin it. Vendor "recommended" is often
|
|
122
|
+
flagship.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## 5. Traps
|
|
127
|
+
|
|
128
|
+
**Print mode without `--force` looks successful and changes nothing.** You
|
|
129
|
+
will "review" an empty diff and think the plan was a no-op.
|
|
130
|
+
|
|
131
|
+
**`--force` on the shared working tree.** The flag exists because there is no
|
|
132
|
+
human to click Approve. The worktree is what stops it from writing the
|
|
133
|
+
conductor's unfinished files.
|
|
134
|
+
|
|
135
|
+
**Injected kit files leaking into the PR.** If you generate `.cursor/` /
|
|
136
|
+
`.claude/` into the worktree so the executor follows this kit, exclude them
|
|
137
|
+
from `git add` (per-worktree `info/exclude` is the usual mechanism). The
|
|
138
|
+
buyer did not ask for a kit dump in their diff.
|
|
139
|
+
|
|
140
|
+
**Assuming `cursor` (the editor) is the agent CLI.** `command -v cursor` can
|
|
141
|
+
succeed and still not speak `-p`. Probe `cursor-agent` / `agent` as above.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## 6. When not to use this
|
|
146
|
+
|
|
147
|
+
- You are in an interactive Cursor session and the edit is small — just edit.
|
|
148
|
+
- The job needs judgement the plan did not already make — that is the
|
|
149
|
+
conductor, or `claude-exec` if Claude is the typist.
|
|
150
|
+
- You were about to pass `--model` a flagship id and the human did not name
|
|
151
|
+
it this turn — stop. Keep judgement on the conductor, or ask.
|
|
152
|
+
---
|