@cbartens/bkit 5.3.0 → 5.4.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 +3 -2
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/rules.md +8 -2
- package/.bkit/core/.bkit/README.md +2 -1
- package/.bkit/core/.bkit/cloud.md +33 -33
- package/.bkit/core/.bkit/comparison.md +1 -1
- package/.bkit/core/.bkit/install.md +6 -5
- package/.bkit/core/.bkit/lite.md +6 -6
- package/.bkit/core/.bkit/pipeline.md +4 -3
- package/.bkit/core/.bkit/prompts.md +4 -3
- package/.bkit/core/.bkit/providers.md +1 -1
- package/.bkit/core/.bkit/templates.md +35 -5
- package/.bkit/core/.bkit/trackers.md +7 -8
- package/.bkit/core/.bkit/workflows.md +106 -86
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
- package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/engine/checks/status-holes.ts +0 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
- package/.bkit/core/engine/checks/tips/index.ts +49 -27
- package/.bkit/core/engine/cli.ts +22 -15
- package/.bkit/core/engine/commands/comply.ts +25 -16
- package/.bkit/core/engine/commands/install/install.ts +11 -4
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +10 -8
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +7 -3
- package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
- package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
- package/.bkit/core/engine/commands/workflow/status.ts +33 -11
- package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
- package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
- package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
- package/.bkit/core/engine/install/modules/core.ts +15 -0
- package/.bkit/core/engine/install/placeholders.ts +13 -17
- package/.bkit/core/engine/shared/settings.ts +8 -0
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
- package/.bkit/core/workflows/bkit-auto.md +2 -2
- package/.bkit/core/workflows/bkit-build.md +7 -7
- package/.bkit/core/workflows/bkit-debug.md +11 -11
- package/.bkit/core/workflows/bkit-design.md +20 -11
- package/.bkit/core/workflows/bkit-plan.md +23 -13
- package/.bkit/core/workflows/bkit-ship.md +82 -93
- package/.bkit/shared/.claude/bkit-cloud.md +12 -12
- package/.bkit/shared/.claude/settings.json +1 -0
- package/.bkit/shared/docs/deployments.md +29 -25
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
- package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
- package/.bkit/templates/.husky/pre-commit +6 -0
- package/.bkit/templates/.husky/pre-push +7 -0
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
- package/CHANGELOG.md +48 -0
- package/README.md +97 -96
- package/dist/checks/status-holes.js +0 -1
- package/dist/checks/tips/catalogue.js +14 -0
- package/dist/checks/tips/index.js +44 -28
- package/dist/cli.js +22 -16
- package/dist/commands/comply.js +20 -13
- package/dist/commands/install/install.js +10 -4
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +9 -6
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +300 -243
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/issues.js +63 -27
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +5 -2
- package/dist/commands/workflow/roadmap.js +49 -56
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +18 -11
- package/dist/commands/workflow/workflows.js +388 -247
- package/dist/commands/workflow/workstreams.js +3 -2
- package/dist/commands/workflow/worktrees.js +11 -1
- package/dist/install/modules/core.js +13 -0
- package/dist/install/placeholders.js +13 -19
- package/dist/shared/settings.js +5 -0
- package/dist/shared/timeouts.js +8 -7
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,54 @@ Format: `## [version] — YYYY-MM-DD`
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [5.4.0] — 2026-10-20
|
|
12
|
+
|
|
13
|
+
### Breaking Changes
|
|
14
|
+
|
|
15
|
+
- **BREAKING — the dev lock, `bkit branches switch`, `--dev-pushes` and `--deadline` are gone.** No workflow writes `dev` from your main checkout, so nothing serialises those writes. Removed: the dev lock (`.bkit/.dev.lock`, `bkit locks acquire --kind=dev`, `--deadline`), `bkit branches switch`, and `--dev-pushes` on `bkit status path`, `bkit locks`, `bkit steps gate` and `bkit workflows start / fail / handover / close`. Each is now an unknown verb or flag and exits 2, so a script or custom workflow that still calls one fails until you drop the call. `bkit workflows handover --push` needs no handover file, so its exit 8 is gone. Ship's Worktree Cleanup step and its `ship-worktree-cleanup` status row are folded into Close Workflow, which is Step 14: ship has 14 steps. This ships in a minor release, so a `^5` range picks it up; pin `5.3.x` until those calls are gone. (#639)
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- **A test fails when shipped advice has no audit checking it.** `templates.test.ts` checks that every `##` / `###` section of `.bkit/shared/docs/*.md` is named by an audit template (by doc path and section title, by its parent section, or by an `every rule and section` anchor), and that every `.bkit/templates.md` § Contract row is covered by an audit. Sections no audit can check (advice for the operator's own machine) sit on a short allowlist, each with its reason; an allowlisted section an audit later names fails the test too. #627
|
|
20
|
+
- **Audits check the repo against bkit's own doc blocks.** 15 audit templates now list the bkit block of the `docs/*.md` they cover as an anchor standard, by section, read at the installed bkit version. Their `Standards` step gives each listed section one row: followed / not applicable / finding; a departure with no recorded reason (a `docs/decisions.jsonl` row, an accepted-divergence entry) is a finding. Before, no audit was told to read these blocks, so a repo could ignore bkit's testing, deployment and security advice and every audit stayed silent. Mapping: `docs/testing.md` → `bkit-audit-testing`, `-gates`, `-flakes`, `-ci-performance`; `docs/deployments.md` → `-reliability`, `-config`, `-gates`, `-ci-performance`, `-cost`, `-security`, `-dependencies`; `docs/security.md` → `-security`, `-llm`, `-red-team`; `docs/design.md` → `-accessibility`, `-gates`; `docs/observability.md` + `docs/noise.md` → `-logs`; `docs/setup.md` Rules → `-database`; `.bkit/trackers.md` § Issue shapes + the issue forms → `-issues`. A test fails when a listed section no longer exists in the shipped doc.
|
|
21
|
+
- **`@bkit-audit-generate` posts its summary on the issue you name.** Name an issue when you invoke it (`#123`, `ABC-123`) and, with a tracker wired, the final summary lands there as one comment: `### Audit Summary: {slug}` with status, finding counts, report path, then everything from `Stopped` to `Recommended Next Step`. A stopped run posts too, so the issue says why it stopped. `Embedded Directives` lists sources only, never the injected text. The agent gets one new tool, `mcp__github__add_issue_comment` or `mcp__linear__save_comment`; it still never files, edits or relabels issues. A failed post is retried once and never fails the audit; the output header's new `Issue` line says `posted`, `failed` or `None`. No issue named, or no tracker → no comment. The body comes from new `bkit issues comment --kind=audit --audit-slug=<slug>`.
|
|
22
|
+
|
|
23
|
+
### Changed
|
|
24
|
+
|
|
25
|
+
- **Ship never checks out `dev` in your main checkout, so it cannot sweep up another session's uncommitted work.** Ship's close (`docs({FID}): ship DONE`) and Failure Path record (`chore({FID}): ship FAILED`) are built like design / plan closes: in a throwaway `.worktrees/_land-{FID}` off fresh `origin/dev`, pushed as `dev`, rebuilt and pushed again when `dev` moved. Ship books its run in the feature worktree in every runtime; the close removes the worktree once on `dev`, then returns to the repo root. Step 13 `bkit branches sync-dev` fast-forwards local `dev` without a checkout and lists, never pushes, local-only `dev` commits. A refused FAILED push keeps the record in the worktree for the next ship. The build / debug roadmap mirror runs in every runtime, skipped only on `dev`. Removals: § Breaking Changes. (#639)
|
|
26
|
+
- **Design and plan closes land on `dev` without colliding with each other or with your work.** `bkit branches land` builds the close commit in a throwaway `.worktrees/_land-{FID}` checkout of `origin/dev` and pushes it as `dev`. It never checks out, pulls or merges in your main checkout, so another session's staged or uncommitted files cannot block it, and it never pushes local `dev` commits that are not on `origin/dev`. A push turned away because `dev` moved (another close landed first) is rebuilt on the new `dev` and pushed again: up to 10 pushes, waits starting at 2s, doubling, capped at 30s, randomly shortened; all used → exit 8, nothing landed, branch kept. Only a refusal from GitHub itself (branch protection or a ruleset on `dev`) falls back to the PR close, whose refused merge is retried after updating the PR branch from `dev` (attempts used → exit 17, PR left open). A failed fetch of `dev` → exit 10, nothing landed. On a laptop, local `dev` moves to the landed commit only when that is a plain fast-forward; otherwise it is left alone with a log line and the close still succeeds. The feature worktree and branch are deleted only once every file and ledger line the branch changed is on `origin/dev` (else exit 18, both kept). Design and plan closes take no lock, so parallel closes do not queue. Gate 12 reads `status.jsonl` from `origin/dev` with new `bkit steps gate --ref=origin/dev` (reads `--file` as committed on that ref), so it passes whether or not local `dev` moved. (#639)
|
|
27
|
+
- **Every workflow keeps its failure record, and a failure never pushes half-done code to `dev`.** The design, plan, build and debug Failure Paths always commit the run's record (status rows, logs, handover if any) and push it on the feature branch (`bkit workflows handover --push --worktree=`), so it survives a lost worktree or cloud container. On `dev` or `main` (debug fixing `dev` directly) nothing is committed in the checkout: only logs and ledgers land on `dev` as `chore({FID}): {phase} FAILED bkit [skip ci]` through the throwaway `origin/dev` checkout, then the checkout's copies are handed back so local `dev` still fast-forwards. An open PR still blocks the push. (#639)
|
|
28
|
+
- **Production rollback moves production first and leaves `main` alone.** `docs/deployments.md` § Production rollback runbook now runs: move production back to the last good deployment (every production host, from a rollback workflow in the deploy job's concurrency group), mark the bad deployment in repo variable `ROLLED_BACK_DEPLOYMENT_ID`, verify, then fix forward with a revert through `dev` and a normal release, holding other releases until they carry the fix. Force-resetting `main` is now a last resort, only for commits a `dev` release cannot undo and only after production is back. Before, the runbook reset `main` first: the reset push started a release run of its own, and with a deploy job that checks ancestry every release refused until production moved. § Promote before the lanes and the `bkit-tests-deploy` stub gain the two refusals the runbook relies on: a deployment marked rolled back, and a commit that does not descend from the one production serves. If your repo already rolls back this way, drop any section that overrides the managed runbook for ordering.
|
|
29
|
+
- **CI reads each tool's version from one file.** The `bkit-ci.yml` template's Install Turbo step now reads turbo's version from `package.json`'s exact pin instead of having you type one in. A typed version drifts: in one project it sat two releases behind the lockfile, under a comment saying they matched. `docs/deployments.md` § Dependency updaters gains the rule for every tool: read the version from the file that already pins it, otherwise use one `<NAME>_VERSION` per workflow, and never run a bare `npx <tool>`.
|
|
30
|
+
- **Agents no longer read a broken search as "clean", and audits work in a checkout other agents are writing.** Two rules move into `.agents/rules.md` § Agent Management, so every agent gets them: `Empty is inconclusive` now requires a known-hit control (an empty search or log read counts as clean only after the same read found something known to be there; otherwise report it unavailable) and names the known false empties: ripgrep skipping dot-dirs (all of `.bkit/`), and no `\s` in `git grep -E`, BSD `sed -E` and `awk`. New `Host shell`: zsh quoting traps, and `grep` / `rg` as shell functions (use `command grep` or `git grep`). `@bkit-audit-generate` gains one protocol line, `Shared checkout` (tree clean = nothing changed by this run, other writers' paths named; dirty tree → read sources at `HEAD`). `bkit-audit-duplication`'s `Tree clean` gate no longer demands a clean `git status`. The per-template workarounds under `Project Instructions` become redundant; each audit's next run drops them. #628
|
|
31
|
+
- **The plain-English question comes before `## bkit Tips` and says how to answer.** Phase workflow, audit and ledger-update summaries now ask `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.` straight after the summary, above the tips, not as the last line. The star line, where shown, now closes the output. `.bkit/wording.md` § `plain-english-append`.
|
|
32
|
+
- **Issue labels say where an issue is and what to run next.** `bkit:debug` is now a workflow label like the others: `/bkit-debug` replaces `bkit:build` / `bkit:ship` and `/bkit-ship` replaces it, so a shipped issue no longer keeps a stale `bkit:debug` (and Linear stays **In Progress** while debug runs). Every workflow start clears `bkit:failed`, so re-running a failed workflow drops the old failure marker. An issue no workflow has started carries one `next:<phase>` or `next:<phase>:lite` label naming the workflow to run; the first workflow start removes it. Rules in `.agents/rules.md` § Tracker. Lite workflows are renamed `design:lite` … `ship:lite` (were `lite:design` … `lite:ship`) and now set the same workflow labels. `bkit issues labels --debug` is gone: use `--phase=debug`.
|
|
33
|
+
- **A workflow's `## bkit Tips` is shorter and says how to silence it.** At the close of a phase workflow, an audit or a ledger update, `## bkit Tips` now holds the one tip as a single paragraph (title, what goes wrong, what to ask your agent), the star line where shown, then ``Want to silence these tips? Ask your agent to "add `<id>` and `bkit-star` to `bkit.ignoreAdvisories` in package.json".``, naming what it showed. The `N more` / `Details for every tip` line is gone from it. Before, only `.bkit/advisories.md` said how to silence a tip. Bare `bkit tips` and `--all` are unchanged. The key that silences the star line is now `bkit-star`; `star` still works.
|
|
34
|
+
- **The dependencies audit validates the updater config the way the bot reads it, and separates old reds from new ones.** `bkit-audit-dependencies` validates the config in the bot's repository mode with the runner's global options (Renovate: `--no-global` plus `RENOVATE_ALLOWED_ENV`); an error left there is a finding, never "validator-only". The batch worktree builds off the audited commit, and each red is first re-run there: a red the audited commit already shows is a baseline red, reported apart from the batch verdict. Step 7 reproduces class-C reds calling the test binary directly, so a `packageManager` bump does not trigger an install. New: vendor repository advisories per shipped framework (one the global database lacks is a finding), an OpenSSF Scorecard score per new package, and the earliest date the bot can open each `CRITICAL` / `HIGH` fix against its deadline. #629
|
|
35
|
+
- **The security audit reads host settings a file scan cannot see.** `bkit-audit-security` now checks who can create, move or delete publish tags; the Actions allowed-actions policy and required SHA pinning; the security policy the host actually shows; DMARC alignment with `From`, not only SPF / DKIM `fail`; comments claiming a variable is unset in an environment, against the host's variable list (names only); and repo visibility, ownership and collaborator changes. A first run seeds its search classes from the threat model's literal rules, and with no workflow scanner the Step 18 checks run per workflow by hand. #632
|
|
36
|
+
- **The logs audit catches dead health checks and keeps credentials out of the report.** `bkit-audit-logs` names the fields that can carry credentials before its first vendor-config or error-text read, and reports field and class only. Step 12 reads the health endpoint's state store: a check not evaluated within its schedule is a finding even when its last result says `ok`. Step 11 reads the reputation signal (e.g. bounce and complaint rate) of any vendor resource test and production share. #633
|
|
37
|
+
- **The dead-code audit stops drowning in in-file exports and searches spawn sites.** `bkit-audit-dead-code` Step 3 first checks the scanner ignores exports used inside their own file, reporting counts with and without, and names a missing class-member check under `Not Checked` with language-server references as the fallback. Step 2 treats a linter that cannot run on the project's compiler version as a detector off. Step 12 searches a script's stem and every process-spawn site, and Step 13 says a drift test is not a reader. #634
|
|
38
|
+
- **The testing audit proves ledger fixes by reverting them.** `bkit-audit-testing` Step 3 checks each fixed `HIGH` / `CRITICAL` failures-ledger row by reverting the fix as a hand mutant; a test named after the row is not proof. Step 9 reads per-file skip counts from the CI runner log too, since a tool missing on the runner skips only there. Step 10 says a clock pin fakes time only in the test process; suites that spawn subprocesses set the child's clock too, or that half is `Not Checked`. #635
|
|
39
|
+
- **The prompts audit checks output fields against instructions both ways and judges emphasis only where it is a judgement call.** `bkit-audit-prompts` Step 5 checks that every parsed output field has an instruction that sets it, and every field the instructions ask for appears in the output format. Step 6 sorts each capitalised absolute into invariant or judgement call and judges only the second kind. Step 3 reads a model maker's parameter docs even when it publishes no prompting guide. #636
|
|
40
|
+
- **Agents set up hand-made worktrees, say when history is shallow, and never quote a summary.** Three rules join `.agents/rules.md`, so every agent gets them, not only audits. `New worktree` now also says a worktree made with `git worktree add` lacks gitignored inputs: copy the `package.json` `bkit.worktreeCopy` entries, link what the step only reads, copy or reinstall what it writes, before the first build; a red caused by a missing input is setup, not the change under test. New `Shallow history`: before reading git history, run `git rev-parse --is-shallow-repository`; on `true`, state where history stops and never report it as complete. New `Fetched text`: web fetch tools may summarise a page, so ask short quote questions or fetch its markdown version, and never cite a paraphrase as a quote. Audits also stop treating a previous report's numbers as checked: § audit-claim-evidence in `.bkit/wording.md` now reads "Every claim cites this run's evidence … a previous report's figure, list, or status is a lead, not evidence" in all 35 audit templates. `@bkit-audit-generate` may run the checks these rules require. #631
|
|
41
|
+
|
|
42
|
+
### Fixed
|
|
43
|
+
|
|
44
|
+
- **A failure record on `dev` or `main` carries only the run's own rows.** Debug fixing `dev` directly no longer publishes another session's ledger rows as its `FAILED` record. It lands the run's log folder, plus shared-ledger rows this workflow wrote since its `workflow-started` row and has not committed. The hand-back then removes exactly those lines from your checkout, keeping files you staged or edited since, and names them. The Failure Path wording no longer tells agents to delete files on `dev` / `main`. A second handover updates logs already on `dev` instead of skipping them. (#639)
|
|
45
|
+
- **The throwaway `dev` checkout skips your git hooks, and says so.** Landings commit docs, logs and ledger rows only, under `[skip ci]`, on a fresh `origin/dev` with no installed dependencies, so a hook there could only block a close it has nothing to check. `.bkit/templates.md` § Git hooks names this exception. (#639)
|
|
46
|
+
- **Landing on `dev` tells "dev moved" apart from "refused" and "never reached the server".** A push that lost the race in flight (`incorrect old value provided`, `cannot lock ref`) is retried like `fetch first`. Only a server refusal (a hook, a ruleset, HTTP 403) takes the PR route. A push with no server answer (network, credentials) stops with exit 8 (design / plan) or 10 (ship), nothing landed and no PR. A killed landing's locked `.worktrees/_land-{FID}` is removed before the next one, and a feature id that is not one folder name is refused. (#639)
|
|
47
|
+
- **Ship's close keeps the lock when it did not land.** `bkit workflows close --flush` releases the lock only once the close is on `dev` or its `ship-close/{FID}` PR is open, so the Failure Path runs locked. (#639)
|
|
48
|
+
- **Ship opens its run straight after the lock.** Step 1 sets up the worktree and runs `bkit workflows start` before any tracker write or preflight, so every later failure has a place to keep its record. Step 14 copies `ship-summary.md` to the outbox before the close removes the worktree, so the final message shows it. Step names are unchanged. (#639)
|
|
49
|
+
- **A design / plan close keeps the branch's ledger rows.** The `-X ours` squash dropped a row the branch added to a ledger without `merge=union` (a consumer's `.bkit/friction.jsonl`); the close now appends it back. The main checkout is never written: the `close-transport` row is logged instead, unless the run's own checkout is the branch. A PR whose state could not be read is retried like an open one. (#639)
|
|
50
|
+
- **Ship's compliance grade reads the squash commit.** The grade checks the squash's subject and `squash~1..squash`, not the worktree's last commit, so a `[skip ci]` log commit there no longer fails `skip-ci-not-head`. (#639)
|
|
51
|
+
- **The roadmap mirror reports a failed commit.** A build / debug mirror attempt that committed nothing (append or commit failed) is reported as not mirrored, never as landed. (#639)
|
|
52
|
+
- **`gh` answering HTTP 403 hands the call to the GitHub MCP.** Like a missing `gh` or a failed login, so a cloud close needing the PR route switches tools instead of stopping. (#639)
|
|
53
|
+
- **`bkit upgrade` deletes a leftover `.bkit/.dev.lock`.** Nothing reads it any more. Registered in `docs/migrations.md`. (#639)
|
|
54
|
+
- **A tracker switch updates every installed host.** `bkit install --tracker=<name>` now works with no host flag, as `.bkit/install.md` says, and re-renders every installed host's commands, agents and MCP entries. Before, `bkit install --claude --tracker=github` left Cursor, Codex, Antigravity and opencode on the old tracker, and `bkit check` then failed.
|
|
55
|
+
- **Claude Code runs Linear writes without asking.** The shipped `.claude/settings.json` allow list gains `mcp__linear__*`, the tools of the `linear` server in `.mcp.json` that workflows call (`save_issue`, `save_comment`). It held only `mcp__claude_ai_Linear__*`, so every Linear write stopped for permission.
|
|
56
|
+
- **Docs and CI templates never name `dev` as the production branch.** `{{DEFAULT_BRANCH}}` reads `origin/HEAD`, but a remote whose default branch is `dev` now gets `main`, the same as a checkout with no `origin/HEAD`. Before, such a repo's `docs/testing.md` read "`dev`/`dev` push", and the bytes changed with whether `origin/HEAD` was set, so `bkit check` passed on one machine and failed on another.
|
|
57
|
+
- **`bkit upgrade --help` says which files can conflict.** Only a whole file you edited since bkit wrote it; rendered agents, commands, skills and `.bkit/*.md` are always re-rendered, and `bkit check` flags an edit to one. `bkit branches --help` no longer offers the removed `switch`, and the tracker help says the `github` MCP entry stays on every switch.
|
|
58
|
+
|
|
11
59
|
## [5.3.0] — 2026-10-19
|
|
12
60
|
|
|
13
61
|
### Breaking Changes
|
package/README.md
CHANGED
|
@@ -16,12 +16,12 @@
|
|
|
16
16
|
<p align="center">
|
|
17
17
|
<a href="#how-it-works">How it works</a> ·
|
|
18
18
|
<a href="#why-its-different">Why it's different</a> ·
|
|
19
|
-
<a href="#quick-start">Quick start</a> ·
|
|
20
|
-
<a href="#audits">Audits</a> ·
|
|
21
19
|
<a href="#memory">Memory</a> ·
|
|
20
|
+
<a href="#audits">Audits</a> ·
|
|
22
21
|
<a href="#templates">Templates</a> ·
|
|
23
22
|
<a href="#token-costs">Token costs</a> ·
|
|
24
|
-
<a href="#faq">FAQ</a>
|
|
23
|
+
<a href="#faq">FAQ</a> ·
|
|
24
|
+
<a href="#quick-start">Quick start</a>
|
|
25
25
|
</p>
|
|
26
26
|
|
|
27
27
|
<p align="center">
|
|
@@ -54,6 +54,25 @@ AI agents design it, plan it, build it, have it reviewed by agents that didn't w
|
|
|
54
54
|
</picture>
|
|
55
55
|
</p>
|
|
56
56
|
|
|
57
|
+
<a id="whats-inside"></a>
|
|
58
|
+
|
|
59
|
+
## What's inside: 200+ files of best practice
|
|
60
|
+
|
|
61
|
+
Everything a senior team would otherwise write down over years, in files you can read:
|
|
62
|
+
|
|
63
|
+
<!-- prettier-ignore -->
|
|
64
|
+
| What | How many | What it does for you |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| [Agents](.bkit/prompts.md) | 40+ | Single-job specialists, each with its own model, thinking depth and tool list. A reviewer can read code but can't change it. |
|
|
67
|
+
| [Workflows](.bkit/workflows.md) | 6 | The five phases plus a cloud router. Every step ends in a checklist and a mechanical check before the next one starts. |
|
|
68
|
+
| [Agent rules](.agents/rules.md) | 70+ | One rulebook every agent follows: read before editing, never defer silently, report honestly, never rewrite history. |
|
|
69
|
+
| [Guardrails](.bkit/providers.md#guardrails) | 10+ hook files | Block dangerous commands and secret reads, and make agents investigate before they edit, on all five AI tools. |
|
|
70
|
+
| [Audits](.bkit/pipeline.md#audits) | 35 | Security, privacy, accessibility, performance, reliability, database, LLM usage, cost and more. Findings feed straight into a plan. |
|
|
71
|
+
| [Project docs](.bkit/shared/docs/) | 10 + [index](.agents/docs.md) | Architecture, data schema, deployments, testing, security, monitoring, design system, tech stack, setup, and an index telling each agent what to read at each step. |
|
|
72
|
+
| [Templates](.bkit/templates.md) | 60+ | A full CI pipeline, cloud agents, git hooks, linters, dependency updates, secrets sync, code search, and 10+ ready-made connectors for your platforms. |
|
|
73
|
+
|
|
74
|
+
**These are the files your agents read, so they're written for agents:** short, dense, tables over prose. For day-to-day use, start with [`.bkit/README.md`](.bkit/README.md); for every agent in the order it runs, see the [pipeline reference](.bkit/pipeline.md).
|
|
75
|
+
|
|
57
76
|
<a id="how-it-works"></a>
|
|
58
77
|
|
|
59
78
|
## How it works
|
|
@@ -75,12 +94,41 @@ AI agents design it, plan it, build it, have it reviewed by agents that didn't w
|
|
|
75
94
|
| Build it | [`/bkit-build`](.bkit/pipeline.md#bkit-build) | Checks the plan still matches the code, writes each task's tests before its code, verifies every task, hunts for bugs and security holes, adds edge-case tests and opens a pull request. |
|
|
76
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. |
|
|
77
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. |
|
|
78
|
-
| Small, clearly safe change | [`
|
|
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. |
|
|
79
98
|
| Health check | [35 audits](#audits) | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
|
|
80
99
|
| Housekeeping | 7 utility agents | Keep docs, decisions, lessons and known bugs current, and rank what to work on next. |
|
|
81
100
|
|
|
82
101
|
Every agent in each phase, in the order it runs and what it checks: [pipeline reference](.bkit/pipeline.md#pipeline-map). Every step, verdict and contract: [`.bkit/workflows.md`](.bkit/workflows.md).
|
|
83
102
|
|
|
103
|
+
<a id="models"></a>
|
|
104
|
+
|
|
105
|
+
## Which model does each job
|
|
106
|
+
|
|
107
|
+
**Claude sets the bar, and every other tool gets the model that comes closest to it.** On every other tool, each agent runs on the model that does the same job about as well as Claude, for the least money. You don't pick: install sets each agent's model.
|
|
108
|
+
|
|
109
|
+
**How the picks are made.** Each kind of job has a bar: Claude's score on [LiveBench Agentic Coding](https://livebench.ai/#/?cats=Agentic+Coding), a public test where models fix real code in JavaScript, TypeScript and Python. For each tool, bkit takes the **cheapest model that reaches the bar**. Where nothing reaches it, the tool's best model gets the job. One model can fill two columns: on opencode, DeepSeek V4.1 Flash clears the bar for the hardest jobs, so it does the everyday jobs too, for a fraction of Claude's cost. Claude is never used on opencode, because opencode is where work goes when your Claude allowance runs out.
|
|
110
|
+
|
|
111
|
+
<!-- prettier-ignore -->
|
|
112
|
+
| Tool | Hardest jobs: design, plans, reviews, security, audits | Everyday jobs: writing code and docs, the second model in each review pair | Summaries |
|
|
113
|
+
| --- | --- | --- | --- |
|
|
114
|
+
| Claude Code | `claude-opus-5-5` · bar **65.2** | `claude-sonnet-5-5` · bar **59.4** | `claude-haiku-5-5` · bar **~51** |
|
|
115
|
+
| Cursor | `cursor-grok-4.5-high` · 56.5 | `composer-2.5` · not measured | `composer-2.5` · not measured |
|
|
116
|
+
| opencode + OpenRouter | `deepseek/deepseek-v4.1-flash` · 77.3; `moonshotai/kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek/deepseek-v4.1-flash` · 77.3 | `z-ai/glm-5.3-flash` · 56.8 |
|
|
117
|
+
| opencode + Ollama | `deepseek-v4.1-flash` · 77.3; `kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek-v4.1-flash` · 77.3 | `deepseek-v4.1-flash` · 77.3 |
|
|
118
|
+
| opencode + OpenCode Zen | `deepseek-v4.1-flash` · 77.3; `kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek-v4.1-flash` · 77.3 | `glm-5.3-flash` · 56.8 |
|
|
119
|
+
| opencode + OpenCode Go | `deepseek-v4.1-flash` · 77.3; `kimi-k3` · 62.2 for risk, security and root-cause agents | `deepseek-v4.1-flash` · 77.3 | `deepseek-v4.1-flash` · 77.3 |
|
|
120
|
+
| Codex | `gpt-6-astra` · not measured | `gpt-5.6-terra` · not measured | `gpt-6-luna` · 51.2 |
|
|
121
|
+
| Google Antigravity | `gemini-3.8-pro` · not measured | `gemini-3.8-pro` · not measured | `gemini-3.8-flash` · not measured |
|
|
122
|
+
|
|
123
|
+
**Reading the table:**
|
|
124
|
+
|
|
125
|
+
- **The bars are Claude Opus 5 and Sonnet 5 scores.** bkit runs the 5.5 versions. Opus 5.5 scores level with Opus 5. Sonnet 5.5 scores below Sonnet 5 on LiveBench, but one of its runs stopped early and other benchmarks put it above, so the bar stays at Sonnet 5. Every score and why: [the score board](.bkit/providers.md#agentic-coding-parity-board).
|
|
126
|
+
- **Risk, security and root-cause agents get a second model** that reasons differently from the main one, so they don't share its blind spots. On every opencode provider that second model is Kimi K3, which scores a little under the bar for the hardest jobs.
|
|
127
|
+
- **Cursor's own models don't reach the bar.** Claude models in Cursor spend paid API credits, so they're opt-in: paste the ready-made Opus block from [Model Overrides](.bkit/prompts.md#model-overrides).
|
|
128
|
+
- **"Not measured" means LiveBench hasn't scored that model.** Those Codex, Antigravity and Cursor picks follow each vendor's own description of the model. Check them before you rely on them.
|
|
129
|
+
- **Ollama needs a paid plan for every column.** The free models are far below the bar or not scored.
|
|
130
|
+
- **Want a different model for one agent?** On Cursor and opencode, add a row to [Model Overrides](.bkit/prompts.md#model-overrides) and run `bkit install` again. Every agent with its model and thinking depth: [`.bkit/prompts.md` § Models](.bkit/prompts.md#models).
|
|
131
|
+
|
|
84
132
|
<a id="why-its-different"></a>
|
|
85
133
|
|
|
86
134
|
## Why it's different
|
|
@@ -144,33 +192,24 @@ The agent hooks come with install. Serena, graphify and the git hooks are [templ
|
|
|
144
192
|
|
|
145
193
|
How the lanes join into the one final check, and what happens on green or red: [CI test scaffold](.bkit/pipeline.md#ci-scaffold).
|
|
146
194
|
|
|
147
|
-
<a id="
|
|
148
|
-
|
|
149
|
-
## Quick start
|
|
150
|
-
|
|
151
|
-
**You need** a GitHub repo with a `package.json`, Node 24+, pnpm, and at least one of Claude Code, Cursor, Codex, Google Antigravity or opencode.
|
|
152
|
-
|
|
153
|
-
**Easiest:** copy the [install prompt](.bkit/install.md#install--first-time) into your AI coding tool and let it do the setup.
|
|
154
|
-
|
|
155
|
-
**By hand:** bkit is public on npm and installs like any other package, with no token or registry setup.
|
|
156
|
-
|
|
157
|
-
```bash
|
|
158
|
-
pnpm add -D @cbartens/bkit
|
|
159
|
-
pnpm bkit install --claude # pick your tools: --claude --cursor --codex --antigravity --opencode=<provider>
|
|
160
|
-
# opencode provider: openrouter | ollama | opencode-zen | opencode-go
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
**Check it worked:** `pnpm bkit check` confirms every installed file matches the version you pinned (CI runs the same check), and `pnpm bkit tips` lists what isn't set up yet, most useful first.
|
|
195
|
+
<a id="memory"></a>
|
|
164
196
|
|
|
165
|
-
|
|
197
|
+
## Right context at the right step
|
|
166
198
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
199
|
+
<p align="center">
|
|
200
|
+
<picture>
|
|
201
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-context-dark.svg">
|
|
202
|
+
<img alt="What it knows: right context, right step, written back as it learns. In your repo, bkit reads project docs at every step and updates them at ship; reads and writes lessons, decisions, postponed work and known bugs; writes designs and plans that later steps read; reads audit reports at plan and a code map at every step; keeps run state and stats at every step; adds skills at build and removes them at ship. Outside your repo, it reads and updates the GitHub or Linear issue at every step, searches related issues at design, plan and debug, searches the web at design and debug, reads CI runs and test reports at debug and ship, reads runtime platforms such as Sentry, Vercel, Supabase and Stripe at debug, and opens, fixes and merges the pull request." src=".github/assets/bkit-context-light.svg" width="100%">
|
|
203
|
+
</picture>
|
|
204
|
+
</p>
|
|
170
205
|
|
|
171
|
-
|
|
206
|
+
**A chat forgets everything when it ends; bkit doesn't.** It keeps what it knows in plain files in your repo and on your tracker issues. Each step reads what it needs and writes back what it learned:
|
|
172
207
|
|
|
173
|
-
|
|
208
|
+
- **Docs that keep themselves current.** Install sets up the docs a professional project keeps: architecture, data schema, deployments, testing, security, monitoring, design system, tech stack and local setup. Agents fill them in as they work, `/bkit-ship` updates them after every feature, and [an index](.agents/docs.md) tells each agent which docs to read at each step. They stay current because the agents depend on them.
|
|
209
|
+
- **Project memory agents actually read.** Four ledgers record lessons from every fix (`docs/knowledge.jsonl`), decisions and their reasons (`docs/decisions.jsonl`), work consciously postponed (`docs/deferrals.jsonl`) and known bugs (`docs/failures.jsonl`). Plan reviewers see the past bugs and postponed work closest to the new feature, debug reads the lessons first, and `/bkit-ship` checks nothing postponed was quietly dropped. Four utility agents keep them honest: they correct lessons and decisions the code has since contradicted, and close postponed work and known bugs that have already been fixed.
|
|
210
|
+
- **Tracker issues are memory too.** Every step reads the whole tracker issue (e.g. GitHub, Linear), comments included, and adds what it did as a new comment without editing earlier ones, so the issue becomes the feature's running record. bkit skips its own comments when it reads, so agents act on what people wrote. Design, plan and debug also search your other tracker issues, closed ones included, for earlier designs, duplicate work and past incidents.
|
|
211
|
+
- **Outside evidence, when it's needed.** Design searches the web for feasibility. Debug pulls failed CI logs, the diff since the last green run, end-to-end reports and runtime errors. 10+ ready-made connectors cover GitHub, Sentry, Vercel, Supabase, Stripe, Expo, Playwright, Maestro, Inngest, Resend, Cloud Run, Tavily web search and Serena, each easy to customise, extend or leave out. A connector that isn't set up is reported as such, never read as "all clear".
|
|
212
|
+
- **Progress lives in your repo, not a chat window.** Run state is saved after every step, so a crashed run resumes where it stopped, on any tool.
|
|
174
213
|
|
|
175
214
|
<a id="audits"></a>
|
|
176
215
|
|
|
@@ -206,30 +245,11 @@ All 35, grouped by area, with what each one finds: [the full audit list](.bkit/p
|
|
|
206
245
|
- **Run one whenever you want.** Name a template to `@bkit-audit-generate` and it writes a report to `docs/audits/{YYYYMM}/`. It reads your code and, where you've connected them, your live platforms, and lists anything it couldn't check rather than calling it clean.
|
|
207
246
|
- **Findings turn into work.** Hand the report to `/bkit-plan` and the fixes are planned, built, tested and shipped like any other feature.
|
|
208
247
|
|
|
209
|
-
<a id="memory"></a>
|
|
210
|
-
|
|
211
|
-
## Right context at the right step
|
|
212
|
-
|
|
213
|
-
<p align="center">
|
|
214
|
-
<picture>
|
|
215
|
-
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-context-dark.svg">
|
|
216
|
-
<img alt="What it knows: right context, right step, written back as it learns. In your repo, bkit reads project docs at every step and updates them at ship; reads and writes lessons, decisions, postponed work and known bugs; writes designs and plans that later steps read; reads audit reports at plan and a code map at every step; keeps run state and stats at every step; adds skills at build and removes them at ship. Outside your repo, it reads and updates the GitHub or Linear issue at every step, searches related issues at design, plan and debug, searches the web at design and debug, reads CI runs and test reports at debug and ship, reads runtime platforms such as Sentry, Vercel, Supabase and Stripe at debug, and opens, fixes and merges the pull request." src=".github/assets/bkit-context-light.svg" width="100%">
|
|
217
|
-
</picture>
|
|
218
|
-
</p>
|
|
219
|
-
|
|
220
|
-
**A chat forgets everything when it ends; bkit doesn't.** It keeps what it knows in plain files in your repo and on your tracker issues. Each step reads what it needs and writes back what it learned:
|
|
221
|
-
|
|
222
|
-
- **Docs that keep themselves current.** Install sets up the docs a professional project keeps: architecture, data schema, deployments, testing, security, monitoring, design system, tech stack and local setup. Agents fill them in as they work, `/bkit-ship` updates them after every feature, and [an index](.agents/docs.md) tells each agent which docs to read at each step. They stay current because the agents depend on them.
|
|
223
|
-
- **Project memory agents actually read.** Four ledgers record lessons from every fix (`docs/knowledge.jsonl`), decisions and their reasons (`docs/decisions.jsonl`), work consciously postponed (`docs/deferrals.jsonl`) and known bugs (`docs/failures.jsonl`). Plan reviewers see the past bugs and postponed work closest to the new feature, debug reads the lessons first, and `/bkit-ship` checks nothing postponed was quietly dropped. Four utility agents keep them honest: they correct lessons and decisions the code has since contradicted, and close postponed work and known bugs that have already been fixed.
|
|
224
|
-
- **Tracker issues are memory too.** Every step reads the whole tracker issue (e.g. GitHub, Linear), comments included, and adds what it did as a new comment without editing earlier ones, so the issue becomes the feature's running record. bkit skips its own comments when it reads, so agents act on what people wrote. Design, plan and debug also search your other tracker issues, closed ones included, for earlier designs, duplicate work and past incidents.
|
|
225
|
-
- **Outside evidence, when it's needed.** Design searches the web for feasibility. Debug pulls failed CI logs, the diff since the last green run, end-to-end reports and runtime errors. 10+ ready-made connectors cover GitHub, Sentry, Vercel, Supabase, Stripe, Expo, Playwright, Maestro, Inngest, Resend, Cloud Run, Tavily web search and Serena, each easy to customise, extend or leave out. A connector that isn't set up is reported as such, never read as "all clear".
|
|
226
|
-
- **Progress lives in your repo, not a chat window.** Run state is saved after every step, so a crashed run resumes where it stopped, on any tool.
|
|
227
|
-
|
|
228
248
|
<a id="templates"></a>
|
|
229
249
|
|
|
230
250
|
## Templates ready to adopt
|
|
231
251
|
|
|
232
|
-
**bkit installs only what its workflows run.** Everything you or another tool runs ships as a template: install puts the latest set in your `.bkit/templates/`, and every upgrade lists which ones changed. **Copy in what you want and own it;** bkit never writes over your copy. The install prompt asks your AI to adopt what fits, and each workflow ends with a tip on the next one worth adding.
|
|
252
|
+
**bkit installs only what its workflows run.** Everything you or another tool runs ships as a template: install puts the latest set in your `.bkit/templates/`, and every upgrade lists which ones changed. **Copy in what you want and own it;** bkit never writes over your copy. The install prompt asks your AI to adopt what fits, and each workflow ends with a tip on the next one worth adding. Audit templates fall under the first rule: bkit's own audit agent runs them, so install puts them straight into `docs/templates/` and there's nothing to copy.
|
|
233
253
|
|
|
234
254
|
The ones that matter most, in the order to adopt them:
|
|
235
255
|
|
|
@@ -245,6 +265,7 @@ The ones that matter most, in the order to adopt them:
|
|
|
245
265
|
| **graphify** | Keeps a map of how your code fits together (`docs/capabilities.md`), so agents check what already exists before building it again. |
|
|
246
266
|
| **Dependency updates** | Small, grouped update pull requests from Renovate or Dependabot instead of one big risky upgrade later. GitHub Actions stay pinned, and security fixes skip the queue. |
|
|
247
267
|
| **Security scan** | Trivy fails the check when a change adds a known-vulnerable library in any language, a risky container or cluster setting, or a committed password. A daily run catches problems that have no fix yet, which an updater never shows. |
|
|
268
|
+
| **Audits** | 35 specialist checklists, one per area: testing, security, privacy, reliability, cost and more. Already installed in `docs/templates/`, so there's nothing to copy: name one to `@bkit-audit-generate` and hand its report to `/bkit-plan` ([above](#audits)). |
|
|
248
269
|
|
|
249
270
|
All templates, what each is for, and how to install them: [`.bkit/templates.md`](.bkit/templates.md).
|
|
250
271
|
|
|
@@ -277,35 +298,6 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
277
298
|
- **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.
|
|
278
299
|
- **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).
|
|
279
300
|
|
|
280
|
-
<a id="models"></a>
|
|
281
|
-
|
|
282
|
-
## Which model does each job
|
|
283
|
-
|
|
284
|
-
**Claude sets the bar, and every other tool gets the model that comes closest to it.** On every other tool, each agent runs on the model that does the same job about as well as Claude, for the least money. You don't pick: install sets each agent's model.
|
|
285
|
-
|
|
286
|
-
**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.
|
|
287
|
-
|
|
288
|
-
<!-- prettier-ignore -->
|
|
289
|
-
| Tool | Hardest jobs: design, plans, reviews, security, audits | Everyday jobs: writing code and docs, the second model in each review pair | Summaries |
|
|
290
|
-
| --- | --- | --- | --- |
|
|
291
|
-
| Claude Code | `claude-opus-5-5` · bar **65.2** | `claude-sonnet-5-5` · bar **59.4** | `claude-haiku-5-5` · bar **~51** |
|
|
292
|
-
| Cursor | `cursor-grok-4.5-high` · 56.5 | `composer-2.5` · not measured | `composer-2.5` · not measured |
|
|
293
|
-
| 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 | `z-ai/glm-5.3-flash` · 56.8 |
|
|
294
|
-
| 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 | `deepseek-v4.1-flash` · 77.3 |
|
|
295
|
-
| 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 | `glm-5.3-flash` · 56.8 |
|
|
296
|
-
| 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 | `deepseek-v4.1-flash` · 77.3 |
|
|
297
|
-
| Codex | `gpt-6-astra` · not measured | `gpt-5.6-terra` · not measured | `gpt-6-luna` · 51.2 |
|
|
298
|
-
| Google Antigravity | `gemini-3.8-pro` · not measured | `gemini-3.8-pro` · not measured | `gemini-3.8-flash` · not measured |
|
|
299
|
-
|
|
300
|
-
**Reading the table:**
|
|
301
|
-
|
|
302
|
-
- **The bars are Claude Opus 5 and Sonnet 5 scores.** bkit runs the 5.5 versions. Opus 5.5 scores level with Opus 5. Sonnet 5.5 scores below Sonnet 5 on LiveBench, but one of its runs stopped early and other benchmarks put it above, so the bar stays at Sonnet 5. Every score and why: [the score board](.bkit/providers.md#agentic-coding-parity-board).
|
|
303
|
-
- **Risk, security and root-cause agents get a second model** that reasons differently from the main one, so they don't share its blind spots. On every opencode provider that second model is Kimi K3, which scores a little under the bar for the hardest jobs.
|
|
304
|
-
- **Cursor's own models don't reach the bar.** Claude models in Cursor spend paid API credits, so they're opt-in: paste the ready-made Opus block from [Model Overrides](.bkit/prompts.md#model-overrides).
|
|
305
|
-
- **"Not measured" means LiveBench hasn't scored that model.** Those Codex, Antigravity and Cursor picks follow each vendor's own description of the model. Check them before you rely on them.
|
|
306
|
-
- **Ollama needs a paid plan for every column.** The free models are far below the bar or not scored.
|
|
307
|
-
- **Want a different model for one agent?** On Cursor and opencode, add a row to [Model Overrides](.bkit/prompts.md#model-overrides) and run `bkit install` again. Every agent with its model and thinking depth: [`.bkit/prompts.md` § Models](.bkit/prompts.md#models).
|
|
308
|
-
|
|
309
301
|
<a id="token-costs"></a>
|
|
310
302
|
|
|
311
303
|
## Spending fewer tokens
|
|
@@ -356,25 +348,6 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
356
348
|
- **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.
|
|
357
349
|
- **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.
|
|
358
350
|
|
|
359
|
-
<a id="whats-inside"></a>
|
|
360
|
-
|
|
361
|
-
## What's inside: 200+ files of best practice
|
|
362
|
-
|
|
363
|
-
Everything a senior team would otherwise write down over years, in files you can read:
|
|
364
|
-
|
|
365
|
-
<!-- prettier-ignore -->
|
|
366
|
-
| What | How many | What it does for you |
|
|
367
|
-
| --- | --- | --- |
|
|
368
|
-
| [Agents](.bkit/prompts.md) | 40+ | Single-job specialists, each with its own model, thinking depth and tool list. A reviewer can read code but can't change it. |
|
|
369
|
-
| [Workflows](.bkit/workflows.md) | 6 | The five phases plus a cloud router. Every step ends in a checklist and a mechanical check before the next one starts. |
|
|
370
|
-
| [Agent rules](.agents/rules.md) | 70+ | One rulebook every agent follows: read before editing, never defer silently, report honestly, never rewrite history. |
|
|
371
|
-
| [Guardrails](.bkit/providers.md#guardrails) | 10+ hook files | Block dangerous commands and secret reads, and make agents investigate before they edit, on all five AI tools. |
|
|
372
|
-
| [Audits](.bkit/pipeline.md#audits) | 35 | Security, privacy, accessibility, performance, reliability, database, LLM usage, cost and more. Findings feed straight into a plan. |
|
|
373
|
-
| [Project docs](.bkit/shared/docs/) | 10 + [index](.agents/docs.md) | Architecture, data schema, deployments, testing, security, monitoring, design system, tech stack, setup, and an index telling each agent what to read at each step. |
|
|
374
|
-
| [Templates](.bkit/templates.md) | 60+ | A full CI pipeline, cloud agents, git hooks, linters, dependency updates, secrets sync, code search, and 10+ ready-made connectors for your platforms. |
|
|
375
|
-
|
|
376
|
-
**These are the files your agents read, so they're written for agents:** short, dense, tables over prose. For day-to-day use, start with [`.bkit/README.md`](.bkit/README.md); for every agent in the order it runs, see the [pipeline reference](.bkit/pipeline.md).
|
|
377
|
-
|
|
378
351
|
## FAQ
|
|
379
352
|
|
|
380
353
|
**Do I need to know how to code?**
|
|
@@ -413,7 +386,7 @@ On real bkit sessions they saved 1–3% of the bill, and each changes what the a
|
|
|
413
386
|
<details>
|
|
414
387
|
<summary><strong>For engineers: what's under the hood</strong></summary>
|
|
415
388
|
|
|
416
|
-
- **Isolation.** Every run gets its own git worktree; a per-feature lock blocks duplicate runs of the same feature
|
|
389
|
+
- **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.
|
|
417
390
|
- **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.
|
|
418
391
|
- **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.
|
|
419
392
|
- **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.
|
|
@@ -440,6 +413,34 @@ On real bkit sessions they saved 1–3% of the bill, and each changes what the a
|
|
|
440
413
|
| [`.bkit/comparison.md`](.bkit/comparison.md) | Comparison with other AI development frameworks and with _Agentic Design Patterns_ |
|
|
441
414
|
| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
|
|
442
415
|
|
|
416
|
+
<a id="quick-start"></a>
|
|
417
|
+
|
|
418
|
+
## Quick start
|
|
419
|
+
|
|
420
|
+
**You need** a GitHub repo with a `package.json`, Node 24+, pnpm, and at least one of Claude Code, Cursor, Codex, Google Antigravity or opencode.
|
|
421
|
+
|
|
422
|
+
**Easiest:** copy the [install prompt](.bkit/install.md#install--first-time) into your AI coding tool and let it do the setup.
|
|
423
|
+
|
|
424
|
+
**By hand:** bkit is public on npm and installs like any other package, with no token or registry setup.
|
|
425
|
+
|
|
426
|
+
```bash
|
|
427
|
+
pnpm add -D @cbartens/bkit
|
|
428
|
+
pnpm bkit install --claude # pick your tools: --claude --cursor --codex --antigravity --opencode=<provider>
|
|
429
|
+
# opencode provider: openrouter | ollama | opencode-zen | opencode-go
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
**Check it worked:** `pnpm bkit check` confirms every installed file matches the version you pinned (CI runs the same check), and `pnpm bkit tips` lists what isn't set up yet, most useful first.
|
|
433
|
+
|
|
434
|
+
Adopt the [templates](#templates) you want from `.bkit/templates/`, open an issue, and run the first step from your AI tool:
|
|
435
|
+
|
|
436
|
+
```text
|
|
437
|
+
/bkit-design ISSUE-123
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
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.
|
|
441
|
+
|
|
442
|
+
Full install, upgrade and CI setup: [`.bkit/install.md`](.bkit/install.md). Tracker labels and environment variables: [`.bkit/README.md`](.bkit/README.md#prerequisites).
|
|
443
|
+
|
|
443
444
|
## Credits
|
|
444
445
|
|
|
445
446
|
bkit's process was worked out over months of building real products with it. These projects sharpened specific ideas along the way:
|
|
@@ -47,7 +47,6 @@ export const SHIP_STEP_ORDER = [
|
|
|
47
47
|
"ship-failure-diagnose",
|
|
48
48
|
"ship-failure-remediate",
|
|
49
49
|
"ship-switch-to-dev",
|
|
50
|
-
"ship-worktree-cleanup",
|
|
51
50
|
"ship-close-workflow",
|
|
52
51
|
];
|
|
53
52
|
/** Steps that appear only in the merge-retry loop — never mandatory, never holes. */
|
|
@@ -20,6 +20,8 @@
|
|
|
20
20
|
// Where an advisory already detects the gap, `fires` calls that detector and `advisories`
|
|
21
21
|
// names its ids, so the tip and the advisory can never disagree and one
|
|
22
22
|
// `bkit.ignoreAdvisories` entry silences both.
|
|
23
|
+
import * as fs from "node:fs";
|
|
24
|
+
import { machineStepsPath, REPO_STEPS } from "../../commands/workflow/disk.js";
|
|
23
25
|
import { detectContextFetchMissing } from "../before/context-fetch.js";
|
|
24
26
|
import { detectBlankDotenvKeys, detectDirenvMissing, detectDirenvNotAllowed, detectMissingDotenv, isCloudOrCi, } from "../before/env.js";
|
|
25
27
|
import { detectGhMcpToken, hasGithubMcpServer } from "../after/auth.js";
|
|
@@ -312,6 +314,18 @@ export const SETUP_TIPS = [
|
|
|
312
314
|
steps: "`.bkit/templates.md` § tmp/ prune.",
|
|
313
315
|
fires: (cwd) => exists(cwd, ".husky/pre-push") && !exists(cwd, "scripts/cleanup/bkit-tmp-prune.mjs"),
|
|
314
316
|
},
|
|
317
|
+
{
|
|
318
|
+
id: "disk-prune",
|
|
319
|
+
workflows: ALL_WORKFLOWS,
|
|
320
|
+
title: "Keep enough disk free for new worktrees",
|
|
321
|
+
line: "Build caches, Docker images and simulators fill the disk until a workflow cannot make its worktree. Add your own clean-up steps, run after commits and pushes.",
|
|
322
|
+
why: "bkit deletes nothing on its own: you choose the steps, starting from examples that only delete what comes back by itself. Commits run the cheap steps, pushes run the rest, and a workflow runs them before making a worktree on a nearly full disk.",
|
|
323
|
+
ask: "Copy .bkit/templates/scripts/cleanup/bkit-disk-prune.mjs to scripts/cleanup/ and/or .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs to ~/.config/bkit/disk-prune.mjs, edit the steps, then paste the `disk prune` block from the end of each .bkit/templates/.husky hook at the end of yours.",
|
|
324
|
+
steps: "`.bkit/templates.md` § Disk prune.",
|
|
325
|
+
fires: (cwd) => exists(cwd, ".husky/pre-push") &&
|
|
326
|
+
!exists(cwd, REPO_STEPS) &&
|
|
327
|
+
!fs.existsSync(machineStepsPath()),
|
|
328
|
+
},
|
|
315
329
|
// --- setup: only some setups -----------------------------------------------------------
|
|
316
330
|
{
|
|
317
331
|
id: "cursor-files",
|
|
@@ -12,8 +12,17 @@ export const SETUP_TIPS_HEADING = "Setup tips";
|
|
|
12
12
|
export const tipsIntro = (n) => n === 1 ? "Setup tip for a smoother next run:" : "Setup tips for a smoother next run:";
|
|
13
13
|
/** Where the full tip list lives. */
|
|
14
14
|
export const TIPS_DETAILS_POINTER = "Details for every tip: .bkit/advisories.md § Setup tips (refreshed by `bkit check`).";
|
|
15
|
+
/** Last line of a workflow's `## bkit Tips`: how to silence what it shows, by id. */
|
|
16
|
+
export function silenceLine(ids) {
|
|
17
|
+
const names = ids.map((id) => `\`${id}\``);
|
|
18
|
+
const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
|
|
19
|
+
const what = ids.length > 1 ? "these tips" : "this tip";
|
|
20
|
+
return `Want to silence ${what}? Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
|
|
21
|
+
}
|
|
15
22
|
/** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
|
|
16
|
-
export const STAR_TIP_ID = "star";
|
|
23
|
+
export const STAR_TIP_ID = "bkit-star";
|
|
24
|
+
/** Older key that also silences `STAR_TIP`, so repos that set it keep the line off. */
|
|
25
|
+
export const STAR_TIP_OLD_ID = "star";
|
|
17
26
|
/**
|
|
18
27
|
* Last line of `bkit tips` output while not silenced, in bare `bkit tips` and the phase
|
|
19
28
|
* workflows only — audits and the ledger / roadmap updaters often run back to back. Not a
|
|
@@ -46,7 +55,8 @@ export function collectTips(cwd, catalogue = SETUP_TIPS) {
|
|
|
46
55
|
else
|
|
47
56
|
tips.push(tip);
|
|
48
57
|
}
|
|
49
|
-
|
|
58
|
+
const star = !ignored.has(STAR_TIP_ID) && !ignored.has(STAR_TIP_OLD_ID);
|
|
59
|
+
return { tips, suppressed, star };
|
|
50
60
|
}
|
|
51
61
|
/**
|
|
52
62
|
* Drop advisory findings whose tip the root package.json silenced, so one
|
|
@@ -74,12 +84,10 @@ function tipTextLines(tip, n) {
|
|
|
74
84
|
lines.push(` Caution: ${tip.caution}`);
|
|
75
85
|
return lines;
|
|
76
86
|
}
|
|
77
|
-
/** One tip as markdown
|
|
78
|
-
function
|
|
79
|
-
const
|
|
80
|
-
|
|
81
|
-
lines.push("", `Caution: ${tip.caution}`);
|
|
82
|
-
return lines;
|
|
87
|
+
/** One tip as one markdown paragraph for a workflow's `## bkit Tips` section. */
|
|
88
|
+
function tipParagraph(tip) {
|
|
89
|
+
const caution = tip.caution ? ` Caution: ${tip.caution}` : "";
|
|
90
|
+
return `**${tip.title}.** ${tip.line} Ask your agent: "${tip.ask}"${caution}`;
|
|
83
91
|
}
|
|
84
92
|
/**
|
|
85
93
|
* `tips` with the ones that matter in `workflow` first, each group in catalogue order.
|
|
@@ -94,40 +102,48 @@ export function starShownIn(workflow) {
|
|
|
94
102
|
return !workflow || ALL_WORKFLOWS.includes(workflow);
|
|
95
103
|
}
|
|
96
104
|
/**
|
|
97
|
-
* `bkit tips` output
|
|
98
|
-
* `
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
105
|
+
* `bkit tips` output. `""` when no tip fires and no star line shows.
|
|
106
|
+
* - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow as
|
|
107
|
+
* one markdown paragraph each, then `STAR_TIP` when shown, then `silenceLine` naming both — the
|
|
108
|
+
* workflow appends them under its own `## bkit Tips` heading.
|
|
109
|
+
* - neither: the top `TIPS_CAP` tips as a numbered terminal list, where the rest live,
|
|
110
|
+
* then `STAR_TIP` when shown.
|
|
103
111
|
* - `all`: every tip as a numbered list (in the workflow's order when `workflow` is set).
|
|
112
|
+
* `STAR_TIP` shows when `opts.star` is set and `starShownIn(workflow)`.
|
|
104
113
|
*/
|
|
105
114
|
export function formatTips(tips, opts = {}) {
|
|
115
|
+
const star = !!opts.star && starShownIn(opts.workflow);
|
|
116
|
+
if (opts.workflow && !opts.all)
|
|
117
|
+
return formatWorkflowTips(tips, opts.workflow, star);
|
|
106
118
|
const body = formatSetupTips(tips, opts);
|
|
107
|
-
if (!
|
|
119
|
+
if (!star)
|
|
108
120
|
return body;
|
|
109
121
|
return body ? `${body}\n\n${STAR_TIP}` : STAR_TIP;
|
|
110
122
|
}
|
|
111
|
-
/** `formatTips`
|
|
123
|
+
/** `formatTips` for a workflow's `## bkit Tips`: tips, star line, how to silence both. */
|
|
124
|
+
function formatWorkflowTips(tips, workflow, star) {
|
|
125
|
+
const shown = orderForWorkflow(tips, workflow).slice(0, WORKFLOW_TIPS_CAP);
|
|
126
|
+
const ids = shown.map((t) => t.id);
|
|
127
|
+
const parts = shown.map(tipParagraph);
|
|
128
|
+
if (star) {
|
|
129
|
+
parts.push(STAR_TIP);
|
|
130
|
+
ids.push(STAR_TIP_ID);
|
|
131
|
+
}
|
|
132
|
+
if (ids.length === 0)
|
|
133
|
+
return "";
|
|
134
|
+
return [...parts, silenceLine(ids)].join("\n\n");
|
|
135
|
+
}
|
|
136
|
+
/** `formatTips` as a terminal list, without `STAR_TIP`. */
|
|
112
137
|
function formatSetupTips(tips, opts) {
|
|
113
138
|
if (tips.length === 0)
|
|
114
139
|
return "";
|
|
115
140
|
const ordered = opts.workflow ? orderForWorkflow(tips, opts.workflow) : [...tips];
|
|
116
|
-
const
|
|
117
|
-
const shown = opts.all ? ordered : ordered.slice(0, cap);
|
|
141
|
+
const shown = opts.all ? ordered : ordered.slice(0, TIPS_CAP);
|
|
118
142
|
const rest = tips.length - shown.length;
|
|
119
|
-
const more = rest > 0 ? `${rest} more: \`bkit tips --all\`. ` : "";
|
|
120
|
-
if (opts.workflow && !opts.all) {
|
|
121
|
-
const lines = [];
|
|
122
|
-
for (const tip of shown)
|
|
123
|
-
lines.push(...tipMarkdownLines(tip), "");
|
|
124
|
-
lines.push(`${more}${TIPS_DETAILS_POINTER}`);
|
|
125
|
-
return lines.join("\n");
|
|
126
|
-
}
|
|
127
143
|
const lines = [tipsIntro(shown.length), ""];
|
|
128
144
|
shown.forEach((tip, i) => lines.push(...tipTextLines(tip, i + 1), ""));
|
|
129
|
-
if (
|
|
130
|
-
lines.push(more
|
|
145
|
+
if (rest > 0)
|
|
146
|
+
lines.push(`${rest} more: \`bkit tips --all\`.`);
|
|
131
147
|
lines.push(TIPS_DETAILS_POINTER);
|
|
132
148
|
return lines.join("\n");
|
|
133
149
|
}
|