@cbartens/bkit 5.3.0 → 5.5.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 +20 -7
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/rules.md +14 -9
- package/.bkit/core/.bkit/README.md +19 -6
- package/.bkit/core/.bkit/cloud.md +77 -46
- package/.bkit/core/.bkit/comparison.md +3 -3
- package/.bkit/core/.bkit/install.md +21 -18
- package/.bkit/core/.bkit/lite.md +6 -6
- package/.bkit/core/.bkit/pipeline.md +6 -3
- package/.bkit/core/.bkit/prompts.md +14 -10
- package/.bkit/core/.bkit/providers.md +7 -7
- package/.bkit/core/.bkit/templates.md +46 -10
- package/.bkit/core/.bkit/trackers.md +92 -38
- package/.bkit/core/.bkit/workflows.md +140 -116
- package/.bkit/core/AGENTS.md +2 -2
- 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 +2 -2
- 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 +25 -8
- 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/after/auth.ts +88 -45
- package/.bkit/core/engine/checks/after/github.ts +18 -5
- package/.bkit/core/engine/checks/after/index.ts +1 -1
- package/.bkit/core/engine/checks/after/tools.ts +1 -1
- package/.bkit/core/engine/checks/before/env.ts +28 -18
- package/.bkit/core/engine/checks/before/mcp.ts +4 -2
- package/.bkit/core/engine/checks/status-holes.ts +0 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
- package/.bkit/core/engine/checks/tips/index.ts +49 -27
- package/.bkit/core/engine/cli.ts +27 -18
- package/.bkit/core/engine/commands/ci/ci.ts +107 -0
- package/.bkit/core/engine/commands/comply.ts +25 -16
- package/.bkit/core/engine/commands/install/install.ts +11 -4
- package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
- 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/fids.ts +23 -15
- package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
- package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
- package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
- 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 +26 -17
- package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
- 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/manifest.ts +31 -10
- package/.bkit/core/engine/install/modules/cloud.ts +3 -1
- package/.bkit/core/engine/install/modules/core.ts +97 -4
- package/.bkit/core/engine/install/modules/opencode.ts +5 -0
- package/.bkit/core/engine/install/placeholders.ts +13 -17
- package/.bkit/core/engine/install/write.ts +37 -1
- package/.bkit/core/engine/render/trackers.ts +35 -23
- package/.bkit/core/engine/shared/egress.ts +6 -0
- package/.bkit/core/engine/shared/settings.ts +96 -1
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/hooks/guardrails-tiers.js +1 -1
- package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-design-generate.md +2 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
- package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
- package/.bkit/core/workflows/bkit-auto.md +19 -6
- package/.bkit/core/workflows/bkit-build.md +64 -22
- package/.bkit/core/workflows/bkit-debug.md +72 -28
- package/.bkit/core/workflows/bkit-design.md +101 -37
- package/.bkit/core/workflows/bkit-plan.md +82 -31
- package/.bkit/core/workflows/bkit-ship.md +127 -108
- package/.bkit/shared/.bkit/.env.example +8 -0
- package/.bkit/shared/.claude/bkit-cloud.md +12 -12
- package/.bkit/shared/.claude/settings.json +4 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
- package/.bkit/shared/.cursor/mcp.json +11 -4
- package/.bkit/shared/.mcp.json +11 -4
- package/.bkit/shared/.opencode/opencode.json +2 -0
- package/.bkit/shared/docs/deployments.md +44 -29
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/testing.md +3 -3
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
- package/.bkit/templates/.github/renovate.json5 +1 -1
- package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
- package/.bkit/templates/.husky/pre-commit +10 -4
- package/.bkit/templates/.husky/pre-push +69 -12
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
- package/CHANGELOG.md +85 -1
- package/README.md +102 -100
- package/dist/checks/after/auth.js +81 -45
- package/dist/checks/after/github.js +17 -5
- package/dist/checks/after/index.js +1 -1
- package/dist/checks/after/tools.js +1 -1
- package/dist/checks/before/env.js +24 -17
- package/dist/checks/before/mcp.js +4 -2
- package/dist/checks/status-holes.js +0 -1
- package/dist/checks/tips/catalogue.js +28 -2
- package/dist/checks/tips/index.js +44 -28
- package/dist/cli.js +27 -19
- package/dist/commands/ci/ci.js +100 -0
- package/dist/commands/comply.js +20 -13
- package/dist/commands/install/install.js +10 -4
- package/dist/commands/install/uninstall.js +42 -0
- 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/fids.js +22 -15
- package/dist/commands/workflow/issues.js +90 -41
- package/dist/commands/workflow/ledgers.js +26 -11
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +8 -3
- package/dist/commands/workflow/repo.js +5 -0
- package/dist/commands/workflow/roadmap.js +52 -57
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +20 -13
- package/dist/commands/workflow/workflows.js +397 -251
- package/dist/commands/workflow/workstreams.js +3 -2
- package/dist/commands/workflow/worktrees.js +11 -1
- package/dist/install/manifest.js +30 -10
- package/dist/install/modules/cloud.js +3 -1
- package/dist/install/modules/core.js +95 -5
- package/dist/install/modules/opencode.js +6 -0
- package/dist/install/placeholders.js +13 -19
- package/dist/install/write.js +26 -2
- package/dist/render/trackers.js +34 -20
- package/dist/shared/egress.js +6 -0
- package/dist/shared/settings.js +44 -0
- package/dist/shared/timeouts.js +8 -7
- package/package.json +11 -2
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">
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
|
|
33
33
|
AI coding agents are fast, but on their own they skip what makes software safe to ship: a design someone challenged, a plan someone checked, a second pair of eyes on every change, tests that actually ran. **Vibe coding gets you a demo. Production takes a process.**
|
|
34
34
|
|
|
35
|
-
**bkit is that process, ready-made.** Describe a feature in a GitHub or
|
|
35
|
+
**bkit is that process, ready-made.** Describe a feature in a GitHub, Linear or Jira issue and type one command:
|
|
36
36
|
|
|
37
37
|
```text
|
|
38
38
|
/bkit-design ISSUE-123
|
|
@@ -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
|
|
@@ -119,7 +167,7 @@ What that gets you:
|
|
|
119
167
|
- **The fences grow with every feature.** Each build adds tests every later change has to pass. A prompt-only framework is as strict on your fiftieth feature as on your first; bkit gets stricter.
|
|
120
168
|
- **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, not a guess.
|
|
121
169
|
- **Agents look before they change anything.** Code search ([Serena](https://github.com/oraios/serena)) shows every definition and caller of the code about to change, not just lines with matching words, and [graphify](https://github.com/Graphify-Labs/graphify)'s code map shows what already exists. Fewer bad changes reach the fences at all.
|
|
122
|
-
- **Problems are caught at the nearest fence.** Agent hooks nudge on every edit: read a file before changing it, 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 keeps only what can't run there:
|
|
170
|
+
- **Problems are caught at the nearest fence.** Agent hooks nudge on every edit: read a file before changing it, fix the code rather than loosen a check. The pre-commit hook formats in seconds. The pre-push hook runs type checks, unit tests, integration tests (once you declare that gate), the prose checker and the junk-code scanner before anything leaves your laptop. CI keeps only what can't run there: end-to-end and live-site tests. Hooks, agents and CI's quick-checks lane all run the same `bkit:gate:*` scripts, so most failures show up on your machine first.
|
|
123
171
|
|
|
124
172
|
The agent hooks come with install. Serena, graphify and the git hooks are [templates](#templates) you adopt. Compared with other frameworks: [agents and CI](.bkit/comparison.md#agents-and-ci).
|
|
125
173
|
|
|
@@ -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, Linear or Jira 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, Jira), 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
|
|
|
@@ -266,9 +287,10 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
266
287
|
|
|
267
288
|
### Your tracker is the control panel
|
|
268
289
|
|
|
269
|
-
- **Every run lives on the tracker issue.** bkit reads the tracker issue (e.g. GitHub, Linear), posts progress as it goes, moves the issue along and links the pull request.
|
|
290
|
+
- **Every run lives on the tracker issue.** bkit reads the tracker issue (e.g. GitHub, Linear, Jira), posts progress as it goes, moves the issue along and links the pull request.
|
|
270
291
|
- **Issues that start the right step.** Optional issue forms for a new idea, a well-defined change or a bug ask for what the agents read first, and each names the command to run next. A well-defined change can be the plan itself: what done looks like, the tests and the tasks.
|
|
271
292
|
- **It tells you what to work on next.** `@bkit-utility-update-roadmap` reads your board and the open known bugs and postponed work from the ledgers, then writes a ranked shortlist into `docs/roadmap.md`.
|
|
293
|
+
- **It keeps the tracker tidy.** `@bkit-utility-update-tracker` brings open issues in line with the tracker rules: short titles, the right labels, board status, priority, size, milestone, parent and blocked-by links. It takes priorities from the latest issue prioritisation audit and suggests new milestones and parent issues, but never creates or closes an issue.
|
|
272
294
|
- **See it live:** [bkit's own board](https://github.com/users/cbartens/projects/1/views/1), and the shortlist bkit ranked from it in [`docs/roadmap.md`](docs/roadmap.md).
|
|
273
295
|
|
|
274
296
|
### You stay in control
|
|
@@ -277,35 +299,6 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
277
299
|
- **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
300
|
- **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
301
|
|
|
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
302
|
<a id="token-costs"></a>
|
|
310
303
|
|
|
311
304
|
## Spending fewer tokens
|
|
@@ -356,25 +349,6 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
|
|
|
356
349
|
- **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
350
|
- **Summarise long sessions earlier:** `"autoCompactWindow": 300000` in `.claude/settings.json`, or `model_auto_compact_token_limit` in `.codex/config.toml`. By default a session grows close to the model's full size before it summarises, and every request re-reads all of it. Summaries lose some detail, so bkit suggests this rather than setting it.
|
|
358
351
|
|
|
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
352
|
## FAQ
|
|
379
353
|
|
|
380
354
|
**Do I need to know how to code?**
|
|
@@ -399,7 +373,7 @@ No full run, from design to merge, has taken longer than a day. Each run posts i
|
|
|
399
373
|
**Not without your sign-off.** In the full workflows, work happens in a separate copy of the repo, goes through a pull request, must pass every test, and merges into `dev`, never `main`. Lite workflows skip the pull request and CI, which is why they're only for small, clearly safe changes.
|
|
400
374
|
|
|
401
375
|
**Which issue tracker, and which code host?**
|
|
402
|
-
GitHub Issues or
|
|
376
|
+
GitHub Issues, Linear or Jira for the tracker. The code has to live on GitHub: pull requests, CI and cloud mode run there.
|
|
403
377
|
|
|
404
378
|
**Is this the bkit Vibecoding Kit?**
|
|
405
379
|
No. [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code) is a separate project that shares the name. This bkit is `@cbartens/bkit` on npm, at [github.com/cbartens/bkit](https://github.com/cbartens/bkit).
|
|
@@ -413,7 +387,7 @@ On real bkit sessions they saved 1–3% of the bill, and each changes what the a
|
|
|
413
387
|
<details>
|
|
414
388
|
<summary><strong>For engineers: what's under the hood</strong></summary>
|
|
415
389
|
|
|
416
|
-
- **Isolation.** Every run gets its own git worktree; a per-feature lock blocks duplicate runs of the same feature
|
|
390
|
+
- **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
391
|
- **Resume from state, not session.** Run state lives in `status.jsonl` and `docs/plans/`. A crashed or interrupted run resumes from its last completed step, on any host.
|
|
418
392
|
- **Mechanical step gates.** `bkit steps finish` checks each step's verdict and artifacts before the workflow moves on; build ticks a task only on a confirmed artifact; ship's deferred sweep fails the merge on an unplanned gap.
|
|
419
393
|
- **Engine.** The `bkit` CLI is TypeScript in [`.bkit/core/engine/`](.bkit/core/engine/), built to `dist/`, covered by 5,800+ tests. `commands/` holds what you type; `install/`, `render/`, `checks/`, `ledgers/` and `shared/` hold the code underneath; `audits/` holds the tests that read shipped text.
|
|
@@ -440,6 +414,34 @@ On real bkit sessions they saved 1–3% of the bill, and each changes what the a
|
|
|
440
414
|
| [`.bkit/comparison.md`](.bkit/comparison.md) | Comparison with other AI development frameworks and with _Agentic Design Patterns_ |
|
|
441
415
|
| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
|
|
442
416
|
|
|
417
|
+
<a id="quick-start"></a>
|
|
418
|
+
|
|
419
|
+
## Quick start
|
|
420
|
+
|
|
421
|
+
**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.
|
|
422
|
+
|
|
423
|
+
**Easiest:** copy the [install prompt](.bkit/install.md#install--first-time) into your AI coding tool and let it do the setup.
|
|
424
|
+
|
|
425
|
+
**By hand:** bkit is public on npm and installs like any other package, with no token or registry setup.
|
|
426
|
+
|
|
427
|
+
```bash
|
|
428
|
+
pnpm add -D @cbartens/bkit
|
|
429
|
+
pnpm bkit install --claude # pick your tools: --claude --cursor --codex --antigravity --opencode=<provider>
|
|
430
|
+
# opencode provider: openrouter | ollama | opencode-zen | opencode-go
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
**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.
|
|
434
|
+
|
|
435
|
+
Adopt the [templates](#templates) you want from `.bkit/templates/`, open an issue, and run the first step from your AI tool:
|
|
436
|
+
|
|
437
|
+
```text
|
|
438
|
+
/bkit-design ISSUE-123
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
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.
|
|
442
|
+
|
|
443
|
+
Full install, upgrade and CI setup: [`.bkit/install.md`](.bkit/install.md). Tracker labels and environment variables: [`.bkit/README.md`](.bkit/README.md#prerequisites).
|
|
444
|
+
|
|
443
445
|
## Credits
|
|
444
446
|
|
|
445
447
|
bkit's process was worked out over months of building real products with it. These projects sharpened specific ideas along the way:
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// the cloud router's), and the cloud-dashboard secrets checklist.
|
|
3
3
|
import * as fs from "node:fs";
|
|
4
4
|
import * as path from "node:path";
|
|
5
|
-
import {
|
|
5
|
+
import { spawnSync } from "node:child_process";
|
|
6
6
|
import { readJsonFile } from "../../shared/json.js";
|
|
7
7
|
import { readBkitConfig } from "../../shared/settings.js";
|
|
8
8
|
/**
|
|
@@ -68,27 +68,33 @@ export function detectGhMcpToken(cwd) {
|
|
|
68
68
|
}
|
|
69
69
|
return null;
|
|
70
70
|
}
|
|
71
|
+
/**
|
|
72
|
+
* Names of the consumer repo's GitHub Actions secrets or variables (repo level only).
|
|
73
|
+
* `null` if gh CLI unavailable, unauthenticated, or not a GitHub repo.
|
|
74
|
+
*/
|
|
75
|
+
function listGhNames(kind) {
|
|
76
|
+
const res = spawnSync("gh", [kind, "list", "--json", "name", "-q", ".[].name"], {
|
|
77
|
+
encoding: "utf-8",
|
|
78
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
79
|
+
timeout: 5000,
|
|
80
|
+
});
|
|
81
|
+
if (res.status !== 0 || typeof res.stdout !== "string")
|
|
82
|
+
return null;
|
|
83
|
+
return res.stdout
|
|
84
|
+
.split("\n")
|
|
85
|
+
.map((s) => s.trim())
|
|
86
|
+
.filter(Boolean);
|
|
87
|
+
}
|
|
71
88
|
/**
|
|
72
89
|
* Detect whether a named secret is set on the consumer's GitHub repo.
|
|
73
90
|
* Returns "present" | "missing" | "unknown".
|
|
74
91
|
* "unknown" if gh CLI unavailable, unauthenticated, or not a GitHub repo.
|
|
75
92
|
*/
|
|
76
93
|
export function detectGhSecret(secretName) {
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
encoding: "utf-8",
|
|
80
|
-
stdio: ["ignore", "pipe", "ignore"],
|
|
81
|
-
timeout: 5000,
|
|
82
|
-
});
|
|
83
|
-
const names = out
|
|
84
|
-
.split("\n")
|
|
85
|
-
.map((s) => s.trim())
|
|
86
|
-
.filter(Boolean);
|
|
87
|
-
return names.includes(secretName) ? "present" : "missing";
|
|
88
|
-
}
|
|
89
|
-
catch {
|
|
94
|
+
const names = listGhNames("secret");
|
|
95
|
+
if (names === null)
|
|
90
96
|
return "unknown";
|
|
91
|
-
|
|
97
|
+
return names.includes(secretName) ? "present" : "missing";
|
|
92
98
|
}
|
|
93
99
|
/**
|
|
94
100
|
* Build the consolidated "three locations to sync secrets" advisory. Fires when
|
|
@@ -105,17 +111,19 @@ export function buildCloudDashboardsAdvisory(cwd) {
|
|
|
105
111
|
const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
|
|
106
112
|
if (!hasRouter && !hasClaude && !hasCursor)
|
|
107
113
|
return null;
|
|
108
|
-
// cloud=claude path (bkit-cloud.yml): GitHub-tracker only, ANTHROPIC_API_KEY
|
|
109
|
-
// cloud=cursor path (.cursor/): BKIT_LINEAR_API_KEY for Cursor dashboard.
|
|
110
|
-
// Distinguish by recorded variant; fall back to presence-based detection.
|
|
111
|
-
const
|
|
112
|
-
const isCursorCloud =
|
|
114
|
+
// cloud=claude path (bkit-cloud.yml): GitHub-tracker only, ANTHROPIC_API_KEY or federation.
|
|
115
|
+
// cloud=cursor path (.cursor/): BKIT_LINEAR_API_KEY for Cursor dashboard; Linear-tracker only.
|
|
116
|
+
// Distinguish by recorded variant; fall back to presence-based detection under linear.
|
|
117
|
+
const config = readBkitConfig(cwd);
|
|
118
|
+
const isCursorCloud = config.cloudAgents === "cursor" ||
|
|
119
|
+
(!hasRouter && hasCursor && config.issueTracker === "linear");
|
|
113
120
|
const secretList = isCursorCloud ? "`BKIT_LINEAR_API_KEY`" : "`ANTHROPIC_API_KEY`";
|
|
114
121
|
const ghSetLines = isCursorCloud
|
|
115
122
|
? " gh secret set BKIT_LINEAR_API_KEY --body='<value>'\n\n" +
|
|
116
123
|
" Verify: `gh secret list | grep -E 'BKIT_LINEAR_API_KEY'`\n\n"
|
|
117
124
|
: " gh secret set ANTHROPIC_API_KEY --body='<value>'\n\n" +
|
|
118
|
-
" Verify: `gh secret list | grep -E 'ANTHROPIC_API_KEY'`\n\n"
|
|
125
|
+
" Verify: `gh secret list | grep -E 'ANTHROPIC_API_KEY'`\n\n" +
|
|
126
|
+
" Keyless alternative for bkit-cloud.yml (workload identity federation): leave the secret unset and set the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables (`gh variable set`) from a Claude Console federation rule.\n\n";
|
|
119
127
|
const vendorNote = isCursorCloud
|
|
120
128
|
? "BKIT_LINEAR_API_KEY is read from the Linear dashboard (https://linear.app/settings/api)."
|
|
121
129
|
: "ANTHROPIC_API_KEY is read from the Anthropic dashboard (https://console.anthropic.com/settings/keys); `.bkit/.env` holds the same value as BKIT_ANTHROPIC_API_KEY. The Claude GitHub App (`/install-github-app`) is also required for `cloud=claude`.";
|
|
@@ -133,35 +141,63 @@ export function buildCloudDashboardsAdvisory(cwd) {
|
|
|
133
141
|
vendorNote,
|
|
134
142
|
};
|
|
135
143
|
}
|
|
144
|
+
/** Repo variables that, both set, switch bkit-cloud.yml's claude job to workload identity federation. */
|
|
145
|
+
const FEDERATION_VARIABLES = ["ANTHROPIC_FEDERATION_RULE_ID", "ANTHROPIC_ORGANIZATION_ID"];
|
|
136
146
|
/**
|
|
137
|
-
* Detect whether
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
* GitHub-tracker only — no
|
|
141
|
-
*
|
|
147
|
+
* Detect whether `bkit-cloud.yml`'s claude job has a credential. Only fires when
|
|
148
|
+
* `.github/workflows/bkit-cloud.yml` exists. The claude job (claude-code-action) takes the
|
|
149
|
+
* `ANTHROPIC_API_KEY` repo secret OR workload identity federation (both
|
|
150
|
+
* `FEDERATION_VARIABLES` repo variables). The workflow is GitHub-tracker only — no
|
|
151
|
+
* `BKIT_LINEAR_API_KEY` dependency. Silent when gh cannot list secrets; when only the
|
|
152
|
+
* variables are unlistable, a missing key still raises the missing-credential finding.
|
|
142
153
|
*/
|
|
143
154
|
export function detectCiRouterSecrets(cwd) {
|
|
144
|
-
const findings = [];
|
|
145
155
|
const routerPath = path.join(cwd, ".github", "workflows", "bkit-cloud.yml");
|
|
146
156
|
if (!fs.existsSync(routerPath))
|
|
147
|
-
return
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
const
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
id:
|
|
157
|
+
return [];
|
|
158
|
+
const key = detectGhSecret("ANTHROPIC_API_KEY");
|
|
159
|
+
if (key === "unknown")
|
|
160
|
+
return [];
|
|
161
|
+
const variables = listGhNames("variable");
|
|
162
|
+
const federated = variables !== null && FEDERATION_VARIABLES.every((v) => variables.includes(v));
|
|
163
|
+
if (key === "present" && federated) {
|
|
164
|
+
return [
|
|
165
|
+
{
|
|
166
|
+
id: "anthropic-api-key-shadows-federation",
|
|
167
|
+
severity: "advisory",
|
|
168
|
+
detect: "The `ANTHROPIC_API_KEY` repo secret and the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables are all set. claude-code-action uses the key and skips workload identity federation.",
|
|
169
|
+
action: "To run keyless, delete the secret: `gh secret delete ANTHROPIC_API_KEY`. To stay on the key, delete the variables: `gh variable delete ANTHROPIC_FEDERATION_RULE_ID` and `gh variable delete ANTHROPIC_ORGANIZATION_ID`.",
|
|
170
|
+
},
|
|
171
|
+
];
|
|
172
|
+
}
|
|
173
|
+
if (key === "present")
|
|
174
|
+
return [];
|
|
175
|
+
if (federated) {
|
|
176
|
+
if (fs.readFileSync(routerPath, "utf-8").includes("anthropic_federation_rule_id:"))
|
|
177
|
+
return [];
|
|
178
|
+
return [
|
|
179
|
+
{
|
|
180
|
+
id: "anthropic-federation-template-stale",
|
|
157
181
|
severity: "advisory",
|
|
158
|
-
detect: `
|
|
159
|
-
action:
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
});
|
|
163
|
-
}
|
|
164
|
-
// "unknown" → silent skip (CLI absent / unauthenticated).
|
|
182
|
+
detect: "The `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables are set, but `.github/workflows/bkit-cloud.yml` does not pass `anthropic_federation_rule_id` to claude-code-action — the claude job exits no-op.",
|
|
183
|
+
action: "Re-copy the template: `cp .bkit/templates/.github/workflows/bkit-cloud.yml .github/workflows/bkit-cloud.yml`, then re-apply your own edits (the `runs-on` runner at minimum).",
|
|
184
|
+
},
|
|
185
|
+
];
|
|
165
186
|
}
|
|
166
|
-
return
|
|
187
|
+
return [
|
|
188
|
+
{
|
|
189
|
+
id: "anthropic-api-key-secret-missing",
|
|
190
|
+
severity: "advisory",
|
|
191
|
+
detect: variables === null
|
|
192
|
+
? "gh confirms the `ANTHROPIC_API_KEY` repo secret is not set on this GitHub repo, and could not list repo variables to check for the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` federation variables."
|
|
193
|
+
: "gh confirms neither the `ANTHROPIC_API_KEY` repo secret nor both `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables are set on this GitHub repo.",
|
|
194
|
+
action: "`.github/workflows/bkit-cloud.yml`'s claude job needs one claude credential; without it, the job exits no-op. Set ONE of:\n\n" +
|
|
195
|
+
"- API key:\n\n gh secret set ANTHROPIC_API_KEY --body='<paste-value-here>'\n\n" +
|
|
196
|
+
"- Workload identity federation (keyless): Claude Console → Settings → Workload identity → Connect workload → GitHub Actions creates the issuer, service account and federation rule. Then:\n\n" +
|
|
197
|
+
" gh variable set ANTHROPIC_FEDERATION_RULE_ID --body='fdrl_...'\n" +
|
|
198
|
+
" gh variable set ANTHROPIC_ORGANIZATION_ID --body='<organization-uuid>'\n\n" +
|
|
199
|
+
" Optional: `ANTHROPIC_SERVICE_ACCOUNT_ID` (`svac_...`) and `ANTHROPIC_WORKSPACE_ID` (`wrkspc_...`, needed when the rule covers more than one workspace).\n\n" +
|
|
200
|
+
"Then verify: `gh secret list` / `gh variable list`. The workflow itself does not need redeploying — both are read at run time.",
|
|
201
|
+
},
|
|
202
|
+
];
|
|
167
203
|
}
|
|
@@ -64,7 +64,8 @@ export function detectActionsWritePermissions() {
|
|
|
64
64
|
*
|
|
65
65
|
* - `github` → GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN`; `gh` uses `gh auth login`.
|
|
66
66
|
* - `linear` → existing Linear setup message (BKIT_LINEAR_API_KEY + LINEAR_ISSUE_ID).
|
|
67
|
-
* - `
|
|
67
|
+
* - `jira` → admin switch, BKIT_JIRA_API_TOKEN and `bkit.jira` in package.json.
|
|
68
|
+
* - `none` → prompt to run `bkit install --tracker=github`, `--tracker=linear` or `--tracker=jira`.
|
|
68
69
|
*
|
|
69
70
|
* Only fires when bkit workflows are installed (.claude/ or .cursor/ present).
|
|
70
71
|
*/
|
|
@@ -90,6 +91,14 @@ export function buildTrackerSetupAdvisory(cwd) {
|
|
|
90
91
|
action: "Linear tracker: set `BKIT_LINEAR_API_KEY` in `.bkit/.env` (generate at https://linear.app/settings/api). `LINEAR_ISSUE_ID` is injected per-session by the Linear integration — do not hardcode. Run `direnv allow` after setting the key so MCP servers and the preflight hook can authenticate.",
|
|
91
92
|
};
|
|
92
93
|
}
|
|
94
|
+
if (tracker === "jira") {
|
|
95
|
+
return {
|
|
96
|
+
id: "tracker-setup-jira",
|
|
97
|
+
severity: "advisory",
|
|
98
|
+
detect: "bkit tracker is configured as `jira`. Jira Cloud is the active tracker.",
|
|
99
|
+
action: 'Jira tracker: (1) an org admin turns on API-token sign-in for the Rovo MCP server (admin.atlassian.com → Rovo → Rovo MCP server → Authentication → "Allow API token authentication"); (2) create an API token with scopes for the app "Atlassian MCP V2" at https://id.atlassian.com/manage-profile/security/api-tokens and set it as `BKIT_JIRA_API_TOKEN` in `.bkit/.env`, then `direnv allow`; (3) set `bkit.jira.site` (e.g. `https://acme.atlassian.net`) and `bkit.jira.project` (the project key) in package.json. Full steps: `.bkit/trackers.md` § jira.',
|
|
100
|
+
};
|
|
101
|
+
}
|
|
93
102
|
// tracker === "none". Distinguish opt-out (explicit `bkit.issueTracker: "none"`)
|
|
94
103
|
// from undecided (field absent). An explicit `none` silences the nudge, as with the
|
|
95
104
|
// dep-updater advisory.
|
|
@@ -99,7 +108,7 @@ export function buildTrackerSetupAdvisory(cwd) {
|
|
|
99
108
|
id: "tracker-setup-none",
|
|
100
109
|
severity: "advisory",
|
|
101
110
|
detect: "bkit tracker is not configured (`bkit.issueTracker` absent). Workflows run but every tracker call is a no-op.",
|
|
102
|
-
action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended)
|
|
111
|
+
action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended), `--tracker=linear` or `--tracker=jira` to enable tracker integration. GitHub tracker requires `BKIT_GH_TOKEN` in `.bkit/.env` (fine-grained PAT for one owner, classic PAT across owners). Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. Jira tracker requires `BKIT_JIRA_API_TOKEN` in `.bkit/.env` and `bkit.jira` in package.json. To opt out and silence this advisory, set `bkit.issueTracker` to `"none"` in package.json.',
|
|
103
112
|
};
|
|
104
113
|
}
|
|
105
114
|
/**
|
|
@@ -259,6 +268,7 @@ export function detectGithubProjectFieldIdFormat(cwd) {
|
|
|
259
268
|
* opt-out):
|
|
260
269
|
* - `.github/workflows/bkit-cloud.yml` present → `cloud-router` (informational; active)
|
|
261
270
|
* - `bkit.cloudAgents === "none"` → null (opt-out — stay quiet)
|
|
271
|
+
* - `bkit.issueTracker === "jira"` → null (Jira runs locally only)
|
|
262
272
|
* - otherwise (undecided) → `cloud-router-none` (nudge to choose)
|
|
263
273
|
*
|
|
264
274
|
* Only fires when there is a `.github/workflows/` dir (the router wakes on a CI
|
|
@@ -285,14 +295,16 @@ export function buildCloudSetupAdvisory(cwd) {
|
|
|
285
295
|
id: "cloud-router",
|
|
286
296
|
severity: "advisory",
|
|
287
297
|
detect: "Cloud agents: post-CI auto-routing is active (`.github/workflows/bkit-cloud.yml` present). The Claude GitHub App is required — run `/install-github-app` (Claude Code CLI) once if not already done.",
|
|
288
|
-
action: `The workflow requires: the \`ANTHROPIC_API_KEY\` repo secret, the Claude GitHub App (\`/install-github-app\`), and GitHub Actions write permissions (org AND repo). See the \`bkit-auto-setup\` advisory (emitted by \`bkit install --auto=claude\`) and bkit's \`cloud.md\` § Post-CI auto-routing for the full checklist.\n\nbkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".`,
|
|
298
|
+
action: `The workflow requires: the \`ANTHROPIC_API_KEY\` repo secret OR the \`ANTHROPIC_FEDERATION_RULE_ID\` + \`ANTHROPIC_ORGANIZATION_ID\` repo variables (keyless workload identity federation), the Claude GitHub App (\`/install-github-app\`), and GitHub Actions write permissions (org AND repo). See the \`bkit-auto-setup\` advisory (emitted by \`bkit install --auto=claude\`) and bkit's \`cloud.md\` § Post-CI auto-routing for the full checklist.\n\nbkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".`,
|
|
289
299
|
};
|
|
290
300
|
}
|
|
291
301
|
// No router present — distinguish opt-out from undecided.
|
|
292
|
-
const { cloudAgents, cloudAgentsExplicit } = readBkitConfig(cwd);
|
|
302
|
+
const { cloudAgents, cloudAgentsExplicit, issueTracker } = readBkitConfig(cwd);
|
|
293
303
|
if (cloudAgents === "none" && cloudAgentsExplicit) {
|
|
294
304
|
return null; // consumer explicitly chose `none` — stay quiet
|
|
295
305
|
}
|
|
306
|
+
if (issueTracker === "jira")
|
|
307
|
+
return null; // no cloud setup exists for a Jira tracker
|
|
296
308
|
// Only nudge if there's a workflows dir for the router to wake on.
|
|
297
309
|
if (!fs.existsSync(path.join(cwd, ".github", "workflows")))
|
|
298
310
|
return null;
|
|
@@ -301,7 +313,7 @@ export function buildCloudSetupAdvisory(cwd) {
|
|
|
301
313
|
severity: "advisory",
|
|
302
314
|
detect: "Cloud agents: post-CI auto-routing is not configured. `.github/workflows/` exists but no `bkit-cloud.yml` — CI pass/fail does not auto-dispatch bkit-ship / bkit-debug.",
|
|
303
315
|
action: "Optional post-install decision. For a GitHub-tracker repo: `pnpm bkit install --auto=claude --tracker=github`. For a Linear-tracker repo: `pnpm bkit install --auto=cursor --tracker=linear`.\n\n" +
|
|
304
|
-
"Prerequisites for `--auto=claude`: `ANTHROPIC_API_KEY` repo secret + Claude GitHub App (`/install-github-app`) + GitHub Actions write permissions.\n\n" +
|
|
316
|
+
"Prerequisites for `--auto=claude`: `ANTHROPIC_API_KEY` repo secret (or the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables for keyless workload identity federation) + Claude GitHub App (`/install-github-app`) + GitHub Actions write permissions.\n\n" +
|
|
305
317
|
'To opt out and silence this advisory, set `bkit.cloudAgents` to `"none"` in package.json.',
|
|
306
318
|
};
|
|
307
319
|
}
|
|
@@ -308,7 +308,7 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
|
|
|
308
308
|
const cloudSetup = buildCloudSetupAdvisory(cwd);
|
|
309
309
|
if (cloudSetup)
|
|
310
310
|
phase3.push(cloudSetup);
|
|
311
|
-
// bkit-cloud.yml needs the ANTHROPIC_API_KEY repo secret.
|
|
311
|
+
// bkit-cloud.yml's claude job needs the ANTHROPIC_API_KEY repo secret or federation variables.
|
|
312
312
|
for (const f of detectCiRouterSecrets(cwd))
|
|
313
313
|
phase3.push(f);
|
|
314
314
|
// bkit-cloud.yml also needs repo Actions write permissions + PR-creation
|
|
@@ -106,7 +106,7 @@ const BKIT_STUBS = [
|
|
|
106
106
|
{
|
|
107
107
|
id: "coverage",
|
|
108
108
|
file: ".github/workflows/bkit-ci.yml",
|
|
109
|
-
description: "Report vitest coverage on PRs and in every run's job summary via davelosert/vitest-coverage-report-action (free, runs inside Actions with GITHUB_TOKEN — no third-party service, safe for private repos). PER-TIER: unit and integration are measured and commented SEPARATELY (a single merged number lets integration mask a hollow unit suite — coverage is a union). Report-only by default: nothing fails the build until a threshold is set. Enabling (documented in the stub header): (1) add `@vitest/coverage-v8` (pinned to your vitest major) plus a vitest.config coverage block with `reporter: ['text','json-summary','json']` and `reportOnFailure: true` — json-summary + json are load-bearing (the action reads coverage-summary.json and coverage-final.json); (2) run coverage TWICE into separate dirs — unit → coverage/unit (exclude integration files), integration → coverage/integration — so each tier gets its own honest number (avoids the last-writer-wins clobber a second same-dir run would cause); (3) add a JOB-LEVEL permissions block to bkit-tests-unit with `actions: read` + `contents: read` + `pull-requests: write` — job-level REPLACES the workflow-level block (not additive) and the Check
|
|
109
|
+
description: "Report vitest coverage on PRs and in every run's job summary via davelosert/vitest-coverage-report-action (free, runs inside Actions with GITHUB_TOKEN — no third-party service, safe for private repos). PER-TIER: unit and integration are measured and commented SEPARATELY (a single merged number lets integration mask a hollow unit suite — coverage is a union). Report-only by default: nothing fails the build until a threshold is set. Enabling (documented in the stub header): (1) add `@vitest/coverage-v8` (pinned to your vitest major) plus a vitest.config coverage block with `reporter: ['text','json-summary','json']` and `reportOnFailure: true` — json-summary + json are load-bearing (the action reads coverage-summary.json and coverage-final.json); (2) run coverage TWICE into separate dirs — unit → coverage/unit (exclude integration files), integration → coverage/integration — so each tier gets its own honest number (avoids the last-writer-wins clobber a second same-dir run would cause); (3) add a JOB-LEVEL permissions block to bkit-tests-unit with `actions: read` + `contents: read` + `pull-requests: write` — job-level REPLACES the workflow-level block (not additive) and the Check Tree Cache step needs `actions: read`, so omitting it breaks the cache step; (4) two report steps with distinct `name:` (unit / integration) pointing at each dir's coverage-summary.json + coverage-final.json; the unit step runs on every event (`if: !cancelled()` plus a `hashFiles` guard on its summary), sets `vite-config-path: vitest.unit.config.ts` so the job summary and PR comment show the floor as the target, and comments only on same-repo PRs (`comment-on: pr`, else `none`). SEPARATE LANES (one job per tier): put the integration run + report + its OWN pull-requests: write block in bkit-tests-integration, not bkit-tests-unit — each lane posts its own comment. Thresholds are opt-in and PER TIER: UNIT is the gate — put `coverage.thresholds.branches` in a `vitest.unit.config.ts` (`mergeConfig` over vitest.config) that ONLY the unit run loads via `-c` (vitest coverage is per-RUN/root config, NOT per-project — `projects` does not scope it and a `thresholds` block in vitest.config reds BOTH runs; the report action reads the same file as raw text, so keep the floor on one unquoted `branches: <n>` line and no other metric name + colon + number in it; branches is the meaningful floor, set to current and ratchet up). INTEGRATION is REPORT-ONLY — gate it on EXECUTION (the capstone's integration_ran > 0), not a %: a whole-repo integration % is denominator-noise (it covers boundaries/flows, not pure logic). For a real integration %, add `--coverage.include=src/server/**` on the integration run (same CLI-flag idiom as --exclude) then set a floor, or ratchet from current — never a picked number. Fork PRs: GITHUB_TOKEN is read-only, so the unit step sets `comment-on: none` there (its job summary still lands) and the integration step keeps the `head.repo == repo` guard (or use the action's workflow_run two-workflow pattern). Guard the integration report on `hashFiles('coverage/integration/coverage-summary.json') != ''` so a repo with no integration tier skips it cleanly.",
|
|
110
110
|
},
|
|
111
111
|
{
|
|
112
112
|
id: "e2e-coverage",
|