@cbartens/bkit 5.0.3 → 5.2.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 +14 -10
- package/.bkit/core/.agents/docs.md +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +93 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +137 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
- package/.bkit/core/.agents/rules.md +10 -6
- package/.bkit/core/.agents/shortcuts.md +73 -0
- package/.bkit/core/.agents/skills.md +5 -3
- package/.bkit/core/.bkit/LICENSE.md +18 -140
- package/.bkit/core/.bkit/README.md +13 -9
- package/.bkit/core/.bkit/cloud.md +12 -15
- package/.bkit/core/.bkit/comparison.md +68 -16
- package/.bkit/core/.bkit/install.md +36 -11
- package/.bkit/core/.bkit/jsonl.md +0 -1
- package/.bkit/core/.bkit/prompts.md +83 -81
- package/.bkit/core/.bkit/providers.md +110 -28
- package/.bkit/core/.bkit/templates.md +42 -13
- package/.bkit/core/.bkit/workflows.md +64 -42
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
- package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
- package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
- package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
- package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
- package/.bkit/core/AGENTS.md +11 -0
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
- package/.bkit/core/docs/templates/bkit-plan.md +6 -3
- package/.bkit/core/engine/checks/after/auth.ts +32 -0
- package/.bkit/core/engine/checks/after/github.ts +4 -4
- package/.bkit/core/engine/checks/after/index.ts +36 -50
- package/.bkit/core/engine/checks/after/managed.ts +44 -1
- package/.bkit/core/engine/checks/before/index.ts +5 -4
- package/.bkit/core/engine/checks/before/mcp.ts +60 -54
- package/.bkit/core/engine/checks/status-holes.ts +1 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
- package/.bkit/core/engine/checks/tips/detect.ts +144 -0
- package/.bkit/core/engine/checks/tips/index.ts +174 -0
- package/.bkit/core/engine/cli.ts +82 -18
- package/.bkit/core/engine/commands/install/check.ts +2 -0
- package/.bkit/core/engine/commands/install/doctor.ts +14 -1
- package/.bkit/core/engine/commands/install/install.ts +59 -9
- package/.bkit/core/engine/commands/install/uninstall.ts +59 -34
- package/.bkit/core/engine/commands/install/upgrade.ts +30 -28
- package/.bkit/core/engine/commands/launch.ts +33 -11
- package/.bkit/core/engine/commands/tips.ts +16 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +20 -2
- package/.bkit/core/engine/commands/workflow/runs.ts +82 -18
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
- package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
- package/.bkit/core/engine/install/cloud-env.ts +7 -21
- package/.bkit/core/engine/install/hosts.ts +21 -0
- package/.bkit/core/engine/install/managed-block.ts +36 -0
- package/.bkit/core/engine/install/manifest.ts +83 -5
- package/.bkit/core/engine/install/modules/antigravity.ts +266 -0
- package/.bkit/core/engine/install/modules/claude.ts +6 -6
- package/.bkit/core/engine/install/modules/cloud.ts +2 -2
- package/.bkit/core/engine/install/modules/codex.ts +8 -5
- package/.bkit/core/engine/install/modules/core.ts +30 -10
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/index.ts +33 -6
- package/.bkit/core/engine/install/modules/opencode.ts +4 -4
- package/.bkit/core/engine/install/payload-links.ts +6 -10
- package/.bkit/core/engine/install/placeholders.ts +1 -1
- package/.bkit/core/engine/install/version-file.ts +17 -9
- package/.bkit/core/engine/install/write.ts +68 -1
- package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
- package/.bkit/core/engine/render/hosts.ts +174 -1
- package/.bkit/core/engine/render/models.ts +10 -0
- package/.bkit/core/engine/shared/package-roots.ts +8 -10
- package/.bkit/core/hooks/antigravity-hook.js +67 -0
- package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
- package/.bkit/core/hooks/gateguard-engine.js +16 -6
- package/.bkit/core/hooks/guardrails-read.js +23 -0
- package/.bkit/core/hooks/readguard-engine.js +259 -0
- package/.bkit/core/hooks/readguard-payload.js +67 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-1.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-2.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +2 -1
- package/.bkit/core/prompts/bkit-build-install-skills.md +7 -5
- package/.bkit/core/prompts/bkit-build-plan-current.md +2 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +6 -2
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +2 -1
- package/.bkit/core/prompts/bkit-build-plan-verify.md +12 -4
- package/.bkit/core/prompts/bkit-build-summary.md +2 -1
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -1
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +2 -1
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +2 -1
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +2 -1
- package/.bkit/core/prompts/bkit-debug-summary.md +2 -1
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +2 -1
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +2 -1
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +2 -1
- package/.bkit/core/prompts/bkit-design-generate.md +10 -5
- package/.bkit/core/prompts/bkit-design-organise.md +2 -1
- package/.bkit/core/prompts/bkit-design-review-1.md +2 -1
- package/.bkit/core/prompts/bkit-design-review-2.md +2 -1
- package/.bkit/core/prompts/bkit-design-spike.md +2 -1
- package/.bkit/core/prompts/bkit-design-summary.md +2 -1
- package/.bkit/core/prompts/bkit-design-update.md +2 -1
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +2 -1
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +4 -3
- package/.bkit/core/prompts/bkit-plan-generate.md +2 -1
- package/.bkit/core/prompts/bkit-plan-review-1.md +2 -1
- package/.bkit/core/prompts/bkit-plan-review-2.md +2 -1
- package/.bkit/core/prompts/bkit-plan-review-3.md +2 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +3 -2
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +3 -2
- package/.bkit/core/prompts/bkit-plan-summary.md +2 -1
- package/.bkit/core/prompts/bkit-plan-update.md +3 -2
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +2 -1
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +2 -1
- package/.bkit/core/prompts/bkit-ship-summary.md +2 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +2 -1
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-failures.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -3
- package/.bkit/core/workflows/bkit-auto.md +1 -1
- package/.bkit/core/workflows/bkit-build.md +35 -21
- package/.bkit/core/workflows/bkit-debug.md +31 -22
- package/.bkit/core/workflows/bkit-design.md +83 -38
- package/.bkit/core/workflows/bkit-plan.md +10 -2
- package/.bkit/core/workflows/bkit-ship.md +10 -2
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +36 -0
- package/.bkit/shared/.agents/plugins/bkit/plugin.json +5 -0
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.codex/hooks.json +21 -0
- package/.bkit/shared/.cursor/hooks.json +6 -1
- package/.bkit/shared/.opencode/opencode.json +1 -1
- package/.bkit/shared/GEMINI.md +11 -0
- package/.bkit/shared/docs/deployments.md +1 -1
- package/.bkit/shared/docs/security.md +3 -3
- package/.bkit/shared/docs/testing.md +12 -1
- package/.bkit/templates/.github/dependabot.yml +6 -0
- package/.bkit/templates/.github/renovate.json5 +3 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +24 -13
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
- package/.bkit/templates/.prettierignore +4 -1
- package/.bkit/templates/context/bkit-expo.md +22 -13
- package/.bkit/templates/context/bkit-github.md +20 -6
- package/.bkit/templates/context/bkit-inngest.md +10 -4
- package/.bkit/templates/context/bkit-maestro.md +5 -5
- package/.bkit/templates/context/bkit-playwright.md +3 -3
- package/.bkit/templates/context/bkit-sentry.md +6 -5
- package/.bkit/templates/context/bkit-stripe.md +31 -8
- package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
- package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +2 -2
- package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
- package/.bkit/templates/slop-scan.config.json +10 -3
- package/CHANGELOG.md +62 -0
- package/LICENSE.md +21 -161
- package/README.md +66 -35
- package/dist/checks/after/auth.js +28 -0
- package/dist/checks/after/github.js +4 -4
- package/dist/checks/after/index.js +29 -45
- package/dist/checks/after/managed.js +41 -1
- package/dist/checks/before/index.js +5 -4
- package/dist/checks/before/mcp.js +53 -53
- package/dist/checks/status-holes.js +1 -1
- package/dist/checks/tips/catalogue.js +297 -0
- package/dist/checks/tips/detect.js +130 -0
- package/dist/checks/tips/index.js +146 -0
- package/dist/cli.js +68 -17
- package/dist/commands/install/check.js +2 -0
- package/dist/commands/install/doctor.js +9 -1
- package/dist/commands/install/install.js +49 -8
- package/dist/commands/install/uninstall.js +61 -34
- package/dist/commands/install/upgrade.js +31 -33
- package/dist/commands/launch.js +27 -11
- package/dist/commands/tips.js +10 -0
- package/dist/commands/workflow/prs.js +13 -1
- package/dist/commands/workflow/runs.js +74 -18
- package/dist/commands/workflow/runtime.js +8 -0
- package/dist/commands/workflow/steps.js +1 -0
- package/dist/commands/workflow/tests.js +541 -4
- package/dist/commands/workflow/workstreams.js +4 -4
- package/dist/install/cloud-env.js +3 -14
- package/dist/install/hosts.js +22 -0
- package/dist/install/managed-block.js +36 -0
- package/dist/install/manifest.js +79 -4
- package/dist/install/modules/antigravity.js +225 -0
- package/dist/install/modules/claude.js +6 -6
- package/dist/install/modules/cloud.js +2 -2
- package/dist/install/modules/codex.js +8 -5
- package/dist/install/modules/core.js +21 -6
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/index.js +17 -6
- package/dist/install/modules/opencode.js +4 -4
- package/dist/install/payload-links.js +5 -5
- package/dist/install/placeholders.js +1 -1
- package/dist/install/version-file.js +12 -3
- package/dist/install/write.js +61 -2
- package/dist/render/hosts.js +149 -1
- package/dist/render/models.js +9 -0
- package/dist/shared/package-roots.js +8 -11
- package/package.json +8 -8
- package/.bkit/core/LICENSE.md +0 -149
- package/.bkit/shared/LICENSE.md +0 -22
- package/.bkit/templates/LICENSE.md +0 -22
package/README.md
CHANGED
|
@@ -8,9 +8,9 @@
|
|
|
8
8
|
<p align="center">
|
|
9
9
|
<a href="https://github.com/cbartens/bkit/actions/workflows/bkit-ci.yml"><img alt="CI" src="https://github.com/cbartens/bkit/actions/workflows/bkit-ci.yml/badge.svg?branch=main"></a>
|
|
10
10
|
<a href="https://www.npmjs.com/package/@cbartens/bkit"><img alt="npm version" src="https://img.shields.io/npm/v/@cbartens/bkit"></a>
|
|
11
|
-
<a href="#license"><img alt="License:
|
|
11
|
+
<a href="#license"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
|
|
12
12
|
<img alt="Node 20+" src="https://img.shields.io/badge/node-%E2%89%A520-339933">
|
|
13
|
-
<img alt="Works with Claude Code, Cursor, Codex and opencode" src="https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Cursor%20%C2%B7%20Codex%20%C2%B7%20opencode-8250df">
|
|
13
|
+
<img alt="Works with Claude Code, Cursor, Codex, Antigravity and opencode" src="https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Cursor%20%C2%B7%20Codex%20%C2%B7%20Antigravity%20%C2%B7%20opencode-8250df">
|
|
14
14
|
</p>
|
|
15
15
|
|
|
16
16
|
<p align="center">
|
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
<a href="#a-ci-pipeline-built-the-way-senior-teams-build-them">CI template</a> ·
|
|
20
20
|
<a href="#right-context-at-the-right-step">Context</a> ·
|
|
21
21
|
<a href="#faq">FAQ</a> ·
|
|
22
|
+
<a href=".bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks">Comparison</a> ·
|
|
22
23
|
<a href=".bkit/install.md">Install guide</a>
|
|
23
24
|
</p>
|
|
24
25
|
|
|
@@ -29,12 +30,12 @@ AI coding agents are fast, but on their own they skip the parts that make softwa
|
|
|
29
30
|
- **For solo founders and makers** who have outgrown vibe coding: you get the habits of a senior engineering team without hiring one. You need to be able to read a plan and make a call, not write the code.
|
|
30
31
|
- **For engineers** who want a proven agentic process instead of building their own: rules, prompts, workflows, guardrails, audits and a CI pipeline that already work together.
|
|
31
32
|
|
|
32
|
-
**
|
|
33
|
+
**Researched and battle-tested, not a weekend prompt pack.** bkit is built with bkit. Its rules, prompts and workflows come from months of research into how agentic engineering works best, refined over >1,000 commits, >500 issues and >100 merged pull requests run through its own pipeline. That history is recorded in >200 lessons and >300 decisions agents read before they start. How it compares with other AI development frameworks, feature by feature: [`.bkit/comparison.md`](.bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks).
|
|
33
34
|
|
|
34
35
|
<p align="center">
|
|
35
36
|
<picture>
|
|
36
37
|
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-features-dark.svg">
|
|
37
|
-
<img alt="What ships with bkit, one coloured row per phase. Design: three rival designs, probe code for the risky unknowns, reads your history, reviewed for failure modes. Plan: five reviewers, big work split up, learns from past bugs and postponed work, more than 30 audits. Build:
|
|
38
|
+
<img alt="What ships with bkit, one coloured row per phase. Design: three rival designs, probe code for the risky unknowns, reads your history, reviewed for failure modes. Plan: five reviewers, big work split up, learns from past bugs and postponed work, more than 30 audits. Build: test first and verified, hunts bugs and security holes, checks the plan is still current, skills on demand. Debug: outside evidence from CI and your platforms, root cause first, hard-bug mode, knows when to stop. Ship: honest CI, nothing quietly dropped, docs and memory, never touches main. Every phase: any AI tool, best model per job, independent review, laptop to cloud." src=".github/assets/bkit-features-light.svg" width="100%">
|
|
38
39
|
</picture>
|
|
39
40
|
</p>
|
|
40
41
|
|
|
@@ -48,7 +49,7 @@ Everything a senior team would otherwise write down over years, in files you can
|
|
|
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
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. |
|
|
50
51
|
| Agent rules | >70 | One shared rulebook every agent follows: read before editing, never defer silently, report honestly, never rewrite history. |
|
|
51
|
-
| Guardrails | >10 hook files | Block dangerous commands and make agents investigate before they edit, on all
|
|
52
|
+
| Guardrails | >10 hook files | Block dangerous commands and make agents investigate before they edit, on all five AI tools. |
|
|
52
53
|
| Audits | >30 | Security, privacy, accessibility, performance, reliability, database, LLM usage, cost and more. Findings feed straight into a plan. |
|
|
53
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. |
|
|
54
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. |
|
|
@@ -62,7 +63,7 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
|
|
|
62
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. |
|
|
64
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. |
|
|
65
|
-
| Build it | `/bkit-build` | Checks the plan still matches the code, writes
|
|
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. |
|
|
66
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. |
|
|
67
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. |
|
|
68
69
|
| Health check | >30 audits | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
|
|
@@ -73,7 +74,7 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
|
|
|
73
74
|
<p align="center">
|
|
74
75
|
<picture>
|
|
75
76
|
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-pipeline-dark.svg">
|
|
76
|
-
<img alt="The bkit pipeline: design, plan, build and ship, with debug fixing failed tests. Each dot is one of 40 AI agents: 10 in design, 10 in plan, 11 in build, 5 in debug and 4 in ship. It waits for your sign-off after design, after plan and before merge, merges into dev, and leaves production to you. Runs on Claude Code, Cursor, Codex and opencode." src=".github/assets/bkit-pipeline-light.svg" width="100%">
|
|
77
|
+
<img alt="The bkit pipeline: design, plan, build and ship, with debug fixing failed tests. Each dot is one of 40 AI agents: 10 in design, 10 in plan, 11 in build, 5 in debug and 4 in ship. It waits for your sign-off after design, after plan and before merge, merges into dev, and leaves production to you. Runs on Claude Code, Cursor, Codex, Antigravity and opencode." src=".github/assets/bkit-pipeline-light.svg" width="100%">
|
|
77
78
|
</picture>
|
|
78
79
|
</p>
|
|
79
80
|
|
|
@@ -86,18 +87,30 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
|
|
|
86
87
|
</picture>
|
|
87
88
|
</p>
|
|
88
89
|
|
|
89
|
-
|
|
90
|
+
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.
|
|
90
91
|
|
|
91
92
|
## A CI pipeline built the way senior teams build them
|
|
92
93
|
|
|
93
|
-
CI (continuous integration)
|
|
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:
|
|
95
|
+
|
|
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.
|
|
101
|
+
|
|
102
|
+
<p align="center">
|
|
103
|
+
<picture>
|
|
104
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-ci-dark.svg">
|
|
105
|
+
<img alt="bkit's CI pipeline, flowing left to right: plan the run (work out what to test); check and build (quick checks, unit tests, integration tests, web, iOS and Android builds, database migrations); set the stage (preview deploy, reset test data); test like a user (web, iOS and Android end-to-end tests, and a live-site check); tidy up. Every lane feeds one final check, the only one merging needs, which fails if any lane failed, was skipped or ran zero tests. /bkit-build starts CI by opening the pull request, /bkit-debug reads the logs of any lane that fails and fixes it, and /bkit-ship merges only when the final check is green." src=".github/assets/bkit-ci-light.svg" width="100%">
|
|
106
|
+
</picture>
|
|
107
|
+
</p>
|
|
94
108
|
|
|
95
109
|
- **Ready on day one.** Two lanes run side by side: quick checks (type checking, formatting, a prose checker, a scanner for junk code AI tends to write, a workflow-file checker, and `bkit check`) and unit tests.
|
|
96
|
-
- **A green tick means every test ran.** One final check joins all lanes and is the only one branch protection needs. It fails if any lane failed, was skipped or cancelled, or ran zero tests, so a half-finished run can't pass as tested.
|
|
110
|
+
- **A green tick means every test ran.** One final check joins all lanes and is the only one branch protection needs. It fails if any lane failed, was skipped or cancelled, or ran zero tests, so a half-finished run can't pass as tested. The gates audit flags any check that can never fail.
|
|
97
111
|
- **Grows with your project.** >20 ready-to-enable building blocks: integration tests, end-to-end tests for web, iOS and Android, database migrations (locked once merged, with security-policy checks), coverage reports, waiting for preview deploys, live checks against the deployed site, smoke and health checks, and a planner that runs only what a change affects. `bkit check` reminds you of each one until you enable or delete it.
|
|
98
112
|
- **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.
|
|
99
113
|
- **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.
|
|
100
|
-
- **Wired into the workflows.** `/bkit-ship` merges only when the final check is green, `/bkit-debug` reads its failed logs, the cloud router starts from its result, and the gates audit flags any check that can never fail.
|
|
101
114
|
|
|
102
115
|
## Right context at the right step
|
|
103
116
|
|
|
@@ -120,7 +133,7 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
|
|
|
120
133
|
### The quality is real
|
|
121
134
|
|
|
122
135
|
- **Everything is checked by an agent that didn't write it.** An AI checking its own work tends to approve it. bkit gives every design, plan and code change to separate reviewers, each with one job (one hunts bugs, another security holes). They never see each other's verdicts, and several review groups mix models on purpose, so one model's blind spot is less likely to get past all of them.
|
|
123
|
-
- **"Done" is checked by code, not taken on trust.** Every step's output is verified before the next step starts, a task is ticked only when its result really exists, and a silent TODO or skipped test blocks the merge.
|
|
136
|
+
- **"Done" is checked by code, not taken on trust.** Every step's output is verified before the next step starts, a task is ticked only when its result really exists, each task's tests must be seen failing before its code is written, and a silent TODO or skipped test blocks the merge.
|
|
124
137
|
- **Broken builds fix themselves, and stay fixed.** `/bkit-debug` finds the root cause before it changes anything, fixes it, re-runs the tests and records the lesson. Bugs that only show up at runtime get a dedicated mode that adds logging, fixes on evidence and removes the logging again.
|
|
125
138
|
- **It knows when to stop.** If a failure can't be fixed, bkit writes a clear handover and stops, instead of guessing over and over.
|
|
126
139
|
|
|
@@ -134,7 +147,7 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
|
|
|
134
147
|
|
|
135
148
|
### It fits how you work
|
|
136
149
|
|
|
137
|
-
- **Never blocked by usage limits.** Out of Claude for the week? Carry on in Cursor, Codex or
|
|
150
|
+
- **Never blocked by usage limits.** Out of Claude for the week? Carry on in Cursor, Codex or Antigravity, or point opencode at your own key — OpenRouter, Ollama or the opencode gateways. Same feature, same checks, nothing to set up again.
|
|
138
151
|
- **Start on your laptop, check in from your phone.** A feature started at your desk can continue in a cloud session (Claude Code on the web or the Claude app, Cursor cloud agents, or opencode on GitHub Actions), or start by itself when CI finishes: ship on green, debug on red. The cloud setup ships ready to adopt.
|
|
139
152
|
- **Run several features at once.** Each one works in its own copy of the repo (a git worktree), so they never trip over each other.
|
|
140
153
|
- **Your issue tracker is the control panel.** bkit reads the GitHub or Linear issue, posts progress as it goes, moves the issue along and links the pull request.
|
|
@@ -148,23 +161,27 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
|
|
|
148
161
|
|
|
149
162
|
## Templates ready to adopt
|
|
150
163
|
|
|
151
|
-
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
|
|
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.
|
|
165
|
+
|
|
166
|
+
The ones that matter most, in the order to adopt them:
|
|
152
167
|
|
|
153
168
|
<!-- prettier-ignore -->
|
|
154
|
-
| Template | What it
|
|
169
|
+
| Template | What it's for |
|
|
155
170
|
| --- | --- |
|
|
156
|
-
| **CI pipeline** | Two lanes ready to go and >20 building blocks for the rest ([above](#a-ci-pipeline-built-the-way-senior-teams-build-them)).
|
|
157
|
-
| **Quality checks** |
|
|
158
|
-
| **
|
|
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)). |
|
|
172
|
+
| **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
|
+
| **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
|
+
| **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. |
|
|
159
175
|
| **Cloud agents** | When CI finishes, a cloud agent picks up: ship on green, debug on red. No laptop needed. |
|
|
160
|
-
| **
|
|
161
|
-
| **
|
|
162
|
-
| **
|
|
163
|
-
|
|
176
|
+
| **Secrets sync** | Keeps every password and key the same everywhere: one local file, one command to push it to Vercel, GitHub Actions, Google Cloud, Supabase and Expo, another to prove every copy matches without printing a value. Prevents "works for me, broken in production". |
|
|
177
|
+
| **graphify** | Keeps a map of how your code fits together (`docs/capabilities.md`), so agents check what already exists before building it again. |
|
|
178
|
+
| **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. |
|
|
179
|
+
|
|
180
|
+
All templates, what each is for, and how to install them: [`.bkit/templates.md`](.bkit/templates.md).
|
|
164
181
|
|
|
165
182
|
## Quick start
|
|
166
183
|
|
|
167
|
-
You need a GitHub repo, Node 20+, pnpm, and at least one of Claude Code, Cursor, Codex or opencode.
|
|
184
|
+
You need a GitHub repo, Node 20+, pnpm, and at least one of Claude Code, Cursor, Codex, Google Antigravity or opencode.
|
|
168
185
|
|
|
169
186
|
**Easiest:** copy the [install prompt](.bkit/install.md#install--first-time) into your AI coding tool and let it do the setup.
|
|
170
187
|
|
|
@@ -172,7 +189,8 @@ You need a GitHub repo, Node 20+, pnpm, and at least one of Claude Code, Cursor,
|
|
|
172
189
|
|
|
173
190
|
```bash
|
|
174
191
|
pnpm add -D @cbartens/bkit
|
|
175
|
-
pnpm bkit install --claude # pick your tools: --claude --cursor --codex --opencode=<provider>
|
|
192
|
+
pnpm bkit install --claude # pick your tools: --claude --cursor --codex --antigravity --opencode=<provider>
|
|
193
|
+
# opencode provider: openrouter | ollama | opencode-zen | opencode-go
|
|
176
194
|
```
|
|
177
195
|
|
|
178
196
|
Adopt the templates you want from `.bkit/templates/`, then open an issue and run the first step from your AI tool:
|
|
@@ -192,7 +210,7 @@ No, but you do need to read a design and a plan and decide whether they're right
|
|
|
192
210
|
bkit is heavier than a single prompt. For a one-off script or a quick experiment, just ask your AI. bkit pays off on a project you'll keep changing and want to trust.
|
|
193
211
|
|
|
194
212
|
**What does it cost?**
|
|
195
|
-
bkit is free
|
|
213
|
+
bkit is free and open source under the MIT licence, for anyone, commercial use included ([License](#license)). It runs on AI subscriptions you already have (Claude, Cursor, ChatGPT for Codex, Google Antigravity), on Antigravity's free tier, or with your own key on pay-as-you-go providers through opencode (OpenRouter, Ollama or the opencode gateways). Several agents reviewing in parallel uses more of your quota than a single chat; that's the price of the second opinions.
|
|
196
214
|
|
|
197
215
|
**Can it break my live site?**
|
|
198
216
|
Not without your sign-off. Work happens in a separate copy of the repo, goes through a pull request, must pass every test, and merges into `dev`, never `main`.
|
|
@@ -200,6 +218,12 @@ Not without your sign-off. Work happens in a separate copy of the repo, goes thr
|
|
|
200
218
|
**Which issue tracker?**
|
|
201
219
|
GitHub Issues or Linear.
|
|
202
220
|
|
|
221
|
+
**Is this the bkit Vibecoding Kit?**
|
|
222
|
+
No. [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code) is a separate project that happens to share the name. This bkit is `@cbartens/bkit` on npm and lives at [github.com/cbartens/bkit](https://github.com/cbartens/bkit).
|
|
223
|
+
|
|
224
|
+
**How does it compare with other tools?**
|
|
225
|
+
Feature by feature against the main AI development frameworks, from spec toolkits to autonomous agents: [`.bkit/comparison.md`](.bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks).
|
|
226
|
+
|
|
203
227
|
<details>
|
|
204
228
|
<summary><strong>For engineers: what's under the hood</strong></summary>
|
|
205
229
|
|
|
@@ -207,7 +231,7 @@ GitHub Issues or Linear.
|
|
|
207
231
|
- **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.
|
|
208
232
|
- **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.
|
|
209
233
|
- **Engine.** The `bkit` CLI is TypeScript in [`.bkit/core/engine/`](.bkit/core/engine/), built to `dist/`, covered by >3,000 tests. `commands/` holds what you type; `install/`, `render/`, `checks/`, `ledgers/` and `shared/` hold the code underneath; `audits/` holds the tests that read shipped text.
|
|
210
|
-
- **One source, every host.** `.bkit/` renders `.claude/`, `.cursor/`, `.codex/` and `.opencode/`. `bkit check` is the CI drift gate.
|
|
234
|
+
- **One source, every host.** `.bkit/` renders `.claude/`, `.cursor/`, `.codex/`, `.agents/` (Antigravity) and `.opencode/`. `bkit check` is the CI drift gate.
|
|
211
235
|
- **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.
|
|
212
236
|
- **Per-agent pins.** Model and effort per agent, per provider ([`.bkit/prompts.md`](.bkit/prompts.md) § Models), immune to the session default.
|
|
213
237
|
- **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).
|
|
@@ -225,20 +249,27 @@ GitHub Issues or Linear.
|
|
|
225
249
|
| [`.bkit/providers.md`](.bkit/providers.md) | Tool and provider differences, model pins |
|
|
226
250
|
| [`.bkit/cloud.md`](.bkit/cloud.md) | Cloud agents: Claude Code on the web, Cursor, opencode |
|
|
227
251
|
| [`.bkit/templates.md`](.bkit/templates.md) | Templates ready to adopt |
|
|
228
|
-
| [`.bkit/comparison.md`](.bkit/comparison.md) | Full pipeline reference
|
|
252
|
+
| [`.bkit/comparison.md`](.bkit/comparison.md) | Full pipeline reference, agentic-patterns mapping, comparison with other AI development frameworks |
|
|
229
253
|
| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
|
|
230
254
|
|
|
231
|
-
##
|
|
255
|
+
## Credits
|
|
232
256
|
|
|
233
|
-
bkit
|
|
257
|
+
bkit's process was worked out over months of building real products with it. These projects sharpened specific ideas along the way:
|
|
234
258
|
|
|
235
|
-
-
|
|
236
|
-
|
|
259
|
+
<!-- prettier-ignore -->
|
|
260
|
+
| Project | Idea bkit took |
|
|
261
|
+
| --- | --- |
|
|
262
|
+
| [everything-claude-code](https://github.com/affaan-m/ECC) (affaan-m) | GateGuard, the hook that makes an agent investigate before it edits, name included; the warning when an agent edits lint or type-check settings; confidence and scope on recorded lessons; the untrusted-input notice on agents that read outside content. |
|
|
263
|
+
| [gstack](https://github.com/garrytan/gstack) (Garry Tan) | Writing the setup once and generating every AI tool's copy from it, with a check that the copies match; the completeness and search-before-building principles in the shared rules; resuming a run from saved state. |
|
|
264
|
+
| _Agentic Design Patterns_ (Antonio Gulli) | A "done when" line on every plan task, and testing hypotheses before fixing in debug. The book is also the yardstick in the [patterns comparison](.bkit/comparison.md#part-2--comparison-to-agentic-design-patterns). |
|
|
265
|
+
| [skills](https://github.com/mattpocock/skills) (Matt Pocock) | The interview that opens `/bkit-design`, adapted from `grill-me`: open questions are settled with you before any design work starts. |
|
|
266
|
+
|
|
267
|
+
**Built on.** The templates set up these tools; thanks to their maintainers: [Serena](https://github.com/oraios/serena), [graphify](https://github.com/Graphify-Labs/graphify), [slop-scan](https://github.com/modem-dev/slop-scan), [Vale](https://github.com/vale-cli/vale) with [write-good](https://github.com/vale-cli/write-good), [Renovate](https://github.com/renovatebot/renovate), [Dependabot](https://docs.github.com/en/code-security/dependabot), [Husky](https://github.com/typicode/husky), [lint-staged](https://github.com/lint-staged/lint-staged), [Prettier](https://github.com/prettier/prettier), [actionlint](https://github.com/rhysd/actionlint) and [direnv](https://github.com/direnv/direnv).
|
|
237
268
|
|
|
238
|
-
|
|
269
|
+
## License
|
|
239
270
|
|
|
240
|
-
|
|
271
|
+
bkit is [MIT](LICENSE.md): use it, change it and share it for any purpose, commercial included, as long as the copyright and licence notice stay with it.
|
|
241
272
|
|
|
242
|
-
**
|
|
273
|
+
**The code bkit's agents write for you is yours.** The licence covers bkit itself, not what its agents produce in your repo.
|
|
243
274
|
|
|
244
|
-
|
|
275
|
+
The full text travels in your repo at [`.bkit/LICENSE.md`](.bkit/LICENSE.md) after install.
|
|
@@ -41,6 +41,34 @@ export function hasGithubMcpServer(cwd) {
|
|
|
41
41
|
}
|
|
42
42
|
return false;
|
|
43
43
|
}
|
|
44
|
+
/**
|
|
45
|
+
* BKIT_GH_TOKEN unset or empty in the shell while a `github` MCP server is configured.
|
|
46
|
+
* Never in CI. The GitHub MCP server authenticates with `Authorization: Bearer
|
|
47
|
+
* ${BKIT_GH_TOKEN}` in .mcp.json, which powers the entire tracker + PR + Projects MCP
|
|
48
|
+
* surface.
|
|
49
|
+
*/
|
|
50
|
+
export function detectGhMcpToken(cwd) {
|
|
51
|
+
if (!hasGithubMcpServer(cwd) || process.env.CI)
|
|
52
|
+
return null;
|
|
53
|
+
const status = detectShellGhMcpToken();
|
|
54
|
+
if (status === "missing") {
|
|
55
|
+
return {
|
|
56
|
+
id: "gh-mcp-token-unset-shell",
|
|
57
|
+
severity: "advisory",
|
|
58
|
+
detect: "BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
|
|
59
|
+
action: "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
if (status === "empty") {
|
|
63
|
+
return {
|
|
64
|
+
id: "gh-mcp-token-empty-shell",
|
|
65
|
+
severity: "advisory",
|
|
66
|
+
detect: 'BKIT_GH_TOKEN is set to an empty string (BKIT_GH_TOKEN=""). The GitHub MCP server sends an empty bearer token and fails to authenticate — distinct from unset, same effect.',
|
|
67
|
+
action: "Set a non-empty BKIT_GH_TOKEN in .bkit/.env (fine-grained PAT for one owner, or classic across owners; Contents / Pull requests / Issues / Actions read & write), then `direnv allow` and restart your editor so MCP servers reload.",
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
return null;
|
|
71
|
+
}
|
|
44
72
|
/**
|
|
45
73
|
* Detect whether a named secret is set on the consumer's GitHub repo.
|
|
46
74
|
* Returns "present" | "missing" | "unknown".
|
|
@@ -75,7 +75,7 @@ export function readConsumerIssueTracker(cwd) {
|
|
|
75
75
|
/**
|
|
76
76
|
* Emit a tracker-specific setup advisory.
|
|
77
77
|
*
|
|
78
|
-
* - `github` → GitHub tracker:
|
|
78
|
+
* - `github` → GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN`; `gh` uses `gh auth login`.
|
|
79
79
|
* - `linear` → existing Linear setup message (BKIT_LINEAR_API_KEY + LINEAR_ISSUE_ID).
|
|
80
80
|
* - `none` → prompt to run `bkit install --tracker=github` or `--tracker=linear`.
|
|
81
81
|
*
|
|
@@ -92,7 +92,7 @@ export function buildTrackerSetupAdvisory(cwd) {
|
|
|
92
92
|
id: "tracker-setup-github",
|
|
93
93
|
severity: "advisory",
|
|
94
94
|
detect: "bkit tracker is configured as `github`. GitHub Issues + Projects v2 is the active tracker.",
|
|
95
|
-
action: "GitHub tracker: MCP
|
|
95
|
+
action: "GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN` (fine-grained PAT for one owner, classic PAT across owners) — set it in `.bkit/.env`, then `direnv allow`. Unset → every tracker and PR MCP call fails. The `gh` CLI signs in separately: run `gh auth login` once. Ensure the `github` MCP server is configured in `.mcp.json` and `.cursor/mcp.json`.",
|
|
96
96
|
};
|
|
97
97
|
}
|
|
98
98
|
if (tracker === "linear") {
|
|
@@ -112,7 +112,7 @@ export function buildTrackerSetupAdvisory(cwd) {
|
|
|
112
112
|
id: "tracker-setup-none",
|
|
113
113
|
severity: "advisory",
|
|
114
114
|
detect: "bkit tracker is not configured (`bkit.issueTracker` absent). Workflows run but every tracker call is a no-op.",
|
|
115
|
-
action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended) or `bkit install --tracker=linear` to enable tracker integration. GitHub tracker
|
|
115
|
+
action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended) or `bkit install --tracker=linear` 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`. To opt out and silence this advisory, set `bkit.issueTracker` to `"none"` in package.json.',
|
|
116
116
|
};
|
|
117
117
|
}
|
|
118
118
|
/** True when package.json has an explicit `bkit.issueTracker` field (any value). */
|
|
@@ -379,7 +379,7 @@ export function buildCloudSetupAdvisory(cwd) {
|
|
|
379
379
|
id: "cloud-router",
|
|
380
380
|
severity: "advisory",
|
|
381
381
|
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.",
|
|
382
|
-
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.`,
|
|
382
|
+
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".`,
|
|
383
383
|
};
|
|
384
384
|
}
|
|
385
385
|
// No router present — distinguish opt-out from undecided.
|
|
@@ -7,12 +7,12 @@ import { dedupeById } from "../before/index.js";
|
|
|
7
7
|
import { detectMissingDotenv, detectBlankDotenvKeys, detectDirenvMissing, detectDirenvNotAllowed, } from "../before/env.js";
|
|
8
8
|
import { getPkgRoot } from "../../shared/package-roots.js";
|
|
9
9
|
import { detectOpencodeYmlProviderDrift } from "../../install/modules/opencode.js";
|
|
10
|
-
import {
|
|
11
|
-
import {
|
|
12
|
-
import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectShellGhMcpToken, hasGithubMcpServer, } from "./auth.js";
|
|
10
|
+
import { detectManagedDuplicate, detectManagedStale } from "./managed.js";
|
|
11
|
+
import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectGhMcpToken } from "./auth.js";
|
|
13
12
|
import { buildCloudSetupAdvisory, buildGithubProjectAdvisory, buildTrackerSetupAdvisory, detectActionsWritePermissions, detectGithubProjectFieldIdFormat, detectMainBranchProtection, readConsumerIssueTracker, } from "./github.js";
|
|
14
13
|
import { buildDepUpdaterSetupAdvisory, detectBkitStubs, detectValePackageNotSynced, detectWorkflowLintToolsMissing, } from "./tools.js";
|
|
15
14
|
import { detectBkitCloudYmlAlwaysTrueGate, detectCiYmlCapstoneContractDrift, detectCiYmlMissingActionlint, detectCiYmlRunInjection, detectGhaFloatingTags, detectRunLevelsNotComposed, detectTaggedTestsWithoutCiHome, detectTestIntegrationEnv, detectTurboIntegrationInputs, } from "./ci-yml.js";
|
|
15
|
+
import { dropTipSilencedAdvisories, setupTipsChecklistLines, setupTipsMarkdownLines, } from "../tips/index.js";
|
|
16
16
|
// ---------------------------------------------------------------------------
|
|
17
17
|
// formatChecklist — pure renderer
|
|
18
18
|
// ---------------------------------------------------------------------------
|
|
@@ -48,23 +48,23 @@ export function suppressedNoteLines(suppressed) {
|
|
|
48
48
|
}
|
|
49
49
|
/**
|
|
50
50
|
* Format a list of findings into the post-install console checklist.
|
|
51
|
-
* Returns `""` when findings
|
|
52
|
-
* stay silent. No console.log inside — caller logs.
|
|
51
|
+
* Returns `""` when findings, suppressed and tips are all empty — callers can `if (banner)`
|
|
52
|
+
* to stay silent. No console.log inside — caller logs.
|
|
53
53
|
*
|
|
54
|
-
* Same content as `renderAdvisoriesMarkdown`: title, summary, agent instructions
|
|
55
|
-
*
|
|
56
|
-
* the markdown form.
|
|
54
|
+
* Same content as `renderAdvisoriesMarkdown`: title, summary, agent instructions and
|
|
55
|
+
* setup tips are the shared strings; only the separators differ from the markdown form.
|
|
57
56
|
*
|
|
58
57
|
* Format per finding:
|
|
59
58
|
* --- i/N [severity] id ---
|
|
60
59
|
* Detect: ...
|
|
61
60
|
* Action: ...
|
|
62
61
|
*
|
|
63
|
-
* `
|
|
64
|
-
* advisory stays visible even when
|
|
62
|
+
* `tips` follow the findings as the Setup tips block; `suppressed` is appended as its own
|
|
63
|
+
* block (see `suppressedNoteLines`) — a dismissed advisory or tip stays visible even when
|
|
64
|
+
* nothing else fired.
|
|
65
65
|
*/
|
|
66
|
-
export function formatChecklist(findings, suppressed = []) {
|
|
67
|
-
if (findings.length === 0 && suppressed.length === 0)
|
|
66
|
+
export function formatChecklist(findings, suppressed = [], tips = []) {
|
|
67
|
+
if (findings.length === 0 && suppressed.length === 0 && tips.length === 0)
|
|
68
68
|
return "";
|
|
69
69
|
const banner = "=".repeat(58);
|
|
70
70
|
const total = findings.length;
|
|
@@ -79,8 +79,6 @@ export function formatChecklist(findings, suppressed = []) {
|
|
|
79
79
|
lines.push("");
|
|
80
80
|
lines.push(ADVISORIES_AGENT_INSTRUCTIONS);
|
|
81
81
|
lines.push("");
|
|
82
|
-
lines.push(TEMPLATES_POINTER);
|
|
83
|
-
lines.push("");
|
|
84
82
|
}
|
|
85
83
|
for (let i = 0; i < findings.length; i++) {
|
|
86
84
|
const f = findings[i];
|
|
@@ -89,6 +87,7 @@ export function formatChecklist(findings, suppressed = []) {
|
|
|
89
87
|
lines.push(`Action: ${f.action}`);
|
|
90
88
|
lines.push("");
|
|
91
89
|
}
|
|
90
|
+
lines.push(...setupTipsChecklistLines(tips));
|
|
92
91
|
const suppressedLines = suppressedNoteLines(suppressed);
|
|
93
92
|
if (suppressedLines.length > 0) {
|
|
94
93
|
lines.push(...suppressedLines);
|
|
@@ -101,10 +100,10 @@ export function formatChecklist(findings, suppressed = []) {
|
|
|
101
100
|
/**
|
|
102
101
|
* Render findings as a markdown artifact suitable for `.bkit/advisories.md`.
|
|
103
102
|
* Renders the SAME content as `formatChecklist` (shared title, summary, agent
|
|
104
|
-
* instructions,
|
|
103
|
+
* instructions, setup tips and suppressed block) in markdown form, so the file can
|
|
105
104
|
* be referenced and revisited between installs. Overwritten on every run.
|
|
106
105
|
*/
|
|
107
|
-
export function renderAdvisoriesMarkdown(findings, opts, suppressed = []) {
|
|
106
|
+
export function renderAdvisoriesMarkdown(findings, opts, suppressed = [], tips = []) {
|
|
108
107
|
const lines = [];
|
|
109
108
|
// This is a generated, gitignored artifact — not authored prose. Advisory
|
|
110
109
|
// strings (and reproduced config snippets like `.vale.ini`'s `write-good.So =
|
|
@@ -120,7 +119,7 @@ export function renderAdvisoriesMarkdown(findings, opts, suppressed = []) {
|
|
|
120
119
|
lines.push("");
|
|
121
120
|
lines.push("> Auto-generated by `bkit install` / `bkit check` / `bkit doctor`. Overwritten on each run.");
|
|
122
121
|
lines.push("");
|
|
123
|
-
if (findings.length === 0 && suppressed.length === 0) {
|
|
122
|
+
if (findings.length === 0 && suppressed.length === 0 && tips.length === 0) {
|
|
124
123
|
lines.push("**No advisories.** Last run was clean.");
|
|
125
124
|
lines.push("");
|
|
126
125
|
return lines.join("\n");
|
|
@@ -130,8 +129,6 @@ export function renderAdvisoriesMarkdown(findings, opts, suppressed = []) {
|
|
|
130
129
|
lines.push("");
|
|
131
130
|
lines.push(`> ${ADVISORIES_AGENT_INSTRUCTIONS}`);
|
|
132
131
|
lines.push("");
|
|
133
|
-
lines.push(`> ${TEMPLATES_POINTER}`);
|
|
134
|
-
lines.push("");
|
|
135
132
|
}
|
|
136
133
|
const total = findings.length;
|
|
137
134
|
for (let i = 0; i < total; i++) {
|
|
@@ -143,6 +140,7 @@ export function renderAdvisoriesMarkdown(findings, opts, suppressed = []) {
|
|
|
143
140
|
lines.push(`**Action:** ${f.action}`);
|
|
144
141
|
lines.push("");
|
|
145
142
|
}
|
|
143
|
+
lines.push(...setupTipsMarkdownLines(tips));
|
|
146
144
|
const suppressedLines = suppressedNoteLines(suppressed);
|
|
147
145
|
if (suppressedLines.length > 0) {
|
|
148
146
|
lines.push(...suppressedLines);
|
|
@@ -163,7 +161,7 @@ export function writeAdvisoriesArtifact(findings, opts) {
|
|
|
163
161
|
const content = renderAdvisoriesMarkdown(findings, {
|
|
164
162
|
mode: opts.mode,
|
|
165
163
|
version: opts.version,
|
|
166
|
-
}, opts.suppressed ?? []);
|
|
164
|
+
}, opts.suppressed ?? [], opts.tips ?? []);
|
|
167
165
|
fs.writeFileSync(filePath, content);
|
|
168
166
|
const n = findings.length;
|
|
169
167
|
console.log(`${opts.logPrefix} Wrote .bkit/advisories.md (${n} item${n === 1 ? "" : "s"}).`);
|
|
@@ -258,29 +256,14 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
|
|
|
258
256
|
const managedStale = detectManagedStale(cwd);
|
|
259
257
|
if (managedStale)
|
|
260
258
|
phase3.push(managedStale);
|
|
261
|
-
//
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
id: "gh-mcp-token-unset-shell",
|
|
270
|
-
severity: "advisory",
|
|
271
|
-
detect: "BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
|
|
272
|
-
action: "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
|
|
273
|
-
});
|
|
274
|
-
}
|
|
275
|
-
else if (ghMcpTokenStatus === "empty") {
|
|
276
|
-
phase3.push({
|
|
277
|
-
id: "gh-mcp-token-empty-shell",
|
|
278
|
-
severity: "advisory",
|
|
279
|
-
detect: 'BKIT_GH_TOKEN is set to an empty string (BKIT_GH_TOKEN=""). The GitHub MCP server sends an empty bearer token and fails to authenticate — distinct from unset, same effect.',
|
|
280
|
-
action: "Set a non-empty BKIT_GH_TOKEN in .bkit/.env (fine-grained PAT for one owner, or classic across owners; Contents / Pull requests / Issues / Actions read & write), then `direnv allow` and restart your editor so MCP servers reload.",
|
|
281
|
-
});
|
|
282
|
-
}
|
|
283
|
-
}
|
|
259
|
+
// Older unmarked copy of a managed markdown block left outside its markers.
|
|
260
|
+
const managedDuplicate = detectManagedDuplicate(cwd);
|
|
261
|
+
if (managedDuplicate)
|
|
262
|
+
phase3.push(managedDuplicate);
|
|
263
|
+
// BKIT_GH_TOKEN shell env — authenticates the GitHub MCP server.
|
|
264
|
+
const ghMcpToken = detectGhMcpToken(cwd);
|
|
265
|
+
if (ghMcpToken)
|
|
266
|
+
phase3.push(ghMcpToken);
|
|
284
267
|
// Main branch protection — bkit's PR-base gates (build Step 17, ship Step 2)
|
|
285
268
|
// assert feat/* PRs target dev. Enforcing it at the GitHub layer needs branch
|
|
286
269
|
// protection on main restricting merges to PRs from dev.
|
|
@@ -426,6 +409,7 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
|
|
|
426
409
|
// appears in Phase 3, then merge Phase 3 at the front for the winning position).
|
|
427
410
|
const phase3Ids = new Set(deduped.map((f) => f.id));
|
|
428
411
|
const filteredPreflight = dedupedPreflight.filter((f) => !phase3Ids.has(f.id));
|
|
429
|
-
// Final order: preflight advisories (that weren't superseded) first, then Phase 3
|
|
430
|
-
|
|
412
|
+
// Final order: preflight advisories (that weren't superseded) first, then Phase 3.
|
|
413
|
+
// An advisory a setup tip reuses goes quiet with that tip (`bkit.ignoreAdvisories`).
|
|
414
|
+
return dropTipSilencedAdvisories([...filteredPreflight, ...deduped], cwd, onSuppressed);
|
|
431
415
|
}
|
|
@@ -6,7 +6,7 @@ import { spawnSync } from "node:child_process";
|
|
|
6
6
|
import { getModuleManifest } from "../../install/manifest.js";
|
|
7
7
|
import { readManagedVersion } from "../../install/version-file.js";
|
|
8
8
|
import { getPkgRoot } from "../../shared/package-roots.js";
|
|
9
|
-
import { detectMarkerStyle, findLineAnchoredMarkers, selectMarkers, } from "../../install/managed-block.js";
|
|
9
|
+
import { detectMarkerStyle, extractManagedBlock, findLineAnchoredMarkers, findUnmarkedCopy, selectMarkers, stripManagedBlock, } from "../../install/managed-block.js";
|
|
10
10
|
import { listStampedFiles } from "../../install/modules/index.js";
|
|
11
11
|
// ---------------------------------------------------------------------------
|
|
12
12
|
// detectManagedStale — managed-version marker gate over every stamped file
|
|
@@ -144,12 +144,52 @@ export function detectManagedStale(cwd, installingVersion = readPkgVersion(), on
|
|
|
144
144
|
action: "Re-render every bkit-managed file at the installed version, then commit the result: run `pnpm bkit upgrade` (resyncs every host, doc and hook) or re-run `pnpm bkit install` with your host flags. To MOVE to a newer bkit, use `pnpm bkit upgrade --latest` (or `--to=<version>`) — it bumps @cbartens/bkit AND re-renders in one step; `pnpm add @cbartens/bkit` alone does NOT re-render. Never hand-edit a rendered agent/command or the content between `bkit:start` and `bkit:end`: put your own content outside the block, where install and upgrade never write.",
|
|
145
145
|
};
|
|
146
146
|
}
|
|
147
|
+
// ---------------------------------------------------------------------------
|
|
148
|
+
// detectManagedDuplicate — an older unmarked copy kept beside a managed markdown block
|
|
149
|
+
// ---------------------------------------------------------------------------
|
|
150
|
+
/**
|
|
151
|
+
* Managed markdown blocks whose file also holds an older, unmarked copy of the block outside
|
|
152
|
+
* the markers (findUnmarkedCopy). Install never touches content outside the markers, so that
|
|
153
|
+
* copy stays at the version it was left at while agents read it beside the live block.
|
|
154
|
+
* Advisory: the match is a heuristic. Null when no stamped file has one.
|
|
155
|
+
*/
|
|
156
|
+
export function detectManagedDuplicate(cwd) {
|
|
157
|
+
const copies = [];
|
|
158
|
+
for (const { path: rel, scope } of listStampedFiles(cwd)) {
|
|
159
|
+
if (scope !== "block" || !rel.endsWith(".md"))
|
|
160
|
+
continue;
|
|
161
|
+
const abs = path.join(cwd, rel);
|
|
162
|
+
if (!fs.existsSync(abs))
|
|
163
|
+
continue;
|
|
164
|
+
const content = fs.readFileSync(abs, "utf-8");
|
|
165
|
+
const block = extractManagedBlock(content);
|
|
166
|
+
if (block === null)
|
|
167
|
+
continue;
|
|
168
|
+
const title = findUnmarkedCopy(stripManagedBlock(content), block);
|
|
169
|
+
if (title === null)
|
|
170
|
+
continue;
|
|
171
|
+
const lines = content.split("\n");
|
|
172
|
+
const start = lines.indexOf(selectMarkers("html-comment")[0]);
|
|
173
|
+
const end = lines.indexOf(selectMarkers("html-comment")[1]);
|
|
174
|
+
const line = lines.findIndex((l, i) => l === title && (i < start || i > end)) + 1;
|
|
175
|
+
copies.push(`${rel} (\`${title}\` at line ${line})`);
|
|
176
|
+
}
|
|
177
|
+
if (copies.length === 0)
|
|
178
|
+
return null;
|
|
179
|
+
return {
|
|
180
|
+
id: "bkit-managed-duplicate",
|
|
181
|
+
severity: "advisory",
|
|
182
|
+
detect: `${copies.length} bkit-managed file(s) hold an older bkit copy outside their \`bkit:start\`/\`bkit:end\` block: ${copies.join(", ")}. Install never updates text outside the markers, so agents read that stale copy beside the live block.`,
|
|
183
|
+
action: "In each file, delete the old copy: the run of lines starting at the named title line, up to `<!-- bkit:start -->` (or from just after `<!-- bkit:end -->` when the copy sits below). Keep any lines you wrote yourself by moving them below `<!-- bkit:end -->`. Then run `pnpm bkit check` again.",
|
|
184
|
+
};
|
|
185
|
+
}
|
|
147
186
|
/** Host modules whose manifest hook files a host config runs, and the flag that installs each. */
|
|
148
187
|
const HOOK_HOST_FLAGS = [
|
|
149
188
|
["claude", "--claude"],
|
|
150
189
|
["cursor", "--cursor"],
|
|
151
190
|
["codex", "--codex"],
|
|
152
191
|
["opencode", "--opencode=<provider>"],
|
|
192
|
+
["antigravity", "--antigravity"],
|
|
153
193
|
];
|
|
154
194
|
/** Manifest paths a host runs as a hook: `.<host>/hooks/<file>` and `.opencode/plugin/<file>`. */
|
|
155
195
|
const HOOK_FILE_RE = /\/(hooks|plugin)\/[^/]+$/;
|
|
@@ -143,15 +143,16 @@ export function runPreflight(modules, cwd = process.cwd(), installingVersion, is
|
|
|
143
143
|
const bkitNotOnPath = detectBkitNotOnPath();
|
|
144
144
|
if (bkitNotOnPath)
|
|
145
145
|
advisories.push(bkitNotOnPath);
|
|
146
|
-
// Missing MCP server advisory — one finding per missing required key, per file
|
|
147
|
-
//
|
|
148
|
-
//
|
|
149
|
-
// Extra MCP server advisory — one finding per bkit-managed server that the
|
|
146
|
+
// Missing MCP server advisory — one finding per missing required key, per file: the
|
|
147
|
+
// resolved tracker's own server (none → nothing required), matching what install writes.
|
|
148
|
+
// Extra MCP server advisory — one finding per bkit-written tracker-only server that the
|
|
150
149
|
// resolved tracker does not use (e.g. a stale `linear` entry under `github`).
|
|
150
|
+
// opencode.json is drift-gated, so only the extra check runs there (map key `mcp`).
|
|
151
151
|
for (const relPath of [".mcp.json", ".cursor/mcp.json"]) {
|
|
152
152
|
advisories.push(...detectMissingMcpServers(cwd, relPath, resolvedTracker));
|
|
153
153
|
advisories.push(...detectExtraMcpServers(cwd, relPath, resolvedTracker));
|
|
154
154
|
}
|
|
155
|
+
advisories.push(...detectExtraMcpServers(cwd, ".opencode/opencode.json", resolvedTracker, "mcp"));
|
|
155
156
|
// [mcp-env] detectors run in Phase 3 (runPostInstallCheck in checks/after/index.ts),
|
|
156
157
|
// not here: the .bkit/.env.example scaffold exists only after writes. Detectors are
|
|
157
158
|
// exported from this file for the postinstall module.
|