@cbartens/bkit 5.0.3 → 5.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +14 -10
- package/.bkit/core/.agents/docs.md +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +93 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +137 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
- package/.bkit/core/.agents/rules.md +10 -6
- package/.bkit/core/.agents/shortcuts.md +73 -0
- package/.bkit/core/.agents/skills.md +5 -3
- package/.bkit/core/.bkit/LICENSE.md +18 -140
- package/.bkit/core/.bkit/README.md +13 -9
- package/.bkit/core/.bkit/cloud.md +12 -15
- package/.bkit/core/.bkit/comparison.md +68 -16
- package/.bkit/core/.bkit/install.md +36 -11
- package/.bkit/core/.bkit/jsonl.md +0 -1
- package/.bkit/core/.bkit/prompts.md +83 -81
- package/.bkit/core/.bkit/providers.md +110 -28
- package/.bkit/core/.bkit/templates.md +42 -13
- package/.bkit/core/.bkit/workflows.md +64 -42
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
- package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
- package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
- package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
- package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
- package/.bkit/core/AGENTS.md +11 -0
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
- package/.bkit/core/docs/templates/bkit-plan.md +6 -3
- package/.bkit/core/engine/checks/after/auth.ts +32 -0
- package/.bkit/core/engine/checks/after/github.ts +4 -4
- package/.bkit/core/engine/checks/after/index.ts +36 -50
- package/.bkit/core/engine/checks/after/managed.ts +44 -1
- package/.bkit/core/engine/checks/before/index.ts +5 -4
- package/.bkit/core/engine/checks/before/mcp.ts +60 -54
- package/.bkit/core/engine/checks/status-holes.ts +1 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
- package/.bkit/core/engine/checks/tips/detect.ts +144 -0
- package/.bkit/core/engine/checks/tips/index.ts +174 -0
- package/.bkit/core/engine/cli.ts +82 -18
- package/.bkit/core/engine/commands/install/check.ts +2 -0
- package/.bkit/core/engine/commands/install/doctor.ts +14 -1
- package/.bkit/core/engine/commands/install/install.ts +59 -9
- package/.bkit/core/engine/commands/install/uninstall.ts +59 -34
- package/.bkit/core/engine/commands/install/upgrade.ts +30 -28
- package/.bkit/core/engine/commands/launch.ts +33 -11
- package/.bkit/core/engine/commands/tips.ts +16 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +20 -2
- package/.bkit/core/engine/commands/workflow/runs.ts +82 -18
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
- package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
- package/.bkit/core/engine/install/cloud-env.ts +7 -21
- package/.bkit/core/engine/install/hosts.ts +21 -0
- package/.bkit/core/engine/install/managed-block.ts +36 -0
- package/.bkit/core/engine/install/manifest.ts +83 -5
- package/.bkit/core/engine/install/modules/antigravity.ts +266 -0
- package/.bkit/core/engine/install/modules/claude.ts +6 -6
- package/.bkit/core/engine/install/modules/cloud.ts +2 -2
- package/.bkit/core/engine/install/modules/codex.ts +8 -5
- package/.bkit/core/engine/install/modules/core.ts +30 -10
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/index.ts +33 -6
- package/.bkit/core/engine/install/modules/opencode.ts +4 -4
- package/.bkit/core/engine/install/payload-links.ts +6 -10
- package/.bkit/core/engine/install/placeholders.ts +1 -1
- package/.bkit/core/engine/install/version-file.ts +17 -9
- package/.bkit/core/engine/install/write.ts +68 -1
- package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
- package/.bkit/core/engine/render/hosts.ts +174 -1
- package/.bkit/core/engine/render/models.ts +10 -0
- package/.bkit/core/engine/shared/package-roots.ts +8 -10
- package/.bkit/core/hooks/antigravity-hook.js +67 -0
- package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
- package/.bkit/core/hooks/gateguard-engine.js +16 -6
- package/.bkit/core/hooks/guardrails-read.js +23 -0
- package/.bkit/core/hooks/readguard-engine.js +259 -0
- package/.bkit/core/hooks/readguard-payload.js +67 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-1.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-2.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +2 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +2 -1
- package/.bkit/core/prompts/bkit-build-install-skills.md +7 -5
- package/.bkit/core/prompts/bkit-build-plan-current.md +2 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +6 -2
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +2 -1
- package/.bkit/core/prompts/bkit-build-plan-verify.md +12 -4
- package/.bkit/core/prompts/bkit-build-summary.md +2 -1
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -1
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +2 -1
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +2 -1
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +2 -1
- package/.bkit/core/prompts/bkit-debug-summary.md +2 -1
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +2 -1
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +2 -1
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +2 -1
- package/.bkit/core/prompts/bkit-design-generate.md +10 -5
- package/.bkit/core/prompts/bkit-design-organise.md +2 -1
- package/.bkit/core/prompts/bkit-design-review-1.md +2 -1
- package/.bkit/core/prompts/bkit-design-review-2.md +2 -1
- package/.bkit/core/prompts/bkit-design-spike.md +2 -1
- package/.bkit/core/prompts/bkit-design-summary.md +2 -1
- package/.bkit/core/prompts/bkit-design-update.md +2 -1
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +2 -1
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +4 -3
- package/.bkit/core/prompts/bkit-plan-generate.md +2 -1
- package/.bkit/core/prompts/bkit-plan-review-1.md +2 -1
- package/.bkit/core/prompts/bkit-plan-review-2.md +2 -1
- package/.bkit/core/prompts/bkit-plan-review-3.md +2 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +3 -2
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +3 -2
- package/.bkit/core/prompts/bkit-plan-summary.md +2 -1
- package/.bkit/core/prompts/bkit-plan-update.md +3 -2
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +2 -1
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +2 -1
- package/.bkit/core/prompts/bkit-ship-summary.md +2 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +2 -1
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-failures.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -3
- package/.bkit/core/workflows/bkit-auto.md +1 -1
- package/.bkit/core/workflows/bkit-build.md +35 -21
- package/.bkit/core/workflows/bkit-debug.md +31 -22
- package/.bkit/core/workflows/bkit-design.md +83 -38
- package/.bkit/core/workflows/bkit-plan.md +10 -2
- package/.bkit/core/workflows/bkit-ship.md +10 -2
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +36 -0
- package/.bkit/shared/.agents/plugins/bkit/plugin.json +5 -0
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.codex/hooks.json +21 -0
- package/.bkit/shared/.cursor/hooks.json +6 -1
- package/.bkit/shared/.opencode/opencode.json +1 -1
- package/.bkit/shared/GEMINI.md +11 -0
- package/.bkit/shared/docs/deployments.md +1 -1
- package/.bkit/shared/docs/security.md +3 -3
- package/.bkit/shared/docs/testing.md +12 -1
- package/.bkit/templates/.github/dependabot.yml +6 -0
- package/.bkit/templates/.github/renovate.json5 +3 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +24 -13
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
- package/.bkit/templates/.prettierignore +4 -1
- package/.bkit/templates/context/bkit-expo.md +22 -13
- package/.bkit/templates/context/bkit-github.md +20 -6
- package/.bkit/templates/context/bkit-inngest.md +10 -4
- package/.bkit/templates/context/bkit-maestro.md +5 -5
- package/.bkit/templates/context/bkit-playwright.md +3 -3
- package/.bkit/templates/context/bkit-sentry.md +6 -5
- package/.bkit/templates/context/bkit-stripe.md +31 -8
- package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
- package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +2 -2
- package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
- package/.bkit/templates/slop-scan.config.json +10 -3
- package/CHANGELOG.md +62 -0
- package/LICENSE.md +21 -161
- package/README.md +66 -35
- package/dist/checks/after/auth.js +28 -0
- package/dist/checks/after/github.js +4 -4
- package/dist/checks/after/index.js +29 -45
- package/dist/checks/after/managed.js +41 -1
- package/dist/checks/before/index.js +5 -4
- package/dist/checks/before/mcp.js +53 -53
- package/dist/checks/status-holes.js +1 -1
- package/dist/checks/tips/catalogue.js +297 -0
- package/dist/checks/tips/detect.js +130 -0
- package/dist/checks/tips/index.js +146 -0
- package/dist/cli.js +68 -17
- package/dist/commands/install/check.js +2 -0
- package/dist/commands/install/doctor.js +9 -1
- package/dist/commands/install/install.js +49 -8
- package/dist/commands/install/uninstall.js +61 -34
- package/dist/commands/install/upgrade.js +31 -33
- package/dist/commands/launch.js +27 -11
- package/dist/commands/tips.js +10 -0
- package/dist/commands/workflow/prs.js +13 -1
- package/dist/commands/workflow/runs.js +74 -18
- package/dist/commands/workflow/runtime.js +8 -0
- package/dist/commands/workflow/steps.js +1 -0
- package/dist/commands/workflow/tests.js +541 -4
- package/dist/commands/workflow/workstreams.js +4 -4
- package/dist/install/cloud-env.js +3 -14
- package/dist/install/hosts.js +22 -0
- package/dist/install/managed-block.js +36 -0
- package/dist/install/manifest.js +79 -4
- package/dist/install/modules/antigravity.js +225 -0
- package/dist/install/modules/claude.js +6 -6
- package/dist/install/modules/cloud.js +2 -2
- package/dist/install/modules/codex.js +8 -5
- package/dist/install/modules/core.js +21 -6
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/index.js +17 -6
- package/dist/install/modules/opencode.js +4 -4
- package/dist/install/payload-links.js +5 -5
- package/dist/install/placeholders.js +1 -1
- package/dist/install/version-file.js +12 -3
- package/dist/install/write.js +61 -2
- package/dist/render/hosts.js +149 -1
- package/dist/render/models.js +9 -0
- package/dist/shared/package-roots.js +8 -11
- package/package.json +8 -8
- package/.bkit/core/LICENSE.md +0 -149
- package/.bkit/shared/LICENSE.md +0 -22
- package/.bkit/templates/LICENSE.md +0 -22
|
@@ -22,8 +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` |
|
|
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` |
|
|
27
28
|
|
|
28
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.
|
|
29
30
|
|
|
@@ -35,6 +36,7 @@
|
|
|
35
36
|
| Claude Code | `anthropic` | Claude subscription = cheapest path to Claude models |
|
|
36
37
|
| Cursor | `cursor` | Cursor subscription covers its whole catalog |
|
|
37
38
|
| Codex CLI | `openai` | ChatGPT subscription |
|
|
39
|
+
| Google Antigravity | `google` | Antigravity free tier / Google subscription — cheapest path to Gemini |
|
|
38
40
|
| opencode | **pick one**: `openrouter`, `ollama`, `opencode-zen`, `opencode-go` | no subscription — BYO key, so the choice is yours |
|
|
39
41
|
|
|
40
42
|
Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-key host → pluggable, flag names the provider (`--opencode=<provider>`). Per-model deviation → consumer `## Model Overrides` below `bkit:end`; no provider override.
|
|
@@ -45,13 +47,26 @@ Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-
|
|
|
45
47
|
| Concern | On Codex |
|
|
46
48
|
| --- | --- |
|
|
47
49
|
| Agent files | `.codex/agents/*.toml` (TOML, not markdown). Required: `name`, `description`, `developer_instructions`. Pin + rung: `model`, `model_reasoning_effort`. |
|
|
48
|
-
| Workflows = SKILLS, invoked `$bkit-design` | no project-scoped command surface — custom prompts are `~/.codex/prompts` only, not repo-shared, deprecated for skills (upstream declined repo-scoped prompts). bkit renders `.agents/skills/bkit-<workflow>/SKILL.md`, on Codex's skill path (`$REPO_ROOT/.agents/skills`).
|
|
50
|
+
| Workflows = SKILLS, invoked `$bkit-design` | no project-scoped command surface — custom prompts are `~/.codex/prompts` only, not repo-shared, deprecated for skills (upstream declined repo-scoped prompts). bkit renders `.agents/skills/bkit-<workflow>/SKILL.md`, on Codex's skill path (`$REPO_ROOT/.agents/skills`). This path is Codex's; Antigravity ships its own skills in a plugin (`.agents/plugins/bkit/skills/`). |
|
|
49
51
|
| `tools:` not enforced | No per-agent tool allowlist upstream; `sandbox_mode` cannot substitute — every bkit agent is write-capable, so all would be `workspace-write`. Each agent gets the full built-in tool set regardless of declared `tools:`. GateGuard still gates, as everywhere. |
|
|
50
52
|
|
|
51
53
|
> **GateGuard needs the `.codex/` layer TRUSTED.** Codex loads project-local hooks only once trusted. Until then the hook is installed and never fires — present, proving nothing. Same for `bkit-guardrails.cjs`.
|
|
52
54
|
>
|
|
53
55
|
> **Codex cannot prompt.** It parses `permissionDecision: "ask"` but does not implement it — an ask is recorded as an error and the call proceeds. `bkit-guardrails.cjs` therefore blocks the `deny` tier for real and emits the `ask` tier as advisory `additionalContext`: the gate fires and informs, it cannot stop the command. Every ask-tier command is already PROHIBITED in all five workflow headers, so no bkit workflow reaches one. Asserted in `.bkit/core/engine/install/modules/index.integration.test.ts`.
|
|
54
56
|
|
|
57
|
+
### Google Antigravity — installs as a workspace plugin
|
|
58
|
+
|
|
59
|
+
<!-- prettier-ignore -->
|
|
60
|
+
| Concern | On Antigravity |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| Install layout | the whole host is a workspace **plugin** at `.agents/plugins/bkit/` (`plugin.json` + `skills/` + `agents/` + `hooks.json` + `hooks/`) — Antigravity's own packaging surface, activated per project. `.agents/` root stays the dedicated Codex install. |
|
|
63
|
+
| Workflows = SKILLS at `.agents/plugins/bkit/skills/bkit-<workflow>/SKILL.md` | Antigravity auto-discovers a workspace plugin's `skills/`. Codex's workflow skills stay at `.agents/skills/bkit-*/`; with both hosts installed Antigravity's selector lists both sets (accepted; `antigravity-codex-skill-overlap` advisory names which to pick). |
|
|
64
|
+
| Prompt files + no native subagent tool | prompts at `.agents/plugins/bkit/agents/*.md` — frontmatter `name`/`description`, model pin from § Models `Google` column, `effort` from § Effort `Antigravity` column, `tools:` respelled to Antigravity tool names. The orchestrator loads each with `view_file` and runs it in-session; isolated runs use `run_command` (`agy`). `**Subagent:** @name` respells to `` `view_file` `.agents/plugins/bkit/agents/name.md` `` rather than a `/name` slash command. |
|
|
65
|
+
|
|
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
|
+
>
|
|
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
|
+
|
|
55
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.
|
|
56
71
|
|
|
57
72
|
**Cheap models inside an IDE — no extension needed.** A host is its dir, not the window its process runs in. `bkit install --claude --cursor --opencode=openrouter` + opencode in the IDE's integrated terminal = every agent pin, GateGuard and the full workflow on OpenRouter while editing in Cursor. Supported path when the Claude subscription is spent.
|
|
@@ -60,7 +75,7 @@ Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-
|
|
|
60
75
|
|
|
61
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.
|
|
62
77
|
|
|
63
|
-
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.
|
|
64
79
|
|
|
65
80
|
---
|
|
66
81
|
|
|
@@ -84,7 +99,7 @@ bkit opencode # /Applications/opencode.app/Contents/MacOS/opencode
|
|
|
84
99
|
|
|
85
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`.
|
|
86
101
|
|
|
87
|
-
**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.
|
|
88
103
|
|
|
89
104
|
```bash
|
|
90
105
|
launchctl setenv BKIT_GH_TOKEN "$BKIT_GH_TOKEN"
|
|
@@ -104,6 +119,7 @@ Persistent variant: `RunAtLoad` LaunchAgent plist (`~/Library/LaunchAgents/`) wi
|
|
|
104
119
|
| Claude | `Agent` | `@` | `@bkit-build-plan-execute` invoked via `Agent` tool |
|
|
105
120
|
| Cursor | `Task` | `/` | `/bkit-build-plan-execute` invoked via `Task` tool |
|
|
106
121
|
| opencode | `/` (slash command) | `/` | `/bkit-build-plan-execute` invoked via opencode slash command |
|
|
122
|
+
| Antigravity | `view_file` (in-session prompt load) | `.agents/plugins/bkit/agents/` | `view_file` `.agents/plugins/bkit/agents/bkit-build-plan-execute.md` |
|
|
107
123
|
|
|
108
124
|
**Transform (Claude → Cursor, command bodies):**
|
|
109
125
|
|
|
@@ -259,17 +275,21 @@ Both hosts: `/<filename-without-ext>` (`/bkit-build`, `/bkit-plan`, etc.). Ident
|
|
|
259
275
|
<!-- prettier-ignore -->
|
|
260
276
|
| Part | Shared by | Holds |
|
|
261
277
|
| --- | --- | --- |
|
|
262
|
-
| `gateguard-engine.js` | Claude, Cursor, Codex, opencode `gateguard` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice` |
|
|
278
|
+
| `gateguard-engine.js` | Claude, Cursor, Codex, Google Antigravity, opencode `gateguard` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice` |
|
|
263
279
|
| `gateguard-edit-payload.js` | Claude, Cursor `gateguard` | `Edit` / `Write` / `MultiEdit` payload adapter `bkitGateguard(payload)` |
|
|
264
|
-
| `
|
|
265
|
-
| `
|
|
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`) |
|
|
283
|
+
| `guardrails-shell.js` | Claude, Cursor, Codex, Google Antigravity `guardrails` | segment parsing, curl / wget host allowlist, shell-as-edit-channel detection |
|
|
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`) |
|
|
266
286
|
| `preflight-linear.sh` | Claude, Cursor `preflight` | Linear key / issue checks, GraphQL query, `bkit:auto` + terminal-state guards |
|
|
267
287
|
|
|
268
|
-
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.
|
|
269
289
|
|
|
270
290
|
### GateGuard
|
|
271
291
|
|
|
272
|
-
Advisory hook, on all
|
|
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.
|
|
273
293
|
|
|
274
294
|
<!-- prettier-ignore -->
|
|
275
295
|
| Host | Implementation | File | Registration |
|
|
@@ -278,37 +298,53 @@ Advisory hook, on all four hosts (Claude Code, Cursor, Codex, opencode). Claude
|
|
|
278
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/`) |
|
|
279
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 |
|
|
280
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` |
|
|
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` |
|
|
281
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` |
|
|
282
303
|
|
|
283
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()`.
|
|
284
305
|
|
|
285
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.
|
|
286
307
|
|
|
287
|
-
**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.
|
|
309
|
+
|
|
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`.
|
|
288
311
|
|
|
289
|
-
**
|
|
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.
|
|
290
313
|
|
|
291
|
-
|
|
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.
|
|
292
328
|
|
|
293
329
|
---
|
|
294
330
|
|
|
295
331
|
## Permissions / auto-approve
|
|
296
332
|
|
|
297
333
|
<!-- prettier-ignore -->
|
|
298
|
-
| Concern | Claude | Cursor | opencode |
|
|
299
|
-
| --- | --- | --- | --- |
|
|
300
|
-
| 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 |
|
|
301
|
-
| 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) |
|
|
302
|
-
| 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`) |
|
|
303
|
-
| Granularity | Per-tool glob | Hook script (project-scoped, failClosed) | Per-path / per-command glob in `permission` |
|
|
304
|
-
| Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` | Implicit per-mode (Composer / Agent / Background) | `opencode --auto` + permission defaults |
|
|
305
|
-
| MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` |
|
|
306
|
-
| MCP tool approval | `permissions.allow` `mcp__<s>__*` from consumer `mcp-servers` (§ MCP servers) | Generated `.cursor/cli.json` `Mcp(<s>:*)` | `permission` `"<s>_*": "allow"` |
|
|
307
|
-
| 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 |
|
|
308
344
|
|
|
309
|
-
**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.
|
|
310
346
|
|
|
311
|
-
### Network allowlist — one source,
|
|
347
|
+
### Network allowlist — one source, five hosts
|
|
312
348
|
|
|
313
349
|
**Source of truth:** bkit's own hosts come from the egress registry (`.bkit/core/engine/shared/egress.ts`) and must never be re-declared. Stack domains come from consumer `.agents/context.md` → `<!-- allowed-domains:start -->` **after** `<!-- bkit:end -->` (apex domains). Never ship Vercel/Supabase/Sentry/etc. into every consumer.
|
|
314
350
|
|
|
@@ -318,9 +354,10 @@ Advisory hook, on all four hosts (Claude Code, Cursor, Codex, opencode). Claude
|
|
|
318
354
|
| Host | Where the allowlist lives | Why that shape |
|
|
319
355
|
| --- | --- | --- |
|
|
320
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(*)`. |
|
|
321
|
-
| **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. |
|
|
322
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/`). |
|
|
323
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. |
|
|
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. |
|
|
324
361
|
|
|
325
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.
|
|
326
363
|
|
|
@@ -351,12 +388,57 @@ Both hosts: same `mcpServers` shape; files differ:
|
|
|
351
388
|
|
|
352
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.
|
|
353
390
|
|
|
354
|
-
**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.
|
|
355
392
|
|
|
356
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.
|
|
357
394
|
|
|
358
395
|
---
|
|
359
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
|
+
## MCP project scope
|
|
413
|
+
|
|
414
|
+
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`).
|
|
415
|
+
|
|
416
|
+
<!-- prettier-ignore -->
|
|
417
|
+
| Service | Locked URL | Effect |
|
|
418
|
+
| --- | --- | --- |
|
|
419
|
+
| Sentry | `https://mcp.sentry.dev/mcp/<org>/<project>` | `find_organizations` / `find_projects` hidden |
|
|
420
|
+
| 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 |
|
|
421
|
+
| Vercel | `https://mcp.vercel.com/<team>/<project>` | calls default to that team and project |
|
|
422
|
+
|
|
423
|
+
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.
|
|
424
|
+
|
|
425
|
+
## claude.ai connectors
|
|
426
|
+
|
|
427
|
+
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.
|
|
428
|
+
|
|
429
|
+
<!-- prettier-ignore -->
|
|
430
|
+
| Aspect | Detail |
|
|
431
|
+
| --- | --- |
|
|
432
|
+
| Stops | claude.ai connectors in Claude Code sessions for this repo — terminal and desktop app |
|
|
433
|
+
| 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 |
|
|
434
|
+
| Before | move anything agents reach through a connector onto `.mcp.json` (§ MCP project scope), a context-fetch block or the provider CLI |
|
|
435
|
+
| Per person | `false` in `.claude/settings.local.json` turns connectors back on |
|
|
436
|
+
| Verify | `/context` before and after |
|
|
437
|
+
|
|
438
|
+
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.
|
|
439
|
+
|
|
440
|
+
---
|
|
441
|
+
|
|
360
442
|
## Runtime environment (cloud agents)
|
|
361
443
|
|
|
362
444
|
> Setup recipe + alignment: `.bkit/cloud.md`. This section = host-diff matrix only.
|
|
@@ -405,7 +487,7 @@ Installed provider catalog changes. Look up model IDs before pinning in `.openco
|
|
|
405
487
|
|
|
406
488
|
**opencode-zen / opencode-go — two OpenCode built-in providers.** Both emit minimal `provider.<id>` with only `options.apiKey: "{env:BKIT_OPENCODE_API_KEY}"` (no npm driver, no baseURL). OpenCode resolves from models.dev — Go Qwen/MiniMax use Anthropic `/messages`, not openai-compatible `/chat/completions`. Zen keyed `opencode`; Go `opencode-go`. `bkit install --opencode=opencode-zen` (or `=opencode-go`) → `bkit.opencodeProvider` in `package.json`; legacy `opencode` → `opencode-zen` via `OPENCODE_PROVIDER_ALIASES`. Reinstall **replaces** seeded block (heals hijacked npm/baseURL). Set `BKIT_OPENCODE_API_KEY` in `.bkit/.env` (<https://opencode.ai/auth>). Columns from **models.dev**.
|
|
407
489
|
|
|
408
|
-
**All four providers ship curated columns.** Tier design — **per-tier quality target, cheapest sufficient pin**. A tier cell is not "the same rung of this provider's ladder": it is the cheapest model that **reaches that tier's Claude score**, and reaching means _approaching_ — it does not have to beat it. Targets are the LiveBench Agentic Coding scores on the board below (opus `claude-opus-5` **65.2**, sonnet `claude-sonnet-5` **59.4**, haiku `claude-haiku-5-5` **~51**). The opus and sonnet targets stay the 5.0 scores although the 5.5 pins are on the CSV: `claude-opus-5-5` lands level at `xhigh` (65.4), and the `claude-sonnet-5-5` rows don't read cleanly (see the board). The haiku target is Haiku 5.5 at `xhigh`, the closest measured rung to the `high` effort the summary writers run at. Where a provider's ceiling sits under the sonnet target, opus+sonnet **collapse onto that ceiling** — spreading them across two rungs buys nothing and costs quality on the sonnet half. Where a cheap model already clears the haiku target, the haiku cell **stays cheap** — a $5/task flagship serving a read-and-emit summariser is waste, not safety.
|
|
490
|
+
**All four opencode providers ship curated columns.** Tier design — **per-tier quality target, cheapest sufficient pin**. A tier cell is not "the same rung of this provider's ladder": it is the cheapest model that **reaches that tier's Claude score**, and reaching means _approaching_ — it does not have to beat it. Targets are the LiveBench Agentic Coding scores on the board below (opus `claude-opus-5` **65.2**, sonnet `claude-sonnet-5` **59.4**, haiku `claude-haiku-5-5` **~51**). The opus and sonnet targets stay the 5.0 scores although the 5.5 pins are on the CSV: `claude-opus-5-5` lands level at `xhigh` (65.4), and the `claude-sonnet-5-5` rows don't read cleanly (see the board). The haiku target is Haiku 5.5 at `xhigh`, the closest measured rung to the `high` effort the summary writers run at. Where a provider's ceiling sits under the sonnet target, opus+sonnet **collapse onto that ceiling** — spreading them across two rungs buys nothing and costs quality on the sonnet half. Where a cheap model already clears the haiku target, the haiku cell **stays cheap** — a $5/task flagship serving a read-and-emit summariser is waste, not safety.
|
|
409
491
|
|
|
410
492
|
### Selecting pins
|
|
411
493
|
|
|
@@ -12,6 +12,30 @@
|
|
|
12
12
|
> - `bkit install` and `bkit upgrade` never write these files and never overwrite a copy.
|
|
13
13
|
> - Adapt app roots, workspace package scope, rules JSON. Examples use `apps/web`, `apps/mobile`, `packages/api`, `@scope`.
|
|
14
14
|
|
|
15
|
+
## What each template is for
|
|
16
|
+
|
|
17
|
+
Adoption order = `bkit tips` order. Sections below: install steps and traps.
|
|
18
|
+
|
|
19
|
+
<!-- prettier-ignore -->
|
|
20
|
+
| Template | What it's for | Skip it and |
|
|
21
|
+
| --- | --- | --- |
|
|
22
|
+
| direnv | Loads `.bkit/.env` tokens whenever the project opens. | Saved tokens never load; every sign-in fails while the file looks right. |
|
|
23
|
+
| Serena | Agents look code up like an editor ("where is this defined, what uses it?"). Read-only. | Agents grep and read whole files: more accidental changes, more correction rounds, higher token cost. |
|
|
24
|
+
| CI workflow + CI scripts | Runs every check on GitHub on every change; one capstone check gates merge; `/bkit-ship` waits for it. | "Shipped" means merged, not checked. |
|
|
25
|
+
| Git hooks (Husky) | Same checks locally on commit and push, in seconds. | Failures surface minutes later in CI, after the agent moved on. |
|
|
26
|
+
| Prettier ignore list | One formatting baseline; stops Prettier reformatting bkit's managed files. | Reviews fill with spacing noise; every bkit upgrade shows false changes. |
|
|
27
|
+
| slop-scan | Flags net-new junk code AI tends to write (filler, dead code, type escapes). | Junk passes skim review and piles up. |
|
|
28
|
+
| Vale | Prose lint for docs and agent instructions. | Padded, vague docs every agent re-reads on every run. |
|
|
29
|
+
| lint-staged | Formats only the staged files inside the commit hook. | Commit hook does nothing, or is slow enough to get skipped. |
|
|
30
|
+
| Cloud-agent workflow + SessionStart hook | CI result starts a cloud agent: ship on green, debug on red; hook installs the cloud toolchain. | Every next step needs a local session. |
|
|
31
|
+
| Context-fetch blocks | `/bkit-debug` reads real CI logs, runtime errors and web results. | Debug guesses from code; real errors stay hidden. |
|
|
32
|
+
| Secrets sync | One local file → every secret store; proves copies match without printing values. | Hand-copied secrets drift: "works for me, broken in production". |
|
|
33
|
+
| graphify | Code map (`docs/capabilities.md`) agents check before building something again. | Agents rediscover structure each run; ripple effects missed. |
|
|
34
|
+
| Dependabot / Renovate | Small grouped update PRs; pinned Actions; security fixes skip the queue. | Updates pile into one large risky upgrade. |
|
|
35
|
+
| Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
|
|
36
|
+
| Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
|
|
37
|
+
| Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
|
|
38
|
+
|
|
15
39
|
## Contract
|
|
16
40
|
|
|
17
41
|
<!-- prettier-ignore -->
|
|
@@ -37,7 +61,6 @@
|
|
|
37
61
|
| Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
|
|
38
62
|
| Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
|
|
39
63
|
| Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
|
|
40
|
-
| Licence | `.bkit/templates/LICENSE.md` | — | read it; the copies in `.bkit/templates/` are MIT-0 |
|
|
41
64
|
|
|
42
65
|
Placeholders. Copies keep them raw; replace each in your copy:
|
|
43
66
|
|
|
@@ -47,7 +70,7 @@ Placeholders. Copies keep them raw; replace each in your copy:
|
|
|
47
70
|
| `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments) | your default branch | `origin/HEAD`, else `main` |
|
|
48
71
|
| `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
|
|
49
72
|
| `{{CLOUD_RUNNER}}` | `bkit-cloud.yml` (`runs-on`, all three jobs) | a runner label | `ubuntu-latest` |
|
|
50
|
-
| `{{SCRIPT_PATH}}` | `ai.bkit.launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/
|
|
73
|
+
| `{{SCRIPT_PATH}}` | `ai.bkit.launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/Users/<you>/.config/bkit/bkit-launchd-env.sh` |
|
|
51
74
|
| `{{ENV_FILE}}` | `ai.bkit.launchd.plist` (`ProgramArguments`, `WatchPaths`) | absolute path to your env file | `/Users/<you>/.config/bkit/launchd.env` |
|
|
52
75
|
|
|
53
76
|
- `bkit install` / `bkit upgrade` refresh `.bkit/templates/` to the package's templates, unsubstituted. `bkit check` fails on a stale copy. `bkit uninstall` removes the folder, never an adopted copy.
|
|
@@ -64,18 +87,18 @@ Placeholders. Copies keep them raw; replace each in your copy:
|
|
|
64
87
|
<!-- prettier-ignore -->
|
|
65
88
|
| File | Fits | `context=` | Fetches | Secret / non-secret env | Domains | CLI (provision) |
|
|
66
89
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
67
|
-
| `github.md` | GitHub Actions | `ci`, `diff` | `ci`: failing run: failed jobs / steps, `::error` annotations, failed-step logs; `diff`: `git diff --stat` since the last green CI run on trunk | `GH_TOKEN` / `BASELINE_BRANCH`, `BASELINE_WORKFLOW` (`diff`) | — | `gh` (base tool) |
|
|
68
|
-
| `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE` | — | `gh` (base tool) |
|
|
69
|
-
| `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's
|
|
90
|
+
| `github.md` | GitHub Actions | `ci`, `diff` | `ci`: failing run: failed jobs / steps, `::error` annotations, failed-step logs tail-bounded per failed job; `diff`: `git diff --stat` (capped) since the last green CI run on trunk | `GH_TOKEN` / `CI_LOG_TAIL`; `BASELINE_BRANCH`, `BASELINE_WORKFLOW`, `DIFF_STAT_N` (`diff`) | — | `gh` (base tool) |
|
|
91
|
+
| `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first; inlined files, lines and binary paths capped | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE`, `E2E_MAX_FILES`, `E2E_MAX_LINES`, `E2E_MAX_BIN` | — | `gh` (base tool) |
|
|
92
|
+
| `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's log, sliced to the result steps, each slice tail-bounded | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS`, `MAESTRO_LOG_TAIL` | — | `gh` (base tool) |
|
|
70
93
|
| `tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
|
|
71
|
-
| `sentry.md` | Sentry | `runtime` | unresolved issues,
|
|
94
|
+
| `sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
|
|
72
95
|
| `vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV` | `vercel.com` | `vercel` (yes) |
|
|
73
96
|
| `supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` lines | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID` | `supabase.com` | — |
|
|
74
|
-
| `stripe.md` | Stripe | `runtime` | failure / dispute / refund events | `STRIPE_SECRET_KEY` /
|
|
97
|
+
| `stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source | `STRIPE_SECRET_KEY` / `STRIPE_N`, `STRIPE_SINCE_S` | `stripe.com` | — |
|
|
75
98
|
| `resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends | `RESEND_API_KEY` / — | `resend.com` | — |
|
|
76
|
-
| `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events | `INNGEST_SIGNING_KEY` /
|
|
99
|
+
| `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events in a window | `INNGEST_SIGNING_KEY` / `INNGEST_N`, `SINCE_ISO`, `INNGEST_ENV` | `inngest.com` | — |
|
|
77
100
|
| `cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE` | `googleapis.com`, `google.com` | `gcloud` (yes) |
|
|
78
|
-
| `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: build status + errored-build log lines; `e2e`: per-flow exceptions, JUnit, screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR` | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
|
|
101
|
+
| `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: build status + errored-build log lines (capped per build); `e2e`: failed jobs' per-flow exceptions, JUnit (capped), screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR`, `EAS_PLATFORM`, `EAS_PROFILE`, `EAS_LOG_N` (`runtime`); `EAS_WF_FILE`, `EAS_JUNIT_N` (`e2e`) | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
|
|
79
102
|
| `serena.md` | Serena MCP server | — | nothing: provision only, installs `serena` in cloud | — | — | `uv` (yes) |
|
|
80
103
|
|
|
81
104
|
MCP names listed: `sentry` / `Sentry`, `vercel` / `Vercel`, `supabase` / `Supabase`, `inngest`, `serena`. Every tool on a listed server runs without a prompt, writes included — list only servers you trust with that.
|
|
@@ -140,6 +163,7 @@ pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
|
|
|
140
163
|
- `slop:delta` runs `bkit ci slop` (bkit devDep on `PATH` through the package script). CI passes the base sha as its one bare argument.
|
|
141
164
|
- `lint:prose` runs `bkit ci prose`: Vale over every `*.md` outside `node_modules/`. Narrow it with repeatable `--glob=<pattern>` (`*`, `**`, `?`, relative to the repo root), e.g. `bkit ci prose --glob='docs/*.md' --glob='.agents/*.md'`.
|
|
142
165
|
- Non-Node stack → point each gate at your own commands; keep the gate names.
|
|
166
|
+
- `bkit:test:file` (not seeded; `test-file-script-missing` until declared) runs ONE test file — bkit appends its repo-relative path — and writes a JUnit report to `$BKIT_TEST_REPORT`; `/bkit-build` reads it for test-first. Vitest: `"bkit:test:file": "vitest run --reporter=default --reporter=junit --outputFile.junit=\"$BKIT_TEST_REPORT\""`. Call the runner directly, not through a caching task runner.
|
|
143
167
|
|
|
144
168
|
## CI workflow — `bkit-ci.yml`
|
|
145
169
|
|
|
@@ -260,12 +284,15 @@ launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist
|
|
|
260
284
|
launchctl getenv BKIT_OPENROUTER_API_KEY # bootstrap proof
|
|
261
285
|
```
|
|
262
286
|
|
|
263
|
-
- `WatchPaths` re-runs the loader on every env-file write → rotate a token by editing the
|
|
287
|
+
- `WatchPaths` re-runs the loader on every env-file write → rotate a token by editing the value, revoke it by deleting the line or emptying the value (`KEY=""`); no re-bootstrap.
|
|
288
|
+
- Loader loads `BKIT_*` keys only (others logged as skipped). An empty value runs `launchctl unsetenv`. Loaded key names are recorded in `.launchd-loaded-keys` next to the env file (mode 600; `BKIT_LAUNCHD_STATE` overrides the path); a recorded key missing from the env file is unset on the next run.
|
|
289
|
+
- One failing key is logged and skipped; the rest still load and the loader exits 1. A failed unset stays recorded and retries on the next run.
|
|
264
290
|
- Log `~/Library/Logs/bkit-launchd.log` records key names only, never values. `BKIT_LAUNCHD_LOG` and `BKIT_LAUNCHD_ENV` override the log and env-file defaults.
|
|
265
291
|
- Loader self-skips (log line + `exit 0`) when the env file is absent or `launchctl` is off `PATH` (Linux CI).
|
|
266
292
|
- launchd cannot exec a loader under `~/Documents`, `~/Desktop` or `~/Downloads`: macOS TCC denies it and `/tmp/bkit-launchd.log` reads `Operation not permitted`. Repo under one of those → keep the adopted copy in git but place the loader launchd runs at `~/.config/bkit/bkit-launchd-env.sh` (or another unprotected path) and point `{{SCRIPT_PATH}}` there.
|
|
267
293
|
- Env-file rules: blank lines and `#` comments ignored; optional `export ` prefix; key must match `[A-Za-z0-9_]`; matching surrounding quotes stripped from the value.
|
|
268
|
-
- `launchctl setenv` reaches apps launched after the load; a running app keeps its environment until relaunch.
|
|
294
|
+
- `launchctl setenv` reaches apps launched after the load; a running app keeps its environment until relaunch (set and unset alike).
|
|
295
|
+
- **Exposure:** `launchctl setenv` makes every loaded token visible to every app started in the login session, not only the app that needs it. Load only tokens you accept that for; prefer `bkit cursor` / `bkit opencode` (per-process env) where possible.
|
|
269
296
|
- Remove: `launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.
|
|
270
297
|
|
|
271
298
|
## Cursor — `settings.json`, `environment.json`, `Dockerfile`
|
|
@@ -335,7 +362,7 @@ PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
|
|
|
335
362
|
|
|
336
363
|
## graphify — map
|
|
337
364
|
|
|
338
|
-
On-demand only — not an MCP server
|
|
365
|
+
On-demand only — not an installed skill or git hook. graphify ships an MCP server (`graphify-mcp`, stdio default); it stays unwired because its answers come from the `graph.json` snapshot and build/debug agents invalidate the graph faster than it rebuilds — Serena (no index to go stale) owns the agent surface. The one CI touch is the self-skipping register-freshness gate below: on pushes it installs a pinned graphify and runs `pnpm graph:check`, forcing `docs/capabilities.md` to be current. Agents read `docs/capabilities.md`; audit templates that need the graph build it via `scripts/graphify/bkit-graphify.sh`. Only tracked output: `docs/capabilities.md`. Mermaid views: `docs/graphify-out/reports/graph-packages.mmd`, `graph-modules.mmd`. Reference: https://github.com/Graphify-Labs/graphify.
|
|
339
366
|
|
|
340
367
|
```bash
|
|
341
368
|
uv tool install "graphifyy[sql]"
|
|
@@ -371,6 +398,8 @@ graphify-out/
|
|
|
371
398
|
```
|
|
372
399
|
|
|
373
400
|
- Paste `scripts/graphify/bkit-graph-pre-push.sh` at the end of your `.husky/pre-push`, below the bkit lines. Warn-only: does not run graphify, does not block push.
|
|
401
|
+
- `.github/workflows/bkit-ci.yml` ships `Check Capability Register` (push events): installs pinned graphify and runs `pnpm graph:check`, so a stale register fails CI. Self-skips without `scripts/graphify/bkit-graphify.sh`; bump `GRAPHIFY_SPEC` and refresh the register in the same change.
|
|
402
|
+
- graphify's MCP server is opt-in: install `graphifyy[mcp]` (`mcp` + `starlette`; HTTP transport also needs `uvicorn`) and pass the graph path explicitly — `graphify-mcp` defaults to `graphify-out/graph.json`, not the pinned `docs/graphify-out/graph.json`. Snapshot-dated answers suit audit/orientation, never build or debug.
|
|
374
403
|
- `.graphifyignore` merges `.gitignore`.
|
|
375
404
|
- Keep `package.json` in corpus — excluding it drops workspace `name` fields graphify resolves package imports with; graph still looks complete.
|
|
376
405
|
- Keep `tsconfig.json` out; graphify reads `paths` regardless.
|
|
@@ -383,7 +412,7 @@ graphify-out/
|
|
|
383
412
|
| `pnpm graph:clean` | Same, after deleting `docs/graphify-out/`. Required after any tsconfig `paths` change. `--force` does not invalidate the module-resolution cache. |
|
|
384
413
|
| `pnpm graph:update` | Re-extract changed files, then recluster. |
|
|
385
414
|
| `pnpm graph:rollup` | Package and module views, plus `docs/capabilities.md`. |
|
|
386
|
-
| `pnpm graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces.
|
|
415
|
+
| `pnpm graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces. Shipped as a self-skipping CI step (push events); enabled in bkit's own CI. |
|
|
387
416
|
| `pnpm graph:scoped [path]` | One subtree. Default `apps/web/src`. |
|
|
388
417
|
| `pnpm graph:graphml` | Opt-in GraphML for Gephi / yEd. |
|
|
389
418
|
|