@cbartens/bkit 5.1.0 → 5.2.1
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 +11 -7
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
- package/.bkit/core/.agents/rules.md +8 -4
- package/.bkit/core/.agents/shortcuts.md +1 -1
- package/.bkit/core/.bkit/LICENSE.md +18 -140
- package/.bkit/core/.bkit/README.md +10 -6
- package/.bkit/core/.bkit/cloud.md +12 -15
- package/.bkit/core/.bkit/comparison.md +66 -14
- package/.bkit/core/.bkit/install.md +31 -8
- package/.bkit/core/.bkit/jsonl.md +0 -1
- package/.bkit/core/.bkit/prompts.md +14 -13
- package/.bkit/core/.bkit/providers.md +92 -26
- package/.bkit/core/.bkit/templates.md +38 -11
- package/.bkit/core/.bkit/workflows.md +63 -41
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
- package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
- package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
- package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
- package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
- package/.bkit/core/docs/templates/bkit-plan.md +6 -3
- package/.bkit/core/engine/checks/after/auth.ts +32 -0
- package/.bkit/core/engine/checks/after/github.ts +4 -4
- package/.bkit/core/engine/checks/after/index.ts +36 -50
- package/.bkit/core/engine/checks/after/managed.ts +40 -0
- package/.bkit/core/engine/checks/before/index.ts +5 -4
- package/.bkit/core/engine/checks/before/mcp.ts +60 -54
- package/.bkit/core/engine/checks/status-holes.ts +1 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
- package/.bkit/core/engine/checks/tips/detect.ts +144 -0
- package/.bkit/core/engine/checks/tips/index.ts +174 -0
- package/.bkit/core/engine/cli.ts +57 -9
- package/.bkit/core/engine/commands/install/doctor.ts +5 -1
- package/.bkit/core/engine/commands/install/install.ts +39 -9
- package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
- package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
- package/.bkit/core/engine/commands/launch.ts +33 -11
- package/.bkit/core/engine/commands/tips.ts +16 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
- package/.bkit/core/engine/commands/workflow/runtime.ts +10 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
- package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
- package/.bkit/core/engine/install/cloud-env.ts +7 -21
- package/.bkit/core/engine/install/hosts.ts +21 -0
- package/.bkit/core/engine/install/managed-block.ts +36 -0
- package/.bkit/core/engine/install/manifest.ts +46 -4
- package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
- package/.bkit/core/engine/install/modules/claude.ts +6 -6
- package/.bkit/core/engine/install/modules/cloud.ts +2 -2
- package/.bkit/core/engine/install/modules/codex.ts +5 -5
- package/.bkit/core/engine/install/modules/core.ts +23 -9
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +4 -4
- package/.bkit/core/engine/install/payload-links.ts +6 -10
- package/.bkit/core/engine/install/placeholders.ts +1 -1
- package/.bkit/core/engine/install/version-file.ts +17 -9
- package/.bkit/core/engine/install/write.ts +68 -1
- package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
- package/.bkit/core/engine/shared/package-roots.ts +8 -10
- package/.bkit/core/hooks/antigravity-hook.js +67 -0
- package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
- package/.bkit/core/hooks/gateguard-engine.js +16 -6
- package/.bkit/core/hooks/guardrails-read.js +23 -0
- package/.bkit/core/hooks/readguard-engine.js +259 -0
- package/.bkit/core/hooks/readguard-payload.js +67 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
- package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
- package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
- package/.bkit/core/prompts/bkit-build-summary.md +1 -0
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
- package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
- package/.bkit/core/prompts/bkit-design-generate.md +9 -4
- package/.bkit/core/prompts/bkit-design-organise.md +1 -0
- package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
- package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
- package/.bkit/core/prompts/bkit-design-spike.md +1 -0
- package/.bkit/core/prompts/bkit-design-summary.md +1 -0
- package/.bkit/core/prompts/bkit-design-update.md +1 -0
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
- package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
- package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
- package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
- package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
- package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
- package/.bkit/core/prompts/bkit-plan-update.md +2 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
- package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
- package/.bkit/core/workflows/bkit-build.md +33 -21
- package/.bkit/core/workflows/bkit-debug.md +29 -22
- package/.bkit/core/workflows/bkit-design.md +81 -38
- package/.bkit/core/workflows/bkit-plan.md +8 -2
- package/.bkit/core/workflows/bkit-ship.md +8 -2
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.codex/hooks.json +21 -0
- package/.bkit/shared/.cursor/hooks.json +6 -1
- package/.bkit/shared/.opencode/opencode.json +1 -1
- package/.bkit/shared/docs/deployments.md +1 -1
- package/.bkit/shared/docs/testing.md +12 -1
- package/.bkit/templates/.github/dependabot.yml +6 -0
- package/.bkit/templates/.github/renovate.json5 +3 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
- package/.bkit/templates/.prettierignore +1 -1
- package/.bkit/templates/context/bkit-expo.md +22 -13
- package/.bkit/templates/context/bkit-github.md +20 -6
- package/.bkit/templates/context/bkit-inngest.md +10 -4
- package/.bkit/templates/context/bkit-maestro.md +5 -5
- package/.bkit/templates/context/bkit-playwright.md +3 -3
- package/.bkit/templates/context/bkit-sentry.md +6 -5
- package/.bkit/templates/context/bkit-stripe.md +31 -8
- package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
- package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
- package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
- package/.bkit/templates/slop-scan.config.json +7 -2
- package/CHANGELOG.md +50 -0
- package/LICENSE.md +21 -161
- package/README.md +61 -28
- package/dist/checks/after/auth.js +28 -0
- package/dist/checks/after/github.js +4 -4
- package/dist/checks/after/index.js +29 -45
- package/dist/checks/after/managed.js +40 -1
- package/dist/checks/before/index.js +5 -4
- package/dist/checks/before/mcp.js +53 -53
- package/dist/checks/status-holes.js +1 -1
- package/dist/checks/tips/catalogue.js +297 -0
- package/dist/checks/tips/detect.js +130 -0
- package/dist/checks/tips/index.js +146 -0
- package/dist/cli.js +47 -9
- package/dist/commands/install/doctor.js +5 -1
- package/dist/commands/install/install.js +27 -7
- package/dist/commands/install/uninstall.js +31 -16
- package/dist/commands/install/upgrade.js +15 -32
- package/dist/commands/launch.js +27 -11
- package/dist/commands/tips.js +10 -0
- package/dist/commands/workflow/runs.js +52 -16
- package/dist/commands/workflow/runtime.js +8 -0
- package/dist/commands/workflow/steps.js +1 -0
- package/dist/commands/workflow/tests.js +541 -4
- package/dist/commands/workflow/workstreams.js +4 -4
- package/dist/install/cloud-env.js +3 -14
- package/dist/install/hosts.js +22 -0
- package/dist/install/managed-block.js +36 -0
- package/dist/install/manifest.js +45 -4
- package/dist/install/modules/antigravity.js +8 -7
- package/dist/install/modules/claude.js +6 -6
- package/dist/install/modules/cloud.js +2 -2
- package/dist/install/modules/codex.js +5 -5
- package/dist/install/modules/core.js +14 -5
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +4 -4
- package/dist/install/payload-links.js +5 -5
- package/dist/install/placeholders.js +1 -1
- package/dist/install/version-file.js +12 -3
- package/dist/install/write.js +61 -2
- package/dist/shared/package-roots.js +8 -11
- package/package.json +4 -6
- package/.bkit/core/LICENSE.md +0 -149
- package/.bkit/shared/LICENSE.md +0 -22
- package/.bkit/templates/LICENSE.md +0 -22
|
@@ -24,7 +24,7 @@ Install the latest `@cbartens/bkit` in this repo and finish setup.
|
|
|
24
24
|
bkit install --claude --cursor
|
|
25
25
|
```
|
|
26
26
|
Writes `.agents/`, `.claude/`, `.cursor/` and the `bkit:gate:*` `package.json` scripts, and copies the templates (CI workflow, hooks, tool configs) into `.bkit/templates/` without applying them. `.bkit/templates.md` lists each template plus the tool scripts and devDeps the gates chain.
|
|
27
|
-
3. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why.
|
|
27
|
+
3. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why. Then § Setup tips: follow each tip's **Agent steps** unless the person declines it.
|
|
28
28
|
4. Read `.bkit/templates.md`, then compare each template in `.bkit/templates/` (CI workflows, git hooks, lint and Vale configs, Cursor config, dependency updaters, etc.) with this repo. bkit never applies templates, so adoption is your job: adopt unless adoption would break existing functionality. For any template not adopted, state which and why.
|
|
29
29
|
5. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
|
|
30
30
|
````
|
|
@@ -40,7 +40,7 @@ Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resyn
|
|
|
40
40
|
bkit upgrade --latest
|
|
41
41
|
```
|
|
42
42
|
Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
|
|
43
|
-
2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why.
|
|
43
|
+
2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why. Then § Setup tips: follow each tip's **Agent steps** unless the person declines it.
|
|
44
44
|
3. Read the template changes `bkit upgrade` printed (or `git diff .bkit/templates`), then `.bkit/templates.md`. bkit never applies templates, so adoption is your job: adopt each change unless it would break existing functionality. For any change not adopted, state which and why.
|
|
45
45
|
4. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
|
|
46
46
|
````
|
|
@@ -109,7 +109,7 @@ bkit check
|
|
|
109
109
|
|
|
110
110
|
Install and upgrade create two **relative symlinks** into the installed package, so the payload sources (workflows, prompts, hooks) are browsable in-repo: `.bkit/core` → `../node_modules/@cbartens/bkit/.bkit/core`, same shape for `shared`. Views, not copies — always the installed version, zero drift. Rules:
|
|
111
111
|
|
|
112
|
-
- Both paths sit in the `.gitignore` managed block — they dangle on a fresh clone or in CI (no `node_modules`); `bkit install` / `upgrade` recreates them.
|
|
112
|
+
- Both paths sit in the `.gitignore` managed block — they dangle on a fresh clone or in CI (no `node_modules`); `bkit install` / `upgrade` recreates them. A missing or mis-pointed link is never `bkit check` drift (links join no WriteSet).
|
|
113
113
|
- The `bkit` binary reads its payload from the package regardless; the links are browse-only. Editors resolve them to the `node_modules/…` paths.
|
|
114
114
|
- A real directory at either path is never clobbered (advisory `payload-link-real-dir`) — remove it yourself and re-run install to get the link. A platform that refuses symlinks (Windows without Developer Mode) falls back to a junction, then to advisory `payload-link-failed` — never a failure.
|
|
115
115
|
- `bkit uninstall` removes the links (symlinks only — consumer content stays).
|
|
@@ -222,6 +222,7 @@ After writes, bkit re-runs credential and environment checks — some only accur
|
|
|
222
222
|
<!-- prettier-ignore -->
|
|
223
223
|
| `id` | When |
|
|
224
224
|
| --- | --- |
|
|
225
|
+
| `bkit-managed-duplicate` | A managed markdown file holds an older unmarked copy of its block outside `bkit:start`/`bkit:end`: the block's `# ` title plus 10+ of its long lines verbatim, fenced code ignored. Install never updates that copy. Names each file and title line; delete the copy. |
|
|
225
226
|
| `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset/empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
|
|
226
227
|
| `tracker-setup-none` / `-github` / `-linear` | Optional post-install decision — which issue tracker is wired (`bkit.issueTracker`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
227
228
|
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.githubProject` absent and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.githubProject: false`. |
|
|
@@ -238,7 +239,7 @@ After writes, bkit re-runs credential and environment checks — some only accur
|
|
|
238
239
|
|
|
239
240
|
Phase 1 and Phase 3 findings merged and deduplicated by `id` (Phase 3 wins on conflict — re-detection more accurate post-write). Zero findings → no banner.
|
|
240
241
|
|
|
241
|
-
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only) — same advisory set as `bkit install` minus writes. Changes no managed file (regenerates `.bkit/advisories.md` artifact) and **exits 1 when any managed-file write would occur** in installed module — Tier-2 JSON deep-containment or markered-block drift, whole-file byte-equal mismatch, **host agent/command mirror content drift** (would-write / orphan delete), or when any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carries a stale managed-version marker (`bkit-managed-stale`). Gate covers the **installed** module set ({core, claude, cursor, codex} plus **opencode**, each detected by sentinel files). A missing `bkit:gate:*` name counts as a write. opencode gated: `.opencode/opencode.json` (provider block + tracker
|
|
242
|
+
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only) — same advisory set as `bkit install` minus writes. Changes no managed file (regenerates `.bkit/advisories.md` artifact) and **exits 1 when any managed-file write would occur** in installed module — Tier-2 JSON deep-containment or markered-block drift, whole-file byte-equal mismatch, **host agent/command mirror content drift** (would-write / orphan delete), or when any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carries a stale managed-version marker (`bkit-managed-stale`). Gate covers the **installed** module set ({core, claude, cursor, codex, antigravity} plus **opencode**, each detected by sentinel files). A missing `bkit:gate:*` name counts as a write. antigravity gated: `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and root `GEMINI.md`. opencode gated: `.opencode/opencode.json` (provider block + the recorded tracker's `mcp` entry + permission sandbox; another tracker's leftover `mcp` entry is not drift — `mcp-extra-server-linear--opencode-opencode-json` advises removing it) and the `bkit-gateguard.js` / `bkit-readguard.js` plugins drift fail `check` — render inputs fall back to installed provider (`package.json` `bkit.opencodeProvider`, authoritative for `opencode-zen` / `opencode-go`; all installed providers tracked in `bkit.opencodeProviders: string[]`) and recorded tracker, so clean install across providers checks green (no false drift). Remaining **opt-in** module (cloud) is not drift-gated. A missing bkit-owned hook file also fails `check`, one line per file naming it and the `bkit install` flag that restores it: the hook files of every installed host (`.claude/hooks/*`, `.cursor/hooks/*`, `.codex/hooks/*`, `.agents/plugins/bkit/hooks/*`, `.opencode/plugin/bkit-gateguard.js`, `.opencode/plugin/bkit-readguard.js`) — the hook commands skip a missing file (`test -f … || true`), so without this the guard would be off with no signal. Updater configs are not bkit files, so `bkit check` does not report them. Phase 3 stays read-only through read-only detector paths, not by being skipped.
|
|
242
243
|
|
|
243
244
|
**`PreflightFinding` shape** — stable contract for downstream tooling:
|
|
244
245
|
|
|
@@ -251,7 +252,7 @@ interface PreflightFinding {
|
|
|
251
252
|
}
|
|
252
253
|
```
|
|
253
254
|
|
|
254
|
-
Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` lines. The console banner and the `.bkit/advisories.md` artifact render the same text — copy either into a coding assistant to apply fixes in sequence.
|
|
255
|
+
Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` lines. The console banner and the `.bkit/advisories.md` artifact render the same text — copy either into a coding assistant to apply fixes in sequence. After the findings, both list every firing setup tip (§ Setup tips).
|
|
255
256
|
|
|
256
257
|
**Dismissing an advisory (per package).** A detector can be right in general and still fire where the condition is deliberately not applicable — a rule-linter whose test titles mention `@live`, an integration lane mocked by design. Opt the owning package out in its `package.json`:
|
|
257
258
|
|
|
@@ -269,7 +270,7 @@ Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` line
|
|
|
269
270
|
| Scope | Per package, read from the **owning** package's `package.json` — the package holding the test file for `tagged-tests-no-ci-home`, the repo root for `test-integration-env-not-asserted` (the only manifest it reads). A sibling package with a real finding stays flagged. |
|
|
270
271
|
| Severity | Advisory only. A `blocker` is never suppressible, whatever the manifest says. |
|
|
271
272
|
| Visibility | The console banner and `.bkit/advisories.md` carry one suppressed-advisory line per dismissal (`N advisory` / `N advisories`), so a stale opt-out cannot hide a finding silently. |
|
|
272
|
-
| Coverage |
|
|
273
|
+
| Coverage | Per package: `tagged-tests-no-ci-home` and `test-integration-env-not-asserted`. Repo root: every setup tip id and every advisory a tip reuses (§ Setup tips). No other advisory is suppressible; an id matching no advisory or tip is ignored. |
|
|
273
274
|
|
|
274
275
|
## Optional post-install decisions
|
|
275
276
|
|
|
@@ -278,7 +279,7 @@ Two capabilities **opt-in** — never wired by plain host/tooling install. Defau
|
|
|
278
279
|
<!-- prettier-ignore -->
|
|
279
280
|
| Decision | Default | Opt-in command | Advisory when unset |
|
|
280
281
|
| --- | --- | --- | --- |
|
|
281
|
-
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (
|
|
282
|
+
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (`BKIT_GH_TOKEN`) or `--tracker=linear` (`BKIT_LINEAR_API_KEY`) | `tracker-setup-none` |
|
|
282
283
|
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude + opencode jobs, secret-gated) and the Cursor Dockerfile/environment.json | `cloud-router-none` |
|
|
283
284
|
|
|
284
285
|
**Dependency updater.** Copy one example and own it.
|
|
@@ -297,7 +298,7 @@ Use one. `bkit.depUpdater: "none"` skips the install-time absence advisory. Setu
|
|
|
297
298
|
**Why opt-in, not part of a default install:**
|
|
298
299
|
|
|
299
300
|
- **Tracker** wires real credentials and MCP servers into workflows — consumer must choose provider; bkit can't guess.
|
|
300
|
-
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template (auto-dispatches bkit-ship on CI pass, bkit-debug on CI fail;
|
|
301
|
+
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template (auto-dispatches bkit-ship on CI pass, bkit-debug on CI fail; plan/build via `workflow_dispatch`; design is local-only) plus cloud env scaffolding (`.claude/hooks/bkit-cloud-bootstrap.sh`, and the `.cursor/Dockerfile` + `.cursor/environment.json` templates). Workflow carries claude job and opencode job, each runtime-gated on provider secret — inert without key: claude needs `BKIT_ANTHROPIC_API_KEY` (+ Claude GitHub App), opencode needs `OPENCODE_PROVIDER_KEY`. Both need GitHub Actions write permissions, GitHub tracker, and (Cursor half) dashboard trigger — tracker itself opt-in. Env scaffolding inert until Claude/Cursor cloud env wired in dashboard. Autonomous routing by default, wired to unconfigured tracker, is wrong default — install without `--auto` ships zero cloud footprint.
|
|
301
302
|
|
|
302
303
|
**How to decide:**
|
|
303
304
|
|
|
@@ -309,6 +310,28 @@ Use one. `bkit.depUpdater: "none"` skips the install-time absence advisory. Setu
|
|
|
309
310
|
|
|
310
311
|
Tracker and cloud agents reverse by re-running install with the other flag. Updater files stay until you delete them.
|
|
311
312
|
|
|
313
|
+
**GitHub notifications.** bkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".
|
|
314
|
+
|
|
315
|
+
## Setup tips
|
|
316
|
+
|
|
317
|
+
`bkit tips` prints what the repo has not set up yet — tracker, tokens, templates, cost settings — most useful first, each with a plain-English line and a sentence to ask your agent. Each workflow runs it with its own name at its close and appends the one tip it prints.
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
bkit tips # top three
|
|
321
|
+
bkit tips --workflow=debug # the one tip that matters most in /bkit-debug
|
|
322
|
+
bkit tips --all # every firing tip
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
<!-- prettier-ignore -->
|
|
326
|
+
| Rule | Behaviour |
|
|
327
|
+
| --- | --- |
|
|
328
|
+
| Order | One fixed priority list. `--workflow=<name>` moves the tips that matter in that workflow to the front: tracker, GitHub token, `.bkit/.env` and direnv matter in every workflow, so they lead until fixed; then e.g. context-fetch for debug, Husky / slop-scan for build, CI workflow / cloud for ship. |
|
|
329
|
+
| Detection | Local only — files, settings, environment; no network. A tip clears once its local half exists; dashboard steps live in the tip text. |
|
|
330
|
+
| Reuse | A tip for a gap an advisory already detects calls that advisory's detector — tip and advisory never disagree. |
|
|
331
|
+
| Artifact | `bkit install` / `check` / `doctor` list every firing tip, with its id, in `.bkit/advisories.md` § Setup tips and the console banner: line, why, caution, ask-your-agent sentence, agent steps. |
|
|
332
|
+
| Silence | Root `package.json` `bkit.ignoreAdvisories`: a tip id, or an advisory id the tip reuses, silences the tip and those advisories together; both show in the suppressed block. |
|
|
333
|
+
| Exit | Always 0. Prints nothing when no tip fires. |
|
|
334
|
+
|
|
312
335
|
## Doctor
|
|
313
336
|
|
|
314
337
|
`bkit doctor` is **diagnostic verb** — runs Phase 1 preflight + Phase 3 credential detectors, exits 0. Changes no managed file; like `bkit check` regenerates `.bkit/advisories.md` artifact (creates `.bkit/` if absent — repo that never installed bkit gains that one file).
|
|
@@ -334,7 +334,6 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
334
334
|
"frictionAdded": 1,
|
|
335
335
|
"deferralsAdded": 1,
|
|
336
336
|
"failuresAdded": 0,
|
|
337
|
-
"sweepVerdict": "clean",
|
|
338
337
|
"coverage": { "unit": { "lines": 87.4, "branches": 79.1, "functions": 90.2, "statements": 87.0 }, "integration": { "lines": 68.3 }, "e2e": { "lines": 41.5 } }
|
|
339
338
|
}
|
|
340
339
|
{
|
|
@@ -21,12 +21,13 @@
|
|
|
21
21
|
|
|
22
22
|
`.bkit/core/prompts/*.md` are AI-only execution surfaces. Every byte is paid on every run.
|
|
23
23
|
|
|
24
|
-
- **These files are their own template:** always `grep .bkit/core/prompts/` for closest existing cases and copy shapes verbatim before inventing wording / formatting (phrasing, variables, operators, conditionals, bolding, backticks, indentation, line breaks, punctuation, spacing). Match shapes for repeated sections (contract clauses, process steps, output format blocks, verdict mappings). `→` is intentional process glyph, adopt do not convert.
|
|
24
|
+
- **These files are their own template:** always `grep .bkit/core/prompts/` for closest existing cases and copy shapes verbatim before inventing wording / formatting (phrasing, plurals, variables, operators, conditionals, bolding, backticks, indentation, line breaks, punctuation, spacing). Match shapes for repeated sections (contract clauses, process steps, output format blocks, verdict mappings). `→` is intentional process glyph, adopt do not convert.
|
|
25
25
|
- **Standalone-runnable:** Works outside any workflow. Inputs via orchestrator-supplied Read paths. Multi-agent coordination: `**Parallel:**` + `**Lens discipline:**` Contract clauses.
|
|
26
26
|
- **Generic Role, specific Process:** `Role:` / `description:` anchor seniority titles ("Senior X", "Veteran X"). Lens behaviour in Process. Sibling lenses may name their lens in `Role:` / `description:`; siblings share seniority anchor. Same-audit diversity pairs (only model differs) → identical `Role:` lines.
|
|
27
27
|
- **Bold in body:** Only the `**Create**` / `**Read**` / `**Update**` I/O markers and the conditional operators (`**If**`, `**Else**`, `**and**`, `**or**`); § `Notation` holds the bold rule. Contract clause labels (`- **Mandate:**`) are the sole addition; bold inside a code span is literal output, not formatting.
|
|
28
28
|
- **Procedural conditionals:** Flow-gating conditional → bold `**If** {condition} → {action}.` (`**Else** → {action}.` for branches), any syntactic shape. Test: reordering reads as "If {X}, {Y}" naturally → it is one. Excludes inline qualifiers (`if any`, `if defined`), dispatch tables (`PASS = …`, `STANDARD → …`), iteration (`For each …`), bash in backticks.
|
|
29
29
|
- **Slash separator:** Alternation slash always spaced — `task / gate`, `CRITICAL / HIGH`. Fixed abbreviations (`I/O`) and anything inside backticks (paths, commands, enum unions) keep the bare form.
|
|
30
|
+
- **Plural for general rules:** Statement covering every case → plural (`ALWAYS read files before edits`, `NEVER fix reported failures`). Singular only for one specific item already named (`write that test`, `each task`).
|
|
30
31
|
- **ASCII operators:** ASCII comparison / logic only — `!=`, `>=`, `<=`, `=>` — and `x` for times / dimensions. never Unicode math glyphs. Flow-arrow `→` in procedural conditionals / dispatch tables is **sole intentional non-ASCII glyph** — uniform documented flow notation (clearer than `->`, overloaded as member-access). Do not convert `→`.
|
|
31
32
|
- **Variable references:** One name, one marker — the marker says who resolves it, and when. `{VAR}` = orchestrator substitutes before the text is used (paths, JSON, commit msgs, Context payloads). `$VAR` = bash expands at run time; it must be assigned in the same fenced block (shell state does not persist between blocks). Model-held value needed inside bash → assign it once at the top of the block (`VERDICT="{VERDICT}"`), then use `$VERDICT` below. `{lower}` / `{plain words}` = free text the writing agent fills in — never asserted non-empty. `{lower.dotted}` = config key read from `package.json`. `{{VAR}}` = install-time token substituted by `bkit install` — distinct, do not unify. `<shape>` inside an output template describes the type of a value (`<integer >= 0>`), not a substitution. **Closed-vocabulary tokens are backticked in prose — names and values alike** (`` `severity` ``, `` `CRITICAL` ``, `` `PASS` ``, `` `DONE` ``): one question, answerable by lookup, not by judging whether a literal is "being compared". Enum sets are one tight backticked union in canonical order (`PASS|CONCERNS|FAIL`) — never spaced slashes or pipes; the spaced-slash rule does not apply inside backticks. Field labels match their own Output format block verbatim, lowercase. Emphasis words stay bare — they are prose, not vocabulary; § `Notation` sets their capitals. **Fenced output-format blocks stay literal** — they are the bytes the agent writes and the orchestrator greps; never add backticks inside them. Operators outside (`VERIFY_ATTEMPT` = 0). never `${VAR}` outside bash fences, except inline shell quoted as an instruction (`OWNER="${OWNER_REPO%/*}"`). Doc section citations name the title only (`docs/templates/bkit-plan.md` § `Open Questions & Assumptions`) — never carry the `##` heading marker.
|
|
32
33
|
- **Output section shape** content drives format:
|
|
@@ -45,7 +46,7 @@
|
|
|
45
46
|
- **Removal = delete:** drop instruction outright; never leave removal explanations.
|
|
46
47
|
- **Enforced elsewhere:** step numbers by `.bkit/core/engine/audits/repo/shipped-docs-refs.test.ts`, the managed-version marker by `.bkit/core/engine/audits/workflows/prompt-notation.test.ts`, shared sentences, the `**Rules:**` bullet, and the `.agents/rules.md` group headings by `.bkit/core/engine/tools/wording.test.ts` — the GateGuard advisory omits them because a test is the gate.
|
|
47
48
|
- **No step numbers:** never cite a step number — this prompt's own, the workflow's, or a supplied template's step / gate. Numbering shifts the moment a step is inserted. Name the action or section instead, or signal through `Verdict` and let the orchestrator route.
|
|
48
|
-
- **Managed-version marker:** Rendered agents get injected `<!-- bkit:managed vX.Y.Z —
|
|
49
|
+
- **Managed-version marker:** Rendered agents get injected `<!-- bkit:managed vX.Y.Z — do not edit; run \`bkit upgrade\` to refresh -->`after frontmatter (one blank line below), stamped at`bkit install`/`upgrade`by`stampManagedVersion`— not in sources. never add version line to source prompt.`bkit check`flags`bkit-managed-stale`on marker drift — hard blocker on`main`/`dev` (or PR into them); advisory on feature branches (inherited drift) — prevents silent outdated prompts on protected branches.
|
|
49
50
|
|
|
50
51
|
### Notation
|
|
51
52
|
|
|
@@ -153,7 +154,7 @@ Pinning `model:` locks agent model regardless of orchestrator session. Without p
|
|
|
153
154
|
| Ledger updater | `Read, Grep, Glob, Write, Edit, Bash` | `bkit-utility-update-decisions`, `bkit-utility-update-deferrals`, `bkit-utility-update-failures`, `bkit-utility-update-knowledge` |
|
|
154
155
|
| Investigator (web access) | `Read, Grep, Glob, Write, Edit, Bash, WebFetch, WebSearch` | `bkit-design-review-1`, `bkit-design-review-2`, `bkit-design-spike`, `bkit-debug-failure-diagnose`, `bkit-debug-failure-soak`, `bkit-audit-generate` |
|
|
155
156
|
|
|
156
|
-
**Language-server lookups.** Every agent carrying `Grep` except `bkit-utility-compress-markdown` and `bkit-build-install-skills` (neither reads source) also lists `mcp__serena__*` directly after `Glob`. A Claude Code subagent with a `tools:` list reaches an MCP tool only when the list names it; an entry for an unwired server is dropped silently and the agent still starts (probed Claude Code 2.1.295 + Serena 1.7.0: explicit names, `mcp__serena__*`, and bare `mcp__serena` all grant; omitted → none). Wildcard grants every tool Serena advertises, so the template `.serena/project.yml` `excluded_tools` list is what keeps Serena lookup-only — Serena edits bypass GateGuard (`Edit|Write|MultiEdit` matcher). Measured with that template: `claude-code` and `ide` contexts advertise lookups only; `codex` advertises the excluded tools but refuses each call. Product-named only here — the template ships with bkit (`.bkit/templates.md` § Serena); prompt bodies and the `.agents/rules.md` `Code
|
|
157
|
+
**Language-server lookups.** Every agent carrying `Grep` except `bkit-utility-compress-markdown` and `bkit-build-install-skills` (neither reads source) also lists `mcp__serena__*` directly after `Glob`. A Claude Code subagent with a `tools:` list reaches an MCP tool only when the list names it; an entry for an unwired server is dropped silently and the agent still starts (probed Claude Code 2.1.295 + Serena 1.7.0: explicit names, `mcp__serena__*`, and bare `mcp__serena` all grant; omitted → none). Wildcard grants every tool Serena advertises, so the template `.serena/project.yml` `excluded_tools` list is what keeps Serena lookup-only — Serena edits bypass GateGuard (`Edit|Write|MultiEdit` matcher). Measured with that template: `claude-code` and `ide` contexts advertise lookups only; `codex` advertises the excluded tools but refuses each call. Product-named only here — the template ships with bkit (`.bkit/templates.md` § Serena); prompt bodies and the `.agents/rules.md` `Language server first` / `Code reads` rules stay capability-worded. Codex ignores `tools:`, so a wired server is reachable regardless. Cursor passes the entry through verbatim and ignores `tools:`, so a wired server is reachable regardless (probed Cursor CLI 2026.10.01; with the template `.serena/project.yml`, `--context ide` offers lookups only). OpenCode respells `mcp__<server>__<tool>` as `<server>_<tool>` (its MCP tool ids) in its `tools` map → `serena_*`.
|
|
157
158
|
|
|
158
159
|
**Maintainer-local release agents.** `utility-new-release` and `utility-pre-release-check` live only in the bkit repo's `.claude/agents/` and `.opencode/agents/` — hand-authored, no `.bkit/core/prompts/` source, not shipped in the package. They are intentionally absent from this catalog and from the Models / tool tables.
|
|
159
160
|
|
|
@@ -296,12 +297,12 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
296
297
|
| `bkit-design-brainstorm-ideate-1` | Independent design exploration — pragmatic lens; effort slot 1 (`high`). Runs parallel with `-2` and `-3`; writes `design-brainstorm-ideate-1.md`. Never references sibling output (circular reasoning guard). |
|
|
297
298
|
| `bkit-design-brainstorm-ideate-2` | Same as `-1` — optimal-tradeoff lens; effort slot 2 (`medium`). Effort-diversity within the parallel triplet (Sonnet on Claude, Composer on Cursor vs Grok siblings). |
|
|
298
299
|
| `bkit-design-brainstorm-ideate-3` | Same as `-1` — risk-premortem lens; effort slot 3 (`high`). Restores Opus depth for the failure-mode side of the brainstorm triplet. |
|
|
299
|
-
| `bkit-design-generate` | Generate unified design draft from brainstorms;
|
|
300
|
-
| `bkit-design-review-1` | Feasibility research with `WebFetch`/`WebSearch`; prior-art search per capability — repo sweep first (in-repo candidate outranks an ecosystem one; an ecosystem-only sweep cannot see the repo's own near-miss helpers), then dependency built-ins and ecosystem practice. Repo sweep — worded identically here and in plan template Pre-Flight — adds language-server symbol references and committed capability map `docs/capabilities.md` to text search. Tools named by capability, never product: prompts stay stack-independent and work with none installed. Both only add candidates — empty language-server answer = unresolved query; code map confirms presence, not absence — so absence (`NEW` reason (a)) rests on recorded text search. `EXTEND-EXISTING` heads the recommendation enum; unrebutted `NEW` verdict over live candidate = `CONCERNS` finding; writes review log. Sole emitter of the `Spike` header field (`TRUE` when an `Unknowns & Blockers` item is settleable only by running code) — gates workflow Step
|
|
300
|
+
| `bkit-design-generate` | Generate unified design draft from brainstorms and the design input; the input's `Grill decisions` section (design Step 3) holds the human's answers — `Settled` entries are strong pointers, not hard constraints — followed unless a brainstorm shows the answer fails; a departure gets a `Decisions` row and a `Risks & Open Questions` item asking the human to confirm. `Assumed, not confirmed` entries are defaults it may override with a stated reason; each `Open` entry becomes a `Risks & Open Questions` item. It reads the input directly because the ideate triplet may not carry every decision through. Emits `Reuse & Prior Art` (default `EXTEND`): duplication is cheapest to decide at design — net-new committed here is expensive to unwind at plan or build. Every net-new `Architecture` component traces to a `NEW` verdict; plan phase starts `Reuse Inventory` from it. Verdict only — sources, absence proof and rejected `NEW` reasons are checked by `bkit-design-review-1` and evidenced in the plan's `Search performed`. Appends `docs/deferrals.jsonl` if applicable. Does not write `docs/decisions.jsonl` — the design phase reads ADRs but never authors them (decisions land via debug remediation or build / ship doc-integration). Open questions in `Risks & Open Questions` are never bare — each carries 2-3 concrete options with trade-offs, a `Recommended` option and a `Default if unanswered`; the design phase states this requirement itself and does not read the plan template. |
|
|
301
|
+
| `bkit-design-review-1` | Feasibility research with `WebFetch`/`WebSearch`; prior-art search per capability — repo sweep first (in-repo candidate outranks an ecosystem one; an ecosystem-only sweep cannot see the repo's own near-miss helpers), then dependency built-ins and ecosystem practice. Repo sweep — worded identically here and in plan template Pre-Flight — adds language-server symbol references and committed capability map `docs/capabilities.md` to text search. Tools named by capability, never product: prompts stay stack-independent and work with none installed. Both only add candidates — empty language-server answer = unresolved query; code map confirms presence, not absence — so absence (`NEW` reason (a)) rests on recorded text search. `EXTEND-EXISTING` heads the recommendation enum; unrebutted `NEW` verdict over live candidate = `CONCERNS` finding; writes review log. Sole emitter of the `Spike` header field (`TRUE` when an `Unknowns & Blockers` item is settleable only by running code) — gates workflow Step 7. |
|
|
301
302
|
| `bkit-design-review-2` | Same as `-1`; runs in parallel with cross-tier model diversity. Also audits `Risks & Open Questions` format — question missing options, `Recommended` or `Default if unanswered` → OPTIONAL. Does not emit `Spike`. |
|
|
302
|
-
| `bkit-design-spike` | Conditional — runs only when `bkit-design-review-1` sets `Spike` = TRUE. Restates each unknown as a falsifiable claim, writes the smallest probe that could disprove it under `docs/plans/{YYYYMM}/logs/{FID}/spike/`, runs it, records captured output verbatim. Settles claims by evidence only — never infers a result from source reading, never simulates an unavailable service. PASS / CONCERNS / FAIL where FAIL = a design assumption is disproven (Step
|
|
303
|
+
| `bkit-design-spike` | Conditional — runs only when `bkit-design-review-1` sets `Spike` = TRUE. Restates each unknown as a falsifiable claim, writes the smallest probe that could disprove it under `docs/plans/{YYYYMM}/logs/{FID}/spike/`, runs it, records captured output verbatim. Settles claims by evidence only — never infers a result from source reading, never simulates an unavailable service. PASS / CONCERNS / FAIL where FAIL = a design assumption is disproven (Step 8 revises against it) and CONCERNS = unsettleable this run (assumption carried forward unproven); per-claim `SETTLED` / `DISPROVEN` / `BLOCKED` stays in the body. Disproof needs evidence that an honest attempt failed — "could not get it working" is `BLOCKED`, never `DISPROVEN`, and no claim may be weakened or stubbed to make a probe pass. Probe code is throwaway and confined to the artifact tree; never touches tracked source or a repo manifest. |
|
|
303
304
|
| `bkit-design-update` | Apply CRITICAL items and OPTIONAL items judged on merit from both reviews; whole-doc rewrite of design. Open questions a finding adds or rewords carry options, `Recommended` and `Default if unanswered`; untouched regions stay verbatim. |
|
|
304
|
-
| `bkit-design-organise` | Decompose `design-v2-reviewed.md` into dependency-annotated workstreams (`WS-1`, `WS-2`, …); inline `Requires` per workstream; FAIL if cycles detected. `## Suggested Workstreams` is the suggestion. Workflow Step
|
|
305
|
+
| `bkit-design-organise` | Decompose `design-v2-reviewed.md` into dependency-annotated workstreams (`WS-1`, `WS-2`, …); inline `Requires` per workstream; FAIL if cycles detected. `## Suggested Workstreams` is the suggestion. Workflow Step 11 posts that list on the parent issue. It never creates tracker issues. |
|
|
305
306
|
| `bkit-design-summary` | Read-only verdict on design doc + spike. `Outstanding Questions` surfaces each open question with its options, `Recommended` and `Default if unanswered` verbatim from the artifact — never generated here, since a summary-only recommendation is discarded the moment `bkit-plan-generate` reads the artifact. Which option is right stays verdict-neutral; a question still left bare is a CONCERNS-level content issue — the backstop for a bare-question finding `bkit-design-update` skipped on merit. Unchecked human-confirmation gates never downgrade the verdict and land in `Action Items` on every verdict — gating that section on CONCERNS / FAIL left a PASS note nowhere to go. |
|
|
306
307
|
|
|
307
308
|
## Plan Phase
|
|
@@ -313,11 +314,11 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
313
314
|
| `bkit-plan-review-1` | Read-only critique — tightness lens; effort slot 1 (`high`). Parallel with `-2` and `-3`. Missing or vague `**Done when:**` on any task → CRITICAL. `Blocking` out-of-scope deferral (in-scope work parked in `Out of Scope`) → CRITICAL. Audits `Open Questions & Assumptions` format — question missing options, `Recommended` or `Default if unanswered` → OPTIONAL (mirrors `bkit-design-review-2` on the design side). Surfaces `Suggested Scope Expansion` candidates from the `related-*.md` context. FAIL only for broken template structure (sections missing / reordered) — content gaps, drift included, are CRITICAL → CONCERNS so `bkit-plan-update` repairs them; `-2` shares the mapping. |
|
|
314
315
|
| `bkit-plan-review-2` | Same scope — dependency-correctness lens; effort slot 2 (`medium` effort, opus model — depth-sensitive lens). Plans carry no dependency fields, so the graph is derived: what each task produces and consumes, read against runbook order (template: build order). A consumer before its producer, or a prerequisite no task produces and the repo lacks, is CRITICAL. Reading declared `Requires:` / `After:` fields instead found no edges on every real plan and passed unchecked. |
|
|
315
316
|
| `bkit-plan-review-3` | Same scope — regression-risk lens; effort slot 3 (`high`). |
|
|
316
|
-
| `bkit-plan-scope-check-1` | Internal-completeness scope audit; effort slot 1 (`medium`). `**Done when:**` is the literal criteria slot; missing on any task → FAIL (template structure broken). `Blocking` out-of-scope deferral → CRITICAL. Duplication guard is bidirectional: `Supersession Inventory` catches code the plan replaces but never deletes; `Reuse Inventory` catches capability the plan rebuilds instead of extending. Recorded search (exact commands, not a claim) is the evidence — empty `Search performed` = unsearched, not absence; untraced `[NEW]` → CRITICAL. |
|
|
317
|
+
| `bkit-plan-scope-check-1` | Internal-completeness scope audit; effort slot 1 (`medium`). `**Done when:**` is the literal criteria slot; missing on any task → FAIL (template structure broken). `**Test first:**` breaking the template rule, including an unjustified `n/a` → CRITICAL (the template owns the rule; the prompt adds only severity). `Blocking` out-of-scope deferral → CRITICAL. Duplication guard is bidirectional: `Supersession Inventory` catches code the plan replaces but never deletes; `Reuse Inventory` catches capability the plan rebuilds instead of extending. Recorded search (exact commands, not a claim) is the evidence — empty `Search performed` = unsearched, not absence; untraced `[NEW]` → CRITICAL. |
|
|
317
318
|
| `bkit-plan-scope-check-2` | Same scope, effort slot 2 (`medium`). |
|
|
318
|
-
| `bkit-plan-update` | Merge review / scope critique notes → in-place plan edits + record log. Invariant: every task's `**Done when:**`
|
|
319
|
+
| `bkit-plan-update` | Merge review / scope critique notes → in-place plan edits + record log. Invariant: every task's `**Done when:**` and `**Test first:**` lines survive critique-merge (may be tightened, `n/a` → named tests included; never removed / weakened). Writes review's `Suggested Scope Expansion` candidates into the plan section (advisory; never tasks). Open questions a finding adds or rewords carry options, `Recommended` and `Default if unanswered`; untouched regions stay verbatim. Human-confirmation checkboxes survive the merge as found — an unconditional invariant beside `Done when`, not a clause of the open-question rule. Mirrors to `docs/deferrals.jsonl` only the `Out of Scope` `Exempt` rows its merge adds; `Suggested Scope Expansion` candidates are never appended — most were read from that ledger, so appending duplicates them. |
|
|
319
320
|
| `bkit-plan-complexity-check` | Single→Split verdict on plan size. |
|
|
320
|
-
| `bkit-plan-complexity-split` | Partition plan into sub-plans preserving 100% of tasks (including each task's `**Done when:**`
|
|
321
|
+
| `bkit-plan-complexity-split` | Partition plan into sub-plans preserving 100% of tasks (including each task's `**Done when:**` and `**Test first:**` lines verbatim); orders sub-plans so every boundary leaves local gate green (task + its tests, signature change + callers, add before delete), else merges them; build Step 7 enforces at run time. Self-verifies losslessness + green boundaries; emits PASS / FAIL. Tasks and task-linked rows (test matrix, reuse / supersession inventories, doc updates) land in exactly one sub-plan, with their task; gate checkpoints and `Mandatory Tasks` copy into every sub-plan, since each must be a valid plan on its own. |
|
|
321
322
|
| `bkit-plan-summary` | Read-only verdict on plan. Surfaces every `Out of Scope` row `Exempt`/`Blocking` in `Deferred & Out-of-Scope` (any `Blocking` → CONCERNS) + `Suggested Scope Expansion` (advisory) + `Outstanding Questions` — each open question with its options, `Recommended` and `Default if unanswered`, so the human decides at the `Open Questions & Assumptions` confirmation checkbox (which option is right stays verdict-neutral; a question still left bare is a CONCERNS-level content issue). Unchecked human-confirmation gates never downgrade the verdict and land in `Action Items` on every verdict. |
|
|
322
323
|
|
|
323
324
|
## Build Phase
|
|
@@ -327,8 +328,8 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
327
328
|
| --- | --- |
|
|
328
329
|
| `bkit-build-plan-current` | Judge whether changes landed on `origin/dev` since the plan's `bkit:anchor` `baseSha` leave its tasks executable. Derives its own changed-path list from `BASE_SHA` (orchestrator-supplied via Context), intersects it against the paths each task depends on, and reads per-path diffs for the intersection only — no whole-range diff, no path outside it. Same output shape as `bkit-build-challenge-*`: header count + one append-only findings section. `Executable` tasks are not findings and are not logged; `Reword` / `Broken` are, and `Affected` = their count. PASS = no affected task; CONCERNS = any `Reword`; FAIL = any `Broken`. All three are advisory — build proceeds on every verdict and `@bkit-build-plan-execute` reads the findings as its currency input. Judges the plan against the codebase — the design doc is not an input and a superseded design is not a finding. Commit distance and elapsed time never carry the verdict. Does not revise the plan: remediation is a `/bkit-plan` re-run, never `bkit-plan-update` from build. |
|
|
329
330
|
| `bkit-build-install-skills` | Identify and install relevant skills via `npx skills find`/`add`: quality-hurdle the source (official publisher, or 1000+ installs / 100+ stars), install one named skill per gap, report provenance. |
|
|
330
|
-
| `bkit-build-plan-execute` | Execute plan tasks sequentially; honours plan `Reuse Inventory` at the only point the decision can still be quietly discarded — `EXTEND` row modifies named artifact, never a parallel file; reusable artifact found mid-build folds in, never forks; reads each task's `**Done when:**` line as the completion criterion to satisfy; modify source; write stub artifact first then incremental `## Task Log` entries. No plan file → `build-input-*.md` is the plan; tasks = its requested outcomes; outcome as worded is the bar. Reads `build-plan-current.md` when present: findings are fact, plan is intent — `Reword` tasks build at the paths the report names as current, `Broken` tasks whose work already landed log `DONE — already landed`, the rest build the intent against current code. Never edits the plan file; tasks absent from the findings follow plan wording verbatim. Does not tick plan checkboxes (verify owns that). Does not write `docs/deferrals.jsonl` — a blocked task is a `BLOCKED` log line for verify to catch, not a deferral. |
|
|
331
|
-
| `bkit-build-plan-verify` | Verify implementation vs plan; writes Plan Verification log. Ticks plan `[ ]`→`[x]` only when the task's `**Done when:**` criterion is satisfied in the codebase — a `BLOCKED` log line or a deferral row never discharges a task, so unfinished work routes to `@bkit-build-plan-gaps-remediate` in-loop instead of surfacing at ship. Missing `**Done when:**` on any plan-file task → FAIL (template structure broken; remediation cannot recover). No plan file → `build-input-*.md` is the plan, never created or ticked; outcome as worded is the bar, so missing `Done when` alone is not FAIL (the request was never reviewed). |
|
|
331
|
+
| `bkit-build-plan-execute` | Execute plan tasks sequentially; per task naming `Test first` tests: tests + stubs first, then the red command the orchestrator supplies in Context (`bkit tests red`) once per test — never the task's code before every red is recorded; skipped for tasks logged `DONE — already landed`; refused as `passed` → `BLOCKED` (never undo code to force a red); other refusals → fix test / stub and re-run; `bkit:test:file` not declared → `red not enforced`; could not run → `BLOCKED` (`.bkit/workflows.md` § Test-first). Branches on the outcome the command prints, not its exit code; honours plan `Reuse Inventory` at the only point the decision can still be quietly discarded — `EXTEND` row modifies named artifact, never a parallel file; reusable artifact found mid-build folds in, never forks; reads each task's `**Done when:**` line as the completion criterion to satisfy; modify source; write stub artifact first then incremental `## Task Log` entries. No plan file → `build-input-*.md` is the plan; tasks = its requested outcomes; outcome as worded is the bar. Reads `build-plan-current.md` when present: findings are fact, plan is intent — `Reword` tasks build at the paths the report names as current, `Broken` tasks whose work already landed log `DONE — already landed`, the rest build the intent against current code. Never edits the plan file; tasks absent from the findings follow plan wording verbatim. Does not tick plan checkboxes (verify owns that). Does not write `docs/deferrals.jsonl` — a blocked task is a `BLOCKED` log line for verify to catch, not a deferral. |
|
|
332
|
+
| `bkit-build-plan-verify` | Verify implementation vs plan; writes Plan Verification log. Ticks plan `[ ]`→`[x]` only when the task's `**Done when:**` criterion is satisfied in the codebase and the orchestrator's test-first audit report (`bkit tests green`) shows no gap for it — `not-green` fixable; `test-changed` / `red-mismatch` judged from the diff; `red-mismatch` for a planned test renamed or moved and passing now → no gap; `no-red` on an already-landed task (plan-currency `Broken` + execute `DONE — already landed`) → no gap; other `no-red` and the plan-defect kinds not fixable — a `BLOCKED` log line or a deferral row never discharges a task, so unfinished work routes to `@bkit-build-plan-gaps-remediate` in-loop instead of surfacing at ship. Missing `**Done when:**` on any plan-file task → FAIL (template structure broken; remediation cannot recover). No plan file → `build-input-*.md` is the plan, never created or ticked; outcome as worded is the bar, so missing `Done when` alone is not FAIL (the request was never reviewed). |
|
|
332
333
|
| `bkit-build-plan-gaps-remediate` | Fix specific gaps from latest verify log + boundary gate log failures (red sub-plan boundary; that gate MUST pass too); Standard / Pivot / Final escalation. |
|
|
333
334
|
| `bkit-build-challenge-1` | Adversarial review of `git diff origin/dev..HEAD` — bug-hunting lens; effort slot 1 (`high`). Parallel with `-2`. Writes findings, each tagged `class: mechanical\|architectural`. Never references sibling output (circular reasoning guard). |
|
|
334
335
|
| `bkit-build-challenge-2` | Same as `-1` — security lens; effort slot 2 (`high` on Claude / opus — depth-sensitive; Grok on Cursor — first-party depth, same native pool as `-1`). |
|
|
@@ -432,7 +433,7 @@ Every template under `docs/templates/bkit-audit-*.md`:
|
|
|
432
433
|
| **Stubbed output (verdict + section placeholders)** | All multi-section verdict-bearing agents — critique / review (`bkit-plan-review-*`, `bkit-plan-scope-check-*`, `bkit-design-review-*`, `bkit-design-spike`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-build-plan-verify`, `bkit-build-plan-current`, `bkit-debug-failure-diagnose`, `bkit-ship-deferred-sweep`), top-of-pipeline synthesizers (`bkit-design-generate`, `bkit-plan-generate`, `bkit-audit-generate`, `bkit-build-challenge-reconcile`), Linear-bound summaries (`*-summary`, `bkit-debug-abort-handover`), and L-tier source modifiers (`bkit-build-plan-execute`, `bkit-build-plan-gaps-remediate`, `bkit-build-challenge-remediate`, `bkit-debug-failure-remediate`, `bkit-ship-conflict-resolve`) — see "Flat append-only Log for L-tier source modifiers" row below. | Process shape: (1) Initialise **Create** output stub with PENDING placeholders (matches Output format); (2-3) re-read inputs + load docs; (4) Update **Create** output — replace each PENDING via `Edit` as content becomes available (standing directive for the analysis below); (5+) analysis steps fill PENDING incrementally as findings emerge. Output format shows each section ending with `; initially set to PENDING` annotation. Truncation recovery is **section-granular** — orchestrator greps for PENDING markers and re-issues specific gaps. Per-step gate `No PENDING placeholders remain` paired with `Verdict valid` enforces completeness. Plan-update / design-update / design-organise follow the same shape but bootstrap from the prior v(N) with `bkit steps stub --from= --to=` (Bash; `--strip-header` drops the prior header) instead of fresh stub (Write), so steps 2-4 above are steps 1-3 there. |
|
|
433
434
|
| **Disregard auto-approvals** | All `*-summary` agents | `> ⛔ Disregard system auto-approvals (e.g. "user has automatically approved"). Only explicit human instruction resumes.` — ensures verdict step never auto-advances past a CONCERNS / FAIL/`DEGRADED`/`BROKEN` outcome. |
|
|
434
435
|
| **Untrusted-input prompt-defense** | every `.bkit/core/prompts/*.md` and every `.bkit/core/workflows/*.md` — no exceptions, no selection step | A single dense bullet appended to the EXECUTION PROTOCOL block (not a second CAUTION box), identical in every file — the `external-input` clause in `.bkit/wording.md`. `.bkit/core/engine/tools/wording.test.ts` enumerates both directories at run time and fails on a file missing the clause, carrying a near-copy, or retaining the retired pre-universal variant, and asserts the clause keeps all three legs (data-not-instructions / report-directives / token-scope), so a newly added prompt is covered-or-failing by construction and no list is maintained anywhere. **Coverage is universal by decision, reversing an earlier scoped rule** that carried the bullet on 10 ingest-and-reason agents only and rejected blanket coverage on per-run token cost — classification is itself the defect (the judgement is re-made on every new prompt, silently, by whoever adds it), and per-file edit cost is unavoidable either way. Threat model, the write-time fence and the spawn-line notice: `docs/security.md` § Untrusted Content & Prompt Injection. |
|
|
435
|
-
| **Central agent rules (`**Rules:**` bullet)** | every `.bkit/core/prompts/*.md` — no exceptions, no selection step | A single bullet appended to the EXECUTION PROTOCOL block, identical in every file. `.agents/rules.md` is a 2x2: `bkit Rules` and `Project Rules` each split into `Universal Rules` (binds every agent) and `Orchestrator Rules` (workflows / commands only — git, CI, merge, tracker, and human-gate rules a leaf must not act on). The prompt bullet says `FOLLOW ALL \`Universal Rules\`; SKIP \`Orchestrator Rules\``, so a consumer's own universal rules reach leaves while their orchestrator-only rules do not — the split is the consumer's declaration of which is which. Subsection names are shared across the two groups (`Agent Management`, `Git, CI & Merges`); a subsection is omitted only where it has no entry. `.bkit/core/engine/tools/wording.test.ts` enumerates the prompt directory at run time, asserts both groups appear under `bkit Rules`, and fails any orchestrator subsection whose name has no universal counterpart — so a newly added prompt is covered-or-failing by construction and the two groups cannot drift into synonyms. **Assertions stop at `bkit:end`:** everything below it is consumer-owned `Project Rules`, which `bkit install` never writes and `bkit check` ignores, so its shape is never gated — only that the shipped template seeds none of it. **Position is contract:** `**Rules:**` is always the first labelled clause of the CAUTION block and `**External input:**` ALWAYS the last, in every prompt and every workflow — the central set frames what follows, and the untrusted-content fence is the last thing read before the file's own instructions begin. Workflows take the unscoped variant `FOLLOW ALL rules` (they are the orchestrators `Orchestrator Rules` is written for, so nothing is skipped) and carry no separate `.agents/rules.md` pointer above the block — the bullet is the only one. The same unscoped line is the entry-file pointer in `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/bkit-rules.mdc`, un-quoted there (`- **Rules:**`) — those files have no CAUTION block to sit inside. `.bkit/core/engine/tools/wording.test.ts` asserts both anchors (`position: first` / `last` in `.bkit/wording.md`), the order of every positioned header clause in between (`position: header`, in `.bkit/wording.md` order), and that no workflow carries the leaf skip variant (`rules-leaf` is `forbidden` on workflows). **The bullet adds reach; it does not replace inlining, but inlining is a per-rule judgement, not an obligation.** Clauses a prompt still carries inline (`**Order:**`, `**No improv:**`, `**Tools:**`, `**No commits:**` (prompts whose `tools` list holds `Bash`; forbidden without it), `**External input:**`, `**Destructive git PROHIBITED:**`) stay in the file and are also stated centrally — deliberate redundancy, because an execution surface must stand alone if the central read fails, truncates, or is deprioritised, and because prose far from the payload is the weakest placement for the rules injection targets. `**Auto-apply:**` is `rules.md` § `Orchestrator Rules` only — it governs how a workflow drives its own steps, so it is deliberately out of reach of leaves and inlined in no prompt. Leaves get the equivalent from `Recommend, do NOT decide` (`Universal Rules`), which already states that steps inside `/bkit-*` workflows are pre-approved. The central copy is the backstop and the home for every rule not inlined anywhere. |
|
|
436
|
+
| **Central agent rules (`**Rules:**` bullet)** | every `.bkit/core/prompts/*.md` — no exceptions, no selection step | A single bullet appended to the EXECUTION PROTOCOL block, identical in every file. `.agents/rules.md` is a 2x2: `bkit Rules` and `Project Rules` each split into `Universal Rules` (binds every agent) and `Orchestrator Rules` (workflows / commands only — git, CI, merge, tracker, and human-gate rules a leaf must not act on). The prompt bullet says `FOLLOW ALL \`Universal Rules\`; SKIP \`Orchestrator Rules\``, so a consumer's own universal rules reach leaves while their orchestrator-only rules do not — the split is the consumer's declaration of which is which. Subsection names are shared across the two groups (`Agent Management`, `Git, CI & Merges`); a subsection is omitted only where it has no entry. `.bkit/core/engine/tools/wording.test.ts` enumerates the prompt directory at run time, asserts both groups appear under `bkit Rules`, and fails any orchestrator subsection whose name has no universal counterpart — so a newly added prompt is covered-or-failing by construction and the two groups cannot drift into synonyms. **Assertions stop at `bkit:end`:** everything below it is consumer-owned `Project Rules`, which `bkit install` never writes and `bkit check` ignores, so its shape is never gated — only that the shipped template seeds none of it. **Position is contract:** `**Rules:**` is always the first labelled clause of the CAUTION block and `**External input:**` ALWAYS the last, in every prompt and every workflow — the central set frames what follows, and the untrusted-content fence is the last thing read before the file's own instructions begin. Workflows take the unscoped variant `FOLLOW ALL rules` (they are the orchestrators `Orchestrator Rules` is written for, so nothing is skipped) and carry no separate `.agents/rules.md` pointer above the block — the bullet is the only one. The same unscoped line is the entry-file pointer in `CLAUDE.md`, `AGENTS.md`, and `.cursor/rules/bkit-rules.mdc`, un-quoted there (`- **Rules:**`) — those files have no CAUTION block to sit inside. `.bkit/core/engine/tools/wording.test.ts` asserts both anchors (`position: first` / `last` in `.bkit/wording.md`), the order of every positioned header clause in between (`position: header`, in `.bkit/wording.md` order), and that no workflow carries the leaf skip variant (`rules-leaf` is `forbidden` on workflows). **The bullet adds reach; it does not replace inlining, but inlining is a per-rule judgement, not an obligation.** Clauses a prompt still carries inline (`**Code reads:**` (one-line condensation of `rules.md` § `Code reads`), `**Order:**`, `**No improv:**`, `**Tools:**`, `**No commits:**` (prompts whose `tools` list holds `Bash`; forbidden without it), `**External input:**`, `**Destructive git PROHIBITED:**`) stay in the file and are also stated centrally — deliberate redundancy, because an execution surface must stand alone if the central read fails, truncates, or is deprioritised, and because prose far from the payload is the weakest placement for the rules injection targets. `**Auto-apply:**` is `rules.md` § `Orchestrator Rules` only — it governs how a workflow drives its own steps, so it is deliberately out of reach of leaves and inlined in no prompt. Leaves get the equivalent from `Recommend, do NOT decide` (`Universal Rules`), which already states that steps inside `/bkit-*` workflows are pre-approved. The central copy is the backstop and the home for every rule not inlined anywhere. |
|
|
436
437
|
| **`.agents/docs.md` read exemption** | `bkit-utility-compress-markdown` | Single-file mechanical utility — compress prose in one supplied target. No domain reasoning, so the doc catalog earns nothing against its token cost. Every other prompt loads it. |
|
|
437
438
|
| **`acceptEdits` hard requirement** | All in-pipeline agents | `Bash(*)`/`Edit(*)`/`Write(*)` blanket-allow lives in `.claude/settings.json`; `acceptEdits` skips per-call prompts. Stricter modes break end-to-end runs. |
|
|
438
439
|
| **Plan checkbox ticking owned by verify** | `bkit-build-plan-execute` (does not tick), `bkit-build-plan-verify` (ticks `[ ]`→`[x]` only on verified codebase artifact) | Plan-execute runs timed out during the per-task `Edit`-tick phase, after implementation already done. Splitting responsibilities (executor → flat append-only log; verify → checkbox ticks based on verified diff / files) removes ~30 Edit calls from the budget-pressured agent and preserves resume-safety: durable progress record = artifact's `DONE —` lines, plan checkboxes = verify's derived view. never tick checkboxes in `bkit-build-plan-execute`. |
|
|
@@ -22,9 +22,9 @@
|
|
|
22
22
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
23
23
|
| Claude Code | canonical | `.claude/agents/` | `.claude/commands/` | `.claude/settings.json` | `.claude/hooks/` (registered in settings) | `bkit install --claude` |
|
|
24
24
|
| Cursor | derived | `.cursor/agents/` | `.cursor/commands/` | `.cursor/settings.json` + `.cursor/environment.json` + `.cursor/Dockerfile` (templates, `.bkit/templates.md`) | `.cursor/hooks/` (registered in `.cursor/hooks.json`) | `bkit install --cursor` |
|
|
25
|
-
| opencode | additive (opt-in) | `.opencode/agents/` | `.opencode/commands/` | `.opencode/opencode.json` | `.opencode/plugin/bkit-gateguard.js` (
|
|
26
|
-
| Codex CLI | additive (opt-in) | `.codex/agents/` (TOML) | none — skills (below) | none (`openai` = reserved built-in id) | `.codex/hooks/bkit-gateguard.cjs` + `.codex/hooks/bkit-guardrails.cjs` (PreToolUse `apply_patch` / `Bash`, via `.codex/hooks.json`) | `bkit install --codex` |
|
|
27
|
-
| Google Antigravity | additive (opt-in) | `.agents/plugins/bkit/agents/` | none — skills (plugin, below) | `GEMINI.md` (workspace rule) | `.agents/plugins/bkit/hooks/bkit-gateguard.cjs` + `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` (PreToolUse `write_to_file` / `replace_file_content` / `run_command`, via `.agents/plugins/bkit/hooks.json`) | `bkit install --antigravity` |
|
|
25
|
+
| opencode | additive (opt-in) | `.opencode/agents/` | `.opencode/commands/` | `.opencode/opencode.json` | `.opencode/plugin/bkit-gateguard.js` + `.opencode/plugin/bkit-readguard.js` (tool execute hooks) | `bkit install --opencode=<provider>` |
|
|
26
|
+
| Codex CLI | additive (opt-in) | `.codex/agents/` (TOML) | none — skills (below) | none (`openai` = reserved built-in id) | `.codex/hooks/bkit-gateguard.cjs` + `.codex/hooks/bkit-guardrails.cjs` + `.codex/hooks/bkit-readguard.cjs` (PreToolUse `apply_patch` / `Bash`, PreCompact, via `.codex/hooks.json`) | `bkit install --codex` |
|
|
27
|
+
| Google Antigravity | additive (opt-in) | `.agents/plugins/bkit/agents/` | none — skills (plugin, below) | `GEMINI.md` (workspace rule) | `.agents/plugins/bkit/hooks/bkit-gateguard.cjs` + `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` + `.agents/plugins/bkit/hooks/bkit-readguard.cjs` (PreToolUse `write_to_file` / `replace_file_content` / `view_file` / `run_command`, via `.agents/plugins/bkit/hooks.json`) | `bkit install --antigravity` |
|
|
28
28
|
|
|
29
29
|
**Two axes — host != provider.** **Host** = program reading what bkit writes, identified by its dir (`.claude/`, `.cursor/`, `.opencode/`, `.codex/`). **Provider** = gateway tokens are bought through. Model IDs are per-provider → `prompts.md` § Models = one column per PROVIDER (shared provider = one column, never two). Thinking depth is per-host (field name + ladder set by host config format: `effort:` claude/cursor, a `variant:` field opencode, `model_reasoning_effort` codex) → § Effort = one column per HOST. Neither table grows as hosts x providers.
|
|
30
30
|
|
|
@@ -65,7 +65,7 @@ Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-
|
|
|
65
65
|
|
|
66
66
|
> **Antigravity tool names differ from Claude's.** `Read`→`view_file`, `Write`→`write_to_file`, `Edit`→`replace_file_content`, `Bash`→`run_command`, `Grep`→`grep_search`, `Glob`→`list_dir`, `WebSearch`→`search_web`, `WebFetch`→`read_url`. `mcp__<server>__<tool>` keeps its spelling. `applyAntigravityPrompt` / `antigravityToolsBlock` (`.bkit/core/engine/render/hosts.ts`) apply the map at render.
|
|
67
67
|
>
|
|
68
|
-
> **GateGuard + guardrails wired from `.agents/plugins/bkit/hooks.json`** (PreToolUse on `write_to_file` / `replace_file_content` / `run_command`). Same fail-open advisory
|
|
68
|
+
> **GateGuard + ReadGuard + guardrails wired from `.agents/plugins/bkit/hooks.json`** (PreToolUse on `write_to_file` / `replace_file_content` / `view_file` / `run_command`). Same fail-open engines as the other hosts on Antigravity's own contract, live-verified on the agy CLI: stdin `{ conversationId, toolCall: { name, args }, workspacePaths }`, stdout `{ decision, reason }`. Only a `deny`'s reason reaches the model, so every advisory denies the call once with the advisory as the reason and lets the identical retry through; the guardrails deny tier blocks every time; its ask tier is Antigravity's own `ask`. Guardrails also gates `view_file` secret reads (§ Permissions / auto-approve). A `PreInvocation` entry in `hooks.json` stops every hook in the file from firing — bkit registers none. Plugin hook commands run with the plugin dir (`.agents/plugins/bkit/`) as cwd, so each command tries `hooks/<file>` first, then `.agents/plugins/bkit/hooks/<file>`.
|
|
69
69
|
|
|
70
70
|
**Explicit host axis (no implicit full):** `bkit install` requires ≥1 module flag — bare `bkit install` errors. Every host explicit; hosts compose: `bkit install --claude --cursor --opencode=opencode-zen` installs all three (+ implicit core). `--opencode` cannot render without `=<provider>` (strict allowlist). Switch providers: re-run install. All hosts render from `.bkit/`; run state in `status.jsonl` + plan docs + tracker (never host session) — phase/resumed run moves across hosts/providers mid-feature with identical gates + per-agent pins: hit limit on one, continue on another. `bkit status` → installed hosts + active providers; `bkit doctor` → credentials + tool reachability.
|
|
71
71
|
|
|
@@ -75,7 +75,7 @@ Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-
|
|
|
75
75
|
|
|
76
76
|
**Additive multi-provider install:** `bkit install --opencode=<provider>` additive — second provider adds block to `opencode.json`, keeps first. Agent frontmatter (`model:`) re-renders to last-installed (active) provider; other blocks stay for interactive switch/overrides. Installed providers → `bkit.opencodeProviders: string[]` in `package.json`; active → `bkit.opencodeProvider`. `bkit status` lists all, marks active; `bkit doctor` checks all credentials. Remove one: `bkit uninstall --opencode=<provider>` (surgical — block + array; if active removed, re-point via `bkit install --opencode=<new>` or `bkit upgrade`). `bkit uninstall --opencode` (bare) tears down entire opencode host.
|
|
77
77
|
|
|
78
|
-
New host — row above + `run<Host>Module` (`.bkit/core/engine/install/modules/<host>.ts`) + manifest block (`.bkit/core/engine/install/manifest.ts`) + `.bkit/core/.<host>/hooks/` (the host config JSON in `.bkit/shared/.<host>/`) + GateGuard case in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts`. New provider also needs `GATEWAY_COLUMN` (`.bkit/core/engine/render/models.ts`) + a curated `prompts.md` § Models column.
|
|
78
|
+
New host — row above + `run<Host>Module` (`.bkit/core/engine/install/modules/<host>.ts`) + manifest block (`.bkit/core/engine/install/manifest.ts`) + `.bkit/core/.<host>/hooks/` (the host config JSON in `.bkit/shared/.<host>/`) + GateGuard case in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts` + ReadGuard case in `.bkit/core/engine/audits/hooks/readguard-parity.integration.test.ts`. New provider also needs `GATEWAY_COLUMN` (`.bkit/core/engine/render/models.ts`) + a curated `prompts.md` § Models column.
|
|
79
79
|
|
|
80
80
|
---
|
|
81
81
|
|
|
@@ -99,7 +99,7 @@ bkit opencode # /Applications/opencode.app/Contents/MacOS/opencode
|
|
|
99
99
|
|
|
100
100
|
**`bkit doctor` check:** reports `.bkit/.env` keys with non-empty file value but absent from `process.env` (= Dock/Finder session); advisory → `bkit cursor` / `bkit opencode`.
|
|
101
101
|
|
|
102
|
-
**launchctl fallback (opt-in, not recommended):** exposes key to
|
|
102
|
+
**launchctl fallback (opt-in, not recommended):** exposes key to EVERY app in the login session (not only the intended one; not persistent across reboots). Manual re-run after restart + manual rotation/removal — prefer launcher verbs.
|
|
103
103
|
|
|
104
104
|
```bash
|
|
105
105
|
launchctl setenv BKIT_GH_TOKEN "$BKIT_GH_TOKEN"
|
|
@@ -277,15 +277,19 @@ Both hosts: `/<filename-without-ext>` (`/bkit-build`, `/bkit-plan`, etc.). Ident
|
|
|
277
277
|
| --- | --- | --- |
|
|
278
278
|
| `gateguard-engine.js` | Claude, Cursor, Codex, Google Antigravity, opencode `gateguard` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice` |
|
|
279
279
|
| `gateguard-edit-payload.js` | Claude, Cursor `gateguard` | `Edit` / `Write` / `MultiEdit` payload adapter `bkitGateguard(payload)` |
|
|
280
|
+
| `readguard-engine.js` | Claude, Cursor, Codex, Google Antigravity, opencode `readguard` | shell-read parser, line-range log per (session, agent), repeat-read note, `resetReadLog` |
|
|
281
|
+
| `readguard-payload.js` | Claude, Cursor, Codex, Google Antigravity `readguard` | read / shell payload adapter `bkitReadguard(payload)`; compaction event → reset |
|
|
282
|
+
| `antigravity-hook.js` | Google Antigravity `gateguard`, `guardrails`, `readguard` | Antigravity envelope → Claude-family shape (`fromAntigravityPayload`), call signature, deny-once advisory delivery (`adviseOnce`) |
|
|
280
283
|
| `guardrails-shell.js` | Claude, Cursor, Codex, Google Antigravity `guardrails` | segment parsing, curl / wget host allowlist, shell-as-edit-channel detection |
|
|
281
284
|
| `guardrails-tiers.js` | Cursor, Codex, Google Antigravity `guardrails` | deny rules, ask patterns, `classifyShell` precedence |
|
|
285
|
+
| `guardrails-read.js` | Cursor, Google Antigravity `guardrails` | `classifyRead`: deny `*.pem` / `*.p12` / `id_rsa`, ask `.env` / `.env.*` (not `.env.example`) |
|
|
282
286
|
| `preflight-linear.sh` | Claude, Cursor `preflight` | Linear key / issue checks, GraphQL query, `bkit:auto` + terminal-state guards |
|
|
283
287
|
|
|
284
|
-
Per host, outside the parts: Claude `gateguard` / `guardrails` — `require` + `hookSpecificOutput` driver, guardrails advisory-only; Cursor — `{ permission }` output, guardrails
|
|
288
|
+
Per host, outside the parts: Claude `gateguard` / `guardrails` — `require` + `hookSpecificOutput` driver, guardrails advisory-only; Cursor — `{ permission }` output, guardrails `Read|TabRead` path extraction, gateguard workspace-relative path resolve; Codex — `apply_patch` envelope parser, ask tier emitted as advisory; Google Antigravity — `antigravity-hook.js` envelope conversion + deny-once delivery, `{ decision, reason }` driver, `write_to_file` / `replace_file_content` edit tools (path `TargetFile`), `view_file` and `run_command` (`CommandLine`); opencode — ES module, `write` / `edit` / `patch` (`apply_patch`) vocabulary, every `*** Add|Update|Delete File:` / `*** Move to:` target of a `patchText` checked (deny mode blocks if any target is a first touch), checklist appended to the tool result in `execute.after` + throw from `execute.before` to block (2.0 exposes no pre-edit context hook, and stderr does not reach the model); `preflight` — trigger (Claude `LINEAR_ISSUE_ID`, Cursor `is_background_agent` + `.bkit/.runtime-cursor` marker), Claude-only Darwin brew check, `emit_context` shape.
|
|
285
289
|
|
|
286
290
|
### GateGuard
|
|
287
291
|
|
|
288
|
-
Advisory hook, on all five hosts (Claude Code, Cursor, Codex, Google Antigravity, opencode). Claude / Cursor / Codex
|
|
292
|
+
Advisory hook, on all five hosts (Claude Code, Cursor, Codex, Google Antigravity, opencode). Claude / Cursor / Codex inject the checklist pre-edit (PreToolUse); Antigravity denies the first edit of a file once with the checklist as the reason (the only text its hooks deliver to the model) and allows the retry; opencode 2.0 exposes no pre-edit context hook, so it appends the checklist to the tool result in the post-execute hook — the first edit's result, not a pre-edit gate — and reserves the pre-execute hook for deny mode. First file touch per session → investigation checklist; gate-config paths (JS/TS: tsconfig/eslint/prettier/vitest/jest/vale/slop/lint-staged; Python: ruff.toml/.ruff.toml/.flake8/mypy.ini/.mypy.ini/pylintrc/.pylintrc/pytest.ini; Go: golangci; Rust: clippy.toml/.clippy.toml/rustfmt.toml/.rustfmt.toml; mixed-purpose manifests such as package.json, pyproject.toml, setup.cfg, tox.ini are not matched) → "fix code, don't weaken gate" advisory, except under a consumer's `.bkit/templates/` (reference copies; in bkit's own repo, package name `@cbartens/bkit`, that folder is the template source and stays guarded); new-file writes → reuse-over-duplicate nudge; `docs/**.md` (not `docs/plans/`) → density advisory appended. **fail-open**, **subagents included**, dedup `(session, agent, file)` via OS-temp state, 24h TTL.
|
|
289
293
|
|
|
290
294
|
<!-- prettier-ignore -->
|
|
291
295
|
| Host | Implementation | File | Registration |
|
|
@@ -294,36 +298,51 @@ Advisory hook, on all five hosts (Claude Code, Cursor, Codex, Google Antigravity
|
|
|
294
298
|
| opencode | `bkit-gateguard.js` (ESM) | `.opencode/plugin/bkit-gateguard.js` | `.opencode/opencode.json` → `plugin` array, spec `./plugin/bkit-gateguard.js` (config-file-relative; opencode 2.0 reads a bare `.opencode/…` spec as an npm package and fails to load — the plugin also auto-loads from `.opencode/plugin/`) |
|
|
295
299
|
| Cursor | `bkit-gateguard.cjs` (CJS) — managed block generated from the same parts as the Claude twin, so byte-identical | `.cursor/hooks/bkit-gateguard.cjs` | `.cursor/hooks.json` → `preToolUse` (matcher `Write`), no `failClosed` — an advisory hook that fails closed would block the edit it only meant to comment on |
|
|
296
300
|
| Codex | `bkit-gateguard.cjs` (CJS) — Claude's stdin/stdout contract; parses the `apply_patch` envelope for target paths | `.codex/hooks/bkit-gateguard.cjs` | `.codex/hooks.json` → `hooks.PreToolUse` on `apply_patch` |
|
|
297
|
-
| Antigravity | `bkit-gateguard.cjs` (CJS) —
|
|
301
|
+
| Antigravity | `bkit-gateguard.cjs` (CJS) — Antigravity's `{ toolCall, conversationId }` stdin / `{ decision, reason }` stdout; `write_to_file` / `replace_file_content` edit tools, path from `args.TargetFile` | `.agents/plugins/bkit/hooks/bkit-gateguard.cjs` | `.agents/plugins/bkit/hooks.json` → `hooks.PreToolUse` on `write_to_file\|replace_file_content` |
|
|
298
302
|
| Cursor | `bkit-guardrails.cjs` (CJS) — destructive-op / secret-exposure gates, the Cursor equivalent of Claude's `permissions` and opencode's `permission` map | `.cursor/hooks/bkit-guardrails.cjs` | `.cursor/hooks.json` → `beforeShellExecution` + `preToolUse` (`Read\|TabRead`), both `failClosed` |
|
|
299
303
|
|
|
300
304
|
**Ownership:** both GateGuard files — and Cursor's `bkit-guardrails.cjs` — are **markered-text** (slash-comment: `// bkit:start` / `// bkit:end`). bkit owns only the advisory engine between the markers and reconverges it on every install / upgrade; the driver around it — Claude's stdin read + single `emit()`, opencode's exported `plugin` — is consumer-owned from first install onward, so consumer advisories survive upgrades. bkit's block is pure (no stdin, no stdout / stderr, no top-level call): Claude Code parses hook stdout as one JSON document, so two emitters would produce `{...}{...}` and the whole hook's output — bkit's included — is discarded. Marker-less file on upgrade → hash matches a bkit release: replaced wholesale; hash unknown: block appended plus printed wiring instructions. Uninstall strips the block, leaving the consumer's driver working. `bkit-guardrails.cjs` follows the identical split: bkit owns `bkitGuardrails(payload)`, which returns a decision object or `null` for no-opinion, and the consumer owns the stdin read and the single `emit()`.
|
|
301
305
|
|
|
302
306
|
**Modes (env):** unset → advisory _[default]_; `BKIT_GATEGUARD=off` → disabled; `BKIT_GATEGUARD=deny` → deny first touch (checklist as reason), allow retry. `BKIT_ALLOW_CONFIG_EDIT=1` suppresses gate-config advisory.
|
|
303
307
|
|
|
304
|
-
**Subagents:** not exempt on any host
|
|
308
|
+
**Subagents:** not exempt on any host; dedup is per (session, agent, file) wherever the host names the agent. Claude Code — a subagent shares its parent's `session_id`; its `agent_id` keys its own dedup, so it gets its own checklist. opencode — a subagent runs in its own session. Codex — tool payloads carry the parent's `session_id` inside a subagent and no agent id; Cursor — no subagent marker; Antigravity — no native subagents (prompts run in-session; `agy` runs are their own conversation). On Codex and Cursor a subagent editing a file its parent already touched gets no checklist.
|
|
305
309
|
|
|
306
|
-
**Deny mode, per host:** Claude
|
|
310
|
+
**Deny mode, per host:** Claude and Codex `permissionDecision: "deny"` with the checklist as `permissionDecisionReason`; Antigravity `decision: "deny"` with the checklist as `reason` — the same as its advisory mode; Cursor `permission: "deny"` with the checklist as `agent_message` (`user_message` goes to the human, not the model); opencode throws from `execute.before` — the only hook that can block — and appends the checklist to the tool result in `execute.after`, because 2.0 exposes no pre-edit context hook and stderr does not reach the model. Same behaviour, three delivery mechanisms across five hosts; asserted uniformly in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts`.
|
|
307
311
|
|
|
308
|
-
**Divergence budget:** every host's block carries `hooks/gateguard-engine.js` verbatim, and the Claude and Cursor blocks are byte-identical (both test-asserted on the generated hooks). opencode's differs only where the runtime forces it — ES module rather than CJS, tool vocabulary `write`/`edit`/`patch` rather than `Edit`/`Write`/`MultiEdit`. Codex's differs only in its payload — every edit arrives as `apply_patch` with a V4A envelope and no file path, so its block carries the envelope parser. Antigravity's differs
|
|
312
|
+
**Divergence budget:** every host's block carries `hooks/gateguard-engine.js` verbatim, and the Claude and Cursor blocks are byte-identical (both test-asserted on the generated hooks). opencode's differs only where the runtime forces it — ES module rather than CJS, tool vocabulary `write`/`edit`/`patch` rather than `Edit`/`Write`/`MultiEdit`, plus a `patchText` envelope parser for `patch`. Codex's differs only in its payload — every edit arrives as `apply_patch` with a V4A envelope and no file path, so its block carries the envelope parser (Add / Update / Delete / Move-to targets). Antigravity's differs in its tool vocabulary (`write_to_file` / `replace_file_content`), its `TargetFile` extraction and the `antigravity-hook.js` contract part. Every advisory string, gate-config pattern and docs-path rule is identical across all five.
|
|
313
|
+
|
|
314
|
+
### ReadGuard
|
|
315
|
+
|
|
316
|
+
Advisory repeat-read hook, on all five hosts. A read of a line range the same agent already read in this conversation, file unchanged since (same mtime + size), gets a note: use the earlier output; re-read only if it left context (summarised, or read by another agent). Tracks read-tool calls (`offset` / `limit`, `StartLine` / `EndLine`; no limit → first 2000 lines, opencode → whole file) and plain shell reads — `cat FILE`, `sed -n 'A,Bp' FILE`, `head` / `tail` with a line count; pipes, lists, redirects, substitutions, globs and other programs are not tracked. Ranges merge per file; a changed file starts a fresh log. **fail-open**, never blocks, log in OS temp (`bkit-readguard/`), 24h TTL. `BKIT_READGUARD=off` → disabled.
|
|
317
|
+
|
|
318
|
+
<!-- prettier-ignore -->
|
|
319
|
+
| Host | File | Registration | Delivery | Log key | Reset on summary |
|
|
320
|
+
| --- | --- | --- | --- | --- | --- |
|
|
321
|
+
| Claude Code | `.claude/hooks/bkit-readguard.cjs` | `.claude/settings.json` → `PreToolUse` (`Read\|Bash`) + `PreCompact` | `additionalContext`, before the read | `session_id` + `agent_id` | `PreCompact` |
|
|
322
|
+
| Cursor | `.cursor/hooks/bkit-readguard.cjs` | `.cursor/hooks.json` → `preToolUse` (`Read\|Shell`) + `preCompact`, no `failClosed` | `additional_context` on an allow, before the read | `conversation_id` | `preCompact` |
|
|
323
|
+
| Codex | `.codex/hooks/bkit-readguard.cjs` | `.codex/hooks.json` → `PreToolUse` (`Bash`) + `PreCompact` | `additionalContext`, before the read | `session_id` | `PreCompact` |
|
|
324
|
+
| Antigravity | `.agents/plugins/bkit/hooks/bkit-readguard.cjs` | `.agents/plugins/bkit/hooks.json` → `PreToolUse` (`view_file\|run_command`) | deny once with the note as `reason`, before the read; the identical retry passes | `conversationId` | none — no compaction hook |
|
|
325
|
+
| opencode | `.opencode/plugin/bkit-readguard.js` | `.opencode/opencode.json` → `plugin` array | appended to the tool result in `execute.after`, after the read | `sessionID` | 1.x `session.compacted` event; 2.0 none — no event subscription for plugins |
|
|
326
|
+
|
|
327
|
+
**Gaps:** Codex has no read tool, so shell reads only. Codex, Cursor and Antigravity tool payloads carry no subagent id, and Codex subagents share the parent `session_id`, so a subagent can be told about its parent's read — the note's re-read clause covers it. Antigravity and opencode 2.0 never reset on a summary — same clause. opencode's note arrives with the repeated read, not before it; Antigravity's costs one extra call (the retry). Shared code: `readguard-engine.js` everywhere, `readguard-payload.js` on the four CJS hosts plus `antigravity-hook.js` on Antigravity; the Claude, Cursor and Codex managed blocks are byte-identical (test-asserted in `.bkit/core/engine/audits/hooks/readguard-parity.integration.test.ts`). Ownership as § GateGuard.
|
|
309
328
|
|
|
310
329
|
---
|
|
311
330
|
|
|
312
331
|
## Permissions / auto-approve
|
|
313
332
|
|
|
314
333
|
<!-- prettier-ignore -->
|
|
315
|
-
| Concern | Claude | Cursor | opencode |
|
|
316
|
-
| --- | --- | --- | --- |
|
|
317
|
-
| File / secrets | `.claude/settings.json` → `permissions.{allow,deny,ask}` (`Read(./**/*.pem)` deny; `.env` variants ask; `.env.example` allow) | `.cursor/hooks/bkit-guardrails.cjs` via `preToolUse` (`Read\|TabRead`) — same deny/ask policy | `.opencode/opencode.json` → `permission.read` map |
|
|
318
|
-
| Shell / destructive | `permissions.deny` / `ask` on force-push (not `--force-with-lease`), `rm -rf /*`, publish, destructive git/gh, etc. Shell `curl` / `wget` are not gated here — `permissions` cannot match a URL host, so only the `WebFetch` TOOL is allowlisted | `.cursor/hooks/bkit-guardrails.cjs` via `beforeShellExecution` — same deny/ask policy | `permission.bash` deny/ask map (same rules) |
|
|
319
|
-
| Network fetch | `WebSearch` + tooling `WebFetch(domain:…)`; install/upgrade enriches from the shipped egress registry union consumer `allowed-domains` in `.agents/context.md` (stack hosts never shipped), recording what it wrote so it can later prune it | `curl`/`wget` ask unless host ∈ `.cursor/allowlist.json` (tooling ∪ consumer domains) | `websearch` allow; `webfetch` URL map (`"*": ask` → `*{domain}*: allow`) for the fetch tool **and** `curl *`/`wget *` ask → `curl *{domain}*`/`wget *{domain}*` allow for shell, from the same allowlist (baked into `opencode.json`) |
|
|
320
|
-
| Granularity | Per-tool glob | Hook script (project-scoped, failClosed) | Per-path / per-command glob in `permission` |
|
|
321
|
-
| Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` | Implicit per-mode (Composer / Agent / Background) | `opencode --auto` + permission defaults |
|
|
322
|
-
| MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` |
|
|
323
|
-
| MCP tool approval | `permissions.allow` `mcp__<s>__*` from consumer `mcp-servers` (§ MCP servers) | Generated `.cursor/cli.json` `Mcp(<s>:*)` | `permission` `"<s>_*": "allow"` |
|
|
324
|
-
| Local-only (not shipped) | `.claude/settings.local.json` (`additionalDirectories`, extra allows) | Cursor project/user settings / MCP as needed | `~/.config/opencode/opencode.json` → `permission.external_directory` |
|
|
334
|
+
| Concern | Claude | Cursor | opencode | Codex | Antigravity |
|
|
335
|
+
| --- | --- | --- | --- | --- | --- |
|
|
336
|
+
| File / secrets | `.claude/settings.json` → `permissions.{allow,deny,ask}` (`Read(./**/*.pem)` deny; `.env` variants ask; `.env.example` allow) | `.cursor/hooks/bkit-guardrails.cjs` via `preToolUse` (`Read\|TabRead`) — same deny/ask policy | `.opencode/opencode.json` → `permission.read` map | **none** — no file-read tool (reads run through `Bash`); `bkit-guardrails.cjs` gates shell tiers only, so `cat .env` passes. Deferral `codex-read-tier-gates-not-wired-file-read-tool-name-unverified` | `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` via `PreToolUse` (`view_file`, path `AbsolutePath`) — same deny/ask policy; ask = Antigravity's own `ask`. Shell reads (`cat .env`) ungated |
|
|
337
|
+
| Shell / destructive | `permissions.deny` / `ask` on force-push (not `--force-with-lease`), `rm -rf /*`, publish, destructive git/gh, etc. Shell `curl` / `wget` are not gated here — `permissions` cannot match a URL host, so only the `WebFetch` TOOL is allowlisted | `.cursor/hooks/bkit-guardrails.cjs` via `beforeShellExecution` — same deny/ask policy | `permission.bash` deny/ask map (same rules) | `.codex/hooks/bkit-guardrails.cjs` via `PreToolUse` (`Bash`) — deny blocks; ask emitted as advisory `additionalContext`, command runs (Codex cannot prompt) | same hook via `PreToolUse` (`run_command`) — deny blocks every time; ask = Antigravity's own `ask` |
|
|
338
|
+
| Network fetch | `WebSearch` + tooling `WebFetch(domain:…)`; install/upgrade enriches from the shipped egress registry union consumer `allowed-domains` in `.agents/context.md` (stack hosts never shipped), recording what it wrote so it can later prune it | `curl`/`wget` ask unless host ∈ `.cursor/allowlist.json` (tooling ∪ consumer domains) | `websearch` allow; `webfetch` URL map (`"*": ask` → `*{domain}*: allow`) for the fetch tool **and** `curl *`/`wget *` ask → `curl *{domain}*`/`wget *{domain}*` allow for shell, from the same allowlist (baked into `opencode.json`) | `curl`/`wget` off `.cursor/allowlist.json` → advisory `additionalContext`, command runs | `curl`/`wget` off `.cursor/allowlist.json` → denied once with the advisory, retry passes; `read_url` / `search_web` ungated |
|
|
339
|
+
| Granularity | Per-tool glob | Hook script (project-scoped, failClosed) | Per-path / per-command glob in `permission` | Hook script (project-scoped, fail-open; fires only once `.codex/` is trusted) | Hook script (workspace plugin, fail-open) |
|
|
340
|
+
| Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` | Implicit per-mode (Composer / Agent / Background) | `opencode --auto` + permission defaults | host defaults — bkit writes no `.codex/config.toml` | host defaults — bkit ships none |
|
|
341
|
+
| MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` | none written | none written |
|
|
342
|
+
| MCP tool approval | `permissions.allow` `mcp__<s>__*` from consumer `mcp-servers` (§ MCP servers) | Generated `.cursor/cli.json` `Mcp(<s>:*)` | `permission` `"<s>_*": "allow"` | none — no project-level MCP approval file | none written |
|
|
343
|
+
| Local-only (not shipped) | `.claude/settings.local.json` (`additionalDirectories`, extra allows) | Cursor project/user settings / MCP as needed | `~/.config/opencode/opencode.json` → `permission.external_directory` | `~/.codex/config.toml` | user-level settings |
|
|
325
344
|
|
|
326
|
-
**Install behaviour:** template drops, host-specific encoding of the **same** shared policy. No single canonical JSON —
|
|
345
|
+
**Install behaviour:** template drops, host-specific encoding of the **same** shared policy. No single canonical JSON — each host's native form kept in lockstep; asserted in `.bkit/core/engine/install/modules/index.integration.test.ts` § permissions-parity. Machine-local paths stay out of templates.
|
|
327
346
|
|
|
328
347
|
### Network allowlist — one source, five hosts
|
|
329
348
|
|
|
@@ -335,10 +354,10 @@ Advisory hook, on all five hosts (Claude Code, Cursor, Codex, Google Antigravity
|
|
|
335
354
|
| Host | Where the allowlist lives | Why that shape |
|
|
336
355
|
| --- | --- | --- |
|
|
337
356
|
| **Claude** | `.claude/settings.json` `WebFetch(domain:…)` allow rules; shell fetches host-checked by `.claude/hooks/bkit-guardrails.cjs` (advisory) | Claude has a first-class settings permission model. No separate allowlist file. Shell `curl` is not domain-gated at all — Claude rules match a command prefix, not a URL host, so `curl` runs under `Bash(*)` with `deny` + the auto-mode classifier as backstops. Prefer `WebFetch` for allowlisted hosts; context-fetch uses `curl` / CLI under `Bash(*)`. |
|
|
338
|
-
| **OpenCode** | Baked into `.opencode/opencode.json`: `permission.webfetch` URL map (`"*": "ask"` then `*{domain}*: allow`) for the fetch tool, and `permission.bash` `curl *`/`wget *` **ask** then `curl *{domain}*`/`wget *{domain}*` **allow** for shell fetch (last-match-wins on both) | Both fetch surfaces are domain-gated, so an allowlisted host does not prompt whichever path the agent takes. `webfetch` matches the resource against the requested URL, `bash` against the command string. No separate allowlist file. |
|
|
357
|
+
| **OpenCode** | Baked into `.opencode/opencode.json`: `permission.webfetch` URL map (`"*": "ask"` then `*{domain}*: allow`) for the fetch tool, and `permission.bash` `curl *`/`wget *` **ask** then `curl *{domain}*`/`wget *{domain}*` **allow** for shell fetch (last-match-wins on both) | Both fetch surfaces are domain-gated, so an allowlisted host does not prompt whichever path the agent takes. `webfetch` matches the resource against the requested URL, `bash` against the command string. **Looser than Claude's `domain:`:** OpenCode globs match the whole string (`*` → `.*`, crossing `/` `?` `@`), so `*{domain}*` allows the domain anywhere in the URL or command — apex and every subdomain, but also `https://evil.tld/?x={domain}`. Accepted risk: no OpenCode glob covers subdomains without it. No separate allowlist file. |
|
|
339
358
|
| **Cursor** | Generated `.cursor/allowlist.json` read at **runtime** by `.cursor/hooks/bkit-guardrails.cjs` | Cursor has no project settings equivalent to Claude `permissions` / OpenCode `permission` for curl host globs. Parity is a **hook** (`beforeShellExecution`): ask on `curl`/`wget` unless the command contains a host from the allowlist. The JSON is Cursor-only by design (IDE-scoped artifact under `.cursor/`, not `.bkit/`). |
|
|
340
359
|
| **Codex** | Reads the same `.cursor/allowlist.json` at runtime via `.codex/hooks/bkit-guardrails.cjs` | Codex has no project-level permission file. The hook host-parses `curl`/`wget` and emits an advisory `ask` — Codex cannot prompt, so the allowlist informs rather than enforces. |
|
|
341
|
-
| **Antigravity** | Reads the same `.cursor/allowlist.json` at runtime via `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` | Antigravity has no project-level permission file. The hook host-parses `curl`/`wget` on the `run_command` matcher and
|
|
360
|
+
| **Antigravity** | Reads the same `.cursor/allowlist.json` at runtime via `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` | Antigravity has no project-level permission file. The hook host-parses `curl`/`wget` on the `run_command` matcher and denies a non-allowlisted fetch once with the advisory as the reason; the retry passes. |
|
|
342
361
|
|
|
343
362
|
**Do not hand-edit** `.cursor/allowlist.json` — regenerate via install/upgrade after changing `allowed-domains`. Missing file ⇒ the hook resolves no hosts and every host reads as unknown; there is deliberately no list embedded in the hook, because a second copy drifts from the registry silently.
|
|
344
363
|
|
|
@@ -369,12 +388,59 @@ Both hosts: same `mcpServers` shape; files differ:
|
|
|
369
388
|
|
|
370
389
|
Both: `"type": "http"`, `"url": "https://api.githubcopilot.com/mcp/"`, `"headers": { "Authorization": "Bearer ${BKIT_GH_TOKEN}" }`. `${BKIT_GH_TOKEN}` at session start — must be in shell (local) or dashboard env (cloud). See `.bkit/cloud.md` § MCP issue-tracker integration for full JSON.
|
|
371
390
|
|
|
372
|
-
**bkit owns one entry per file.** In `.mcp.json` / `.cursor/mcp.json` bkit owns only `mcpServers.<tracker>`: an absent file gets the tracker-filtered render; in an existing file install and upgrade reset that one entry to the template and keep every other key, in its order (malformed JSON stops the install). `bkit check` reports a pending reset. Tracker `none` owns no entry. A tracker switch (e.g. `--tracker=linear` → `--tracker=github`) adds the new entry and leaves the old one. Uninstall removes bkit's entry while it still equals the template. Advisories: `mcp-missing-server-<name>` (file lacks
|
|
391
|
+
**bkit owns one entry per file.** In `.mcp.json` / `.cursor/mcp.json` bkit owns only `mcpServers.<tracker>`: an absent file gets the tracker-filtered render; in an existing file install and upgrade reset that one entry to the template and keep every other key, in its order (malformed JSON stops the install). `bkit check` reports a pending reset. Tracker `none` owns no entry. A tracker switch (e.g. `--tracker=linear` → `--tracker=github`) adds the new entry and leaves the old one. Uninstall removes bkit's entry while it still equals the template. Advisories: `mcp-missing-server-<name>` (file lacks the configured tracker's server; `none` needs none), `mcp-extra-server-<name>` (`linear` entry while the configured tracker is not `linear`; also checked in `.opencode/opencode.json` `mcp`). `github` never flagged as extra: every phase workflow's gh MCP fallback (PR / CI / merge when `gh` is unavailable) calls it — under `linear` / `none`, add it by hand to keep that fallback. Consumer-added MCP servers never flagged.
|
|
373
392
|
|
|
374
393
|
> Note: `mcpServers` in `.claude/settings.json` silently ignored for server defs — only `.mcp.json` (project) or `claude mcp add` (user) take effect. Tool-permission `allow` (`mcp__github__*`) remain in settings.
|
|
375
394
|
|
|
376
395
|
---
|
|
377
396
|
|
|
397
|
+
## Context compaction
|
|
398
|
+
|
|
399
|
+
bkit ships no compaction setting; each host auto-summarises near the model's full window by default. To summarise earlier (e.g. 300,000 tokens), set it per host below. Effective threshold = min(setting, model window).
|
|
400
|
+
|
|
401
|
+
<!-- prettier-ignore -->
|
|
402
|
+
| Host | Setting | Subagents | Notes |
|
|
403
|
+
| --- | --- | --- | --- |
|
|
404
|
+
| Claude Code | `.claude/settings.json` → `"autoCompactWindow": 300000` (range 100,000–1,000,000 or `"auto"`) — install / upgrade keep keys bkit does not own | inherit it; agent files also accept `autoCompactWindow` frontmatter | per person: `.claude/settings.local.json`; env `CLAUDE_CODE_AUTO_COMPACT_WINDOW` beats every settings file |
|
|
405
|
+
| Codex CLI | `.codex/config.toml` → `model_auto_compact_token_limit = 300000`, above the first `[table]` header (below one, the key belongs to that table and does nothing) | inherit it (agent role files drop the key) | read only once the project is trusted; one run: `codex -c model_auto_compact_token_limit=N`; above 90% of the model window, Codex uses 90% |
|
|
406
|
+
| opencode | none — no absolute-count trigger. Auto-compaction fires at the model's input (else context) limit minus `compaction.buffer` (default 10%, min 16,000) | same settings | per model: `providers.<id>.models.<model>.limit.input` (or `limit.context` when the catalog gives no input limit) ≈ target + buffer. Not `compaction.buffer`: one global buffer large enough for a 1M model goes negative on 128k–200k models and compacts before nearly every call |
|
|
407
|
+
| Cursor | none — trigger fixed server-side | — | manual `/summarize` |
|
|
408
|
+
| Google Antigravity | none — threshold internal, no setting / env reaches it | — | manual `/compact` |
|
|
409
|
+
|
|
410
|
+
**Floor:** keep the window well above the largest single tool result plus the recent turns kept after a summary. Claude Code ends an agent whose context refills to the limit within 3 turns of a summary, 3 times in a row (`Autocompact is thrashing`).
|
|
411
|
+
|
|
412
|
+
**Compression proxies:** bkit ships none (caveman, Headroom). On 456 real Claude Code transcripts they saved ~1–3% of token cost: both keep the prompt cache intact, so each tool result is compressed once on arrival and reused, and tool results ≥ 2 KB are 27% of cost. Headroom's Kompress text model rewrote code (`=> void` → `void`). Method, results, scripts to measure own sessions: [comparison](https://github.com/cbartens/bkit/blob/main/tests/compression/bkit-caveman-headroom-compression-proxy-comparison.md). bkit cuts reading instead, losslessly: § ReadGuard + `Code reads` / `Narrow text search first` in `.agents/rules.md`.
|
|
413
|
+
|
|
414
|
+
## MCP project scope
|
|
415
|
+
|
|
416
|
+
A remote MCP server that can see a whole account makes agents look up account and project IDs before every task. Lock its URL to one project and those lookup tools disappear; calls default to that project. Lock it in every host file that declares the server (`.mcp.json`, `.cursor/mcp.json`, `.opencode/opencode.json`, `.codex/config.toml`).
|
|
417
|
+
|
|
418
|
+
<!-- prettier-ignore -->
|
|
419
|
+
| Service | Locked URL | Effect |
|
|
420
|
+
| --- | --- | --- |
|
|
421
|
+
| Sentry | `https://mcp.sentry.dev/mcp/<org>/<project>` | `find_organizations` / `find_projects` hidden |
|
|
422
|
+
| Supabase | `https://mcp.supabase.com/mcp?project_ref=<ref>&read_only=true` | `list_projects` hidden; `read_only` runs SQL as a read-only database user |
|
|
423
|
+
| Vercel | `https://mcp.vercel.com/<team>/<project>` | calls default to that team and project |
|
|
424
|
+
|
|
425
|
+
Only servers in the repo's own files lock this way; claude.ai connectors cannot be locked per repo (§ claude.ai connectors). The `mcp-scope` setup tip fires on an unlocked URL for a service in this table.
|
|
426
|
+
|
|
427
|
+
## claude.ai connectors
|
|
428
|
+
|
|
429
|
+
Claude Code loads every connector on the person's claude.ai account in every repo, and re-sends their tool names on every request whether used or not. `"disableClaudeAiConnectors": true` in `.claude/settings.json` stops that for the repo.
|
|
430
|
+
|
|
431
|
+
<!-- prettier-ignore -->
|
|
432
|
+
| Aspect | Detail |
|
|
433
|
+
| --- | --- |
|
|
434
|
+
| Stops | claude.ai connectors in Claude Code sessions for this repo — terminal and desktop app |
|
|
435
|
+
| Keeps | the repo's `.mcp.json` servers (bkit's tracker server included), `claude mcp add` servers, and the connectors themselves in claude.ai / desktop-app chats and cloud routines |
|
|
436
|
+
| Before | move anything agents reach through a connector onto `.mcp.json` (§ MCP project scope), a context-fetch block or the provider CLI |
|
|
437
|
+
| Per person | `false` in `.claude/settings.local.json` turns connectors back on |
|
|
438
|
+
| Verify | `/context` before and after |
|
|
439
|
+
|
|
440
|
+
bkit ships no default: the setting also hides each person's own connectors (mail, drive, …), and install / upgrade keep keys bkit does not own, so a shipped `true` could not be turned off in `.claude/settings.json`. The `claude-connectors` setup tip fires on a Claude Code repo that sets neither value.
|
|
441
|
+
|
|
442
|
+
---
|
|
443
|
+
|
|
378
444
|
## Runtime environment (cloud agents)
|
|
379
445
|
|
|
380
446
|
> Setup recipe + alignment: `.bkit/cloud.md`. This section = host-diff matrix only.
|