@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
|
@@ -2,23 +2,30 @@
|
|
|
2
2
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> [!CAUTION]
|
|
6
|
+
> **Purpose:** This file covers first-time install and upgrade, the install lifecycle, uninstall and recovery. It ships in the package at `node_modules/@cbartens/bkit/.bkit/core/.bkit/install.md` and is mirrored into the consumer repo at `.bkit/install.md`. Ongoing ops and triggering workflows are in `.bkit/README.md`.
|
|
7
|
+
>
|
|
8
|
+
> **Rules:**
|
|
9
|
+
>
|
|
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`.
|
|
6
13
|
|
|
7
14
|
> [!IMPORTANT]
|
|
8
|
-
> **bkit installs from npmjs.** `@cbartens/bkit` is public on `https://registry.npmjs.org
|
|
15
|
+
> **bkit installs from npmjs.** `@cbartens/bkit` is public on `https://registry.npmjs.org`, so `pnpm add -D @cbartens/bkit` resolves with no registry mapping, PAT, or CI / Vercel env.
|
|
9
16
|
|
|
10
17
|
## Quick install / upgrade — paste into your AI
|
|
11
18
|
|
|
12
|
-
|
|
19
|
+
There are two paste blocks below: install (first time) and upgrade (already on bkit). Both end the same way: apply advisories, reconcile templates, and verify with `bkit check`.
|
|
13
20
|
|
|
14
21
|
### Install — first time
|
|
15
22
|
|
|
16
|
-
No token or registry setup is needed
|
|
23
|
+
No token or registry setup is needed, because `@cbartens/bkit` is public on npmjs. Copy the block below into Claude / Codex / Antigravity / Cursor / OpenCode.
|
|
17
24
|
|
|
18
25
|
````text
|
|
19
26
|
Install the latest `@cbartens/bkit` in this repo and finish setup.
|
|
20
27
|
1. `@cbartens/bkit` is public on npmjs — no registry mapping, no PAT, no env. Confirmed.
|
|
21
|
-
2. Install and seed hosts in one Bash call (`bkit install` requires named modules — core implicit; pick the hosts this repo uses from `--claude --
|
|
28
|
+
2. Install and seed hosts in one Bash call (`bkit install` requires named modules — core implicit; pick the hosts this repo uses from `--claude --codex --antigravity --cursor --opencode=<provider>`, provider = `openrouter` | `ollama` | `opencode-zen` | `opencode-go`; if `bkit` not on PATH use `pnpm bkit`):
|
|
22
29
|
```bash
|
|
23
30
|
pnpm add -D @cbartens/bkit@latest && \
|
|
24
31
|
bkit install --claude --cursor
|
|
@@ -26,12 +33,13 @@ Install the latest `@cbartens/bkit` in this repo and finish setup.
|
|
|
26
33
|
Writes `.agents/`, `.claude/`, `.cursor/` and the `bkit:gate:*` `package.json` scripts, and copies the templates (CI workflow, hooks, tool configs) into `.bkit/templates/` without applying them. `.bkit/templates.md` lists each template plus the tool scripts and devDeps the gates chain.
|
|
27
34
|
3. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why. Then § Setup tips: follow each tip's **Agent steps** unless the person declines it.
|
|
28
35
|
4. Read `.bkit/templates.md`, then compare each template in `.bkit/templates/` (CI workflows, git hooks, lint and Vale configs, Cursor config, dependency updaters, etc.) with this repo. bkit never applies templates, so adoption is your job: adopt unless adoption would break existing functionality. For any template not adopted, state which and why.
|
|
29
|
-
5.
|
|
36
|
+
5. Reconcile every permanent skill through `.agents/skills.md` § Install / Update, including the project's own rows. Verify each skill file and installer-generated lock entry, and review its activation boundaries.
|
|
37
|
+
6. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons), skills reconciled or incomplete (with errors).
|
|
30
38
|
````
|
|
31
39
|
|
|
32
40
|
### Upgrade — already installed
|
|
33
41
|
|
|
34
|
-
|
|
42
|
+
Copy this block when the repo already has `@cbartens/bkit`. Prefer `bkit upgrade --latest`, which bumps the package and resyncs the managed files. Do not run only `pnpm add`.
|
|
35
43
|
|
|
36
44
|
````text
|
|
37
45
|
Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
|
|
@@ -42,12 +50,13 @@ Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resyn
|
|
|
42
50
|
Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
|
|
43
51
|
2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why. Then § Setup tips: follow each tip's **Agent steps** unless the person declines it.
|
|
44
52
|
3. Read the template changes `bkit upgrade` printed (or `git diff .bkit/templates`), then `.bkit/templates.md`. bkit never applies templates, so adoption is your job: adopt each change unless it would break existing functionality. For any change not adopted, state which and why.
|
|
45
|
-
4.
|
|
53
|
+
4. Reconcile every permanent skill through `.agents/skills.md` § Install / Update, including the project's own rows. Verify each skill file and installer-generated lock entry, and review its activation boundaries.
|
|
54
|
+
5. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons), skills reconciled or incomplete (with errors).
|
|
46
55
|
````
|
|
47
56
|
|
|
48
57
|
## Install
|
|
49
58
|
|
|
50
|
-
bkit is published publicly on
|
|
59
|
+
bkit is published publicly on npmjs (`https://registry.npmjs.org`). Add it to a consumer repo:
|
|
51
60
|
|
|
52
61
|
```bash
|
|
53
62
|
pnpm add -D @cbartens/bkit
|
|
@@ -62,14 +71,15 @@ Run these in order on a brand-new consumer repo.
|
|
|
62
71
|
| --- | --- | --- |
|
|
63
72
|
| 1 | `pnpm add -D @cbartens/bkit` — no token, no registry mapping | this section |
|
|
64
73
|
| 2 | Run `bkit install --claude --cursor` to seed both hosts (writes `.bkit/.env.example`; `.envrc` is a template in `.bkit/templates/`) | this section |
|
|
65
|
-
| 3 | Set up direnv + `.bkit/.env` for `BKIT_GH_TOKEN` (GitHub MCP), `BKIT_LINEAR_API_KEY` or `
|
|
66
|
-
| 4 |
|
|
74
|
+
| 3 | Set up direnv + `.bkit/.env` for `BKIT_GH_TOKEN` (GitHub MCP), `BKIT_LINEAR_API_KEY` or `BKIT_JIRA_API_KEY` — no registry token | [§ Local env setup](#local-env-setup) |
|
|
75
|
+
| 4 | Reconcile permanent third-party skills and their lock entries | `.agents/skills.md` § Install / Update |
|
|
76
|
+
| 5 | Push to a feature branch and verify CI runs green | — |
|
|
67
77
|
|
|
68
|
-
No CI step, secret, `.npmrc` mapping or Vercel env is needed
|
|
78
|
+
No CI step, secret, `.npmrc` mapping or Vercel env is needed, because CI reaches npmjs anonymously.
|
|
69
79
|
|
|
70
80
|
### Then in the consumer repo
|
|
71
81
|
|
|
72
|
-
`bkit install` requires you to name
|
|
82
|
+
`bkit install` requires you to name at least one module, and a bare `bkit install` errors. Core (the stack-agnostic foundation) is always implicit. Re-run it, or run `bkit upgrade`, after package updates. Use `bkit check` as the CI drift gate.
|
|
73
83
|
|
|
74
84
|
> **Shell alias (add once to `~/.zshrc` or `~/.bashrc`, then `source ~/.zshrc`)**
|
|
75
85
|
>
|
|
@@ -77,19 +87,19 @@ No CI step, secret, `.npmrc` mapping or Vercel env is needed — CI reaches npmj
|
|
|
77
87
|
> alias bkit='pnpm bkit'
|
|
78
88
|
> ```
|
|
79
89
|
>
|
|
80
|
-
> Type `bkit <verb>` from anywhere in repo. Without alias, prefix with `pnpm`: `pnpm bkit install --claude`. `bkit doctor` emits advisory if
|
|
90
|
+
> Type `bkit <verb>` from anywhere in the repo. Without the alias, prefix with `pnpm`: `pnpm bkit install --claude`. `bkit doctor` emits an advisory if it does not detect the alias.
|
|
81
91
|
|
|
82
92
|
```bash
|
|
83
93
|
# Name the host(s) + stack you want — core is implicit. Hosts compose.
|
|
84
94
|
bkit install --claude # .claude/** + CLAUDE.md + core
|
|
85
|
-
bkit install --cursor # .cursor/** + core
|
|
86
95
|
bkit install --codex # Codex CLI host + core
|
|
87
|
-
bkit install --antigravity #
|
|
88
|
-
bkit install --
|
|
89
|
-
|
|
96
|
+
bkit install --antigravity # Antigravity host + core
|
|
97
|
+
bkit install --cursor # .cursor/** + core
|
|
98
|
+
bkit install --opencode=opencode-go # additive OpenCode host (OpenCode-native gateway) + core
|
|
99
|
+
# OpenCode provider: openrouter | ollama | opencode-zen | opencode-go
|
|
90
100
|
|
|
91
101
|
# A bare install errors — name at least one module, or a tracker:
|
|
92
|
-
bkit install # ✗ error: requires
|
|
102
|
+
bkit install # ✗ error: requires >=1 module flag
|
|
93
103
|
bkit install --tracker=github # tracker alone: re-renders every installed host
|
|
94
104
|
|
|
95
105
|
# Ongoing sync — re-render everything installed at the CURRENT version (offline)
|
|
@@ -102,24 +112,27 @@ bkit upgrade --latest # newest published; or --to=<version> t
|
|
|
102
112
|
bkit check
|
|
103
113
|
```
|
|
104
114
|
|
|
105
|
-
**Module flags** (composable;
|
|
115
|
+
**Module flags** (composable; install and uninstall are symmetric): `--claude` `--codex` `--antigravity` `--cursor` `--opencode=<provider>`. Any other module flag is an unknown-flag error.
|
|
116
|
+
|
|
117
|
+
- The CI workflow, the Vale config, the tool configs, the git hooks, the slop-scan type-suppression plugin (`scripts/slop/bkit-slop-type-suppression.mjs`), and the tool `package.json` scripts and devDeps are templates you copy from `.bkit/templates/` (`.bkit/templates.md`).
|
|
118
|
+
- Core, implicit on every install, seeds the `bkit:gate:*` / `bkit:deps:*` scripts every workflow runs. It adds them only if missing, and never touches a name that is already present. Point their values at your stack (see `.bkit/README.md` § Required tools).
|
|
106
119
|
|
|
107
|
-
**Opt-in flags:** `--tracker=github|linear|jira`, `--auto=claude|cursor|opencode` (cloud agents), `--opencode=<provider>` (additive
|
|
120
|
+
**Opt-in flags:** `--tracker=github|linear|jira`, `--auto=claude|cursor|opencode` (cloud agents), `--opencode=<provider>` (additive OpenCode execution host: `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). For dependency updaters, copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
|
|
108
121
|
|
|
109
122
|
### Payload view links — `.bkit/core` + `.bkit/shared`
|
|
110
123
|
|
|
111
|
-
Install and upgrade create two
|
|
124
|
+
Install and upgrade create two relative symlinks into the installed package, so the payload sources (workflows, prompts, hooks) can be browsed in the repo: `.bkit/core` → `../node_modules/@cbartens/bkit/.bkit/core`, and the same shape for `shared`. They are views, not copies, so they always show the installed version with zero drift. Rules:
|
|
112
125
|
|
|
113
|
-
- Both paths sit in the `.gitignore` managed block
|
|
114
|
-
- The `bkit` binary reads its payload from the package regardless
|
|
115
|
-
- A real directory at either path is never clobbered (advisory `payload-link-real-dir`)
|
|
116
|
-
- `bkit uninstall` removes the links
|
|
126
|
+
- Both paths sit in the `.gitignore` managed block. They dangle on a fresh clone or in CI (no `node_modules`), and `bkit install` / `upgrade` recreates them. A missing or mis-pointed link is never `bkit check` drift, because links join no WriteSet.
|
|
127
|
+
- The `bkit` binary reads its payload from the package regardless, so the links are browse-only. Editors resolve them to the `node_modules/…` paths.
|
|
128
|
+
- A real directory at either path is never clobbered (advisory `payload-link-real-dir`). Remove it yourself and re-run install to get the link. A platform that refuses symlinks (Windows without Developer Mode) falls back to a junction, then to advisory `payload-link-failed`, and never fails.
|
|
129
|
+
- `bkit uninstall` removes the links. It removes symlinks only, and consumer content stays.
|
|
117
130
|
|
|
118
|
-
>
|
|
131
|
+
> **Moving bkit versions: use `bkit upgrade --latest` (or `--to=<version>`).** It bumps `@cbartens/bkit` and resyncs the `.agents/` payload + `.bkit/version` pin in one atomic step, so the two can never drift apart. A bare `pnpm add @cbartens/bkit` (or a Renovate / Dependabot bump) only refreshes `package.json` + the lockfile and does not resync. Skipping the resync reds CI on the `bkit check` drift gate. If you bump the package separately, run `bkit upgrade` afterward and commit the resync alongside the version bump in the same PR. A target equal to the installed version re-renders in place. The exception is when `package.json` declares `@cbartens/bkit` by a non-registry spec (`file:` tarball, `link:`, `workspace:`, `npm:` alias, git, URL, path): then it still runs `pnpm add` to swap in the published package.
|
|
119
132
|
|
|
120
133
|
### Local env setup
|
|
121
134
|
|
|
122
|
-
|
|
135
|
+
There are two flows. Pick one. Both put `BKIT_GH_TOKEN` in the shell for the GitHub MCP server. Linear repos also need `BKIT_LINEAR_API_KEY`, and Jira repos need `BKIT_JIRA_API_KEY` (`.bkit/trackers.md` § jira — setup and notes). Use `gh auth login` for the CLI.
|
|
123
136
|
|
|
124
137
|
#### Flow A — Shell export (quickest, no extra deps)
|
|
125
138
|
|
|
@@ -127,17 +140,17 @@ Two flows — pick one. Both put `BKIT_GH_TOKEN` in shell for the GitHub MCP ser
|
|
|
127
140
|
# Add to ~/.zshrc (or ~/.bashrc)
|
|
128
141
|
export BKIT_GH_TOKEN=<PAT — fine-grained (one owner) or classic (multiple owners)> # GitHub MCP
|
|
129
142
|
export BKIT_LINEAR_API_KEY=<Linear personal API key> # Linear MCP + preflight
|
|
130
|
-
export
|
|
143
|
+
export BKIT_JIRA_API_KEY=<Atlassian MCP V2 scoped token> # Jira MCP
|
|
131
144
|
|
|
132
145
|
# Reload
|
|
133
146
|
source ~/.zshrc # or: source ~/.bashrc
|
|
134
147
|
```
|
|
135
148
|
|
|
136
|
-
Pros: one step, no install. Cons: tokens in every shell on machine
|
|
149
|
+
Pros: one step, no install. Cons: the tokens are in every shell on the machine, with no per-repo scoping.
|
|
137
150
|
|
|
138
151
|
#### Flow B — direnv + `.bkit/.env` (recommended for daily use)
|
|
139
152
|
|
|
140
|
-
`bkit install` writes `.bkit/.env.example` (placeholders + permission notes
|
|
153
|
+
`bkit install` writes `.bkit/.env.example` (placeholders + permission notes). bkit owns that file and overwrites edits, so real values go in `.bkit/.env`. `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy it from `.bkit/templates/.envrc`. direnv loads `.bkit/.env` on `cd` and unloads it when you leave, so the tokens are scoped to the repo.
|
|
141
154
|
|
|
142
155
|
```bash
|
|
143
156
|
# 1. One-time per machine — install direnv
|
|
@@ -151,7 +164,7 @@ echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc
|
|
|
151
164
|
# 3. One-time per consumer repo (after `bkit install`)
|
|
152
165
|
cp .bkit/templates/.envrc .envrc # unless you already have one
|
|
153
166
|
cp .bkit/.env.example .bkit/.env
|
|
154
|
-
# Edit .bkit/.env: set BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY or
|
|
167
|
+
# Edit .bkit/.env: set BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY or BKIT_JIRA_API_KEY
|
|
155
168
|
direnv allow # trust the .envrc
|
|
156
169
|
|
|
157
170
|
# 4. Verify
|
|
@@ -159,21 +172,34 @@ echo "len=${#BKIT_GH_TOKEN}" # non-ze
|
|
|
159
172
|
gh auth status # gh CLI uses keyring, not BKIT_GH_TOKEN
|
|
160
173
|
```
|
|
161
174
|
|
|
162
|
-
After step 4, restart open Claude
|
|
175
|
+
After step 4, restart any open Claude / Cursor sessions in this repo, so the new env reaches the MCP servers.
|
|
163
176
|
|
|
164
|
-
`.bkit/.env` gitignored
|
|
177
|
+
`.bkit/.env` is gitignored. NEVER commit it. For cloud sessions (Claude on the web, Cursor Background Agents), set the same names in each host's online dashboard (see `.bkit/cloud.md` § Tokens by session type). `bkit install` / `bkit check` advisories detect a missing direnv, blank required keys and an un-allowed `.envrc`. Follow whichever fires.
|
|
165
178
|
|
|
166
|
-
## Cloud agent environments (Claude
|
|
179
|
+
## Cloud agent environments (Claude on the web + Cursor Background Agents)
|
|
167
180
|
|
|
168
|
-
bkit ships repo-side scaffolding for both cloud agents
|
|
181
|
+
bkit ships repo-side scaffolding for both cloud agents:
|
|
169
182
|
|
|
170
|
-
|
|
183
|
+
- The opt-in `bkit install --auto=claude` writes no file.
|
|
184
|
+
- The per-session install hook (`.claude/hooks/bkit-cloud-bootstrap.sh`), the phase-routed `.github/workflows/bkit-cloud.yml` and the Cursor cloud image files (`.cursor/Dockerfile`, `.cursor/environment.json`) are templates in `.bkit/templates/` that you copy and own.
|
|
185
|
+
- `.cursor/hooks.json` (the Linear preflight wiring) ships with `--cursor`, not `--auto`.
|
|
186
|
+
- An install without `--auto` ships zero cloud footprint.
|
|
171
187
|
|
|
172
|
-
|
|
188
|
+
You configure the online-dashboard half (the Claude env in `claude.ai/code`, the Cursor env vars in `Cursor → Settings → Background Agents`) once per machine / account.
|
|
189
|
+
|
|
190
|
+
For post-CI auto-routing (ship-vs-debug after CI), bkit ships a single `.github/workflows/bkit-cloud.yml` template with two runtime-gated dispatch jobs, plus a `/bkit-auto` slash command that both clouds invoke from a single source:
|
|
191
|
+
|
|
192
|
+
- The **claude** job (`claude-code-action`) runs when the `ANTHROPIC_API_KEY` repo secret is set, or keyless through the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables.
|
|
193
|
+
- The **OpenCode** job (`opencode run` CLI) runs when `OPENCODE_PROVIDER_KEY` is set.
|
|
194
|
+
- Cursor wires the slash command through a dashboard trigger, with no GHA on the Cursor side.
|
|
195
|
+
|
|
196
|
+
`bkit install --auto=opencode` requires `tracker=github`.
|
|
197
|
+
|
|
198
|
+
`.bkit/cloud.md` holds the full recipe, the paste-in setup script, the env-var inventory, the Cursor dashboard config and the consumer customisation patterns. The host-delta matrix is in `.bkit/providers.md` § Runtime environment.
|
|
173
199
|
|
|
174
200
|
## JSON ownership model — deep-containment
|
|
175
201
|
|
|
176
|
-
`.claude/settings.json` and `.cursor/hooks.json` managed
|
|
202
|
+
`.claude/settings.json` and `.cursor/hooks.json` are managed through **deep-containment**: bkit declares a scope (the full template JSON tree) that must be present as a subset of the consumer's document. Consumer-added keys outside the template tree survive every `bkit install` byte-identically, with no special key or wrapper required.
|
|
177
203
|
|
|
178
204
|
```json
|
|
179
205
|
// .claude/settings.json
|
|
@@ -188,13 +214,13 @@ Full recipe + paste-in setup script + env-var inventory + Cursor dashboard confi
|
|
|
188
214
|
}
|
|
189
215
|
```
|
|
190
216
|
|
|
191
|
-
In this example, `hooks.SessionStart` is bkit-declared scope (from template). `hooks.Stop` and `failClosed` are consumer-added
|
|
217
|
+
In this example, `hooks.SessionStart` is bkit-declared scope (from the template). `hooks.Stop` and `failClosed` are consumer-added, and bkit never touches them.
|
|
192
218
|
|
|
193
219
|
**Rules:**
|
|
194
220
|
|
|
195
|
-
- Consumer keys outside template tree survive every `bkit install` byte-identically.
|
|
196
|
-
- `bkit install` uses `deepContains(template, consumer)
|
|
197
|
-
- `bkit check` surfaces `tier2-json-drift` advisory when `deepContains` fails and
|
|
221
|
+
- Consumer keys outside the template tree survive every `bkit install` byte-identically.
|
|
222
|
+
- `bkit install` uses `deepContains(template, consumer)`, which checks that every template leaf is present. On drift, it deep-merges with the template winning, and consumer-only siblings are preserved.
|
|
223
|
+
- `bkit check` surfaces the `tier2-json-drift` advisory when `deepContains` fails, and exits 1 (CI drift gate). It writes nothing. The consumer reviews and re-runs `bkit install` to reconverge.
|
|
198
224
|
- `.cursor/hooks.json` uses Cursor v1 keyed-object schema: `{"version": 1, "hooks": {"sessionStart": [...], "sessionStop": [...]}}`.
|
|
199
225
|
|
|
200
226
|
## Install lifecycle
|
|
@@ -203,7 +229,7 @@ In this example, `hooks.SessionStart` is bkit-declared scope (from template). `h
|
|
|
203
229
|
|
|
204
230
|
**Phase 1 — Preflight (read-only, before any writes)**
|
|
205
231
|
|
|
206
|
-
bkit checks preconditions and known advisory patterns before touching any file.
|
|
232
|
+
bkit checks preconditions and known advisory patterns before touching any file. When a blocker fires, install exits 1 immediately with a formatted `[blocker]` line and zero writes. Advisories are collected for Phase 3.
|
|
207
233
|
|
|
208
234
|
<!-- prettier-ignore -->
|
|
209
235
|
| Severity | When |
|
|
@@ -219,34 +245,60 @@ Module dispatch writes managed files.
|
|
|
219
245
|
|
|
220
246
|
**Phase 3 — Post-install (re-detect + unified output)**
|
|
221
247
|
|
|
222
|
-
After writes, bkit re-runs credential and environment checks
|
|
248
|
+
After the writes, bkit re-runs the credential and environment checks, because some are only accurate after install (for example the `bkit:gate:*` scripts core just seeded into `package.json`). The table also lists the module advisories that render in the same checklist.
|
|
223
249
|
|
|
224
250
|
<!-- prettier-ignore -->
|
|
225
251
|
| `id` | When |
|
|
226
252
|
| --- | --- |
|
|
227
253
|
| `bkit-managed-duplicate` | A managed markdown file holds an older unmarked copy of its block outside `bkit:start`/`bkit:end`: the block's `# ` title plus 10+ of its long lines verbatim, fenced code ignored. Install never updates that copy. Names each file and title line; delete the copy. |
|
|
228
|
-
| `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset/empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
|
|
229
|
-
| `tracker-setup-none` / `-github` / `-linear` / `-jira` | Optional post-install decision — which issue tracker is wired (`bkit.
|
|
230
|
-
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.github.project` absent or not a board URL, and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.github.project: false`. |
|
|
231
|
-
| `
|
|
254
|
+
| `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset / empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
|
|
255
|
+
| `tracker-setup-none` / `-github` / `-linear` / `-jira` | Optional post-install decision — which issue tracker is wired (`bkit.tracker.default`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
256
|
+
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.tracker.github.project` empty, absent or not a board URL, and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.tracker.github.project: false`. |
|
|
257
|
+
| `github-project-token-scope` | A board is configured but `BKIT_GH_TOKEN` cannot reach it: a classic token lacks the `project` scope, or a fine-grained token's board query returns nothing. Board moves fall back to the MCP. Checked live via `gh`; skipped on cloud / CI. |
|
|
258
|
+
| `dep-updater-absent` | No Renovate or Dependabot config. Copy one example and own it. `bkit.dependencies.updater: "none"` silences this. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
232
259
|
| `dep-updater-both` | Both updater configs are present. Keep one. |
|
|
233
|
-
| `
|
|
260
|
+
| `dep-updater-unset` | Blocker. One updater's config is present but `bkit.dependencies.updater` does not name it (empty or unrecognised). Set it, or run `bkit upgrade`, which fills an empty value. |
|
|
261
|
+
| `dep-updater-mismatch` | Blocker. `bkit.dependencies.updater` names one updater (or `none`) while the other's config is present, or names an updater with no config. Fix the value or the config. |
|
|
262
|
+
| `cloud-router-none` / `cloud-router` | Optional post-install decision — post-CI auto-routing (`bkit.cloud.agent`). `none` (undecided) nudges `bkit install --auto=<variant>`, except under the jira tracker (local runs only); `cloud-router` is informational once `bkit-cloud.yml` is present. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
234
263
|
| `actions-write-permissions-missing` | `bkit-cloud.yml` present but repo Actions permissions are read-only / PR creation disabled — `actions/checkout` + `gh pr create` 403. Repo-level check; org policy can override. |
|
|
235
|
-
| `opencode-setup` |
|
|
264
|
+
| `opencode-setup` | OpenCode host installed (`--opencode=<provider>`) — names the provider key to set (e.g. `BKIT_OPENROUTER_API_KEY`; `BKIT_OPENCODE_API_KEY` for `opencode-zen` / `opencode-go`), confirms the pre-seeded base URL, and notes all four providers ship curated per-agent pins (re-pin via `.bkit/prompts.md` § Model Overrides). Verify with `bkit doctor` + `bkit status`. |
|
|
265
|
+
| `vale-not-installed` | `bkit:lint:prose` runs `bkit ci prose` but vale is not on PATH, so the prose gate fails |
|
|
236
266
|
| `vale-package-not-synced` | vale on PATH but `.vale/styles/write-good/` absent |
|
|
237
267
|
| `gate-missing-called-scripts` | A `bkit:gate:*` script still at bkit's default chains a script `package.json` does not declare (e.g. `typecheck`, `format:check`, `test`). Add it (`.bkit/templates.md` lists the tool scripts and devDeps) or rewrite the gate. |
|
|
238
|
-
| `gate-commit-repeats-push` | `bkit:gate:format` (pre-commit) runs a script the push gate runs again (e.g. `lint:prose`), so it runs on every commit and again on the push. Drop it from `bkit:gate:format`. |
|
|
268
|
+
| `gate-commit-repeats-push` | `bkit:gate:format` (pre-commit) runs a script the push gate runs again (e.g. `bkit:lint:prose`), so it runs on every commit and again on the push. Drop it from `bkit:gate:format`. |
|
|
239
269
|
| `gate-noop` | A `bkit:gate:*` script is empty or cannot fail (`true`, `:`, `exit 0`, `echo …`), so every agent run and push passes it. Warn-only, at install, `bkit check` and `bkit upgrade`, on every branch. Point it at real checks, or delete it and run `bkit upgrade` to restore bkit's default. |
|
|
240
270
|
| `gate-tier-not-wired` | `package.json` declares a deeper test tier (`test:integration`, `test:e2e`, `test:live`) that no `bkit:gate:*` script runs; the advisory prints the gate line to add. |
|
|
241
271
|
| `test-file-script-missing` | `package.json` does not declare `bkit:test:file`, so `/bkit-build` reports test-first as not enforced. The advisory prints the script contract and a Vitest line. |
|
|
272
|
+
| `lint-file-script-missing` | `package.json` declares `bkit:test:file` but not `bkit:lint:file`, so `bkit tests red` records a group's reds before the linter sees the tests, and a lint fix after it changes a frozen test file, which the code step's `steps finish` refuses. The advisory prints the script contract and ESLint / Ruff lines. |
|
|
273
|
+
| `gate-changed-script-missing` | `package.json` does not declare `bkit:gate:changed`, so build and debug agents run a whole gate after every change instead of checking only the changed files. The advisory prints the script contract and a Vitest + ESLint line. Silence it with `bkit.advisories.ignore`. |
|
|
274
|
+
|
|
275
|
+
Every `gate-*` advisory ends with what a gate may run, which bkit cannot check: no test that needs a deployed boundary or remote service outside the two `…-e2e` gates (`.bkit/workflows.md` § Local gate scripts).
|
|
242
276
|
|
|
243
|
-
Phase 1 and Phase 3 findings merged and deduplicated by `id
|
|
277
|
+
Phase 1 and Phase 3 findings are merged and deduplicated by `id`. Phase 3 wins on conflict, because re-detection is more accurate after the writes. Zero findings → no banner.
|
|
244
278
|
|
|
245
|
-
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only)
|
|
279
|
+
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only): the same advisory set as `bkit install`, minus the writes. It changes no managed file (it regenerates the `.bkit/advisories.md` artifact), and it exits 1 when any managed-file write would occur in an installed module:
|
|
246
280
|
|
|
247
|
-
|
|
281
|
+
- Tier-2 JSON deep-containment or markered-block drift.
|
|
282
|
+
- A whole-file byte-equal mismatch.
|
|
283
|
+
- Host agent / command mirror content drift (would-write / orphan delete).
|
|
284
|
+
- Any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carrying a stale managed-version marker (`bkit-managed-stale`).
|
|
285
|
+
- A missing `bkit:gate:*` name, which counts as a write.
|
|
248
286
|
|
|
249
|
-
|
|
287
|
+
The gate covers the installed module set ({core, claude, cursor, codex, antigravity} plus OpenCode). Each module is detected by sentinel files: for a host, its `agents/` dir, and for antigravity, any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host. `bkit status` uses the same detection.
|
|
288
|
+
|
|
289
|
+
- **antigravity gated:** `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and the root `GEMINI.md`.
|
|
290
|
+
- **OpenCode gated:** Drift in `.opencode/opencode.json` (the provider block + the recorded tracker's `mcp` entry + the permission sandbox) and in the `bkit-gateguard.js` / `bkit-readguard.js` / `bkit-rules.js` plugins fails `check`.
|
|
291
|
+
- Another tracker's `mcp` entry that the consumer edited, kept by a tracker switch, is not drift. `mcp-extra-server-linear--opencode-opencode-json` advises removing it.
|
|
292
|
+
- Render inputs fall back to the installed provider (`package.json` `bkit.providers.opencode.default`, authoritative for `opencode-zen` / `opencode-go`; all installed providers are tracked in `bkit.providers.opencode.installed: string[]`) and the recorded tracker, so a clean install across providers checks green, with no false drift.
|
|
293
|
+
- The remaining opt-in module (cloud) is not drift-gated.
|
|
294
|
+
|
|
295
|
+
A missing bkit-owned hook file also fails `check`, with one line per file naming it and the `bkit install` flag that restores it. This covers the hook files of every installed host (`.claude/hooks/*`, `.cursor/hooks/*`, `.codex/hooks/*`, `.agents/plugins/bkit/hooks/*`, `.opencode/plugin/bkit-gateguard.js`, `.opencode/plugin/bkit-readguard.js`, `.opencode/plugin/bkit-rules.js`). The hook commands skip a missing file (`test -f … || true`), so without this check the guard would be off with no signal.
|
|
296
|
+
|
|
297
|
+
Updater configs are not bkit files, so `bkit check` does not report them. Phase 3 stays read-only through read-only detector paths, not by being skipped.
|
|
298
|
+
|
|
299
|
+
**`bkit upgrade`** (not `--dry-run`) ends with the same read-only pass as `bkit check`: it prints the checklist and rewrites `.bkit/advisories.md` (`Mode: upgrade`). It only reports the drift and blockers it finds, and upgrade's exit code is unchanged.
|
|
300
|
+
|
|
301
|
+
**`PreflightFinding` shape** — a stable contract for downstream tooling:
|
|
250
302
|
|
|
251
303
|
```typescript
|
|
252
304
|
interface PreflightFinding {
|
|
@@ -257,14 +309,14 @@ interface PreflightFinding {
|
|
|
257
309
|
}
|
|
258
310
|
```
|
|
259
311
|
|
|
260
|
-
Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` lines. The console banner and the `.bkit/advisories.md` artifact render the same text
|
|
312
|
+
Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` lines. The console banner and the `.bkit/advisories.md` artifact render the same text, so copy either into a coding assistant to apply the fixes in sequence. After the findings, both list every firing setup tip (§ Setup tips).
|
|
261
313
|
|
|
262
|
-
**Dismissing an advisory (per package).** A detector can be right in general and still fire where the condition is deliberately not applicable
|
|
314
|
+
**Dismissing an advisory (per package).** A detector can be right in general and still fire where the condition is deliberately not applicable, such as a rule-linter whose test titles mention `@live`, or an integration lane mocked by design. Opt the owning package out in its `package.json`:
|
|
263
315
|
|
|
264
316
|
```json
|
|
265
317
|
{
|
|
266
318
|
"bkit": {
|
|
267
|
-
"
|
|
319
|
+
"advisories": { "ignore": ["tagged-tests-no-ci-home"] }
|
|
268
320
|
}
|
|
269
321
|
}
|
|
270
322
|
```
|
|
@@ -272,20 +324,20 @@ Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` line
|
|
|
272
324
|
<!-- prettier-ignore -->
|
|
273
325
|
| Rule | Behaviour |
|
|
274
326
|
| --- | --- |
|
|
275
|
-
| Scope | Per package, read from the
|
|
327
|
+
| Scope | Per package, read from the owning package's `package.json` — the package holding the test file for `tagged-tests-no-ci-home`, the repo root for `test-integration-env-not-asserted` (the only manifest it reads). A sibling package with a real finding stays flagged. |
|
|
276
328
|
| Severity | Advisory only. A `blocker` is never suppressible, whatever the manifest says. |
|
|
277
329
|
| Visibility | The console banner and `.bkit/advisories.md` carry one suppressed-advisory line per dismissal (`N advisory` / `N advisories`), so a stale opt-out cannot hide a finding silently. |
|
|
278
330
|
| Coverage | Per package: `tagged-tests-no-ci-home` and `test-integration-env-not-asserted`. Repo root: every setup tip id and every advisory a tip reuses (§ Setup tips). No other advisory is suppressible; an id matching no advisory or tip is ignored. |
|
|
279
331
|
|
|
280
332
|
## Optional post-install decisions
|
|
281
333
|
|
|
282
|
-
Two capabilities
|
|
334
|
+
Two capabilities are opt-in, and a plain host / tooling install never wires them. The default install never enables them, and the post-install advisory banner nudges you to choose, once. Each choice is recorded in `package.json` (`bkit.tracker.default`, `bkit.cloud.agent`), so the nudge knows whether you've decided or deliberately opted out.
|
|
283
335
|
|
|
284
336
|
<!-- prettier-ignore -->
|
|
285
337
|
| Decision | Default | Opt-in command | Advisory when unset |
|
|
286
338
|
| --- | --- | --- | --- |
|
|
287
|
-
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (`BKIT_GH_TOKEN`) `--tracker=linear` (`BKIT_LINEAR_API_KEY`) or `--tracker=jira` (`
|
|
288
|
-
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude +
|
|
339
|
+
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (`BKIT_GH_TOKEN`) `--tracker=linear` (`BKIT_LINEAR_API_KEY`) or `--tracker=jira` (`BKIT_JIRA_API_KEY` + `bkit.tracker.jira.site` / `bkit.tracker.jira.project`) | `tracker-setup-none` |
|
|
340
|
+
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude + OpenCode jobs, secret-gated) and the Cursor Dockerfile/environment.json | `cloud-router-none` |
|
|
289
341
|
|
|
290
342
|
**Dependency updater.** Copy one example and own it.
|
|
291
343
|
|
|
@@ -296,28 +348,38 @@ Two capabilities **opt-in** — never wired by plain host/tooling install. Defau
|
|
|
296
348
|
| Renovate self-hosted runner | `.bkit/templates/.github/workflows/bkit-renovate.yml` |
|
|
297
349
|
| Dependabot | `.bkit/templates/.github/dependabot.yml` |
|
|
298
350
|
|
|
299
|
-
Use one
|
|
351
|
+
Use one, and record it in `bkit.dependencies.updater` (`"renovate"` / `"dependabot"`). Install and upgrade fill an empty value from the config present. `"none"` skips the install-time absence advisory. `bkit check` emits `dep-updater-absent` and `dep-updater-both`, and blocks on `dep-updater-unset` / `dep-updater-mismatch` when the value and the configs disagree. Setup: `docs/deployments.md` § Dependency updaters.
|
|
300
352
|
|
|
301
|
-
**Security scan.**
|
|
353
|
+
**Security scan.** An updater only offers fixes once a fixed release exists. To fail CI on known-vulnerable packages, risky config or committed secrets, copy `.bkit/templates/.github/workflows/bkit-trivy.yml` and own it. It also runs daily, and you accept findings in `.trivyignore.yaml`. There is no advisory, and `bkit tips` suggests it. Setup: `.bkit/templates.md` § Trivy.
|
|
302
354
|
|
|
303
|
-
**Test lint.** JS / TS repos, to fail `lint` on a test that cannot fail (no assertion, branch inside a test, unawaited promise):
|
|
355
|
+
**Test lint.** In JS / TS repos, to fail `lint` on a test that cannot fail (no assertion, a branch inside a test, an unawaited promise):
|
|
304
356
|
|
|
305
|
-
|
|
357
|
+
1. Copy and own `.bkit/templates/.oxlintrc.json`.
|
|
358
|
+
2. Add `oxlint` + `oxlint-tsgolint`.
|
|
359
|
+
3. Set `lint` to `oxlint -c .oxlintrc.json --type-aware --deny-warnings`.
|
|
360
|
+
|
|
361
|
+
There is no advisory, and `bkit tips` suggests it. Setup: `.bkit/templates.md` § Oxlint.
|
|
362
|
+
|
|
363
|
+
**All templates.** You copy and own them, and they are never installed. Catalog and install steps: `.bkit/templates.md`.
|
|
306
364
|
|
|
307
365
|
**Why opt-in, not part of a default install:**
|
|
308
366
|
|
|
309
|
-
- **Tracker** wires real credentials and MCP servers into workflows
|
|
310
|
-
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template
|
|
367
|
+
- **Tracker** wires real credentials and MCP servers into workflows, so the consumer must choose the provider. bkit can't guess.
|
|
368
|
+
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template plus the cloud env scaffolding (`.claude/hooks/bkit-cloud-bootstrap.sh`, and the `.cursor/Dockerfile` + `.cursor/environment.json` templates). The template auto-dispatches bkit-ship on CI pass and bkit-debug on CI fail, and runs design / plan / build only through `workflow_dispatch`.
|
|
369
|
+
- The workflow carries a claude job and an OpenCode job, each runtime-gated on its provider secret, so each is inert without its key. claude needs the `ANTHROPIC_API_KEY` repo secret or the federation repo variables (+ the Claude GitHub App). OpenCode needs `OPENCODE_PROVIDER_KEY`.
|
|
370
|
+
- Both need GitHub Actions write permissions, the GitHub tracker, and (for the Cursor half) a dashboard trigger, and the tracker itself is opt-in.
|
|
371
|
+
- The env scaffolding is inert until the Claude / Cursor cloud env is wired in the dashboard.
|
|
372
|
+
- Autonomous routing by default, wired to an unconfigured tracker, is the wrong default, so an install without `--auto` ships zero cloud footprint.
|
|
311
373
|
|
|
312
374
|
**How to decide:**
|
|
313
375
|
|
|
314
|
-
1. Run `bkit install --claude --cursor` (or whichever modules you want).
|
|
315
|
-
2. Pick tracker: `bkit install --tracker=github` (or `linear` / `jira`).
|
|
316
|
-
3. Copy one updater example (table above). Land Renovate config on the default branch before installing the App.
|
|
317
|
-
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`.
|
|
318
|
-
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.
|
|
376
|
+
1. Run `bkit install --claude --cursor` (or whichever modules you want). If you have not decided yet, the post-install banner lists `tracker-setup-none`, `dep-updater-absent` and `cloud-router-none`.
|
|
377
|
+
2. Pick a tracker: `bkit install --tracker=github` (or `linear` / `jira`). It needs no host flag, and it re-renders every installed host. The choice is persisted to `bkit.tracker.default`, and future installs preserve it (switching is free).
|
|
378
|
+
3. Copy one updater example (table above). Land the Renovate config on the default branch before installing the App. The next `bkit install` / `bkit upgrade` sets `bkit.dependencies.updater` to it.
|
|
379
|
+
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. The choice is persisted to `bkit.cloud.agent`, and install prints the secrets + permissions + dashboard checklist (`bkit-auto-setup`). The shipped `bkit-cloud.yml` carries a claude job (`ANTHROPIC_API_KEY` repo secret or federation repo variables, see `.bkit/cloud.md` § Claude — workload identity federation) and an OpenCode job (`OPENCODE_PROVIDER_KEY`), each runtime-gated.
|
|
380
|
+
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.tracker.default` / `bkit.dependencies.updater` / `bkit.cloud.agent`). The advisory then stays quiet. The `""` that install seeds means undecided, and keeps the nudge.
|
|
319
381
|
|
|
320
|
-
|
|
382
|
+
To reverse the tracker or cloud-agent choice, re-run install with the other flag. Updater files stay until you delete them.
|
|
321
383
|
|
|
322
384
|
**GitHub notifications.** bkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".
|
|
323
385
|
|
|
@@ -335,17 +397,17 @@ bkit tips --all # every firing tip
|
|
|
335
397
|
<!-- prettier-ignore -->
|
|
336
398
|
| Rule | Behaviour |
|
|
337
399
|
| --- | --- |
|
|
338
|
-
| Order | One fixed priority list. `--workflow=<name>` moves the tips that matter in that workflow to the front: tracker, GitHub token, `.bkit/.env` and direnv matter in every workflow, so they lead until fixed; then e.g. context-fetch for debug, Husky / slop-scan / Oxlint for build, CI workflow / cloud for ship, Serena / CI workflow / graphify / updater / Trivy for `audit`, Serena for `utility`. |
|
|
400
|
+
| Order | One fixed priority list. The upgrade tip (a newer bkit is out, per the answer `bkit repo info` caches) comes first everywhere, since an outdated bkit runs old workflow text, and no `bkit.advisories.ignore` entry silences it. `--workflow=<name>` moves the tips that matter in that workflow to the front: tracker, GitHub token, `.bkit/.env` and direnv matter in every workflow, so they lead until fixed; then e.g. context-fetch for debug, Husky / slop-scan / Oxlint for build, CI workflow / cloud for ship, Serena / CI workflow / graphify / updater / Trivy for `audit`, Serena for `utility`. |
|
|
339
401
|
| Detection | Local only — files, settings, environment; no network. A tip clears once its local half exists; dashboard steps live in the tip text. |
|
|
340
402
|
| Reuse | A tip for a gap an advisory already detects calls that advisory's detector — tip and advisory never disagree. |
|
|
341
403
|
| Artifact | `bkit install` / `check` / `upgrade` / `doctor` list every firing tip, with its id, in `.bkit/advisories.md` § Setup tips and the console banner: line, why, caution, ask-your-agent sentence, agent steps. |
|
|
342
404
|
| Star line | `Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!` (markdown link) closes bare `bkit tips`, after the tips and outside the cap; in a phase workflow it follows the tip with `Do you like bkit?` in bold, and the silence line follows it. Never under `--workflow=audit` / `utility` (those agents often run back to back), in `.bkit/advisories.md` or the console banner. |
|
|
343
|
-
| Silence | Root `package.json` `bkit.
|
|
405
|
+
| Silence | Root `package.json` `bkit.advisories.ignore`: a tip id (a workflow's `## bkit Tips` ends with `` **Want to silence these tips?** Ask your agent to "add `<id>` and `bkit-star` to `bkit.advisories.ignore` in package.json". ``, naming what it showed), or an advisory id the tip reuses, silences the tip and those advisories together; both show in the suppressed block. `bkit-star` (or the older `star`) silences the star line. |
|
|
344
406
|
| Exit | Always 0. Prints nothing when no tip fires and no star line shows. |
|
|
345
407
|
|
|
346
408
|
## Doctor
|
|
347
409
|
|
|
348
|
-
`bkit doctor` is **diagnostic verb
|
|
410
|
+
`bkit doctor` is the **diagnostic verb**: it runs the Phase 1 preflight + Phase 3 credential detectors, and exits 0. It changes no managed file. Like `bkit check`, it regenerates the `.bkit/advisories.md` artifact, and it creates `.bkit/` if absent, so a repo that never installed bkit gains that one file.
|
|
349
411
|
|
|
350
412
|
```bash
|
|
351
413
|
# Diagnose drift without running install
|
|
@@ -354,16 +416,17 @@ bkit doctor
|
|
|
354
416
|
|
|
355
417
|
Use `bkit doctor` to:
|
|
356
418
|
|
|
357
|
-
- Check `BKIT_GH_TOKEN`
|
|
358
|
-
- Surface `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
|
|
359
|
-
- Preview all advisories `bkit install` would show
|
|
360
|
-
- Verify environment ready before `bkit install` on new machine.
|
|
419
|
+
- Check that `BKIT_GH_TOKEN` is present in the shell (GitHub MCP auth), and check the cloud-router claude credential (`ANTHROPIC_API_KEY` repo secret or federation repo variables). It also flags a key shadowing federation, and an adopted `bkit-cloud.yml` too old for federation.
|
|
420
|
+
- Surface the `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
|
|
421
|
+
- Preview all the advisories `bkit install` would show after install, without triggering writes.
|
|
422
|
+
- Verify the environment is ready before `bkit install` on a new machine.
|
|
361
423
|
- Detect macOS GUI-isolation (`bkit cursor` / `bkit opencode`): see `.bkit/providers.md` § macOS GUI-isolation.
|
|
362
|
-
|
|
424
|
+
|
|
425
|
+
`bkit doctor` always exits 0. When it finds advisories, it prints them in the same checklist banner format as `bkit install`. When it finds none, it prints `[bkit-doctor] No advisories found.`
|
|
363
426
|
|
|
364
427
|
## Uninstall
|
|
365
428
|
|
|
366
|
-
`bkit uninstall` surgically removes bkit-managed content while preserving consumer customisations. The `.bkit/core` / `.bkit/shared` payload view links go with a full/core uninstall
|
|
429
|
+
`bkit uninstall` surgically removes bkit-managed content while preserving consumer customisations. The `.bkit/core` / `.bkit/shared` payload view links go with a full / core uninstall. It removes symlinks only, because a real directory at either path is consumer content and stays.
|
|
367
430
|
|
|
368
431
|
```bash
|
|
369
432
|
# Uninstall EVERYTHING — all modules, including the cloud add-on if present.
|
|
@@ -378,7 +441,7 @@ bkit uninstall --dry-run
|
|
|
378
441
|
|
|
379
442
|
# Uninstall specific modules (targeted — leaves core + the other modules intact)
|
|
380
443
|
bkit uninstall --claude # removes the claude host only
|
|
381
|
-
bkit uninstall --auto # clears the
|
|
444
|
+
bkit uninstall --auto # clears the bkit.cloud.agent key (cloud files are copy-and-own)
|
|
382
445
|
|
|
383
446
|
# Force-delete byte-equal-text files even if consumer modified them
|
|
384
447
|
bkit uninstall --force
|
|
@@ -395,43 +458,51 @@ bkit uninstall --nuke --yes
|
|
|
395
458
|
| Format | Behaviour |
|
|
396
459
|
| --- | --- |
|
|
397
460
|
| `fully-managed` | Always deleted (bkit owns 100% of the file). |
|
|
398
|
-
| `markered-text` | bkit block stripped; consumer content above/below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
|
|
461
|
+
| `markered-text` | bkit block stripped; consumer content above / below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
|
|
399
462
|
| `byte-equal-text` | Deleted only if current hash matches the hash `.bkit/version` recorded when bkit last wrote it (`canonicalHashes`). Consumer modifications → preserved. `canonicalHashes` is internal state `bkit check` does not verify: a hand-edited or corrupted entry makes uninstall keep that file as consumer-modified (`--force` deletes it anyway) and upgrade's whole-file diff report a conflict instead of updating it. Rendered `.bkit/*.md` skip that diff: upgrade always re-renders them, and `bkit check` flags a hand edit. |
|
|
400
463
|
| `json` | bkit's keys stripped; consumer keys preserved. `.mcp.json` / `.cursor/mcp.json`: only bkit's tracker entry is removed, and only while it still equals the template. `.opencode/opencode.json`: every `mcp` tracker entry (`github`, `linear`, `jira`) and every `provider` block of a supported provider is removed while it still equals what install renders — all the earlier installs left, not just the active one; an edited entry is kept whole. File deleted when nothing is left. |
|
|
401
464
|
|
|
402
465
|
### Idempotency
|
|
403
466
|
|
|
404
|
-
Running `bkit uninstall` twice is safe
|
|
467
|
+
Running `bkit uninstall` twice is safe, because later runs skip absent files and produce zero writes.
|
|
405
468
|
|
|
406
469
|
### What a full uninstall preserves
|
|
407
470
|
|
|
408
|
-
|
|
471
|
+
A bare uninstall removes bkit-managed files and strips bkit-managed blocks, but it is not a guaranteed zero-footprint wipe. In `docs/`, bkit's block (managed marker included) is stripped from every installed `docs/*.md`, a file holding nothing else is deleted, and the owned `docs/templates/bkit-*.md` are deleted. It deliberately leaves:
|
|
472
|
+
|
|
473
|
+
- everything outside `bkit:start` / `bkit:end` in `docs/*.md`, `.agents/context.md`, `.agents/skills.md` and the other managed-block files;
|
|
474
|
+
- your own files in `docs/` and `docs/templates/`;
|
|
475
|
+
- every file you copied from `.bkit/templates/`;
|
|
476
|
+
- any owned whole-file the consumer modified (hash mismatch → preserved);
|
|
477
|
+
- generated artefacts that are not manifest-tracked (`.bkit/advisories.md`, `.bkit/friction.jsonl`, the newest-release cache `.git/bkit-latest-version.json`).
|
|
478
|
+
|
|
479
|
+
Use `--nuke` to force-remove every manifest-listed bkit file regardless of consumer modifications. The generated artefacts are still yours to delete by hand.
|
|
409
480
|
|
|
410
481
|
## Phase 3 exit-1 and recovery
|
|
411
482
|
|
|
412
|
-
When `bkit install` detects
|
|
483
|
+
When `bkit install` detects a blocker-severity finding in Phase 3 (for example `owned-hook-missing`: a bkit-owned hook file is gone, so the guard or setup step it holds does not run), it exits 1 and prints a single-line recovery command:
|
|
413
484
|
|
|
414
485
|
```
|
|
415
486
|
[bkit-install] 1 Phase 3 blocker(s) detected. Recovery:
|
|
416
487
|
bkit uninstall <flags> && <fix the issue> && bkit install <flags>
|
|
417
488
|
```
|
|
418
489
|
|
|
419
|
-
Advisories (non-blockers) informational only
|
|
490
|
+
Advisories (non-blockers) are informational only, and do not trigger exit-1.
|
|
420
491
|
|
|
421
492
|
### --auto-revert
|
|
422
493
|
|
|
423
|
-
Add `--auto-revert` to `bkit install` to automatically run `bkit uninstall` in-process when Phase 3 blocker fires:
|
|
494
|
+
Add `--auto-revert` to `bkit install` to automatically run `bkit uninstall` in-process when a Phase 3 blocker fires:
|
|
424
495
|
|
|
425
496
|
```bash
|
|
426
497
|
bkit install --auto-revert
|
|
427
498
|
```
|
|
428
499
|
|
|
429
|
-
|
|
500
|
+
This is useful in CI scripts to guarantee a clean state on failure.
|
|
430
501
|
|
|
431
502
|
## Install staging directory
|
|
432
503
|
|
|
433
|
-
`bkit install` renders derived files (
|
|
504
|
+
`bkit install` renders derived files (for example `.opencode/opencode.json`) into the `.bkit-staging/` scratch directory before merging them into the consumer destinations. The scratch directory is cleaned up after every run, on success and failure alike, and never persists in committed consumer repo state.
|
|
434
505
|
|
|
435
|
-
**Not a cross-module transaction.** Modules write directly to destinations
|
|
506
|
+
**Not a cross-module transaction.** Modules write directly to their destinations, so `bkit install` is not atomic across modules. A failure partway (for example a hand-broken `.claude/settings.json` that makes the JSON merge throw) leaves the earlier modules' files written and `.bkit/version` unpinned. The error is surfaced, not swallowed.
|
|
436
507
|
|
|
437
|
-
**Recovery is re-run.** `bkit install` idempotent
|
|
508
|
+
**Recovery is re-run.** `bkit install` is idempotent: fix the offending file and re-run to complete. `bkit uninstall` removes whatever was written.
|