@cbartens/bkit 5.5.1 → 6.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +167 -154
- package/.bkit/core/.agents/context.md +95 -29
- package/.bkit/core/.agents/docs.md +18 -15
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
- package/.bkit/core/.agents/rules.md +112 -102
- package/.bkit/core/.agents/skills.md +63 -15
- package/.bkit/core/.bkit/README.md +167 -154
- package/.bkit/core/.bkit/authoring.md +747 -0
- package/.bkit/core/.bkit/cli.md +407 -0
- package/.bkit/core/.bkit/cloud.md +283 -195
- package/.bkit/core/.bkit/comparison.md +45 -43
- package/.bkit/core/.bkit/install.md +166 -95
- package/.bkit/core/.bkit/jsonl.md +339 -196
- package/.bkit/core/.bkit/pipeline.md +142 -145
- package/.bkit/core/.bkit/prompts.md +295 -264
- package/.bkit/core/.bkit/providers.md +460 -277
- package/.bkit/core/.bkit/router.md +69 -0
- package/.bkit/core/.bkit/templates.md +530 -256
- package/.bkit/core/.bkit/trackers.md +116 -65
- package/.bkit/core/.bkit/workflows.md +742 -618
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
- package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
- package/.bkit/core/AGENTS.md +6 -80
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
- package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
- package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
- package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
- package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
- package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
- package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
- package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
- package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
- package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
- package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
- package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
- package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
- package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
- package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
- package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
- package/.bkit/core/docs/templates/bkit-plan.md +158 -281
- package/.bkit/core/engine/checks/after/auth.ts +40 -37
- package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
- package/.bkit/core/engine/checks/after/github.ts +95 -17
- package/.bkit/core/engine/checks/after/index.ts +21 -8
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +125 -123
- package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
- package/.bkit/core/engine/checks/before/env.ts +3 -3
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +25 -1
- package/.bkit/core/engine/checks/before/repo.ts +208 -2
- package/.bkit/core/engine/checks/status-holes.ts +916 -123
- package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
- package/.bkit/core/engine/checks/tips/detect.ts +66 -0
- package/.bkit/core/engine/checks/tips/index.ts +52 -11
- package/.bkit/core/engine/cli.ts +251 -130
- package/.bkit/core/engine/commands/analysis.ts +282 -199
- package/.bkit/core/engine/commands/ci/ci.ts +363 -29
- package/.bkit/core/engine/commands/ci/pins.ts +172 -0
- package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
- package/.bkit/core/engine/commands/comply.ts +77 -103
- package/.bkit/core/engine/commands/install/doctor.ts +2 -2
- package/.bkit/core/engine/commands/install/install.ts +57 -18
- package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
- package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
- package/.bkit/core/engine/commands/land.ts +139 -18
- package/.bkit/core/engine/commands/lib.ts +381 -22
- package/.bkit/core/engine/commands/registry.ts +10 -2
- package/.bkit/core/engine/commands/setup/setup.ts +8 -7
- package/.bkit/core/engine/commands/stats.ts +260 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
- package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
- package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
- package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
- package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
- package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
- package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
- package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
- package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
- package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
- package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
- package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
- package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
- package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
- package/.bkit/core/engine/commands/workflow/status.ts +329 -33
- package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
- package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
- package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
- package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
- package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
- package/.bkit/core/engine/install/cloud-env.ts +251 -121
- package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
- package/.bkit/core/engine/install/manifest.ts +67 -17
- package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
- package/.bkit/core/engine/install/modules/cloud.ts +24 -16
- package/.bkit/core/engine/install/modules/codex.ts +15 -2
- package/.bkit/core/engine/install/modules/core.ts +1196 -45
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +18 -6
- package/.bkit/core/engine/install/template-notes.ts +130 -0
- package/.bkit/core/engine/install/version-file.ts +9 -4
- package/.bkit/core/engine/install/write.ts +5 -0
- package/.bkit/core/engine/ledgers/compact.ts +124 -0
- package/.bkit/core/engine/ledgers/journal.ts +291 -0
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +249 -21
- package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
- package/.bkit/core/engine/render/hosts.ts +118 -14
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/dep-updater.ts +60 -0
- package/.bkit/core/engine/shared/egress.ts +8 -1
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/package-manager.ts +9 -0
- package/.bkit/core/engine/shared/settings.ts +243 -31
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/shared/timeouts.ts +2 -0
- package/.bkit/core/engine/tools/cli-doc.ts +111 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
- package/.bkit/core/engine/tools/instructions.ts +1802 -0
- package/.bkit/core/hooks/antigravity-hook.js +25 -10
- package/.bkit/core/hooks/gateguard-engine.js +54 -29
- package/.bkit/core/hooks/guardrails-shell.js +4 -5
- package/.bkit/core/hooks/guardrails-tiers.js +10 -4
- package/.bkit/core/hooks/preflight-linear.sh +9 -9
- package/.bkit/core/hooks/preflight-rules.sh +8 -0
- package/.bkit/core/hooks/readguard-engine.js +29 -10
- package/.bkit/core/hooks/session-rules-advisory.js +61 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
- package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
- package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
- package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
- package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
- package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
- package/.bkit/core/prompts/bkit-design-generate.md +80 -46
- package/.bkit/core/prompts/bkit-design-organise.md +83 -32
- package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
- package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
- package/.bkit/core/prompts/bkit-design-spike.md +64 -40
- package/.bkit/core/prompts/bkit-design-update.md +53 -28
- package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
- package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
- package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
- package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
- package/.bkit/core/prompts/bkit-plan-update.md +86 -31
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
- package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
- package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
- package/.bkit/core/workflows/bkit-auto.md +89 -58
- package/.bkit/core/workflows/bkit-build.md +967 -517
- package/.bkit/core/workflows/bkit-debug.md +555 -387
- package/.bkit/core/workflows/bkit-design.md +319 -283
- package/.bkit/core/workflows/bkit-plan.md +319 -342
- package/.bkit/core/workflows/bkit-ship.md +525 -328
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/bkit-cloud.md +12 -10
- package/.bkit/shared/.claude/settings.json +14 -0
- package/.bkit/shared/.codex/bkit-cloud.md +98 -0
- package/.bkit/shared/.codex/hooks.json +20 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
- package/.bkit/shared/.cursor/mcp.json +1 -1
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
- package/.bkit/shared/.gitattributes +1 -1
- package/.bkit/shared/.mcp.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +12 -1
- package/.bkit/shared/CLAUDE.md +6 -2
- package/.bkit/shared/GEMINI.md +5 -2
- package/.bkit/shared/docs/architecture.md +4 -7
- package/.bkit/shared/docs/data-schema.md +4 -7
- package/.bkit/shared/docs/deployments.md +241 -168
- package/.bkit/shared/docs/design.md +11 -12
- package/.bkit/shared/docs/noise.md +8 -7
- package/.bkit/shared/docs/observability.md +5 -8
- package/.bkit/shared/docs/security.md +35 -17
- package/.bkit/shared/docs/setup.md +29 -18
- package/.bkit/shared/docs/technology.md +3 -6
- package/.bkit/shared/docs/testing.md +289 -174
- package/.bkit/shared/gitignore +6 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
- package/.bkit/templates/.cursor/Dockerfile +12 -8
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
- package/.bkit/templates/.github/renovate.json5 +34 -6
- package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
- package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
- package/.bkit/templates/.husky/pre-commit +2 -2
- package/.bkit/templates/.husky/pre-push +96 -36
- package/.bkit/templates/.prettierignore +6 -0
- package/.bkit/templates/.vale.ini +27 -27
- package/.bkit/templates/context/bkit-cloudrun.md +23 -15
- package/.bkit/templates/context/bkit-expo.md +70 -52
- package/.bkit/templates/context/bkit-github.md +93 -56
- package/.bkit/templates/context/bkit-inngest.md +21 -15
- package/.bkit/templates/context/bkit-maestro.md +22 -16
- package/.bkit/templates/context/bkit-playwright.md +23 -17
- package/.bkit/templates/context/bkit-resend.md +12 -10
- package/.bkit/templates/context/bkit-sentry.md +30 -20
- package/.bkit/templates/context/bkit-serena.md +8 -7
- package/.bkit/templates/context/bkit-stripe.md +14 -13
- package/.bkit/templates/context/bkit-supabase.md +16 -13
- package/.bkit/templates/context/bkit-tavily.md +14 -11
- package/.bkit/templates/context/bkit-vercel.md +27 -18
- package/.bkit/templates/docs/capabilities.md +15 -14
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
- package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
- package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
- package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
- package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
- package/.bkit/templates/slop-scan.config.json +9 -2
- package/CHANGELOG.md +231 -0
- package/README.md +278 -89
- package/dist/checks/after/auth.js +36 -33
- package/dist/checks/after/ci-yml.js +91 -30
- package/dist/checks/after/github.js +91 -17
- package/dist/checks/after/index.js +22 -11
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +111 -114
- package/dist/checks/before/context-fetch.js +218 -33
- package/dist/checks/before/env.js +3 -3
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +20 -3
- package/dist/checks/before/repo.js +197 -2
- package/dist/checks/status-holes.js +739 -114
- package/dist/checks/tips/catalogue.js +70 -19
- package/dist/checks/tips/detect.js +62 -0
- package/dist/checks/tips/index.js +51 -9
- package/dist/cli.js +234 -124
- package/dist/commands/analysis.js +174 -141
- package/dist/commands/ci/ci.js +302 -25
- package/dist/commands/ci/pins.js +142 -0
- package/dist/commands/ci/push-gate.js +194 -0
- package/dist/commands/comply.js +54 -91
- package/dist/commands/install/doctor.js +2 -2
- package/dist/commands/install/install.js +50 -19
- package/dist/commands/install/uninstall.js +82 -55
- package/dist/commands/install/upgrade.js +21 -11
- package/dist/commands/land.js +137 -17
- package/dist/commands/lib.js +295 -21
- package/dist/commands/registry.js +10 -2
- package/dist/commands/setup/setup.js +8 -7
- package/dist/commands/stats.js +175 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +1873 -152
- package/dist/commands/workflow/challenge.js +609 -0
- package/dist/commands/workflow/completeness.js +97 -0
- package/dist/commands/workflow/context.js +1045 -46
- package/dist/commands/workflow/counters.js +385 -86
- package/dist/commands/workflow/decisions.js +484 -0
- package/dist/commands/workflow/disk.js +214 -56
- package/dist/commands/workflow/fids.js +706 -33
- package/dist/commands/workflow/issues.js +349 -59
- package/dist/commands/workflow/ledgers.js +1123 -37
- package/dist/commands/workflow/locks.js +26 -2
- package/dist/commands/workflow/plan-blocks.js +501 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/plans.js +205 -0
- package/dist/commands/workflow/prs.js +154 -35
- package/dist/commands/workflow/repo.js +58 -8
- package/dist/commands/workflow/roadmap.js +58 -23
- package/dist/commands/workflow/run-facts.js +421 -0
- package/dist/commands/workflow/runs.js +670 -72
- package/dist/commands/workflow/runtime.js +15 -1
- package/dist/commands/workflow/skills.js +1 -0
- package/dist/commands/workflow/status.js +282 -34
- package/dist/commands/workflow/step-table.js +308 -0
- package/dist/commands/workflow/steps.js +703 -96
- package/dist/commands/workflow/summary-findings.js +117 -0
- package/dist/commands/workflow/summary.js +388 -0
- package/dist/commands/workflow/tasks.js +378 -0
- package/dist/commands/workflow/test-blocks.js +231 -0
- package/dist/commands/workflow/tests-changed.js +172 -0
- package/dist/commands/workflow/tests.js +1695 -305
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +1014 -222
- package/dist/commands/workflow/worktrees.js +432 -26
- package/dist/install/cloud-env.js +233 -99
- package/dist/install/context-ci-workflow.js +85 -0
- package/dist/install/manifest.js +64 -17
- package/dist/install/modules/antigravity.js +3 -2
- package/dist/install/modules/cloud.js +25 -16
- package/dist/install/modules/codex.js +12 -2
- package/dist/install/modules/core.js +1090 -48
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +13 -7
- package/dist/install/template-notes.js +116 -0
- package/dist/install/version-file.js +9 -4
- package/dist/ledgers/compact.js +87 -0
- package/dist/ledgers/journal.js +233 -0
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +176 -13
- package/dist/ledgers/telemetry.js +1010 -125
- package/dist/render/hosts.js +104 -14
- package/dist/render/models.js +12 -0
- package/dist/shared/bkit-latest.js +26 -4
- package/dist/shared/branches.js +3 -1
- package/dist/shared/dep-updater.js +49 -0
- package/dist/shared/egress.js +8 -1
- package/dist/shared/json.js +20 -7
- package/dist/shared/package-manager.js +6 -0
- package/dist/shared/settings.js +181 -24
- package/dist/shared/text.js +333 -0
- package/dist/shared/timeouts.js +2 -0
- package/dist/tools/cli-doc.js +97 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +720 -0
- package/dist/tools/instructions.js +1623 -0
- package/package.json +156 -51
- package/.bkit/core/.bkit/lite.md +0 -73
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
- package/.bkit/core/engine/tools/wording.ts +0 -748
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
- package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
- package/.bkit/core/prompts/bkit-build-summary.md +0 -94
- package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
- package/.bkit/core/prompts/bkit-design-summary.md +0 -107
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
- package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
- package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
- package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
- package/dist/commands/harvest.js +0 -353
- package/dist/commands/workflow/workstreams.js +0 -143
- package/dist/tools/wording.js +0 -680
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
- /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
- /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
|
@@ -1,73 +1,75 @@
|
|
|
1
|
-
# Cloud agent environments — Claude
|
|
1
|
+
# Cloud agent environments — Claude on the web + Codex Cloud + Cursor Cloud Agents + OpenCode
|
|
2
2
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
5
|
> [!CAUTION]
|
|
6
|
-
> **Purpose:**
|
|
6
|
+
> **Purpose:** The canonical reference for Claude on the web (mobile / web), Codex Cloud, Cursor Cloud Agents and OpenCode cloud runners. Environments do not depend on the tracker: every generated `<host>/bkit-cloud.md` carries the same env block (`BKIT_GH_TOKEN` plus whatever `.envrc` resolves, tracker keys included) for any tracker. Dispatch pairs each agent with one tracker: Claude and OpenCode with GitHub (one unified `bkit-cloud.yml`), and Cursor with Linear. Jira and Codex Cloud have no bkit dispatch, so you launch those runs by hand (§ Cloud-agent support matrix).
|
|
7
7
|
>
|
|
8
8
|
> **Rules:**
|
|
9
9
|
>
|
|
10
|
-
> -
|
|
11
|
-
> -
|
|
12
|
-
> -
|
|
13
|
-
> - Claude
|
|
14
|
-
> - Update when
|
|
10
|
+
> - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
|
|
11
|
+
> - This file ships to every project that installs bkit. Describe the current setup only.
|
|
12
|
+
> - Leave out internal labels, such as tracker issue numbers, ledger keys and review-finding ids, and leave out project history. Decisions go in `docs/decisions.jsonl`, and incidents go in `docs/knowledge.jsonl`.
|
|
13
|
+
> - Claude's environment config lives in the Claude app, and Cursor's lives in `.cursor/` in the repo. Both have an in-repo SessionStart guard.
|
|
14
|
+
> - Update this file when any of the three clouds' pre-installed toolchain or default allowlist changes. The sources are `code.claude.com/docs/en/claude-code-on-the-web`, `cursor.com/docs/cloud-agent/setup` and `learn.chatgpt.com/docs/environments/cloud-environments`.
|
|
15
15
|
|
|
16
16
|
## Scope
|
|
17
17
|
|
|
18
|
-
> **Host-delta matrix:** `.bkit/providers.md` § Runtime environment (cloud agents)
|
|
18
|
+
> **Host-delta matrix:** `.bkit/providers.md` § Runtime environment (cloud agents) is the canonical home for what differs between Claude and Cursor cloud agents. This file holds the paste-in setup recipe, the alignment guarantees, the pattern for sharing across repos, and the caveats.
|
|
19
19
|
|
|
20
20
|
## Cloud-agent support matrix (read first)
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Dispatch pairs each agent with one tracker, while the environments (`<host>/bkit-cloud.md`) work with any tracker. Pick the row for the agent you run:
|
|
23
23
|
|
|
24
24
|
<!-- prettier-ignore -->
|
|
25
25
|
| Agent (the agent, not the editor) | Ways to launch a cloud agent | Tracker | not supported |
|
|
26
26
|
| --- | --- | --- | --- |
|
|
27
|
-
| **Claude
|
|
28
|
-
| **
|
|
29
|
-
| **Cursor** (native agent) | **A)** Cursor's built-in cloud-agent launch · **B)** Cursor's GitHub integration on PR events (CI pass/fail) · **C)** Linear → Cursor integration |
|
|
27
|
+
| **Claude** (terminal — any IDE host) | **A)** Claude iOS / desktop app → Claude-on-web env (`.claude/hooks/bkit-cloud-bootstrap.sh` + the env defined in `claude.ai/code`) · **B)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **C)** GitHub CI pass / fail → `bkit-cloud.yml` claude job · **D)** `@claude` mention on a GitHub issue / PR (needs `/install-github-app`, the base requirement for `cloud=claude`) | GitHub | Linear |
|
|
28
|
+
| **Codex** (Codex Cloud) | **A)** ChatGPT Codex → task on the env from `.codex/bkit-cloud.md` (manual; no bkit dispatch) | any (tracker MCP + env block) | bkit-triggered runs |
|
|
29
|
+
| **Cursor** (native agent) | **A)** Cursor's built-in cloud-agent launch · **B)** Cursor's GitHub integration on PR events (CI pass / fail) · **C)** Linear → Cursor integration | Linear (+ GitHub PR events) | GitHub Projects / Issues |
|
|
30
|
+
| **OpenCode** (GitHub runner) | **A)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **B)** GitHub CI pass / fail → `bkit-cloud.yml` OpenCode job (requires `OPENCODE_PROVIDER_KEY` secret) · **C)** reactive `/oc` comment handler (self-installed, not bkit's: § Reactive comment handlers) | GitHub | Linear |
|
|
30
31
|
|
|
31
|
-
**Unified file — additive coexistence:** Claude
|
|
32
|
+
**Unified file — additive coexistence:** Claude and OpenCode share one `bkit-cloud.yml`. A `context` job resolves the phase once, and two runner jobs follow, each gated at run time on its own credential: the claude job on the `ANTHROPIC_API_KEY` secret or the federation variables, and the OpenCode job on `OPENCODE_PROVIDER_KEY`. Both jobs can fire on the same CI event. With both credentials set, both agents run, and with one set, only that agent runs. Cursor is separate: it has no GitHub Action and uses its native triggers. Cursor cloud pairs with Linear.
|
|
32
33
|
|
|
33
|
-
**Manual dispatch (Claude or
|
|
34
|
+
**Manual dispatch (Claude or OpenCode, path A):** GitHub → **Actions** → **bkit-cloud** → **Run workflow**, then pick `phase` (`ship` / `debug` / `design` / `plan` / `build`) and `issue`. Use it on demand, or as a smoke test, for `design` / `plan` / `build`. `ship` / `debug` normally fire from CI. A dispatched `design` runs headless (`runtimeHeadless` = true on a GitHub runner): Grill asks nothing, records each recommended answer as `Assumed, not confirmed`, and records the draft acceptance scenario as not reviewed by a human. A dispatched `/bkit-auto` orchestrator hands off to the matching phase skill, which takes its brief from the GitHub issue through the MCP.
|
|
34
35
|
|
|
35
36
|
### Reactive comment handlers (`claude.yml` + `opencode.yml`) — separately managed, not bkit
|
|
36
37
|
|
|
37
|
-
`.github/workflows/claude.yml` (the `@claude` handler) and `.github/workflows/opencode.yml` (the `/oc` handler) are
|
|
38
|
+
`.github/workflows/claude.yml` (the `@claude` handler) and `.github/workflows/opencode.yml` (the `/oc` handler) are not bkit's. Each is generated, and regenerated, by its own vendor tool. bkit ships no template for either, and `bkit install` / `upgrade` never writes, rewrites or drift-gates them: neither is in the bkit manifest. They coexist additively with `bkit-cloud.yml`, the CI-completion and `workflow_dispatch` lane, which bkit ships as a template. A comment fires the vendor handler, and a CI run fires `bkit-cloud.yml`.
|
|
38
39
|
|
|
39
40
|
<!-- prettier-ignore -->
|
|
40
41
|
| Reactive handler (not bkit) | Installed by (vendor tool) | Auth | Launch a bkit phase |
|
|
41
42
|
| --- | --- | --- | --- |
|
|
42
|
-
| `.github/workflows/claude.yml` | `/install-github-app` (Claude
|
|
43
|
-
| `.github/workflows/opencode.yml` | `opencode github install` (
|
|
43
|
+
| `.github/workflows/claude.yml` | `/install-github-app` (Claude CLI → official Claude GitHub App) | OIDC as the App (`bkit-cloud.yml` grants `id-token: write`; no App installed → OIDC error at boot) | comment `@claude /bkit-plan` (or any phase) on an issue / PR |
|
|
44
|
+
| `.github/workflows/opencode.yml` | `opencode github install` (OpenCode CLI) | your provider key (`BKIT_OPENCODE_API_KEY` / `BKIT_OPENROUTER_API_KEY` / etc.) — no App, no OIDC | comment `/oc` or `/opencode` on an issue / PR |
|
|
44
45
|
|
|
45
|
-
|
|
46
|
+
You maintain these files, not bkit. `opencode.yml` hardcodes a `model:` and a provider-secret `env:`. Keep both in sync with your installed OpenCode provider. `bkit check` and postinstall raise a non-fatal advisory when they drift. Fix the file by hand, because bkit will not rewrite it. `claude.yml` has no equivalent check, because its `@claude` handler is fixed to Claude as its provider. For Claude, the `@claude` path is the base requirement for `cloud=claude`. Enable it with `bkit install --auto=claude`, which works with the GitHub tracker only. The App also gives the runner a GitHub identity for the `mcp__github__*` surface.
|
|
46
47
|
|
|
47
48
|
## What lives where (orient first)
|
|
48
49
|
|
|
49
50
|
<!-- prettier-ignore -->
|
|
50
51
|
| Configuration | Lives in the repo (bkit-managed) | Lives in the online dashboard (manual, one-time) |
|
|
51
52
|
| --- | --- | --- |
|
|
52
|
-
| **Claude
|
|
53
|
-
| **
|
|
53
|
+
| **Claude on the web** | `.claude/hooks/bkit-preflight.sh` (tracker opt-in guard) + `.claude/hooks/bkit-cloud-bootstrap.sh` (per-session install — copy-and-own template, adopt it from `.bkit/templates/`) | `claude.ai/code` → environment selector → **+ Add environment**: name, **setup script** (paste from § Setup script), **environment variables** (paste block from `.claude/bkit-cloud.md`), **network access** (`Custom`, list from the same doc) |
|
|
54
|
+
| **Codex Cloud** | `.codex/hooks.json` + `.codex/hooks/*` (unproven in cloud tasks — § Codex Cloud) + `.agents/skills/bkit-*` | ChatGPT → **Settings > Codex Cloud > Environments** → **Create environment**: repo, **Install script**, **Environment variables**, **Internet access** — all pasted from `.codex/bkit-cloud.md` |
|
|
55
|
+
| **Cursor Cloud Agents** | `.cursor/Dockerfile` + `.cursor/environment.json` (`install` / `start` / `terminals[]` / `env`), both copied from bkit's templates and owned by the repo, + `.cursor/hooks.json` (wires preflight `failClosed: true`) + `.cursor/hooks/bkit-preflight.sh` (Linear guard) | Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab, as **Runtime Secret**s: paste block from `.cursor/bkit-cloud.md`. (The integration injects `LINEAR_ISSUE_ID` / `GITHUB_ISSUE_ID` per session, so don't hardcode them.) |
|
|
54
56
|
|
|
55
|
-
**Rule of thumb:** env vars
|
|
57
|
+
**Rule of thumb:** env vars and auth tokens go in the online dashboard, out of git. Scripts, the Dockerfile and install hooks go in the repo.
|
|
56
58
|
|
|
57
59
|
**Alignment guarantees bkit enforces:**
|
|
58
60
|
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
- pnpm
|
|
62
|
-
- gh CLI
|
|
63
|
-
-
|
|
61
|
+
- Both clouds run the same Node (24.21.0, sha256-checked, from nodejs.org): the web setup script and `.cursor/Dockerfile` carry the identical `NODE_VERSION` + `NODE_SHA256` pair.
|
|
62
|
+
- Both clouds have the same vale version (3.9.1) pre-installed.
|
|
63
|
+
- Both get pnpm through corepack. The web setup script pre-warms the pnpm version in your `package.json` `packageManager`, and `.cursor/Dockerfile` pre-warms its `PNPM_VERSION` build argument. Inside the repo, corepack resolves the repo's own `packageManager` either way, so one setup script serves any pnpm pin, and the pre-warmed version only warms the cache.
|
|
64
|
+
- Both have the gh CLI. The web setup script installs a pinned, sha256-checked binary (`GH_VERSION`, downloaded from a `github.com` release the same way as vale), and the GitHub-Actions runner ships with it pre-installed. Auth is shared through `bkit-cloud-bootstrap.sh`, which runs `gh auth login --with-token` with `BKIT_GH_TOKEN` and skips it when `GITHUB_TOKEN` already authenticates on the runner.
|
|
65
|
+
- Both use the same opt-in guard pattern, keyed on the opt-in label `bkit:auto` and wrapped in `<!-- bkit:start --> ... <!-- bkit:end -->` (bkit-managed in consumer repos). The label is `bkit:auto` on both trackers.
|
|
64
66
|
|
|
65
67
|
## Background
|
|
66
68
|
|
|
67
|
-
Both clouds run Ubuntu 24.04 (4 vCPU / 16 GB RAM / 30 GB disk class).
|
|
69
|
+
Both clouds run Ubuntu 24.04 (4 vCPU / 16 GB RAM / 30 GB disk class). What comes pre-installed differs:
|
|
68
70
|
|
|
69
71
|
<!-- prettier-ignore -->
|
|
70
|
-
| Pre-installed | Claude
|
|
72
|
+
| Pre-installed | Claude on the web | Cursor Cloud Agents (after bkit Dockerfile) |
|
|
71
73
|
| --- | --- | --- |
|
|
72
74
|
| Node | 20 + 22 — setup script adds 24 (checksum-pinned, into `/usr/local`, first on `PATH`) | 24 (template default, checksum-pinned; match your `engines.node` / `.nvmrc`) |
|
|
73
75
|
| Package manager | pnpm + bun (latest) | pnpm (corepack-pinned in `.cursor/Dockerfile`; each repo's `packageManager` honored in-repo) |
|
|
@@ -75,90 +77,109 @@ Both clouds run Ubuntu 24.04 (4 vCPU / 16 GB RAM / 30 GB disk class). Pre-instal
|
|
|
75
77
|
| Databases | Postgres 16, Redis 7 | Not installed (add to Dockerfile if needed) |
|
|
76
78
|
| Docker | Yes (host engine) | N/A — we are inside Docker |
|
|
77
79
|
| Utilities | git, jq, ripgrep | git, jq |
|
|
78
|
-
| `gh` CLI |
|
|
79
|
-
| `vale` |
|
|
80
|
+
| `gh` CLI | Not pre-installed: the setup script adds it | Added via Dockerfile (pinned release tarball, sha256-checked) |
|
|
81
|
+
| `vale` | Not pre-installed: the setup script adds 3.9.1 | Added via Dockerfile (3.9.1) |
|
|
80
82
|
| Playwright | Not pre-installed | Not installed (commented example in the consumer section of `.cursor/Dockerfile`) |
|
|
81
83
|
|
|
82
|
-
|
|
84
|
+
Customisation comes in two halves:
|
|
83
85
|
|
|
84
|
-
- **Cloud-side install** (one-time, cached): Claude
|
|
85
|
-
- **Repo-side install** (per-session, lockfile-aware): Claude
|
|
86
|
+
- **Cloud-side install** (one-time, cached): Claude uses the setup script in the app, and Cursor uses `.cursor/Dockerfile`.
|
|
87
|
+
- **Repo-side install** (per-session, lockfile-aware): Claude uses `.claude/hooks/bkit-cloud-bootstrap.sh`, and Cursor uses the `install` field of `.cursor/environment.json`.
|
|
86
88
|
|
|
87
|
-
|
|
89
|
+
**Failed provision recipes:** Every host runs each `context-fetch:provision` recipe on its own. The Claude setup script and the Codex install script run them inline, and the Claude session hook and the Cursor `install` run them through `bkit context provision`. A failing recipe never fails setup. Setup names it, with its last error line, in the setup log and in the closing `cloud setup done` line, and lists it in `.bkit/.unavailable`, one `<name>: <reason>` line per recipe. The file is removed when no recipe fails. The Claude session hook prints that file into the session's context, and `.agents/rules.md` § Cloud setup gaps tells every agent to read it.
|
|
90
|
+
|
|
91
|
+
# Claude on the web
|
|
88
92
|
|
|
89
93
|
> [!TIP]
|
|
90
|
-
> **No manual copy needed.** `bkit install --claude` writes `.claude/bkit-cloud.md
|
|
94
|
+
> **No manual copy needed.** `bkit install --claude` writes `.claude/bkit-cloud.md`: this recipe, with the repo's env-var values resolved from `.envrc`. Variables that file `unset`s are dropped, and `BKIT_ANTHROPIC_API_KEY` is left out to protect subscription billing. Open the file and paste each block into the Claude app. The file is gitignored because it holds real secrets, and it regenerates on every install and upgrade. The reference below documents each field it fills.
|
|
91
95
|
|
|
92
96
|
## Where config lives
|
|
93
97
|
|
|
94
|
-
Open `claude.ai/code` → environment selector → **+ Add environment**.
|
|
98
|
+
Open `claude.ai/code` → environment selector → **+ Add environment**. It has three surfaces: the setup script (bash, run as root, once, then snapshotted), environment variables (`.env` format, plaintext, visible to anyone with edit access) and network access (`None` / `Trusted` / `Full` / `Custom`).
|
|
95
99
|
|
|
96
100
|
## In-repo side
|
|
97
101
|
|
|
98
|
-
- `.claude/hooks/bkit-preflight.sh` —
|
|
99
|
-
- `.claude/hooks/bkit-cloud-bootstrap.sh` — runs `pnpm install --frozen-lockfile`
|
|
100
|
-
- Both registered in `.claude/settings.json` under `hooks.SessionStart`.
|
|
102
|
+
- `.claude/hooks/bkit-preflight.sh` — the tracker opt-in guard plus the rules-read advisory, as one JSON document (`.bkit/providers.md` § Rules-read advisory). When the tracker issue ID env var is unset, as in an IDE session, it prints the advisory alone and exits 0. On Claude a non-zero exit is informational only, because `SessionStart` cannot block. The agent reads the `HARD STOP` text from `additionalContext`.
|
|
103
|
+
- `.claude/hooks/bkit-cloud-bootstrap.sh` — when `CLAUDE_CODE_REMOTE=true`, runs `pnpm install --frozen-lockfile` and `vale sync`, then gh auth, then context-fetch CLI provisioning through the just-installed bkit (`bkit context provision`). When bkit is missing, it skips provisioning with a loud log line. A failed recipe's `.bkit/.unavailable` line goes to stdout, and so into the session's context. Locally the hook does nothing.
|
|
104
|
+
- Both are registered in `.claude/settings.json` under `hooks.SessionStart`.
|
|
101
105
|
|
|
102
|
-
|
|
106
|
+
These ship with the repo. Do not paste them into the app.
|
|
103
107
|
|
|
104
108
|
## What to paste into the Claude app
|
|
105
109
|
|
|
106
110
|
### Name
|
|
107
111
|
|
|
108
|
-
Name environment
|
|
112
|
+
Name the environment after the repo: one environment per repo keeps secrets isolated (§ Sharing across repos). The setup script is identical across repos.
|
|
109
113
|
|
|
110
|
-
|
|
114
|
+
The setup-script body, the network policy and bkit's baseline token name (`BKIT_GH_TOKEN`) are identical across repos, and only the values change. The rest of the env-vars box is this repo's own, copied from the env-var files that `.envrc` follows (§ Tokens by session type).
|
|
111
115
|
|
|
112
116
|
### Network access
|
|
113
117
|
|
|
114
|
-
Always `Custom
|
|
118
|
+
Always choose `Custom`, because the rendered list carries bkit's own shipped hosts (trackers, registries, agent and provider APIs, and the search host a `context=web` block calls) whether or not the repo declares anything:
|
|
119
|
+
|
|
120
|
+
1. Select **Custom**.
|
|
121
|
+
2. Tick **Also include default list of common package managers**. It extends the trusted defaults (package registries, GitHub, cloud SDKs) and never replaces them.
|
|
122
|
+
3. Paste the domains bkit renders into `.claude/bkit-cloud.md` § Network access into **Allowed domains**.
|
|
123
|
+
|
|
124
|
+
Declare only what bkit cannot see: the log-backend and API hosts that the implicit CLI blocks reach (`vercel` / `gcloud`), plus the app's production and preview / dev domains. Declare apex domains only. `bkit install` expands each one to `<domain>` + `*.<domain>` and unions them with the derived set. Under `Trusted` those hosts are unreachable, so a cloud `/bkit-debug` gets no runtime logs and e2e tests can't reach the deployment.
|
|
115
125
|
|
|
116
|
-
|
|
126
|
+
A repo with no `allowed-domains` block still needs `Custom`, because `Trusted` does not reach bkit's own tracker MCP, provider catalog or search hosts. Ticking **Also include default list of common package managers** keeps npm, the vale tarball on `objects.githubusercontent.com`, Docker Hub and PyPI. Raise the setting to `Full` only for open-internet tasks.
|
|
117
127
|
|
|
118
128
|
### Setup script
|
|
119
129
|
|
|
120
|
-
`bkit install` generates copy-paste-ready setup script into `.claude/bkit-cloud.md` § Setup script
|
|
130
|
+
`bkit install` generates a copy-paste-ready setup script into `.claude/bkit-cloud.md` § Setup script. It is resolved for this repo, with the cache-bust line, the base-tool installs and any `context-fetch:provision` recipes. Paste that, not a hand-copied snippet, because a stale copy drifts: a hard-pinned pnpm can seed a version known to break the `bkit` download, and `apt install gh` is unreliable because gh is not in the default repos.
|
|
121
131
|
|
|
122
|
-
What
|
|
132
|
+
What the script does, and why it is split from the in-repo hook:
|
|
123
133
|
|
|
124
|
-
- **`# cache-bust <date>-<n>`** first line generator writes
|
|
125
|
-
- **Base tools (Node, vale, gh, jq)** install once into snapshot from upstream releases
|
|
126
|
-
-
|
|
127
|
-
- `
|
|
134
|
+
- **`# cache-bust <date>-<n>`** is the first line the generator writes, and `bkit install` / `bkit upgrade` re-stamp it. The snapshot is keyed on the setup script's exact text, so the line's only job is to change. A new date, or a bumped same-day counter, forces a fresh snapshot on the next paste. That re-pulls any unpinned tool a `context-fetch:provision` recipe installs, and picks up base-image drift, even when the rest of the script is byte-identical. Leave the line in place, and do not edit it by hand.
|
|
135
|
+
- **Base tools (Node, vale, gh, jq)** install once into the snapshot from upstream releases. Each is pinned to a version and checked with `sha256sum -c` before it is unpacked or made executable. The `# renovate:` comment above each `*_VERSION` lets Renovate bump the pin.
|
|
136
|
+
- Node 24 comes from the nodejs.org `linux-x64` tarball into `/usr/local`, and `/usr/local/bin` is prepended to `PATH` so corepack and every later step run on it. bkit needs Node >=24, and the image ships 20 + 22.
|
|
137
|
+
- `gh` comes from the `cli/cli` release tarball, not `apt`.
|
|
138
|
+
- `jq` is installed because `curl`-based context-fetch blocks pipe through it.
|
|
139
|
+
- The Node, gh and vale pins match `.cursor/Dockerfile`.
|
|
140
|
+
- These are binaries the cloud lacks but a laptop has, so they belong here, not in a repo-level hook.
|
|
141
|
+
- **pnpm corepack pre-warm** seeds one pnpm into the snapshot: `corepack enable && corepack prepare pnpm@<version> --activate`, with the version read from your `package.json` `packageManager`. With no `packageManager` pin, the line is a bare `corepack enable`. Inside the repo, corepack resolves the repo's `packageManager` and fetches it if it differs, so one setup script serves any pnpm pin. The pre-warm only warms the cache.
|
|
142
|
+
- `pnpm install` and `vale sync` are not here. They belong in `.claude/hooks/bkit-cloud-bootstrap.sh`, so a resumed session picks up a drifted lockfile or styles, and each repo installs its own deps.
|
|
128
143
|
|
|
129
|
-
Keep total runtime under ~5 minutes or snapshot won't build.
|
|
144
|
+
Keep the total runtime under ~5 minutes, or the snapshot won't build.
|
|
130
145
|
|
|
131
146
|
#### Workspace trust + auto-mode config
|
|
132
147
|
|
|
133
|
-
`permissions.allow` / `permissions.additionalDirectories` in `.claude/settings.json`
|
|
148
|
+
`permissions.allow` / `permissions.additionalDirectories` in `.claude/settings.json` grant capability. Claude applies them only after the workspace trust dialog, which a cloud (`-p` / SDK) session never shows. `deny` / `ask` are unaffected, because they only restrict. In an untrusted workspace every `allow` row is ignored, and the only notice is one stderr line that no cloud session surfaces.
|
|
134
149
|
|
|
135
|
-
|
|
150
|
+
The setup script writes both of these on the host side, after the `jq` install:
|
|
136
151
|
|
|
137
152
|
<!-- prettier-ignore -->
|
|
138
153
|
| Written | Where | Why setup script |
|
|
139
154
|
| --- | --- | --- |
|
|
140
|
-
| `projects[<repo path>].hasTrustDialogAccepted = true` | `~/.claude.json` | Settings resolve
|
|
141
|
-
| `autoMode.environment` — `"$defaults"` first, `Host containment` entry, network-allowlist hosts | `~/.claude/settings.json` |
|
|
155
|
+
| `projects[<repo path>].hasTrustDialogAccepted = true` | `~/.claude.json` | Settings resolve before `SessionStart`, so a hook is too late, and `.claude/` is a protected path, so an in-session write is refused. The setup script runs as root, before the clone and before Claude, and is snapshotted. |
|
|
156
|
+
| `autoMode.environment` — `"$defaults"` first, `Host containment` entry, network-allowlist hosts | `~/.claude/settings.json` | The classifier reads `autoMode` from user / managed settings only, never from `.claude/settings.json` / `.claude/settings.local.json`, so it cannot ship in the repo. |
|
|
142
157
|
|
|
143
|
-
Both `jq
|
|
158
|
+
Both writes merge with `jq` and never clobber. `autoMode.environment` is seeded with `//=`, so a consumer's list is never overwritten. If `"$defaults"` is omitted, the whole built-in list for that section is discarded, `Trusted repo` included, so the renderer always emits it.
|
|
144
159
|
|
|
145
|
-
Neither file
|
|
160
|
+
Neither file can be committed. `~/.claude/settings.json` resolves outside the repo tree, and a git-tracked `.claude/settings.local.json` counts as repository-supplied, so it sits behind the same trust gate.
|
|
146
161
|
|
|
147
|
-
|
|
162
|
+
The baked path `/home/user/<repo-name>` is an observation of the current image, not a contract: no env var names the repo root. `.claude/hooks/bkit-cloud-bootstrap.sh` re-checks the discovered git root each session and warns on a mismatch. It only diagnoses, and does not repair. To fix a mismatch, re-paste the setup script.
|
|
148
163
|
|
|
149
|
-
Auto mode drops blanket `Bash(*)` on entry
|
|
164
|
+
Auto mode drops a blanket `Bash(*)` on entry, while narrow rows survive, so cloud auto-mode sessions run on the classifier's verdicts and `autoMode.environment`, not on the allow list. By default the classifier trusts the working repo and its remotes, and every context-fetch host counts as external until it is named. The default `Host containment` entry assumes an open-internet dev machine.
|
|
150
165
|
|
|
151
166
|
### Environment variables
|
|
152
167
|
|
|
153
|
-
|
|
168
|
+
The minimum:
|
|
154
169
|
|
|
155
170
|
```
|
|
156
171
|
BKIT_GH_TOKEN=<PAT — fine-grained for one owner, classic across owners; see permissions below>
|
|
157
172
|
```
|
|
158
173
|
|
|
159
|
-
|
|
174
|
+
Tracker keys (`BKIT_LINEAR_API_KEY`, `BKIT_JIRA_API_KEY`) join the block whenever `.envrc` resolves them, so the block is the same for every tracker. Set `BKIT_GH_TOKEN` for the GitHub MCP, and authenticate `gh` with `gh auth login --with-token` in the bootstrap hook, because env vars are not visible during the setup script (see § Notes).
|
|
160
175
|
|
|
161
|
-
Optional
|
|
176
|
+
Optional, for context-fetch:
|
|
177
|
+
|
|
178
|
+
- You need these only if you use `.agents/context.md` blocks, for example ones copied from `.bkit/templates/context/`.
|
|
179
|
+
- The tokens below are examples. Set whatever operator creds your enabled blocks need.
|
|
180
|
+
- They are cloud-dashboard entries, not `.bkit/.env` entries, because that file is for bkit / agent tooling only.
|
|
181
|
+
- Non-secret selectors (`VERCEL_SCOPE` / `SUPABASE_PROJECT_ID`) are committed in the copied block, so cloud agents inherit them without a dashboard entry.
|
|
182
|
+
- The CLIs install from each block's `context-fetch:provision` sibling.
|
|
162
183
|
|
|
163
184
|
```
|
|
164
185
|
VERCEL_TOKEN=<Vercel access token — https://vercel.com/account/settings/tokens>
|
|
@@ -167,7 +188,10 @@ SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/da
|
|
|
167
188
|
|
|
168
189
|
#### `BKIT_GH_TOKEN` — token permissions
|
|
169
190
|
|
|
170
|
-
**Choose the token type by how many owners it covers:**
|
|
191
|
+
**Choose the token type by how many owners it covers:** A fine-grained PAT reaches only resources under one resource owner (a user or an org). Use it when every target repo is under that owner. Use a classic PAT when one token must span more than one owner (two or more orgs, or a user + an org), since fine-grained PATs cannot access multiple organizations.
|
|
192
|
+
|
|
193
|
+
- **Fine-grained:** It has a mandatory expiry and a repo-scoped blast radius. Prefer it when it fits, because env vars are plaintext.
|
|
194
|
+
- **Classic:** Give it the scopes `repo`, `workflow`, `read:org`, `project`, `security_events` (+ `user:email` for Renovate authorship), and keep the expiry short. An org may block classic tokens (403), and SAML SSO orgs need the token authorized per org.
|
|
171
195
|
|
|
172
196
|
<!-- prettier-ignore -->
|
|
173
197
|
| Permission | Level | What it unlocks |
|
|
@@ -177,30 +201,30 @@ SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/da
|
|
|
177
201
|
| Issues | Read & write | `gh issue` |
|
|
178
202
|
| Actions | Read & write | `gh run view` logs, `gh workflow run` |
|
|
179
203
|
| Workflows | Read & write | `gh workflow` (edit `.github/workflows/*`) |
|
|
180
|
-
| Projects (org) | Read & write | GitHub Projects v2 board status sync (`bkit.github.project`) — org-owned boards only; see note |
|
|
204
|
+
| Projects (org) | Read & write | GitHub Projects v2 board status sync (`bkit.tracker.github.project`) — org-owned boards only; see note |
|
|
181
205
|
| Metadata | Read | mandatory, auto-included |
|
|
182
206
|
|
|
183
|
-
`gh` does
|
|
207
|
+
`gh` does not read `BKIT_GH_TOKEN`. Pipe it in once after the session starts: `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` (for example in `.claude/hooks/bkit-cloud-bootstrap.sh`). Locally, run `gh auth login` and leave `GH_TOKEN` unset, so the keyring is not overridden.
|
|
184
208
|
|
|
185
|
-
> **Projects v2 board sync (`bkit.github.project`):**
|
|
209
|
+
> **Projects v2 board sync (`bkit.tracker.github.project`):** The Projects permission is an Organization permission (table row above). It appears only when the token's resource owner is the org, not a personal account, and the org may require the token to be approved. It sits under the token UI's Organizations tab, not under Repository permissions, and it governs `…/orgs/{org}/projectsV2/…`. Fine-grained PATs cannot reach user-owned (personal-account) boards (see below).
|
|
186
210
|
|
|
187
211
|
#### When classic is still required
|
|
188
212
|
|
|
189
213
|
- **More than one repo across owners.** A fine-grained PAT is limited to a single resource owner (one user or one org), so it cannot cover two or more orgs, or a user plus an org. Classic reaches every repo your user can.
|
|
190
|
-
- **Cross-repo work in single cloud session.** Fine-grained PATs only
|
|
191
|
-
- **User-owned (personal-account) Projects v2 boards.** Fine-grained PATs expose Projects only as
|
|
214
|
+
- **Cross-repo work in single cloud session.** Fine-grained PATs see only their allowlist, while classic sees everything your user can.
|
|
215
|
+
- **User-owned (personal-account) Projects v2 boards.** Fine-grained PATs expose Projects only as an organization permission, so personal boards are unreachable. Use a classic PAT with `project` scope, or move the board under an org.
|
|
192
216
|
|
|
193
217
|
#### Notes
|
|
194
218
|
|
|
195
|
-
- Claude app warns "don't add secrets"
|
|
196
|
-
-
|
|
197
|
-
- **Env vars set in Claude app are not visible inside setup script.**
|
|
219
|
+
- The Claude app warns "don't add secrets", because env vars are visible to anyone with edit rights. On a personal account that is just you. Treat a team account as low-trust.
|
|
220
|
+
- For earlier auto-compaction, set `autoCompactWindow` in the committed `.claude/settings.json` (`.bkit/providers.md` § Context compaction). It applies to cloud sessions as-is, with no env var.
|
|
221
|
+
- **Env vars set in the Claude app are not visible inside the setup script.** They are injected only after Claude starts, so they reach `SessionStart` hooks and the interactive shell, not the snapshot build. A tool that needs a token to bootstrap would have to inline it, which is the leak you want to avoid. Today that is avoided, because vale / gh / corepack don't need auth.
|
|
198
222
|
|
|
199
|
-
##
|
|
223
|
+
## Tokens by session type
|
|
200
224
|
|
|
201
225
|
Token management by session type:
|
|
202
226
|
|
|
203
|
-
- **Local sessions** — bkit writes `.bkit/.env.example` (token placeholders)
|
|
227
|
+
- **Local sessions** — bkit writes `.bkit/.env.example` (token placeholders). `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy `.bkit/templates/.envrc`. Copy `.env.example` → `.bkit/.env`, fill in the tokens and run `direnv allow`. direnv auto-exports `BKIT_GH_TOKEN` and `BKIT_LINEAR_API_KEY` when you enter the repo, with no manual `source` or shell-rc export. `.bkit/.env` is gitignored. NEVER commit it.
|
|
204
228
|
|
|
205
229
|
```bash
|
|
206
230
|
cp .bkit/.env.example .bkit/.env
|
|
@@ -208,19 +232,28 @@ Token management by session type:
|
|
|
208
232
|
direnv allow
|
|
209
233
|
```
|
|
210
234
|
|
|
211
|
-
- **Cloud sessions** (Claude
|
|
235
|
+
- **Cloud sessions** (Claude on the web, Codex Cloud, Cursor Cloud Agents) — `.bkit/.env` is absent in cloud containers. Set the same names (`BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY`) in each host's dashboard:
|
|
236
|
+
- Claude app → environment selector → Environment variables.
|
|
237
|
+
- Cursor Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab (as **Runtime Secret**s).
|
|
238
|
+
- ChatGPT → **Settings > Codex Cloud > Environments** → **Environment variables**.
|
|
239
|
+
|
|
240
|
+
Each host's generated `<host>/bkit-cloud.md` is the paste-ready block.
|
|
212
241
|
|
|
213
|
-
**Beyond bkit tokens
|
|
242
|
+
**Beyond bkit tokens:** Fill in the rest from the env-var files that the repo's `.envrc` sources (for example `.bkit/.env`, then the app's `.env.local`). Don't hand-pick from memory. Copy from those files, following `.envrc`:
|
|
214
243
|
|
|
215
|
-
- **Drop every var `.envrc` `unset`s
|
|
216
|
-
- **Skip session-hijacking keys — notably `BKIT_ANTHROPIC_API_KEY
|
|
217
|
-
- **Values, not selectors.** Non-secret selectors (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`, …) stay committed in
|
|
244
|
+
- **Drop every var `.envrc` `unset`s.** These are kept out of the repo shell on purpose (for example prod cache creds that flip unit tests off the mock branch, or a project ref that mis-names the local stack), and they have no place in the cloud env.
|
|
245
|
+
- **Skip session-hijacking keys — notably `BKIT_ANTHROPIC_API_KEY`.** It redirects Claude model calls onto API-key billing instead of the subscription. The same goes for any var that re-points the agent's own auth.
|
|
246
|
+
- **Values, not selectors.** Non-secret selectors (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`, …) stay committed in the repo (§ observability / MCP blocks) and get no dashboard entry.
|
|
218
247
|
|
|
219
248
|
## MCP issue-tracker integration
|
|
220
249
|
|
|
221
|
-
bkit wires the chosen tracker's MCP server (`bkit.
|
|
250
|
+
bkit wires the chosen tracker's MCP server (`bkit.tracker.default`) into `.mcp.json` at the repo root (project-shared, read by the Claude `/mcp` UI). Cursor reads the same shape from `.cursor/mcp.json`. All of them are remote HTTP MCPs, with no docker:
|
|
222
251
|
|
|
223
|
-
|
|
252
|
+
- GitHub: the `BKIT_GH_TOKEN` PAT in the `Authorization` header, with no OAuth.
|
|
253
|
+
- Linear: OAuth on first use. Claude launches browser auth the first time it touches the server and stores the token in its own secret store.
|
|
254
|
+
- Jira: the `BKIT_JIRA_API_KEY` scoped token in the `Authorization` header, with no OAuth.
|
|
255
|
+
|
|
256
|
+
> Note: Claude silently ignores `mcpServers` in `.claude/settings.json`. It takes definitions only from `.mcp.json` (project) or `claude mcp add` (user scope). The `mcp__<name>__*` entries in `.claude/settings.json` `permissions.allow` are tool-permission allowlists, a different concern, and they stay there.
|
|
224
257
|
|
|
225
258
|
```json
|
|
226
259
|
"mcpServers": {
|
|
@@ -233,85 +266,114 @@ bkit wires the chosen tracker's MCP server (`bkit.issueTracker`) into `.mcp.json
|
|
|
233
266
|
"jira": {
|
|
234
267
|
"type": "http",
|
|
235
268
|
"url": "https://mcp.atlassian.com/v2/mcp",
|
|
236
|
-
"headers": { "Authorization": "Bearer ${
|
|
269
|
+
"headers": { "Authorization": "Bearer ${BKIT_JIRA_API_KEY}" }
|
|
237
270
|
}
|
|
238
271
|
}
|
|
239
272
|
```
|
|
240
273
|
|
|
241
|
-
`"type": "http"` required
|
|
274
|
+
`"type": "http"` is required. Without it, Claude defaults to the stdio transport and rejects the entry for a missing `command`.
|
|
242
275
|
|
|
243
|
-
- **GitHub** — official GitHub MCP at `api.githubcopilot.com` (not gated by Copilot subscription).
|
|
244
|
-
- **Linear** — full Linear workspace surface (`get_issue`, `save_issue`, `save_comment`, `list_*`).
|
|
245
|
-
- **Jira** — Atlassian Rovo MCP at `mcp.atlassian.com/v2/mcp`.
|
|
276
|
+
- **GitHub** — the official GitHub MCP at `api.githubcopilot.com` (not gated by a Copilot subscription). Its surface includes `issue_write`, `add_issue_comment`, `label_write`, `projects_write` and more. It is used under the GitHub provider. The endpoint does not support OAuth DCR, so auth goes through `Authorization: Bearer ${BKIT_GH_TOKEN}` (an MCP-only env var, see § Environment variables).
|
|
277
|
+
- **Linear** — the full Linear workspace surface (`get_issue`, `save_issue`, `save_comment`, `list_*`). It is used when `bkit.tracker.default` = `linear`. Auth is OAuth (Dynamic Client Registration): a browser flow on first use, with no env var.
|
|
278
|
+
- **Jira** — the Atlassian Rovo MCP at `mcp.atlassian.com/v2/mcp`. Its surface is `getJiraIssue`, `editJiraIssue`, `transitionJiraIssue`, `addOrEditJiraIssueComment`, `searchJiraIssuesUsingJql` and `executeRead` / `executeWrite`. It is used when `bkit.tracker.default` = `jira`. Auth goes through `Authorization: Bearer ${BKIT_JIRA_API_KEY}`, a scoped **Atlassian MCP V2** token, and the org admin must allow API-token sign-in (`.bkit/trackers.md` § jira — setup and notes).
|
|
246
279
|
|
|
247
280
|
**Auth flow per server:**
|
|
248
281
|
|
|
249
|
-
- **GitHub:** Claude
|
|
250
|
-
- **Linear:** Claude
|
|
251
|
-
- **Jira:** Claude
|
|
282
|
+
- **GitHub:** Claude substitutes `${BKIT_GH_TOKEN}` from the environment at session start. If it is unset, the server fails. Set it in the shell (`export BKIT_GH_TOKEN=...`) or the cloud dashboard.
|
|
283
|
+
- **Linear:** Claude asks you to authorize in the browser on first use, and keeps the token in Claude's secret store. No further action is needed.
|
|
284
|
+
- **Jira:** Claude substitutes `${BKIT_JIRA_API_KEY}` from the environment at session start. If it is unset or a classic token, every Jira call fails.
|
|
252
285
|
|
|
253
|
-
**`gh auth login` required for gh CLI surface** (PR creation, branch ops, git push). Locally, keyring
|
|
286
|
+
**`gh auth login` is required for the gh CLI surface** (PR creation, branch ops, git push). Locally, gh uses the keyring, so do not export `GH_TOKEN` from `.bkit/.env`. In cloud / headless sessions, `bkit-cloud-bootstrap.sh` runs `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` at SessionStart, so there is no manual step. The `bkit runtime detect` gh probe guards that step, and it does nothing on an Actions runner, where `GITHUB_TOKEN` authenticates. The same PAT value is fine. The different env-var name keeps the local `gh` on the keyring.
|
|
254
287
|
|
|
255
|
-
**Cloud sessions** (Claude on the web, Cursor Cloud Agents): GitHub MCP reads `BKIT_GH_TOKEN
|
|
288
|
+
**Cloud sessions** (Claude on the web, Codex Cloud, Cursor Cloud Agents): The GitHub MCP reads `BKIT_GH_TOKEN`, and the Jira MCP reads `BKIT_JIRA_API_KEY`, from the dashboard env vars. The Linear MCP runs OAuth on first touch, the same as locally. Jira has no cloud dispatch, so a manually launched session reaches Jira once `BKIT_JIRA_API_KEY` is set.
|
|
256
289
|
|
|
257
290
|
## After saving the Claude env
|
|
258
291
|
|
|
259
|
-
1. Trigger session: `claude --remote "echo ready"` from repo, or tap
|
|
260
|
-
2.
|
|
261
|
-
3. Verify in
|
|
262
|
-
4. Verify workspace trust on the discovered root
|
|
292
|
+
1. Trigger a session: run `claude --remote "echo ready"` from the repo, or tap the environment in the iOS app.
|
|
293
|
+
2. The first session is slow (setup script + snapshot). Later sessions start from the snapshot.
|
|
294
|
+
3. Verify in the session: `vale --version && gh --version && pnpm -v && which corepack`.
|
|
295
|
+
4. Verify workspace trust on the discovered root. `true` means the `allow` rows apply, and `MISSING` means the clone path differs from the baked one (§ Workspace trust + auto-mode config):
|
|
263
296
|
|
|
264
297
|
```bash
|
|
265
298
|
jq -r --arg p "$(git rev-parse --show-toplevel)" \
|
|
266
299
|
'.projects[$p].hasTrustDialogAccepted // "MISSING"' "${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json"
|
|
267
300
|
```
|
|
268
301
|
|
|
269
|
-
5.
|
|
270
|
-
6. **Force rebuild without semantic changes**:
|
|
302
|
+
5. The snapshot rebuilds when the setup-script body changes, the allowed-hosts list changes, or the ~7-day TTL expires. Editing env vars or in-repo hook scripts does not invalidate the snapshot.
|
|
303
|
+
6. **Force rebuild without semantic changes**: run `bkit install` or `bkit upgrade`, which re-stamps the `# cache-bust` line, then paste the new setup script.
|
|
304
|
+
|
|
305
|
+
# Codex Cloud
|
|
306
|
+
|
|
307
|
+
> [!TIP]
|
|
308
|
+
> **Nothing to hand-assemble.** `bkit install --codex` writes `.codex/bkit-cloud.md`, the
|
|
309
|
+
> twin of `.claude/bkit-cloud.md`: the install script, the env block resolved from `.envrc` (the same
|
|
310
|
+
> block as the other hosts, for any tracker) and the network list. The file is gitignored and chmod 600 because it holds real
|
|
311
|
+
> secrets. It regenerates on every install / upgrade, and `bkit uninstall --codex` deletes it.
|
|
312
|
+
|
|
313
|
+
## What to paste
|
|
314
|
+
|
|
315
|
+
ChatGPT → **Settings > Codex Cloud > Environments** → **Create environment** → pick the repo → name it after the repo (one env per repo, § Sharing across repos):
|
|
316
|
+
|
|
317
|
+
<!-- prettier-ignore -->
|
|
318
|
+
| Field | Paste from `.codex/bkit-cloud.md` |
|
|
319
|
+
| --- | --- |
|
|
320
|
+
| **Install script** | § Install script — Claude setup script's pinned toolchain (Node, vale, gh, jq; sliced from the Claude template at install, never a second copy of the pins), corepack pnpm, context-fetch provision recipes, then `pnpm install --frozen-lockfile`, `vale sync` (if `.vale.ini`), non-blocking `gh auth login --with-token` from `BKIT_GH_TOKEN` |
|
|
321
|
+
| **Environment variables** | § Environment variables — `.env` block (**Paste your .env or type a key**) |
|
|
322
|
+
| **Internet access** | § Network access — keep **Enable package manager domains**, paste the list into **Additional allowed domains** (`*.` entries untested on Codex: its docs list exact hosts, and a root domain also allows `www`). **Enable all public internet access** = open egress |
|
|
323
|
+
|
|
324
|
+
## Env vars vs network secrets
|
|
325
|
+
|
|
326
|
+
- **Environment variables** reach every program as-is, so put every bkit token here (MCP servers, `gh`, `pnpm` and bkit read the process env).
|
|
327
|
+
- **Network secrets** (Key / Value / **Allowed domains**): Programs see a placeholder. The proxy substitutes the real value only on requests to allowed domains, during setup and tasks. This fits a token used only in HTTP headers to known hosts, and breaks any token a program reads directly (`gh auth login --with-token`).
|
|
328
|
+
- **Personal vault** shares a secret across **All environments** or **Selected environments**, for a token several repos reuse.
|
|
329
|
+
|
|
330
|
+
## Hooks in cloud tasks
|
|
331
|
+
|
|
332
|
+
Repo skills (`.agents/skills/bkit-*`, `$bkit-design`) load in cloud tasks. Codex's cloud docs do not say whether `.codex/hooks.json` runs there, so GateGuard, ReadGuard, guardrails and the rules advisory are unproven in cloud tasks. Review cloud diffs as unguarded. Locally they fire only once the `.codex/` layer is trusted (`.bkit/providers.md` § Codex CLI — three deviations).
|
|
271
333
|
|
|
272
334
|
# Cursor Cloud Agents
|
|
273
335
|
|
|
274
|
-
> Cursor calls these **Cloud Agents
|
|
336
|
+
> Cursor calls these **Cloud Agents**. Secrets live in the **Secrets tab** of the Cloud
|
|
275
337
|
> Agents dashboard (`cursor.com/dashboard/cloud-agents`). The webhook field is
|
|
276
338
|
> `is_background_agent`. This doc uses "Cloud Agents" throughout.
|
|
277
339
|
|
|
278
340
|
> [!TIP]
|
|
279
341
|
> **No manual copy needed for the dashboard secrets.** `bkit install --cursor` writes
|
|
280
|
-
> `.cursor/bkit-cloud.md
|
|
281
|
-
>
|
|
342
|
+
> `.cursor/bkit-cloud.md`, the twin of `.claude/bkit-cloud.md`, with the Cursor secrets block
|
|
343
|
+
> resolved from `.envrc` (the same block as the Claude side, for any tracker). Open it, then in the
|
|
282
344
|
> Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets**
|
|
283
|
-
> tab, add each as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript).
|
|
284
|
-
>
|
|
285
|
-
> half is the committed `.cursor/Dockerfile` + `.cursor/environment.json
|
|
286
|
-
> paste
|
|
345
|
+
> tab, add each entry as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript).
|
|
346
|
+
> The file is gitignored because it holds real secrets, and it regenerates on every install/upgrade. The toolchain
|
|
347
|
+
> half is the committed `.cursor/Dockerfile` + `.cursor/environment.json`, with nothing to
|
|
348
|
+
> paste. It has the same tools, at the same versions, as the Claude setup script.
|
|
287
349
|
|
|
288
350
|
## Where config lives
|
|
289
351
|
|
|
290
|
-
Everything in repo under `.cursor/`. bkit ships canonical content for all four files:
|
|
352
|
+
Everything lives in the repo under `.cursor/`. bkit ships canonical content for all four files:
|
|
291
353
|
|
|
292
354
|
<!-- prettier-ignore -->
|
|
293
355
|
| File | Role | bkit ownership |
|
|
294
356
|
| --- | --- | --- |
|
|
295
357
|
| `.cursor/Dockerfile` | Cloud image — vale + gh + Node 24 (template default) + pnpm (corepack-pinned); Node, gh and vale are version-pinned and sha256-checked; browsers etc. added by the consumer | Template: copy from `.bkit/templates/.cursor/Dockerfile`; yours after |
|
|
296
|
-
| `.cursor/environment.json` | Build pointer + per-snapshot `install` hook (`pnpm install --frozen-lockfile` + `vale sync` if `.vale.ini`) | Template: copy from `.bkit/templates/.cursor/environment.json`; yours after |
|
|
358
|
+
| `.cursor/environment.json` | Build pointer + per-snapshot `install` hook (`pnpm install --frozen-lockfile` + `vale sync` if `.vale.ini` + `pnpm exec bkit context provision`) | Template: copy from `.bkit/templates/.cursor/environment.json`; yours after |
|
|
297
359
|
| `.cursor/hooks.json` | Wires `sessionStart` → `bkit-preflight.sh` (`failClosed: true`) | Tier 2 contained JSON |
|
|
298
|
-
| `.cursor/hooks/bkit-preflight.sh` | Tracker opt-in guard — `bkit:auto` label + non-terminal status.
|
|
360
|
+
| `.cursor/hooks/bkit-preflight.sh` | Tracker opt-in guard — `bkit:auto` label + non-terminal status — plus the rules-read advisory (`.bkit/providers.md` § Rules-read advisory). IDE session → the advisory alone, exit 0 | Tier 2 contained (bkit:start / end markers) |
|
|
299
361
|
|
|
300
362
|
## How GitHub dispatch works
|
|
301
363
|
|
|
302
|
-
GitHub dispatch uses Cursor Automations "Pull request label changed" trigger
|
|
364
|
+
GitHub dispatch uses the Cursor Automations "Pull request label changed" trigger, with no Linear webhook.
|
|
303
365
|
|
|
304
|
-
**Prerequisites:** Cursor GitHub App installed on consumer repo or org.
|
|
366
|
+
**Prerequisites:** The Cursor GitHub App is installed on the consumer repo or org.
|
|
305
367
|
|
|
306
368
|
**Trigger flow:**
|
|
307
369
|
|
|
308
|
-
1. `bkit-build` writes `bkit:auto` as static PR label (opt-in marker).
|
|
309
|
-
2.
|
|
310
|
-
3. Cursor Automations fires on "Pull request label changed" → spawns Background Agent session against repo.
|
|
311
|
-
4. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, non-zero exit hard-stops agent.
|
|
312
|
-
5. `GITHUB_ISSUE_ID` injected from PR body metadata marker `<!-- bkit:issue=#NNN
|
|
370
|
+
1. `bkit-build` writes `bkit:auto` as a static PR label (the opt-in marker). The matching GitHub issue must also carry `bkit:auto`, which is the runtime kill switch: remove it to stop dispatch.
|
|
371
|
+
2. The workflow adds the phase label (`bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`) to the PR. Cursor reads the label for workflow dispatch.
|
|
372
|
+
3. Cursor Automations fires on "Pull request label changed" → spawns a Background Agent session against the repo. The Automation's prompt must contain `bkit-auto`, because `AGENTS.md` routes only a `bkit-{command}` prompt, and `.bkit/router.md` reads the phase from the issue's labels.
|
|
373
|
+
4. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, a non-zero exit hard-stops the agent.
|
|
374
|
+
5. `GITHUB_ISSUE_ID` is injected from the PR body metadata marker `<!-- bkit:issue=#NNN -->`, which the router extracts at dispatch time.
|
|
313
375
|
|
|
314
|
-
**Constraint:** `/bkit-design` and `/bkit-plan` have no PR
|
|
376
|
+
**Constraint:** `/bkit-design` and `/bkit-plan` have no PR, so on Cursor cloud with the GitHub tracker they are local-IDE-only. Run them locally through Claude or the Cursor IDE.
|
|
315
377
|
|
|
316
378
|
**Required env vars (GitHub tracker):**
|
|
317
379
|
|
|
@@ -319,29 +381,34 @@ GitHub dispatch uses Cursor Automations "Pull request label changed" trigger —
|
|
|
319
381
|
BKIT_GH_TOKEN=<PAT — fine-grained for one owner, classic across owners; same permissions as the Claude side>
|
|
320
382
|
```
|
|
321
383
|
|
|
322
|
-
`GITHUB_ISSUE_ID` injected per
|
|
384
|
+
`GITHUB_ISSUE_ID` is injected per session, so do not hardcode it. Tracker calls need no `BKIT_LINEAR_API_KEY` or `LINEAR_ISSUE_ID`: the GitHub MCP authenticates with `BKIT_GH_TOKEN` above, and `gh` uses `gh auth login` locally or `--with-token` in the cloud bootstrap.
|
|
323
385
|
|
|
324
386
|
## How Linear dispatch works
|
|
325
387
|
|
|
326
|
-
`@cursor` is
|
|
388
|
+
`@cursor` is Cursor's native Linear integration, not bkit. bkit does not intercept the mention or run its own Linear webhook. The spawned agent picks up bkit because every Cursor cloud agent reads the root `AGENTS.md`, which sends a `bkit-{command}` prompt to `.bkit/router.md` → matching workflow.
|
|
327
389
|
|
|
328
|
-
1.
|
|
329
|
-
2. Cursor webhook → background agent against repo with `is_background_agent: true` and `LINEAR_ISSUE_ID` set.
|
|
330
|
-
3. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, non-zero exit hard-stops agent before work.
|
|
331
|
-
4. Preflight skips
|
|
390
|
+
1. Comment `@cursor bkit-auto ISSUE-NNN` (phase from the issue's labels) or `@cursor /bkit-design ISSUE-NNN`, which is Cursor's standard Linear integration. Assigning the issue to **Cursor** alone starts no workflow, because its prompt names no `bkit-{command}`.
|
|
391
|
+
2. The Cursor webhook → a background agent against the repo, with `is_background_agent: true` and `LINEAR_ISSUE_ID` set.
|
|
392
|
+
3. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, a non-zero exit hard-stops the agent before work.
|
|
393
|
+
4. Preflight skips IDE sessions (`is_background_agent !== true`), so the local Cursor IDE is unaffected.
|
|
332
394
|
|
|
333
395
|
## Required env vars (Cursor side)
|
|
334
396
|
|
|
335
|
-
Set in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab) as **Runtime Secret**s (loaded as env vars, redacted from the agent's transcript),
|
|
397
|
+
Set these in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab) as **Runtime Secret**s (loaded as env vars, redacted from the agent's transcript), not in `.cursor/environment.json`:
|
|
336
398
|
|
|
337
399
|
```
|
|
338
|
-
BKIT_LINEAR_API_KEY=<Linear personal API key — bkit-preflight.sh calls the GraphQL API>
|
|
339
400
|
BKIT_GH_TOKEN=<PAT — fine-grained for one owner, classic across owners; same permissions as the Claude side>
|
|
340
401
|
```
|
|
341
402
|
|
|
342
|
-
`
|
|
403
|
+
Add every tracker key `.envrc` resolves. Under Linear that is `BKIT_LINEAR_API_KEY` (a Linear personal API key, because `bkit-preflight.sh` calls the GraphQL API). The Cursor / Linear integration injects `LINEAR_ISSUE_ID` per session, so do not hardcode it.
|
|
343
404
|
|
|
344
|
-
Optional
|
|
405
|
+
Optional, for context-fetch:
|
|
406
|
+
|
|
407
|
+
- You need these only if you use `.agents/context.md` blocks, for example ones copied from `.bkit/templates/context/`.
|
|
408
|
+
- The tokens below are examples. Set whatever operator creds your enabled blocks need.
|
|
409
|
+
- They are cloud-dashboard entries, not `.bkit/.env` entries, because that file is for bkit / agent tooling only.
|
|
410
|
+
- Non-secret selectors (`VERCEL_SCOPE` / `SUPABASE_PROJECT_ID`) are committed in the copied block, so cloud agents inherit them without a dashboard entry.
|
|
411
|
+
- The CLIs install from each block's `context-fetch:provision` sibling.
|
|
345
412
|
|
|
346
413
|
```
|
|
347
414
|
VERCEL_TOKEN=<Vercel access token — https://vercel.com/account/settings/tokens>
|
|
@@ -350,66 +417,73 @@ SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/da
|
|
|
350
417
|
|
|
351
418
|
## Network access (Cursor side)
|
|
352
419
|
|
|
353
|
-
Cloud Agents get network access by default
|
|
420
|
+
Cloud Agents get network access by default. Egress is configurable in the dashboard → **Security**: **Allow all** / **Default + allowlist** / **Allowlist only**, at user / environment / team scope. This is the analogue of Claude's `Trusted` / `Custom`. `.cursor/bkit-cloud.md` § Network access lists bkit's derived hosts exactly, and each declared `allowed-domains` entry as the domain plus its `*.` wildcard, like the Claude side, so the subdomains a declared CLI or API calls (`api.vercel.com` under `vercel.com`) are reachable. A declared shared hosting platform (`vercel.app`, `supabase.co`, the rest of `MULTI_TENANT_APEXES` in `.bkit/core/engine/shared/egress.ts`) is widened too, with a note: its wildcard reaches every tenant on the platform, the exfiltration path Cursor's docs warn about. To narrow it, declare the exact hosts you call there instead (`myapp.vercel.app`, `logging.googleapis.com`).
|
|
354
421
|
|
|
355
422
|
## After modifying `.cursor/*`
|
|
356
423
|
|
|
357
|
-
1. Run `pnpm
|
|
358
|
-
2. Commit changes.
|
|
359
|
-
3. **
|
|
360
|
-
4. Verify in
|
|
424
|
+
1. Run `pnpm install && pnpm bkit install` to regenerate the mirrors.
|
|
425
|
+
2. Commit the changes.
|
|
426
|
+
3. **The first Cursor session after Dockerfile changes is slow**, because the image rebuilds. Later sessions reuse the cached layers.
|
|
427
|
+
4. Verify in the session: `vale --version && gh --version && pnpm -v && python3 --version`.
|
|
361
428
|
|
|
362
429
|
# Sharing across repos
|
|
363
430
|
|
|
364
431
|
## Claude — one environment per repo
|
|
365
432
|
|
|
366
|
-
Each repo gets
|
|
433
|
+
Each repo gets its own Claude environment, named after the repo. The reason is secrets, not mechanics.
|
|
434
|
+
|
|
435
|
+
**Secrets are per-repo.** App tokens (Supabase, Stripe, Vercel, …) differ per repo. Even bkit tokens differ in scope: a fine-grained `BKIT_GH_TOKEN` is scoped to one resource owner / repo, and covering different owners needs one classic PAT, which cannot be per-repo. One Claude environment holds one value per name, so a shared environment forces either a mega-scoped PAT across repos (a wide blast radius) or one repo's secrets leaking into the rest. Per-repo environments isolate secrets.
|
|
436
|
+
|
|
437
|
+
Shared across repos (copy, don't re-derive), non-secret only:
|
|
367
438
|
|
|
368
|
-
**
|
|
439
|
+
- **Setup script** — generic binaries only (Node, vale, gh, jq, pnpm via corepack). The repo-specific install is left to the committed `bkit-cloud-bootstrap.sh` (lockfile → `pnpm install`, `.vale.ini` → `vale sync`). One body fits every repo.
|
|
440
|
+
- **bkit baseline token name** (`BKIT_GH_TOKEN`) + **network policy** (`Custom`) — the same everywhere, while the values differ. The repo's other env vars are not shared. Copy them from the repo's own env files, following `.envrc`: drop the `unset`s and skip `BKIT_ANTHROPIC_API_KEY` (§ Tokens by session type).
|
|
441
|
+
- **Non-secret selectors** (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`) stay committed in the repo (§ Tokens by session type), never in the dashboard.
|
|
369
442
|
|
|
370
|
-
|
|
443
|
+
## Codex — one environment per repo
|
|
371
444
|
|
|
372
|
-
-
|
|
373
|
-
- **bkit baseline token _name_** (`BKIT_GH_TOKEN`) + **network policy** (`Trusted`) — same everywhere, values differ. Repo _other_ env vars **not** shared: copy from own env files per `.envrc` — drop `unset`s, skip `BKIT_ANTHROPIC_API_KEY` (§ Environment variables).
|
|
374
|
-
- **Non-secret selectors** (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`) stay committed in-repo (§ Environment variables), never in dashboard.
|
|
445
|
+
The rule is the same as for Claude: a per-repo environment with per-repo secrets. The install script is identical across repos, because the repo-specific steps guard themselves on `pnpm-lock.yaml` / `.vale.ini`. For a token shared on purpose, use the **Personal vault** scoped to **Selected environments**, not a mega-scoped PAT.
|
|
375
446
|
|
|
376
447
|
## Cursor — byte-identical Dockerfile
|
|
377
448
|
|
|
378
|
-
Cursor environment
|
|
449
|
+
Cursor resolves the environment in this order: (1) `.cursor/environment.json` in the repo, (2) a personal saved environment in the Cursor account, (3) a team saved environment. There are three sharing patterns:
|
|
379
450
|
|
|
380
|
-
1. **In-repo copy (bkit default).** Each consumer repo carries `.cursor/Dockerfile` + `.cursor/environment.json`, copied from bkit's templates and owned by the repo.
|
|
381
|
-
2. **Personal saved environment (cross-repo).** Don't commit `.cursor/environment.json
|
|
382
|
-
3. **Multi-repo environment.** Cursor binds one environment to multiple repos cloned into same agent VM.
|
|
451
|
+
1. **In-repo copy (bkit default).** Each consumer repo carries `.cursor/Dockerfile` + `.cursor/environment.json`, copied from bkit's templates and owned by the repo. Cursor environments are functionally equivalent across consumers, and bkit ships base-toolchain updates as template changes the consumer adopts.
|
|
452
|
+
2. **Personal saved environment (cross-repo).** Don't commit `.cursor/environment.json`. Configure a single environment in the Cursor account dashboard, and Cursor falls back to it for any session. Like any cross-repo environment, it holds one secret set for all repos. Prefer the per-repo default (#1) when repos have distinct secrets.
|
|
453
|
+
3. **Multi-repo environment.** Cursor binds one environment to multiple repos cloned into the same agent VM. This allows cross-repo work, but the agent sees all selected repos, which is a different security boundary.
|
|
383
454
|
|
|
384
|
-
When bkit reference Dockerfile changes (
|
|
455
|
+
When bkit's reference Dockerfile changes (for example a vale bump):
|
|
385
456
|
|
|
386
|
-
-
|
|
457
|
+
- bkit never writes the consumer's `.cursor/Dockerfile`, because it is the consumer's copy of a template.
|
|
387
458
|
- `bkit upgrade` refreshes `.bkit/templates/.cursor/Dockerfile` and names it in its changed-templates list.
|
|
388
|
-
-
|
|
459
|
+
- The consumer diffs the refreshed template against their copy and merges what they want.
|
|
389
460
|
|
|
390
461
|
## What every consumer repo needs to do
|
|
391
462
|
|
|
392
|
-
1. `pnpm bkit install
|
|
393
|
-
|
|
394
|
-
|
|
463
|
+
1. Run `pnpm bkit install`. bkit-managed toolchain updates land in the written payload.
|
|
464
|
+
- `.claude/hooks/bkit-cloud-bootstrap.sh` is a copy-and-own template. When `bkit upgrade` lists that path, diff your copy against `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` and merge what you want.
|
|
465
|
+
- `.cursor/Dockerfile` is your copy of a template. Diff it against `.bkit/templates/.cursor/Dockerfile` when `bkit upgrade` lists that path.
|
|
466
|
+
2. Set the `.cursor/bkit-cloud.md` block as **Runtime Secret**s in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab).
|
|
467
|
+
3. Add a Claude environment named after the repo at `claude.ai/code`, and paste the recipe from § Claude on the web (one environment per repo, because secrets are per-repo).
|
|
468
|
+
Codex: do the same at **Settings > Codex Cloud > Environments**, pasted from `.codex/bkit-cloud.md` (§ Codex Cloud).
|
|
395
469
|
4. Customise `.cursor/Dockerfile` Node version (`NODE_VERSION` + `NODE_SHA256`) / Playwright / extra system deps. Keep the `bkit toolchain` section as the template ships it, so a template diff stays readable.
|
|
396
470
|
|
|
397
471
|
# Post-CI auto-routing
|
|
398
472
|
|
|
399
|
-
After `bkit-build` Step
|
|
473
|
+
After `bkit-build` Step 16 close-workflow pushes the CI-trigger commit (`chore({FID}): close-workflow`, no skip tags) and exits, the post-CI router decides ship vs. debug and dispatches the matching skill in a fresh cloud session. No operator action is needed between CI completion and the dispatched session.
|
|
400
474
|
|
|
401
|
-
|
|
475
|
+
The routing logic lives in a single bkit-managed slash-command orchestrator (`.bkit/core/workflows/bkit-auto.md`, mirrored to `.claude/commands/bkit-auto.md` + `.cursor/commands/bkit-auto.md` on each `pnpm bkit install`). The routing trigger is wired separately per IDE, because each IDE has different event surfaces.
|
|
402
476
|
|
|
403
477
|
## What lives where (post-CI half)
|
|
404
478
|
|
|
405
479
|
<!-- prettier-ignore -->
|
|
406
480
|
| | Lives in the repo (bkit-managed) | Lives in the online dashboard / GitHub (manual, one-time) |
|
|
407
481
|
| --- | --- | --- |
|
|
408
|
-
| **Claude** | `.github/workflows/bkit-cloud.yml` — `claude` job (opt-in via `bkit install --auto=claude`; GitHub-tracker only). Two-tier gate: (1) free tier — job `if: contains(head_commit.message, 'bkit [auto route]')` (zero runner minutes for non-opted-in commits); (2) cheap tier — in-job `gh issue view {ISSUE} --json labels` re-checks `bkit:auto` (live kill switch); then dispatches `claude-code-action` as the Claude GitHub App (OIDC, `id-token: write`). | Claude credential: GitHub repo secret `ANTHROPIC_API_KEY` (`.bkit/.env` holds the same value as `BKIT_ANTHROPIC_API_KEY`)
|
|
409
|
-
| **
|
|
410
|
-
| **
|
|
482
|
+
| **Claude** | `.github/workflows/bkit-cloud.yml` — `claude` job (opt-in via `bkit install --auto=claude`; GitHub-tracker only). Two-tier gate: (1) free tier — job `if: contains(head_commit.message, 'bkit [auto route]')` (zero runner minutes for non-opted-in commits); (2) cheap tier — in-job `gh issue view {ISSUE} --json labels` re-checks `bkit:auto` (live kill switch); then dispatches `claude-code-action` as the Claude GitHub App (OIDC, `id-token: write`). | Claude credential: GitHub repo secret `ANTHROPIC_API_KEY` (`.bkit/.env` holds the same value as `BKIT_ANTHROPIC_API_KEY`) or keyless federation repo variables (§ Claude — workload identity federation). Claude GitHub App required (`/install-github-app`). The linked **GitHub issue** must carry `bkit:auto`. |
|
|
483
|
+
| **Cursor** | Nothing — Cursor cloud agents have native triggers. | Cursor → Cloud Agents dashboard → Triggers → + Add trigger. Event: CI workflow completion on `feat/**` branches. Prompt (paste literally, no edits): `/bkit-auto $CI_STATUS $PR_NUMBER`. Concurrency: latest-supersedes. |
|
|
484
|
+
| **OpenCode** | Same `.github/workflows/bkit-cloud.yml` — `opencode` job (opt-in via `bkit install --auto=opencode`; GitHub-tracker only). Same two-tier gate (same file, separate job). Dispatches via `opencode run "/bkit-auto $PHASE $ARG"`. No `id-token: write` — no OIDC; uses `github.token` for repo ops. | GitHub repo secret: `OPENCODE_PROVIDER_KEY` (set to your provider API key). Provider model committed in `.opencode/opencode.json`. The linked **GitHub issue** must carry `bkit:auto`. |
|
|
411
485
|
|
|
412
|
-
**Why dashboard prompt never needs re-pasting:** Cursor substitutes `$CI_STATUS` and `$PR_NUMBER` from event payload at dispatch
|
|
486
|
+
**Why the dashboard prompt never needs re-pasting:** Cursor substitutes `$CI_STATUS` and `$PR_NUMBER` from the event payload at dispatch, so the pasted string is generic and timeless. When bkit's routing logic evolves, only the mirrored `.cursor/commands/bkit-auto.md` changes, and the dashboard stays untouched.
|
|
413
487
|
|
|
414
488
|
## Cursor dashboard — exact paste
|
|
415
489
|
|
|
@@ -419,32 +493,39 @@ Routing **logic** in single bkit-managed slash-command orchestrator (`.bkit/core
|
|
|
419
493
|
|
|
420
494
|
## Claude — required GitHub Actions permissions
|
|
421
495
|
|
|
422
|
-
Flip
|
|
496
|
+
Flip the setting on both the org and the repo before the first router run. Otherwise `actions/checkout` 403s with `Write access to repository not granted`. The workflow declares `permissions: contents: write` at workflow scope, but the org / repo "Workflow permissions" ceiling overrides it, and the repo cannot exceed the org.
|
|
423
497
|
|
|
424
498
|
- **Org**: `https://github.com/organizations/{ORG}/settings/actions` → Workflow permissions → **Read and write permissions** + tick **Allow GitHub Actions to create and approve pull requests**.
|
|
425
|
-
- **Repo**: `https://github.com/{ORG}/{REPO}/settings/actions` → same section, same two settings. Apply at repo too
|
|
499
|
+
- **Repo**: `https://github.com/{ORG}/{REPO}/settings/actions` → the same section, the same two settings. Apply them at the repo too, because inheriting from the org is not automatic.
|
|
426
500
|
|
|
427
|
-
`workflow_run`-triggered runs do
|
|
501
|
+
`workflow_run`-triggered runs do not inherit the parent CI workflow's `permissions:` block (only fork-PR tokens get narrowed), so a parent CI at `contents: read` is fine.
|
|
428
502
|
|
|
429
503
|
## bkit-cloud.yml — required GitHub repo credentials
|
|
430
504
|
|
|
431
505
|
<!-- prettier-ignore -->
|
|
432
506
|
| Secret / variable | Job | Why | Scope |
|
|
433
507
|
| --- | --- | --- | --- |
|
|
434
|
-
| `ANTHROPIC_API_KEY` secret | `claude` | `claude-code-action` authenticates against Anthropic. | API key with Claude
|
|
508
|
+
| `ANTHROPIC_API_KEY` secret | `claude` | `claude-code-action` authenticates against Anthropic. | API key with Claude access. Omit when using federation. |
|
|
435
509
|
| `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` variables | `claude` | Keyless alternative: the action trades the job's GitHub OIDC token for a short-lived Claude API token. | IDs, not secrets — repo **variables**. Optional `ANTHROPIC_SERVICE_ACCOUNT_ID` / `ANTHROPIC_WORKSPACE_ID`. § Claude — workload identity federation. |
|
|
436
510
|
| `OPENCODE_PROVIDER_KEY` | `opencode` | Fanned out to every cloud provider's env var name (`BKIT_OPENROUTER_API_KEY`, `BKIT_OLLAMA_API_KEY`, `BKIT_OPENCODE_API_KEY`) so the `.opencode/opencode.json` `{env:VAR}` reference resolves whichever provider is installed. | Provider API key for whichever provider you configured. |
|
|
437
511
|
|
|
438
|
-
A `context` job (`Check runner credentials` step) checks both credentials and resolves phase + arg once
|
|
512
|
+
A `context` job (`Check runner credentials` step) checks both credentials and resolves the phase + arg once. It does nothing unless `package.json` `bkit.tracker.default` is `github` or unset, because Linear cloud runs start from Cursor's Linear integration and Jira runs locally only. Each runner job needs it, and runs only when its own credential is set:
|
|
513
|
+
|
|
514
|
+
- The Claude credential is `ANTHROPIC_API_KEY`, or both federation variables. With only one of the two variables set, the job prints a `::notice::` naming the missing one, and the claude job does nothing.
|
|
515
|
+
- Only the claude credential set → only the claude job runs.
|
|
516
|
+
- Only `OPENCODE_PROVIDER_KEY` set → only the OpenCode job runs.
|
|
517
|
+
- Both set → both jobs run (additive coexistence).
|
|
518
|
+
|
|
519
|
+
No `BKIT_LINEAR_API_KEY` is needed, because `bkit-cloud.yml` is GitHub-tracker only for both jobs. The workflow grants `id-token: write` per job, for claude only (Claude GitHub App + federation token exchange). OpenCode has no OIDC.
|
|
439
520
|
|
|
440
521
|
## Claude — workload identity federation
|
|
441
522
|
|
|
442
|
-
|
|
523
|
+
The keyless claude job stores no long-lived `ANTHROPIC_API_KEY` in GitHub. `claude-code-action` asks GitHub for the job's OIDC token (issuer `https://token.actions.githubusercontent.com`, audience `https://api.anthropic.com`). Anthropic checks it against a federation rule and returns a short-lived Claude API token. The action refreshes it in the background on long runs.
|
|
443
524
|
|
|
444
525
|
**Setup (one-time):**
|
|
445
526
|
|
|
446
|
-
1. Claude Console → **Settings → Workload identity → Connect workload → GitHub Actions**.
|
|
447
|
-
2. Scope the rule to this repo's default branch
|
|
527
|
+
1. Claude Console → **Settings → Workload identity → Connect workload → GitHub Actions**. This creates the federation issuer, a service account, and a federation rule.
|
|
528
|
+
2. Scope the rule to this repo's default branch, because `bkit-cloud.yml` runs from it (`workflow_run` + `workflow_dispatch`):
|
|
448
529
|
- `subject_prefix`: `repo:<owner>/<repo>:ref:refs/heads/<default-branch>`
|
|
449
530
|
- claims: `repository_owner` = `<owner>`, `ref` = `refs/heads/<default-branch>`
|
|
450
531
|
- to limit the rule to `bkit-cloud.yml`, add claim `workflow_ref` = `<owner>/<repo>/.github/workflows/bkit-cloud.yml@refs/heads/<default-branch>`. GitHub's token carries it; Anthropic's docs do not list it as matchable. Without it, every workflow on the default branch matches the rule.
|
|
@@ -454,70 +535,77 @@ Keyless claude job: no long-lived `ANTHROPIC_API_KEY` stored in GitHub. `claude-
|
|
|
454
535
|
gh variable set ANTHROPIC_ORGANIZATION_ID --body='<organization-uuid>'
|
|
455
536
|
# optional: ANTHROPIC_SERVICE_ACCOUNT_ID (svac_...), ANTHROPIC_WORKSPACE_ID
|
|
456
537
|
```
|
|
457
|
-
4. Delete the key if one is set: `gh secret delete ANTHROPIC_API_KEY`. **A set key wins over federation
|
|
538
|
+
4. Delete the key if one is set: `gh secret delete ANTHROPIC_API_KEY`. **A set key wins over federation:** the action uses the key, and federation never runs. `bkit check` flags both being set (`anthropic-api-key-shadows-federation`).
|
|
458
539
|
|
|
459
|
-
**Adopted copy predates federation:** variables set but `.github/workflows/bkit-cloud.yml` lacks the `anthropic_federation_rule_id:` input
|
|
540
|
+
**Adopted copy predates federation:** The variables are set, but `.github/workflows/bkit-cloud.yml` lacks the `anthropic_federation_rule_id:` input, so the claude job sees no credential. `bkit check` flags it (`anthropic-federation-template-stale`). Re-copy from `.bkit/templates/.github/workflows/bkit-cloud.yml`, then re-apply your local edits (`runs-on`).
|
|
460
541
|
|
|
461
|
-
**401 from token exchange:** Anthropic returns `401 Authentication failed` whichever check failed. Console → Workload identity → authentication history shows the deny reason per attempt
|
|
542
|
+
**401 from token exchange:** Anthropic returns `401 Authentication failed` whichever check failed. Console → Workload identity → authentication history shows the deny reason per attempt. `match_subject_prefix` means the run's `sub` doesn't match the rule's `subject_prefix`: fix or widen the rule. A job on a non-default branch or an `environment:` has a different subject (`...:ref:refs/heads/<branch>` / `...:environment:<name>`).
|
|
462
543
|
|
|
463
|
-
|
|
544
|
+
The slash command body is already in the checked-out repo (mirrored to `.claude/commands/bkit-auto.md` and `.opencode/commands/bkit-auto.md` at dev time by `bkit install`). Repo git / gh ops use the auto-provided `github.token`, scoped by the workflow's `permissions:` block.
|
|
464
545
|
|
|
465
546
|
## Branch-aware routing
|
|
466
547
|
|
|
467
|
-
`bkit-cloud.yml`'s `workflow_run` trigger covers `feat/**` and `dev`. `main` is never auto-routed
|
|
548
|
+
`bkit-cloud.yml`'s `workflow_run` trigger covers `feat/**` and `dev`. `main` is never auto-routed, so `dev` → `main` promotion stays manual.
|
|
468
549
|
|
|
469
550
|
<!-- prettier-ignore -->
|
|
470
551
|
| CI trigger | success | failure |
|
|
471
552
|
| --- | --- | --- |
|
|
472
|
-
| `feat/**` (pre-merge) |
|
|
473
|
-
| `dev` (post-merge) | no-op — the merge already happened |
|
|
553
|
+
| `feat/**` (pre-merge) | → `/bkit-ship` | → `/bkit-debug` |
|
|
554
|
+
| `dev` (post-merge) | no-op — the merge already happened | → `/bkit-debug {FID}` (capped) |
|
|
474
555
|
| `main` | manual only | manual only |
|
|
475
556
|
|
|
476
|
-
**Build still running (`feat/**`):**
|
|
557
|
+
**Build still running (`feat/**`):** Before dispatch, read the branch's `docs/plans/*/logs/{FID}/status.jsonl` from `origin`:
|
|
477
558
|
|
|
478
|
-
- `build` `workflow-started
|
|
479
|
-
-
|
|
480
|
-
- No file
|
|
559
|
+
- A `build` `workflow-started` row with no later `workflow-done` / `workflow-failed`, and the newest build row < 30 min old → `/bkit-build` owns the branch → no-op.
|
|
560
|
+
- The newest build row >= 30 min old → abandoned → dispatch.
|
|
561
|
+
- No file, or an unreadable one → dispatch.
|
|
481
562
|
|
|
482
|
-
The post-merge `dev` surface reuses the same free-tier gate: `/bkit-ship` threads ` bkit [auto route]` onto the PR squash-merge `--subject
|
|
563
|
+
The post-merge `dev` surface reuses the same free-tier gate. When the issue carries `bkit:auto`, `/bkit-ship` threads ` bkit [auto route]` onto the PR squash-merge `--subject`, so the commit that lands on `dev`, and triggers post-merge CI, already carries the marker the gate checks.
|
|
483
564
|
|
|
484
565
|
## Routing decision (router orchestrator)
|
|
485
566
|
|
|
486
|
-
|
|
567
|
+
The slash command takes two args: `$CI_STATUS` in `success|failure|pass|fail` (normalised), and `$ARG`, which is a PR number (pre-merge) or a `{FID}` slug (post-merge `dev`, no open PR). Then:
|
|
487
568
|
|
|
488
|
-
1. PR-number arg
|
|
489
|
-
2.
|
|
490
|
-
3. Stale-run guard. Pre-merge
|
|
491
|
-
4. Opt-in gate: refuses dispatch unless linked GitHub issue carries `bkit:auto` label.
|
|
492
|
-
5.
|
|
493
|
-
6.
|
|
569
|
+
1. With a PR-number arg, it reads `gh pr view $ARG` for `headRefName`, `headRefOid`, `state`, and refuses non-open PRs. With a slug arg, it skips the PR lookup entirely.
|
|
570
|
+
2. It extracts `{FID}` from the head branch (`feat/{FID}` convention). With a slug arg, `{ARG}` is the `{FID}`, allowlist-asserted before use. On the `dev` surface the workflow recovers it from the squash-merge commit scope (`feat({FID}): …`, tracker-agnostic), and falls back to the linked PR body's `bkit:fid=` marker. If either path fails → no-op, no dispatch.
|
|
571
|
+
3. Stale-run guard. Pre-merge, it compares the latest CI run's `headSha` against the PR's current `headRefOid`. Post-merge on `dev`, it compares the most recently completed `dev` CI run's `headSha` against the triggering run's head SHA. A `git rev-parse origin/dev` comparison would mismatch on every legitimate dispatch, because ship's terminal close commit lands on `dev` while that CI run is still going. Close commits carry `[skip ci]`, so they never trigger CI and never become that most-recent-completed head. An empty run list fails open (dispatches).
|
|
572
|
+
4. Opt-in gate: it refuses dispatch unless the linked GitHub issue carries the `bkit:auto` label.
|
|
573
|
+
5. It appends a `bkit-auto → /bkit-{ship,debug}` line to the GitHub issue / PR comment thread.
|
|
574
|
+
6. It invokes `/bkit-ship {FID}` (CI pass) or `/bkit-debug {FID} DEBUG_MODE=pr` (CI fail) through the `Skill` / `Task` tool. The dispatched skill owns the session lifecycle from there.
|
|
494
575
|
|
|
495
|
-
Skip conditions emit single GitHub-comment no-op line and exit 0
|
|
576
|
+
Skip conditions emit a single GitHub-comment no-op line and exit 0. Only real failures (missing args, GitHub API unreachable, malformed state) take the Failure Path.
|
|
496
577
|
|
|
497
578
|
## Operating notes
|
|
498
579
|
|
|
499
|
-
- **Loop bound (pre-merge `feat/**`):** `/bkit-debug` enforces `
|
|
500
|
-
- **Loop bound (`dev`):**
|
|
501
|
-
-
|
|
502
|
-
-
|
|
503
|
-
-
|
|
504
|
-
-
|
|
580
|
+
- **Loop bound (pre-merge `feat/**`):** `/bkit-debug` enforces `bkit.workflows.debug.fix` and `.soak` `maxAttempts` internally, counted across every debug run of the feature. The router never counts attempts. Once the fix attempts are used up, debug switches to soak. Once the soak attempts are used up, it takes the Failure Path (handover) and stops.
|
|
581
|
+
- **Loop bound (`dev`):** The cap is `bkit.workflows.debug.fix.maxAttempts` + `bkit.workflows.debug.soak.maxAttempts` (2 + 2 by default) distinct failed CI SHAs per `{FID}`, all-time. Every debug run makes at least one attempt, so more dispatches could never run one.
|
|
582
|
+
- The router reads both values from `package.json` with `jq`, because bkit is not installed at that point. It falls back to 2 for a missing or bad value, as the engine does.
|
|
583
|
+
- This is the surface that needs a cross-session cap. `/bkit-debug` adopts `dev` in place, so its fix push re-reds `dev` CI and re-triggers this same router.
|
|
584
|
+
- The ctx step of `bkit-cloud.yml`'s `context` job checks and writes the cap immediately before dispatch, so a run that could not record its own attempts is still bounded.
|
|
585
|
+
- The counter row (`type: "dev-dispatch"`) is committed to `dev` with `[skip ci]` before dispatch, and its presence on `origin/dev` is verified after one retry. A row that lands nowhere durable would make the cap unbounded.
|
|
586
|
+
- When the cap is used up → no-op + `::notice::` for operator review. Delete the rows in `status.jsonl` to reset it.
|
|
587
|
+
- **GitHub Actions runtime limit:** The host's job limit still applies. bkit bounds attempts and command waits, and sets no universal workflow-step deadline; the attempt count alone does not bound the job's duration.
|
|
588
|
+
- **Concurrency:** `cancel-in-progress` is `true` for `feat/**` (latest-wins) and `false` for `dev`, so an in-flight `/bkit-debug` finishes instead of being cancelled mid-run with a half-written `status.jsonl` or a held worktree lock. GHA queues at most one pending run per group. The queued run re-checks the dispatch cap when it starts, so the same `{FID}` needs no manual re-trigger. The Cursor dashboard trigger is "latest-supersedes." The ship squash-merge is atomic, so mid-run cancels cannot corrupt PR state.
|
|
589
|
+
- **`bkit-auto-dev` is one concurrency group for all FIDs.** GHA resolves `concurrency.group` from the trigger-payload context before the ctx step derives the `{FID}`, so the group cannot be keyed on it. When two different FIDs fail `dev` CI near-simultaneously, queue-collapse can drop the older, different FID's pending run. The stale-run guard detects it (its head SHA no longer matches the most-recent-completed `dev` CI run) and writes a `dev-dispatch-dropped` row to the job summary plus a `::warning::`, rather than discarding it silently. The row goes to the job summary, not a committed `status.jsonl`, because this branch is reached only when `dev` has already advanced. Committing the row would usually be a non-fast-forward, and the row would be lost in exactly the case it records.
|
|
590
|
+
- **Both clouds together:** Nothing stops Claude + Cursor from dispatching against the same PR, and they would race. Pick one IDE per repo as the auto-router. The recommendation is Claude via GHA, which is runner-resident and Anthropic-maintained. Leave Cursor for ad-hoc Linear-dispatch work.
|
|
505
591
|
|
|
506
592
|
# Caveats (both clouds)
|
|
507
593
|
|
|
508
|
-
- **No secrets store yet (Claude).** Env vars and setup-script body plaintext in Claude app. Rotate PATs regularly.
|
|
509
|
-
- **Env vars do not reach Claude setup script.** Auth at snapshot-build time
|
|
510
|
-
- **Cache invalidation is body-based (Claude).** Editing env-vars block or repo-side hook scripts doesn't trigger rebuild.
|
|
511
|
-
- **Husky runs on `pnpm install`** (repos that adopted the `.husky/*` templates). `prepare` registers git hooks during install. The pre-commit hook (`bkit:gate:format` → `lint-staged`) runs when agent commits. `slop-scan` devDep
|
|
512
|
-
- **Bun proxy issues (Claude).** Bun known proxy issues with cloud security proxy. bkit uses pnpm
|
|
513
|
-
- **Custom base image not supported (Claude).**
|
|
514
|
-
- **Cursor image cache layer-based.** Reorder `RUN` lines carefully
|
|
515
|
-
- **GitHub App vs `/web-setup` (Claude).** Auto-fix PRs require GitHub App. `/web-setup` (
|
|
516
|
-
- **IP allowlists** on org GitHub / Anthropic accounts block cloud sessions
|
|
594
|
+
- **No secrets store yet (Claude).** Env vars and the setup-script body are plaintext in the Claude app. Rotate PATs regularly.
|
|
595
|
+
- **Env vars do not reach Claude setup script.** Auth at snapshot-build time would have to be inlined, which is the leak you want to avoid. Design around it: put public binaries in the setup script, and leave auth-bearing work to the SessionStart hook.
|
|
596
|
+
- **Cache invalidation is body-based (Claude).** Editing the env-vars block or the repo-side hook scripts doesn't trigger a rebuild. To force one, run `bkit install` or `bkit upgrade`, which re-stamps the `# cache-bust` line, then paste the new setup script.
|
|
597
|
+
- **Husky runs on `pnpm install`** (repos that adopted the `.husky/*` templates). `prepare` registers git hooks during install. The pre-commit hook (`bkit:gate:format` → `lint-staged`) runs when the agent commits. The `slop-scan` devDep reaches PATH through `node_modules/.bin`. The `vale` system binary comes from the setup script (Claude) or the Dockerfile (Cursor).
|
|
598
|
+
- **Bun proxy issues (Claude).** Bun has known proxy issues with the cloud security proxy. bkit uses pnpm, so it is unaffected. Flag this for bun consumers.
|
|
599
|
+
- **Custom base image not supported (Claude).** The escape hatch is `docker compose` sidecars. The bkit stack does not need it today.
|
|
600
|
+
- **Cursor image cache layer-based.** Reorder `RUN` lines carefully, because a frequently-changing line above a slow one invalidates the cache below it.
|
|
601
|
+
- **GitHub App vs `/web-setup` (Claude).** Auto-fix PRs require the GitHub App. `/web-setup` (syncs the `gh` token to the Claude account) is enough for clone + push, but not for auto-fix.
|
|
602
|
+
- **IP allowlists** on org GitHub / Anthropic accounts block cloud sessions. Contact support to exempt managed infra.
|
|
603
|
+
- **Hooks unproven (Codex Cloud).** Cloud tasks have no documented hook support, so there is no GateGuard / guardrails guarantee there (§ Codex Cloud → Hooks in cloud tasks).
|
|
517
604
|
|
|
518
605
|
# Sources
|
|
519
606
|
|
|
520
607
|
- Anthropic docs: <https://code.claude.com/docs/en/claude-code-on-the-web>
|
|
608
|
+
- Codex Cloud environments: <https://learn.chatgpt.com/docs/environments/cloud-environments>
|
|
521
609
|
- Cursor Cloud Agents: <https://cursor.com/docs/cloud-agent/setup>
|
|
522
|
-
- Zenn article on Claude env-var/setup-script gotcha: <https://zenn.dev/harieshokunin/articles/b1064354319ce2?locale=en>
|
|
610
|
+
- Zenn article on Claude env-var / setup-script gotcha: <https://zenn.dev/harieshokunin/articles/b1064354319ce2?locale=en>
|
|
523
611
|
- Managed Agents environments (separate product, similar shape): <https://platform.claude.com/docs/en/managed-agents/environments>
|