@cbartens/bkit 5.2.2 → 5.2.3

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.
Files changed (82) hide show
  1. package/.bkit/README.md +1 -1
  2. package/.bkit/core/.agents/context.md +2 -2
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +7 -1
  4. package/.bkit/core/.bkit/comparison.md +114 -45
  5. package/.bkit/core/.bkit/install.md +3 -3
  6. package/.bkit/core/.bkit/jsonl.md +3 -3
  7. package/.bkit/core/.bkit/prompts.md +6 -5
  8. package/.bkit/core/.bkit/providers.md +5 -4
  9. package/.bkit/core/.bkit/templates.md +11 -10
  10. package/.bkit/core/.bkit/workflows.md +7 -5
  11. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +5 -1
  12. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -2
  13. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +5 -2
  14. package/.bkit/core/docs/templates/bkit-audit-adoption.md +5 -2
  15. package/.bkit/core/docs/templates/bkit-audit-agents.md +5 -2
  16. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +5 -2
  17. package/.bkit/core/docs/templates/bkit-audit-analytics.md +5 -2
  18. package/.bkit/core/docs/templates/bkit-audit-annotations.md +6 -3
  19. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +5 -2
  20. package/.bkit/core/docs/templates/bkit-audit-app-store.md +5 -2
  21. package/.bkit/core/docs/templates/bkit-audit-architecture.md +5 -2
  22. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +5 -2
  23. package/.bkit/core/docs/templates/bkit-audit-config.md +5 -2
  24. package/.bkit/core/docs/templates/bkit-audit-cost.md +5 -2
  25. package/.bkit/core/docs/templates/bkit-audit-coverage.md +5 -2
  26. package/.bkit/core/docs/templates/bkit-audit-database.md +5 -2
  27. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -2
  28. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +5 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +5 -2
  30. package/.bkit/core/docs/templates/bkit-audit-documentation.md +5 -2
  31. package/.bkit/core/docs/templates/bkit-audit-duplication.md +5 -2
  32. package/.bkit/core/docs/templates/bkit-audit-failures.md +6 -3
  33. package/.bkit/core/docs/templates/bkit-audit-flakes.md +6 -3
  34. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  35. package/.bkit/core/docs/templates/bkit-audit-issues.md +5 -2
  36. package/.bkit/core/docs/templates/bkit-audit-llm.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-logs.md +16 -12
  38. package/.bkit/core/docs/templates/bkit-audit-models.md +5 -2
  39. package/.bkit/core/docs/templates/bkit-audit-privacy.md +5 -2
  40. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -2
  41. package/.bkit/core/docs/templates/bkit-audit-red-team.md +5 -2
  42. package/.bkit/core/docs/templates/bkit-audit-reliability.md +6 -3
  43. package/.bkit/core/docs/templates/bkit-audit-repo.md +5 -2
  44. package/.bkit/core/docs/templates/bkit-audit-security.md +6 -3
  45. package/.bkit/core/docs/templates/bkit-audit-slop.md +5 -2
  46. package/.bkit/core/docs/templates/bkit-audit-testing.md +5 -2
  47. package/.bkit/core/docs/templates/bkit-audit-usability.md +5 -2
  48. package/.bkit/core/docs/templates/bkit-plan.md +1 -1
  49. package/.bkit/core/engine/commands/install/check.ts +3 -11
  50. package/.bkit/core/engine/commands/install/doctor.ts +2 -3
  51. package/.bkit/core/engine/commands/install/uninstall.ts +60 -44
  52. package/.bkit/core/engine/commands/install/upgrade.ts +4 -1
  53. package/.bkit/core/engine/commands/workflow/branches.ts +13 -4
  54. package/.bkit/core/engine/install/hosts.ts +14 -4
  55. package/.bkit/core/engine/ledgers/telemetry.ts +3 -4
  56. package/.bkit/core/hooks/guardrails-read.js +4 -9
  57. package/.bkit/core/hooks/guardrails-tiers.js +312 -28
  58. package/.bkit/core/prompts/bkit-audit-generate.md +19 -5
  59. package/.bkit/shared/.claude/settings.json +19 -0
  60. package/.bkit/shared/.opencode/opencode.json +21 -1
  61. package/.bkit/shared/docs/deployments.md +14 -0
  62. package/.bkit/templates/.github/workflows/bkit-ci.yml +9 -0
  63. package/.bkit/templates/context/bkit-cloudrun.md +28 -19
  64. package/.bkit/templates/context/bkit-expo.md +30 -13
  65. package/.bkit/templates/context/bkit-inngest.md +54 -17
  66. package/.bkit/templates/context/bkit-resend.md +36 -8
  67. package/.bkit/templates/context/bkit-sentry.md +11 -4
  68. package/.bkit/templates/context/bkit-stripe.md +39 -22
  69. package/.bkit/templates/context/bkit-supabase.md +45 -20
  70. package/.bkit/templates/context/bkit-vercel.md +45 -16
  71. package/.bkit/templates/scripts/ci/accepted-advisories.json +7 -0
  72. package/.bkit/templates/scripts/ci/check-dependency-audit.mjs +200 -0
  73. package/.bkit/templates/scripts/ci/check-dependency-audit.test.mjs +127 -0
  74. package/CHANGELOG.md +39 -0
  75. package/README.md +76 -20
  76. package/dist/commands/install/check.js +3 -15
  77. package/dist/commands/install/doctor.js +2 -1
  78. package/dist/commands/install/uninstall.js +52 -45
  79. package/dist/commands/install/upgrade.js +4 -1
  80. package/dist/commands/workflow/branches.js +13 -5
  81. package/dist/install/hosts.js +11 -4
  82. package/package.json +1 -1
