@cbartens/bkit 5.5.1 → 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 +35 -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 +19 -18
- 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 +91 -167
- package/.bkit/core/.bkit/providers.md +29 -32
- package/.bkit/core/.bkit/templates.md +12 -11
- package/.bkit/core/.bkit/trackers.md +51 -28
- package/.bkit/core/.bkit/workflows.md +394 -355
- 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 -29
- package/.bkit/core/engine/checks/after/github.ts +95 -17
- package/.bkit/core/engine/checks/after/index.ts +10 -7
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +46 -91
- 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 +6 -6
- 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 +407 -64
- 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 +58 -8
- 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 +185 -8
- 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 +250 -3
- 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 +157 -20
- 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 +29 -15
- 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 +32 -14
- 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 +72 -18
- 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 +29 -14
- 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 +27 -12
- 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 +41 -18
- 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 +11 -11
- 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 +16 -7
- 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 +1 -1
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
- package/.bkit/templates/.husky/pre-push +4 -4
- package/.bkit/templates/.prettierignore +7 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
- package/CHANGELOG.md +112 -0
- package/README.md +50 -35
- package/dist/checks/after/ci-yml.js +39 -28
- package/dist/checks/after/github.js +91 -17
- package/dist/checks/after/index.js +11 -8
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +39 -82
- 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 +4 -4
- 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 +343 -59
- 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 -8
- 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 +147 -9
- package/dist/install/manifest.js +11 -9
- package/dist/install/modules/cloud.js +22 -13
- package/dist/install/modules/core.js +247 -3
- 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 +125 -17
- 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 +113 -24
- 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/dist/commands/harvest.js +0 -353
- package/dist/tools/wording.js +0 -680
|
@@ -39,6 +39,13 @@ pnpm-lock.yaml
|
|
|
39
39
|
# never be byte-equal to what the renderer emits and every close would carry a
|
|
40
40
|
# formatting-only diff. The fold's output is the source of truth.
|
|
41
41
|
docs/roadmap.md
|
|
42
|
+
# Raw gate output — `bkit tests run` logs that workflows commit as `.md` beside
|
|
43
|
+
# a run's artifacts. The text is command output, not markdown; prettier would
|
|
44
|
+
# escape and reflow it, and a gate's own format check would fail on it.
|
|
45
|
+
docs/plans/*/logs/*/run-tests-*.md
|
|
46
|
+
docs/plans/*/logs/*/build-group-gate-*.md
|
|
47
|
+
docs/plans/*/logs/*/build-subplan-gate-*.md
|
|
48
|
+
docs/plans/*/logs/*/context-tests-local-*.md
|
|
42
49
|
# bkit's reference copies of its templates — refreshed by `bkit upgrade`, never
|
|
43
50
|
# formatted by this repo.
|
|
44
51
|
.bkit/templates/
|
|
@@ -87,7 +87,7 @@ function judge(cwd, wt, fid) {
|
|
|
87
87
|
|
|
88
88
|
/** Remove worktree `wt`; null when gone, else why not. */
|
|
89
89
|
function removeWorktree(cwd, wt, fid) {
|
|
90
|
-
const r = spawnSync("pnpm", ["-s", "bkit", "worktrees", "remove", `--fid=${fid}
|
|
90
|
+
const r = spawnSync("pnpm", ["-s", "bkit", "worktrees", "remove", `--fid=${fid}`, "--json"], {
|
|
91
91
|
cwd,
|
|
92
92
|
encoding: "utf8",
|
|
93
93
|
});
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,118 @@ Format: `## [version] — YYYY-MM-DD`
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [6.0.0] — 2026-10-25
|
|
10
|
+
|
|
11
|
+
### Breaking Changes
|
|
12
|
+
|
|
13
|
+
- **BREAKING — `bkit <noun> <verb>` prints text, not JSON; `--json` prints the old JSON.** stdout is `key: value` lines, nested keys indented under their parent, lists of flat rows as markdown tables. A hook, script or CI step that parses bkit output (piped to `jq`, or read with `JSON.parse`) reads nothing until it adds `--json`. The `bkit-cloud-bootstrap.sh` and `bkit-disk-prune.mjs` templates pass `--json`; copy the change into adopted copies. Setup tip `bkit-output-json` names each file still parsing text. Text output also leaves out the keys no workflow reads (each verb's `textOmit`, e.g. the written ledger `row`); `--json` prints every key. #681
|
|
14
|
+
- **BREAKING — the `package.json` `bkit` settings are grouped into sections, and `bkit upgrade` moves them for you.** `tracker` (`default`, `github`, `linear`, `jira`), `cloud.agent`, `providers.opencode` (`default`, `installed`), `testing` (`minPushPaths`, `ciCapstone`, `ciWorkflow`, `shipGate`), `workflows` (`minFreeGb`, `worktree`, `tasks`, and the ask points), `prompts.roadmapNext`, `dependencies.updater` and `advisories.ignore`. On install and upgrade, `migrateBkitLayout` moves each flat key to its section once and deletes the old key; `loopPause` becomes `ask` on every ask point. A value already at the new path wins, and the file keeps its indent. bkit reads only the new layout, so a script of yours that reads an old key from `package.json` reads nothing. `docs/migrations.md` lists every move. #693
|
|
15
|
+
- **BREAKING — `bkit prs merge` refuses a PR whose base is not `dev`.** It exits 8 and merges nothing, and `bkit prs open --base=main` is refused too: bkit opens and merges into `dev` only, and releases stay manual. A consumer script that merges a PR into another base through `bkit prs merge` breaks. #650
|
|
16
|
+
- **BREAKING — `bkit harvest` and `bkit analysis` are removed.** `bkit stats` replaces `bkit analysis` for a repo's own report. Collecting stats across repos is no longer part of the package. #683
|
|
17
|
+
- **BREAKING — `.bkit/.env` names the Jira key `BKIT_JIRA_API_KEY`.** `bkit upgrade` renames `BKIT_JIRA_API_TOKEN` lines in place and keeps the value. #675
|
|
18
|
+
|
|
19
|
+
### Added
|
|
20
|
+
|
|
21
|
+
- **`bkit context fetch` writes a JSON list from a context-fetch block as a markdown table.** It runs the same block runner as `bkit context run-block` (which stays). With `--render=table` (the default), a JSON array of flat objects becomes a table when the table parses back to the same values and types; anything else is written as printed, and stderr logs `render: raw (<reason>)`. The output as printed is copied to `{OUTBOX}/{name}.raw.{ext}` first, never committed; the clamp record gains `render`. `/bkit-debug` Step 4 fetches through it. #681
|
|
22
|
+
- **New verbs and flags for the git work workflows did by hand.** Each prints only the fields the workflow reads next. #679
|
|
23
|
+
- `bkit branches push --mode=plain [--set-upstream] [--ahead-of=<ref>]`: a feature-branch push, never forced; exit 21 when on `dev` / `main` or nothing is ahead.
|
|
24
|
+
- `bkit branches push --commit=<msg> [--label=…] --file --workflow`: one marker commit per run (auto-route suffix from the labels), then the push.
|
|
25
|
+
- `bkit branches fast-forward --onto=<ref>`: fetch and fast-forward; exit 22 when the local branch diverged.
|
|
26
|
+
- `bkit branches scan-diff --base=<ref>` with `--paths=<regex>`, `--marker=<text>` or `--code`: exit 0 when the diff has a match, 1 when not.
|
|
27
|
+
- `bkit branches force-build`: see Fixed.
|
|
28
|
+
- `bkit prs open --file --workflow`: a re-run reuses the PR the first run opened.
|
|
29
|
+
- `bkit workflows start --branch` (exit 15 on another branch; ship clears stale sentinels), `bkit workflows close --summary --summary-missing`, `bkit workflows handover --list-stray`.
|
|
30
|
+
- `bkit worktrees setup --issue` (ship prints `branchWarning`), `bkit counters route --rows=<type>:<next|count>`, `bkit status meta --debug-attempt=run`, `bkit runs gate --fetch`.
|
|
31
|
+
- `bkit ledgers commit --path=<file>` commits one file alone; `--stage-tracked-updates` with a commit mode commits tracked modifications too.
|
|
32
|
+
- **Workflows run from the prompt alone, with no issue, design or plan.** A missing issue no longer stops design, plan, build, debug or ship. Step 1 recovers the issue from a `FID` the prompt names or a `feat/{FID}` branch (`bkit fids parse`); with none, the run warns once (line 1 of its final message) and continues, skipping every tracker read, label, comment, board call and kill-switch check. Workflows still never create an issue. A run with no issue mints its `FID` as `{branch-suffix}-{slug}` with every all-digit word dropped, so no tracker can read it as an issue id; when a finished run already used that name, `bkit fids resolve` takes the first free `-b`, `-c`, … suffix (naming the `FID` in the prompt is how you continue a run). A `feat/{FID}` branch gives its suffix verbatim as the `FID` for any lowercase slug (`feat/upgrade-react-19`), and the issue id in it counts only when `.bkit/issues.jsonl` has a feature row for it; a branch suffix that is not a lowercase slug (`feat/Fix_CI`) stops the run and asks you to rename the branch or name an issue. #650
|
|
33
|
+
- **`bkit fids check --issue` and `bkit steps gate --issue`.** Passing the run's issue id (or an empty value for a run with no issue) checks the `FID` against it: with an issue the `FID` must embed that same id, with none any lowercase slug passes. `bkit prs open --issue` puts only `<!-- bkit:fid={FID} -->` in the PR body when there is no issue. #650
|
|
34
|
+
- **`/bkit-debug` on `dev` works in place, on its own paths and its own commits.** Steps 9 and 10 push nothing. Step 11 pushes only the run's commits with `bkit branches push --mode=dev`, then waits for the `dev` CI run at the pushed commit (`bkit runs dispatch --sha`, `bkit runs wait --until=completed`, `bkit runs gate --capstone-only`) before it releases the lock. A red run, a refused push or a replay conflict goes to the Failure Path naming the run; a file someone else changed during the run stops the workflow and asks you. #650
|
|
35
|
+
- **`bkit stats` writes this repo's stats report to `.bkit/stats.md`.** It reads only this repo's `.bkit/stats.jsonl`, `.bkit/friction.jsonl` and `docs/deferrals.jsonl`, and prints the report too. `chat` / `run` rows are not counted. Always exits 0. #683
|
|
36
|
+
- **Plan caps are a `package.json` setting, `bkit.workflows.tasks`.** `maxPerGroup` (default 3) and `maxTestsPerGroup` (default 15) cap each plan group's tasks and `TEST FIRST` tests; `maxTestsPerTask` (default 10) and `maxTestFilesPerTask` (default 3) cap each task. Install and upgrade add any missing key and never change a set one. A value that is not a whole number of 1 or more falls back to its default, and `bkit check` shows advisory `bkit-tasks-invalid`. `bkit tests plan-check` and `bkit challenge merge` read them; `bkit repo info` prints them as `tasks`, and `/bkit-plan` and `/bkit-build` pass them to every agent that writes, reviews, executes or verifies plan tasks; no prompt carries a number of its own. When `.github/ISSUE_TEMPLATE/bkit-change.yml` shows a cap as `(default N)` with N other than the configured value, `bkit check` shows advisory `bkit-tasks-form-stale` naming the number to change. #668
|
|
37
|
+
|
|
38
|
+
- **`bkit workflows summary` writes each phase's summary.** Design, plan, build, debug and ship run it at their Summary step instead of a summary subagent. It reads the run's `status.jsonl` rows, the plan files, `docs/deferrals.jsonl` and the Decision Pause files, writes `{workflow}-summary.md` and prints `verdict`, `failures`, `reasons` and `nextStep`. FAIL: a build plan task left unticked, a build with no plan file (`No plan file`), the last test run FAIL, or a step whose last row is FAIL with no later step answering it. CONCERNS: a step whose last row is CONCERNS, an item accepted at a Decision Pause, or a deferral written this run. The recommended next command comes from a fixed table per workflow and verdict. Ship's summary shows the PR's size from `gh` (`--pr`), and drops the line when `gh` fails. Ship now runs it after `@bkit-ship-update-docs` returns, not beside it. #682
|
|
39
|
+
- **`bkit challenge merge` turns build challenge findings into plan tasks.** It reads one or two challenge reports, each finding a task block under `## Findings Log` with `Severity`, `Class`, `Fixable`, `Location`, `DONE WHEN` and `TEST FIRST`. Findings at the same `path:line` merge into one (the worse severity wins); a location accepted at a Decision Pause is dropped, including a path with no file extension (`Makefile:12`). A finding at the `Location` and severity of an earlier challenge task that is still open reopens that task instead of adding a twin: its `**Round:**` line gains the round (`1, 2`) and it is listed in `reopened` and `fixTasks`. One already done in an earlier round gets a new task. CRITICAL, HIGH and MEDIUM findings are appended to `{FID}-plan.md` (`--plan`) as task blocks numbered after its last task, in new last groups of at most `bkit.workflows.tasks.maxPerGroup` tasks (default 3). More than 4 x `bkit.workflows.tasks.maxPerGroup` findings writes nothing and routes `pause` with `overflow` set, so the owner picks which to fix. Each LOW finding becomes a `docs/deferrals.jsonl` row with `reason` `low-severity`. The plan is checked before it is written: a failing check (exit 23) changes no file and prints the `problems`; Build Step 10 then re-runs the reviewers once with them, as it does for exit 22. It prints `route`: `pause` when a finding says `Fixable: false`, round 2 left tasks or the findings overflow, `fix` when it appended or reopened tasks, else `none`; also `fixTasks` (reopened, then appended), `appended`, `reopened`, `deferred` (rows written), `dropped`, `plan` and `round`. `overflow` counts only new CRITICAL, HIGH and MEDIUM findings. A report with findings but no task blocks exits 22. Running it again with the same reports appends nothing. Build Step 10 runs it. #682
|
|
40
|
+
- **`bkit status resume --workflow=<name>` names where a stopped run picks up.** It reads `status.jsonl` and prints the step after the active `IN_PROGRESS` run's last `DONE` step (`step`, `number`, `title`, `after`, `group`, `active`, and for build `challengeRound` and `challengeDone`). A build stopped after a Decision Pause resumes where that decision's row sends it: each row records `route` (`fix` → Plan Execute, `verify` → Plan Verify, `tests` → Run Tests). Steps 1-2 run again on every resume, so their rows place no resume point; rows of steps the workflow no longer has are ignored; a step whose next step depends on its verdict resumes at itself; a Plan Execute row with verdict `HANDOVER` resumes at Plan Execute for the same group. A build stopped in one of the removed challenge steps resumes at Run Tests. Every workflow's Resume line calls it. Exit 2 for an unknown workflow, 3 for an unreadable log. #682
|
|
41
|
+
|
|
42
|
+
- **`bkit context brief` writes one build group's brief.** `--plan` and `--group=N` (or `--next`, the first group with an open task) write `build-brief-{G}-{n}.md` into the `--dir` logs folder: the plan's title, Context & Goals, Narrative, Success Criteria and Out of Scope; every group and task with its state; the group's open task blocks word for word; the reds `status.jsonl` (`--file`) already holds for them, each marked "test written and seen failing; code may be partly done"; one line per earlier task they depend on; the plan's `Reuse Inventory` rows and `Architecture & Component Changes` entries that name the open tasks' `CREATE` / `UPDATE` / `DELETE` files; and the `--note-file` text under Deviations. A task is done when its box is ticked or a `build-plan-execute-*-log.md` in the folder has its `DONE — TASK N` line. It prints only `artifact`, `bytes`, `group`, `tasks`, `workBytes` and `workCap` (8192), so the orchestrator never reads the brief. Inventory rows and Architecture entries past the 8 KB work cap are left out and counted, and the brief names the plan section to read instead; task blocks over the cap warn. `--next` with nothing open writes nothing and prints `group: null`. #668
|
|
43
|
+
- **`bkit check` lists plans the next build will convert.** Advisory `plan-task-markers-missing` names each `docs/plans/{YYYYMM}/{FID}-plan.md` with no task markers whose FID has not shipped (`archive/` and `logs/` are not read). Nothing to do by hand: the FID's next `/bkit-build` converts it. #668
|
|
44
|
+
- **Workflow closes record how full each subagent's context got, and `bkit stats` reports it.** On Claude Code, `bkit workflows close` adds `ctx` to the `outcome` row: for each agent type, how many subagents ran (`runs`) and the largest context one model call reached (`peak`), read from the closing session's subagent transcripts that started during the run. `.bkit/stats.md` gains `## Agent context peaks` (agent type, subagents, runs, peak, runs over 160,000 tokens), or "No context data." when no run recorded any. Other hosts record nothing: Cursor keeps no token counts, and Codex, opencode and Antigravity give no confirmed way to tell this run's transcripts apart. A run spread over two Claude Code sessions counts only the closing session. A transcript folder that cannot be read is skipped and never fails the close. #668
|
|
45
|
+
- **`bkit status route --step=` prints `parentSha`,** the commit HEAD was at when the step's last row was written. For a `build-group-start` row that is the group's start commit, so `bkit context diff --base=<parentSha>` reviews only that group's commits. #668
|
|
46
|
+
|
|
47
|
+
- **Every bkit Claude Code subagent summarises its context at 300,000 tokens at the latest.** Each `bkit-*` agent (and the `utility-*` release agents) carries `autoCompactWindow: 300000` in its frontmatter; it only lowers the window, so a lower repo or user setting and `CLAUDE_CODE_AUTO_COMPACT_WINDOW` still win (Claude Code v2.1.296+). Codex, opencode, Cursor and Antigravity have no working per-agent setting, so their renderers drop the field; `.bkit/providers.md` § Context compaction lists each host's answer with its source. Your main session's window stays your setting. #668
|
|
48
|
+
|
|
49
|
+
- **`bkit counters progress`** reports how a fix loop is going since the last decision: problems after each round (`5 → 2`), whether the rounds changed source code, the last and next fix strategy, minutes per round, a trend (`closing` / `stuck` / `worse`) and a recommendation. #670
|
|
50
|
+
- **Step 1 of every phase workflow resolves the issue and `FID` in the engine.** The workflow writes the session prompt to `{SESSION_DIR}/prompt.md` (`bkit repo info` now prints `sessionDir`, a new folder per run under the outbox, pruned after 7 days). `bkit fids parse --prompt-file` prints the issue it names (`source`, `issue`, `ref`, `fidNamed`) for GitHub, Linear or Jira. `bkit fids resolve` replaces the prose chain: a `FID` the prompt names, the `feat/{FID}` branch, the feature logged for the issue (on `dev` too), a mint from the title, then a free `-b`, `-c`, … suffix and the format check, in one call. `bkit fids plans` counts build's sub-plans and tells build and ship when there is no plan. `bkit fids design --description-file --prompt-file` gives plan its parent design and audit report paths; a named file that is missing exits 7. #677
|
|
51
|
+
- **`bkit workflows start` prints where a resumed run picks up.** `lastDoneStep` is the run's last finished step, and `openDecision` the build Decision Pause still waiting for an answer, with every field Step 3 of the pause needs. The workflows no longer read `status.jsonl` or decision files by hand to resume. #677
|
|
52
|
+
- **The engine reads and writes the tracker; the tracker MCP is the fallback.** On GitHub (`gh` with `BKIT_GH_TOKEN`), Linear (its GraphQL API with `BKIT_LINEAR_API_KEY`) and Jira (the Rovo MCP endpoint over HTTP with `BKIT_JIRA_API_KEY`), bkit verbs now post step comments (`steps finish --post`, `issues comment --post`, `workflows fail|handover|close|links --post`), write labels, state and the board move (`issues labels --write`), and read issues. Each prints `tracker`; the workflow calls the tracker MCP only when a verb exits 80 or prints `done` = false. A re-run never posts the same step comment twice: `status.jsonl` records each post as an `engine-action` row, and close-time comments are checked against the issue's last 5 comments. #675
|
|
53
|
+
- **New tracker verbs.** `bkit issues fetch` writes the issue's description, comments and facts to the session folder (or the outbox) and prints only `title`, `url`, `state` and `labels`. `bkit issues related` reads each related-search hit and writes the related-issues file. `bkit issues blocked-by` prints a build's open blockers. `bkit workflows input` writes the run's input file. `bkit runs context` prints `ref`, the issue as `/bkit-auto` passes it on. #675
|
|
54
|
+
- **`bkit workflows close --final-return` prints the run's last message.** It holds the summary, the issue link, `## Suggested Replies` and `## bkit Tips`; `--warning`, `--line` and `--suggest` add the run's own lines. `workflows close` and `workflows fail` delete the run's session folder when given `--session-dir`. #675
|
|
55
|
+
- **`bkit tests run` counts failing tests itself and writes the trimmed log.** It empties `{log}.reports/` next to the log and passes it to the gate as `$BKIT_TEST_REPORT_DIR`; `failures` is the failing plus erroring test cases in the JUnit files written there. A FAIL with no reports prints `failures: null` and a hint, never a guessed count. `--artifact --fid --step --attempt` copies the log into the plan folder, trims it and records the trim in the same call (exit 5 when that fails); build Steps 7 and 14 and debug Step 3 use it, and drop `--failures` when the count is unknown. Wire your test runners' JUnit output into that folder (`docs/testing.md` § JUnit reports for bkit). #678
|
|
56
|
+
- **`bkit status route --prompt-file` decides debug's start.** For `--workflow=debug` it prints `debugAttempt`, `debugMode`, `soakEntry`, `repro` and `gates` from the session prompt and the current run (`--fid` and `--month` stand in for `--file`). Debug's Step 1 is one call instead of jq and prose. `[live=off]` now counts only in the session prompt, not in the issue body. #678
|
|
57
|
+
- **Every trimmed file keeps its untouched original in the outbox.** `context clamp`, `context run-block`, `context diff` and `tests run --artifact` copy the original to `{OUTBOX}/{name}.raw.{ext}` before cutting it (never committed). The clamp record gains `raw`, `source` (the command and inputs that produced the file) and `fetchedAt`. `context clamp` takes `--source`. #678
|
|
58
|
+
- **After-check `github-project-token-scope`.** With a GitHub board configured, `bkit check` warns when `BKIT_GH_TOKEN` cannot write it (a classic token without the `project` scope, or a fine-grained token that cannot see the board), and names the fix. Skipped on cloud runtimes, where the engine never moves the board. #675
|
|
59
|
+
- **Every point where a run can ask you has an `ask` setting and a hard limit.** `package.json` `bkit.workflows.<workflow>.<point>` holds both: `design.grill` (`maxTurns`, default 6), `build.verify`, `build.challenge`, `build.tests`, `debug.fix`, `debug.soak` and `ship.merge` (`maxAttempts`, default 2), each `ask: true` by default. A used-up limit always goes to the Failure Path, and a question never resets a count. With `ask: false`, or in a headless GitHub Actions run, the run takes each recommendation: `Fix now` is applied, and an `Accept` is recorded as assumed. Questions with no recommendation are still asked in a session and go to the Failure Path headless. `bkit counters route --point=` and `bkit counters max --point=` read the settings; a bad value falls back to its default with the advisory `bkit-ask-settings-invalid`. #671
|
|
60
|
+
- **`bkit decisions compose`, `apply` and `pending` handle build questions from pause to ship.** `compose` writes the Decision Pause file in one question layout from the orchestrator's items JSON, with the progress block and the loop question first for `--loop=verify|tests`. `apply --by=headless` takes each recommendation and writes `Accept (assumed)`; it exits 4 when questions with no recommendation are left. `/bkit-ship` lists the assumed items with `pending` at its new Confirm Assumed Items step and asks you to confirm each: `apply --by=owner --confirm` writes the real acceptance, `--reject` records the rejection, and `pending --defer` writes one `needs-decision` deferral per item rejected or never confirmed; ship still merges. #671
|
|
61
|
+
- **`.bkit/authoring.md` holds the authoring rules for every agent-read markdown file.** Docs, prompts and workflows share one set: § All Agent-Read Files, § Notation (one job per punctuation mark, the closed list of capitalised words), § Docs, § Prompts and Workflows, § Prompts Only and § Workflows Only. It ships with the other `.bkit/*.md` docs and has a row in `.agents/docs.md`; `.bkit/prompts.md` and `.bkit/workflows.md` keep only the explanations behind the rules. #684
|
|
62
|
+
|
|
63
|
+
### Changed
|
|
64
|
+
|
|
65
|
+
- **Ship, debug and build make no raw `git` / `gh` calls, `jq` pipes or hand copies.** Every one is now a `bkit` verb, and a test in `workflow-fence-syntax.test.ts` fails on any that comes back (the `{BKIT}` bootstrap line is the one named exception). Ship Step 5 now stops when the fetch of the PR branch fails, where it used to carry on with the local copy. #679
|
|
66
|
+
- **Each agent that reads the run's diff gets a fresh diff file.** Build Steps 7, 9 and 10, debug Step 10, ship Step 5 and every Failure Path handover run `bkit context diff --reset-log` into `tmp/bkit-diff-{FID}.md` right before the agent; the Large Diff Guard rule is gone. Past 10000 lines the file names the files it does not show whole, and the security challenger reads each security-relevant one with its own `git diff`. `context diff` prints `omitted` and takes `--reset-log`. #678
|
|
67
|
+
- **`/bkit-plan` runs one review round with two reviewers and one scope check.** Step 5 runs `@bkit-plan-review-1` (tightness and task order), `@bkit-plan-review-2` (regression risk) and `@bkit-plan-scope-check` (template, criteria and verification) in parallel; Step 6 applies all three reports in one pass to `plan-v2-reviewed.md`. The separate scope round and its apply step are gone. review-1 fails a plan only for a task-order cycle no reordering fixes or a plan that contradicts its design. `bkit upgrade` removes the retired agent files from each host. A plan paused mid-review under the old steps: run `/bkit-plan` again. #665
|
|
68
|
+
- **Build Step 10 runs only the security reviewer on a small change.** `bkit challenge gate` fetches `origin dev` first (offline, it measures against the last fetch and logs that), then measures `origin/dev...HEAD` (`docs/plans/**` excluded) on every pass: under 300 lines and 10 files, `@bkit-build-challenge-2` runs alone and challenge-1 is skipped; a larger change runs both. Each pass writes a `challenge-gate` row to `status.jsonl`, the summary's `## Challenge` section says when challenge-1 was skipped, the `outcome` row carries `build.challenge.gate`, and `bkit stats` counts runs by size. #665
|
|
69
|
+
- **`.bkit/prompts.md` § Model Overrides rows naming an agent bkit no longer ships are reported.** `bkit install`, `check` and `upgrade` list them as the `model-override-unknown-agent` advisory; those rows are not applied. #665
|
|
70
|
+
- **The build challenge is one step, and build has 15 steps.** Step 10 runs the two challenge reviewers, then `bkit challenge merge` adds their findings to the plan as tasks, each with a test to write first. Fixable findings go back through Plan Execute and Plan Verify once (round 2 reviews again but never fixes on its own); a finding no agent can fix, or anything left after round 2, goes to the Decision Pause. Accepting a challenge task there ticks it in the plan. The challenge's `status.jsonl` row records the round it ran as, and `bkit status resume` reports it back as `challengeRound`, so a resumed build picks up the right round. The challenge runs at most two rounds: once a round-2 challenge has merged, `bkit status resume` prints `challengeDone: true` and Step 10 goes on to Run Tests, and a round-2 `Fix now` runs the fix without a third review. A build resumed into an open challenge Decision Pause re-runs the size check and the merge, which finds its tasks already in the plan and writes nothing, and asks the same questions again. The old Steps 11-13 (reconcile, remediate, edge-case tests) are gone, and Steps 14-18 are now 11-15: Run Tests 11, Failure Diagnose 12, Failure Remediate 13, Summary 14, Close Workflow & Create PR 15. `MAX_CHALLENGE_REMEDIATE_ATTEMPT` is removed. #682
|
|
71
|
+
- **`@bkit-build-plan-execute` writes `docs/knowledge.jsonl` gotcha rows** once its tasks' tests pass, now that it fixes challenge findings. #682
|
|
72
|
+
- **`/bkit-plan` writes its tasks in groups and checks the plan after every write; it has 8 steps.** `@bkit-plan-generate` writes groups of task blocks in build order, each group at most 3 tasks and 15 `TEST FIRST` tests. A task's `DEPENDS ON` takes task numbers (`1, 2`) or `TASK N` names. Step 3 runs `bkit tests plan-check --existence=refuse` on the draft straight after the agent, and Step 6 runs it again on `plan-v2-reviewed.md`; a refused plan goes back to the same agent once to fix only the lines the report names, and a second refusal fails the run. A draft still holding `PENDING` (the agent hit its turn cap) gets one more `@bkit-plan-generate` that fills only the `PENDING` sections. Fetch Context no longer checks the draft. Summary is Step 7 and Close Workflow Step 8; a plan stopped after the old Complexity Split resumes at Summary. #668
|
|
73
|
+
- **`bkit tests plan-check` refuses more malformed plans.** Group numbers must ascend through the file, and task numbers within a group, because the build runs groups in file order; neither may be 0. `DEPENDS ON`, `DONE WHEN`, `TEST FIRST` and `TEST EXCEPTION` may each appear once per task. A bold `**TASK N:**` line inside another task's block, and a task depending on itself, are refused. A code fence that is never closed is reported by its line ("nothing after it is read"). A plan with Windows line endings (CRLF) reads like any other, and `DEPENDS ON: none (...)` names no task. #668
|
|
74
|
+
- **`bkit tests green` reports a `DELETE` that did not happen.** A plan task's `DELETE` line whose file still exists, or whose name is still found in the tree (`git grep`, untracked files included, the plan folder skipped), is a `delete-still-referenced` gap. A `DELETE` and `CREATE` of the same thing is a move and is not checked; for a file-only `DELETE` with a `CREATE` of the same file name, the new file and paths to it are not counted as references; when the search itself fails, the gap says `references not checked`. Plan Verify reads each hit: a different thing with the same name is no gap, anything else is `Fixable: true`. A `§ heading` must match a heading line exactly, and in a JSON, YAML or TOML file a dotted key must match its full path (flat or nested, one-line JSON included); in code and other files it matches its last segment. `bkit tests green --group=N` exits 2 when the group is missing or has no tasks. #668
|
|
75
|
+
- **`bkit workflows promote` copies `{FID}-plan.md` only.** It no longer copies or archives `{FID}-plan-N.md` sub-plans and prints no `subPlans`; a `{FID}-plan-N.md` an older run left in the bucket stays where it is and nothing reads it. The newest draft never counts `plan-vN-split.md` or `plan-vN-K.md`, so a re-run of an old split plan promotes its new reviewed plan. `bkit branches land` checks only the one canonical doc. #668
|
|
76
|
+
- **`/bkit-build` runs one plan group at a time.** Steps 6-8 loop over the groups of `{FID}-plan.md`: `bkit context brief --next` writes the group's brief and `@bkit-build-plan-execute` reads only that; verify judges the group's own diff (`bkit context diff --base=` the group's start commit) and is the only step that ticks tasks; the gate between groups writes a `build-group-gate` row (it was `build-subplan-gate`). Verify attempts count per group (`bkit.workflows.build.verify.maxAttempts`). Holistic verify (Step 9) and the challenge (Step 10) run once, after the last group. A Decision Pause `Fix now` writes a task block into the paused group when it stays within 3 tasks and 15 tests, else into a new group right after it; Accept writes a `TEST EXCEPTION` field. `@bkit-build-plan-execute`, `@bkit-build-plan-verify` and `@bkit-build-plan-gaps-remediate` now stop at 100 turns. Near its turn cap `@bkit-build-plan-execute` sets the verdict `HANDOVER`; Step 6 then runs the group once more with a fresh brief that leaves out its `DONE` tasks, counted as a handover, not a failed attempt, and the re-run keeps the existing log. The tracker comment shows `HANDOVER`. #668
|
|
77
|
+
- **A build with no plan, or a plan with no task markers, gets one written first.** Step 3 runs `bkit tests plan-check`; when it finds no plan or no task blocks, the new `@bkit-build-plan-convert` agent writes `{FID}-plan.md` in task-block form, and the check runs again. It works from `build-input-{RUN}.md`, which Step 2 writes for every build with the prompt, the issue text and the plan as it arrived, keeping an existing plan's other sections; where the plan and the issue disagree, the plan wins. Only the convert agent reads `build-input-{RUN}.md`: it holds the whole plan again, so execute, verify, install-skills, the challenge agents and diagnose work from the plan or the group's brief instead, and run instructions in the session prompt (a redo, a resume, a constraint) reach each brief's `Deviations` section through `bkit context brief --note-file`. Ship no longer records `planSource`. A build already past its execute step finishes on the bkit version it started on: upgrade between builds, not during one. On a plan with no task markers `bkit tests green` stops with "this plan has no task markers; run /bkit-build again to convert it" instead of reporting zero tasks. #668
|
|
78
|
+
- **Workflow input files are dated, and the newer text wins.** `bkit workflows input` writes the issue description and each human comment as its own section, each comment with the time it was posted, and dates the plan, design and audit report sections by their last commit's author date (uncommitted changes count as newer than any commit). Every agent that reads an input file is told: where two sections disagree, the newer one wins, and older text still counts wherever nothing newer contradicts it. `###### bkit:ignore-earlier` is still the only way to drop text. `/bkit-build` also runs `@bkit-build-plan-convert` when the issue has comments posted after the plan's last commit, so those comments change the plan before any code; `workflows input` prints the count as `newerThanPlan`. #691
|
|
79
|
+
- **The change issue form shows the plan's full task block.** Its Tasks example and `.bkit/trackers.md` § Issue shapes show every field a plan task has: `CREATE` / `READ` / `UPDATE` / `DELETE`, `DEPENDS ON`, `DONE WHEN`, `TEST FIRST` and `TEST EXCEPTION`, with the group and per-task caps. Free text still works: the build converts it. Copy the updated `.github/ISSUE_TEMPLATE/bkit-change.yml` from `.bkit/templates/` if you use the form. #668
|
|
80
|
+
- **A `TEST EXCEPTION` written in an issue is a request the owner confirms.** The convert agent and `@bkit-plan-generate` copy it into the task word for word and never write one of their own. `bkit tests green` now checks who wrote an exception on a task with no `TEST FIRST` too: one last changed by a workflow step commit is an `exception-refused` gap, which verify marks `Fixable: false`, so the build stops at the Decision Pause. Accept replaces the field with your reason and the date, so its plan-only commit always has a change and git credits you. A plain `TEST FIRST: n/a — reason` is not checked. #668
|
|
81
|
+
- **Subagents carry their bkit rules in the prompt and read only what sits below `bkit:end`.** Each `.bkit/core/prompts/*.md` agent has a `**bkit Rules:**` block holding, word for word, the bkit rules it acts on. Its `**Rules:**` line now reads `.agents/rules.md` below `<!-- bkit:end -->` only (`Universal Rules`, skipping `Orchestrator Rules`): an agent that can search finds that line with `grep -n` and reads from there, so it never loads the bkit block. `bkit-build-plan-execute` also carries `Check gotchas first`. A rule every subagent must follow belongs under `## Project Rules` › `### Universal Rules`; `## Project Settings` still reaches subagents. Workflows still read all of `.agents/rules.md`. #666
|
|
82
|
+
- **A sentence in two or more prompts, or two or more workflows, has one master wording.** It is a clause in `.bkit/instructions.md` § Clauses, and `pnpm instructions:sync` keeps every copy in step: it rewrites near copies and old wordings, and the check fails on a prompt or workflow missing its clause. The cut-off was 5 prompts and 3 workflows; audit templates stay at 5. #684
|
|
83
|
+
- **Plan and audit templates hold shape only; the prompts that act on them carry the rules.** `docs/templates/bkit-plan.md` keeps its headings, tables, checkbox labels, owner callouts and the lines the engine parses, and drops every instruction block (37.4 KB to 15.7 KB, so every new plan is that much smaller). The 35 audit templates drop their shared boilerplate; `bkit-audit-generate` carries it once. `bkit-build-plan-execute` ticks every applicable Pre-Flight and gate box and continues without asking. The `Permissions`, `No placeholders` and `Process Improvements` report boxes each say in a few words what they check. Your `Project Instructions` below `bkit:end` still apply: step titles, numbers and the `Permissions` label are unchanged. #667
|
|
84
|
+
- **Nine rules join `.agents/rules.md`:** New file locations, UI design, Dependencies, Tests discriminate, Test-only files, Explicit logging, CLIs over dashboards, Server-side validation, Multi-store writes. They lived only in the plan template, so agents working without bkit now get them too. #667
|
|
85
|
+
- **Six rules are sharper.** R24 allows appending a log line to your own step output file with `>>`; R43 excepts standing audit parents; R61 lets docs-only landings push straight to `dev` through `bkit branches land`, with a PR only when the push is refused; R62 accepts an explicit empty merge body; R94 excepts a workflow's named decision points; R98 resolves `FID` from tracker markers, or from a `feat/{FID}` branch when no tracker is wired. #666
|
|
86
|
+
- **`bkit-utility-update-tracker` never comments on issues,** reads labels through the tracker MCP first, and lists bugs it finds under `## Found Bugs` for the orchestrator to file; `bkit-utility-update-roadmap` does the same and lists every container with its URL. #666
|
|
87
|
+
- **Every planner prompt that writes `TEST FIRST` names the per-task caps,** as do the issue shapes: 1 to `bkit.workflows.tasks.maxTestsPerTask` tests (default 10) across at most `bkit.workflows.tasks.maxTestFilesPerTask` test files (default 3), the caps `bkit tests plan-check` enforces. A test pins these defaults to the engine's. #667
|
|
88
|
+
- **The `**Code reads:**` line names `grep -l` before `grep -n`,** limits whole-file reads to short files or files being rewritten, and allows a re-read after context was summarised. Prompts with neither `Grep` nor `Bash` no longer carry it. The `**Tools:**` header label is now `**Verify tools:**`. #666
|
|
89
|
+
- **Install and upgrade write every `bkit` setting into `package.json`.** Each setting is now visible where you look for it. A missing key gets its default (for example `workflows.build.verify`, `prompts.roadmapNext: 25`, `testing.minPushPaths`, `workflows.worktree.copy`, the tracker progress and review states); a choice not made yet (`tracker.default`, `cloud.agent`, `tracker.github.project`, `providers.opencode.default`, ...) gets `""` or `[]`, which reads exactly like absent, so the tracker and cloud setup nudges still show. A key already set is never touched, nested blocks get their missing keys, and `bkit check` reports a missing one. #670
|
|
90
|
+
- **Fix loops ask you before each further round.** The build verify → fix-gaps loop and the build tests → diagnose → fix loop stop at the Decision Pause after a failed round while their limit has rounds left, instead of retrying on their own. The pause opens with the progress report and asks whether to run another fix round, worded so "yes" takes its recommendation; **Try again** runs exactly one more round, using the next strategy, and the fixer reads your answer. Whether a loop asks, and how many rounds it gets, are its ask point's `ask` and `maxAttempts` settings (#671). #670
|
|
91
|
+
- **`.bkit/stats.md` is committed.** The managed `.gitignore` block no longer ignores it, so commit the file after `bkit stats`. It holds no timestamp and changes only when the ledgers do. #683
|
|
92
|
+
- **`/bkit-ship` of `dev` or `main` prints the engine's refusal and stops.** It releases its lock first. `bkit worktrees setup` also refuses `main` in place for design, plan and build. #650
|
|
93
|
+
- **`api.github.com` is in the egress allowlist.** The engine's GitHub tracker calls need it on runtimes that filter egress. #675
|
|
94
|
+
|
|
95
|
+
### Fixed
|
|
96
|
+
|
|
97
|
+
- **`/bkit-debug` runs the integration gate when no e2e gate is declared.** Debug Step 3 now tries `bkit:gate:static-unit-integration` before `bkit:gate:static-unit`, so it runs the same gate as build; it used to skip integration tests and could report green on a failure build caught.
|
|
98
|
+
- **The `rm -rf` guard covers the home folder itself.** Every host denies `rm -rf` / `rm -fr` on `~`, `$HOME` and `${HOME}` (bare, with `/` or `/*`), as well as `/`. The hooks also catch `-Rf` and `-r -f`. Only `~/*` and `$HOME/*` were denied before.
|
|
99
|
+
- **`bkit check` passes after `bkit uninstall --opencode` or `--auto`.** A targeted uninstall resets the module's `bkit.providers.opencode` or `bkit.cloud.agent` keys to unset (`""`, `[]`) instead of deleting them, so check no longer reports them as missing.
|
|
100
|
+
- **`[force build]` now reaches CI on a pull request.** CI reads markers from the PR title on `pull_request` events, so the empty `[force build]` commit build Step 18 pushed was ignored. The new `bkit branches force-build` adds ` bkit [force build]` to the open PR's title, then pushes the empty marker commit, whose `synchronize` event starts the run that reads the title. It never amends, and a re-run does not push a second marker. Build calls it after `prs open` when the branch changes a `migrations/` or `migrate/` directory. The consumer CI template reads the marker differently from bkit's own `bkit-ci.yml`: the PR title on `pull_request`, else the head commit message, including on `workflow_dispatch`; bkit's own reads the head commit only on pushes to `main` / `dev`. #679
|
|
101
|
+
- **A finished debug run no longer forces the next run into SOAK.** Soak rows from a closed run used to count on the next run of the same `FID`. #678
|
|
102
|
+
- **A SOAK escalation survives a resumed debug run.** An escalation recorded only in `workflow-meta` used to be lost on resume, and the run restarted in NORMAL. #678
|
|
103
|
+
- **`bkit status route` reads a FAIL with no `failures` as `null`.** It used to print 0. #678
|
|
104
|
+
- **`/bkit-debug` no longer stages the whole tree for its CI-trigger commit.** It runs `git commit --allow-empty` only. On a feature branch, the design, plan, build and debug Failure Paths remove only files the run created by mistake, never other agents' changes. #666
|
|
105
|
+
- **A debug or build after a failed ship starts instead of stopping at Step 2.** A failed ship saves its record to `dev` and leaves the feature worktree as it was; the next resume rebase refused to start over those files (exit 9). `bkit worktrees setup` now commits what an earlier run left uncommitted before that rebase (`chore({FID}): carry the failed ship record left uncommitted bkit`, reported as `carriedSha`). An untracked log `dev` already holds is dropped first so `dev`'s copy wins (`carriedDropped`), and the `bkit.workflows.worktree.copy` entries (such as `.env`) are never committed. Exit 9 now means only that this commit was refused. #662
|
|
106
|
+
- **Failure handovers and close commits never commit the `bkit.workflows.worktree.copy` entries either.** `bkit workflows handover --push` on a feature branch and `bkit workflows close --message` used to commit the whole worktree, so a `.env` that setup copied in and the project had not gitignored could land in a pushed commit. Both now leave those entries out. #662
|
|
107
|
+
- **The ship naming warning fires on a run with no issue.** A branch not named for the `FID` now warns when `ISSUE_ID` is empty; an empty id used to match every branch name. #650
|
|
108
|
+
- **Build Step 15.9 and debug Step 11.9 kill-switch checks skip when `ISSUE_ID` is empty,** and ship Step 14.3's label calls skip on a merged run with no issue. #650
|
|
109
|
+
- **The build boundary gate (Step 7) and the debug local test run (Step 3) can pass their own format check.** Both wrote their test log straight into `docs/plans/{YYYYMM}/logs/{FID}/`, where the gate's `prettier --check .` found the half-written log and failed. They now log to the outbox and copy the finished log in. The `.prettierignore` template gains three `docs/plans/*/logs/*/` lines (`run-tests-*.md`, `build-subplan-gate-*.md`, `context-tests-local-*.md`); templates are copy-and-own, so a consumer that already adopted `.prettierignore` adds the three lines by hand. #650
|
|
110
|
+
|
|
111
|
+
### Removed
|
|
112
|
+
|
|
113
|
+
- **The `bkit-plan-complexity-split` subagent and plan Step 7 Complexity Split.** Groups of task blocks replace sub-plans. `bkit upgrade` deletes its host copies. #668
|
|
114
|
+
- **The chat-stats template (`.bkit/templates/scripts/stats/`).** An adopted `scripts/stats/` copy keeps working on its own; delete it if unused. #683
|
|
115
|
+
- **Three plan subagents: `bkit-plan-review-3`, `bkit-plan-scope-check-1` and `bkit-plan-scope-check-2`.** `/bkit-plan` runs `@bkit-plan-review-1`, `@bkit-plan-review-2` and one `@bkit-plan-scope-check` instead. `bkit upgrade` deletes their host copies; a `## Model Overrides` row naming one of them is reported as `model-override-unknown-agent` and can be deleted. #665
|
|
116
|
+
- **The five summary subagents: `bkit-plan-summary`, `bkit-design-summary`, `bkit-build-summary`, `bkit-debug-summary` and `bkit-ship-summary`.** `bkit workflows summary` writes the summary instead. `bkit upgrade` deletes their host copies; a `## Model Overrides` row naming one of them no longer matches an agent and can be deleted. Past `status.jsonl` and `.bkit/stats.jsonl` rows that name them stay as written. #682
|
|
117
|
+
- **Three build challenge subagents: `bkit-build-challenge-reconcile`, `bkit-build-challenge-remediate` and `bkit-build-challenge-tests`.** `bkit challenge merge` folds the findings into the plan, and Plan Execute fixes and tests them. `bkit upgrade` deletes their host copies; a `## Model Overrides` row naming one of them no longer matches an agent and can be deleted. Past `status.jsonl` rows that name them stay as written. #682
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
9
121
|
## [5.5.1] — 2026-10-22
|
|
10
122
|
|
|
11
123
|
### Breaking Changes
|
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. |
|
|
@@ -109,23 +109,23 @@ Every agent in each phase, in the order it runs and what it checks: [pipeline re
|
|
|
109
109
|
<p align="center">
|
|
110
110
|
<picture>
|
|
111
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
|
|
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
113
|
</picture>
|
|
114
114
|
</p>
|
|
115
115
|
|
|
116
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.
|
|
117
117
|
|
|
118
118
|
<!-- prettier-ignore -->
|
|
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 |
|
|
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 |
|
|
129
129
|
|
|
130
130
|
**Reading the table:**
|
|
131
131
|
|
|
@@ -149,7 +149,7 @@ Every agent in each phase, in the order it runs and what it checks: [pipeline re
|
|
|
149
149
|
</picture>
|
|
150
150
|
</p>
|
|
151
151
|
|
|
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.
|
|
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.
|
|
153
153
|
|
|
154
154
|
<a id="agents-and-ci"></a>
|
|
155
155
|
|
|
@@ -282,10 +282,10 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
282
282
|
|
|
283
283
|
### Engineering know-how, built in
|
|
284
284
|
|
|
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,
|
|
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).
|
|
286
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.
|
|
287
|
-
- **Big features are
|
|
288
|
-
- **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.
|
|
289
289
|
|
|
290
290
|
### It fits how you work
|
|
291
291
|
|
|
@@ -306,6 +306,8 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
306
306
|
|
|
307
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").
|
|
308
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.
|
|
309
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).
|
|
310
312
|
|
|
311
313
|
<a id="token-costs"></a>
|
|
@@ -314,17 +316,27 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
314
316
|
|
|
315
317
|
<p align="center">
|
|
316
318
|
<picture>
|
|
317
|
-
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-
|
|
318
|
-
<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%">
|
|
319
321
|
</picture>
|
|
320
322
|
</p>
|
|
321
323
|
|
|
322
|
-
**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)).
|
|
323
325
|
|
|
324
|
-
**
|
|
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.
|
|
325
327
|
|
|
326
|
-
|
|
327
|
-
|
|
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>
|
|
328
340
|
|
|
329
341
|
<!-- prettier-ignore -->
|
|
330
342
|
| Tool | How it works | Share of the bill saved | What went wrong |
|
|
@@ -337,10 +349,12 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
337
349
|
|
|
338
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.
|
|
339
351
|
|
|
340
|
-
</details>
|
|
341
|
-
|
|
342
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.
|
|
343
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.
|
|
344
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.
|
|
345
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.
|
|
346
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.
|
|
@@ -356,7 +370,7 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
356
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.
|
|
357
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.
|
|
358
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.
|
|
359
|
-
- **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.
|
|
360
374
|
|
|
361
375
|
## FAQ
|
|
362
376
|
|
|
@@ -391,17 +405,17 @@ No. [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code) i
|
|
|
391
405
|
Feature by feature against the main AI development frameworks, from spec toolkits to autonomous agents: [`.bkit/comparison.md`](.bkit/comparison.md#frameworks).
|
|
392
406
|
|
|
393
407
|
**Why doesn't bkit use a compression tool like caveman, Headroom or RTK?**
|
|
394
|
-
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).
|
|
395
409
|
|
|
396
410
|
<details>
|
|
397
411
|
<summary><strong>For engineers: what's under the hood</strong></summary>
|
|
398
412
|
|
|
399
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.
|
|
400
|
-
- **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.
|
|
401
|
-
- **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.
|
|
402
|
-
- **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.
|
|
403
417
|
- **One source, every host.** `.bkit/` renders `.claude/`, `.cursor/`, `.codex/`, `.agents/` (Antigravity) and `.opencode/`. `bkit check` is the CI drift gate.
|
|
404
|
-
- **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.
|
|
405
419
|
- **Per-agent pins.** Model and effort per agent, per provider ([`.bkit/prompts.md`](.bkit/prompts.md) § Models), immune to the session default.
|
|
406
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).
|
|
407
421
|
|
|
@@ -420,6 +434,7 @@ On real bkit sessions they saved 1–3% of the bill, and each changes what the a
|
|
|
420
434
|
| [`.bkit/templates.md`](.bkit/templates.md) | Templates ready to adopt |
|
|
421
435
|
| [`.bkit/lite.md`](.bkit/lite.md) | Lite workflows: shorter prompts for small changes |
|
|
422
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 |
|
|
423
438
|
| [`.bkit/comparison.md`](.bkit/comparison.md) | Comparison with other AI development frameworks and with _Agentic Design Patterns_ |
|
|
424
439
|
| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
|
|
425
440
|
|
|
@@ -444,7 +459,7 @@ pnpm bkit install --claude # pick your tools: --claude --cursor --codex --ant
|
|
|
444
459
|
Adopt the [templates](#templates) you want from `.bkit/templates/`, open an issue, and run the first step from your AI tool:
|
|
445
460
|
|
|
446
461
|
```text
|
|
447
|
-
/bkit-design
|
|
462
|
+
/bkit-design issue #123
|
|
448
463
|
```
|
|
449
464
|
|
|
450
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.
|