@cbartens/bkit 5.2.4 → 5.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +27 -11
- package/.bkit/core/.agents/context.md +1 -1
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
- package/.bkit/core/.agents/rules.md +18 -1
- package/.bkit/core/.bkit/README.md +26 -10
- package/.bkit/core/.bkit/cloud.md +40 -39
- package/.bkit/core/.bkit/comparison.md +68 -345
- package/.bkit/core/.bkit/install.md +16 -9
- package/.bkit/core/.bkit/lite.md +73 -0
- package/.bkit/core/.bkit/pipeline.md +346 -0
- package/.bkit/core/.bkit/prompts.md +90 -74
- package/.bkit/core/.bkit/providers.md +42 -23
- package/.bkit/core/.bkit/templates.md +138 -19
- package/.bkit/core/.bkit/trackers.md +49 -4
- package/.bkit/core/.bkit/workflows.md +144 -123
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +26 -21
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-llm.md +22 -15
- 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 +7 -7
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +12 -9
- 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 +14 -12
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -8
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +8 -6
- package/.bkit/core/engine/checks/after/auth.ts +9 -9
- package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
- package/.bkit/core/engine/checks/after/github.ts +29 -120
- package/.bkit/core/engine/checks/after/index.ts +2 -2
- package/.bkit/core/engine/checks/after/managed.ts +8 -28
- package/.bkit/core/engine/checks/after/tools.ts +3 -15
- package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
- package/.bkit/core/engine/checks/before/index.ts +7 -43
- package/.bkit/core/engine/checks/before/mcp.ts +17 -8
- package/.bkit/core/engine/checks/before/repo.ts +9 -12
- package/.bkit/core/engine/checks/status-holes.ts +4 -6
- package/.bkit/core/engine/checks/tips/catalogue.ts +76 -24
- package/.bkit/core/engine/checks/tips/detect.ts +45 -2
- package/.bkit/core/engine/checks/tips/index.ts +77 -26
- package/.bkit/core/engine/cli.ts +57 -27
- package/.bkit/core/engine/commands/analysis.ts +36 -26
- package/.bkit/core/engine/commands/comply.ts +42 -32
- package/.bkit/core/engine/commands/harvest.ts +12 -12
- package/.bkit/core/engine/commands/install/doctor.ts +57 -28
- package/.bkit/core/engine/commands/install/install.ts +73 -130
- package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
- package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +45 -18
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +12 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +386 -286
- package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
- package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +15 -4
- package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
- package/.bkit/core/engine/commands/workflow/roadmap.ts +49 -53
- package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
- 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 +25 -15
- package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
- package/.bkit/core/engine/commands/workflow/workflows.ts +436 -267
- package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +24 -6
- package/.bkit/core/engine/install/cloud-env.ts +10 -31
- package/.bkit/core/engine/install/manifest.ts +14 -7
- package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
- package/.bkit/core/engine/install/modules/claude.ts +20 -28
- package/.bkit/core/engine/install/modules/cloud.ts +5 -2
- package/.bkit/core/engine/install/modules/codex.ts +15 -29
- package/.bkit/core/engine/install/modules/core.ts +106 -70
- package/.bkit/core/engine/install/modules/cursor.ts +6 -20
- package/.bkit/core/engine/install/modules/index.ts +7 -1
- package/.bkit/core/engine/install/modules/opencode.ts +48 -70
- package/.bkit/core/engine/install/network-allowlist.ts +73 -0
- package/.bkit/core/engine/install/placeholders.ts +16 -35
- package/.bkit/core/engine/install/write.ts +59 -12
- package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
- package/.bkit/core/engine/render/hosts.ts +47 -67
- package/.bkit/core/engine/render/models.ts +29 -11
- package/.bkit/core/engine/shared/branches.ts +13 -0
- package/.bkit/core/engine/shared/egress.ts +3 -3
- package/.bkit/core/engine/shared/json.ts +18 -1
- package/.bkit/core/engine/shared/package-json.ts +63 -0
- package/.bkit/core/engine/shared/package-roots.ts +0 -10
- package/.bkit/core/engine/shared/protected-paths.ts +5 -130
- package/.bkit/core/engine/shared/settings.ts +44 -0
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/hooks/antigravity-hook.js +1 -0
- package/.bkit/core/hooks/guardrails-shell.js +186 -40
- package/.bkit/core/hooks/guardrails-tiers.js +5 -78
- package/.bkit/core/prompts/bkit-audit-generate.md +103 -7
- package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
- 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-install-skills.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
- package/.bkit/core/prompts/bkit-design-spike.md +1 -1
- package/.bkit/core/prompts/bkit-design-summary.md +2 -2
- package/.bkit/core/prompts/bkit-design-update.md +1 -1
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
- package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
- package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
- package/.bkit/core/prompts/bkit-plan-update.md +1 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
- package/.bkit/core/workflows/bkit-auto.md +2 -2
- package/.bkit/core/workflows/bkit-build.md +10 -10
- package/.bkit/core/workflows/bkit-debug.md +80 -44
- package/.bkit/core/workflows/bkit-design.md +22 -13
- package/.bkit/core/workflows/bkit-plan.md +33 -16
- package/.bkit/core/workflows/bkit-ship.md +87 -98
- package/.bkit/shared/.claude/bkit-cloud.md +58 -25
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.cursor/mcp.json +2 -1
- package/.bkit/shared/.opencode/opencode.json +19 -1
- package/.bkit/shared/docs/deployments.md +49 -29
- package/.bkit/shared/docs/security.md +8 -6
- package/.bkit/shared/docs/testing.md +9 -5
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.cursor/Dockerfile +30 -16
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
- package/.bkit/templates/.github/renovate.json5 +91 -12
- package/.bkit/templates/.github/workflows/bkit-ci.yml +73 -55
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
- package/.bkit/templates/.husky/pre-commit +6 -0
- package/.bkit/templates/.husky/pre-push +15 -3
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/.oxlintrc.json +21 -0
- package/.bkit/templates/docs/capabilities.md +1 -1
- package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -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-graph-eager.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
- package/CHANGELOG.md +98 -3
- package/README.md +252 -122
- package/dist/checks/after/auth.js +10 -11
- package/dist/checks/after/ci-yml.js +11 -14
- package/dist/checks/after/github.js +32 -125
- package/dist/checks/after/index.js +3 -2
- package/dist/checks/after/managed.js +8 -24
- package/dist/checks/after/tools.js +3 -16
- package/dist/checks/before/context-fetch.js +1 -21
- package/dist/checks/before/index.js +6 -42
- package/dist/checks/before/mcp.js +14 -9
- package/dist/checks/before/repo.js +8 -11
- package/dist/checks/status-holes.js +5 -7
- package/dist/checks/tips/catalogue.js +65 -18
- package/dist/checks/tips/detect.js +41 -2
- package/dist/checks/tips/index.js +61 -25
- package/dist/cli.js +52 -26
- package/dist/commands/analysis.js +21 -5
- package/dist/commands/comply.js +40 -31
- package/dist/commands/harvest.js +12 -13
- package/dist/commands/install/doctor.js +55 -23
- package/dist/commands/install/install.js +72 -122
- package/dist/commands/install/uninstall.js +165 -31
- package/dist/commands/install/upgrade.js +46 -39
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +41 -16
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +10 -3
- package/dist/commands/workflow/branches.js +303 -248
- package/dist/commands/workflow/counters.js +17 -7
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/fids.js +39 -0
- package/dist/commands/workflow/issues.js +63 -27
- package/dist/commands/workflow/ledgers.js +3 -1
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +8 -5
- package/dist/commands/workflow/repo.js +2 -2
- package/dist/commands/workflow/roadmap.js +50 -57
- package/dist/commands/workflow/runs.js +5 -5
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +19 -11
- package/dist/commands/workflow/tests.js +16 -3
- package/dist/commands/workflow/workflows.js +390 -249
- package/dist/commands/workflow/workstreams.js +4 -2
- package/dist/commands/workflow/worktrees.js +15 -6
- package/dist/install/cloud-env.js +10 -23
- package/dist/install/manifest.js +14 -7
- package/dist/install/modules/antigravity.js +15 -26
- package/dist/install/modules/claude.js +17 -21
- package/dist/install/modules/cloud.js +6 -2
- package/dist/install/modules/codex.js +15 -29
- package/dist/install/modules/core.js +95 -63
- package/dist/install/modules/cursor.js +6 -9
- package/dist/install/modules/index.js +6 -1
- package/dist/install/modules/opencode.js +41 -72
- package/dist/install/network-allowlist.js +62 -0
- package/dist/install/placeholders.js +16 -35
- package/dist/install/write.js +55 -15
- package/dist/ledgers/telemetry.js +5 -4
- package/dist/render/hosts.js +30 -55
- package/dist/render/models.js +20 -9
- package/dist/shared/branches.js +11 -0
- package/dist/shared/egress.js +0 -2
- package/dist/shared/json.js +14 -0
- package/dist/shared/package-json.js +61 -0
- package/dist/shared/package-roots.js +0 -8
- package/dist/shared/protected-paths.js +5 -122
- package/dist/shared/settings.js +23 -1
- package/dist/shared/timeouts.js +8 -7
- package/package.json +21 -17
- package/.bkit/core/.agents/shortcuts.md +0 -73
package/README.md
CHANGED
|
@@ -9,28 +9,43 @@
|
|
|
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
11
|
<a href="#license"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
|
|
12
|
-
<img alt="Node
|
|
12
|
+
<img alt="Node 24+" src="https://img.shields.io/badge/node-%E2%89%A524-339933">
|
|
13
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">
|
|
17
|
-
<a href="#
|
|
18
|
-
<a href="#
|
|
19
|
-
<a href="#
|
|
20
|
-
<a href="#
|
|
17
|
+
<a href="#how-it-works">How it works</a> ·
|
|
18
|
+
<a href="#why-its-different">Why it's different</a> ·
|
|
19
|
+
<a href="#memory">Memory</a> ·
|
|
20
|
+
<a href="#audits">Audits</a> ·
|
|
21
|
+
<a href="#templates">Templates</a> ·
|
|
22
|
+
<a href="#token-costs">Token costs</a> ·
|
|
21
23
|
<a href="#faq">FAQ</a> ·
|
|
22
|
-
<a href="
|
|
23
|
-
<a href=".bkit/install.md">Install guide</a>
|
|
24
|
+
<a href="#quick-start">Quick start</a>
|
|
24
25
|
</p>
|
|
25
26
|
|
|
26
|
-
|
|
27
|
+
<p align="center">
|
|
28
|
+
<a href=".bkit/install.md">Install guide ↗</a> ·
|
|
29
|
+
<a href=".bkit/README.md">User guide ↗</a> ·
|
|
30
|
+
<a href=".bkit/comparison.md#frameworks">Comparison ↗</a>
|
|
31
|
+
</p>
|
|
32
|
+
|
|
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
|
+
|
|
35
|
+
**bkit is that process, ready-made.** Describe a feature in a GitHub or Linear issue and type one command:
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
/bkit-design ISSUE-123
|
|
39
|
+
```
|
|
27
40
|
|
|
28
|
-
|
|
41
|
+
AI agents design it, plan it, build it, have it reviewed by agents that didn't write it, fix what breaks and ship it, keeping project docs and memory current along the way. You read the design and the plan and make the call.
|
|
29
42
|
|
|
30
|
-
- **For solo founders and makers** who
|
|
43
|
+
- **For solo founders and makers** who've outgrown vibe coding: a senior engineering team's habits, without hiring one. You need to read a plan and make a call, not write the code.
|
|
31
44
|
- **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.
|
|
32
45
|
|
|
33
|
-
**
|
|
46
|
+
**It ships what other frameworks leave to you:** a full CI pipeline for your project (none of the frameworks in [our comparison](.bkit/comparison.md#frameworks) has one), and 35 [audits](#audits) that find the bugs passing tests miss.
|
|
47
|
+
|
|
48
|
+
**Researched and battle-tested, not a weekend prompt pack.** bkit is built with bkit: months of research into how agentic engineering works best, refined over **1,700+ commits, 300+ issues and 100+ merged pull requests** run through its own pipeline. Along the way it recorded **300+ lessons and 600+ decisions**. They shaped the rules and prompts you install, and your own repo starts its own record from the first feature.
|
|
34
49
|
|
|
35
50
|
<p align="center">
|
|
36
51
|
<picture>
|
|
@@ -39,46 +54,82 @@ AI coding agents are fast, but on their own they skip the parts that make softwa
|
|
|
39
54
|
</picture>
|
|
40
55
|
</p>
|
|
41
56
|
|
|
42
|
-
|
|
57
|
+
<a id="whats-inside"></a>
|
|
58
|
+
|
|
59
|
+
## What's inside: 200+ files of best practice
|
|
43
60
|
|
|
44
61
|
Everything a senior team would otherwise write down over years, in files you can read:
|
|
45
62
|
|
|
46
63
|
<!-- prettier-ignore -->
|
|
47
64
|
| What | How many | What it does for you |
|
|
48
65
|
| --- | --- | --- |
|
|
49
|
-
| [Agents](.bkit/
|
|
50
|
-
| Workflows | 6 | The five phases plus a cloud router. Every step ends in a checklist and a mechanical check before the next one starts. |
|
|
51
|
-
| Agent rules |
|
|
52
|
-
| Guardrails |
|
|
53
|
-
| [Audits](.bkit/
|
|
54
|
-
| Project docs | 10 + index | Architecture, data schema, deployments, testing, security, monitoring, design system, tech stack, setup, and an index telling each agent what to read at each step. |
|
|
55
|
-
| Templates |
|
|
56
|
-
|
|
57
|
-
## A ready-made workflow for every job
|
|
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. |
|
|
58
73
|
|
|
59
|
-
|
|
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).
|
|
60
75
|
|
|
61
|
-
|
|
62
|
-
| Job | Command | What happens |
|
|
63
|
-
| --- | --- | --- |
|
|
64
|
-
| Work out how to build it | [`/bkit-design`](.bkit/comparison.md#phase-1--bkit-design) | Reads related issues and past decisions, has three agents propose different approaches and two critique them, and writes throwaway code to test any risky unknowns the reviewers flag. You get one design to approve. |
|
|
65
|
-
| Plan the work | [`/bkit-plan`](.bkit/comparison.md#phase-2--bkit-plan) | A step-by-step plan, stress-tested by five reviewers who also see past bugs and postponed work. Too big for one build? It's split into pieces. You approve it. |
|
|
66
|
-
| Build it | [`/bkit-build`](.bkit/comparison.md#phase-3--bkit-build) | Checks the plan still matches the code, writes each task's tests before its code, verifies every task, hunts for bugs and security holes, adds edge-case tests, and opens a pull request. |
|
|
67
|
-
| Fix what broke | [`/bkit-debug`](.bkit/comparison.md#phase-4--bkit-debug) | Pulls evidence from CI and your platforms, finds the root cause, fixes it, re-tests and records the lesson. Hard runtime bugs get their own mode; if it can't fix something, it stops and writes you a clear handover. |
|
|
68
|
-
| Ship it | [`/bkit-ship`](.bkit/comparison.md#phase-5--bkit-ship) | Checks nothing planned was quietly dropped, waits for every test lane to pass, merges into `dev`, and updates the docs. |
|
|
69
|
-
| Health check | [>30 audits](.bkit/comparison.md#audits) | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
|
|
70
|
-
| Housekeeping | 7 utility agents | Keep docs, decisions, lessons and known bugs current, and rank what to work on next. |
|
|
76
|
+
<a id="how-it-works"></a>
|
|
71
77
|
|
|
72
78
|
## How it works
|
|
73
79
|
|
|
74
80
|
<p align="center">
|
|
75
81
|
<picture>
|
|
76
82
|
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-pipeline-dark.svg">
|
|
77
|
-
<img alt="The bkit pipeline: design, plan, build and ship, with debug fixing failed tests. Each dot is one of
|
|
83
|
+
<img alt="The bkit pipeline: design, plan, build and ship, with debug fixing failed tests. Each dot is one of 41 AI agents: 10 in design, 10 in plan, 11 in build, 6 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%">
|
|
78
84
|
</picture>
|
|
79
85
|
</p>
|
|
80
86
|
|
|
81
|
-
|
|
87
|
+
**One command per job.** Each runs a team of specialised agents, so there are no prompts to write and no steps to remember.
|
|
88
|
+
|
|
89
|
+
<!-- prettier-ignore -->
|
|
90
|
+
| Job | Command | What happens |
|
|
91
|
+
| --- | --- | --- |
|
|
92
|
+
| Work out how to build it | [`/bkit-design`](.bkit/pipeline.md#bkit-design) | Reads related issues and past decisions. Three agents propose different approaches, two critique them, and throwaway code tests any risky unknown the reviewers flag. **You approve one design.** |
|
|
93
|
+
| Plan the work | [`/bkit-plan`](.bkit/pipeline.md#bkit-plan) | A 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.** |
|
|
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. |
|
|
95
|
+
| Fix what broke | [`/bkit-debug`](.bkit/pipeline.md#bkit-debug) | Pulls evidence from CI and your platforms, fixes the root cause, re-tests and records the lesson. Hard runtime bugs get their own mode; if it can't fix something, it stops and writes you a clear handover. |
|
|
96
|
+
| Ship it | [`/bkit-ship`](.bkit/pipeline.md#bkit-ship) | Checks nothing planned was quietly dropped, waits for every test lane to pass, merges into `dev` and updates the docs. |
|
|
97
|
+
| 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. |
|
|
98
|
+
| Health check | [35 audits](#audits) | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
|
|
99
|
+
| Housekeeping | 7 utility agents | Keep docs, decisions, lessons and known bugs current, and rank what to work on next. |
|
|
100
|
+
|
|
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).
|
|
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
|
+
|
|
132
|
+
<a id="why-its-different"></a>
|
|
82
133
|
|
|
83
134
|
## Why it's different
|
|
84
135
|
|
|
@@ -89,7 +140,9 @@ Every agent in each phase, in the order it runs and what it checks: [pipeline re
|
|
|
89
140
|
</picture>
|
|
90
141
|
</p>
|
|
91
142
|
|
|
92
|
-
Most AI development frameworks are prompts
|
|
143
|
+
**Most AI development frameworks are prompts:** they describe good work and trust the agent to deliver it. But an agent can be talked into calling something done, and a prompt can't stop it. **bkit builds fences instead.** Reviewer agents that didn't write the work fence in the design and the plan. They never see each other's verdicts, and several review groups mix models on purpose, so one model's blind spot is less likely to get past all of them. From the first line of code, automated checks join them, and those can't be argued with.
|
|
144
|
+
|
|
145
|
+
<a id="agents-and-ci"></a>
|
|
93
146
|
|
|
94
147
|
## Agents and CI, built to work together
|
|
95
148
|
|
|
@@ -100,27 +153,29 @@ Most AI development frameworks are prompts: they describe good work and trust th
|
|
|
100
153
|
</picture>
|
|
101
154
|
</p>
|
|
102
155
|
|
|
103
|
-
The strongest fence is CI (continuous integration): the robot that runs every check on every change, on GitHub's servers, before anything merges.
|
|
156
|
+
**The strongest fence is CI** (continuous integration): the robot that runs every check on every change, on GitHub's servers, before anything merges. Where other frameworks stop at a pull request and leave CI to you, bkit's workflows are built around it and around the checks that run before it. Every change passes the same fences, nearest and lightest first:
|
|
104
157
|
|
|
105
|
-
- **Every agent
|
|
158
|
+
- **Every agent** looks code up before changing it, is nudged by the agent hooks on each edit, can't finish a step until the step gates (scripts, not prompts) find its verdict and files, and has its code formatted on each commit.
|
|
106
159
|
- **`/bkit-plan`** decides which tests each feature needs and where each one runs: unit, integration or end-to-end.
|
|
107
|
-
- **`/bkit-build`** writes each test before its code and runs it to prove it fails, so a test that can't fail is never added.
|
|
108
|
-
- **`/bkit-debug`**
|
|
160
|
+
- **`/bkit-build`** writes each test before its code and runs it to prove it fails, so a test that can't fail is never added. The pre-push hook sends back anything that fails on your machine; then build opens a pull request, which starts CI.
|
|
161
|
+
- **`/bkit-debug`** works from what came back: the logs of the failed lanes, the diff since the last green run, end-to-end reports. It fixes the root cause and pushes, and CI runs again.
|
|
109
162
|
- **`/bkit-ship`** checks nothing planned was quietly dropped, then merges into `dev` only when CI's final check is green on the exact commit being merged.
|
|
110
|
-
- **On autopilot
|
|
163
|
+
- **On autopilot,** for issues labelled `bkit:auto`, CI's result starts ship (green) or debug (red) in a cloud session, with no laptop open ([cloud setup](.bkit/cloud.md#post-ci-auto-routing)).
|
|
111
164
|
|
|
112
165
|
What that gets you:
|
|
113
166
|
|
|
114
|
-
- **The fences grow with every feature.** Each build adds tests
|
|
115
|
-
- **What's sent back is evidence, not a verdict.** A red lane hands debug the failing logs and what changed since the last green run, so the fix starts from the actual error
|
|
116
|
-
- **Agents look before they change anything.** Code search ([Serena](https://github.com/oraios/serena)) shows
|
|
117
|
-
- **Problems are caught at the nearest fence.** Agent hooks nudge on every edit: read a file before changing it,
|
|
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.
|
|
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.
|
|
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.
|
|
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, the prose checker and the junk-code scanner before anything leaves your laptop. CI keeps only what can't run there: integration, 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.
|
|
118
171
|
|
|
119
|
-
The agent hooks come with install. Serena, graphify and the git hooks are [templates](#templates
|
|
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).
|
|
173
|
+
|
|
174
|
+
<a id="ci-pipeline"></a>
|
|
120
175
|
|
|
121
176
|
### The CI pipeline
|
|
122
177
|
|
|
123
|
-
None of the AI development frameworks in our [comparison](.bkit/comparison.md#
|
|
178
|
+
**None of the AI development frameworks in our [comparison](.bkit/comparison.md#frameworks) ships a full test pipeline for your project.** bkit ships one ready to adopt:
|
|
124
179
|
|
|
125
180
|
<p align="center">
|
|
126
181
|
<picture>
|
|
@@ -129,13 +184,15 @@ None of the AI development frameworks in our [comparison](.bkit/comparison.md#pa
|
|
|
129
184
|
</picture>
|
|
130
185
|
</p>
|
|
131
186
|
|
|
132
|
-
- **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
|
|
187
|
+
- **Ready on day one.** Two lanes run side by side: unit tests, and quick checks (type checking, formatting, a prose checker, a scanner for junk code AI tends to write, a workflow-file checker and `bkit check`).
|
|
133
188
|
- **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.
|
|
134
|
-
- **Grows with your project.**
|
|
189
|
+
- **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, smoke and health checks against the deployed site; and a planner that runs only what a change affects. `bkit check` reminds you of each one until you enable or delete it.
|
|
135
190
|
- **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.
|
|
136
191
|
- **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.
|
|
137
192
|
|
|
138
|
-
How the lanes join into the one final check, and what happens on green or red: [CI test scaffold](.bkit/
|
|
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).
|
|
194
|
+
|
|
195
|
+
<a id="memory"></a>
|
|
139
196
|
|
|
140
197
|
## Right context at the right step
|
|
141
198
|
|
|
@@ -146,42 +203,15 @@ How the lanes join into the one final check, and what happens on green or red: [
|
|
|
146
203
|
</picture>
|
|
147
204
|
</p>
|
|
148
205
|
|
|
149
|
-
|
|
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:
|
|
150
207
|
|
|
151
|
-
- **
|
|
152
|
-
- **Project memory agents actually read.** Four ledgers record lessons from every fix (`docs/knowledge.jsonl`), decisions and
|
|
153
|
-
- **
|
|
208
|
+
- **Docs that keep themselves current.** Install sets up the docs a professional project keeps: architecture, data schema, deployments, testing, security, monitoring, design system, tech stack and local setup. Agents fill them in as they work, `/bkit-ship` updates them after every feature, and [an index](.agents/docs.md) tells each agent which docs to read at each step. They stay current because the agents depend on them.
|
|
209
|
+
- **Project memory agents actually read.** Four ledgers record lessons from every fix (`docs/knowledge.jsonl`), decisions and their reasons (`docs/decisions.jsonl`), work consciously postponed (`docs/deferrals.jsonl`) and known bugs (`docs/failures.jsonl`). Plan reviewers see the past bugs and postponed work closest to the new feature, debug reads the lessons first, and `/bkit-ship` checks nothing postponed was quietly dropped. Four utility agents keep them honest: they correct lessons and decisions the code has since contradicted, and close postponed work and known bugs that have already been fixed.
|
|
210
|
+
- **Tracker issues are memory too.** Every step reads the whole tracker issue (e.g. GitHub, Linear), comments included, and adds what it did as a new comment without editing earlier ones, so the issue becomes the feature's running record. bkit skips its own comments when it reads, so agents act on what people wrote. Design, plan and debug also search your other tracker issues, closed ones included, for earlier designs, duplicate work and past incidents.
|
|
211
|
+
- **Outside evidence, when it's needed.** Design searches the web for feasibility. Debug pulls failed CI logs, the diff since the last green run, end-to-end reports and runtime errors. 10+ ready-made connectors cover GitHub, Sentry, Vercel, Supabase, Stripe, Expo, Playwright, Maestro, Inngest, Resend, Cloud Run, Tavily web search and Serena, each easy to customise, extend or leave out. A connector that isn't set up is reported as such, never read as "all clear".
|
|
154
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.
|
|
155
213
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
### The quality is real
|
|
159
|
-
|
|
160
|
-
- **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.
|
|
161
|
-
- **"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.
|
|
162
|
-
- **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.
|
|
163
|
-
- **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.
|
|
164
|
-
|
|
165
|
-
### Engineering know-how, built in
|
|
166
|
-
|
|
167
|
-
- **Best model for each job, on every tool.** Each agent has its own model and thinking depth, chosen per tool and provider. Deep reasoning models do architecture and security review; quick ones write summaries. Starting a session on a cheaper model never quietly downgrades the reviewers.
|
|
168
|
-
- **It tests ideas before you commit to them.** When reviewers flag an unknown a design depends on, design writes throwaway probe code to settle it before you approve, and a design reviewer checks failure modes and monitoring, not just whether it can be built.
|
|
169
|
-
- **Big features are split up.** A plan too big for one build becomes a sequence of smaller plans, and each is re-checked against the current code right before it's built.
|
|
170
|
-
- **Numbers on your own work.** Every run records its time, size of change and retries in `.bkit/stats.jsonl`, and posts them to the issue next to the median of your last five runs.
|
|
171
|
-
|
|
172
|
-
### It fits how you work
|
|
173
|
-
|
|
174
|
-
- **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.
|
|
175
|
-
- **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.
|
|
176
|
-
- **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.
|
|
177
|
-
- **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.
|
|
178
|
-
- **The right expertise for each feature.** When a plan needs, say, Stripe or Supabase, bkit installs a matching skill for the build and removes it when the feature ships.
|
|
179
|
-
|
|
180
|
-
### You stay in control
|
|
181
|
-
|
|
182
|
-
- **Decide in plain English, not code.** Before any code is written you approve two short documents: a design ("three ways to build this; we recommend this one, because…") and a plan ("these twelve steps, and how we'll know each is done").
|
|
183
|
-
- **Three sign-offs, and production stays yours.** bkit stops after the design, after the plan and before merging. It merges into your `dev` branch and never touches `main`: promoting to production is always your call. Cloud mode can ship on green without you, but only for issues you've labelled `bkit:auto`, and removing the label stops it.
|
|
184
|
-
- **Guardrails on the AI itself.** Dangerous commands like force-pushing or rewriting history are blocked. Each agent only gets the tools its job needs.
|
|
214
|
+
<a id="audits"></a>
|
|
185
215
|
|
|
186
216
|
## Audits find what green tests miss
|
|
187
217
|
|
|
@@ -192,9 +222,9 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
|
|
|
192
222
|
</picture>
|
|
193
223
|
</p>
|
|
194
224
|
|
|
195
|
-
A green tick proves the tests passed, not that they test the right things
|
|
225
|
+
**A green tick proves the tests passed, not that they test the right things.** Every finding on this map sat in an app whose tests were passing, and just two of bkit's audit templates found them all.
|
|
196
226
|
|
|
197
|
-
Each template is a specialist's checklist for one area
|
|
227
|
+
**Each template is a specialist's checklist for one area:** what to check, how, and what counts as a problem. Ten to start with:
|
|
198
228
|
|
|
199
229
|
<!-- prettier-ignore -->
|
|
200
230
|
| Audit | What it checks | For example |
|
|
@@ -210,90 +240,160 @@ Each template is a specialist's checklist for one area: what to check, how, and
|
|
|
210
240
|
| **Accessibility** | What automated accessibility checks miss, against WCAG 2.2 AA | A form a screen reader can't get through |
|
|
211
241
|
| **Cost** | Vendor plans against what you actually use | A plan two tiers above your usage |
|
|
212
242
|
|
|
213
|
-
All 35, grouped by area, with what each one finds: [the full audit list](.bkit/
|
|
243
|
+
All 35, grouped by area, with what each one finds: [the full audit list](.bkit/pipeline.md#audits).
|
|
214
244
|
|
|
215
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.
|
|
216
246
|
- **Findings turn into work.** Hand the report to `/bkit-plan` and the fixes are planned, built, tested and shipped like any other feature.
|
|
217
247
|
|
|
248
|
+
<a id="templates"></a>
|
|
249
|
+
|
|
218
250
|
## Templates ready to adopt
|
|
219
251
|
|
|
220
|
-
bkit installs only what its workflows run
|
|
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.
|
|
221
253
|
|
|
222
254
|
The ones that matter most, in the order to adopt them:
|
|
223
255
|
|
|
224
256
|
<!-- prettier-ignore -->
|
|
225
257
|
| Template | What it's for |
|
|
226
258
|
| --- | --- |
|
|
227
|
-
| **
|
|
228
|
-
| **
|
|
229
|
-
| **
|
|
230
|
-
| **Context connectors** | Let `/bkit-debug` read the real errors instead of guessing from the code: >10 ready-made connectors for CI, error trackers, hosting, databases, payments, email, queues and the web. |
|
|
259
|
+
| **Serena** | 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. |
|
|
260
|
+
| **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](#ci-pipeline)). |
|
|
261
|
+
| **Quality checks** | Catches problems on your own machine in seconds, before they reach GitHub: type checking, formatting, a prose checker, a scanner for junk code AI tends to write and a test linter that fails tests which cannot fail, wired into git hooks and CI. Your `bkit:gate:*` scripts in `package.json` define what "the checks" are. |
|
|
231
262
|
| **Cloud agents** | When CI finishes, a cloud agent picks up: ship on green, debug on red. No laptop needed. |
|
|
232
|
-
| **
|
|
263
|
+
| **Context connectors** | `/bkit-debug` reads 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. |
|
|
264
|
+
| **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, Expo and Cursor's cloud agents, another to prove every copy matches without printing a value. Prevents "works for me, broken in production". |
|
|
233
265
|
| **graphify** | Keeps a map of how your code fits together (`docs/capabilities.md`), so agents check what already exists before building it again. |
|
|
234
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. |
|
|
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)). |
|
|
235
269
|
|
|
236
270
|
All templates, what each is for, and how to install them: [`.bkit/templates.md`](.bkit/templates.md).
|
|
237
271
|
|
|
238
|
-
##
|
|
272
|
+
## What else you get
|
|
239
273
|
|
|
240
|
-
|
|
274
|
+
### Engineering know-how, built in
|
|
241
275
|
|
|
242
|
-
**
|
|
276
|
+
- **Best model for each job, on every tool.** Each agent has its own model and thinking depth, per tool and provider: deep reasoning models for architecture and security review, quick ones for summaries. Starting a session on a cheaper model never quietly downgrades the reviewers. [Which model does each job](#models).
|
|
277
|
+
- **It tests ideas before you commit to them.** When reviewers flag an unknown a design depends on, design writes throwaway probe code to settle it before you approve. A design reviewer also checks failure modes and monitoring, not just whether it can be built.
|
|
278
|
+
- **Big features are split up.** A plan too big for one build becomes a sequence of smaller plans, each re-checked against the current code right before it's built.
|
|
279
|
+
- **Numbers on your own work.** Every run records its time, size of change and retries in `.bkit/stats.jsonl`, and posts them to the issue next to the median of your last five runs.
|
|
243
280
|
|
|
244
|
-
|
|
281
|
+
### It fits how you work
|
|
245
282
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
```
|
|
283
|
+
- **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. [Tool differences](.bkit/providers.md).
|
|
284
|
+
- **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: [`.bkit/cloud.md`](.bkit/cloud.md).
|
|
285
|
+
- **Run several features at once.** Each works in its own copy of the repo (a git worktree), so they never trip over each other.
|
|
286
|
+
- **The right expertise for each feature.** When a plan needs, say, Stripe or Supabase, bkit installs a matching skill for the build and removes it when the feature ships.
|
|
251
287
|
|
|
252
|
-
|
|
288
|
+
### Your tracker is the control panel
|
|
253
289
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
290
|
+
- **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.
|
|
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.
|
|
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
|
+
- **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).
|
|
294
|
+
|
|
295
|
+
### You stay in control
|
|
296
|
+
|
|
297
|
+
- **Decide in plain English, not code.** Before any code is written you approve two short documents: a design ("three ways to build this; we recommend this one, because…") and a plan ("these twelve steps, and how we'll know each is done").
|
|
298
|
+
- **Three sign-offs, and production stays yours.** The full workflows stop after the design, after the plan and before merging. bkit merges into your `dev` branch and never touches `main`: promoting to production is always your call. Cloud mode ships on green without you only for issues you've labelled `bkit:auto`; removing the label stops it. Lite workflows skip the stops, and only run when you choose them for a small change.
|
|
299
|
+
- **Guardrails on the AI itself.** Dangerous commands like force-pushing or rewriting history are blocked, private keys can't be read, and each agent only gets the tools its job needs. [What each guard does](.bkit/providers.md#guardrails) and [what it tells agents](.bkit/prompts.md#hook-injected-text).
|
|
300
|
+
|
|
301
|
+
<a id="token-costs"></a>
|
|
302
|
+
|
|
303
|
+
## Spending fewer tokens
|
|
304
|
+
|
|
305
|
+
<p align="center">
|
|
306
|
+
<picture>
|
|
307
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-tokens-dark.svg">
|
|
308
|
+
<img alt="Compression saves 1 to 3 percent; the risks cost more. Where Claude Code's cost goes across 456 real bkit transcripts: 69 percent is the model re-reading the system prompt, rules, tool list and conversation on every request; 4 percent is the model's own writing; 27 percent is big tool output, the only part a compressor can touch; the tools remove 1 to 3 percent of the bill. What you gain: 1 to 3 percent of the bill saved, big cuts on huge logs, prompt cache intact. What it costs you: wrong answers from compressed logs, broken code when lines are rewritten or cut, hidden content that costs tokens to fetch back, silent failures that turn compression off, a proxy that sees all your model traffic, and clashes with bkit's own setup." src=".github/assets/bkit-tokens-light.svg" width="100%">
|
|
309
|
+
</picture>
|
|
310
|
+
</p>
|
|
311
|
+
|
|
312
|
+
**Most of what a session costs is the model re-reading, not writing code.** On every request, Claude Code sends the system prompt, rules, tool list and the whole conversation so far, and the model reads all of it again. Across 456 real Claude Code transcripts from a repo that uses bkit, re-reading was **69% of the bill**. The model's own writing was 4%.
|
|
313
|
+
|
|
314
|
+
**Why bkit doesn't use compression tools.** They shorten the output of commands and file reads before the model sees it. That output was 27% of the bill, and most of it is code the agent needs word for word, so there's little a tool can safely cut. We measured three: none saved more than 3% of the bill, and the ones that saved most did it by changing what the agent reads. One made an agent answer a question wrongly; another rewrote code.
|
|
315
|
+
|
|
316
|
+
<details>
|
|
317
|
+
<summary><strong>The three tools, how we measured, and why the risks outweigh the saving</strong></summary>
|
|
318
|
+
|
|
319
|
+
<!-- prettier-ignore -->
|
|
320
|
+
| Tool | How it works | Share of the bill saved | What went wrong |
|
|
321
|
+
| --- | --- | --- | --- |
|
|
322
|
+
| [caveman](https://www.npmjs.com/package/@caveman-ai/cli) | Sits between Claude Code and the model and shortens tool output | 1.3% | An agent answered a question wrongly from a compressed log |
|
|
323
|
+
| [Headroom](https://pypi.org/project/headroom-ai/) | Same idea, plus an optional text model that rewrites output | 2.8% with the text model, 0.8% without | The text model rewrote code: `(preset) => void` came back as `(preset) void` |
|
|
324
|
+
| [RTK](https://github.com/rtk-ai/rtk) | A hook that swaps shell commands for versions that print less | 0.7–2.1% | Its `grep` strips indentation and cuts lines at 80 characters |
|
|
325
|
+
|
|
326
|
+
**How we measured.** The cost split above comes from all 456 transcripts. The table compares the three tools on the 314 of them still on disk when RTK was tested, so all three are measured on the same data. We ran each tool over the large tool results, with no model calls. Each result counts by how often the model re-read it later, because that's what it cost. RTK acts before a command runs, so we re-ran the read-only commands with and without it. Full method, every result with its 95% range, and the scripts: [the comparison](tests/compression/bkit-caveman-headroom-compression-proxy-comparison.md). Your sessions may differ: run the scripts on your own transcripts before you choose.
|
|
327
|
+
|
|
328
|
+
**Why the risks outweigh the saving, for now.** The saving is real but small, and the tools that save most get there by changing what the agent reads. An agent reading a shortened log can answer wrongly. An edit quoting a rewritten or cut-off line won't match the file. Either way the agent goes round again, and every extra round re-reads the whole conversation, so it doesn't take many to wipe out a 1–3% saving. On top of that, a proxy sees all your model traffic, and when one of these tools breaks, it tends to switch itself off without telling you. That could change if a tool learns to leave code alone and fail loudly.
|
|
329
|
+
|
|
330
|
+
</details>
|
|
331
|
+
|
|
332
|
+
**What bkit does instead: read less.** Cutting what gets read loses nothing, and a line an agent never reads is a line it never re-reads on every later request.
|
|
257
333
|
|
|
258
|
-
|
|
334
|
+
- **Find the definition first, then read only those lines.** Reading files through the shell (`sed`, `grep`, `cat`) was about 60% of what shell output cost in our transcripts. A whole file can be thousands of lines when the change needs ten.
|
|
335
|
+
- **List matching files first, then search inside them.** A broad search can return hundreds of lines the agent never needed, and they stay in the conversation.
|
|
336
|
+
- **Ask commands, APIs and databases for short, structured output.** An unfiltered log or API response can run to thousands of lines, re-read on every later request.
|
|
337
|
+
- **Flag re-reads of a file that hasn't changed,** with a [hook](.bkit/prompts.md#hook-injected-text) on all five supported tools. 41% of file reads in our transcripts were repeats, each adding a second copy to the conversation.
|
|
338
|
+
- **Prefer command-line tools to MCP servers** for logs, errors and database data. Every connected MCP server's tool list is re-sent with every request, used or not.
|
|
339
|
+
- **Each step reads only the project docs it needs.** Whatever a step reads at the start is re-read on every request in that step.
|
|
340
|
+
- **A utility agent shortens markdown files without changing what they say.** Rules and prompts go out with every request of every agent, so a line cut there is saved many thousands of times.
|
|
341
|
+
|
|
342
|
+
**Or run fewer steps.** For a change that's clearly small, the [lite workflows](.bkit/lite.md) keep only the steps and reviewers it needs, so fewer requests re-read the conversation. You give up the safety checks, so the full workflow stays the default.
|
|
343
|
+
|
|
344
|
+
**What [`bkit tips`](.bkit/README.md#ongoing-cli) suggests for your repo:**
|
|
345
|
+
|
|
346
|
+
- **Set up Serena,** so agents ask where code is defined and what uses it, like your editor does. That's cheaper than reading whole files, and it doesn't miss callers that text search would.
|
|
347
|
+
- **Switch off claude.ai connectors** (MCP servers from your claude.ai account) in Claude Code for this project: `"disableClaudeAiConnectors": true` in `.claude/settings.json`. Otherwise their tool lists are re-sent with every request, used or not.
|
|
348
|
+
- **Lock MCP servers to this project.** A server that can see your whole account makes agents look up account and project IDs before every task; locked, those extra calls disappear.
|
|
349
|
+
- **Summarise long sessions earlier:** `"autoCompactWindow": 300000` in `.claude/settings.json`, or `model_auto_compact_token_limit` in `.codex/config.toml`. By default a session grows close to the model's full size before it summarises, and every request re-reads all of it. Summaries lose some detail, so bkit suggests this rather than setting it.
|
|
259
350
|
|
|
260
351
|
## FAQ
|
|
261
352
|
|
|
262
353
|
**Do I need to know how to code?**
|
|
263
|
-
No, but you
|
|
354
|
+
No, but you need to read a design and a plan and decide whether they're right. Setup is a few terminal commands, or one pasted prompt.
|
|
264
355
|
|
|
265
356
|
**Who is it not for?**
|
|
266
357
|
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.
|
|
267
358
|
|
|
359
|
+
**Does it work on an existing project?**
|
|
360
|
+
Yes. Install needs a git repo with a `package.json`, because bkit installs as an npm package. It adds its own files and writes into shared ones such as `CLAUDE.md`, `.gitignore` and `docs/*.md` only between `bkit:start` and `bkit:end` markers, leaving the rest alone. The project docs fill in as agents work on your code.
|
|
361
|
+
|
|
362
|
+
**What does install change, and can I remove it?**
|
|
363
|
+
Every file it writes is listed in [what install writes](.bkit/README.md#what-install-writes). `bkit uninstall` removes bkit's files and blocks, and keeps your own edits and every template you copied ([uninstall](.bkit/install.md#uninstall)).
|
|
364
|
+
|
|
268
365
|
**What does it cost?**
|
|
269
|
-
bkit is free and open source under the MIT licence,
|
|
366
|
+
**bkit is free and open source** under the MIT licence, 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 use more of your quota than a single chat; that's the price of the second opinions.
|
|
367
|
+
|
|
368
|
+
**How long does a feature take?**
|
|
369
|
+
No full run, from design to merge, has taken longer than a day. Each run posts its own time to the issue, next to the median of your last five runs, so you can see how yours compare.
|
|
270
370
|
|
|
271
371
|
**Can it break my live site?**
|
|
272
|
-
Not without your sign-off
|
|
372
|
+
**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.
|
|
273
373
|
|
|
274
|
-
**Which issue tracker?**
|
|
275
|
-
GitHub Issues or Linear.
|
|
374
|
+
**Which issue tracker, and which code host?**
|
|
375
|
+
GitHub Issues or Linear for the tracker. The code has to live on GitHub: pull requests, CI and cloud mode run there.
|
|
276
376
|
|
|
277
377
|
**Is this the bkit Vibecoding Kit?**
|
|
278
|
-
No. [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code) is a separate project that
|
|
378
|
+
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).
|
|
279
379
|
|
|
280
380
|
**How does it compare with other tools?**
|
|
281
|
-
Feature by feature against the main AI development frameworks, from spec toolkits to autonomous agents: [`.bkit/comparison.md`](.bkit/comparison.md#
|
|
381
|
+
Feature by feature against the main AI development frameworks, from spec toolkits to autonomous agents: [`.bkit/comparison.md`](.bkit/comparison.md#frameworks).
|
|
282
382
|
|
|
283
|
-
**Why doesn't bkit
|
|
284
|
-
|
|
383
|
+
**Why doesn't bkit use a compression tool like caveman, Headroom or RTK?**
|
|
384
|
+
On real bkit sessions they saved 1–3% of the bill, and each changes what the agent reads in ways that can lead to wrong answers or broken edits. bkit cuts reading instead, which loses nothing. Numbers, risks and what bkit does instead: [Spending fewer tokens](#token-costs).
|
|
285
385
|
|
|
286
386
|
<details>
|
|
287
387
|
<summary><strong>For engineers: what's under the hood</strong></summary>
|
|
288
388
|
|
|
289
|
-
- **Isolation.** Every run gets its own git worktree; a per-feature lock blocks duplicate runs of the same feature
|
|
389
|
+
- **Isolation.** Every run gets its own git worktree; a per-feature lock blocks duplicate runs of the same feature. Bookkeeping reaches `dev` from a throwaway checkout of `origin/dev`, so it never touches your checkout; when another run moved `dev` first, it rebuilds and pushes again. No repo-wide lock.
|
|
290
390
|
- **Resume from state, not session.** Run state lives in `status.jsonl` and `docs/plans/`. A crashed or interrupted run resumes from its last completed step, on any host.
|
|
291
391
|
- **Mechanical step gates.** `bkit steps finish` checks each step's verdict and artifacts before the workflow moves on; build ticks a task only on a confirmed artifact; ship's deferred sweep fails the merge on an unplanned gap.
|
|
292
|
-
- **Engine.** The `bkit` CLI is TypeScript in [`.bkit/core/engine/`](.bkit/core/engine/), built to `dist/`, covered by
|
|
392
|
+
- **Engine.** The `bkit` CLI is TypeScript in [`.bkit/core/engine/`](.bkit/core/engine/), built to `dist/`, covered by 5,800+ tests. `commands/` holds what you type; `install/`, `render/`, `checks/`, `ledgers/` and `shared/` hold the code underneath; `audits/` holds the tests that read shipped text.
|
|
293
393
|
- **One source, every host.** `.bkit/` renders `.claude/`, `.cursor/`, `.codex/`, `.agents/` (Antigravity) and `.opencode/`. `bkit check` is the CI drift gate.
|
|
294
394
|
- **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.
|
|
295
395
|
- **Per-agent pins.** Model and effort per agent, per provider ([`.bkit/prompts.md`](.bkit/prompts.md) § Models), immune to the session default.
|
|
296
|
-
- **Against the literature.** bkit fully implements 13 of the 22 patterns in Antonio Gulli's _Agentic Design Patterns_, partly implements 7 (scoped to shipping code), leaves 2 out by design, and goes beyond the book in 8 places. Full mapping: [patterns comparison](.bkit/comparison.md#
|
|
396
|
+
- **Against the literature.** bkit fully implements 13 of the 22 patterns in Antonio Gulli's _Agentic Design Patterns_, partly implements 7 (scoped to shipping code), leaves 2 out by design, and goes beyond the book in 8 places. Full mapping: [patterns comparison](.bkit/comparison.md#patterns), with [where bkit goes beyond the book](.bkit/comparison.md#beyond-the-book) and its [known gaps](.bkit/comparison.md#known-gaps). Every agent in execution order: [pipeline reference](.bkit/pipeline.md).
|
|
297
397
|
|
|
298
398
|
</details>
|
|
299
399
|
|
|
@@ -305,12 +405,42 @@ We measured both on 456 real Claude Code transcripts. They saved about 1–3% of
|
|
|
305
405
|
| [`.bkit/install.md`](.bkit/install.md) | Install, upgrade, CI auth, uninstall, recovery |
|
|
306
406
|
| [`.bkit/README.md`](.bkit/README.md) | Day-to-day use: running workflows, environment, tracker setup, CLI |
|
|
307
407
|
| [`.bkit/workflows.md`](.bkit/workflows.md) | Every workflow step, verdict and contract |
|
|
308
|
-
| [`.bkit/providers.md`](.bkit/providers.md) | Tool and provider differences, model pins |
|
|
408
|
+
| [`.bkit/providers.md`](.bkit/providers.md) | Tool and provider differences, guardrails, model pins |
|
|
309
409
|
| [`.bkit/cloud.md`](.bkit/cloud.md) | Cloud agents: Claude Code on the web, Cursor, opencode |
|
|
310
410
|
| [`.bkit/templates.md`](.bkit/templates.md) | Templates ready to adopt |
|
|
311
|
-
| [`.bkit/
|
|
411
|
+
| [`.bkit/lite.md`](.bkit/lite.md) | Lite workflows: shorter prompts for small changes |
|
|
412
|
+
| [`.bkit/pipeline.md`](.bkit/pipeline.md) | Every agent in the order it runs, the CI scaffold, every audit template |
|
|
413
|
+
| [`.bkit/comparison.md`](.bkit/comparison.md) | Comparison with other AI development frameworks and with _Agentic Design Patterns_ |
|
|
312
414
|
| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
|
|
313
415
|
|
|
416
|
+
<a id="quick-start"></a>
|
|
417
|
+
|
|
418
|
+
## Quick start
|
|
419
|
+
|
|
420
|
+
**You need** a GitHub repo with a `package.json`, Node 24+, pnpm, and at least one of Claude Code, Cursor, Codex, Google Antigravity or opencode.
|
|
421
|
+
|
|
422
|
+
**Easiest:** copy the [install prompt](.bkit/install.md#install--first-time) into your AI coding tool and let it do the setup.
|
|
423
|
+
|
|
424
|
+
**By hand:** bkit is public on npm and installs like any other package, with no token or registry setup.
|
|
425
|
+
|
|
426
|
+
```bash
|
|
427
|
+
pnpm add -D @cbartens/bkit
|
|
428
|
+
pnpm bkit install --claude # pick your tools: --claude --cursor --codex --antigravity --opencode=<provider>
|
|
429
|
+
# opencode provider: openrouter | ollama | opencode-zen | opencode-go
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
**Check it worked:** `pnpm bkit check` confirms every installed file matches the version you pinned (CI runs the same check), and `pnpm bkit tips` lists what isn't set up yet, most useful first.
|
|
433
|
+
|
|
434
|
+
Adopt the [templates](#templates) you want from `.bkit/templates/`, open an issue, and run the first step from your AI tool:
|
|
435
|
+
|
|
436
|
+
```text
|
|
437
|
+
/bkit-design ISSUE-123
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
Already know exactly what to build? Start at `/bkit-plan`. Something broken? `/bkit-debug`; add `[repro]` if nothing fails yet, and it writes the failing test first.
|
|
441
|
+
|
|
442
|
+
Full install, upgrade and CI setup: [`.bkit/install.md`](.bkit/install.md). Tracker labels and environment variables: [`.bkit/README.md`](.bkit/README.md#prerequisites).
|
|
443
|
+
|
|
314
444
|
## Credits
|
|
315
445
|
|
|
316
446
|
bkit's process was worked out over months of building real products with it. These projects sharpened specific ideas along the way:
|
|
@@ -318,12 +448,12 @@ bkit's process was worked out over months of building real products with it. The
|
|
|
318
448
|
<!-- prettier-ignore -->
|
|
319
449
|
| Project | Idea bkit took |
|
|
320
450
|
| --- | --- |
|
|
321
|
-
| [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. |
|
|
451
|
+
| [everything-claude-code](https://github.com/affaan-m/ECC) (affaan-m) | [GateGuard](.bkit/prompts.md#hook-injected-text), 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. |
|
|
322
452
|
| [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. |
|
|
323
|
-
| _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#
|
|
453
|
+
| _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#patterns). |
|
|
324
454
|
| [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. |
|
|
325
455
|
|
|
326
|
-
**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).
|
|
456
|
+
**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), [Trivy](https://github.com/aquasecurity/trivy), [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).
|
|
327
457
|
|
|
328
458
|
## License
|
|
329
459
|
|