package/README.md CHANGED
@@ -16,7 +16,7 @@
16
16
  <p align="center">
17
17
  <a href="#quick-start">Quick start</a> ·
18
18
  <a href="#a-ready-made-workflow-for-every-job">Workflows</a> ·
19
- <a href="#a-ci-pipeline-built-the-way-senior-teams-build-them">CI template</a> ·
19
+ <a href="#agents-and-ci-built-to-work-together">Agents and CI</a> ·
20
20
  <a href="#right-context-at-the-right-step">Context</a> ·
21
21
  <a href="#faq">FAQ</a> ·
22
22
  <a href=".bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks">Comparison</a> ·
@@ -46,11 +46,11 @@ Everything a senior team would otherwise write down over years, in files you can
46
46
  <!-- prettier-ignore -->
47
47
  | What | How many | What it does for you |
48
48
  | --- | --- | --- |
49
- | Agents | >40 | Single-job specialists, each with its own model, thinking depth and tool list. A reviewer can read code but can't change it. |
49
+ | [Agents](.bkit/comparison.md#part-1--the-five-phase-pipeline-in-order) | >40 | Single-job specialists, each with its own model, thinking depth and tool list. A reviewer can read code but can't change it. |
50
50
  | Workflows | 6 | The five phases plus a cloud router. Every step ends in a checklist and a mechanical check before the next one starts. |
51
51
  | Agent rules | >70 | One shared rulebook every agent follows: read before editing, never defer silently, report honestly, never rewrite history. |
52
52
  | Guardrails | >10 hook files | Block dangerous commands and make agents investigate before they edit, on all five AI tools. |
53
- | Audits | >30 | Security, privacy, accessibility, performance, reliability, database, LLM usage, cost and more. Findings feed straight into a plan. |
53
+ | [Audits](.bkit/comparison.md#audits) | >30 | Security, privacy, accessibility, performance, reliability, database, LLM usage, cost and more. Findings feed straight into a plan. |
54
54
  | Project docs | 10 + index | Architecture, data schema, deployments, testing, security, monitoring, design system, tech stack, setup, and an index telling each agent what to read at each step. |
55
55
  | Templates | >60 | A full CI pipeline, cloud agents, git hooks, linters, dependency updates, secrets sync, code search, and >10 ready-made connectors for your platforms. |
56
56
 
@@ -61,12 +61,12 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
61
61
  <!-- prettier-ignore -->
62
62
  | Job | Command | What happens |
63
63
  | --- | --- | --- |
64
- | Work out how to build it | `/bkit-design` | Reads related issues and past decisions, has three agents propose different approaches and two critique them, and writes throwaway code to test any risky unknowns the reviewers flag. You get one design to approve. |
65
- | Plan the work | `/bkit-plan` | A step-by-step plan, stress-tested by five reviewers who also see past bugs and postponed work. Too big for one build? It's split into pieces. You approve it. |
66
- | Build it | `/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. |
67
- | Fix what broke | `/bkit-debug` | Pulls evidence from CI and your platforms, finds the root cause, fixes it, 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. |
68
- | Ship it | `/bkit-ship` | Checks nothing planned was quietly dropped, waits for every test lane to pass, merges into `dev`, and updates the docs. |
69
- | Health check | >30 audits | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
64
+ | Work out how to build it | [`/bkit-design`](.bkit/comparison.md#phase-1--bkit-design) | Reads related issues and past decisions, has three agents propose different approaches and two critique them, and writes throwaway code to test any risky unknowns the reviewers flag. You get one design to approve. |
65
+ | Plan the work | [`/bkit-plan`](.bkit/comparison.md#phase-2--bkit-plan) | A step-by-step plan, stress-tested by five reviewers who also see past bugs and postponed work. Too big for one build? It's split into pieces. You approve it. |
66
+ | Build it | [`/bkit-build`](.bkit/comparison.md#phase-3--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. |
67
+ | Fix what broke | [`/bkit-debug`](.bkit/comparison.md#phase-4--bkit-debug) | Pulls evidence from CI and your platforms, finds the root cause, fixes it, 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. |
68
+ | Ship it | [`/bkit-ship`](.bkit/comparison.md#phase-5--bkit-ship) | Checks nothing planned was quietly dropped, waits for every test lane to pass, merges into `dev`, and updates the docs. |
69
+ | Health check | [>30 audits](.bkit/comparison.md#audits) | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
70
70
  | Housekeeping | 7 utility agents | Keep docs, decisions, lessons and known bugs current, and rank what to work on next. |
71
71
 
72
72
  ## How it works
@@ -78,6 +78,8 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
78
78
  </picture>
79
79
  </p>
80
80
 
81
+ Every agent in each phase, in the order it runs and what it checks: [pipeline reference](.bkit/comparison.md#pipeline-map-key-steps-only).
82
+
81
83
  ## Why it's different
82
84
 
83
85
  <p align="center">
@@ -89,15 +91,36 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
89
91
 
90
92
  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. From the first line of code, automated checks join them, and those can't be argued with.
91
93
 
92
- ## A CI pipeline built the way senior teams build them
94
+ ## Agents and CI, built to work together
95
+
96
+ <p align="center">
97
+ <picture>
98
+ <source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-fences-details-dark.svg">
99
+ <img alt="Every change hits the same fences. They never argue, and they grow. On the left, the agents. Every agent in every workflow looks up every definition and caller with code search before a change, is nudged by the agent hooks on every edit, has every workflow step checked by the step gates, and has its code formatted by the pre-commit hook on every commit. /bkit-plan decides the tests each feature adds to the fences (unit, integration or end-to-end). /bkit-build writes each test first, sees it fail, then hits every fence; the pre-push hook sends problems back before they leave your laptop. When a CI lane goes red, its logs give /bkit-debug the context to fix it. When CI is green, the change passes through and /bkit-ship merges it, re-checked on the merge commit. On the right, the fences, nearest and lightest first: code search on every lookup, agent hooks on every edit, step gates on every step, the pre-commit hook on every commit, the pre-push hook on every push, and CI, the strongest, on every push and pull request. The step gates are scripts, not prompts: a step missing its verdict or files can't finish, whatever the agent says. The pre-commit hook formats only the files being committed, so it takes seconds, and your own quick checks can go there too. CI runs integration, end-to-end and live-site tests, and one check fails if any lane failed, was skipped or ran no tests. Hooks, agents and CI run the same commands, and in cloud mode CI's answer starts debug or ship by itself." src=".github/assets/bkit-fences-details-light.svg" width="100%">
100
+ </picture>
101
+ </p>
102
+
103
+ The strongest fence is CI (continuous integration): the robot that runs every check on every change, on GitHub's servers, before anything merges. Most AI development frameworks stop at a pull request and leave CI to you. bkit's workflows are built around it, and around the checks that run before it. Every change has to get past the same fences, from the nearest and lightest out to CI:
104
+
105
+ - **Every agent**, in every workflow, looks code up before changing it, is nudged by the agent hooks on each edit, can't finish a step until the step gates (scripts, not prompts) find its verdict and files, and has its code formatted on each commit.
106
+ - **`/bkit-plan`** decides which tests each feature needs and where each one runs: unit, integration or end-to-end.
107
+ - **`/bkit-build`** writes each test before its code and runs it to prove it fails, so a test that can't fail is never added. It runs the quick checks on your machine, where the pre-push hook sends back anything that fails, then opens a pull request, which starts CI.
108
+ - **`/bkit-debug`** uses what was sent back as context: the logs of the lanes that failed, the diff since the last green run, end-to-end reports. It fixes the root cause and pushes, and CI runs again.
109
+ - **`/bkit-ship`** checks nothing planned was quietly dropped, then merges into `dev` only when CI's final check is green on the exact commit being merged.
110
+ - **On autopilot**, nobody has to press go: for issues labelled `bkit:auto`, CI's result starts ship (green) or debug (red) in a cloud session, with no laptop open.
111
+
112
+ What that gets you:
93
113
 
94
- The strongest fence is CI (continuous integration): the robot that runs every check on every change, on GitHub's servers, before anything merges. Most people who start with vibe coding have never set one up, and none of the AI development frameworks in our [comparison](.bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks) ships a full test pipeline for your project. bkit ships one ready to adopt, and its workflows are built around it. Agents and CI hand the work back and forth until every test passes:
114
+ - **The fences grow with every feature.** Each build adds tests that every later change has to pass. A prompt-only framework is as strict on your fiftieth feature as on your first; bkit gets stricter.
115
+ - **What's sent back is evidence, not a verdict.** A red lane hands debug the failing logs and what changed since the last green run, so the fix starts from the actual error instead of a guess.
116
+ - **Agents look before they change anything.** Code search ([Serena](https://github.com/oraios/serena)) shows an agent every definition and caller of the code it's about to change, not just lines with matching words, and [graphify](https://github.com/Graphify-Labs/graphify)'s code map shows what already exists before it writes more. Fewer bad changes reach the fences at all.
117
+ - **Problems are caught at the nearest fence.** Agent hooks nudge on every edit: read a file before changing it, and fix the code rather than loosen a check. The pre-commit hook formats in seconds. The pre-push hook runs type checks, unit tests, the prose checker and the junk-code scanner before anything leaves your laptop. CI is left with what genuinely can't run there: integration, end-to-end and live-site tests. Your hooks and the agents call the same `bkit:gate:*` scripts, and CI's quick-checks lane runs the same commands, so most failures show up on your machine first.
95
118
 
96
- 1. **`/bkit-build`** runs the quick checks on your machine, then opens a pull request, which starts CI.
97
- 2. **CI** runs every lane and reports one result: a final check that's green only if every lane ran and passed.
98
- 3. **Red?** `/bkit-debug` reads the logs of the lanes that failed, finds the root cause, fixes it and pushes, and CI runs again.
99
- 4. **Green?** `/bkit-ship` checks nothing planned was quietly dropped, then merges into `dev`. Nothing less than green gets merged.
100
- 5. **On autopilot**, the loop runs by itself: for issues labelled `bkit:auto`, CI's result starts ship or debug in a cloud session, with no laptop open.
119
+ The agent hooks come with install. Serena, graphify and the git hooks are [templates](#templates-ready-to-adopt) you adopt. How this compares with other frameworks: [agents and CI](.bkit/comparison.md#agents-and-ci).
120
+
121
+ ### The CI pipeline
122
+
123
+ None of the AI development frameworks in our [comparison](.bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks) ships a full test pipeline for your project. bkit ships one ready to adopt:
101
124
 
102
125
  <p align="center">
103
126
  <picture>
@@ -112,6 +135,8 @@ The strongest fence is CI (continuous integration): the robot that runs every ch
112
135
  - **Safe by default.** Every third-party action is pinned to an exact commit, the downloaded prose checker is checksum-verified, and pull-request titles never reach a script unescaped.
113
136
  - **Doesn't waste minutes.** A commit that already passed isn't re-tested, and a newer push cancels the older run, except on your production branch, where a deploy must never be cut off halfway.
114
137
 
138
+ How the lanes join into the one final check, and what happens on green or red: [CI test scaffold](.bkit/comparison.md#ci-test-scaffold-runs-on-every-pr--push).
139
+
115
140
  ## Right context at the right step
116
141
 
117
142
  <p align="center">
@@ -143,7 +168,6 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
143
168
  - **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, and a design reviewer checks failure modes and monitoring, not just whether it can be built.
144
169
  - **Big features are split up.** A plan too big for one build becomes a sequence of smaller plans, and each is re-checked against the current code right before it's built.
145
170
  - **Numbers on your own work.** Every run records its time, size of change and retries in `.bkit/stats.jsonl`, and posts them to the issue next to the median of your last five runs.
146
- - **Health checks on demand.** >30 audit checklists act like hiring a specialist for a day.
147
171
 
148
172
  ### It fits how you work
149
173
 
@@ -159,16 +183,48 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
159
183
  - **Three sign-offs, and production stays yours.** bkit stops after the design, after the plan and before merging. It merges into your `dev` branch and never touches `main`: promoting to production is always your call. Cloud mode can ship on green without you, but only for issues you've labelled `bkit:auto`, and removing the label stops it.
160
184
  - **Guardrails on the AI itself.** Dangerous commands like force-pushing or rewriting history are blocked. Each agent only gets the tools its job needs.
161
185
 
186
+ ## Audits find what green tests miss
187
+
188
+ <p align="center">
189
+ <picture>
190
+ <source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-audits-dark.svg">
191
+ <img alt="The tests were green. The bugs were still there. A map of an app that adopted bkit, in four columns: screens (web and phone), API, services and outside services, with thin lines for the calls between them. Red circles mark what bkit's audit templates found, bigger for bigger problems. Testing audit: tests that could never fail, about 100 of which read the code as text instead of running it; a security hole, where a sign-in link could send people to another website; no test made a request fail, so a failed save could still show “Saved”; a fix in dead code, while the live screen next to it stayed broken; phone tests that weren't, with 23 of 33 actually running as web pages. Duplication audit: one rule written 8 times, whose copies drifted so some billed accounts users had left; one database read in 4 copies, word for word, one inside the API itself. This map used 2 of the more than 30 audit templates bkit ships." src=".github/assets/bkit-audits-light.svg" width="100%">
192
+ </picture>
193
+ </p>
194
+
195
+ A green tick proves the tests passed, not that they test the right things. Every finding on this map sat in an app whose tests were passing, and only two of bkit's audit templates found them all.
196
+
197
+ Each template is a specialist's checklist for one area: what to check, how, and what counts as a problem. Ten to start with:
198
+
199
+ <!-- prettier-ignore -->
200
+ | Audit | What it checks | For example |
201
+ | --- | --- | --- |
202
+ | **Testing** | Whether tests can fail, actually run, and cover what the product must and must never do | Tests that read the code as text instead of running it |
203
+ | **Duplication** | Rules and logic built more than once | A billing rule in eight copies that have drifted apart |
204
+ | **Security** | Sign-in, permissions, secrets, input checks, and protections the docs promise | A sign-in link that can send people to another website |
205
+ | **Red team** | Real attacks on a test copy of your app, never production, one request at a time | One signed-in user reading another user's data |
206
+ | **Reliability** | What happens when a service is slow, down or answers twice | A payment retried with no guard against charging twice |
207
+ | **Privacy** | Where personal data goes, how long it stays, and whether deletion works | A deleted account still sitting in the logs |
208
+ | **Dead code** | Code, settings and routes that look live but never run | A fix made in a file nothing calls |
209
+ | **LLM** | Every AI model call, and what stops it when the input is hostile | A pasted document that talks the model into calling a tool |
210
+ | **Accessibility** | What automated accessibility checks miss, against WCAG 2.2 AA | A form a screen reader can't get through |
211
+ | **Cost** | Vendor plans against what you actually use | A plan two tiers above your usage |
212
+
213
+ All 35, grouped by area, with what each one finds: [the full audit list](.bkit/comparison.md#audits).
214
+
215
+ - **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.
216
+ - **Findings turn into work.** Hand the report to `/bkit-plan` and the fixes are planned, built, tested and shipped like any other feature.
217
+
162
218
  ## Templates ready to adopt
163
219
 
164
- bkit installs only what its workflows run. Everything else, the things you or another tool run, 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.
220
+ bkit installs only what its workflows run. Everything else, the things you or another tool run, 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. Audits aren't among them: they come installed, so there's nothing to copy ([above](#audits-find-what-green-tests-miss)).
165
221
 
166
222
  The ones that matter most, in the order to adopt them:
167
223
 
168
224
  <!-- prettier-ignore -->
169
225
  | Template | What it's for |
170
226
  | --- | --- |
171
- | **CI pipeline** | Runs every check on GitHub on every change, and `/bkit-ship` waits for it before merging. Without it, "shipped" only means merged, not checked. Two lanes ready to go and >20 building blocks for the rest ([above](#a-ci-pipeline-built-the-way-senior-teams-build-them)). |
227
+ | **CI pipeline** | Runs every check on GitHub on every change, and `/bkit-ship` waits for it before merging. Without it, "shipped" only means merged, not checked. Two lanes ready to go and >20 building blocks for the rest ([above](#the-ci-pipeline)). |
172
228
  | **Quality checks** | Catches problems on your own machine in seconds, before they reach GitHub: type checking, formatting, a prose checker and a scanner for junk code AI tends to write, wired into git hooks and CI. Your `bkit:gate:*` scripts in `package.json` define what "the checks" are. |
173
229
  | **Serena** | Lets agents look up code the way your editor does ("where is this defined, and what uses it?") instead of searching for words and reading whole files. Fewer accidental changes, and lower running costs because agents read less. Read-only. |
174
230
  | **Context connectors** | Let `/bkit-debug` read the real errors instead of guessing from the code: >10 ready-made connectors for CI, error trackers, hosting, databases, payments, email, queues and the web. |
@@ -237,7 +293,7 @@ We measured both on 456 real Claude Code transcripts. They saved about 1–3% of
237
293
  - **One source, every host.** `.bkit/` renders `.claude/`, `.cursor/`, `.codex/`, `.agents/` (Antigravity) and `.opencode/`. `bkit check` is the CI drift gate.
238
294
  - **Reviewer independence.** Parallel reviewers can't read sibling output. Design brainstorm, design review and plan scope-check groups also cross models (Opus + Sonnet on Claude; Grok + Composer on Cursor); depth-sensitive lenses (plan review, build challenge) stay on the top tier.
239
295
  - **Per-agent pins.** Model and effort per agent, per provider ([`.bkit/prompts.md`](.bkit/prompts.md) § Models), immune to the session default.
240
- - **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 and every agent in execution order: [`.bkit/comparison.md`](.bkit/comparison.md).
296
+ - **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#part-2--comparison-to-agentic-design-patterns), with [where bkit goes beyond the book](.bkit/comparison.md#where-bkit-goes-beyond-the-catalogue) and its [known gaps](.bkit/comparison.md#known-gaps-scoped-as-opportunities). Every agent in execution order: [pipeline reference](.bkit/comparison.md#part-1--the-five-phase-pipeline-in-order).
241
297
 
242
298
  </details>
243
299
 
@@ -1,13 +1,12 @@
1
1
  // commands/install/check.ts — `bkit check`: the parts only check runs. Check is install in
2
2
  // dry-run mode (commands/install/install.ts runInstall); this file holds the installed-module
3
3
  // detection that scopes its drift gate and the drift verdict.
4
- import * as fs from "node:fs";
5
- import * as path from "node:path";
4
+ import { detectInstalledHostModules } from "../../install/hosts.js";
6
5
  import { describeMissingOwnedHook } from "../../checks/after/managed.js";
7
6
  import { LOG_PREFIX } from "../../shared/log-prefix.js";
8
7
  /**
9
8
  * Installed-module set, detected by sentinel-file presence. Always core, plus the installed
10
- * subset of {claude, cursor, opencode, codex}. Two callers:
9
+ * hosts (detectInstalledHostModules). Two callers:
11
10
  * - `bkit check` — scopes the drift gate, so a `--cursor`-only repo does not
12
11
  * report `.claude/**` as drift.
13
12
  * - `bkit upgrade` — scopes the template walk, so upgrade does NOT force-create files for a
@@ -21,18 +20,7 @@ import { LOG_PREFIX } from "../../shared/log-prefix.js";
21
20
  * Dependency-updater files are not modules: bkit never drift-checks them.
22
21
  */
23
22
  export function detectInstalledModules(cwd) {
24
- const mods = new Set(["core"]);
25
- if (fs.existsSync(path.join(cwd, ".claude", "agents")))
26
- mods.add("claude");
27
- if (fs.existsSync(path.join(cwd, ".cursor", "agents")))
28
- mods.add("cursor");
29
- if (fs.existsSync(path.join(cwd, ".opencode", "agents")))
30
- mods.add("opencode");
31
- if (fs.existsSync(path.join(cwd, ".codex", "agents")))
32
- mods.add("codex");
33
- if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
34
- mods.add("antigravity");
35
- return mods;
23
+ return new Set(["core", ...detectInstalledHostModules(cwd)]);
36
24
  }
37
25
  // Check mode: exit-1 on drift (totalWrites > 0). runInstall emits the banner first.
38
26
  // Host agent/command mirrors push would-writes into ws.writes (content drift OR
@@ -10,6 +10,7 @@ import { runPreflight } from "../../checks/before/index.js";
10
10
  import { runPostInstallCheck, formatChecklist, writeAdvisoriesArtifact, } from "../../checks/after/index.js";
11
11
  import { collectTips } from "../../checks/tips/index.js";
12
12
  import { parseDotenv } from "../../install/cloud-env.js";
13
+ import { detectInstalledHostModules } from "../../install/hosts.js";
13
14
  /**
14
15
  * `bkit status` — read-only host/provider status.
15
16
  * Reports current host+provider sampled from .opencode/opencode.json,
@@ -82,7 +83,7 @@ export function runStatus(cwd, logPrefix) {
82
83
  const codexDir = path.join(cwd, ".codex");
83
84
  const codexPresent = fs.existsSync(codexDir);
84
85
  // --- antigravity host ---
85
- const antigravityPresent = fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json"));
86
+ const antigravityPresent = detectInstalledHostModules(cwd).has("antigravity");
86
87
  const opencodeStatus = opencodePresent
87
88
  ? `INSTALLED (${providerLabel}: ${opencodeProviderDisplay} / model: ${opencodeModel})`
88
89
  : "absent (run: bkit install --opencode=<provider>)";
@@ -23,7 +23,8 @@ import * as path from "node:path";
23
23
  import * as readline from "node:readline";
24
24
  import { stripManagedBlock, detectMarkerStyle } from "../../install/managed-block.js";
25
25
  import { readTemplate } from "../../render/parts.js";
26
- import { getInstallManifest, } from "../../install/manifest.js";
26
+ import { getInstallManifest, ISSUE_TRACKERS, } from "../../install/manifest.js";
27
+ import { OPENCODE_PROVIDERS } from "../../shared/egress.js";
27
28
  import { isConsumerModified, mergeCanonicalHashes, readBkitVersion, writeBkitVersion, } from "../../install/version-file.js";
28
29
  import { getPkgRoot, getSharedRoot, findTemplateSource, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
29
30
  import { PAYLOAD_LINKS } from "../../install/payload-links.js";
@@ -47,34 +48,35 @@ import { LOG_PREFIX, setLogPrefix } from "../../shared/log-prefix.js";
47
48
  // Consumer-only keys at any level are preserved byte-identical.
48
49
  // ---------------------------------------------------------------------------
49
50
  /**
50
- * Detect the tracker bkit seeded into opencode.json from its mcp keys. The template ships an
51
- * `@@OPENCODE_TRACKER_MCP@@` sentinel KEY that renders to `github` / `linear` at install, so a
52
- * strip-scope keyed on the raw template never matches — these detectors let uninstall render the
53
- * template the same way the install did before stripping. Keyed on bkit's known tracker names so
54
- * a consumer-added mcp server is never mistaken for bkit's.
51
+ * Strip bkit's scope from `.opencode/opencode.json`. The template ships `@@OPENCODE_*@@`
52
+ * sentinel KEYS that render to the consumer's tracker and provider, and install keeps every
53
+ * earlier provider block and tracker entry (install is additive), so one file can hold several.
54
+ * Render the template once per known tracker and once per supported provider, then remove each
55
+ * `mcp` entry and `provider` block identical to a rendered one; an entry the consumer added or
56
+ * edited stays whole. The rest of the template (permission sandbox, plugin list) strips leaf by
57
+ * leaf like any Tier-2 JSON file. Reads only the template.
55
58
  */
56
- function detectOpencodeTracker(doc) {
57
- const mcp = doc.mcp;
58
- if (mcp !== null && typeof mcp === "object" && !Array.isArray(mcp)) {
59
- if ("github" in mcp)
60
- return "github";
61
- if ("linear" in mcp)
62
- return "linear";
59
+ export function stripOpencodeJsonScope(consumer, templatePath, cwd) {
60
+ const render = (tracker, provider) => JSON.parse(renderOpencodeJson(templatePath, tracker, provider, cwd));
61
+ const ownedMcp = {};
62
+ for (const tracker of ISSUE_TRACKERS) {
63
+ const { mcp } = render(tracker, OPENCODE_PROVIDERS[0]);
64
+ if (isJsonObject(mcp))
65
+ Object.assign(ownedMcp, mcp);
63
66
  }
64
- return "none";
65
- }
66
- /** Detect the opencode provider key bkit seeded (the first `provider` block key). */
67
- function detectOpencodeProvider(doc) {
68
- const provider = doc.provider;
69
- if (provider !== null && typeof provider === "object" && !Array.isArray(provider)) {
70
- const keys = Object.keys(provider);
71
- if (keys.length > 0) {
72
- const first = keys[0];
73
- // Zen block is keyed `opencode` (built-in id); map back to the bkit CLI key.
74
- return first === "opencode" ? "opencode-zen" : first;
75
- }
67
+ const ownedProviders = {};
68
+ for (const provider of OPENCODE_PROVIDERS) {
69
+ const rendered = render("none", provider).provider;
70
+ if (isJsonObject(rendered))
71
+ Object.assign(ownedProviders, rendered);
76
72
  }
77
- return "opencode-zen";
73
+ const rest = render("none", OPENCODE_PROVIDERS[0]);
74
+ delete rest.mcp;
75
+ delete rest.provider;
76
+ const out = JSON.parse(JSON.stringify(consumer));
77
+ removeOwnedEntries(out, "mcp", ownedMcp);
78
+ removeOwnedEntries(out, "provider", ownedProviders);
79
+ return stripTier2JsonScope(out, rest);
78
80
  }
79
81
  export function stripTier2JsonScope(consumerDoc, templateDoc) {
80
82
  const out = JSON.parse(JSON.stringify(consumerDoc));
@@ -135,18 +137,26 @@ const MCP_JSON_RELPATHS = new Set([".mcp.json", path.join(".cursor", "mcp.json")
135
137
  */
136
138
  export function stripMcpTrackerEntries(consumer, template) {
137
139
  const out = JSON.parse(JSON.stringify(consumer));
138
- const servers = out.mcpServers;
139
140
  const owned = template.mcpServers;
140
- if (!isJsonObject(servers) || !isJsonObject(owned))
141
- return out;
142
- for (const [key, entry] of Object.entries(owned)) {
143
- if (JSON.stringify(servers[key]) === JSON.stringify(entry))
144
- delete servers[key];
145
- }
146
- if (Object.keys(servers).length === 0)
147
- delete out.mcpServers;
141
+ if (isJsonObject(owned))
142
+ removeOwnedEntries(out, "mcpServers", owned);
148
143
  return out;
149
144
  }
145
+ /**
146
+ * Delete each entry of `doc[key]` identical to the same-named entry in `owned`, then drop
147
+ * `doc[key]` once empty. Entries that differ, and names `owned` lacks, stay. Mutates `doc`.
148
+ */
149
+ function removeOwnedEntries(doc, key, owned) {
150
+ const entries = doc[key];
151
+ if (!isJsonObject(entries))
152
+ return;
153
+ for (const [name, entry] of Object.entries(owned)) {
154
+ if (JSON.stringify(entries[name]) === JSON.stringify(entry))
155
+ delete entries[name];
156
+ }
157
+ if (Object.keys(entries).length === 0)
158
+ delete doc[key];
159
+ }
150
160
  function isJsonObject(v) {
151
161
  return v !== null && typeof v === "object" && !Array.isArray(v);
152
162
  }
@@ -457,15 +467,10 @@ export async function runUninstall(modules, ctx) {
457
467
  }
458
468
  const raw = fs.readFileSync(absPath, "utf-8");
459
469
  const consumerDoc = JSON.parse(raw);
460
- let templateRaw = fs.readFileSync(templatePath, "utf-8");
461
- // opencode.json ships `@@OPENCODE_*@@` sentinel KEYS that render to the consumer's
462
- // tracker / provider at install; strip-scope keyed on the RAW template never matches
463
- // the rendered keys, so bkit's mcp + provider blocks (a token-referencing config)
464
- // survive a full uninstall. Render the template with the consumer's OWN tracker +
465
- // provider first so the keys line up and the bkit-owned scope strips cleanly.
466
- if (templateRaw.includes("@@OPENCODE_TRACKER_MCP@@")) {
467
- templateRaw = renderOpencodeJson(templatePath, detectOpencodeTracker(consumerDoc), detectOpencodeProvider(consumerDoc));
468
- }
470
+ const templateRaw = fs.readFileSync(templatePath, "utf-8");
471
+ // opencode.json ships `@@OPENCODE_*@@` sentinel KEYS; stripOpencodeJsonScope
472
+ // renders them for every tracker and provider bkit can have written.
473
+ const isOpencodeJson = templateRaw.includes("@@OPENCODE_TRACKER_MCP@@");
469
474
  const templateDoc = JSON.parse(templateRaw);
470
475
  // `.claude/settings.json` is not written verbatim: after rendering the
471
476
  // template, install appends one `WebFetch(domain:<d>)` grant per entry in
@@ -491,7 +496,9 @@ export async function runUninstall(modules, ctx) {
491
496
  }
492
497
  const stripped = MCP_JSON_RELPATHS.has(summary.file)
493
498
  ? stripMcpTrackerEntries(consumerDoc, templateDoc)
494
- : stripTier2JsonScope(consumerDoc, templateDoc);
499
+ : isOpencodeJson
500
+ ? stripOpencodeJsonScope(consumerDoc, templatePath, ctx.cwd)
501
+ : stripTier2JsonScope(consumerDoc, templateDoc);
495
502
  const strippedJson = JSON.stringify(stripped, null, 2) + "\n";
496
503
  if (Object.keys(stripped).length === 0) {
497
504
  // All keys were bkit-owned → delete file
@@ -724,7 +724,8 @@ export async function runUpgradeCommand(upgradeFlags) {
724
724
  }
725
725
  // Network allowlist + MCP allows — OpenCode from renderOpencodeJson; Claude enrich
726
726
  // below; Cursor `.cursor/allowlist.json` + `.cursor/cli.json` only when cursor
727
- // module installed.
727
+ // module installed. Written artifacts get their canonicalHashes refreshed below.
728
+ const artifactWrites = [];
728
729
  {
729
730
  const cwd = process.cwd();
730
731
  if (renderModules.has("cursor")) {
@@ -733,6 +734,7 @@ export async function runUpgradeCommand(upgradeFlags) {
733
734
  writeCursorCliPermissionsArtifact(cwd, upgradeFlags.dryRun),
734
735
  ]) {
735
736
  if (art.wrote) {
737
+ artifactWrites.push(art.path);
736
738
  console.log(`${LOG_PREFIX}${upgradeFlags.dryRun ? " [dry-run]" : ""} upgrade: ${art.path}`);
737
739
  }
738
740
  }
@@ -761,6 +763,7 @@ export async function runUpgradeCommand(upgradeFlags) {
761
763
  ...result.updated,
762
764
  ...renderedDocPaths,
763
765
  ...mcpWs.writes.map((w) => path.relative(process.cwd(), w.path)),
766
+ ...artifactWrites,
764
767
  ],
765
768
  skipped: result.skipped,
766
769
  skippedSeedable: result.skippedSeedable,
@@ -320,8 +320,8 @@ export function readAnchor(text) {
320
320
  return out;
321
321
  }
322
322
  /** `text` with a fresh anchor block on top and every prior one removed, so re-stamping is idempotent. */
323
- export function stampAnchor(text, baseSha, design) {
324
- const header = [ANCHOR_OPEN, `baseSha: ${baseSha}`, `baseRef: ${UPSTREAM}`];
323
+ export function stampAnchor(text, baseSha, design, baseRef = UPSTREAM) {
324
+ const header = [ANCHOR_OPEN, `baseSha: ${baseSha}`, `baseRef: ${baseRef}`];
325
325
  if (design)
326
326
  header.push(`designPath: ${design.path}`, `designBaseSha: ${design.baseSha}`);
327
327
  header.push(ANCHOR_CLOSE);
@@ -947,6 +947,7 @@ function anchorStampVerb(ctx) {
947
947
  }
948
948
  if (baseSha === "")
949
949
  throw new CommandError(EXIT.USAGE, "--base-sha must be non-empty");
950
+ const baseRef = str(ctx.flags.baseRef) ?? UPSTREAM;
950
951
  const designFlag = str(ctx.flags.design);
951
952
  const designFile = designFlag === undefined ? undefined : path.resolve(ctx.cwd, designFlag);
952
953
  const design = designFlag !== undefined && designFile !== undefined && fs.existsSync(designFile)
@@ -956,7 +957,7 @@ function anchorStampVerb(ctx) {
956
957
  }
957
958
  : undefined;
958
959
  const before = fs.readFileSync(file, "utf-8");
959
- const after = stampAnchor(before, baseSha, design);
960
+ const after = stampAnchor(before, baseSha, design, baseRef);
960
961
  // Temp file + rename: a crash mid-write never leaves a half-stamped doc.
961
962
  const tmp = `${file}.bkit-anchor.tmp`;
962
963
  fs.writeFileSync(tmp, after);
@@ -964,6 +965,7 @@ function anchorStampVerb(ctx) {
964
965
  ctx.emit({
965
966
  file: rel,
966
967
  baseSha,
968
+ baseRef,
967
969
  designPath: design?.path ?? null,
968
970
  designBaseSha: design?.baseSha ?? null,
969
971
  changed: before !== after,
@@ -1206,7 +1208,7 @@ export const branchesCommand = {
1206
1208
  run: landVerb,
1207
1209
  },
1208
1210
  "anchor-stamp": {
1209
- summary: "Put a <!-- bkit:anchor --> block recording the base commit on top of a design/plan doc (idempotent).",
1211
+ summary: "Put a <!-- bkit:anchor --> block recording the base commit on top of a design/plan doc or audit report (idempotent).",
1210
1212
  flags: [
1211
1213
  { name: "file", type: "string", required: true, help: "doc to stamp (must exist)" },
1212
1214
  {
@@ -1215,6 +1217,11 @@ export const branchesCommand = {
1215
1217
  required: true,
1216
1218
  help: "base commit the doc was written against (non-empty)",
1217
1219
  },
1220
+ {
1221
+ name: "base-ref",
1222
+ type: "string",
1223
+ help: `ref baseSha was taken from (default ${UPSTREAM}; audit reports pass the audited branch)`,
1224
+ },
1218
1225
  {
1219
1226
  name: "design",
1220
1227
  type: "string",
@@ -1224,6 +1231,7 @@ export const branchesCommand = {
1224
1231
  output: {
1225
1232
  file: "doc stamped",
1226
1233
  baseSha: "base commit stamped",
1234
+ baseRef: "ref stamped",
1227
1235
  designPath: "design path stamped (null when none)",
1228
1236
  designBaseSha: "the design doc's baseSha stamped (null when none; empty when it had no anchor)",
1229
1237
  changed: "false when the doc already carried exactly this block",
@@ -1234,7 +1242,7 @@ export const branchesCommand = {
1234
1242
  "anchor-read": {
1235
1243
  summary: "Read a doc's anchor fields; with --against, decide whether anything landed since its baseSha.",
1236
1244
  flags: [
1237
- { name: "file", type: "string", required: true, help: "design/plan doc" },
1245
+ { name: "file", type: "string", required: true, help: "design/plan doc or audit report" },
1238
1246
  {
1239
1247
  name: "field",
1240
1248
  type: "string",
@@ -2,9 +2,16 @@
2
2
  import * as fs from "node:fs";
3
3
  import * as path from "node:path";
4
4
  /**
5
- * Detect which host modules a consumer has installed, by the presence of each host's
6
- * source-rendered agents directory. `bkit upgrade` re-renders only these hosts — never
7
- * force-creating an opencode/cursor tree — and setup tips key host-specific advice on them.
5
+ * The Antigravity plugin's bkit-written paths (install/modules/antigravity.ts). Any one
6
+ * present marks the host installed, so deleting a single file (the manifest included) still
7
+ * leaves the host detected and its missing files reported as drift.
8
+ */
9
+ const ANTIGRAVITY_SENTINELS = ["plugin.json", "hooks.json", "agents", "skills", "hooks"].map((p) => path.join(".agents", "plugins", "bkit", p));
10
+ /**
11
+ * Detect which host modules a consumer has installed: each host's source-rendered agents
12
+ * directory, or for Antigravity any of its plugin files. `bkit upgrade` re-renders only these
13
+ * hosts — never force-creating an opencode/cursor tree — and setup tips key host-specific
14
+ * advice on them.
8
15
  */
9
16
  export function detectInstalledHostModules(cwd) {
10
17
  const mods = new Set();
@@ -16,7 +23,7 @@ export function detectInstalledHostModules(cwd) {
16
23
  mods.add("opencode");
17
24
  if (fs.existsSync(path.join(cwd, ".codex", "agents")))
18
25
  mods.add("codex");
19
- if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
26
+ if (ANTIGRAVITY_SENTINELS.some((rel) => fs.existsSync(path.join(cwd, rel))))
20
27
  mods.add("antigravity");
21
28
  return mods;
22
29
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cbartens/bkit",
3
- "version": "5.2.2",
3
+ "version": "5.2.3",
4
4
  "private": false,
5
5
  "description": "From vibe coding to production code. A senior engineering team's process, ready-made: AI agents design, plan, build, review, fix and ship your features on Claude Code, Cursor, Codex, Google Antigravity and opencode.",
6
6
  "keywords": [