@cbartens/bkit 0.0.0-stage → 5.0.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/.bkit/README.md +417 -0
- package/.bkit/core/.agents/context.md +95 -0
- package/.bkit/core/.agents/docs.md +62 -0
- package/.bkit/core/.agents/rules.md +147 -0
- package/.bkit/core/.agents/skills.md +43 -0
- package/.bkit/core/.bkit/LICENSE.md +151 -0
- package/.bkit/core/.bkit/README.md +417 -0
- package/.bkit/core/.bkit/cloud.md +493 -0
- package/.bkit/core/.bkit/comparison.md +321 -0
- package/.bkit/core/.bkit/install.md +401 -0
- package/.bkit/core/.bkit/jsonl.md +497 -0
- package/.bkit/core/.bkit/prompts.md +474 -0
- package/.bkit/core/.bkit/providers.md +598 -0
- package/.bkit/core/.bkit/templates.md +470 -0
- package/.bkit/core/.bkit/trackers.md +95 -0
- package/.bkit/core/.bkit/workflows.md +1550 -0
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
- package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
- package/.bkit/core/AGENTS.md +77 -0
- package/.bkit/core/LICENSE.md +149 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
- package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
- package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
- package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
- package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
- package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
- package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
- package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
- package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
- package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
- package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
- package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
- package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
- package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
- package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
- package/.bkit/core/docs/templates/bkit-plan.md +476 -0
- package/.bkit/core/engine/checks/after/auth.ts +149 -0
- package/.bkit/core/engine/checks/after/ci-yml.ts +701 -0
- package/.bkit/core/engine/checks/after/github.ts +424 -0
- package/.bkit/core/engine/checks/after/index.ts +530 -0
- package/.bkit/core/engine/checks/after/managed.ts +217 -0
- package/.bkit/core/engine/checks/after/suppression.ts +53 -0
- package/.bkit/core/engine/checks/after/tools.ts +427 -0
- package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
- package/.bkit/core/engine/checks/before/env.ts +187 -0
- package/.bkit/core/engine/checks/before/files.ts +204 -0
- package/.bkit/core/engine/checks/before/index.ts +206 -0
- package/.bkit/core/engine/checks/before/mcp.ts +127 -0
- package/.bkit/core/engine/checks/before/repo.ts +77 -0
- package/.bkit/core/engine/checks/before/version.ts +67 -0
- package/.bkit/core/engine/checks/status-holes.ts +479 -0
- package/.bkit/core/engine/cli.ts +867 -0
- package/.bkit/core/engine/commands/analysis.ts +550 -0
- package/.bkit/core/engine/commands/ci/ci.ts +483 -0
- package/.bkit/core/engine/commands/comply.ts +415 -0
- package/.bkit/core/engine/commands/harvest.ts +459 -0
- package/.bkit/core/engine/commands/install/check.ts +70 -0
- package/.bkit/core/engine/commands/install/doctor.ts +254 -0
- package/.bkit/core/engine/commands/install/install.ts +550 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +995 -0
- package/.bkit/core/engine/commands/install/upgrade.ts +1037 -0
- package/.bkit/core/engine/commands/launch.ts +139 -0
- package/.bkit/core/engine/commands/lib.ts +495 -0
- package/.bkit/core/engine/commands/registry.ts +53 -0
- package/.bkit/core/engine/commands/setup/setup.ts +184 -0
- package/.bkit/core/engine/commands/telemetry.ts +32 -0
- package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
- package/.bkit/core/engine/commands/workflow/context.ts +961 -0
- package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
- package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
- package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
- package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
- package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
- package/.bkit/core/engine/commands/workflow/status.ts +455 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
- package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
- package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
- package/.bkit/core/engine/install/cloud-env.ts +924 -0
- package/.bkit/core/engine/install/managed-block.ts +212 -0
- package/.bkit/core/engine/install/manifest.ts +448 -0
- package/.bkit/core/engine/install/modules/claude.ts +362 -0
- package/.bkit/core/engine/install/modules/cloud.ts +173 -0
- package/.bkit/core/engine/install/modules/codex.ts +219 -0
- package/.bkit/core/engine/install/modules/core.ts +620 -0
- package/.bkit/core/engine/install/modules/cursor.ts +231 -0
- package/.bkit/core/engine/install/modules/index.ts +242 -0
- package/.bkit/core/engine/install/modules/opencode.ts +573 -0
- package/.bkit/core/engine/install/payload-links.ts +150 -0
- package/.bkit/core/engine/install/placeholders.ts +108 -0
- package/.bkit/core/engine/install/template-copies.ts +119 -0
- package/.bkit/core/engine/install/version-file.ts +284 -0
- package/.bkit/core/engine/install/write.ts +467 -0
- package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
- package/.bkit/core/engine/ledgers/status.ts +213 -0
- package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
- package/.bkit/core/engine/render/hosts.ts +372 -0
- package/.bkit/core/engine/render/models.ts +323 -0
- package/.bkit/core/engine/render/parts.ts +38 -0
- package/.bkit/core/engine/render/trackers.ts +170 -0
- package/.bkit/core/engine/shared/egress.ts +345 -0
- package/.bkit/core/engine/shared/json.ts +16 -0
- package/.bkit/core/engine/shared/log-prefix.ts +9 -0
- package/.bkit/core/engine/shared/package-json.ts +29 -0
- package/.bkit/core/engine/shared/package-manager.ts +38 -0
- package/.bkit/core/engine/shared/package-roots.ts +163 -0
- package/.bkit/core/engine/shared/protected-paths.ts +164 -0
- package/.bkit/core/engine/shared/settings.ts +72 -0
- package/.bkit/core/engine/shared/timeouts.ts +20 -0
- package/.bkit/core/engine/tools/wording.ts +748 -0
- package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
- package/.bkit/core/hooks/gateguard-engine.js +193 -0
- package/.bkit/core/hooks/guardrails-shell.js +154 -0
- package/.bkit/core/hooks/guardrails-tiers.js +68 -0
- package/.bkit/core/hooks/preflight-linear.sh +73 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
- package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
- package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
- package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
- package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
- package/.bkit/core/prompts/bkit-build-summary.md +93 -0
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
- package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
- package/.bkit/core/prompts/bkit-design-generate.md +110 -0
- package/.bkit/core/prompts/bkit-design-organise.md +85 -0
- package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
- package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
- package/.bkit/core/prompts/bkit-design-spike.md +97 -0
- package/.bkit/core/prompts/bkit-design-summary.md +106 -0
- package/.bkit/core/prompts/bkit-design-update.md +66 -0
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
- package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
- package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
- package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
- package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
- package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
- package/.bkit/core/prompts/bkit-plan-update.md +68 -0
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
- package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
- package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
- package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
- package/.bkit/core/workflows/bkit-auto.md +121 -0
- package/.bkit/core/workflows/bkit-build.md +802 -0
- package/.bkit/core/workflows/bkit-debug.md +649 -0
- package/.bkit/core/workflows/bkit-design.md +495 -0
- package/.bkit/core/workflows/bkit-plan.md +510 -0
- package/.bkit/core/workflows/bkit-ship.md +650 -0
- package/.bkit/shared/.bkit/.env.example +86 -0
- package/.bkit/shared/.claude/bkit-cloud.md +117 -0
- package/.bkit/shared/.claude/settings.json +88 -0
- package/.bkit/shared/.codex/hooks.json +26 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
- package/.bkit/shared/.cursor/hooks.json +26 -0
- package/.bkit/shared/.cursor/mcp.json +15 -0
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
- package/.bkit/shared/.gitattributes +37 -0
- package/.bkit/shared/.mcp.json +16 -0
- package/.bkit/shared/.opencode/opencode.json +62 -0
- package/.bkit/shared/CLAUDE.md +11 -0
- package/.bkit/shared/LICENSE.md +22 -0
- package/.bkit/shared/docs/architecture.md +19 -0
- package/.bkit/shared/docs/data-schema.md +19 -0
- package/.bkit/shared/docs/deployments.md +433 -0
- package/.bkit/shared/docs/design.md +39 -0
- package/.bkit/shared/docs/noise.md +19 -0
- package/.bkit/shared/docs/observability.md +25 -0
- package/.bkit/shared/docs/security.md +42 -0
- package/.bkit/shared/docs/setup.md +30 -0
- package/.bkit/shared/docs/technology.md +18 -0
- package/.bkit/shared/docs/testing.md +413 -0
- package/.bkit/shared/gitignore +97 -0
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +187 -0
- package/.bkit/templates/.cursor/Dockerfile +68 -0
- package/.bkit/templates/.cursor/environment.json +6 -0
- package/.bkit/templates/.cursor/settings.json +11 -0
- package/.bkit/templates/.envrc +7 -0
- package/.bkit/templates/.github/dependabot.yml +52 -0
- package/.bkit/templates/.github/renovate.json5 +224 -0
- package/.bkit/templates/.github/workflows/bkit-ci.yml +1062 -0
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +564 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +102 -0
- package/.bkit/templates/.graphifyignore +108 -0
- package/.bkit/templates/.husky/pre-commit +16 -0
- package/.bkit/templates/.husky/pre-push +91 -0
- package/.bkit/templates/.lintstagedrc.json +3 -0
- package/.bkit/templates/.prettierignore +41 -0
- package/.bkit/templates/.serena/project.yml +243 -0
- package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
- package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
- package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
- package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
- package/.bkit/templates/.vale.ini +67 -0
- package/.bkit/templates/LICENSE.md +22 -0
- package/.bkit/templates/context/bkit-cloudrun.md +84 -0
- package/.bkit/templates/context/bkit-expo.md +186 -0
- package/.bkit/templates/context/bkit-github.md +79 -0
- package/.bkit/templates/context/bkit-inngest.md +45 -0
- package/.bkit/templates/context/bkit-maestro.md +76 -0
- package/.bkit/templates/context/bkit-playwright.md +62 -0
- package/.bkit/templates/context/bkit-resend.md +36 -0
- package/.bkit/templates/context/bkit-sentry.md +65 -0
- package/.bkit/templates/context/bkit-serena.md +33 -0
- package/.bkit/templates/context/bkit-stripe.md +36 -0
- package/.bkit/templates/context/bkit-supabase.md +59 -0
- package/.bkit/templates/context/bkit-tavily.md +49 -0
- package/.bkit/templates/context/bkit-vercel.md +64 -0
- package/.bkit/templates/docs/capabilities.md +72 -0
- package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
- package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
- package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
- package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
- package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
- package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
- package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
- package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
- package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
- package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
- package/.bkit/templates/slop-scan.config.json +120 -0
- package/CHANGELOG.md +1503 -0
- package/LICENSE.md +161 -0
- package/README.md +184 -2
- package/dist/checks/after/auth.js +140 -0
- package/dist/checks/after/ci-yml.js +681 -0
- package/dist/checks/after/github.js +400 -0
- package/dist/checks/after/index.js +431 -0
- package/dist/checks/after/managed.js +187 -0
- package/dist/checks/after/suppression.js +39 -0
- package/dist/checks/after/tools.js +351 -0
- package/dist/checks/before/context-fetch.js +426 -0
- package/dist/checks/before/env.js +163 -0
- package/dist/checks/before/files.js +187 -0
- package/dist/checks/before/index.js +162 -0
- package/dist/checks/before/mcp.js +111 -0
- package/dist/checks/before/repo.js +71 -0
- package/dist/checks/before/version.js +60 -0
- package/dist/checks/status-holes.js +393 -0
- package/dist/cli.js +688 -0
- package/dist/commands/analysis.js +325 -0
- package/dist/commands/ci/ci.js +438 -0
- package/dist/commands/comply.js +310 -0
- package/dist/commands/harvest.js +354 -0
- package/dist/commands/install/check.js +61 -0
- package/dist/commands/install/doctor.js +209 -0
- package/dist/commands/install/install.js +475 -0
- package/dist/commands/install/uninstall.js +839 -0
- package/dist/commands/install/upgrade.js +782 -0
- package/dist/commands/launch.js +118 -0
- package/dist/commands/lib.js +363 -0
- package/dist/commands/registry.js +50 -0
- package/dist/commands/setup/setup.js +158 -0
- package/dist/commands/telemetry.js +29 -0
- package/dist/commands/workflow/branches.js +1265 -0
- package/dist/commands/workflow/context.js +846 -0
- package/dist/commands/workflow/counters.js +227 -0
- package/dist/commands/workflow/fids.js +224 -0
- package/dist/commands/workflow/issues.js +585 -0
- package/dist/commands/workflow/ledgers.js +472 -0
- package/dist/commands/workflow/locks.js +364 -0
- package/dist/commands/workflow/prs.js +904 -0
- package/dist/commands/workflow/repo.js +199 -0
- package/dist/commands/workflow/roadmap.js +495 -0
- package/dist/commands/workflow/runs.js +1717 -0
- package/dist/commands/workflow/runtime.js +257 -0
- package/dist/commands/workflow/skills.js +110 -0
- package/dist/commands/workflow/status.js +392 -0
- package/dist/commands/workflow/steps.js +1093 -0
- package/dist/commands/workflow/tests.js +144 -0
- package/dist/commands/workflow/workflows.js +1342 -0
- package/dist/commands/workflow/workstreams.js +141 -0
- package/dist/commands/workflow/worktrees.js +473 -0
- package/dist/install/cloud-env.js +818 -0
- package/dist/install/managed-block.js +182 -0
- package/dist/install/manifest.js +376 -0
- package/dist/install/modules/claude.js +288 -0
- package/dist/install/modules/cloud.js +151 -0
- package/dist/install/modules/codex.js +193 -0
- package/dist/install/modules/core.js +531 -0
- package/dist/install/modules/cursor.js +186 -0
- package/dist/install/modules/index.js +152 -0
- package/dist/install/modules/opencode.js +504 -0
- package/dist/install/payload-links.js +119 -0
- package/dist/install/placeholders.js +87 -0
- package/dist/install/template-copies.js +106 -0
- package/dist/install/version-file.js +204 -0
- package/dist/install/write.js +342 -0
- package/dist/ledgers/clamp-log.js +27 -0
- package/dist/ledgers/status.js +156 -0
- package/dist/ledgers/telemetry.js +637 -0
- package/dist/render/hosts.js +339 -0
- package/dist/render/models.js +288 -0
- package/dist/render/parts.js +33 -0
- package/dist/render/trackers.js +135 -0
- package/dist/shared/egress.js +299 -0
- package/dist/shared/json.js +16 -0
- package/dist/shared/log-prefix.js +7 -0
- package/dist/shared/package-json.js +22 -0
- package/dist/shared/package-manager.js +32 -0
- package/dist/shared/package-roots.js +145 -0
- package/dist/shared/protected-paths.js +153 -0
- package/dist/shared/settings.js +44 -0
- package/dist/shared/timeouts.js +19 -0
- package/dist/tools/wording.js +680 -0
- package/package.json +101 -4
|
@@ -0,0 +1,598 @@
|
|
|
1
|
+
# IDE / Host Differences
|
|
2
|
+
|
|
3
|
+
{{BKIT_MANAGED_MARKER}}
|
|
4
|
+
|
|
5
|
+
> [!CAUTION]
|
|
6
|
+
> **Purpose:** Authoritative inventory of IDE host differences. Drives install script transform rules. Source-of-truth for "what changes between IDE versions of commands and subagents".
|
|
7
|
+
>
|
|
8
|
+
> **Rules:**
|
|
9
|
+
>
|
|
10
|
+
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
11
|
+
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
12
|
+
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
13
|
+
> - Ships to consumers: describe the current setup only. NEVER an internal identifier (tracker issue number, ledger key, review-finding id) and NEVER project history — decisions belong in `docs/decisions.jsonl`, incidents in `docs/knowledge.jsonl`.
|
|
14
|
+
> - One row per concern. Update when an IDE adds / changes a feature.
|
|
15
|
+
> - Unlisted = identical across hosts; install copies byte-identical.
|
|
16
|
+
> - Canonical format = Claude. All transforms = Claude → other.
|
|
17
|
+
|
|
18
|
+
## Supported hosts
|
|
19
|
+
|
|
20
|
+
<!-- prettier-ignore -->
|
|
21
|
+
| Host | Tier | Subagent dir | Command dir | Settings | Hooks | Install |
|
|
22
|
+
| --- | --- | --- | --- | --- | --- | --- |
|
|
23
|
+
| Claude Code | canonical | `.claude/agents/` | `.claude/commands/` | `.claude/settings.json` | `.claude/hooks/` (registered in settings) | `bkit install --claude` |
|
|
24
|
+
| Cursor | derived | `.cursor/agents/` | `.cursor/commands/` | `.cursor/settings.json` + `.cursor/environment.json` + `.cursor/Dockerfile` (templates, `.bkit/templates.md`) | `.cursor/hooks/` (registered in `.cursor/hooks.json`) | `bkit install --cursor` |
|
|
25
|
+
| opencode | additive (opt-in) | `.opencode/agents/` | `.opencode/commands/` | `.opencode/opencode.json` | `.opencode/plugin/bkit-gateguard.js` (PreToolUse) | `bkit install --opencode=<provider>` |
|
|
26
|
+
| Codex CLI | additive (opt-in) | `.codex/agents/` (TOML) | none — skills (below) | none (`openai` = reserved built-in id) | `.codex/hooks/bkit-gateguard.cjs` + `.codex/hooks/bkit-guardrails.cjs` (PreToolUse `apply_patch` / `Bash`, via `.codex/hooks.json`) | `bkit install --codex` |
|
|
27
|
+
|
|
28
|
+
**Two axes — host != provider.** **Host** = program reading what bkit writes, identified by its dir (`.claude/`, `.cursor/`, `.opencode/`, `.codex/`). **Provider** = gateway tokens are bought through. Model IDs are per-provider → `prompts.md` § Models = one column per PROVIDER (shared provider = one column, never two). Thinking depth is per-host (field name + ladder set by host config format: `effort:` claude/cursor, a `variant:` field opencode, `model_reasoning_effort` codex) → § Effort = one column per HOST. Neither table grows as hosts x providers.
|
|
29
|
+
|
|
30
|
+
**One provider per host = POLICY, not capability.** Nothing technical forces it — Cursor reaches Claude models, so does anything behind OpenRouter. Pin follows cost: each host runs on the gateway whose subscription is already paid. Subscription spent → switch **host**, not provider (the cheap gateway hangs off a different host).
|
|
31
|
+
|
|
32
|
+
<!-- prettier-ignore -->
|
|
33
|
+
| Host | Provider | Why |
|
|
34
|
+
| --- | --- | --- |
|
|
35
|
+
| Claude Code | `anthropic` | Claude subscription = cheapest path to Claude models |
|
|
36
|
+
| Cursor | `cursor` | Cursor subscription covers its whole catalog |
|
|
37
|
+
| Codex CLI | `openai` | ChatGPT subscription |
|
|
38
|
+
| opencode | **pick one**: `openrouter`, `ollama`, `opencode-zen`, `opencode-go` | no subscription — BYO key, so the choice is yours |
|
|
39
|
+
|
|
40
|
+
Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-key host → pluggable, flag names the provider (`--opencode=<provider>`). Per-model deviation → consumer `## Model Overrides` below `bkit:end`; no provider override.
|
|
41
|
+
|
|
42
|
+
### Codex CLI — three deviations
|
|
43
|
+
|
|
44
|
+
<!-- prettier-ignore -->
|
|
45
|
+
| Concern | On Codex |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| Agent files | `.codex/agents/*.toml` (TOML, not markdown). Required: `name`, `description`, `developer_instructions`. Pin + rung: `model`, `model_reasoning_effort`. |
|
|
48
|
+
| Workflows = SKILLS, invoked `$bkit-design` | no project-scoped command surface — custom prompts are `~/.codex/prompts` only, not repo-shared, deprecated for skills (upstream declined repo-scoped prompts). bkit renders `.agents/skills/bkit-<workflow>/SKILL.md`, on Codex's skill path (`$REPO_ROOT/.agents/skills`). `.agents/` is shared → visible to every host. |
|
|
49
|
+
| `tools:` not enforced | No per-agent tool allowlist upstream; `sandbox_mode` cannot substitute — every bkit agent is write-capable, so all would be `workspace-write`. Each agent gets the full built-in tool set regardless of declared `tools:`. GateGuard still gates, as everywhere. |
|
|
50
|
+
|
|
51
|
+
> **GateGuard needs the `.codex/` layer TRUSTED.** Codex loads project-local hooks only once trusted. Until then the hook is installed and never fires — present, proving nothing. Same for `bkit-guardrails.cjs`.
|
|
52
|
+
>
|
|
53
|
+
> **Codex cannot prompt.** It parses `permissionDecision: "ask"` but does not implement it — an ask is recorded as an error and the call proceeds. `bkit-guardrails.cjs` therefore blocks the `deny` tier for real and emits the `ask` tier as advisory `additionalContext`: the gate fires and informs, it cannot stop the command. Every ask-tier command is already PROHIBITED in all five workflow headers, so no bkit workflow reaches one. Asserted in `.bkit/core/engine/install/modules/index.integration.test.ts`.
|
|
54
|
+
|
|
55
|
+
**Explicit host axis (no implicit full):** `bkit install` requires ≥1 module flag — bare `bkit install` errors. Every host explicit; hosts compose: `bkit install --claude --cursor --opencode=opencode-zen` installs all three (+ implicit core). `--opencode` cannot render without `=<provider>` (strict allowlist). Switch providers: re-run install. All hosts render from `.bkit/`; run state in `status.jsonl` + plan docs + tracker (never host session) — phase/resumed run moves across hosts/providers mid-feature with identical gates + per-agent pins: hit limit on one, continue on another. `bkit status` → installed hosts + active providers; `bkit doctor` → credentials + tool reachability.
|
|
56
|
+
|
|
57
|
+
**Cheap models inside an IDE — no extension needed.** A host is its dir, not the window its process runs in. `bkit install --claude --cursor --opencode=openrouter` + opencode in the IDE's integrated terminal = every agent pin, GateGuard and the full workflow on OpenRouter while editing in Cursor. Supported path when the Claude subscription is spent.
|
|
58
|
+
|
|
59
|
+
> **Curated-column status (COMPLETE).** All four allowlisted providers (`openrouter`, `ollama`, `opencode-zen`, `opencode-go`) ship curated per-agent model pins in `prompts.md` § Models → install ready-to-run. Both OpenAI-compatible providers + both opencode gateways curated after live catalog probe + per-model tool-calling smoke (`tools:` chat/completions round-trip emitting `tool_calls`; `/models` alone != proof). **opencode catalogs = models.dev, not `/zen/v1/models`** — REST endpoint returns Zen-only; cannot see Go-only models (`minimax-m3`, `qwen3.7-plus`, …); models.dev source of truth (`opencode` = Zen, `opencode-go` = Go). `opencode-go` curated from models.dev/Go endpoint; prefer pins within Go 5h window; `opencode-zen` existence-validated via models.dev. See § Models for live-probe recipe + tier rationale.
|
|
60
|
+
|
|
61
|
+
**Additive multi-provider install:** `bkit install --opencode=<provider>` additive — second provider adds block to `opencode.json`, keeps first. Agent frontmatter (`model:`) re-renders to last-installed (active) provider; other blocks stay for interactive switch/overrides. Installed providers → `bkit.opencodeProviders: string[]` in `package.json`; active → `bkit.opencodeProvider`. `bkit status` lists all, marks active; `bkit doctor` checks all credentials. Remove one: `bkit uninstall --opencode=<provider>` (surgical — block + array; if active removed, re-point via `bkit install --opencode=<new>` or `bkit upgrade`). `bkit uninstall --opencode` (bare) tears down entire opencode host.
|
|
62
|
+
|
|
63
|
+
New host — row above + `run<Host>Module` (`.bkit/core/engine/install/modules/<host>.ts`) + manifest block (`.bkit/core/engine/install/manifest.ts`) + `.bkit/core/.<host>/hooks/` (the host config JSON in `.bkit/shared/.<host>/`) + GateGuard case in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts`. New provider also needs `GATEWAY_COLUMN` (`.bkit/core/engine/render/models.ts`) + a curated `prompts.md` § Models column.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## macOS GUI-isolation — `bkit cursor` / `bkit opencode`
|
|
68
|
+
|
|
69
|
+
**Root cause:** macOS GUI apps (Dock/Finder/Spotlight) run under `launchd` — **do not** inherit login-shell env. `direnv` exports from `.bkit/.env` stay shell-only. Token placeholders (`${BKIT_GH_TOKEN}` in `.cursor/mcp.json`, `{env:BKIT_OPENCODE_API_KEY}` in `.opencode/opencode.json`) resolve empty → MCP auth failures.
|
|
70
|
+
|
|
71
|
+
**Fix — launcher verbs:** `bkit cursor` / `bkit opencode` exec app binary with `.bkit/.env` merged into child env. Dynamic, per-repo, zero global state.
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
bkit cursor # /Applications/Cursor.app/Contents/MacOS/Cursor
|
|
75
|
+
bkit opencode # /Applications/opencode.app/Contents/MacOS/opencode
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- **Quit first.** Running instance keeps launch-time env; re-exec required.
|
|
79
|
+
- **Binary override:** `BKIT_CURSOR_BIN=<path>` / `BKIT_OPENCODE_BIN=<path>` for non-standard paths.
|
|
80
|
+
- **Cursor:** passes repo `cwd` as positional arg.
|
|
81
|
+
- **opencode:** no positional arg; reads `opencode.json` from `cwd`.
|
|
82
|
+
|
|
83
|
+
**`bkit doctor` check:** reports `.bkit/.env` keys with non-empty file value but absent from `process.env` (= Dock/Finder session); advisory → `bkit cursor` / `bkit opencode`.
|
|
84
|
+
|
|
85
|
+
**launchctl fallback (opt-in, not recommended):** exposes key to launchd apps current session only (not persistent across reboots). Manual re-run after restart + manual rotation — prefer launcher verbs.
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
launchctl setenv BKIT_GH_TOKEN "$BKIT_GH_TOKEN"
|
|
89
|
+
launchctl setenv BKIT_OPENCODE_API_KEY "$BKIT_OPENCODE_API_KEY"
|
|
90
|
+
# then relaunch from Dock — values survive until next reboot
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Persistent variant: `RunAtLoad` LaunchAgent plist (`~/Library/LaunchAgents/`) with one `setenv` per token. Same rotation caveat.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Subagent invocation (tool + prefix)
|
|
98
|
+
|
|
99
|
+
<!-- prettier-ignore -->
|
|
100
|
+
| Host | Tool name | Prefix | Example |
|
|
101
|
+
| --- | --- | --- | --- |
|
|
102
|
+
| Claude | `Agent` | `@` | `@bkit-build-plan-execute` invoked via `Agent` tool |
|
|
103
|
+
| Cursor | `Task` | `/` | `/bkit-build-plan-execute` invoked via `Task` tool |
|
|
104
|
+
| opencode | `/` (slash command) | `/` | `/bkit-build-plan-execute` invoked via opencode slash command |
|
|
105
|
+
|
|
106
|
+
**Transform (Claude → Cursor, command bodies):**
|
|
107
|
+
|
|
108
|
+
- Replace literal `` `Agent` tool `` with `` `Task` tool ``.
|
|
109
|
+
- Replace `using \`Agent\` tool`with`using \`Task\` tool`.
|
|
110
|
+
- Replace literal `` `Skill` tool `` with `` `Task` tool `` (slash-command — Cursor `Task` covers subagent + slash; Claude splits `Agent` + `Skill`).
|
|
111
|
+
- Replace `using \`Skill\` tool`with`using \`Task\` tool`.
|
|
112
|
+
- Replace `@<name>` with `/<name>` for kebab-case identifiers, **only inside `**Subagent:**` lines and protocol description block**. Don't touch `@` elsewhere (anchors, email, npm scopes).
|
|
113
|
+
- Subagent body files lack invocation phrasing — no body transform.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Subagent files
|
|
118
|
+
|
|
119
|
+
### Frontmatter
|
|
120
|
+
|
|
121
|
+
<!-- prettier-ignore -->
|
|
122
|
+
| Field | Claude | Cursor | Notes |
|
|
123
|
+
| --- | --- | --- | --- |
|
|
124
|
+
| `name` | required | required | kebab-case, must match filename. Identical. |
|
|
125
|
+
| `description` | required | required | Identical. |
|
|
126
|
+
| Field | Claude | Cursor | opencode | Notes |
|
|
127
|
+
| --- | --- | --- | --- | --- |
|
|
128
|
+
| `name` | required | required | required | kebab-case, must match filename. Identical. |
|
|
129
|
+
| `description` | required | required | required | Identical. |
|
|
130
|
+
| `effort` | required (`low` / `medium` / `high` / `xhigh` / `max` — last two model-gated, Opus-only on current models) | not supported | emitted as a separate `variant:` field | Drop on Cursor. `applyOpencodeAgent` reads the § Effort **OpenCode** column and writes it to `variant:` (not a `#`-suffix on the model — 1.x keeps the suffix in its model id and fails lookup); the OpenCode column ceilings out, so `medium`→`high`, `high` / `xhigh`→`max`, `max`→`max`, `low`→`none`. The **ollama** gateway omits `variant:` entirely: its provider builds models with no variants, so any variant there is a hard 2.0 error. |
|
|
131
|
+
| `tools` | required (e.g. `[Read, Grep, Glob, Write, Edit, Bash, WebFetch, WebSearch]`) | supported (allowlist) + `disallowedTools` denylist | object map `{ <tool>: true }` | Identity mapping on Cursor (verified), not enforced by Cursor CLI 2026.10.01 (measured: a `tools: [Read]` subagent keeps `Shell` / `Write` / every MCP tool). opencode: built-ins lowercased; `mcp__<server>__<tool>` respelled `<server>_<tool>` (`mcp__serena__*` → `serena_*`). |
|
|
132
|
+
| `permissionMode` | required (`acceptEdits` standard) | not supported | not supported | Drop on Cursor and opencode. |
|
|
133
|
+
| `maxTurns` | required | not supported | not supported | Drop on Cursor and opencode. |
|
|
134
|
+
| `model` | required (explicit Claude model ID — see `prompts.md` § Frontmatter Conventions effort→model mapping) | required | required (provider-prefixed, e.g. `openrouter/moonshotai/kimi-k3`) | Pinned per-agent. Claude locks model. Cursor drives runner via T3. opencode: `<provider>/<model-id>` (see `prompts.md` § Models, columns `OpenRouter` / `Ollama` / …). |
|
|
135
|
+
| `readonly` | not supported (use `tools` allowlist) | optional boolean | not supported | Cursor: derive from `tools` (true if no `Edit`/`Write`/`Bash`). |
|
|
136
|
+
| `is_background` | not supported | optional boolean (Cursor 2.4+) | not supported | Default false. Reserve for future opt-in on parallelisable subagents. |
|
|
137
|
+
| `reasoningEffort` | not a frontmatter field (use `effort`) | not supported | not a field — OpenCode carries effort as a `variant:` field | Was opencode-native through 1.x. `applyOpencodeAgent` now emits `variant: <name>` (1.x reads it natively; 2.0 joins `model` + `variant` internally). A `#`-suffix on the `model` pin breaks 1.x and hard-errors on 2.0 when the model exposes no such variant. |
|
|
138
|
+
|
|
139
|
+
### Body
|
|
140
|
+
|
|
141
|
+
Identical across hosts. Process steps, verdict/findings (`## Verdict` / `## Findings`), `Read:` / `Write:` paths, `> ⛔ STOP` — unchanged. No transform.
|
|
142
|
+
|
|
143
|
+
Cursor model assignment: § Models below — per-agent lookup, not effort-tier derived.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Models
|
|
148
|
+
|
|
149
|
+
> **Effort vs model — different mechanisms.** Claude: `effort: low|medium|high|xhigh` = thinking-budget on pinned model. Cursor: explicit `model:` per agent; native-pool diversity (`cursor-grok-4.5-high` / `composer-2.5` — no API-pool defaults). **Per-agent model assignment canonical**; derive Cursor `model` from `prompts.md` § Models, not `effort` alone.
|
|
150
|
+
|
|
151
|
+
### Cursor model catalog
|
|
152
|
+
|
|
153
|
+
**Pinned selections canonical in `prompts.md`** (§ Models `Cursor` column + § Orchestrators) — not here. Cursor set churns; use pull recipe below.
|
|
154
|
+
|
|
155
|
+
> **Default install = first-party pool only.** Shipped Cursor pins are **`cursor-grok-4.5-high`** + **`composer-2.5`** so workflows keep running when API credits are exhausted. API-pool models (Claude / GPT / Fable) are **opt-in** via `prompts.md` § Model Overrides — never default pins. **Have API credits and want Opus back?** Paste the ready-to-use Opus override block in `prompts.md` § Model Overrides (maps every Claude-opus-tier agent → `claude-opus-5-thinking-high`; `/v0/models` has no Opus 5.5 ID). Sonnet-tier override is `claude-sonnet-5-thinking-high` (Sonnet 5, not 5.5) or `gpt-5.6-sol-high`. Then `bkit install --cursor`. Shipped sonnet cells stay on the first-party ceiling: `grok-4.5` lands 2.9 under the sonnet target at a quarter of Claude's cost per task. **No `cursor-grok-4.7`.**
|
|
156
|
+
|
|
157
|
+
Tier guidance:
|
|
158
|
+
|
|
159
|
+
- **`composer-2.5`** ($) — **default.** Fast/cheap: build executors, summarizers, ship-summary, utilities, `/build` + `/ship` orchestrators. First-party pool.
|
|
160
|
+
- **`cursor-grok-4.5-high`** ($$) — **default.** Depth slots, synthesizers, parallel diversity (design/plan/debug orchestrators + former Opus-tier agents). First-party pool (Cursor + SpaceXAI); Coding Agent Index parity with GPT-5.5 at lower per-task cost. `-fast` variant exists.
|
|
161
|
+
- **`claude-opus-5-thinking-high`** ($$$) — **override only.** Deep review / audit / synthesis when API credits remain. `/v0/models` has Opus 5, not Opus 5.5 (`claude-opus-5-5` is the Claude pin). `-fast` exists. API pool — burns credits; pin via § Model Overrides, never as shipped default.
|
|
162
|
+
- **`claude-sonnet-5-thinking-high`/`-xhigh`** ($$$) — **override only.** Sonnet 5 on the API pool. Not a shipped default. No Sonnet 5.5 ID.
|
|
163
|
+
- **`gpt-5.*`** ($$$) — **override only.** API-pool diversity hedge (`gpt-5.6-sol-high`, …). Not pinned.
|
|
164
|
+
- **`claude-fable-5-thinking-high`/`-xhigh`** ($$$$) — **override only.** Fable 5. Available, not adopted as default (see `prompts.md` § Effort → Claude model mapping). No Fable 5.1 ID on `/v0/models`.
|
|
165
|
+
|
|
166
|
+
Cloud Agents API: `curl https://api.cursor.com/v0/models -u "$BKIT_CURSOR_API_KEY:"` (agent-specific API key — general keys can HTTP 500 on `POST /v0/agents`). **Verify before install — Cursor models churn.** Probed 2026-10-06: first-party `cursor-grok-4.5-high` + `composer-2.5`; no Grok 4.7; no Opus 5.5 / Sonnet 5.5. Sonnet 5 thinking IDs are present and stay opt-in. Build/ship orchestrators use `composer-2.5`.
|
|
167
|
+
|
|
168
|
+
> [!NOTE]
|
|
169
|
+
> **Native-default Cursor pins.** Defaults are first-party only (`cursor-grok-4.5-high` / `composer-2.5`) so zero API credits still runs the harness. API-pool IDs remain in the live `/v0/models` catalog for manual override. Residual: IDE **subagent-runner** ≠ Cloud Agents API; per-subagent dispatch via `Task` not empirically smoke-tested — confirm one dispatch per model ID before full validation.
|
|
170
|
+
>
|
|
171
|
+
> **Claude opus tier pins `claude-opus-5-5`.** Sonnet tier pins `claude-sonnet-5-5`. Both are 1M context, $4/$20 and $2/$10 per MTok. Haiku tier pins `claude-haiku-5-5` — 1M context, $0.10/$0.50 per MTok up to 100K-token prompts, $0.50/$2.50 above. LiveBench scores the 5.5 pins too, but the opus and sonnet targets stay at `claude-opus-5` **65.2** / `claude-sonnet-5` **59.4** — § Agentic-coding parity board says why. Cursor's `/v0/models` catalog lists `claude-opus-5-thinking-high` / `-fast` and `claude-sonnet-5-thinking-high` / `-xhigh`, not the 5.5 IDs. Cursor defaults stay on native models per the native-only policy above.
|
|
172
|
+
|
|
173
|
+
### Per-subagent model assignment
|
|
174
|
+
|
|
175
|
+
**Lives in `.bkit/prompts.md`** (per-agent metadata with descriptions, effort/maxTurns rationale, tool patterns).
|
|
176
|
+
|
|
177
|
+
`prompts.md`: one row per agent: `name | Cursor model | Claude effort | role hint`. Canonical for Cursor frontmatter rewrite (T3); `.bkit/core/engine/audits/workflows/models-table-parity.test.ts` checks it against the prompt frontmatter.
|
|
178
|
+
|
|
179
|
+
### Per-workflow (orchestrator) model
|
|
180
|
+
|
|
181
|
+
Orchestrator model selection (per workflow, every provider) canonical in **`prompts.md` § Orchestrators** — not duplicated here. Orchestrators use **session model** (commands lack frontmatter): Claude → `/model` before invoke; Cursor → workflow launch (Cloud Agent config / GH Action). Subagent `model:` pins independent — Opus-tier subagents stay pinned regardless of orchestrator. Reasoning-depth (`medium` default) + inlining-drift escalation in `prompts.md` § Orchestrators.
|
|
182
|
+
|
|
183
|
+
### Cursor model label IDs
|
|
184
|
+
|
|
185
|
+
Dashboard label-based routing.
|
|
186
|
+
|
|
187
|
+
> **Stale-risk:** dashboard label-routing UUIDs — distinct from `/v0/models` API IDs; may lag pins. Re-pull from Cloud dashboard before label routing. Per-subagent `model:` frontmatter uses API model-ID string, not these UUIDs.
|
|
188
|
+
|
|
189
|
+
<!-- prettier-ignore -->
|
|
190
|
+
| Label | ID |
|
|
191
|
+
| --- | --- |
|
|
192
|
+
| composer-2.5 | `6daa407f-69d4-4bbd-bdc8-ad846611b668` |
|
|
193
|
+
| claude-4.7-opus-high-thinking | `6b77d100-7454-43d5-82f9-bf6a616c6b4b` |
|
|
194
|
+
| claude-4.6-opus-high-thinking | `41ecf3c1-1574-4226-a116-8d85235bdccf` |
|
|
195
|
+
| claude-4.6-opus-high-thinking-fast | `aaa2bccd-533c-4b73-8f0c-3f2ea469ab71` |
|
|
196
|
+
| gpt-5.4-high | `13b4f4e2-3cab-4a70-89bc-9623ff894373` |
|
|
197
|
+
| gpt-5.4-high-fast | `f6cc71eb-715e-4ceb-955f-d5ff1b12d89b` |
|
|
198
|
+
| gpt-5.4-xhigh-fast | `495b2e79-b62a-46b1-a575-c9993868191b` |
|
|
199
|
+
| gpt-5.3-codex-high | `67005fc3-4c02-4a05-8174-939d92f8fca1` |
|
|
200
|
+
| gpt-5.3-codex-high-fast | `57e86144-6029-4145-a90c-dd64f0b25141` |
|
|
201
|
+
| gpt-5.3-codex-xhigh-fast | `2d56fd4b-70b7-4b89-a26c-50fd3389a0d2` |
|
|
202
|
+
|
|
203
|
+
### Architectural note — `readonly` reconciled
|
|
204
|
+
|
|
205
|
+
**Decision:** Cursor **never emits `readonly:`**. Subagents write directly on both hosts, matching canonical Claude command shape. Cursor subagents have full tool access: Cursor CLI 2026.10.01 ignores the `tools:` allowlist (measured).
|
|
206
|
+
|
|
207
|
+
**Implementation:** T3 in `.bkit/core/engine/render/hosts.ts` emits only `name` / `description` / `model` — no `readonly:`. Generated `.cursor/agents/*.md` confirm zero `readonly:` lines.
|
|
208
|
+
|
|
209
|
+
**Trade-off accepted:** Cursor per-agent runtime safety → tool-allowlist sandboxing once `tools:` lands. Canonical command bodies byte-identical-shape; outputs identical.
|
|
210
|
+
|
|
211
|
+
**Discarded options** (record-only):
|
|
212
|
+
|
|
213
|
+
- Inject orchestrator-write logic into `.cursor/commands/` during T2 — high body-transform divergence.
|
|
214
|
+
- Keep `readonly: true`, document runtime divergence — outputs match, mechanism differs, per-host debugging cost.
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## Command files
|
|
219
|
+
|
|
220
|
+
### Frontmatter
|
|
221
|
+
|
|
222
|
+
<!-- prettier-ignore -->
|
|
223
|
+
| Host | Frontmatter | Notes |
|
|
224
|
+
| --- | --- | --- |
|
|
225
|
+
| Claude | `description:` (single field) | Surfaces in slash-command picker. |
|
|
226
|
+
| Cursor | **none** | Per current Cursor docs, command files are plain markdown. Frontmatter tolerated/ignored on legacy files but not part of spec. |
|
|
227
|
+
|
|
228
|
+
**Transform (Claude → Cursor, command files):** replace the YAML frontmatter block with its `description:` value as a plain first line (Cursor shows a command file's literal first line as its picker/hover description, and does not read frontmatter). No `description:` key → plain strip.
|
|
229
|
+
|
|
230
|
+
### Body
|
|
231
|
+
|
|
232
|
+
- Subagent invocation phrasing — § Subagent invocation transform above.
|
|
233
|
+
- Else (Linear MCP, `git`, `gh`, `pnpm`, steps, `Failure Path`, gates, status.jsonl/lock) identical.
|
|
234
|
+
|
|
235
|
+
### Slash-command activation
|
|
236
|
+
|
|
237
|
+
Both hosts: `/<filename-without-ext>` (`/bkit-build`, `/bkit-plan`, etc.). Identical UX.
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Hooks
|
|
242
|
+
|
|
243
|
+
<!-- prettier-ignore -->
|
|
244
|
+
| Concern | Claude | Cursor |
|
|
245
|
+
| --- | --- | --- |
|
|
246
|
+
| Config file | `.claude/settings.json` → `hooks.SessionStart[].hooks[].command` | `.cursor/hooks.json` → `hooks.sessionStart[].command` (separate JSON file) |
|
|
247
|
+
| Script location | `.claude/hooks/*.sh` | `.cursor/hooks/*.sh` |
|
|
248
|
+
| Trigger names | `SessionStart`, `Stop`, others | `sessionStart`, `stop` (camelCase, lowercase first letter) |
|
|
249
|
+
| Stdin payload | `{ session_id, transcript_path, cwd, permission_mode }` | `{ session_id, is_background_agent, composer_mode }` (sessionStart); `{ status }` (stop) |
|
|
250
|
+
| Blocking | **Cannot block** — non-zero exit treated as non-blocking. Must inject `additionalContext` HARD STOP into prompt + write reason to stderr. | **Can block** via `failClosed: true`. Non-zero exit aborts session. |
|
|
251
|
+
| Output format (sessionStart) | JSON: `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "..." } }` | JSON: `{ "additional_context": "..." }` (snake_case) |
|
|
252
|
+
| Stop hook config | `Stop` array | `stop[].loop_limit` (controls iteration cap; `null` = unlimited) |
|
|
253
|
+
| Telemetry | Not part of host (custom in script) | Not part of host (custom in script — see `postflight.sh` log-drain pattern) |
|
|
254
|
+
|
|
255
|
+
**Install behaviour:** hook scripts are **generated at install** (per host, not from `.agents/`). Semantic differences (blocking, stdin, output JSON) prevent one script for every host, so each host keeps a small hook source (`.bkit/core/.<host>/hooks/`, `.bkit/core/.opencode/plugin/`) holding only its module syntax, payload adapter and output shape. Code every host shares lives once in `.bkit/core/hooks/`; install splices it in wherever a template line reads `// {{BKIT_PART <file>}}` / `# {{BKIT_PART <file>}}` (`.bkit/core/engine/render/parts.ts`). The generated file is plain JS / bash with no runtime call into bkit, so it works without `node_modules`.
|
|
256
|
+
|
|
257
|
+
<!-- prettier-ignore -->
|
|
258
|
+
| Part | Shared by | Holds |
|
|
259
|
+
| --- | --- | --- |
|
|
260
|
+
| `gateguard-engine.js` | Claude, Cursor, Codex, opencode `gateguard` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice` |
|
|
261
|
+
| `gateguard-edit-payload.js` | Claude, Cursor `gateguard` | `Edit` / `Write` / `MultiEdit` payload adapter `bkitGateguard(payload)` |
|
|
262
|
+
| `guardrails-shell.js` | Claude, Cursor, Codex `guardrails` | segment parsing, curl / wget host allowlist, shell-as-edit-channel detection |
|
|
263
|
+
| `guardrails-tiers.js` | Cursor, Codex `guardrails` | deny rules, ask patterns, `classifyShell` precedence |
|
|
264
|
+
| `preflight-linear.sh` | Claude, Cursor `preflight` | Linear key / issue checks, GraphQL query, `bkit:auto` + terminal-state guards |
|
|
265
|
+
|
|
266
|
+
Per host, outside the parts: Claude `gateguard` / `guardrails` — `require` + `hookSpecificOutput` driver, guardrails advisory-only; Cursor — `{ permission }` output, guardrails read gate (`.pem` / `.env`), gateguard workspace-relative path resolve; Codex — `apply_patch` envelope parser, ask tier emitted as advisory; opencode — ES module, `write` / `edit` / `patch` vocabulary, checklist appended to the tool result in `execute.after` + throw from `execute.before` to block (2.0 exposes no pre-edit context hook, and stderr does not reach the model); `preflight` — trigger (Claude `LINEAR_ISSUE_ID`, Cursor `is_background_agent` + `.bkit/.runtime-cursor` marker), Claude-only Darwin brew check, `emit_context` shape.
|
|
267
|
+
|
|
268
|
+
### GateGuard
|
|
269
|
+
|
|
270
|
+
Advisory hook, on all four hosts (Claude Code, Cursor, Codex, opencode). Claude / Cursor / Codex inject the checklist pre-edit (PreToolUse); opencode 2.0 exposes no pre-edit context hook, so it appends the checklist to the tool result in the post-execute hook — the first edit's result, not a pre-edit gate — and reserves the pre-execute hook for deny mode. First file touch per session → investigation checklist; gate-config paths (JS/TS: tsconfig/eslint/prettier/vitest/jest/vale/slop/lint-staged; Python: pyproject.toml/ruff/flake8/mypy; Go: golangci; Rust: clippy/rustfmt) → "fix code, don't weaken gate" advisory, except under a consumer's `.bkit/templates/` (reference copies; in bkit's own repo, package name `@cbartens/bkit`, that folder is the template source and stays guarded); new-file writes → reuse-over-duplicate nudge; `docs/**.md` (not `docs/plans/`) → density advisory appended. **fail-open**, **subagents included**, dedup `(session, file)` via OS-temp state, 24h TTL.
|
|
271
|
+
|
|
272
|
+
<!-- prettier-ignore -->
|
|
273
|
+
| Host | Implementation | File | Registration |
|
|
274
|
+
| --- | --- | --- | --- |
|
|
275
|
+
| Claude Code | `bkit-gateguard.cjs` (CJS) | `.claude/hooks/bkit-gateguard.cjs` | `.claude/settings.json` → `hooks.PreToolUse` on `Edit\|Write\|MultiEdit` |
|
|
276
|
+
| opencode | `bkit-gateguard.js` (ESM) | `.opencode/plugin/bkit-gateguard.js` | `.opencode/opencode.json` → `plugin` array, spec `./plugin/bkit-gateguard.js` (config-file-relative; opencode 2.0 reads a bare `.opencode/…` spec as an npm package and fails to load — the plugin also auto-loads from `.opencode/plugin/`) |
|
|
277
|
+
| Cursor | `bkit-gateguard.cjs` (CJS) — managed block generated from the same parts as the Claude twin, so byte-identical | `.cursor/hooks/bkit-gateguard.cjs` | `.cursor/hooks.json` → `preToolUse` (matcher `Write`), no `failClosed` — an advisory hook that fails closed would block the edit it only meant to comment on |
|
|
278
|
+
| Codex | `bkit-gateguard.cjs` (CJS) — Claude's stdin/stdout contract; parses the `apply_patch` envelope for target paths | `.codex/hooks/bkit-gateguard.cjs` | `.codex/hooks.json` → `hooks.PreToolUse` on `apply_patch` |
|
|
279
|
+
| Cursor | `bkit-guardrails.cjs` (CJS) — destructive-op / secret-exposure gates, the Cursor equivalent of Claude's `permissions` and opencode's `permission` map | `.cursor/hooks/bkit-guardrails.cjs` | `.cursor/hooks.json` → `beforeShellExecution` + `preToolUse` (`Read\|TabRead`), both `failClosed` |
|
|
280
|
+
|
|
281
|
+
**Ownership:** both GateGuard files — and Cursor's `bkit-guardrails.cjs` — are **markered-text** (slash-comment: `// bkit:start` / `// bkit:end`). bkit owns only the advisory engine between the markers and reconverges it on every install / upgrade; the driver around it — Claude's stdin read + single `emit()`, opencode's exported `plugin` — is consumer-owned from first install onward, so consumer advisories survive upgrades. bkit's block is pure (no stdin, no stdout / stderr, no top-level call): Claude Code parses hook stdout as one JSON document, so two emitters would produce `{...}{...}` and the whole hook's output — bkit's included — is discarded. Marker-less file on upgrade → hash matches a bkit release: replaced wholesale; hash unknown: block appended plus printed wiring instructions. Uninstall strips the block, leaving the consumer's driver working. `bkit-guardrails.cjs` follows the identical split: bkit owns `bkitGuardrails(payload)`, which returns a decision object or `null` for no-opinion, and the consumer owns the stdin read and the single `emit()`.
|
|
282
|
+
|
|
283
|
+
**Modes (env):** unset → advisory _[default]_; `BKIT_GATEGUARD=off` → disabled; `BKIT_GATEGUARD=deny` → deny first touch (checklist as reason), allow retry. `BKIT_ALLOW_CONFIG_EDIT=1` suppresses gate-config advisory.
|
|
284
|
+
|
|
285
|
+
**Subagents:** not exempt on any host. A subagent edit is an edit, and dedup is per (session, file) with a subagent carrying its own session id, so it gets its own checklist. No host reads a subagent marker (Claude's `agent_id`, opencode's `parentID`); Cursor's payload carries none.
|
|
286
|
+
|
|
287
|
+
**Deny mode, per host:** Claude and Codex `permissionDecision: "deny"` with the checklist as `permissionDecisionReason`; Cursor `permission: "deny"` with the checklist as `agent_message` (`user_message` goes to the human, not the model); opencode throws from `execute.before` — the only hook that can block — and appends the checklist to the tool result in `execute.after`, because 2.0 exposes no pre-edit context hook and stderr does not reach the model. Same behaviour, three delivery mechanisms across four hosts; asserted uniformly in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts`.
|
|
288
|
+
|
|
289
|
+
**Divergence budget:** every host's block carries `hooks/gateguard-engine.js` verbatim, and the Claude and Cursor blocks are byte-identical (both test-asserted on the generated hooks). opencode's differs only where the runtime forces it — ES module rather than CJS, tool vocabulary `write`/`edit`/`patch` rather than `Edit`/`Write`/`MultiEdit`. Codex's differs only in its payload — every edit arrives as `apply_patch` with a V4A envelope and no file path, so its block carries the envelope parser. Every advisory string, gate-config pattern and docs-path rule is identical across all four.
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## Permissions / auto-approve
|
|
294
|
+
|
|
295
|
+
<!-- prettier-ignore -->
|
|
296
|
+
| Concern | Claude | Cursor | opencode |
|
|
297
|
+
| --- | --- | --- | --- |
|
|
298
|
+
| File / secrets | `.claude/settings.json` → `permissions.{allow,deny,ask}` (`Read(./**/*.pem)` deny; `.env` variants ask; `.env.example` allow) | `.cursor/hooks/bkit-guardrails.cjs` via `preToolUse` (`Read\|TabRead`) — same deny/ask policy | `.opencode/opencode.json` → `permission.read` map |
|
|
299
|
+
| Shell / destructive | `permissions.deny` / `ask` on force-push (not `--force-with-lease`), `rm -rf /*`, publish, destructive git/gh, etc. Shell `curl` / `wget` are not gated here — `permissions` cannot match a URL host, so only the `WebFetch` TOOL is allowlisted | `.cursor/hooks/bkit-guardrails.cjs` via `beforeShellExecution` — same deny/ask policy | `permission.bash` deny/ask map (same rules) |
|
|
300
|
+
| Network fetch | `WebSearch` + tooling `WebFetch(domain:…)`; install/upgrade enriches from the shipped egress registry union consumer `allowed-domains` in `.agents/context.md` (stack hosts never shipped), recording what it wrote so it can later prune it | `curl`/`wget` ask unless host ∈ `.cursor/allowlist.json` (tooling ∪ consumer domains) | `websearch` allow + `webfetch: "ask"`; `curl *` ask then `curl *{domain}*` allow from same allowlist (baked into `opencode.json`) |
|
|
301
|
+
| Granularity | Per-tool glob | Hook script (project-scoped, failClosed) | Per-path / per-command glob in `permission` |
|
|
302
|
+
| Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` | Implicit per-mode (Composer / Agent / Background) | `opencode --auto` + permission defaults |
|
|
303
|
+
| MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` |
|
|
304
|
+
| MCP tool approval | `permissions.allow` `mcp__<s>__*` from consumer `mcp-servers` (§ MCP servers) | Generated `.cursor/cli.json` `Mcp(<s>:*)` | `permission` `"<s>_*": "allow"` |
|
|
305
|
+
| Local-only (not shipped) | `.claude/settings.local.json` (`additionalDirectories`, extra allows) | Cursor project/user settings / MCP as needed | `~/.config/opencode/opencode.json` → `permission.external_directory` |
|
|
306
|
+
|
|
307
|
+
**Install behaviour:** template drops, host-specific encoding of the **same** shared policy. No single canonical JSON — three native forms kept in lockstep. Machine-local paths stay out of templates.
|
|
308
|
+
|
|
309
|
+
### Network allowlist — one source, three encodings
|
|
310
|
+
|
|
311
|
+
**Source of truth:** bkit's own hosts come from the egress registry (`.bkit/core/engine/shared/egress.ts`) and must never be re-declared. Stack domains come from consumer `.agents/context.md` → `<!-- allowed-domains:start -->` **after** `<!-- bkit:end -->` (apex domains). Never ship Vercel/Supabase/Sentry/etc. into every consumer.
|
|
312
|
+
|
|
313
|
+
**`bkit install` / `bkit upgrade` apply that set differently per host** — same policy, native mechanics:
|
|
314
|
+
|
|
315
|
+
<!-- prettier-ignore -->
|
|
316
|
+
| Host | Where the allowlist lives | Why that shape |
|
|
317
|
+
| --- | --- | --- |
|
|
318
|
+
| **Claude** | `.claude/settings.json` `WebFetch(domain:…)` allow rules; shell fetches host-checked by `.claude/hooks/bkit-guardrails.cjs` (advisory) | Claude has a first-class settings permission model. No separate allowlist file. Shell `curl` is not domain-gated at all — Claude rules match a command prefix, not a URL host, so `curl` runs under `Bash(*)` with `deny` + the auto-mode classifier as backstops. Prefer `WebFetch` for allowlisted hosts; context-fetch uses `curl` / CLI under `Bash(*)`. |
|
|
319
|
+
| **OpenCode** | Baked into `.opencode/opencode.json` → `permission.bash`: `curl *` / `wget *` **ask**, then `curl *{domain}*` / `wget *{domain}*` **allow** (last-match-wins) | OpenCode `webfetch` is Action-only (`ask`\|`allow`\|`deny`) — cannot store a URL map. Domain exceptions for shell fetch live in `bash`. No separate allowlist file. |
|
|
320
|
+
| **Cursor** | Generated `.cursor/allowlist.json` read at **runtime** by `.cursor/hooks/bkit-guardrails.cjs` | Cursor has no project settings equivalent to Claude `permissions` / OpenCode `permission` for curl host globs. Parity is a **hook** (`beforeShellExecution`): ask on `curl`/`wget` unless the command contains a host from the allowlist. The JSON is Cursor-only by design (IDE-scoped artifact under `.cursor/`, not `.bkit/`). |
|
|
321
|
+
|
|
322
|
+
**Do not hand-edit** `.cursor/allowlist.json` — regenerate via install/upgrade after changing `allowed-domains`. Missing file ⇒ the hook resolves no hosts and every host reads as unknown; there is deliberately no list embedded in the hook, because a second copy drifts from the registry silently.
|
|
323
|
+
|
|
324
|
+
**Cloud egress (separate):** the derived registry union the same `allowed-domains` feed `.claude/bkit-cloud.md` / `.cursor/bkit-cloud.md` paste instructions for dashboard network Custom allowlists — that is proxy egress, not local agent permission files. See `.agents/context.md` § Allowed domains and `.bkit/cloud.md`.
|
|
325
|
+
|
|
326
|
+
### MCP servers — one source, three encodings
|
|
327
|
+
|
|
328
|
+
**Source of truth:** consumer `.agents/context.md` → `<!-- mcp-servers:start -->` **after** `<!-- bkit:end -->`, one server name per line. Every tool on a listed server (reads and writes) runs without a prompt on every host; an unlisted server keeps each host's default. bkit ships no server names — only what the consumer lists.
|
|
329
|
+
|
|
330
|
+
<!-- prettier-ignore -->
|
|
331
|
+
| Host | Where the allows live | Rule per server `<s>` |
|
|
332
|
+
| --- | --- | --- |
|
|
333
|
+
| **Claude** | `.claude/settings.json` `permissions.allow`, recorded in `.bkit/version` `claudeAllowDerived` so a server dropped from the block is pruned | `mcp__<s>__*` (`.mcp.json` servers; claude.ai connectors in cloud sessions) + `mcp__claude_ai_<s>__*` (claude.ai connectors in the local CLI) |
|
|
334
|
+
| **Cursor** | Generated `.cursor/cli.json` `permissions.allow` — Cursor CLI + cloud agents. The IDE agent's MCP auto-run list is user-level only | `Mcp(<s>:*)` |
|
|
335
|
+
| **OpenCode** | Baked into `.opencode/opencode.json` → `permission` | `"<s>_*": "allow"` — opencode names MCP tools `<s>_<tool>` |
|
|
336
|
+
|
|
337
|
+
**Spelling is per host:** a name matches a tool id verbatim — list each spelling a host uses (`sentry` for a `.mcp.json` server, `Sentry` for the claude.ai connector). **Do not hand-edit** `.cursor/cli.json` — it is regenerated whole on install/upgrade. Codex: no project-level MCP approval file — out of scope.
|
|
338
|
+
|
|
339
|
+
### MCP config asymmetry — GitHub tracker
|
|
340
|
+
|
|
341
|
+
Both hosts: same `mcpServers` shape; files differ:
|
|
342
|
+
|
|
343
|
+
<!-- prettier-ignore -->
|
|
344
|
+
| Host | File | Written by |
|
|
345
|
+
| --- | --- | --- |
|
|
346
|
+
| Claude Code | `.mcp.json` at repo root | `bkit install --tracker=github` writes the `github` entry |
|
|
347
|
+
| Cursor | `.cursor/mcp.json` | `bkit install --tracker=github` writes the same `mcpServers.github` block |
|
|
348
|
+
|
|
349
|
+
Both: `"type": "http"`, `"url": "https://api.githubcopilot.com/mcp/"`, `"headers": { "Authorization": "Bearer ${BKIT_GH_TOKEN}" }`. `${BKIT_GH_TOKEN}` at session start — must be in shell (local) or dashboard env (cloud). See `.bkit/cloud.md` § MCP issue-tracker integration for full JSON.
|
|
350
|
+
|
|
351
|
+
**bkit owns one entry per file.** In `.mcp.json` / `.cursor/mcp.json` bkit owns only `mcpServers.<tracker>`: an absent file gets the tracker-filtered render; in an existing file install and upgrade reset that one entry to the template and keep every other key, in its order (malformed JSON stops the install). `bkit check` reports a pending reset. Tracker `none` owns no entry. A tracker switch (e.g. `--tracker=linear` → `--tracker=github`) adds the new entry and leaves the old one. Uninstall removes bkit's entry while it still equals the template. Advisories: `mcp-missing-server-<name>` (file lacks needed server), `mcp-extra-server-<name>` (bkit-managed server the configured tracker does not use). Consumer-added MCP servers never flagged.
|
|
352
|
+
|
|
353
|
+
> Note: `mcpServers` in `.claude/settings.json` silently ignored for server defs — only `.mcp.json` (project) or `claude mcp add` (user) take effect. Tool-permission `allow` (`mcp__github__*`) remain in settings.
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
## Runtime environment (cloud agents)
|
|
358
|
+
|
|
359
|
+
> Setup recipe + alignment: `.bkit/cloud.md`. This section = host-diff matrix only.
|
|
360
|
+
|
|
361
|
+
<!-- prettier-ignore -->
|
|
362
|
+
| Concern | Claude Code on the web | Cursor Background Agents |
|
|
363
|
+
| --- | --- | --- |
|
|
364
|
+
| Where env config lives | Claude app (per-environment), not in repo | In repo (`.cursor/`) |
|
|
365
|
+
| Custom base image | Not supported — setup script layers on top of Anthropic-managed Ubuntu 24.04 | Supported — `.cursor/Dockerfile` |
|
|
366
|
+
| Cold-start cache | Snapshot keyed by setup-script body hash (~7d TTL) | Docker image layers |
|
|
367
|
+
| Per-snapshot install | `.claude/hooks/bkit-cloud-bootstrap.sh` (SessionStart, fires when `CLAUDE_CODE_REMOTE=true`) | `.cursor/environment.json` → `install` |
|
|
368
|
+
| Build env | Setup script (paste-in via Claude app UI) | `.cursor/Dockerfile` (Cursor Cloud builds custom image) |
|
|
369
|
+
| Install/start | n/a (handled by bootstrap hook) | `.cursor/environment.json` → `install`, `start`, `terminals[]`, `env`, `ports` |
|
|
370
|
+
| Port forwarding | n/a | `.cursor/environment.json` → `terminals[].ports` |
|
|
371
|
+
| Cloud-session detection | `CLAUDE_CODE_REMOTE=true` (env var) | `is_background_agent === true` (stdin JSON) |
|
|
372
|
+
| Default network | `Trusted` allowlist (npm, GitHub, PyPI, Docker Hub, vale tarball) | Outbound open in the sandbox |
|
|
373
|
+
| Reusable across repos | Setup script yes (generic snapshot); environment no — one per repo (secrets / PAT scope are per-repo) | No — Dockerfile per repo (copied from the bkit template and owned by the repo) |
|
|
374
|
+
| Secrets | Env vars in Claude app (plaintext; rotate PATs) | Cursor Cloud env vars (Settings → Background Agents → Environment Variables) |
|
|
375
|
+
| Linear preflight | `.claude/hooks/bkit-preflight.sh` (SessionStart, non-blocking — uses `additionalContext` HARD STOP) | `.cursor/hooks/bkit-preflight.sh` (`sessionStart`, `failClosed: true`, blocks on non-zero) |
|
|
376
|
+
|
|
377
|
+
**Install behaviour:** template drops; project tokens at install. Both clouds aligned via bkit: vale 3.9.1, pnpm (corepack-pinned `package.json#packageManager`), gh CLI. See `.bkit/cloud.md` for paste-in recipe + sharing pattern.
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
381
|
+
## Models
|
|
382
|
+
|
|
383
|
+
### Per-provider live model lookup
|
|
384
|
+
|
|
385
|
+
Installed provider catalog changes. Look up model IDs before pinning in `.opencode/opencode.json`:
|
|
386
|
+
|
|
387
|
+
<!-- prettier-ignore -->
|
|
388
|
+
| Provider | Command | Notes |
|
|
389
|
+
| --- | --- | --- |
|
|
390
|
+
| Claude (Anthropic) | `curl https://api.anthropic.com/v1/models -H "x-api-key: $BKIT_ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01"` | Canonical `Claude` column source. No key in-shell → cross-check via the OpenRouter `anthropic/*` mirror. |
|
|
391
|
+
| Cursor | `curl https://api.cursor.com/v0/models -u "$BKIT_CURSOR_API_KEY:"` | `Cursor` column source. Catalog churns. Probed 2026-10-06: `cursor-grok-4.5-high`, `composer-2.5`, `claude-opus-5-thinking-high`, `claude-sonnet-5-thinking-high`/`-xhigh`, `gpt-5.6-*`, Fable 5. No Grok 4.7. No Opus 5.5 / Sonnet 5.5. |
|
|
392
|
+
| OpenRouter | `curl https://openrouter.ai/api/v1/models` | **Public — no key.** Aggregator; `vendor/model` slugs (`:free` variants exist). Filter for tool-calling + coding models before pinning. |
|
|
393
|
+
| Ollama | `curl https://ollama.com/v1/models -H "Authorization: Bearer $BKIT_OLLAMA_API_KEY"` | Hosted Ollama; cloud-tagged models (e.g. `qwen3.5:397b`, `kimi-k2.7-code`). |
|
|
394
|
+
| OpenCode Zen / Go (opencode-native gateways) | `curl https://models.dev/api.json` — read providers `.opencode` (Zen) and `.["opencode-go"]` (Go) `.models` | **models.dev is the source of truth — not `/zen/v1/models`.** The REST catalog `curl https://opencode.ai/zen/v1/models` returns only the Zen catalog and cannot see Go-only models (`minimax-m3`, `qwen3.7-plus`/`qwen3.7-max`, …), so it must not be used to curate the Go column. Two DISTINCT providers: `opencode` (name "OpenCode Zen", api `https://opencode.ai/zen/v1`) and `opencode-go` (name "OpenCode Go", api `https://opencode.ai/zen/**go**/v1` — nested under `/zen/`). Both auth via `BKIT_OPENCODE_API_KEY`. Tool-call smoke: `POST <api>/chat/completions` with a `tools:` payload (bare model id, e.g. `minimax-m3`). |
|
|
395
|
+
|
|
396
|
+
**Model ID format:** opencode provider-prefixed frontmatter: `<provider>/<model-id>` (e.g. `openrouter/moonshotai/kimi-k3`, `ollama/kimi-k2.7-code`). Pins = `prompts.md` § Models — **one column per provider** (`OpenRouter`, `Ollama`, `OpenCode Zen`, `OpenCode Go`). Gateways: `opencode/<id>` Zen, `opencode-go/<id>` Go. CLI keys `opencode-zen` / `opencode-go`.
|
|
397
|
+
|
|
398
|
+
**Lookup mechanic (install pin resolution).** `bkit install --opencode=<provider>` → `buildOpencodeModelLookup(promptsMdPath, provider)` (`.bkit/core/engine/render/models.ts`):
|
|
399
|
+
|
|
400
|
+
1. Provider key → `prompts.md` column via `OPENCODE_PROVIDER_COLUMN` (`openrouter`→`OpenRouter`, `ollama`→`Ollama`, `opencode-zen`→`OpenCode Zen`, `opencode-go`→`OpenCode Go`).
|
|
401
|
+
2. Parse column → seed `.opencode/agents/<name>.md` `model:` verbatim.
|
|
402
|
+
|
|
403
|
+
**opencode-zen / opencode-go — two OpenCode built-in providers.** Both emit minimal `provider.<id>` with only `options.apiKey: "{env:BKIT_OPENCODE_API_KEY}"` (no npm driver, no baseURL). OpenCode resolves from models.dev — Go Qwen/MiniMax use Anthropic `/messages`, not openai-compatible `/chat/completions`. Zen keyed `opencode`; Go `opencode-go`. `bkit install --opencode=opencode-zen` (or `=opencode-go`) → `bkit.opencodeProvider` in `package.json`; legacy `opencode` → `opencode-zen` via `OPENCODE_PROVIDER_ALIASES`. Reinstall **replaces** seeded block (heals hijacked npm/baseURL). Set `BKIT_OPENCODE_API_KEY` in `.bkit/.env` (<https://opencode.ai/auth>). Columns from **models.dev**.
|
|
404
|
+
|
|
405
|
+
**All four providers ship curated columns.** Tier design — **per-tier quality target, cheapest sufficient pin**. A tier cell is not "the same rung of this provider's ladder": it is the cheapest model that **reaches that tier's Claude score**, and reaching means _approaching_ — it does not have to beat it. Targets are the LiveBench Agentic Coding scores on the board below (opus `claude-opus-5` **65.2**, sonnet `claude-sonnet-5` **59.4**, haiku `claude-haiku-5-5` **~51**). The opus and sonnet targets stay the 5.0 scores although the 5.5 pins are on the CSV: `claude-opus-5-5` lands level at `xhigh` (65.4), and the `claude-sonnet-5-5` rows don't read cleanly (see the board). The haiku target is Haiku 5.5 at `xhigh`, the closest measured rung to the `high` effort the summary writers run at. Where a provider's ceiling sits under the sonnet target, opus+sonnet **collapse onto that ceiling** — spreading them across two rungs buys nothing and costs quality on the sonnet half. Where a cheap model already clears the haiku target, the haiku cell **stays cheap** — a $5/task flagship serving a read-and-emit summariser is waste, not safety.
|
|
406
|
+
|
|
407
|
+
### Selecting pins
|
|
408
|
+
|
|
409
|
+
Re-pin **one provider column at a time**. Cells: `prompts.md` § Models. Board below = scores.
|
|
410
|
+
|
|
411
|
+
**Priority — do not invert.**
|
|
412
|
+
|
|
413
|
+
1. **Claude parity** — LiveBench Agentic Coding (pin score) + AA Intelligence Index. Miss the target → not a pin.
|
|
414
|
+
2. **Cost** — cheapest that clears (or the ceiling). AA $/task + LiveBench $/task, rescaled to the billed provider.
|
|
415
|
+
3. **Speed** — remaining ties: AA tok/s, TTFT, think→answer, E2E 500-token.
|
|
416
|
+
|
|
417
|
+
Filters (not above score): endpoint count; automatic prompt caching (bkit sends no `cache_control`). **Never pin Claude** on OpenRouter / Ollama / OpenCode. Convergent = distinct CoT family, not a fourth rung.
|
|
418
|
+
|
|
419
|
+
**Steps.**
|
|
420
|
+
|
|
421
|
+
1. Read `prompts.md` § Models + lineup below.
|
|
422
|
+
2. Pull every source; stamp the date. LiveBench `table_<date>.csv` name ≠ freshness.
|
|
423
|
+
3. Slug live? § Per-provider live model lookup. OpenRouter: also `GET /api/v1/models/{slug}/endpoints`.
|
|
424
|
+
4. Shortlist 1–2 / tier. Reject single-endpoint + `cache_control` hosts (Anthropic, Alibaba) unless no alternative.
|
|
425
|
+
5. Apply: `prompts.md` § Models + this board + `.bkit/core/engine/render/models.test.ts` OpenRouter tests + `bkit install`. Stamp `prompts.md` § Live model-ID verification.
|
|
426
|
+
|
|
427
|
+
**Sources — check all.**
|
|
428
|
+
|
|
429
|
+
<!-- prettier-ignore -->
|
|
430
|
+
| Pri | Source | Decides | URL |
|
|
431
|
+
| --- | --- | --- | --- |
|
|
432
|
+
| 1 | LiveBench Agentic Coding | Pin score (JS / TS / PY mean) | https://livebench.ai/#/?cats=Agentic+Coding — CSV `https://raw.githubusercontent.com/LiveBench/new-livebench/main/public/table_2026_06_25.csv` |
|
|
433
|
+
| 1 | AA Intelligence Index | General intelligence | https://artificialanalysis.ai/leaderboards/models |
|
|
434
|
+
| 1 | DeepSWE | Long-horizon repo work — public board only | https://deepswe.datacurve.ai |
|
|
435
|
+
| 1 | LMArena Code Arena — WebDev | Web-dev preference | https://lmarena.ai (Code / WebDev) |
|
|
436
|
+
| 1 | Design Arena — Code | Web-app preference | https://designarena.ai/leaderboard/code |
|
|
437
|
+
| 1 | CursorBench | Agentic coding at **every effort level** (`low` → `max`) with $/task — the source for choosing an agent's `effort:`; cross-checks LiveBench. Cursor's own `composer-*` rows count as vendor-only | https://cursor.com/cursorbench |
|
|
438
|
+
| 2–3 | AA cost / latency | $/task, tok/s, TTFT, E2E | same AA leaderboard |
|
|
439
|
+
| 2 | LiveBench cost table | Agentic $/task — rescale to billed provider | `cost_2026_06_25.csv` beside the LiveBench table |
|
|
440
|
+
| 2 | OpenRouter model page | List in/out + cache-read | https://openrouter.ai/models/{slug} |
|
|
441
|
+
| filter | OpenRouter endpoints | Host count; 1 = reject | `GET /api/v1/models/{slug}/endpoints` |
|
|
442
|
+
| filter | OpenRouter prompt-caching doc | Auto vs `cache_control`; ignore `supports_implicit_caching` | https://openrouter.ai/docs/features/prompt-caching |
|
|
443
|
+
| filter | Provider catalogs | Existence / context / plan gates | § Per-provider live model lookup |
|
|
444
|
+
|
|
445
|
+
**Do not pin from:** OpenRouter volume; BenchGecko; vendor-only Terminal-Bench / SWE; launch blogs.
|
|
446
|
+
|
|
447
|
+
### Agentic-coding parity board
|
|
448
|
+
|
|
449
|
+
Source: [LiveBench](https://livebench.ai/#/?cats=Agentic+Coding), release **2026-06-25** (`table_2026_06_25.csv` / `cost_2026_06_25.csv`, `LiveBench/new-livebench`). **Score** = mean of the category's three tasks (`javascript`, `typescript`, `python`), per `public/categories_<date>.json`. **$/task** = category dollars ÷ 72 questions, from LiveBench's own cost table. Process + sources: § Selecting pins. Artificial Analysis stays the source for price/latency and general capability; agentic-coding score decides a **pin**, because that is the workload every bkit agent runs.
|
|
450
|
+
|
|
451
|
+
**Re-probe on a schedule, never on a release stamp.** LiveBench appends newly released models to the **existing** `table_<date>.csv` — `RELEASES` in its `src/lib/constants.js` stays put while the file's contents move. The cited date is not a freshness signal, and a column can go stale with nothing here looking stale.
|
|
452
|
+
|
|
453
|
+
**$/task must be rescaled to the provider actually billed.** LiveBench's cost table assumes direct-vendor pricing; an OpenRouter pin is billed at OpenRouter's `pricing.prompt` / `pricing.completion`. The two diverge (LiveBench assumes `$3/$15` per Mtok for `claude-sonnet-5`; OpenRouter charges `$2/$10`). Solve LiveBench's dollar figure for implied input tokens, then re-price.
|
|
454
|
+
|
|
455
|
+
**Sub-scores are too coarse to pin on; use them to sanity-check, not to decide.** Question counts are JS 22 / TS 30 / PY 20, so one TypeScript question moves that sub-score 3.33 points (SE ≈ 9). TypeScript is the hardest of the three and every model scores below its own mean there — the Claude ladder is **not monotonic on TypeScript** (`claude-sonnet-5` 50.0 sits above `claude-opus-5` 43.3). Read the mean as the pin criterion; do not read it as a ranking of ability in any one language.
|
|
456
|
+
|
|
457
|
+
**Score is necessary, not sufficient — operational shape decides ties.** Two properties carry real weight once scores are within noise: **endpoint count** (`/api/v1/models/<slug>/endpoints`) and **whether prompt caching applies without client configuration**. A single-endpoint model cannot be routed around a slow or down host and inherits that one provider's rate limits — disqualifying for a column whose whole job is to absorb work when the Claude quota is spent. Caching is the dominant latency and cost term for bkit workloads: without it every turn of a long agentic loop re-prefills the whole growing transcript.
|
|
458
|
+
|
|
459
|
+
**Read caching from the provider docs, not from `supports_implicit_caching`.** That endpoint field is unreliable — it reports `false` on all 14 `kimi-k3` endpoints while OpenRouter's own [prompt-caching doc](https://openrouter.ai/docs/features/prompt-caching) states Moonshot caching is automated. The doc's per-provider sections are authoritative. Current contracts: **Moonshot, DeepSeek, Z.AI, Gemini 2.5+ cache automatically, no configuration**; **Anthropic, Alibaba Qwen require explicit `cache_control` breakpoints**, which bkit does not send — so an Alibaba-hosted pin gets no caching at all. Cache reads run ~0.03x-0.20x of input price; writes are free except on DeepSeek (charged at input price).
|
|
460
|
+
|
|
461
|
+
**Cache hits need the same endpoint twice — OpenRouter handles this with sticky routing.** After a cached request it pins the conversation to that provider, keyed by `session_id` / `prompt_cache_key` when sent, otherwise by hashing the first system message plus the first non-system message. Sticky sessions expire after **10 minutes of inactivity**, and sticky routing is disabled entirely when `provider.order` is set — do not pin a provider order on a cached model.
|
|
462
|
+
|
|
463
|
+
<!-- prettier-ignore -->
|
|
464
|
+
| Model | Score | $/task | Role in bkit |
|
|
465
|
+
| --- | --- | --- | --- |
|
|
466
|
+
| `deepseek-v4.1-flash` | **77.3** | $0.06 | `openrouter` opus+sonnet — 16+ endpoints, auto cache; clears 65.2. Haiku on `ollama` + `opencode-go` |
|
|
467
|
+
| `claude-opus-5-5` (max) | 71.7 | $4.48 | Claude opus pin at `max` |
|
|
468
|
+
| `claude-opus-5-5` (xhigh) | 65.4 | $1.40 | Claude opus pin at `xhigh` — level with the opus target at about a quarter of the cost |
|
|
469
|
+
| `claude-opus-5` (max) | **65.2** | $5.34 | **opus target** |
|
|
470
|
+
| `deepseek-v4-flash-vision-exp` | 65.1 | $0.11 | **not pinned** — experimental; its own datasheet claims text parity with `deepseek-v4-flash-0731`, which measures 46.8. Score not trusted |
|
|
471
|
+
| `qwen3.8-max` | 64.6 | $1.75 | **not pinned** — single endpoint (Alibaba) and **no caching available**: Alibaba requires explicit breakpoints and this slug is absent from its supported list |
|
|
472
|
+
| `kimi-k3` | 62.2 | $1.76 | `openrouter` convergent — 17 endpoints, auto cache (reads 0.10x, writes free) |
|
|
473
|
+
| `claude-fable-5` (max) | 62.2 | $8.86 | not adopted — below Opus 5 at 1.7x the cost |
|
|
474
|
+
| `qwen3.8-27b` | 61.4 | $1.52 | **not pinned** — 3.57M input tokens/task; `$0.95` on LiveBench's assumed price, `$1.52` at OpenRouter's |
|
|
475
|
+
| `glm-5.3` | 60.9 | $1.60 | **not pinned** — 27 endpoints, auto cache; dominated by V4.1 Flash |
|
|
476
|
+
| `claude-sonnet-5` (xhigh) | **59.4** | $2.14 | **sonnet target** |
|
|
477
|
+
| `gemini-3.7-flash` | 58.3 | $0.42 | **not pinned** — under V4.1 Flash |
|
|
478
|
+
| `claude-haiku-5-5` (max) | 57.2 | $0.21 | Claude haiku pin at `max` |
|
|
479
|
+
| `grok-4.6` | 57.0 | $1.79 | **not pinned** — under V4.1 Flash, higher cost |
|
|
480
|
+
| `glm-5.3-flash` | 56.8 | $0.11 | `openrouter` + `opencode-zen` haiku — 27 endpoints, auto cache; cheapest sufficient |
|
|
481
|
+
| `grok-4.5` | 56.5 | $0.54 | `cursor` opus (ceiling; −2.9 vs sonnet target at a quarter the cost) |
|
|
482
|
+
| `claude-sonnet-5-5` (max) | 56.3 | $5.57 | Claude sonnet pin at `max`. Python 35.0 at both efforts (n=20) |
|
|
483
|
+
| `deepseek-v4-pro-0813` | 54.9 | $0.22 | **not pinned** — dominated by V4.1 Flash |
|
|
484
|
+
| `claude-haiku-5-5` (xhigh) | **51.4** | $0.07 | **haiku target** — closest measured rung to bkit's `high` (CursorBench: `high` 42.3%, `xhigh` 44.3%) |
|
|
485
|
+
| `gpt-6-luna` | 51.2 | $0.03 | `OpenAI` (Codex) haiku — existence via models.dev only |
|
|
486
|
+
| `claude-opus-4-8` (max) | 50.5 | $4.96 | superseded — shows the 4.8 → 5 generational jump (+14.7) |
|
|
487
|
+
| `kimi-k2.7-code` | 45.7 | $0.39 | `ollama`-cloud opus+sonnet (Zen re-pinned to V4.1 Flash — no model variants, so a `variant:` pin hard-errors on 2.0) |
|
|
488
|
+
| `qwen3.7-max` | 43.6 | $0.80 | not pinned (anchor for the unmeasured `qwen3.7-plus`) |
|
|
489
|
+
| `deepseek-v4-pro` | 42.6 | $0.14 | convergent on `ollama` / both gateways; `opencode-go` opus+sonnet. Gone from Ollama's advertised catalog (2026-10-09) but still resolves — re-pin the `ollama` convergent cell before it stops. **Frozen on the 0423 snapshot** — the undated slug does not float |
|
|
490
|
+
| `qwen3.6-plus` | 41.4 | $1.55 | **not pinned** — strictly dominated by `kimi-k2.7-code` (lower score, 4x cost) |
|
|
491
|
+
| `minimax-m3` | 40.7 | $0.42 | **not pinned** — `deepseek-v4-pro` scores higher at a third the cost |
|
|
492
|
+
| `claude-sonnet-5-5` (xhigh) | 39.3 | $0.50 | **not read as a target** — Anthropic recalibrated effort on 5.5, and this run wrote about half Sonnet 5's output tokens before stopping. CursorBench, Artificial Analysis and Anthropic all put 5.5 above 5 at every effort |
|
|
493
|
+
| `deepseek-v4-flash` | 37.6 | **$0.03** | **not pinned** — under the ~51 haiku target |
|
|
494
|
+
| `claude-haiku-4-5` (thinking) | ~35 † | — | not pinned — under the ~51 haiku target |
|
|
495
|
+
| `gpt-oss-120b` | ~10 † | — | **pinned nowhere** — below every target, haiku included |
|
|
496
|
+
|
|
497
|
+
† **Estimated, not measured.** Model absent from the 2026-06-25 release; value bridged from its 2026-01-08 score via the mean delta of the three nearest-scoring models present in both releases. Cross-release scores are not comparable directly (LiveBench rotates questions — overlapping models moved −1.4 to −31.5), so treat † as a bracket, not a number. **Unmeasured entirely** (no anchor in either release, do not infer): `composer-2.5`, `qwen3.5-397b`, `qwen3-coder`, `qwen3.7-plus`, `glm-4.5-air`, `gpt-oss-20b`, `qwen3-coder:30b`.
|
|
498
|
+
|
|
499
|
+
### Per-tier lineup across providers
|
|
500
|
+
|
|
501
|
+
Cells show pin · score · $/task. Deltas are against that column's target. Convergent (CoT lens for risk/diagnosis agents) rides the same board.
|
|
502
|
+
|
|
503
|
+
<!-- prettier-ignore -->
|
|
504
|
+
| Provider | opus — target 65.2 | sonnet — target 59.4 | haiku — target ~51 | convergent | Notes |
|
|
505
|
+
| --- | --- | --- | --- | --- | --- |
|
|
506
|
+
| `claude` | `claude-opus-5-5` 65.4 at `xhigh` | `claude-sonnet-5-5` (see board) | `claude-haiku-5-5` at `high` (51.4 at `xhigh`) | (opus) | Pins are 5.5 ($4/$20 opus, $2/$10 sonnet, $0.10/$0.50 haiku, 1M context). Opus and sonnet targets stay the 5.0 scores (`claude-opus-5` **65.2** · $5.34, `claude-sonnet-5` **59.4** · $2.14): Opus 5.5 lands level at `xhigh`, and Sonnet 5.5's LiveBench rows don't read cleanly. Haiku target = Haiku 5.5 at `xhigh`. |
|
|
507
|
+
| `openrouter` | `deepseek/deepseek-v4.1-flash` 77.3 · $0.06 (+12.1) | same (+17.9) | `z-ai/glm-5.3-flash` 56.8 · $0.11 (+5.4) | `moonshotai/kimi-k3` 62.2 · $1.76 | Aggregator; broad catalog to re-pin from. Opus+sonnet collapse on V4.1 Flash (clears 65.2). Haiku = GLM-5.3 Flash (cheapest sufficient). Convergent = Kimi K3 (distinct CoT). All three auto-cache. Never pin `anthropic/*` — column carries Claude-quota overflow. |
|
|
508
|
+
| `cursor` | `cursor-grok-4.5-high` 56.5 · $0.54 (−8.7) | `composer-2.5` **n/m** | `composer-2.5` **n/m** | (opus) | Ceiling is grok-4.5 — no Cursor model reaches the opus target, which is the correct outcome, not a gap. `composer-2.5` is the one unresolved cell in the matrix: vendor-claimed ≈ Opus 4.7 (which measures 50.7), never on LiveBench. Probe or override before relying on it for sonnet-tier work. Haiku stays `composer-2.5` too: the only measured first-party model over ~51 is `cursor-grok-4.5-high` (56.5), at about 8x the cost. |
|
|
509
|
+
| `ollama` (cloud) | `kimi-k2.7-code` 45.7 · $0.39 (−19.5) | `kimi-k2.7-code` (−13.7) | `deepseek-v4.1-flash` 77.3 · $0.06 (+25.9) | `deepseek-v4-pro` | **Whole column needs a paid Ollama plan.** **No model variants** — the ollama provider builds catalog entries with none, so bkit omits `variant:` on this column (2.0 would reject it); agents run at opencode's default reasoning. `deepseek-v4-pro` (convergent) has left the advertised catalog but still resolves. The free `qwen3.5:397b` / `gpt-oss:20b` are unmeasured or ~10 — free-tier users re-pin in `prompts.md` § Model Overrides and accept unverified quality. |
|
|
510
|
+
| `opencode-zen` | `opencode/deepseek-v4.1-flash` 77.3 · $0.06 (+12.1) | same (+17.9) | `opencode/glm-5.3-flash` 56.8 · $0.11 (+5.4) | `opencode/deepseek-v4-pro` | Opus+sonnet re-pinned from `kimi-k2.7-code` (45.7 · $0.39): 2.0 hard-errors on a `variant:` the model does not expose, and `kimi-k2.7-code` exposes none. V4.1 Flash clears 65.2 and carries variants; **Zen bills it at $0.30/$1.20** (higher than the LiveBench $/task shown). Haiku = GLM-5.3 Flash. Existence-validated via models.dev. |
|
|
511
|
+
| `opencode-go` | `opencode-go/deepseek-v4-pro` 42.6 · $0.14 (−22.6) | same (−16.8) | `opencode-go/deepseek-v4.1-flash` 77.3 · $0.06 (+25.9) | `opencode-go/deepseek-v4-pro` | Budget open-weight plan. `minimax-m3`/`qwen3.7-plus` not pinned (see the board). Prefer pins inside the Go 5h window. DeepSeek models need the workspace privacy setting on "Global regions". |
|
|
512
|
+
|
|
513
|
+
**n/m** = not measured on LiveBench (see the unmeasured list above) — the cell is a catalog/constraint choice, not a scored one.
|
|
514
|
+
|
|
515
|
+
**Hard-constraint escape hatch.** "Cheapest that reaches the target" is bounded by constraints that are not about quality: paid-plan gating (`ollama`), rate/quota/context walls when ~45 agents collapse onto one flagship. Deviate for those, and say so in the Notes cell — a constrained pin must never read as a tier judgement.
|
|
516
|
+
|
|
517
|
+
Cloud OpenAI-compatible cells tool-call-smoked (`tools:` round-trip `tool_calls`) — `/models` != proof (validate-with-real-tool). `opencode-zen` existence-validated via models.dev (Zen balance zero; smoke on Go endpoint). Re-pin: edit agent `model:`, add `prompts.md` § Model Overrides row, or change column + `bkit check`. Probe live catalog first (models.dev opencode; `/v1/models` table rest).
|
|
518
|
+
|
|
519
|
+
**Consumer model overrides (upgrade-safe):** `.bkit/prompts.md` marker-managed (`rules.md` pattern) — bkit refreshes `bkit:start`/`bkit:end` on upgrade; `## Model Overrides` below `bkit:end` consumer-owned. Pin different model per agent×host/provider:
|
|
520
|
+
|
|
521
|
+
```
|
|
522
|
+
| Prompt | Provider | Model |
|
|
523
|
+
| --- | --- | --- |
|
|
524
|
+
| bkit-build-summary | openrouter | openrouter/deepseek/deepseek-v4-pro |
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
`Provider` = host/install key (`cursor`, `openrouter`, `ollama`, …). Install merges overrides over defaults (override wins). Claude reads frontmatter; not overridable via table yet.
|
|
528
|
+
|
|
529
|
+
**Cursor API-credit restore:** when you have third-party / additional API credits and want Claude Opus on Cursor workflows, use the paste block in `prompts.md` § Model Overrides (Claude-opus-tier → `claude-opus-5-thinking-high`) — that is the only way to close the −8.7 opus gap on Cursor. Sonnet-tier agents stay on shipped Composer/Grok (correct under per-tier targeting, not a shortfall) unless you opt into `gpt-5.6-sol-high`. Orchestrators `/design` `/plan` `/debug` = session model (set at launch), not the override table.
|
|
530
|
+
|
|
531
|
+
---
|
|
532
|
+
|
|
533
|
+
## System-prompt / memory files
|
|
534
|
+
|
|
535
|
+
<!-- prettier-ignore -->
|
|
536
|
+
| Host | Reads automatically | Format |
|
|
537
|
+
| --- | --- | --- |
|
|
538
|
+
| Claude Code | `CLAUDE.md` (root + nearest ancestor) | Plain markdown |
|
|
539
|
+
| Cursor | `AGENTS.md` (root, AGENTS.md spec) + `.cursor/rules/*.mdc` (MDC: markdown + optional YAML frontmatter with `description`, `globs`, `alwaysApply`) | Plain markdown / MDC |
|
|
540
|
+
| Both (de-facto cross-host convention) | `AGENTS.md` increasingly read by all hosts incl. Claude Code, Codex, Cursor | Plain markdown |
|
|
541
|
+
|
|
542
|
+
**Current setup:** `CLAUDE.md` + `.cursor/rules/bkit-rules.mdc` redirect to `.agents/rules.md`. `AGENTS.md` = cross-host dispatch spine (workflow router: Linear-issue → label command dispatch), read by every host. **Host-scoped ownership:** `CLAUDE.md` ships `--claude` (Claude analog of `.cursor/rules/bkit-rules.mdc`, `--cursor`); `AGENTS.md` core (always). Each host brings redirect — no rule all three coexist. `--cursor`-only: no `CLAUDE.md`; `--claude`-only: no `.cursor/rules/`.
|
|
543
|
+
|
|
544
|
+
**Transform:** managed-block markers (`<!-- bkit:start -->` … `<!-- bkit:end -->`). Inside regenerated; outside preserved.
|
|
545
|
+
|
|
546
|
+
---
|
|
547
|
+
|
|
548
|
+
## Skills
|
|
549
|
+
|
|
550
|
+
<!-- prettier-ignore -->
|
|
551
|
+
| Host | Mechanism | Location |
|
|
552
|
+
| --- | --- | --- |
|
|
553
|
+
| Claude Code | First-class `Skill` tool. Registered via `.claude/settings.json` → `permissions.allow: ["Skill(*)"]`. Discoverable via plugin marketplace. | `~/.claude/skills/` (user) + `.agents/skills/` (project) + plugin skill dirs |
|
|
554
|
+
| Cursor | Cursor 2.4+ Agent Skills (similar shape). | `.cursor/skills/` (per docs); `.agents/skills/` referenced via custom routing |
|
|
555
|
+
|
|
556
|
+
`.agents/skills/` = **canonical project skill directory**. Both hosts read. No per-host transform. List in `.agents/skills.md`.
|
|
557
|
+
|
|
558
|
+
---
|
|
559
|
+
|
|
560
|
+
## Background / async execution
|
|
561
|
+
|
|
562
|
+
<!-- prettier-ignore -->
|
|
563
|
+
| Host | Mechanism |
|
|
564
|
+
| --- | --- |
|
|
565
|
+
| Claude Code | Synchronous `Agent` tool calls; parallel calls in single turn = parallel execution within main agent. No first-class async/background concept. |
|
|
566
|
+
| Cursor | `is_background: true` on subagent → spawns Cursor Cloud Agent that runs detached; main agent continues. Async by design. |
|
|
567
|
+
| opencode | Concurrent `Task` dispatch (spike-proven: 3 distinct subagents run concurrently, wall-clock < serial sum). Real parallelism only when the backend serves requests concurrently — true for every provider (openrouter, ollama, opencode-zen, opencode-go). The workflow text is unchanged — concurrency is bounded at the Ollama server, not in the command files. |
|
|
568
|
+
|
|
569
|
+
**Implication:** parallel fan-outs (triplets `bkit-design-brainstorm-ideate-1`/`-2`/`-3`, `bkit-plan-review-1`/`-2`/`-3`; pairs `bkit-design-review-*`, `bkit-plan-scope-check-*`, `bkit-build-challenge-*`, `bkit-ship-update-docs`/`-summary`) — Claude: concurrent `Agent` in one turn; Cursor: opt-in `is_background: true` (default off; host config can flip at install); opencode: concurrent `Task` — real on every provider.
|
|
570
|
+
|
|
571
|
+
---
|
|
572
|
+
|
|
573
|
+
## Tool name parity
|
|
574
|
+
|
|
575
|
+
Claude spelling in subagent `tools:` and command bodies (`Bash`, `Edit`, `Read`, etc.). Cursor uses different identifiers (`terminal`, `edit_file`, `read_file`, `apply_diff`). Claude names → Cursor `tools:` allowlist (alias vs strict) unverified. Mapping in `bkit/hosts/cursor.ts`.
|
|
576
|
+
|
|
577
|
+
---
|
|
578
|
+
|
|
579
|
+
## How to add a new host
|
|
580
|
+
|
|
581
|
+
1. Add row to § Supported hosts above.
|
|
582
|
+
2. Document deltas per concern (subagent invocation, frontmatter, hooks, permissions, runtime, etc.).
|
|
583
|
+
3. Implement transforms in `bkit/hosts/<name>.ts`. Each delta = one transform rule.
|
|
584
|
+
4. Drop static templates in `bkit/templates/<name>/` (settings, hooks, runtime).
|
|
585
|
+
5. Regression test: fresh-repo install; verify 5 phase commands + 7 worktree utilities E2E.
|
|
586
|
+
6. Update `AGENTS.md` routing table with new host command paths.
|
|
587
|
+
|
|
588
|
+
---
|
|
589
|
+
|
|
590
|
+
## Verify against current Cursor surface
|
|
591
|
+
|
|
592
|
+
Cursor API/frontmatter churn — confirm before dependent changes:
|
|
593
|
+
|
|
594
|
+
- Cursor model IDs in § Cursor model catalog still exist, not superseded.
|
|
595
|
+
- Cursor `readonly: true` semantics — file writes only, or bash/terminal too.
|
|
596
|
+
- Cursor tool-name parity (`Bash` vs `terminal`, `Edit` vs `edit_file`, etc.).
|
|
597
|
+
- Cursor `Task` resolution: `/<name>` → `.cursor/agents/<name>.md` (mirrors Claude `Agent` `@<name>` → `.claude/agents/<name>.md`).
|
|
598
|
+
- `AGENTS.md` adoption — when all hosts read natively, redirects (`CLAUDE.md`, `.cursor/rules/bkit-rules.mdc`) can shrink.
|