@cbartens/bkit 6.1.0 → 6.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 -12
- package/.bkit/core/.agents/docs.md +1 -11
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
- package/.bkit/core/.agents/rules.md +22 -9
- package/.bkit/core/.bkit/README.md +13 -11
- package/.bkit/core/.bkit/authoring.md +58 -13
- package/.bkit/core/.bkit/cli.md +43 -33
- package/.bkit/core/.bkit/cloud.md +93 -30
- package/.bkit/core/.bkit/install.md +55 -16
- package/.bkit/core/.bkit/jsonl.md +24 -7
- package/.bkit/core/.bkit/pipeline.md +8 -8
- package/.bkit/core/.bkit/prompts.md +160 -43
- package/.bkit/core/.bkit/providers.md +99 -36
- package/.bkit/core/.bkit/templates.md +167 -37
- package/.bkit/core/.bkit/trackers.md +39 -6
- package/.bkit/core/.bkit/workflows.md +344 -136
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
- package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
- 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 +2 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
- package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +38 -8
- package/.bkit/core/engine/checks/after/auth.ts +118 -47
- package/.bkit/core/engine/checks/after/github.ts +161 -37
- package/.bkit/core/engine/checks/after/index.ts +18 -3
- package/.bkit/core/engine/checks/after/tools.ts +245 -1
- package/.bkit/core/engine/checks/before/files.ts +59 -1
- package/.bkit/core/engine/checks/before/index.ts +8 -0
- package/.bkit/core/engine/checks/status-holes.ts +20 -26
- package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
- package/.bkit/core/engine/checks/tips/detect.ts +36 -3
- package/.bkit/core/engine/checks/tips/index.ts +1 -1
- package/.bkit/core/engine/cli.ts +13 -13
- package/.bkit/core/engine/commands/ci/ci.ts +124 -19
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- package/.bkit/core/engine/commands/install/doctor.ts +5 -5
- package/.bkit/core/engine/commands/install/install.ts +28 -25
- package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
- package/.bkit/core/engine/commands/land.ts +2 -3
- package/.bkit/core/engine/commands/lib.ts +394 -39
- package/.bkit/core/engine/commands/registry.ts +1 -1
- package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
- package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
- package/.bkit/core/engine/commands/workflow/context.ts +71 -10
- package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
- package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
- package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
- package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
- package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
- package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
- package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
- package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
- package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
- package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
- package/.bkit/core/engine/commands/workflow/status.ts +324 -11
- package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
- package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
- package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
- package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
- package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
- package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
- package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
- package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
- package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
- package/.bkit/core/engine/install/cloud-env.ts +38 -10
- package/.bkit/core/engine/install/managed-block.ts +105 -0
- package/.bkit/core/engine/install/manifest.ts +7 -1
- package/.bkit/core/engine/install/modules/claude.ts +6 -2
- package/.bkit/core/engine/install/modules/cloud.ts +84 -95
- package/.bkit/core/engine/install/modules/codex.ts +10 -2
- package/.bkit/core/engine/install/modules/core.ts +202 -26
- package/.bkit/core/engine/install/modules/opencode.ts +18 -23
- package/.bkit/core/engine/install/network-allowlist.ts +8 -3
- package/.bkit/core/engine/install/project-docs.ts +650 -0
- package/.bkit/core/engine/install/template-copies.ts +58 -5
- package/.bkit/core/engine/install/write.ts +128 -7
- package/.bkit/core/engine/ledgers/journal.ts +18 -10
- package/.bkit/core/engine/ledgers/migrate.ts +20 -8
- package/.bkit/core/engine/ledgers/status.ts +604 -8
- package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
- package/.bkit/core/engine/render/trackers.ts +46 -11
- package/.bkit/core/engine/shared/package-manager.ts +7 -3
- package/.bkit/core/engine/shared/settings.ts +12 -1
- package/.bkit/core/engine/shared/text.ts +14 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
- package/.bkit/core/engine/tools/instructions.ts +116 -20
- package/.bkit/core/hooks/antigravity-hook.js +20 -4
- package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
- package/.bkit/core/hooks/gateguard-engine.js +249 -23
- package/.bkit/core/hooks/guardrails-deny.js +167 -0
- package/.bkit/core/hooks/guardrails-read.js +3 -3
- package/.bkit/core/hooks/guardrails-shell.js +1122 -167
- package/.bkit/core/hooks/guardrails-tiers.js +247 -176
- package/.bkit/core/hooks/preflight-tracker.sh +219 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
- package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
- package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
- package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
- package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
- package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
- package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
- package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
- package/.bkit/core/prompts/bkit-design-generate.md +6 -4
- package/.bkit/core/prompts/bkit-design-organise.md +4 -3
- package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
- package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
- package/.bkit/core/prompts/bkit-design-spike.md +4 -3
- package/.bkit/core/prompts/bkit-design-update.md +6 -4
- package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
- package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
- package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
- package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
- package/.bkit/core/prompts/bkit-plan-update.md +22 -8
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
- package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
- package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
- package/.bkit/core/workflows/bkit-auto.md +23 -11
- package/.bkit/core/workflows/bkit-build.md +331 -100
- package/.bkit/core/workflows/bkit-debug.md +135 -64
- package/.bkit/core/workflows/bkit-design.md +58 -32
- package/.bkit/core/workflows/bkit-plan.md +73 -45
- package/.bkit/core/workflows/bkit-ship.md +233 -167
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
- package/.bkit/shared/.bkit/.env.example +5 -0
- package/.bkit/shared/.claude/bkit-cloud.md +7 -7
- package/.bkit/shared/.claude/settings.json +5 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
- package/.bkit/shared/.cursor/hooks.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
- package/.bkit/templates/.cursor/Dockerfile +7 -7
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
- package/.bkit/templates/.github/dependabot.yml +5 -0
- package/.bkit/templates/.github/renovate.json5 +5 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
- package/.bkit/templates/.husky/pre-push +123 -6
- package/.bkit/templates/context/bkit-serena.md +1 -1
- package/.bkit/templates/context/bkit-vercel.md +103 -59
- package/.bkit/templates/docs/architecture.md +98 -0
- package/.bkit/templates/docs/capabilities.md +33 -37
- package/.bkit/templates/docs/components.md +142 -0
- package/.bkit/templates/docs/data-schema.md +87 -0
- package/.bkit/{shared → templates}/docs/deployments.md +128 -142
- package/.bkit/templates/docs/design.md +117 -0
- package/.bkit/templates/docs/noise.md +54 -0
- package/.bkit/templates/docs/observability.md +99 -0
- package/.bkit/templates/docs/security.md +137 -0
- package/.bkit/templates/docs/setup.md +93 -0
- package/.bkit/templates/docs/technology.md +70 -0
- package/.bkit/{shared → templates}/docs/testing.md +200 -87
- package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +79 -0
- package/DETAILS.md +661 -0
- package/README.md +73 -604
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +138 -35
- package/dist/checks/after/index.js +16 -4
- package/dist/checks/after/tools.js +224 -1
- package/dist/checks/before/files.js +59 -1
- package/dist/checks/before/index.js +7 -1
- package/dist/checks/status-holes.js +20 -21
- package/dist/checks/tips/catalogue.js +99 -10
- package/dist/checks/tips/detect.js +35 -3
- package/dist/checks/tips/index.js +1 -1
- package/dist/cli.js +13 -13
- package/dist/commands/ci/ci.js +113 -20
- package/dist/commands/ci/push-gate.js +79 -44
- package/dist/commands/install/doctor.js +5 -5
- package/dist/commands/install/install.js +23 -22
- package/dist/commands/install/uninstall.js +36 -30
- package/dist/commands/install/upgrade.js +10 -2
- package/dist/commands/land.js +2 -3
- package/dist/commands/lib.js +323 -25
- package/dist/commands/workflow/branches.js +312 -72
- package/dist/commands/workflow/challenge.js +66 -13
- package/dist/commands/workflow/context.js +46 -10
- package/dist/commands/workflow/counters.js +231 -23
- package/dist/commands/workflow/decisions.js +221 -106
- package/dist/commands/workflow/disk.js +2 -1
- package/dist/commands/workflow/feature-base.js +60 -0
- package/dist/commands/workflow/issues.js +243 -15
- package/dist/commands/workflow/junit.js +137 -0
- package/dist/commands/workflow/ledgers.js +726 -112
- package/dist/commands/workflow/locks.js +150 -29
- package/dist/commands/workflow/loops.js +67 -0
- package/dist/commands/workflow/open-decision.js +199 -0
- package/dist/commands/workflow/plan-blocks.js +6 -0
- package/dist/commands/workflow/plans.js +1 -1
- package/dist/commands/workflow/prs.js +272 -16
- package/dist/commands/workflow/repo.js +1 -1
- package/dist/commands/workflow/run-facts.js +6 -0
- package/dist/commands/workflow/runs.js +747 -155
- package/dist/commands/workflow/runtime.js +8 -4
- package/dist/commands/workflow/status.js +259 -13
- package/dist/commands/workflow/step-table.js +41 -15
- package/dist/commands/workflow/steps.js +530 -26
- package/dist/commands/workflow/summary-findings.js +1 -1
- package/dist/commands/workflow/summary.js +289 -8
- package/dist/commands/workflow/tasks.js +294 -27
- package/dist/commands/workflow/tests-base.js +266 -0
- package/dist/commands/workflow/tests-changed.js +130 -56
- package/dist/commands/workflow/tests-jump.js +77 -0
- package/dist/commands/workflow/tests.js +608 -131
- package/dist/commands/workflow/tracker.js +920 -112
- package/dist/commands/workflow/workflows.js +80 -59
- package/dist/commands/workflow/worktrees.js +387 -58
- package/dist/install/cloud-env.js +32 -10
- package/dist/install/managed-block.js +101 -0
- package/dist/install/manifest.js +7 -1
- package/dist/install/modules/claude.js +6 -2
- package/dist/install/modules/cloud.js +73 -86
- package/dist/install/modules/codex.js +9 -2
- package/dist/install/modules/core.js +190 -27
- package/dist/install/modules/opencode.js +18 -23
- package/dist/install/network-allowlist.js +8 -3
- package/dist/install/project-docs.js +551 -0
- package/dist/install/template-copies.js +55 -5
- package/dist/install/write.js +117 -5
- package/dist/ledgers/journal.js +10 -8
- package/dist/ledgers/migrate.js +20 -9
- package/dist/ledgers/status.js +461 -8
- package/dist/ledgers/telemetry.js +71 -13
- package/dist/render/trackers.js +21 -12
- package/dist/shared/package-manager.js +7 -2
- package/dist/shared/settings.js +8 -0
- package/dist/shared/text.js +13 -0
- package/dist/tools/instructions-sources.js +1 -0
- package/dist/tools/instructions.js +97 -24
- package/package.json +23 -15
- package/.bkit/core/hooks/preflight-linear.sh +0 -73
- package/.bkit/shared/docs/architecture.md +0 -16
- package/.bkit/shared/docs/data-schema.md +0 -16
- package/.bkit/shared/docs/design.md +0 -38
- package/.bkit/shared/docs/noise.md +0 -20
- package/.bkit/shared/docs/observability.md +0 -22
- package/.bkit/shared/docs/security.md +0 -62
- package/.bkit/shared/docs/setup.md +0 -52
- package/.bkit/shared/docs/technology.md +0 -15
- /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
- /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
package/DETAILS.md
ADDED
|
@@ -0,0 +1,661 @@
|
|
|
1
|
+
<picture>
|
|
2
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-hero-dark.svg">
|
|
3
|
+
<img alt="bkit: independent reviewers, your sign-off, completion checked by code, project knowledge, audits and CI." src=".github/assets/bkit-hero-light.svg" width="100%">
|
|
4
|
+
</picture>
|
|
5
|
+
|
|
6
|
+
<p align="center">
|
|
7
|
+
<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>
|
|
8
|
+
<a href="https://www.npmjs.com/package/@cbartens/bkit"><img alt="npm version" src="https://img.shields.io/npm/v/@cbartens/bkit"></a>
|
|
9
|
+
<a href="#license"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
|
|
10
|
+
<img alt="Node 24+" src="https://img.shields.io/badge/node-%E2%89%A524-339933">
|
|
11
|
+
<img alt="Works with Claude, Codex, Antigravity, Cursor and OpenCode" src="https://img.shields.io/badge/works%20with-Claude%20%C2%B7%20Codex%20%C2%B7%20Antigravity%20%C2%B7%20Cursor%20%C2%B7%20OpenCode-8250df">
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
<p align="center">
|
|
15
|
+
<a href=".bkit/install.md">Install guide ↗</a> ·
|
|
16
|
+
<a href=".bkit/README.md">User guide ↗</a> ·
|
|
17
|
+
<a href=".bkit/comparison.md#frameworks">Comparison ↗</a>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
**Explore bkit in detail** · [← Short README](README.md)
|
|
21
|
+
|
|
22
|
+
[What's included](#whats-inside) · [How it works](#how-it-works) · [Models](#models) · [Reviews and checks](#why-its-different) · [Agents and CI](#agents-and-ci) · [Engine](#engine) · [Project knowledge](#knowledge) · [Audits](#audits) · [Templates and code map](#templates) · [Other capabilities](#what-else-you-get) · [Token costs](#token-costs) · [Measurements](#measurements) · [FAQ](#faq) · [Documentation](#documentation) · [Quick start](#quick-start) · [Credits](#credits) · [Licence](#license)
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
**A repeatable process for shipping software with AI coding agents.**
|
|
27
|
+
|
|
28
|
+
Describe a feature in an issue. bkit brings agents together to design, plan, build, review and ship it—with your approval at key stages. Independent reviewers challenge the work, automated checks verify completion, and project files carry decisions and lessons into the next feature.
|
|
29
|
+
|
|
30
|
+
Works with **Claude, Codex, Antigravity, Cursor and OpenCode**. Uses **GitHub, Linear or Jira** for issues, with code and pull requests on **GitHub**. Free and open source.
|
|
31
|
+
|
|
32
|
+
- **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.
|
|
33
|
+
- **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.
|
|
34
|
+
|
|
35
|
+
**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.
|
|
36
|
+
|
|
37
|
+
**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 **2,000+ 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.
|
|
38
|
+
|
|
39
|
+
**Every file bkit gives your agents to read follows Anthropic's, OpenAI's and Google's own prompting advice:** prompts, workflows, rules and project docs are all written to one set of [writing rules](.bkit/authoring.md), [matched practice by practice](.bkit/authoring.md#who-says-what) against each maker's current guide, so the same text works on Claude, GPT and Gemini. The [prompt audit](.bkit/pipeline.md#audits) checks every one of those files against it, and every one passes.
|
|
40
|
+
|
|
41
|
+
<p align="center">
|
|
42
|
+
<picture>
|
|
43
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-features-dark.svg">
|
|
44
|
+
<img alt="What ships with bkit: four features for each phase (design, plan, build, debug, ship) and four that apply to every phase." src=".github/assets/bkit-features-light.svg" width="100%">
|
|
45
|
+
</picture>
|
|
46
|
+
</p>
|
|
47
|
+
|
|
48
|
+
<a id="whats-inside"></a>
|
|
49
|
+
|
|
50
|
+
## What's inside: 200+ files of best practice
|
|
51
|
+
|
|
52
|
+
Everything a senior team would otherwise write down over years, in files you can read:
|
|
53
|
+
|
|
54
|
+
<!-- prettier-ignore -->
|
|
55
|
+
| What | How many | What it does for you |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| [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. |
|
|
58
|
+
| [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. |
|
|
59
|
+
| [Agent rules](.agents/rules.md) | 70+ | One rulebook every agent follows: read before editing, never defer silently, report honestly, never rewrite history. |
|
|
60
|
+
| [Writing rules](.bkit/authoring.md) | 50+ | How every prompt, workflow, rule and doc is worded, [matched practice by practice](.bkit/authoring.md#who-says-what) against Anthropic's, OpenAI's and Google's prompting guides, so one text works on every model. |
|
|
61
|
+
| [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. |
|
|
62
|
+
| [Audits](.bkit/pipeline.md#audits) | 35 | Security, privacy, accessibility, performance, reliability, database, LLM usage, cost and more. Findings feed straight into a plan. |
|
|
63
|
+
| [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. |
|
|
64
|
+
| [Templates](.bkit/templates.md) | 60+ | A full CI pipeline, cloud agents, git hooks, linters, dependency updates, secrets sync, code search, a map of your code that marks likely problems, and 10+ ready-made connectors for your platforms. |
|
|
65
|
+
|
|
66
|
+
**These are the files your agents read, so they're written for agents,** to the writing rules above: 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).
|
|
67
|
+
|
|
68
|
+
<a id="how-it-works"></a>
|
|
69
|
+
|
|
70
|
+
## How it works
|
|
71
|
+
|
|
72
|
+
<p align="center">
|
|
73
|
+
<picture>
|
|
74
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-pipeline-dark.svg">
|
|
75
|
+
<img alt="The bkit pipeline: design, plan, build and ship, with debug fixing failed tests. 30 agents across the five phases, and your sign-off after design, after plan and before merge." src=".github/assets/bkit-pipeline-light.svg" width="100%">
|
|
76
|
+
</picture>
|
|
77
|
+
</p>
|
|
78
|
+
|
|
79
|
+
**One command per job.** Each runs a team of specialised agents, so there are no prompts to write and no steps to remember.
|
|
80
|
+
|
|
81
|
+
<!-- prettier-ignore -->
|
|
82
|
+
| Job | Command | What happens |
|
|
83
|
+
| --- | --- | --- |
|
|
84
|
+
| 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.** |
|
|
85
|
+
| Plan the work | [`/bkit-plan`](.bkit/pipeline.md#bkit-plan) | A plan of small, self-contained tasks, each naming the code it touches and the test that proves it's done. Two reviewers and a scope check go over it in one round, with past bugs and postponed work in view. **You approve it.** |
|
|
86
|
+
| Build it | [`/bkit-build`](.bkit/pipeline.md#bkit-build) | Checks the plan still matches the code, then builds it one group of tasks at a time, each with a fresh agent: tests first, then code, then an independent check. Hunts for bugs and security holes (only security holes on a small change), fixes what it finds as more tasks, and opens a pull request. |
|
|
87
|
+
| Build it, hold the push | `/bkit-build #N publish=false` | The same build, stopped before the push: no pull request, no CI, the worktree and branch kept. `/bkit-ship <ref>` lands it later. |
|
|
88
|
+
| 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. |
|
|
89
|
+
| 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. |
|
|
90
|
+
| Health check | [35 audits](#audits) | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
|
|
91
|
+
| Housekeeping | 8 utility agents | Keep docs, decisions, lessons and known bugs current, and rank what to work on next. |
|
|
92
|
+
|
|
93
|
+
**Build now, publish later.** `/bkit-build #N` builds and publishes: it pushes `feat/{FID}`, opens the pull request and starts CI. `/bkit-build #N publish=false` builds locally and holds. The same plan, tests-first checks and bug hunt run, but nothing is pushed, no pull request is opened and no CI starts. The worktree and branch stay, the lock is released, the issue moves to `In review` with a "built locally, not published" comment, and the summary reads `Publish: held` and `Docs: not synced`. `/bkit-ship <ref>` later lands a held build end to end. To make holding the default on your machine, set `bkit.workflows.build.publish.local` to `false` in `package.json`. Cloud runs always publish: `publish.remote` accepts only `true`, and `publish=false` on a cloud run is turned back into `true` with a warning.
|
|
94
|
+
|
|
95
|
+
<a id="batch-recipe"></a>
|
|
96
|
+
|
|
97
|
+
**Batch recipe (manual).** To land several held builds in one go, build each with `publish=false`, then land them yourself with `git`: merge the held `feat/{FID}` branches into one branch off `dev`, push it, open one pull request and let CI run. bkit has no batch command, and you own the push, the PR, the CI gate, the sweep and the docs sync, because `/bkit-ship` does none of them for a batch. Two limits apply:
|
|
98
|
+
|
|
99
|
+
- One head commit: post-merge auto-debug sees only the last FID, so a failure from an earlier build in the batch is not routed to its own issue.
|
|
100
|
+
- Never batch migrations: a batch applies them together, and one bad migration blocks every build in it.
|
|
101
|
+
|
|
102
|
+
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).
|
|
103
|
+
|
|
104
|
+
<a id="models"></a>
|
|
105
|
+
|
|
106
|
+
## Which model does each job
|
|
107
|
+
|
|
108
|
+
**Spend the subscriptions you already pay for first; when their weekly usage runs out, OpenCode on OpenRouter carries the work.** Inside a subscription — Claude, Codex, Antigravity, Cursor — each agent gets the model from that vendor that gets the most work out of the usage you have paid for. On OpenCode, which bills per token, Claude sets the bar: each agent gets the cheapest model that comes closest to it, under a weekly cap. You don't pick: install sets each agent's model.
|
|
109
|
+
|
|
110
|
+
<p align="center">
|
|
111
|
+
<picture>
|
|
112
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-models-dark.svg">
|
|
113
|
+
<img alt="The Claude model and effort behind each bkit agent: Opus 5.5 for /bkit-design, /bkit-plan, /bkit-debug and 27 agents; Sonnet 5.5 for /bkit-build, /bkit-ship and 12 agents. Pick the model at launch and leave the effort alone." src=".github/assets/bkit-models-light.svg" width="100%">
|
|
114
|
+
</picture>
|
|
115
|
+
</p>
|
|
116
|
+
|
|
117
|
+
**How the picks are made.** Two different questions, one table. **Subscription tools** — Claude, Codex, Antigravity, Cursor — are paid for up front, so each agent gets the best model that vendor's plan includes for its job: depth where the reasoning is, cheaper rungs where the work is volume, spending the included usage where it buys most. They are never imitations of another vendor. **OpenCode gateways** — OpenRouter, Ollama, OpenCode Zen, OpenCode Go — bill per token, so Claude is the yardstick there: each agent gets the cheapest model that comes closest to the Claude model it would run on, within budget. OpenRouter is the overflow for when the subscription's weekly usage is spent. Its default runs almost everything on DeepSeek and puts `gpt-6.1-sol` on the four checks where a miss would ship unnoticed. Covering a two-day gap that way costs about **US$52**, roughly a quarter of a US$200-a-month Claude Max plan, or about one week's share of it. Option 2 in [Model Presets](.bkit/prompts.md#model-presets) doubles the weekly budget to about US$100 for work that matters more than the cost. Every score is from the public LiveBench 2.0 benchmark, **Long Agentic** category, release 2026-10-25, so rows stay comparable; v1's Agentic Coding category is retired and does not convert.
|
|
118
|
+
|
|
119
|
+
<!-- prettier-ignore -->
|
|
120
|
+
| Tool | Hardest jobs: design, plans, reviews, security, audits | Everyday jobs: writing code and docs, the second model in each review pair |
|
|
121
|
+
| --- | --- | --- |
|
|
122
|
+
| Claude | `claude-opus-5-5` · bar **72.8** | `claude-sonnet-5-5` · bar **63.4** |
|
|
123
|
+
| Codex | `gpt-6-astra` · 77.5; `gpt-6.1-sol` · 68.7 for the builders | `gpt-6.1-sol` · 68.7 |
|
|
124
|
+
| Antigravity | `gemini-4-argon` · 61.2 | `gemini-4-argon` · 61.2 |
|
|
125
|
+
| Cursor | `cursor-grok-4.5-high` · not measured | `composer-2.5` · not measured |
|
|
126
|
+
| OpenCode + OpenRouter | `deepseek/deepseek-v4.1-flash-1017` · 40.9; `openai/gpt-6.1-sol` · 68.7 for the four key gates | `deepseek/deepseek-v4.1-flash-1017` · 40.9 |
|
|
127
|
+
| OpenCode + Ollama | `deepseek-v4.1-flash:1017` · 40.9 | `deepseek-v4.1-flash:1017` · 40.9 |
|
|
128
|
+
| OpenCode + OpenCode Zen | `deepseek-v4.1-flash` · not measured; `gpt-6.1-sol` · 68.7 for the four key gates | `deepseek-v4.1-flash` · not measured |
|
|
129
|
+
| OpenCode + OpenCode Go | `deepseek-v4.1-flash` · not measured; `gemini-4-argon` · 61.2 for the four key gates | `deepseek-v4.1-flash` · not measured |
|
|
130
|
+
|
|
131
|
+
**Reading the table:**
|
|
132
|
+
|
|
133
|
+
- **Every score comes from the same benchmark.** `claude-opus-5-5` scores **72.8** and `claude-sonnet-5-5` **63.4** on Long Agentic: the bars every OpenCode pick is measured against.
|
|
134
|
+
- **Four key gates get the strongest model the budget carries.** These are the checks where a miss reaches the merge unnoticed: `bkit-build-plan-verify` (decides a build is done), `bkit-ship-deferred-sweep` (last check before merge), `bkit-debug-failure-diagnose` (picks the root cause the fix chases) and `bkit-build-challenge-2` (the security review). On OpenCode that is `gpt-6.1-sol` on OpenRouter and Zen, `gemini-4-argon` on Go, which has no Sol, and DeepSeek on Ollama, which has nothing stronger.
|
|
135
|
+
- **DeepSeek thinks at its maximum on every OpenCode agent**, because it sits under the Claude bar. `gpt-6.1-sol` already sits near the bar, so it keeps the agent's own Claude effort: effort only goes as high as it takes to get close to Claude, never past it.
|
|
136
|
+
- **On Cursor, bkit pins Cursor's own models**, the ones its plan includes: `cursor-grok-4.5-high` and `composer-2.5`. Neither is measured on LiveBench 2.0 — the catalogue offers no Grok 4.6/4.7 and no Opus 5.5 / Sonnet 5.5, re-probed 2026-10-28. Claude and GPT models in Cursor spend paid API credits, so they're opt-in through [Model Overrides](.bkit/prompts.md#model-overrides).
|
|
137
|
+
- **"Not measured" means LiveBench 2.0 hasn't scored that model.** Those Cursor picks follow each vendor's own description of the model. Check them before you rely on them.
|
|
138
|
+
- **Ollama needs a paid plan for every column.** The free models are not scored.
|
|
139
|
+
- **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).
|
|
140
|
+
|
|
141
|
+
**On Claude, each agent also sets its own effort**, so the effort you leave your session on never changes theirs. Start each `/bkit-*` command on the model the picture above shows and leave effort at the default. Session setup in full: [`.bkit/prompts.md` § Orchestrators](.bkit/prompts.md#orchestrators-slash-commands).
|
|
142
|
+
|
|
143
|
+
<a id="why-its-different"></a>
|
|
144
|
+
|
|
145
|
+
## Why it's different
|
|
146
|
+
|
|
147
|
+
<p align="center">
|
|
148
|
+
<picture>
|
|
149
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-fences-dark.svg">
|
|
150
|
+
<img alt="AI agents start out scattered and are funnelled phase by phase into production-grade code, fenced in first by reviewer agents and then by automated checks, with your sign-off at three points." src=".github/assets/bkit-fences-light.svg" width="100%">
|
|
151
|
+
</picture>
|
|
152
|
+
</p>
|
|
153
|
+
|
|
154
|
+
New to how AI models produce answers? [This 21-slide primer](.github/assets/bkit-how-ai-llms-produce-answers.pdf) shows why an answer is only as good as the model's input, and why bkit gives every agent rich input and checks what it produces.
|
|
155
|
+
|
|
156
|
+
**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. **The fences are code, not instructions:** `bkit` won't let a step finish without its verdict and files, won't pass a task whose test it didn't see fail first, and stops a fix that didn't work after one round.
|
|
157
|
+
|
|
158
|
+
<a id="agents-and-ci"></a>
|
|
159
|
+
|
|
160
|
+
## Agents and CI, built to work together
|
|
161
|
+
|
|
162
|
+
<p align="center">
|
|
163
|
+
<picture>
|
|
164
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-fences-details-dark.svg">
|
|
165
|
+
<img alt="The six checks every change passes, nearest first: code search, agent hooks, step gates, the pre-commit hook, the pre-push hook and CI, and where each workflow meets them." src=".github/assets/bkit-fences-details-light.svg" width="100%">
|
|
166
|
+
</picture>
|
|
167
|
+
</p>
|
|
168
|
+
|
|
169
|
+
**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:
|
|
170
|
+
|
|
171
|
+
- **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.
|
|
172
|
+
- **`/bkit-plan`** decides which tests each feature needs and where each one runs: unit, integration or end-to-end.
|
|
173
|
+
- **`/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.
|
|
174
|
+
- **`/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.
|
|
175
|
+
- **`/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.
|
|
176
|
+
- **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)).
|
|
177
|
+
|
|
178
|
+
What that gets you:
|
|
179
|
+
|
|
180
|
+
- **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.
|
|
181
|
+
- **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.
|
|
182
|
+
- **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.
|
|
183
|
+
- **Problems are caught at the nearest fence.** Agent hooks nudge on every edit: read a file before changing it, fix the code rather than loosen a check. The pre-commit hook formats in seconds. The pre-push hook runs type checks, unit tests, integration tests (once you declare that gate), the prose checker and the junk-code scanner before anything leaves your laptop. CI keeps only what can't run there: end-to-end and live-site tests. Hooks, agents and CI's quick-checks lane all run the same `bkit:gate:*` scripts, so most failures show up on your machine first.
|
|
184
|
+
|
|
185
|
+
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).
|
|
186
|
+
|
|
187
|
+
<a id="ci-pipeline"></a>
|
|
188
|
+
|
|
189
|
+
### The CI pipeline
|
|
190
|
+
|
|
191
|
+
**bkit ships a full test pipeline for your project, ready to adopt:**
|
|
192
|
+
|
|
193
|
+
<p align="center">
|
|
194
|
+
<picture>
|
|
195
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-ci-dark.svg">
|
|
196
|
+
<img alt="bkit’s CI pipeline, from planning the run to tidying up. Every lane feeds one final check, which fails if any lane failed, was skipped or ran no tests." src=".github/assets/bkit-ci-light.svg" width="100%">
|
|
197
|
+
</picture>
|
|
198
|
+
</p>
|
|
199
|
+
|
|
200
|
+
- **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`).
|
|
201
|
+
- **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.
|
|
202
|
+
- **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.
|
|
203
|
+
- **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.
|
|
204
|
+
- **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.
|
|
205
|
+
|
|
206
|
+
How the lanes join into the one final check, and what happens on green or red: [CI test scaffold](.bkit/pipeline.md#ci-scaffold).
|
|
207
|
+
|
|
208
|
+
<a id="engine"></a>
|
|
209
|
+
|
|
210
|
+
## Code keeps every run on track
|
|
211
|
+
|
|
212
|
+
<p align="center">
|
|
213
|
+
<picture>
|
|
214
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-engine-dark.svg">
|
|
215
|
+
<img alt="One /bkit-build run in three layers: agents make the judgement calls, bkit commands do the bookkeeping, and your repo holds the plain files both read and write." src=".github/assets/bkit-engine-light.svg" width="100%">
|
|
216
|
+
</picture>
|
|
217
|
+
</p>
|
|
218
|
+
|
|
219
|
+
**CI checks the code agents write; the engine checks the run itself.** Agents are good at judgement, not bookkeeping. Ask a model to count fix rounds, confirm a test failed before its code existed, or remember where a stopped run left off, and it can get it wrong, and differently on each tool. bkit doesn't ask. Anything with one right answer is a `bkit` command, plain TypeScript covered by 5,800+ tests, and the agents keep only the calls that need judgement.
|
|
220
|
+
|
|
221
|
+
- **Steps that can't be faked.** A step can't finish until `bkit steps gate` finds its verdict and files, whatever the agent reports. A test counts as written first only once `bkit tests red` has seen it fail before its code existed.
|
|
222
|
+
- **Limits no answer can raise.** `bkit counters route` counts fix rounds and stops at the limit set under `bkit.workflows` in `package.json` (2 attempts by default), however sure the agent is.
|
|
223
|
+
- **The same answer on every tool.** Where a stopped run resumes, what goes in a ledger row and what each agent's brief holds are worked out by code, so Claude, Codex, Antigravity, Cursor and OpenCode run the same steps the same way.
|
|
224
|
+
- **Fewer tokens, as a bonus.** No model turn is spent on bookkeeping, and each build agent starts on a brief of a few KB instead of the whole plan ([spending fewer tokens](#token-costs)).
|
|
225
|
+
|
|
226
|
+
<a id="knowledge"></a>
|
|
227
|
+
<a id="memory"></a>
|
|
228
|
+
|
|
229
|
+
## Knowledge store that writes itself
|
|
230
|
+
|
|
231
|
+
<p align="center">
|
|
232
|
+
<picture>
|
|
233
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-context-dark.svg">
|
|
234
|
+
<img alt="Where bkit keeps each kind of fact, in your repo or on your tracker, CI and runtime platforms, and which step reads or writes it." src=".github/assets/bkit-context-light.svg" width="100%">
|
|
235
|
+
</picture>
|
|
236
|
+
</p>
|
|
237
|
+
|
|
238
|
+
**Each kind of fact has one home**, in a plain file in your repo or a comment on your tracker issue. Agents read them directly, the way you do, and write back as they work. Lessons from fixes, decisions and the reasons behind them, work consciously postponed, known bugs, doc updates, tracker comments — the store accrues as the project runs, and every change arrives through git.
|
|
239
|
+
|
|
240
|
+
**Outside evidence, fetched when it's needed, not kept.** 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. Each fetches only the window, severity and fields it needs and tail-bounds what it returns, so a debug run reads lines rather than megabytes. A connector that isn't set up is reported as such, never read as "all clear".
|
|
241
|
+
|
|
242
|
+
**Where every kind of fact lives, who writes it, when the next step reads it:**
|
|
243
|
+
|
|
244
|
+
<!-- prettier-ignore -->
|
|
245
|
+
| Kind of fact | Lives in | Written by | Read at |
|
|
246
|
+
| --- | --- | --- | --- |
|
|
247
|
+
| What the project is | `docs/*.md`: architecture, security, testing, deployments, data schema, observability, technology, design | Agents fill them in as they work; `/bkit-ship` updates them after every feature | Every step, per the [docs index](.agents/docs.md) |
|
|
248
|
+
| Lessons from fixes | `docs/knowledge.jsonl` | `/bkit-debug` on root cause; a utility agent closes rows the code has since contradicted | `/bkit-debug` first; plan reviewers |
|
|
249
|
+
| Decisions and reasons | `docs/decisions.jsonl` | `/bkit-design` and `/bkit-plan`; a utility agent corrects contradicted ones | `/bkit-design`, `/bkit-plan` |
|
|
250
|
+
| Work consciously postponed | `docs/deferrals.jsonl` | Any phase that defers; a utility agent closes done ones | Plan reviewers; `/bkit-ship` checks nothing was quietly dropped |
|
|
251
|
+
| Known bugs | `docs/failures.jsonl` | `/bkit-debug`; a utility agent closes fixed ones | Plan reviewers |
|
|
252
|
+
| A feature's running record | Tracker issue comments (GitHub, Linear or Jira) | Every step appends one new comment and never edits older ones | Every step reads the whole issue; design, plan and debug also search other issues, closed ones included |
|
|
253
|
+
| Audit findings | `docs/audits/{YYYYMM}/` | `@bkit-audit-generate` | `/bkit-plan` when fixing |
|
|
254
|
+
| Run state and stats | `.bkit/status.jsonl`, `.bkit/stats.jsonl` | The engine, after every step | `bkit` on resume (any tool); `bkit stats` for your own numbers |
|
|
255
|
+
|
|
256
|
+
**Here's one run working through it** — a feature building _"Add password reset"_ (issue #123), with the exact file each phase draws from and the exact row it leaves behind:
|
|
257
|
+
|
|
258
|
+
<p align="center">
|
|
259
|
+
<picture>
|
|
260
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-knowledge-flow-dark.svg">
|
|
261
|
+
<img alt="One run on issue #123, “Add password reset”: the file each phase reads and the row or doc it writes back." src=".github/assets/bkit-knowledge-flow-light.svg" width="100%">
|
|
262
|
+
</picture>
|
|
263
|
+
</p>
|
|
264
|
+
|
|
265
|
+
**It's not a knowledge graph.** No nodes and edges, no embeddings, no retrieval service to keep running. The strength is the opposite — boring files, append-only ledgers, one home per fact:
|
|
266
|
+
|
|
267
|
+
- **You can read it.** Open any `.md` or `.jsonl` and see exactly what's there. No reconstruction from vectors, no "ask the graph" step.
|
|
268
|
+
- **Every change lands as a diff.** New lessons, decisions and doc updates arrive through git: review, blame, revert. A wrong fact is corrected the same way a wrong line of code is.
|
|
269
|
+
- **The "why" has a timestamp.** Ledger rows are append-only with a date and a reason, so you can replay how an opinion changed. A graph node loses that unless you build an audit layer yourself.
|
|
270
|
+
- **The agent writes to it in the same loop it works in.** Most "AI knowledge" setups are read-only from the model's side; bkit's agents update docs and ledgers as part of normal work, and utility agents close the rows the code has since contradicted. bkit skips its own tracker comments when it reads, so agents act on what people wrote, not on what the last agent said.
|
|
271
|
+
- **Nothing to run.** No index to rebuild, no embeddings to refresh, no service to fail. The agent's file reading is the lookup.
|
|
272
|
+
|
|
273
|
+
<a id="audits"></a>
|
|
274
|
+
|
|
275
|
+
## Audits find what green tests miss
|
|
276
|
+
|
|
277
|
+
<p align="center">
|
|
278
|
+
<picture>
|
|
279
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-audits-dark.svg">
|
|
280
|
+
<img alt="A map of an app whose tests were all passing, marking the bugs that two of bkit’s 35 audit templates found anyway." src=".github/assets/bkit-audits-light.svg" width="100%">
|
|
281
|
+
</picture>
|
|
282
|
+
</p>
|
|
283
|
+
|
|
284
|
+
**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.
|
|
285
|
+
|
|
286
|
+
**Each template is a specialist's checklist for one area:** what to check, how, and what counts as a problem. Ten to start with:
|
|
287
|
+
|
|
288
|
+
<!-- prettier-ignore -->
|
|
289
|
+
| Audit | What it checks | For example |
|
|
290
|
+
| --- | --- | --- |
|
|
291
|
+
| **Testing** | Whether tests can fail, actually run, and cover what the product must and must never do | Tests that read the code as text instead of running it |
|
|
292
|
+
| **Duplication** | Rules and logic built more than once | A billing rule in eight copies that have drifted apart |
|
|
293
|
+
| **Security** | Sign-in, permissions, secrets, input checks, and protections the docs promise | A sign-in link that can send people to another website |
|
|
294
|
+
| **Red team** | Real attacks on a test copy of your app, never production, one request at a time | One signed-in user reading another user's data |
|
|
295
|
+
| **Reliability** | What happens when a service is slow, down or answers twice | A payment retried with no guard against charging twice |
|
|
296
|
+
| **Privacy** | Where personal data goes, how long it stays, and whether deletion works | A deleted account still sitting in the logs |
|
|
297
|
+
| **Dead code** | Code, settings and routes that look live but never run | A fix made in a file nothing calls |
|
|
298
|
+
| **LLM** | Every AI model call, and what stops it when the input is hostile | A pasted document that talks the model into calling a tool |
|
|
299
|
+
| **Accessibility** | What automated accessibility checks miss, against WCAG 2.2 AA | A form a screen reader can't get through |
|
|
300
|
+
| **Cost** | Vendor plans against what you actually use | A plan two tiers above your usage |
|
|
301
|
+
|
|
302
|
+
All 35, grouped by area, with what each one finds: [the full audit list](.bkit/pipeline.md#audits).
|
|
303
|
+
|
|
304
|
+
- **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.
|
|
305
|
+
- **Findings turn into work.** Hand the report to `/bkit-plan` and the fixes are planned, built, tested and shipped like any other feature.
|
|
306
|
+
|
|
307
|
+
<a id="templates"></a>
|
|
308
|
+
|
|
309
|
+
## Templates ready to adopt
|
|
310
|
+
|
|
311
|
+
**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.
|
|
312
|
+
|
|
313
|
+
The ones that matter most, in the order to adopt them:
|
|
314
|
+
|
|
315
|
+
<!-- prettier-ignore -->
|
|
316
|
+
| Template | What it's for |
|
|
317
|
+
| --- | --- |
|
|
318
|
+
| **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. |
|
|
319
|
+
| **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)). |
|
|
320
|
+
| **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. |
|
|
321
|
+
| **Cloud agents** | When CI finishes, a cloud agent picks up: ship on green, debug on red. No laptop needed. |
|
|
322
|
+
| **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. |
|
|
323
|
+
| **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". |
|
|
324
|
+
| **graphify** | Draws your code as a map (`docs/capabilities.md`), so agents check what already exists before building it again. The map marks likely problems in red, and the check fails when the map falls behind the code ([bkit's own map below](#code-map)). |
|
|
325
|
+
| **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. |
|
|
326
|
+
| **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. |
|
|
327
|
+
| **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)). |
|
|
328
|
+
|
|
329
|
+
<a id="code-map"></a>
|
|
330
|
+
|
|
331
|
+
**See your code as a map, with likely problems marked in red.** This is the map graphify draws of bkit's own engine, and the same template draws yours. Each box is one part of the code, and parts that share a folder sit in one bigger box. An arrow means one part uses another; its number counts the links between them, and the more links, the thicker the arrow.
|
|
332
|
+
|
|
333
|
+
**A red dashed box is an open finding:** a part where graphify found a likely problem. Some code may skip the module that owns a job, two copies of one job may compete, a job may have no owner yet, or a call may go to an API route that nothing serves. Each kind has its own dash pattern. The box counts its findings, and [`docs/capabilities.md`](docs/capabilities.md) names each one. An amber box is one somebody has looked at and accepted, and the check fails if the number of exceptions changes. The map is generated: `pnpm bkit:graph:refresh` redraws it from the code, and the check fails if this copy falls behind. The full map, one level down, is in [`docs/capabilities.md`](docs/capabilities.md).
|
|
334
|
+
|
|
335
|
+
<!-- graph:packages:start -->
|
|
336
|
+
|
|
337
|
+
```mermaid
|
|
338
|
+
---
|
|
339
|
+
config:
|
|
340
|
+
layout: elk
|
|
341
|
+
themeCSS: "marker { overflow: visible; } marker path { transform: scale(1.8); transform-origin: 5px 5px; }"
|
|
342
|
+
flowchart:
|
|
343
|
+
useMaxWidth: false
|
|
344
|
+
---
|
|
345
|
+
flowchart LR
|
|
346
|
+
%% Generated by bkit-graphify-rollup.py — do not edit
|
|
347
|
+
subgraph gn_bkit_core_engine[".bkit/core/engine"]
|
|
348
|
+
n_bkit_core_engine_checks["checks<br/>265 symbols · 18 files"]
|
|
349
|
+
n_bkit_core_engine_cli["cli<br/>33 symbols · 1 files"]
|
|
350
|
+
n_bkit_core_engine_commands["commands<br/>1955 symbols · 57 files"]
|
|
351
|
+
n_bkit_core_engine_install["install<br/>366 symbols · 21 files"]
|
|
352
|
+
n_bkit_core_engine_ledgers["ledgers<br/>240 symbols · 6 files"]
|
|
353
|
+
n_bkit_core_engine_render["render<br/>63 symbols · 4 files"]
|
|
354
|
+
n_bkit_core_engine_shared["shared<br/>157 symbols · 13 files<br/>1 open finding"]
|
|
355
|
+
end
|
|
356
|
+
nscripts_harvest["scripts/harvest<br/>199 symbols · 2 files"]
|
|
357
|
+
n_bkit_core_engine_commands -->|472| n_bkit_core_engine_ledgers
|
|
358
|
+
n_bkit_core_engine_commands -->|431| n_bkit_core_engine_shared
|
|
359
|
+
n_bkit_core_engine_commands -->|219| n_bkit_core_engine_install
|
|
360
|
+
n_bkit_core_engine_install -->|187| n_bkit_core_engine_shared
|
|
361
|
+
n_bkit_core_engine_checks -->|147| n_bkit_core_engine_shared
|
|
362
|
+
n_bkit_core_engine_commands -->|89| n_bkit_core_engine_checks
|
|
363
|
+
n_bkit_core_engine_checks -->|83| n_bkit_core_engine_install
|
|
364
|
+
n_bkit_core_engine_install -->|64| n_bkit_core_engine_render
|
|
365
|
+
n_bkit_core_engine_commands -->|42| n_bkit_core_engine_render
|
|
366
|
+
n_bkit_core_engine_cli -->|35| n_bkit_core_engine_commands
|
|
367
|
+
n_bkit_core_engine_ledgers -->|19| n_bkit_core_engine_shared
|
|
368
|
+
n_bkit_core_engine_checks -->|18| n_bkit_core_engine_commands
|
|
369
|
+
n_bkit_core_engine_install -->|17| n_bkit_core_engine_checks
|
|
370
|
+
n_bkit_core_engine_shared -->|16| n_bkit_core_engine_install
|
|
371
|
+
n_bkit_core_engine_commands -->|15| n_bkit_core_engine_cli
|
|
372
|
+
nscripts_harvest -->|14| n_bkit_core_engine_ledgers
|
|
373
|
+
n_bkit_core_engine_checks -->|12| n_bkit_core_engine_cli
|
|
374
|
+
n_bkit_core_engine_render -->|12| n_bkit_core_engine_shared
|
|
375
|
+
n_bkit_core_engine_checks -->|11| n_bkit_core_engine_ledgers
|
|
376
|
+
n_bkit_core_engine_install -->|11| n_bkit_core_engine_ledgers
|
|
377
|
+
n_bkit_core_engine_install -->|10| n_bkit_core_engine_cli
|
|
378
|
+
n_bkit_core_engine_cli -->|7| n_bkit_core_engine_install
|
|
379
|
+
n_bkit_core_engine_render -->|7| n_bkit_core_engine_install
|
|
380
|
+
n_bkit_core_engine_checks -->|6| n_bkit_core_engine_render
|
|
381
|
+
n_bkit_core_engine_cli -->|6| n_bkit_core_engine_shared
|
|
382
|
+
style gn_bkit_core_engine fill:#59636e0a,stroke:#59636e,stroke-width:2px
|
|
383
|
+
style n_bkit_core_engine_checks stroke:#1a7f37,stroke-width:2px,fill:#1a7f3714
|
|
384
|
+
style n_bkit_core_engine_cli stroke:#8250df,stroke-width:2px,fill:#8250df14
|
|
385
|
+
style n_bkit_core_engine_commands stroke:#0969da,stroke-width:2px,fill:#0969da14
|
|
386
|
+
style n_bkit_core_engine_install stroke:#0a7b83,stroke-width:2px,fill:#0a7b8314
|
|
387
|
+
style n_bkit_core_engine_ledgers stroke:#1a7f37,stroke-width:2px,fill:#1a7f3714
|
|
388
|
+
style n_bkit_core_engine_render stroke:#0a7b83,stroke-width:2px,fill:#0a7b8314
|
|
389
|
+
style n_bkit_core_engine_shared stroke:#cf222e,stroke-width:4px,stroke-dasharray:8 4,fill:#cf222e26
|
|
390
|
+
style nscripts_harvest stroke:#8250df,stroke-width:2px,fill:#8250df14
|
|
391
|
+
linkStyle 0 stroke:#59636e,stroke-width:6px
|
|
392
|
+
linkStyle 1 stroke:#59636e,stroke-width:6px
|
|
393
|
+
linkStyle 2 stroke:#59636e,stroke-width:6px
|
|
394
|
+
linkStyle 3 stroke:#59636e,stroke-width:6px
|
|
395
|
+
linkStyle 4 stroke:#59636e,stroke-width:6px
|
|
396
|
+
linkStyle 5 stroke:#59636e,stroke-width:6px
|
|
397
|
+
linkStyle 6 stroke:#59636e,stroke-width:6px
|
|
398
|
+
linkStyle 7 stroke:#59636e,stroke-width:6px
|
|
399
|
+
linkStyle 8 stroke:#59636e,stroke-width:6px
|
|
400
|
+
linkStyle 9 stroke:#59636eb3,stroke-width:3px
|
|
401
|
+
linkStyle 10 stroke:#59636eb3,stroke-width:3px
|
|
402
|
+
linkStyle 11 stroke:#59636eb3,stroke-width:3px
|
|
403
|
+
linkStyle 12 stroke:#59636eb3,stroke-width:3px
|
|
404
|
+
linkStyle 13 stroke:#59636eb3,stroke-width:3px
|
|
405
|
+
linkStyle 14 stroke:#59636eb3,stroke-width:3px
|
|
406
|
+
linkStyle 15 stroke:#59636eb3,stroke-width:3px
|
|
407
|
+
linkStyle 16 stroke:#59636eb3,stroke-width:3px
|
|
408
|
+
linkStyle 17 stroke:#59636eb3,stroke-width:3px
|
|
409
|
+
linkStyle 18 stroke:#59636e80,stroke-width:2px
|
|
410
|
+
linkStyle 19 stroke:#59636e80,stroke-width:2px
|
|
411
|
+
linkStyle 20 stroke:#59636e80,stroke-width:2px
|
|
412
|
+
linkStyle 21 stroke:#59636e80,stroke-width:2px
|
|
413
|
+
linkStyle 22 stroke:#59636e80,stroke-width:2px
|
|
414
|
+
linkStyle 23 stroke:#59636e80,stroke-width:2px
|
|
415
|
+
linkStyle 24 stroke:#59636e80,stroke-width:2px
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
<!-- graph:packages:end -->
|
|
419
|
+
|
|
420
|
+
All templates, what each is for, and how to install them: [`.bkit/templates.md`](.bkit/templates.md).
|
|
421
|
+
|
|
422
|
+
## What else you get
|
|
423
|
+
|
|
424
|
+
### Engineering know-how, built in
|
|
425
|
+
|
|
426
|
+
- **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, faster ones for writing code and docs. Starting a session on a cheaper model never quietly downgrades the reviewers. [Which model does each job](#models).
|
|
427
|
+
- **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.
|
|
428
|
+
- **Big features are built a group at a time.** The plan's tasks are grouped by the code they share. Each group gets a fresh agent and a short brief from `bkit`, never the whole plan, and an independent check of just that group's changes before the next group starts. [The engine](#engine).
|
|
429
|
+
- **The right expertise for each feature, added and removed for you.** Before build writes code, an agent works out which tools the plan needs (say Stripe or Supabase) and installs one matching skill (a packaged set of instructions for that tool) from [skills.sh](https://skills.sh) for each one not already covered. It only takes a skill from the official publisher, or one with 1,000+ installs and 100+ stars on its repo. It never runs scripts a skill brings along. When the feature ships, bkit removes every skill not listed in `.agents/skills.md`, so add one there to keep it. Put `[skills=false]` in the issue to skip it.
|
|
430
|
+
- **Numbers on your own work.** Every run records its time, size of change, retries and the tokens each agent read in `.bkit/stats.jsonl`, and posts them to the issue next to the median of your last five runs.
|
|
431
|
+
|
|
432
|
+
### It fits how you work
|
|
433
|
+
|
|
434
|
+
- **Never blocked by usage limits.** Out of Claude for the week? Carry on in Codex, Antigravity or Cursor, 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).
|
|
435
|
+
- **Start on your laptop, check in from your phone.** A feature started at your desk can continue in a cloud session (Claude 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).
|
|
436
|
+
- **Run several features at once.** Each works in its own copy of the repo (a git worktree), so they never trip over each other.
|
|
437
|
+
|
|
438
|
+
### Your tracker is the control panel
|
|
439
|
+
|
|
440
|
+
- **Every run lives on the tracker issue.** bkit reads the tracker issue (e.g. GitHub, Linear, Jira), posts progress as it goes, moves the issue along and links the pull request.
|
|
441
|
+
- **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.
|
|
442
|
+
- **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`.
|
|
443
|
+
- **It keeps the tracker tidy.** `@bkit-utility-update-tracker` brings open issues in line with the tracker rules: short titles, the right labels, board status, priority, size, milestone, parent and blocked-by links. It takes priorities from the latest issue prioritisation audit and suggests new milestones and parent issues, but never creates or closes an issue.
|
|
444
|
+
- **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).
|
|
445
|
+
|
|
446
|
+
### You stay in control
|
|
447
|
+
|
|
448
|
+
- **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").
|
|
449
|
+
- **Three sign-offs, and production stays yours.** The 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.
|
|
450
|
+
- **A fix that doesn't work comes back to you.** After one automatic fix round, build asks before trying again, with a report: problems per round, code changed, and whether it's closing in, stuck or getting worse. Each place a run can ask has its own setting under `bkit.workflows` in `package.json`: whether to ask, and a hard limit (2 attempts by default) that no answer can raise.
|
|
451
|
+
- **Questions don't stall the build.** When build needs your decision, it keeps working on the tasks the question doesn't touch. With nobody at the keyboard, it goes ahead on its own recommendation, marks it as assumed, and won't merge until you confirm it.
|
|
452
|
+
- **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).
|
|
453
|
+
|
|
454
|
+
<a id="token-costs"></a>
|
|
455
|
+
|
|
456
|
+
## Spending fewer tokens
|
|
457
|
+
|
|
458
|
+
<p align="center">
|
|
459
|
+
<picture>
|
|
460
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-reread-dark.svg">
|
|
461
|
+
<img alt="Most of what a coding agent reads is the conversation re-sent on every request, not tool output. bkit hands over to a fresh agent with a short brief instead of letting one agent’s context grow." src=".github/assets/bkit-reread-light.svg" width="100%">
|
|
462
|
+
</picture>
|
|
463
|
+
</p>
|
|
464
|
+
|
|
465
|
+
**Most of what a session costs is the model re-reading, not writing code.** On every request, Claude sends the system prompt, rules, tool list and the whole conversation so far, and the model reads all of it again. Across 13.5M GitHub Copilot agent sessions, the conversation so far was 48% of what the model read on each request, tool output 28%, the system prompt 14% and instructions and other context 10%. The model read more than 275 tokens for every 1 it wrote ([Liu et al.](https://arxiv.org/abs/2608.00101); [Manus](https://manus.im/en/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) reports about 100 to 1). Most of that reading comes from the cache, and cache reads are the largest part of an agent's bill ([Bai et al.](https://arxiv.org/abs/2604.22750)).
|
|
466
|
+
|
|
467
|
+
**That makes an agent's cost grow with how long it runs.** Each request re-sends everything so far. A token costs the same at 900k as at 9k ([Anthropic pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing)), but a turn at 900k sends 100 times as many, so every turn costs more than the last. Left alone, an agent keeps going until about 967k, where Claude summarises it and drops detail ([model configuration](https://code.claude.com/docs/en/model-config)). Quality slips long before that: every model in [Chroma's context-rot study](https://www.trychroma.com/research/context-rot) got worse as its input grew, and in [NoLiMa](https://arxiv.org/abs/2502.05167) most models fell below half their short-input score by 32k. Practitioners advise starting fresh at around 40–60% of a 200k window ([HumanLayer](https://humanlayer.dev/blog/advanced-context-engineering)), and Anthropic's own sub-agents hand back 1–2k tokens from tens of thousands they read ([Anthropic](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)). bkit does that: a fresh agent with a short brief takes over by about 160k, so no agent carries a long history. Most of what an agent reads is cheap cache reads, so the dollar saving is smaller than the token saving.
|
|
468
|
+
|
|
469
|
+
**Measure it on your own work.** bkit keeps run statistics in your repo, ready to review and compare. [What we measure and how to share your results](#measurements).
|
|
470
|
+
|
|
471
|
+
**Why bkit doesn't use compression tools.** They shorten the output of commands and file reads before the model sees it. That's only part of what an agent reads, and most of it is code the agent needs word for word, so there's little a tool can safely cut. The re-reading of everything else stays. An independent test of 2,848 Claude runs found the same: RTK cut the whole bill by 2.7%, and Headroom raised it by 48% ([Weinberger & Hozez](https://arxiv.org/abs/2607.12161)). In our tests, the tools that saved most did it by changing what the agent reads: one made an agent answer a question wrongly; another rewrote code.
|
|
472
|
+
|
|
473
|
+
**The three tools, how we measured, and why the risks outweigh the saving.**
|
|
474
|
+
|
|
475
|
+
<p align="center">
|
|
476
|
+
<picture>
|
|
477
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-tokens-dark.svg">
|
|
478
|
+
<img alt="Across more than 400 bkit transcripts, compression tools could touch only the tool-output share of the bill and saved 1 to 3 percent, at the risk of wrong answers and broken code." src=".github/assets/bkit-tokens-light.svg" width="100%">
|
|
479
|
+
</picture>
|
|
480
|
+
</p>
|
|
481
|
+
|
|
482
|
+
<!-- prettier-ignore -->
|
|
483
|
+
| Tool | How it works | Share of the bill saved | What went wrong |
|
|
484
|
+
| --- | --- | --- | --- |
|
|
485
|
+
| [caveman](https://www.npmjs.com/package/@caveman-ai/cli) | Sits between Claude and the model and shortens tool output | 1.3% | An agent answered a question wrongly from a compressed log |
|
|
486
|
+
| [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` |
|
|
487
|
+
| [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 |
|
|
488
|
+
|
|
489
|
+
**How we measured.** The cost split above comes from more than 400 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/experiments/compression/reports/bkit-caveman-headroom-compression-proxy-comparison.md). Your sessions may differ: run the scripts on your own transcripts before you choose.
|
|
490
|
+
|
|
491
|
+
**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.
|
|
492
|
+
|
|
493
|
+
**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. Most of that comes from how a run is split: plain code keeps the books and each agent gets only its part ([the engine](#engine)).
|
|
494
|
+
|
|
495
|
+
- **Fresh agents with short briefs.** `bkit context brief` cuts each group's part out of the plan, a few KB, and a new agent builds from that. No build agent sees the whole plan or runs past about 160k tokens: it hands over to a fresh one.
|
|
496
|
+
- **Code does the bookkeeping.** Anything with one right answer comes from a `bkit` command, not a model turn: ledger rows, whether a test failed before its code was written, run summaries, where a stopped run resumes, how many fix rounds a step has had. That saves the turns, and code gives the same answer every time, on every tool and every model.
|
|
497
|
+
- **Fewer rounds.** One plan review round, with two reviewers and a scope check side by side. One automatic fix round, then you decide. On a small change, build runs only the security reviewer.
|
|
498
|
+
- **Each agent carries only its own rules.** bkit's rules sit in the prompts of the agents that act on them, and plans hold tasks, not pages of instructions.
|
|
499
|
+
- **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.
|
|
500
|
+
- **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.
|
|
501
|
+
- **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.
|
|
502
|
+
- **Bound outside evidence before it's downloaded.** Debug's connectors ask each source for the window, severity and fields they need, tail-bound the logs of each failed job, and page no further than a cap. Records are projected with `jq` to a PII-safe subset of fields, a JSON list is written as a table that repeats no key per row, and anything over 3,000 lines is trimmed to its head, tail and error lines — with a line in the file saying so.
|
|
503
|
+
- **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.
|
|
504
|
+
- **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.
|
|
505
|
+
- **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.
|
|
506
|
+
- **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.
|
|
507
|
+
|
|
508
|
+
**What [`bkit tips`](.bkit/README.md#ongoing-cli) suggests for your repo:**
|
|
509
|
+
|
|
510
|
+
- **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.
|
|
511
|
+
- **Switch off claude.ai connectors** (MCP servers from your claude.ai account) in Claude for this project: `"disableClaudeAiConnectors": true` in `.claude/settings.json`. Otherwise their tool lists are re-sent with every request, used or not.
|
|
512
|
+
- **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.
|
|
513
|
+
- **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 for your main session bkit suggests this rather than setting it. bkit's own Claude subagents already summarise at 300,000 tokens at the latest.
|
|
514
|
+
|
|
515
|
+
<a id="measurements"></a>
|
|
516
|
+
|
|
517
|
+
### Measurements: v6/6.1 versus v5.x
|
|
518
|
+
|
|
519
|
+
**Median tokens for [/bkit-plan](.bkit/core/workflows/bkit-plan.md) and [/bkit-build](.bkit/core/workflows/bkit-build.md) workflow chats fell by roughly half in our latest measurements.** These measurements cover v6 and the development towards v6.1, compared with the last measured v5.x workflows.
|
|
520
|
+
|
|
521
|
+
<p align="center">
|
|
522
|
+
<picture>
|
|
523
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-stats-dark.svg">
|
|
524
|
+
<img alt="v6/6.1 versus v5.x: approximate median tokens for /bkit-plan workflow chats fell from 129M to 62M, a 50–55% reduction; for /bkit-build, from 201M to 104M, a 45–50% reduction. Small sample size; see Stats review #845 for details." src=".github/assets/bkit-stats-light.svg" width="100%">
|
|
525
|
+
</picture>
|
|
526
|
+
</p>
|
|
527
|
+
|
|
528
|
+
**Small sample size.** M means million tokens read per workflow chat, including subagents and incomplete attempts. Tasks, hosts and models differ. See [#845 — Stats review](https://github.com/cbartens/bkit/issues/845#issuecomment-6602753865) for the method, sample sizes and trade-offs.
|
|
529
|
+
|
|
530
|
+
**See where your runs spend time and effort.** Your local report shows run durations, change sizes, agent context peaks where available, rule compliance and workflow problems. Our [deeper local analysis](docs/observability.md#harvest--every-repo-every-chat-bkit-repo-only) adds token use, completion, repeated work and owner waits. It is separate from the report installed in your project.
|
|
531
|
+
|
|
532
|
+
**Your stats stay under your control.** bkit does not automatically upload stats or transcripts to us, and we do not remotely monitor your usage. Reports stay in your repository and follow its access settings.
|
|
533
|
+
|
|
534
|
+
**Help us grow the sample.** Voluntarily [share a cleaned summary](https://github.com/cbartens/bkit/issues/new) so we can test these improvements across more projects, hosts and models. Good results and problems are equally useful. [Report and sharing instructions](.bkit/README.md#share-friction-with-bkit) explain how to review your stats and approve exactly what you share.
|
|
535
|
+
|
|
536
|
+
## FAQ
|
|
537
|
+
|
|
538
|
+
**Do I need to know how to code?**
|
|
539
|
+
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.
|
|
540
|
+
|
|
541
|
+
**Who is it for?**
|
|
542
|
+
People maintaining a project across many changes: solo makers who want a defined engineering process and engineers who want one ready to adopt. A quick script or disposable experiment may need only a single chat.
|
|
543
|
+
|
|
544
|
+
**Does it work on an existing project?**
|
|
545
|
+
Yes, in any language. bkit installs as an npm package, so the repo gets a `package.json` if it hasn't one ([not a JavaScript project?](#quick-start)). 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.
|
|
546
|
+
|
|
547
|
+
**What does install change, and can I remove it?**
|
|
548
|
+
Yes. `bkit uninstall` removes bkit's managed files and blocks while preserving your own edits and copied templates. Review [what install writes](.bkit/README.md#what-install-writes) and the [uninstall guide](.bkit/install.md#uninstall).
|
|
549
|
+
|
|
550
|
+
**What does it cost?**
|
|
551
|
+
bkit is free. Your AI subscription or provider pays for the agents; multiple reviewers use more quota than one chat. See [model choices](#models), [how bkit reduces token costs](#token-costs) and [our measurements and their limits](#measurements).
|
|
552
|
+
|
|
553
|
+
bkit is open source under the MIT licence, commercial use included. It runs on AI subscriptions you already have (Claude, Codex through ChatGPT, Antigravity, Cursor), on Antigravity's free tier, or with your own key on pay-as-you-go providers through OpenCode (OpenRouter, Ollama or the OpenCode gateways).
|
|
554
|
+
|
|
555
|
+
**Isn't a good model enough?**
|
|
556
|
+
No. A model writes each answer by predicting the next word from what it was given, and it doesn't check its own work, so a fluent answer can still be wrong. bkit gives every agent your project's rules, docs and past decisions, then checks the result with reviewers, tests and CI. The [21-slide primer](.github/assets/bkit-how-ai-llms-produce-answers.pdf) explains it step by step.
|
|
557
|
+
|
|
558
|
+
**How long does a feature take?**
|
|
559
|
+
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.
|
|
560
|
+
|
|
561
|
+
**Who controls the work and production?**
|
|
562
|
+
You review designs and plans, and production promotion remains your decision. Features use separate working copies of the repository. bkit merges into `dev`; promotion to `main` is a separate decision. Adopt the CI pipeline to check changes before merge. Optional cloud automation can continue after CI for issues labelled `bkit:auto`.
|
|
563
|
+
|
|
564
|
+
**Which issue tracker, and which code host?**
|
|
565
|
+
GitHub Issues, Linear or Jira for the tracker. The code has to live on GitHub: pull requests, CI and cloud mode run there.
|
|
566
|
+
|
|
567
|
+
**Is this the bkit Vibecoding Kit?**
|
|
568
|
+
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).
|
|
569
|
+
|
|
570
|
+
**How does it compare with other tools?**
|
|
571
|
+
Feature by feature against the main AI development frameworks, from spec toolkits to autonomous agents: [`.bkit/comparison.md`](.bkit/comparison.md#frameworks).
|
|
572
|
+
|
|
573
|
+
**Why doesn't bkit use a compression tool like caveman, Headroom or RTK?**
|
|
574
|
+
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 the re-reading instead, with shorter agents, short briefs and code doing the bookkeeping, which loses nothing. Numbers, risks and what bkit does instead: [Spending fewer tokens](#token-costs).
|
|
575
|
+
|
|
576
|
+
<details>
|
|
577
|
+
<summary><strong>For engineers: what's under the hood</strong></summary>
|
|
578
|
+
|
|
579
|
+
- **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.
|
|
580
|
+
- **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; `bkit` works out which step from `status.jsonl`, so no prompt describes the rule.
|
|
581
|
+
- **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, and checks test-first order before the next task group starts; ship's deferred sweep fails the merge on an unplanned gap.
|
|
582
|
+
- **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. **Facts are code, judgement is the model:** anything with one right answer (ledger rows, briefs, summaries, resume points, fix-round limits, run stats) is a `bkit <noun> <verb>` command, so the workflow prompts hold only the decisions ([picture](#engine)).
|
|
583
|
+
- **One source, every host.** `.bkit/` renders `.claude/`, `.codex/`, `.agents/` (Antigravity), `.cursor/` and `.opencode/`. `bkit check` is the CI drift gate.
|
|
584
|
+
- **Reviewer independence.** Parallel reviewers can't read sibling output. Design brainstorm and design review groups also cross models (Opus + Sonnet on Claude; Grok + Composer on Cursor); depth-sensitive lenses (plan review, build challenge) stay on the top tier.
|
|
585
|
+
- **Per-agent pins.** Model and effort per agent, per provider ([`.bkit/prompts.md`](.bkit/prompts.md) § Models), immune to the session default.
|
|
586
|
+
- **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).
|
|
587
|
+
|
|
588
|
+
</details>
|
|
589
|
+
|
|
590
|
+
## Documentation
|
|
591
|
+
|
|
592
|
+
<!-- prettier-ignore -->
|
|
593
|
+
| Read | For |
|
|
594
|
+
| --- | --- |
|
|
595
|
+
| [`.bkit/install.md`](.bkit/install.md) | Install, upgrade, CI auth, uninstall, recovery |
|
|
596
|
+
| [`.bkit/README.md`](.bkit/README.md) | Day-to-day use: running workflows, environment, tracker setup, CLI |
|
|
597
|
+
| [`.bkit/workflows.md`](.bkit/workflows.md) | Every workflow step, verdict and contract |
|
|
598
|
+
| [`.bkit/providers.md`](.bkit/providers.md) | Tool and provider differences, guardrails, model pins |
|
|
599
|
+
| [`.bkit/cloud.md`](.bkit/cloud.md) | Cloud agents: Claude on the web, Cursor, OpenCode |
|
|
600
|
+
| [`.bkit/templates.md`](.bkit/templates.md) | Templates ready to adopt |
|
|
601
|
+
| [`.bkit/pipeline.md`](.bkit/pipeline.md) | Every agent in the order it runs, the CI scaffold, every audit template |
|
|
602
|
+
| [`.bkit/authoring.md`](.bkit/authoring.md) | Rules for writing docs, prompts and workflows, matched against Anthropic's, OpenAI's and Google's prompting guides |
|
|
603
|
+
| [`.bkit/comparison.md`](.bkit/comparison.md) | Comparison with other AI development frameworks and with _Agentic Design Patterns_ |
|
|
604
|
+
| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
|
|
605
|
+
|
|
606
|
+
<a id="quick-start"></a>
|
|
607
|
+
|
|
608
|
+
## Quick start
|
|
609
|
+
|
|
610
|
+
You need a GitHub repository, **Node 24+**, **pnpm**, and one of the supported AI coding tools.
|
|
611
|
+
|
|
612
|
+
**Let your agent set it up:** paste the [install prompt](.bkit/install.md#install--first-time) into your coding tool. It walks through installation and the optional templates that fit your project.
|
|
613
|
+
|
|
614
|
+
Or install by hand:
|
|
615
|
+
|
|
616
|
+
```bash
|
|
617
|
+
pnpm add -D @cbartens/bkit
|
|
618
|
+
pnpm bkit install --claude
|
|
619
|
+
pnpm bkit check
|
|
620
|
+
pnpm bkit tips
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
Replace `--claude` with `--codex`, `--antigravity`, `--cursor` or `--opencode=<provider>`. You can install for more than one tool. See the [installation guide](.bkit/install.md) for providers and setup options.
|
|
624
|
+
|
|
625
|
+
OpenCode providers: `openrouter`, `ollama`, `opencode-zen` or `opencode-go`.
|
|
626
|
+
|
|
627
|
+
`pnpm bkit check` verifies installed files against the pinned version. `pnpm bkit tips` lists setup recommendations, most useful first.
|
|
628
|
+
|
|
629
|
+
Adopt the [optional templates](.bkit/templates.md) that fit your project, open an issue describing what you want, then run this in your AI coding tool:
|
|
630
|
+
|
|
631
|
+
```text
|
|
632
|
+
/bkit-design issue #123
|
|
633
|
+
```
|
|
634
|
+
|
|
635
|
+
Already know what to build? Start with `/bkit-plan`. Fixing something broken? Use `/bkit-debug`; add `[repro]` if nothing fails yet, and it writes the failing test first.
|
|
636
|
+
|
|
637
|
+
**Any language, existing or new projects.** bkit installs through npm, but your application does not have to use JavaScript. Installation adds a `package.json` if needed. Connect the `bkit:gate:*` scripts to your own lint, build and test commands, such as `ruff check && pytest` or `go test ./...`. [Setup requirements →](.bkit/README.md#required-tools)
|
|
638
|
+
|
|
639
|
+
[Full installation and upgrades →](.bkit/install.md) · [Tracker and environment setup →](.bkit/README.md#prerequisites)
|
|
640
|
+
|
|
641
|
+
## Credits
|
|
642
|
+
|
|
643
|
+
bkit's process was worked out over months of building real products with it. These projects sharpened specific ideas along the way:
|
|
644
|
+
|
|
645
|
+
<!-- prettier-ignore -->
|
|
646
|
+
| Project | Idea bkit took |
|
|
647
|
+
| --- | --- |
|
|
648
|
+
| [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. |
|
|
649
|
+
| [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. |
|
|
650
|
+
| _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). |
|
|
651
|
+
| [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. |
|
|
652
|
+
|
|
653
|
+
**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), [direnv](https://github.com/direnv/direnv) and the [skills](https://github.com/vercel-labs/skills) CLI behind [skills.sh](https://skills.sh).
|
|
654
|
+
|
|
655
|
+
## License
|
|
656
|
+
|
|
657
|
+
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.
|
|
658
|
+
|
|
659
|
+
**The code bkit's agents write for you is yours.** The licence covers bkit itself, not what its agents produce in your repo.
|
|
660
|
+
|
|
661
|
+
The full text travels in your repo at [`.bkit/LICENSE.md`](.bkit/LICENSE.md) after install.
|