@cbartens/bkit 5.2.2 → 5.2.4
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 +4 -2
- package/.bkit/core/.agents/context.md +2 -2
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +7 -1
- package/.bkit/core/.bkit/README.md +3 -1
- package/.bkit/core/.bkit/comparison.md +114 -45
- package/.bkit/core/.bkit/install.md +6 -6
- package/.bkit/core/.bkit/jsonl.md +3 -3
- package/.bkit/core/.bkit/prompts.md +6 -5
- package/.bkit/core/.bkit/providers.md +5 -4
- package/.bkit/core/.bkit/templates.md +30 -11
- package/.bkit/core/.bkit/workflows.md +14 -7
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +5 -1
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -2
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-agents.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +15 -4
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +14 -3
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-database.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +14 -3
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +15 -4
- package/.bkit/core/docs/templates/bkit-audit-gates.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-llm.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +25 -13
- package/.bkit/core/docs/templates/bkit-audit-models.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +14 -3
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +14 -3
- package/.bkit/core/docs/templates/bkit-audit-repo.md +14 -3
- package/.bkit/core/docs/templates/bkit-audit-security.md +15 -4
- package/.bkit/core/docs/templates/bkit-audit-slop.md +13 -2
- package/.bkit/core/docs/templates/bkit-audit-testing.md +14 -3
- package/.bkit/core/docs/templates/bkit-audit-usability.md +13 -2
- package/.bkit/core/docs/templates/bkit-plan.md +1 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +10 -0
- package/.bkit/core/engine/commands/install/check.ts +3 -11
- package/.bkit/core/engine/commands/install/doctor.ts +2 -3
- package/.bkit/core/engine/commands/install/uninstall.ts +60 -44
- package/.bkit/core/engine/commands/install/upgrade.ts +13 -11
- package/.bkit/core/engine/commands/workflow/branches.ts +72 -9
- package/.bkit/core/engine/commands/workflow/repo.ts +16 -2
- package/.bkit/core/engine/commands/workflow/workflows.ts +4 -3
- package/.bkit/core/engine/install/hosts.ts +14 -4
- package/.bkit/core/engine/ledgers/telemetry.ts +3 -4
- package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
- package/.bkit/core/engine/shared/timeouts.ts +6 -0
- package/.bkit/core/hooks/guardrails-read.js +4 -9
- package/.bkit/core/hooks/guardrails-tiers.js +312 -28
- package/.bkit/core/prompts/bkit-audit-generate.md +21 -5
- package/.bkit/core/workflows/bkit-build.md +1 -1
- package/.bkit/core/workflows/bkit-debug.md +1 -1
- package/.bkit/core/workflows/bkit-design.md +1 -1
- package/.bkit/core/workflows/bkit-plan.md +1 -1
- package/.bkit/core/workflows/bkit-ship.md +1 -1
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.opencode/opencode.json +21 -1
- package/.bkit/shared/docs/deployments.md +14 -0
- package/.bkit/templates/.github/workflows/bkit-ci.yml +9 -0
- package/.bkit/templates/.husky/pre-push +7 -0
- package/.bkit/templates/context/bkit-cloudrun.md +28 -19
- package/.bkit/templates/context/bkit-expo.md +30 -13
- package/.bkit/templates/context/bkit-inngest.md +54 -17
- package/.bkit/templates/context/bkit-resend.md +36 -8
- package/.bkit/templates/context/bkit-sentry.md +11 -4
- package/.bkit/templates/context/bkit-stripe.md +39 -22
- package/.bkit/templates/context/bkit-supabase.md +45 -20
- package/.bkit/templates/context/bkit-vercel.md +45 -16
- package/.bkit/templates/scripts/ci/accepted-advisories.json +7 -0
- package/.bkit/templates/scripts/ci/check-dependency-audit.mjs +200 -0
- package/.bkit/templates/scripts/ci/check-dependency-audit.test.mjs +127 -0
- package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
- package/CHANGELOG.md +56 -0
- package/README.md +76 -20
- package/dist/checks/tips/catalogue.js +9 -0
- package/dist/commands/install/check.js +3 -15
- package/dist/commands/install/doctor.js +2 -1
- package/dist/commands/install/uninstall.js +52 -45
- package/dist/commands/install/upgrade.js +13 -11
- package/dist/commands/workflow/branches.js +64 -10
- package/dist/commands/workflow/repo.js +14 -2
- package/dist/commands/workflow/workflows.js +4 -3
- package/dist/install/hosts.js +11 -4
- package/dist/shared/bkit-latest.js +150 -0
- package/dist/shared/timeouts.js +6 -0
- package/package.json +1 -1
package/.bkit/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# bkit — Agent Workflow System
|
|
2
2
|
|
|
3
|
-
<!-- bkit:managed v5.2.
|
|
3
|
+
<!-- bkit:managed v5.2.4 — do not edit; run `bkit upgrade` to refresh -->
|
|
4
4
|
|
|
5
5
|
**bkit** wires Claude Code, Cursor, Codex, Google Antigravity and opencode into five-phase tracker-integrated cycle: `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`. Hosts additive, one flag each: `--claude`, `--cursor`, `--codex`, `--antigravity`, `--opencode=<provider>` — opencode providers: `openrouter`, `ollama`, `opencode-zen` + `opencode-go` (opencode-native gateways; auth via `BKIT_OPENCODE_API_KEY`). Same harness on every host; state lives in the repo, so a feature moves between hosts mid-run (see `.bkit/providers.md` § Hosts + Providers).
|
|
6
6
|
|
|
@@ -191,6 +191,8 @@ bkit tips [--all] # what is not set up yet, most useful first; exits 0
|
|
|
191
191
|
bkit install --claude --cursor # (re)seed hosts; name ≥1 module
|
|
192
192
|
```
|
|
193
193
|
|
|
194
|
+
**Outdated-version warning:** Step 1 of every phase workflow (`bkit repo info`) and every design / plan / audit doc stamp compare `.bkit/version` `pinnedVersion` with the newest published `@cbartens/bkit`; older → a warning naming the upgrade command, and stamped docs carry a visible `Outdated bkit` line under their `bkit:anchor` block. Never a stop. Registry asked at most once a day (cache: `<git common dir>/bkit-latest-version.json`); offline → no warning. `BKIT_NO_UPDATE_CHECK=1` skips the lookup (air-gapped machines, CI).
|
|
195
|
+
|
|
194
196
|
> **⚠️ Version bumps:** use `bkit upgrade --latest` (or `--to=<version>`). Bare `pnpm add @cbartens/bkit` / Renovate bumps refresh lockfile only — run `bkit upgrade` after and commit resync with the bump, or `bkit check` reds CI.
|
|
195
197
|
|
|
196
198
|
### Dogfood path (this repo only)
|
|
@@ -277,7 +279,7 @@ The cloud workflow and the Cursor Background Agent files are templates the `--au
|
|
|
277
279
|
|
|
278
280
|
### Optional post-install decisions (tracker + cloud agents)
|
|
279
281
|
|
|
280
|
-
Two capabilities **opt-in**, excluded from default install: **issue tracker** (`--tracker=github|linear`), **cloud agents** (`--auto=claude|cursor|opencode`: records the choice and points at the copy-and-own templates — `bkit-cloud.yml`, `.claude/hooks/bkit-cloud-bootstrap.sh`, and the Cursor `Dockerfile`/`environment.json`; default install ships zero cloud footprint). Default wires neither; post-install advisory emits `tracker-setup-none` / `cloud-router-none`. Choices persist in `package.json` (`bkit.issueTracker`, `bkit.cloudAgents`); `"none"` silences the nudge. Cloud router split: each job inert without model-auth secret (`
|
|
282
|
+
Two capabilities **opt-in**, excluded from default install: **issue tracker** (`--tracker=github|linear`), **cloud agents** (`--auto=claude|cursor|opencode`: records the choice and points at the copy-and-own templates — `bkit-cloud.yml`, `.claude/hooks/bkit-cloud-bootstrap.sh`, and the Cursor `Dockerfile`/`environment.json`; default install ships zero cloud footprint). Default wires neither; post-install advisory emits `tracker-setup-none` / `cloud-router-none`. Choices persist in `package.json` (`bkit.issueTracker`, `bkit.cloudAgents`); `"none"` silences the nudge. Cloud router split: each job inert without model-auth repo secret (`ANTHROPIC_API_KEY` claude, `OPENCODE_PROVIDER_KEY` opencode) + GHA write permissions + (Cursor) dashboard trigger; depends on opt-in GitHub tracker.
|
|
281
283
|
|
|
282
284
|
**Dependency updaters.** Copy one example and own it: `.bkit/templates/.github/renovate.json5`, `.bkit/templates/.github/workflows/bkit-renovate.yml` (self-hosted runner only), or `.bkit/templates/.github/dependabot.yml`. `bkit.depUpdater: "none"` skips the install-time absence advisory. `bkit check` emits `dep-updater-absent` and `dep-updater-both`. See `docs/deployments.md` § Dependency updaters.
|
|
283
285
|
|
|
@@ -35,7 +35,7 @@ Unnamed block => omit the name segment (`context-runtime-{DEBUG_ATTEMPT}.md`). U
|
|
|
35
35
|
|
|
36
36
|
**Self-contained blocks.** No block exports state. Discover any run id inside the block. No ordering, no shared variables, no parse contract — stdout is the artifact. Stamp the run id / SHA used into the output.
|
|
37
37
|
|
|
38
|
-
**Loudness:** `exit 0` self-skip (missing CLI/token,
|
|
38
|
+
**Loudness:** `exit 0` self-skip (missing CLI/token, API / auth error, host unreachable behind Trusted-egress — § Allowed domains) => source **not checked**, never "no errors". `TRUNCATED` line => window partly read; narrate the unread part. Narrate each block `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` per context, every attempt. Self-skip => unavailable. A skip breadcrumb may name a fallback; taking it => checked; no fallback => UNCHECKED.
|
|
39
39
|
|
|
40
40
|
**Fence rule:** no block-body line may start with a triple backtick. Plain-text section headers (`===== failed-step logs =====`).
|
|
41
41
|
|
|
@@ -43,7 +43,7 @@ Unnamed block => omit the name segment (`context-runtime-{DEBUG_ATTEMPT}.md`). U
|
|
|
43
43
|
|
|
44
44
|
**Cloud agents:** `/bkit-debug` also runs in Claude/Cursor cloud (headless, never see `.bkit/.env`). Non-interactive auth — dashboard env tokens (`VERCEL_TOKEN`, `SUPABASE_ACCESS_TOKEN`, `BKIT_TAVILY_API_KEY`), never `vercel login`. Secret tokens → cloud dashboard; non-secret selectors (scope / project ref / `--environment`) commit in copied block so cloud agents inherit them. Token identical preview/prod — selector only changes. Other backends (`gcloud` / `aws` / `datadog`) self-gate on needed credential.
|
|
45
45
|
|
|
46
|
-
**Authoring your own:** tool-agnostic (`gcloud` / `aws` / `datadog` / …). Read-only + idempotent. Self-gate on credential/tool (`command -v <tool>` + token check; miss → `[context-fetch:<name>] skipped — …` stderr, `exit 0`). Cover severity, time window, log name / stream, label filters. Empty output = no signal.
|
|
46
|
+
**Authoring your own:** tool-agnostic (`gcloud` / `aws` / `datadog` / …). Read-only + idempotent. Self-gate on credential/tool (`command -v <tool>` + token check; miss → `[context-fetch:<name>] skipped — …` stderr, `exit 0`). Same skip line on non-200, non-zero CLI exit, or unexpected body shape; reason = status / exit code, NEVER vendor error text, because it can carry secrets. Check status before jq; a raw error body piped into jq prints nothing. Cover severity, time window, log name / stream, label filters. Page the whole window; page cap or failed later page → keep rows read, print `===== TRUNCATED: <part not read> =====`. Header line: window + count. Empty output = no signal only after a clean answer. `# Customise:` suggests a positive control: known event inside the window; missing → reader broken, not clean.
|
|
47
47
|
|
|
48
48
|
**Bound your own output.** Above 3000 lines / 400 KB bkit clamps the artifact and says so in a footer: it keeps head 500 + tail 1000 plus every line matching `error|fail|exception|timeout|panic|traceback|assert|✕|✗|✘|●|×` with 2 lines of context, shortens single lines over 2000 bytes in place, and drops the quiet remainder. Hard ceiling 12000 lines / 1.5 MB. A block whose failure lines carry none of those words loses them, so name the failure in the line — and bound each block at the source anyway (severity filters, time windows, `--limit` / `head` on every listing, never a whole-run log dump).
|
|
49
49
|
|
|
@@ -106,7 +106,13 @@ function bkitGuardrails(payload) {
|
|
|
106
106
|
if (tier.tier === "ask") {
|
|
107
107
|
return {
|
|
108
108
|
decision: "ask",
|
|
109
|
-
reason: `bkit Antigravity guardrails: this is a destructive or privileged command. It is on the PROHIBITED list in every bkit workflow. Do not run it unless the user asked for this exact command. Note that git clean and git checkout -- . destroy untracked files and uncommitted work, which no reflog can recover. Command: ${cmd}`,
|
|
109
|
+
reason: `bkit Antigravity guardrails: this is a destructive or privileged command (${tier.what}). It is on the PROHIBITED list in every bkit workflow. Do not run it unless the user asked for this exact command. Note that git clean and git checkout -- . destroy untracked files and uncommitted work, which no reflog can recover. Command: ${cmd}`,
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
if (tier.tier === "secret") {
|
|
113
|
+
return {
|
|
114
|
+
decision: "ask",
|
|
115
|
+
reason: `bkit Antigravity guardrails: this command reads ${tier.path}, an env/secrets or private-key file, which may expose secrets. Prefer direnv / documented non-secret examples. Command: ${cmd}`,
|
|
110
116
|
};
|
|
111
117
|
}
|
|
112
118
|
const advisory =
|
|
@@ -191,6 +191,8 @@ bkit tips [--all] # what is not set up yet, most useful first; exits 0
|
|
|
191
191
|
bkit install --claude --cursor # (re)seed hosts; name ≥1 module
|
|
192
192
|
```
|
|
193
193
|
|
|
194
|
+
**Outdated-version warning:** Step 1 of every phase workflow (`bkit repo info`) and every design / plan / audit doc stamp compare `.bkit/version` `pinnedVersion` with the newest published `@cbartens/bkit`; older → a warning naming the upgrade command, and stamped docs carry a visible `Outdated bkit` line under their `bkit:anchor` block. Never a stop. Registry asked at most once a day (cache: `<git common dir>/bkit-latest-version.json`); offline → no warning. `BKIT_NO_UPDATE_CHECK=1` skips the lookup (air-gapped machines, CI).
|
|
195
|
+
|
|
194
196
|
> **⚠️ Version bumps:** use `bkit upgrade --latest` (or `--to=<version>`). Bare `pnpm add @cbartens/bkit` / Renovate bumps refresh lockfile only — run `bkit upgrade` after and commit resync with the bump, or `bkit check` reds CI.
|
|
195
197
|
|
|
196
198
|
### Dogfood path (this repo only)
|
|
@@ -277,7 +279,7 @@ The cloud workflow and the Cursor Background Agent files are templates the `--au
|
|
|
277
279
|
|
|
278
280
|
### Optional post-install decisions (tracker + cloud agents)
|
|
279
281
|
|
|
280
|
-
Two capabilities **opt-in**, excluded from default install: **issue tracker** (`--tracker=github|linear`), **cloud agents** (`--auto=claude|cursor|opencode`: records the choice and points at the copy-and-own templates — `bkit-cloud.yml`, `.claude/hooks/bkit-cloud-bootstrap.sh`, and the Cursor `Dockerfile`/`environment.json`; default install ships zero cloud footprint). Default wires neither; post-install advisory emits `tracker-setup-none` / `cloud-router-none`. Choices persist in `package.json` (`bkit.issueTracker`, `bkit.cloudAgents`); `"none"` silences the nudge. Cloud router split: each job inert without model-auth secret (`
|
|
282
|
+
Two capabilities **opt-in**, excluded from default install: **issue tracker** (`--tracker=github|linear`), **cloud agents** (`--auto=claude|cursor|opencode`: records the choice and points at the copy-and-own templates — `bkit-cloud.yml`, `.claude/hooks/bkit-cloud-bootstrap.sh`, and the Cursor `Dockerfile`/`environment.json`; default install ships zero cloud footprint). Default wires neither; post-install advisory emits `tracker-setup-none` / `cloud-router-none`. Choices persist in `package.json` (`bkit.issueTracker`, `bkit.cloudAgents`); `"none"` silences the nudge. Cloud router split: each job inert without model-auth repo secret (`ANTHROPIC_API_KEY` claude, `OPENCODE_PROVIDER_KEY` opencode) + GHA write permissions + (Cursor) dashboard trigger; depends on opt-in GitHub tracker.
|
|
281
283
|
|
|
282
284
|
**Dependency updaters.** Copy one example and own it: `.bkit/templates/.github/renovate.json5`, `.bkit/templates/.github/workflows/bkit-renovate.yml` (self-hosted runner only), or `.bkit/templates/.github/dependabot.yml`. `bkit.depUpdater: "none"` skips the install-time absence advisory. `bkit check` emits `dep-updater-absent` and `dep-updater-both`. See `docs/deployments.md` § Dependency updaters.
|
|
283
285
|
|
|
@@ -12,6 +12,19 @@
|
|
|
12
12
|
> - Keep prose factual; house / write-good linters apply to `*.md`; no hype adjectives.
|
|
13
13
|
> - Part 3 cells: each project's own repo / docs only, never roundups or AI summaries; no star counts; refresh the as-of month with the table.
|
|
14
14
|
> - Pipeline or subagents change → update Part 1 to match `.bkit/core/workflows/*` and `.bkit/core/.bkit/prompts.md`.
|
|
15
|
+
> - Audit templates added, removed or renamed → update the Part 1 § Audits table to match `.bkit/core/docs/templates/bkit-audit-*.md`.
|
|
16
|
+
|
|
17
|
+
**Contents**
|
|
18
|
+
|
|
19
|
+
- [What this is](#what-this-is)
|
|
20
|
+
- [Part 1 — The five-phase pipeline, in order](#part-1--the-five-phase-pipeline-in-order)
|
|
21
|
+
- [Pipeline map](#pipeline-map-key-steps-only) · [CI test scaffold](#ci-test-scaffold-runs-on-every-pr--push)
|
|
22
|
+
- [Design](#phase-1--bkit-design) · [Plan](#phase-2--bkit-plan) · [Build](#phase-3--bkit-build) · [Debug](#phase-4--bkit-debug) · [Ship](#phase-5--bkit-ship)
|
|
23
|
+
- [Audits: every template](#audits)
|
|
24
|
+
- [Part 2 — Comparison to agentic design patterns](#part-2--comparison-to-agentic-design-patterns)
|
|
25
|
+
- [Where bkit goes beyond the catalogue](#where-bkit-goes-beyond-the-catalogue) · [Known gaps](#known-gaps-scoped-as-opportunities)
|
|
26
|
+
- [Part 3 — Compared with other AI development frameworks](#part-3--compared-with-other-ai-development-frameworks)
|
|
27
|
+
- [Agents and CI](#agents-and-ci)
|
|
15
28
|
|
|
16
29
|
## What this is
|
|
17
30
|
|
|
@@ -19,7 +32,7 @@ bkit turns a single coding-agent request into gated, peer-reviewed engineering.
|
|
|
19
32
|
|
|
20
33
|
Beside those commands, 35 read-only audit templates live at `docs/templates/bkit-audit-*.md`. `@bkit-audit-generate` runs one and writes `docs/audits/{YYYYMM}/{slug}.md`. `/bkit-plan` takes a design, one or more of those reports, or both.
|
|
21
34
|
|
|
22
|
-
Part 1: every phase subagent in execution order, then the main audit templates. Part 2: bkit vs Gulli agentic patterns. Part 3: bkit vs 10 other AI development frameworks, one table
|
|
35
|
+
Part 1: every phase subagent in execution order, then the main audit templates. Part 2: bkit vs Gulli agentic patterns. Part 3: bkit vs 10 other AI development frameworks, one table, then agents and CI in detail.
|
|
23
36
|
|
|
24
37
|
Not related to [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code), a separate project with the same name. This bkit = `@cbartens/bkit`, [github.com/cbartens/bkit](https://github.com/cbartens/bkit).
|
|
25
38
|
|
|
@@ -259,23 +272,48 @@ No command and no phase label. One subagent, one template per run.
|
|
|
259
272
|
|
|
260
273
|
`/bkit-plan` reads a design doc, one or more reports, or both. The invocation names which findings are in scope. The rest of each report stays context.
|
|
261
274
|
|
|
262
|
-
35 templates.
|
|
275
|
+
All 35 templates, by area. Template file = `docs/templates/bkit-audit-{template}.md`.
|
|
263
276
|
|
|
264
277
|
<!-- prettier-ignore -->
|
|
265
|
-
|
|
|
266
|
-
| --- | --- | --- |
|
|
267
|
-
| `
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
271
|
-
|
|
|
272
|
-
|
|
|
273
|
-
| `
|
|
274
|
-
| `
|
|
275
|
-
|
|
|
276
|
-
|
|
|
277
|
-
|
|
278
|
-
|
|
278
|
+
| Area | Audit | Template | What it finds |
|
|
279
|
+
| --- | --- | --- | --- |
|
|
280
|
+
| **Security and privacy** | Security | `security` | Holes in sign-in, permissions, secrets and input checks, plus documented protections that never run. |
|
|
281
|
+
| | Red team | `red-team` | Attacks a test copy of the app, never production, one hostile request at a time. Keeps each request and response, then cleans up. |
|
|
282
|
+
| | Privacy | `privacy` | Where personal data goes and how long it stays, whether deleting an account removes the person, whether the privacy policy matches the code. |
|
|
283
|
+
| **Code quality** | Architecture | `architecture` | Code that breaks the intended layers: server code reaching the client, modules tied together with no visible import. |
|
|
284
|
+
| | Duplication | `duplication` | One behaviour built more than once: copied rules, competing mechanisms, restated types, merges that should not have happened. |
|
|
285
|
+
| | Dead code | `dead-code` | Code, settings, routes, events, tables and assets that look live and never run. |
|
|
286
|
+
| | Slop | `slop` | Every switched-off check: disabled lint rules, casts that hide type errors, skipped tests, config opt-outs. |
|
|
287
|
+
| | Documentation | `documentation` | Docs that disagree with the code, links that land nowhere, facts agents rely on that nobody wrote down. |
|
|
288
|
+
| | Dependencies | `dependencies` | Pending dependency updates merged as one verified batch; security advisories, licences, end-of-life packages, supply-chain settings. |
|
|
289
|
+
| **Tests and CI** | Testing | `testing` | Tests that can't fail, don't run, or skip what the product must and must never do. |
|
|
290
|
+
| | Coverage | `coverage` | How much code the tests reach, against the minimum CI enforces, and the next minimum to set. |
|
|
291
|
+
| | Flaky tests | `flakes` | Tests that pass only on retry or fail on one platform, and the change that makes each one reliable. |
|
|
292
|
+
| | Gates | `gates` | Problems audits keep finding by hand that an automatic check could block, and the order to add those checks. |
|
|
293
|
+
| | Annotations | `annotations` | Warnings buried in green CI runs: silent failures, deprecations with a deadline, ignored lint warnings. |
|
|
294
|
+
| | CI performance | `ci-performance` | The lane that makes CI slow or expensive, and what each change would save. |
|
|
295
|
+
| **Running in production** | Reliability | `reliability` | What breaks when a service is slow, down or answers twice: missing timeouts, unsafe retries, races, failures no alert reports. |
|
|
296
|
+
| | Database | `database` | Who can read and write what, migrations, data integrity, capacity, and whether a restore works. |
|
|
297
|
+
| | Logs | `logs` | Error-tracker issues and logs sorted into real bugs, noise at the wrong level, and failures that never got reported. |
|
|
298
|
+
| | App performance | `app-performance` | Web, phone and server speed, measured against published targets and your own budgets. |
|
|
299
|
+
| | Config | `config` | Settings outside the code that disagree across environments, dashboards, repo and docs; anything with an expiry date. |
|
|
300
|
+
| | Cost | `cost` | Vendor plans that don't fit your usage, what drives each bill, whether a spike shows up before the invoice. |
|
|
301
|
+
| **Users and reach** | Accessibility | `accessibility` | What automated accessibility checks miss against WCAG 2.2 AA, plus the manual checks nothing automates. |
|
|
302
|
+
| | Usability | `usability` | Screens that don't match their design or the other platforms, and main flows a person can't finish. |
|
|
303
|
+
| | Analytics | `analytics` | Product events that don't fire, differ between web and phone, fire before consent, or carry personal data. |
|
|
304
|
+
| | AI search & SEO | `aio-seo` | Whether search engines and AI answer engines can find, read and describe your public pages. |
|
|
305
|
+
| | App Store | `app-store` | What keeps an iOS or Android app listed: deadlines, privacy declarations, permissions, signing, review readiness, crashes, ratings. |
|
|
306
|
+
| **AI features** | LLM | `llm` | What each AI model call can make happen, and what stops it when the input is hostile: prompts, tool limits, output checks, evals. |
|
|
307
|
+
| | Models | `models` | Whether each AI call uses the best current model for the job, whether models and fallbacks still exist, whether one list holds them all. |
|
|
308
|
+
| | Prompts | `prompts` | Product prompts that are unclear, badly structured, or off the model maker's current guide. |
|
|
309
|
+
| **Project upkeep** | Issues | `issues` | Size and priority for every open issue, by rules a later run applies the same way; board, parent, milestone and blocking links. |
|
|
310
|
+
| | Deferrals | `deferrals` | Postponed work sorted into done, replaced, tracked, parked, or in scope and never finished. |
|
|
311
|
+
| | Failures | `failures` | Known bugs sorted into still reachable, already fixed, misdescribed, unconfirmed, or a repeat of an earlier one. |
|
|
312
|
+
| | Repo | `repo` | Leftovers and layout: stale worktrees, branches and stashes, ignored files, files in the wrong place. |
|
|
313
|
+
| | Agents | `agents` | Each AI tool's setup: which instructions load, permissions, hooks, tool servers, model choices, untrusted input each agent reads. |
|
|
314
|
+
| | Adoption | `adoption` | Whether every file bkit installed is used and used correctly: install current, docs filled in, audits run on schedule, each template adopted or declined with a reason. |
|
|
315
|
+
|
|
316
|
+
Agent-facing scope per template: `.bkit/prompts.md` § Audit (Ad-hoc).
|
|
279
317
|
|
|
280
318
|
---
|
|
281
319
|
|
|
@@ -330,42 +368,46 @@ Most partials = deliberate scope. Two remain: automated eval harness with regres
|
|
|
330
368
|
|
|
331
369
|
## Part 3 — Compared with other AI development frameworks
|
|
332
370
|
|
|
333
|
-
As of October 2026. A cross-section of 10: the closest process frameworks, the two main spec toolkits, the largest skills pack, an autonomous agent platform and an agentic IDE. Each
|
|
371
|
+
As of October 2026. A cross-section of 10: the closest process frameworks, the two main spec toolkits, the largest skills pack, an autonomous agent platform and an agentic IDE. Each column read from the project's own repo and docs. ✅ yes · ◐ partly · — no · ? not documented.
|
|
334
372
|
|
|
335
|
-
|
|
336
|
-
| Column | Means |
|
|
337
|
-
| --- | --- |
|
|
338
|
-
| Kind | **Framework** runs a fixed multi-phase process · **Spec toolkit** writes specs / plans, agent does the rest · **Skills pack** library of skills / agents / commands, no fixed process · **Agent** product that writes code itself · **Editor** IDE or single-agent pair programmer |
|
|
339
|
-
| Phases | Own commands / agents for: design, plan, build, review, fix (debug failures), merge |
|
|
340
|
-
| Reviewers | Work reviewed by agents that did not write it |
|
|
341
|
-
| Sign-offs | Process stops for human approval at fixed points |
|
|
342
|
-
| Checked | "Done" verified by code / tests, not the agent's word |
|
|
343
|
-
| CI | Ships a CI pipeline for your project |
|
|
344
|
-
| Memory | File-based lessons / decisions later runs read |
|
|
345
|
-
| Parallel | Several features at once, isolated (e.g. worktrees) |
|
|
346
|
-
| Cloud | Runs unattended, triggered or hosted |
|
|
347
|
-
| Guards | Hooks that block dangerous actions |
|
|
348
|
-
| Audits | Audit / checklist templates |
|
|
373
|
+
Kind: **Framework** runs a fixed multi-phase process · **Spec toolkit** writes specs / plans, agent does the rest · **Skills pack** library of skills / agents / commands, no fixed process · **Agent** product that writes code itself · **Editor** IDE or single-agent pair programmer. ECC is everything-claude-code.
|
|
349
374
|
|
|
350
375
|
<!-- prettier-ignore -->
|
|
351
|
-
|
|
|
352
|
-
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
353
|
-
| **
|
|
354
|
-
|
|
|
355
|
-
|
|
|
356
|
-
|
|
|
357
|
-
|
|
|
358
|
-
|
|
|
359
|
-
|
|
|
360
|
-
|
|
|
361
|
-
|
|
|
362
|
-
|
|
|
363
|
-
|
|
|
376
|
+
| | **bkit** | [Superpowers](https://github.com/obra/superpowers) | [gstack](https://github.com/garrytan/gstack) | [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) | [GSD Core](https://github.com/open-gsd/gsd-core) | [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) + bmad-loop | [Spec Kit](https://github.com/github/spec-kit) | [OpenSpec](https://github.com/Fission-AI/OpenSpec) | [Kiro](https://kiro.dev) (AWS) | [ECC](https://github.com/affaan-m/ECC) | [OpenHands](https://github.com/OpenHands/OpenHands) |
|
|
377
|
+
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
378
|
+
| **Kind** | Framework | Framework | Skills pack (sprint) | Framework | Framework | Framework | Spec toolkit | Spec toolkit | Editor + cloud agent | Skills pack + pipeline | Agent |
|
|
379
|
+
| **Licence** | MIT | MIT | MIT | MIT | MIT | MIT + trademark | MIT | MIT | Closed source, paid tiers | MIT | MIT (paid cloud) |
|
|
380
|
+
| **Phases**<br>design, plan, build, review, fix, merge | all six | all six; no CI wait | all six; host writes code | all six; merge only if granted | all six; never merges | all six; local merge, no PR | design, plan, build | design, plan, build; merges specs | all six; never merges | all six; no merge | no design; plan partial |
|
|
381
|
+
| **Reviewers**<br>agents that didn't write the work | ✅ bug + security, blind to each other | ◐ per task + whole branch | ✅ up to 8 + second model | ✅ blind personas + second model | ✅ checkers + outside AI tools | ✅ 4 blind reviewers | ◐ via extensions | — | ✅ opt-in, mixed model vendors | ✅ + refuter agent | ◐ one reviewer |
|
|
382
|
+
| **Sign-offs**<br>stops for human approval | ✅ design, plan, merge | ✅ design, plan, merge | ✅ design, plan, merge | ◐ interactive only | ✅ roadmap, acceptance, ship | ◐ risky plans, done, epic | ✅ spec, plan | ◐ by convention | ✅ requirements, design, PR | ✅ plan, commit | ◐ per action |
|
|
383
|
+
| **Checked**<br>"done" proved by code, not the agent's word | ✅ tests seen failing before code | ✅ task's test must pass | ✅ test evidence tied to files | ◐ | ✅ goes stale on file change | ◐ (✅ with loop) | ◐ | ◐ spec structure only | ✅ property-based tests | ◐ | ✅ merge waits for CI |
|
|
384
|
+
| **CI**<br>a test pipeline for your project | ✅ fails on skipped lane / zero tests | — | ◐ basic `test.yml` | — | — | — | — | — | ◐ example | — | ◐ AI PR review only |
|
|
385
|
+
| **Tracker** | GitHub, Linear | — | ◐ GitHub | GitHub, Linear, Jira | — by design | GitHub, Jira, Linear, Notion, Trello | ◐ tasks → GitHub issues | ? | ◐ GitHub, GitLab | GitHub, Jira | GitHub, GitLab, Jira, Linear |
|
|
386
|
+
| **Memory**<br>lessons and decisions later runs read | ✅ | — | ✅ outside repo | ✅ `docs/solutions/` | ✅ | ◐ | ◐ constitution | ◐ living specs | ◐ | ✅ | ◐ opt-in |
|
|
387
|
+
| **Docs**<br>project docs kept current | ✅ | — | ✅ | ◐ | ◐ | ◐ | ◐ | ◐ specs | ◐ | ◐ | ◐ AGENTS.md |
|
|
388
|
+
| **Parallel**<br>several features at once, isolated | ✅ | ◐ | ◐ via Conductor | ◐ | ✅ | ◐ | ◐ via extensions | ◐ | ✅ 10 cloud sandboxes | ◐ | ✅ containers |
|
|
389
|
+
| **Cloud**<br>runs unattended, triggered or hosted | ✅ ship on green, debug on red | ? | ◐ stops at gates | ◐ scheduler | ◐ local | ◐ local | ◐ | ◐ via Copilot agent | ✅ | ◐ | ✅ |
|
|
390
|
+
| **Guards**<br>hooks that block dangerous actions | ✅ all hosts | ◐ prompt rules | ◐ opt-in, Claude Code only | ◐ prompt rules | ◐ blocks `.env` reads | — | — | ? | ✅ | ✅ GateGuard | ✅ sandbox + hooks |
|
|
391
|
+
| **Audits**<br>audit / checklist templates | ✅ 35 | — | ✅ ~10 + 8 checklists | ◐ reviewer personas | ◐ ~8 | ◐ 5 lenses | ◐ checklists | ? | ? | ✅ ~25 | ◐ |
|
|
392
|
+
| **AI tools** | 5 | 16 | 1 certified, 7 experimental | ~14 | 15 | 10+ | 40+ | 30+ | own IDE, CLI, web, mobile | 1 stable, ~15 beta / experimental | own UI / CLI / cloud, ACP editors |
|
|
393
|
+
|
|
394
|
+
Where others are ahead of bkit:
|
|
395
|
+
|
|
396
|
+
- **Superpowers:** skills trigger automatically; skill eval harness; official marketplaces.
|
|
397
|
+
- **gstack:** real-browser and iOS device QA; design mockups; deploy + canary monitoring; prompt-injection defences.
|
|
398
|
+
- **Compound Engineering:** learnings shared across repos; Jira; stacked-PR babysitting; Slack / GitHub feedback → plan.
|
|
399
|
+
- **GSD Core:** cross-tool plan review; ship blocked by open security threats; cross-project learnings.
|
|
400
|
+
- **BMAD:** Agile roles and artifacts (PRD, UX spec, epics, stories); most trackers.
|
|
401
|
+
- **Spec Kit:** most AI tools; 181 community extensions; workflow engine for custom processes.
|
|
402
|
+
- **OpenSpec:** light to adopt; made for existing code (spec deltas → living specs); multi-repo planning (beta).
|
|
403
|
+
- **Kiro:** full product; EARS requirements; workflow rules enforced by runtime; enterprise SSO.
|
|
404
|
+
- **ECC:** largest library (70+ agents, 300+ skills); finding refutation; hosted skill generator.
|
|
405
|
+
- **OpenHands:** sandboxed and hosted execution; issue-to-merge with no human; Jira, GitLab.
|
|
364
406
|
|
|
365
407
|
Where bkit stands apart, per the table:
|
|
366
408
|
|
|
367
409
|
- **Only one with all of:** blind bug + security reviewers, sign-off after design / plan / before merge, mechanical "done" checks, a CI pipeline for your project, GitHub / Linear tracker, and file-based memory.
|
|
368
|
-
- **CI pipeline for your project:** none of the 10 ships a multi-lane test pipeline with a final gate. Closest: gstack's basic `test.yml`, OpenHands' AI PR-review workflow, Kiro's example.
|
|
410
|
+
- **CI pipeline for your project:** none of the 10 ships a multi-lane test pipeline with a final gate. Closest: gstack's basic `test.yml`, OpenHands' AI PR-review workflow, Kiro's example. How agents use CI: [Agents and CI](#agents-and-ci).
|
|
369
411
|
- **Merge discipline:** merges into `dev` only after the capstone check, never `main`. OpenHands merges with no human; most stop at a PR.
|
|
370
412
|
- **Debug with outside evidence:** connectors pull CI logs, runtime errors and web results into diagnosis; soak mode for runtime-only bugs; handover when unfixable.
|
|
371
413
|
- **Test first, checked by code:** each plan task's tests are run by bkit and must fail before the task's code exists, then pass; the agent's report of a failure never counts. Superpowers enforces TDD by instruction; Task Master's TDD mode takes pass / fail counts from the agent.
|
|
@@ -373,6 +415,33 @@ Where bkit stands apart, per the table:
|
|
|
373
415
|
|
|
374
416
|
Also reviewed, left out of the table: Claude Task Master, ccpm, wshobson/agents, mattpocock/skills, SuperClaude, Ruflo, oh-my-openagent, Cline, Aider.
|
|
375
417
|
|
|
418
|
+
### Agents and CI
|
|
419
|
+
|
|
420
|
+
bkit's biggest difference from the field is how tightly its agents and its checks work together. Each row asks one question: does the framework itself do this, or is it left to you? Optional add-ons don't count. Rows run in the order of the wall in the README picture, nearest layer first. ✅ yes · ◐ partly · — no · ? not documented.
|
|
421
|
+
|
|
422
|
+
<!-- prettier-ignore -->
|
|
423
|
+
| | **bkit** | Superpowers | gstack | Compound Engineering | GSD Core | BMAD | Spec Kit | OpenSpec | Kiro | ECC | OpenHands |
|
|
424
|
+
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
425
|
+
| **Code search**<br>definitions and callers, not text matches | ✅ Serena template | — | ✅ opt-in; definitions, callers | — | ◐ opt-in graph, planners only | — | — | — | ✅ built in, 18 languages | — | — |
|
|
426
|
+
| **Agent hooks**<br>steer the agent around each edit | ✅ read before editing, don't loosen checks; 4 hosts | — | ✅ opt-in verify gate, Claude Code only | — | ✅ read before editing | ◐ add-on test-quality hook | — | — | ◐ engine; you write the hooks | ✅ GateGuard, config lock, post-edit type check | — engine only |
|
|
427
|
+
| **Git hooks**<br>for your project, same checks as CI | ✅ pre-commit formats; pre-push runs the agents' gate scripts | — | ◐ opt-in pre-push, credentials only | — | ◐ opt-in pre-commit, planning files | — | — | — | — | ◐ Codex only; checks opt-in | ◐ pre-commit on request |
|
|
428
|
+
| **Ships CI**<br>ending in one "every lane passed" check | ✅ fails on a failed or skipped lane, or zero tests | — | ◐ one `test.yml`, no final check | — | — | ◐ optional TEA module | — | — | ◐ AI-review example | — | ◐ AI review and QA bots |
|
|
429
|
+
| **Waits for CI**<br>before merging or calling it done | ✅ green on the exact merge commit | — local suite only | ✅ exact head | ✅ `lfg` and PR babysitter | — left to you | — | — | — | ✅ opt-in workflows | ◐ | ✅ |
|
|
430
|
+
| **Reads CI logs**<br>on red, diagnoses from them | ✅ failed lanes, diff since last green | — | ◐ deploy failure or `/investigate` | ✅ failing jobs and log tails | — | — | — | — | ◐ failed check names, no logs | ◐ by instruction | ✅ failed-job logs |
|
|
431
|
+
| **CI starts next step**<br>fix on red, merge on green, no human | ✅ `bkit:auto`: ship on green, debug on red | — | — stops on red | ✅ watcher fixes and pushes | — | — | — | — | ✅ wakes the agent; never merges | — | ✅ automations; merger with no AI |
|
|
432
|
+
| **Tests mapped to lanes**<br>planning picks each test's tier | ✅ unit, integration or end-to-end | — | ◐ `/ship` fails a file with no lane | ◐ scenarios, no lane | ◐ unit / end-to-end split, no lane | ◐ TEA module only | ◐ optional contract tests | — | ◐ | ◐ tiers, no lane | ? |
|
|
433
|
+
|
|
434
|
+
- **Only one with all eight.** Compound Engineering and OpenHands also close the CI loop, fixing on red with no human, but neither ships a test pipeline or edit hooks for your project. gstack and ECC have strong edit hooks, but gstack hands a red CI result back to you and ECC doesn't watch CI.
|
|
435
|
+
- **Only one whose git hooks run the same checks as its CI.** None of the 10 does; most ship no git hooks for your project at all.
|
|
436
|
+
- **Ahead of bkit here:**
|
|
437
|
+
- ECC's hooks block where bkit's advise. It refuses edits to an existing lint or format config, refuses the first edit of each file until the agent answers its questions, and runs type checks and formatting after each edit.
|
|
438
|
+
- gstack's opt-in gate won't let a turn end until a declared test command passes. `/freeze` keeps the agent inside one folder and switches on by itself when debugging.
|
|
439
|
+
- Kiro's symbol search needs no install and covers 18 languages; Serena needs a language server per language.
|
|
440
|
+
- gstack maps every changed file to a lane read from your CI workflow files, and blocks publishing until a lane your laptop can't run has passed in CI.
|
|
441
|
+
- Compound Engineering re-runs flaky failures instead of debugging them, and notices when its fixes go in circles. It and Kiro wait for CI with a plain script that wakes the agent only on change.
|
|
442
|
+
- OpenHands merges through a step with no AI in it, and closes pull requests that stay red for 14 days.
|
|
443
|
+
- BMAD's TEA module generates CI for five platforms, splits tests across parallel runners, re-runs tests to catch flaky ones, and blocks bad tests as they're written.
|
|
444
|
+
|
|
376
445
|
---
|
|
377
446
|
|
|
378
447
|
Sources: bkit workflow and prompt definitions (`.bkit/core/workflows/*`, `.bkit/core/.bkit/prompts.md`); the Gulli differential review of _Agentic Design Patterns_ (Part 2); each compared project's own repo and docs (Part 3).
|
|
@@ -103,7 +103,7 @@ bkit check
|
|
|
103
103
|
|
|
104
104
|
**Module flags** (composable; symmetric install ↔ uninstall): `--claude` `--cursor` `--codex` `--antigravity` `--opencode=<provider>`. The CI workflow, the Vale config, the tool configs, the git hooks, the slop-scan type-suppression plugin (`scripts/slop/bkit-slop-type-suppression.mjs`), and the tool `package.json` scripts and devDeps are templates you copy from `.bkit/templates/` (`.bkit/templates.md`). Core, implicit on every install, seeds the `bkit:gate:*` / `bkit:deps:*` scripts every workflow runs (add-if-missing; a name already present is never touched); point their values at your stack, see `.bkit/README.md` § Required tools. Any other module flag is an unknown-flag error.
|
|
105
105
|
|
|
106
|
-
**Opt-in flags:** `--tracker=github|linear`, `--auto=claude|cursor` (cloud agents), `--opencode=<provider>` (additive opencode execution host — `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). Dependency updaters: copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
|
|
106
|
+
**Opt-in flags:** `--tracker=github|linear`, `--auto=claude|cursor|opencode` (cloud agents), `--opencode=<provider>` (additive opencode execution host — `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). Dependency updaters: copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
|
|
107
107
|
|
|
108
108
|
### Payload view links — `.bkit/core` + `.bkit/shared`
|
|
109
109
|
|
|
@@ -240,7 +240,7 @@ After writes, bkit re-runs credential and environment checks — some only accur
|
|
|
240
240
|
|
|
241
241
|
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.
|
|
242
242
|
|
|
243
|
-
**`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.
|
|
243
|
+
**`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 host's `agents/` dir; antigravity any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host; `bkit status` uses the same detection). 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.
|
|
244
244
|
|
|
245
245
|
**`bkit upgrade`** (not `--dry-run`) ends with the same read-only pass as `bkit check`: prints the checklist and rewrites `.bkit/advisories.md` (`Mode: upgrade`). Drift and blockers it finds are reported only — upgrade's exit code is unchanged.
|
|
246
246
|
|
|
@@ -301,7 +301,7 @@ Use one. `bkit.depUpdater: "none"` skips the install-time absence advisory. Setu
|
|
|
301
301
|
**Why opt-in, not part of a default install:**
|
|
302
302
|
|
|
303
303
|
- **Tracker** wires real credentials and MCP servers into workflows — consumer must choose provider; bkit can't guess.
|
|
304
|
-
- **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 `
|
|
304
|
+
- **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 the `ANTHROPIC_API_KEY` repo secret (+ 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.
|
|
305
305
|
|
|
306
306
|
**How to decide:**
|
|
307
307
|
|
|
@@ -388,8 +388,8 @@ bkit uninstall --nuke --yes
|
|
|
388
388
|
| --- | --- |
|
|
389
389
|
| `fully-managed` | Always deleted (bkit owns 100% of the file). |
|
|
390
390
|
| `markered-text` | bkit block stripped; consumer content above/below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
|
|
391
|
-
| `byte-equal-text` | Deleted only if current hash matches the hash `.bkit/version` recorded when bkit last wrote it (`canonicalHashes`). Consumer modifications → preserved. |
|
|
392
|
-
| `json` | bkit's keys stripped; consumer keys preserved. `.mcp.json` / `.cursor/mcp.json`: only bkit's tracker entry is removed, and only while it still equals the template. File deleted when nothing is left. |
|
|
391
|
+
| `byte-equal-text` | Deleted only if current hash matches the hash `.bkit/version` recorded when bkit last wrote it (`canonicalHashes`). Consumer modifications → preserved. `canonicalHashes` is internal state `bkit check` does not verify: a hand-edited or corrupted entry makes uninstall keep that file as consumer-modified (`--force` deletes it anyway) and upgrade's whole-file diff report a conflict instead of updating it. |
|
|
392
|
+
| `json` | bkit's keys stripped; consumer keys preserved. `.mcp.json` / `.cursor/mcp.json`: only bkit's tracker entry is removed, and only while it still equals the template. `.opencode/opencode.json`: every `mcp` tracker entry (`github`, `linear`) and every `provider` block of a supported provider is removed while it still equals what install renders — all the earlier installs left, not just the active one; an edited entry is kept whole. File deleted when nothing is left. |
|
|
393
393
|
|
|
394
394
|
### Idempotency
|
|
395
395
|
|
|
@@ -397,7 +397,7 @@ Running `bkit uninstall` twice is safe — subsequent runs skip absent files and
|
|
|
397
397
|
|
|
398
398
|
### What a full uninstall preserves
|
|
399
399
|
|
|
400
|
-
Bare uninstall removes bkit-managed files and strips bkit-managed blocks, but **not** guaranteed zero-footprint wipe. `docs/`: bkit's block (managed marker included) is stripped from every installed `docs/*.md` — a file holding nothing else is deleted — and the owned `docs/templates/bkit-*.md` are deleted. Deliberately leaves: everything outside `bkit:start` / `bkit:end` in `docs/*.md`, `.agents/context.md`, `.agents/skills.md` and the other managed-block files; your own files in `docs/` and `docs/templates/`; every file you copied from `.bkit/templates/`; any owned whole-file the consumer modified (hash mismatch → preserved); generated artefacts not manifest-tracked (`.bkit/advisories.md`, `.bkit/friction.jsonl`). Use `--nuke` to force-remove every manifest-listed bkit file regardless of consumer modifications; generated artefacts still yours to delete by hand.
|
|
400
|
+
Bare uninstall removes bkit-managed files and strips bkit-managed blocks, but **not** guaranteed zero-footprint wipe. `docs/`: bkit's block (managed marker included) is stripped from every installed `docs/*.md` — a file holding nothing else is deleted — and the owned `docs/templates/bkit-*.md` are deleted. Deliberately leaves: everything outside `bkit:start` / `bkit:end` in `docs/*.md`, `.agents/context.md`, `.agents/skills.md` and the other managed-block files; your own files in `docs/` and `docs/templates/`; every file you copied from `.bkit/templates/`; any owned whole-file the consumer modified (hash mismatch → preserved); generated artefacts not manifest-tracked (`.bkit/advisories.md`, `.bkit/friction.jsonl`, the newest-release cache `.git/bkit-latest-version.json`). Use `--nuke` to force-remove every manifest-listed bkit file regardless of consumer modifications; generated artefacts still yours to delete by hand.
|
|
401
401
|
|
|
402
402
|
## Phase 3 exit-1 and recovery
|
|
403
403
|
|
|
@@ -38,7 +38,7 @@ One file per `kind`; writers:
|
|
|
38
38
|
| `counter` | `.bkit/stats.jsonl` | every workflow at its close step (attempt counters) |
|
|
39
39
|
| `friction` | `.bkit/friction.jsonl` | orchestrator workflows (design / plan / build / debug / ship) on observed friction |
|
|
40
40
|
| `deferral` | `docs/deferrals.jsonl` | `@bkit-design-generate`, `@bkit-plan-generate`, `@bkit-plan-update`, `@bkit-build-challenge-remediate` (blocked), `@bkit-debug-abort-handover`, `@bkit-ship-deferred-sweep` (adjudication only), `@bkit-utility-update-deferrals` (close / triage / locator) |
|
|
41
|
-
| `failure` | `docs/failures.jsonl` | any agent on a discovered bug; `@bkit-debug-abort-handover`; `@bkit-utility-update-failures` (close / triage / locator) |
|
|
41
|
+
| `failure` | `docs/failures.jsonl` | any agent on a discovered bug; `@bkit-debug-abort-handover`; `@bkit-audit-generate` (`MEDIUM`+ findings; rerun closes rows it no longer finds); `@bkit-utility-update-failures` (close / triage / locator) |
|
|
42
42
|
| `knowledge` | `docs/knowledge.jsonl` | `@bkit-build-challenge-remediate`, `@bkit-build-plan-gaps-remediate`, `@bkit-debug-failure-remediate` (after verified fix), `@bkit-utility-update-knowledge` (supersede / correct) |
|
|
43
43
|
| `decision` | `docs/decisions.jsonl` | `@bkit-debug-failure-remediate` (forced arch), `@bkit-plan-generate`, `@bkit-utility-update-decisions` (supersede / correct) |
|
|
44
44
|
| `feature` | `.bkit/issues.jsonl` | design / plan / build / debug orchestrators at their phase close; ship Step 6 into the worktree ledger (rides the PR); `ABANDONED` only by a human, or an agent on explicit human instruction |
|
|
@@ -54,7 +54,7 @@ One file per `kind`; writers:
|
|
|
54
54
|
| `kind` | `string` | Closed enum: `compliance`, `outcome`, `counter`, `friction`, `deferral`, `failure`, `knowledge`, `decision`, `feature`. |
|
|
55
55
|
| `repo` | `string` | Origin repo slug, e.g. `cbartens/bkit`. |
|
|
56
56
|
| `bkitVersion` | `string` | bkit version that emitted the row — sole version stamp; readers tally rows per `bkitVersion` for triage. |
|
|
57
|
-
| `workflow` | `string` | Emitting workflow: `design` / `plan` / `build` / `debug` / `ship` (part of the dedup tuple for `compliance` / `counter` / `outcome`). |
|
|
57
|
+
| `workflow` | `string` | Emitting workflow: `design` / `plan` / `build` / `debug` / `ship` / `audit` (part of the dedup tuple for `compliance` / `counter` / `outcome`). |
|
|
58
58
|
| `step` | `string` | The workflow step the row was emitted at, e.g. `build-close-workflow`, `ship-close-gate`. Never an agent name. See § Who Wrote It. |
|
|
59
59
|
| `subagent` | `string?` | The subagent that wrote the row, e.g. `bkit-build-challenge-remediate`. Set on every subagent-written row; absent on orchestrator-written rows. See § Who Wrote It. |
|
|
60
60
|
| `model` | `string?` | The model that wrote the row, from the writing subagent's own frontmatter `model:`. Set only where `subagent` is set. See § Who Wrote It. |
|
|
@@ -251,7 +251,7 @@ Copy prior row, change deltas, append. Carry `key` verbatim — reworded `key` f
|
|
|
251
251
|
|
|
252
252
|
**`TRIAGED`** = middle state on triaged trio (`friction` / `deferral` / `failure` — kinds with `severity`). Ladder: `OPEN` (raised, cause unknown) -> `TRIAGED` (analysed, disposition known, not fixed) -> `CLOSED` (fixed, refuted, not ours). Append like close; disposition in `references`: issue, mapped `Fix N`, or why not ours.
|
|
253
253
|
|
|
254
|
-
**`TRIAGED` is STILL open WORK.** Open-entry counts —
|
|
254
|
+
**`TRIAGED` is STILL open WORK.** Open-entry counts — audit debt lens, age report — test `status != "CLOSED"`. Only `CLOSED` is done.
|
|
255
255
|
|
|
256
256
|
Not on `knowledge` or `decision` — both use `ACTIVE` / `SUPERSEDED`. Absent `status` = `ACTIVE`.
|
|
257
257
|
|
|
@@ -124,7 +124,7 @@ Pinning `model:` locks agent model regardless of orchestrator session. Without p
|
|
|
124
124
|
| `model` | Explicit Claude model pin per the effort mapping table above. Locks the model independent of the orchestrator's session default — without it, subagents inherit user's Claude Code default and `xhigh` thinking depth + 1M context disappear if the user runs Sonnet. | Brittle by version (must update on every model rev), but explicit and discoverable. Never use family alias (`opus` / `sonnet`) — they don't lock context-window variant. |
|
|
125
125
|
| `tools` | Minimum capability sandbox. Enforced on Claude (native). Cursor: `bkit install` T3 transform passes the field through verbatim, but Cursor CLI 2026.10.01 does not enforce it (measured: a `tools: [Read]` subagent still has `Shell`, `Write`, `StrReplace`, and every MCP tool via `CallDynamicTool`). Removing `Edit`/`Bash` makes an agent provably non-mutating on Claude only. | Add `WebFetch`/`WebSearch` only for genuine ecosystem research (`bkit-design-review-1/2`) or to pin a probe against vendor docs before running it (`bkit-design-spike`). |
|
|
126
126
|
| `permissionMode: acceptEdits` | End-to-end runs of `/design`/`/plan`/`/build`/`/debug`/`/ship` would break if mid-workflow prompt blocked an agent. Bash auto-approve surface lives in `.claude/settings.json` (`workflows.md` § Permissions) | Never deviate inside the pipeline; one-off ad-hoc invocations may use stricter modes. |
|
|
127
|
-
| `maxTurns` | Pure runaway-loop safety cap, not a workload budget.
|
|
127
|
+
| `maxTurns` | Pure runaway-loop safety cap, not a workload budget. 4 tiers (S=50 / M=100 / L=150 / XL=300). Hitting the cap means the agent is definitely stuck (tight retry loop, infinite re-read pattern, etc.), not "tight on a complex run." | Cap by **tier** (see § `maxTurns` calibration). Per-agent assignment in § Models. |
|
|
128
128
|
|
|
129
129
|
### Effort tiers
|
|
130
130
|
|
|
@@ -162,14 +162,15 @@ Pinning `model:` locks agent model regardless of orchestrator session. Without p
|
|
|
162
162
|
|
|
163
163
|
`maxTurns` = max **agent turns** (assistant messages); each turn may emit multiple parallel tool calls. **Runaway-loop safety cap, not workload budget.** Runtime bounded by universal 3600s step timeout (`workflows.md` § Execution Protocol).
|
|
164
164
|
|
|
165
|
-
**Same philosophy as timeout:** 3600s ~2x typical 30 min runtime — hit means something wrong. `maxTurns` tiers are S=50 / M=100 / L=150, per-agent in § Models:
|
|
165
|
+
**Same philosophy as timeout:** 3600s ~2x typical 30 min runtime — hit means something wrong. `maxTurns` tiers are S=50 / M=100 / L=150 / XL=300, per-agent in § Models:
|
|
166
166
|
|
|
167
167
|
<!-- prettier-ignore -->
|
|
168
168
|
| Tier | Cap | Typical work | Use for | Examples |
|
|
169
169
|
| --- | --- | --- | --- | --- |
|
|
170
170
|
| **S** | **50** | 3-10 turns | Pure synthesizers, scope checks, single-pass utilities, install / cleanup, summary writers. | `*-summary`, `bkit-debug-abort-handover`, `bkit-plan-complexity-check`, `bkit-plan-scope-check-*`, `bkit-build-install-skills` |
|
|
171
171
|
| **M** | **100** | 5-25 turns | Reviewers, doc writers, multi-doc, web investigators, surgical-edit appliers, single-pass source modifiers (no test loop). | `bkit-design-brainstorm-ideate-*`, `bkit-design-review-*`, `bkit-design-spike`, `bkit-design-generate`, `bkit-design-organise`, `bkit-design-update`, `bkit-plan-review-*`, `bkit-plan-generate`, `bkit-plan-update`, `bkit-plan-complexity-split`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-build-challenge-reconcile`, `bkit-build-challenge-tests`, `bkit-build-plan-verify`, `bkit-debug-failure-diagnose`, `bkit-ship-update-docs`, `bkit-ship-deferred-sweep`, `bkit-utility-update-*`, `bkit-utility-compress-markdown` |
|
|
172
|
-
| **L** | **150** | 30-60 turns | Source modifiers with test loops, plan executor — iterative edit→`pnpm bkit:gate:static-unit`→edit cycles
|
|
172
|
+
| **L** | **150** | 30-60 turns | Source modifiers with test loops, plan executor — iterative edit→`pnpm bkit:gate:static-unit`→edit cycles. | `bkit-build-plan-execute`, `bkit-build-plan-gaps-remediate`, `bkit-build-challenge-remediate`, `bkit-debug-failure-remediate`, `bkit-debug-failure-soak`, `bkit-ship-conflict-resolve` |
|
|
173
|
+
| **XL** | **300** | 60-180 turns | Whole-surface sweeps: every probe step of one audit template against repo and live systems. | `bkit-audit-generate` |
|
|
173
174
|
|
|
174
175
|
**Tier assignment is canonical** — per-agent rows in § Models. Cap hit at any tier → agent stuck (retry loop, infinite re-read) — orchestrator verdict-validation retry handles partial recovery.
|
|
175
176
|
|
|
@@ -206,7 +207,7 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
206
207
|
| `bkit-design-generate` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `kimi-k2.7-code` | `deepseek-v4.1-flash` | `deepseek-v4-pro` | `gpt-6-astra` | `gemini-3.8-pro` | `xhigh` | 100 | generate design from brainstorms (top-of-pipeline synthesizer; whole-doc rewrite) |
|
|
207
208
|
| `bkit-plan-complexity-check` | `claude-sonnet-5-5` | `composer-2.5` | `deepseek/deepseek-v4.1-flash` | `kimi-k2.7-code` | `deepseek-v4.1-flash` | `deepseek-v4-pro` | `gpt-5.6-terra` | `gemini-3.8-pro` | `medium` | 50 | complexity check |
|
|
208
209
|
| `bkit-plan-generate` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `kimi-k2.7-code` | `deepseek-v4.1-flash` | `deepseek-v4-pro` | `gpt-6-astra` | `gemini-3.8-pro` | `xhigh` | 100 | plan draft generator (top-of-pipeline synthesizer) |
|
|
209
|
-
| `bkit-audit-generate` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `kimi-k2.7-code` | `deepseek-v4.1-flash` | `deepseek-v4-pro` | `gpt-6-astra` | `gemini-3.8-pro` | `xhigh` |
|
|
210
|
+
| `bkit-audit-generate` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `kimi-k2.7-code` | `deepseek-v4.1-flash` | `deepseek-v4-pro` | `gpt-6-astra` | `gemini-3.8-pro` | `xhigh` | 300 | audit report from one template (top-of-pipeline synthesizer) |
|
|
210
211
|
| `bkit-plan-review-1` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `kimi-k2.7-code` | `deepseek-v4.1-flash` | `deepseek-v4-pro` | `gpt-6-astra` | `gemini-3.8-pro` | `high` | 100 | review slot 1 (tightness + design-coverage) |
|
|
211
212
|
| `bkit-plan-review-2` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `kimi-k2.7-code` | `deepseek-v4.1-flash` | `deepseek-v4-pro` | `gpt-6-astra` | `gemini-3.8-pro` | `medium` | 100 | review slot 2 (dependency-correctness + design-coverage; depth-sensitive lens — both opus) |
|
|
212
213
|
| `bkit-plan-review-3` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `moonshotai/kimi-k3` | `deepseek-v4-pro` | `deepseek-v4-pro` | `deepseek-v4-pro` | `gpt-6-astra` | `gemini-3.8-pro` | `high` | 100 | review slot 3 (regression-risk + design-coverage) |
|
|
@@ -366,7 +367,7 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
366
367
|
<!-- prettier-ignore -->
|
|
367
368
|
| Agent | Scope |
|
|
368
369
|
| --- | --- |
|
|
369
|
-
| `bkit-audit-generate` | Read one `docs/templates/bkit-audit-*.md` and run its probe steps against the repo. Write the filled template to `docs/audits/{YYYYMM}/{slug}.md` (`{slug}` = template basename without `bkit-audit-`). **If** that month already has this slug → `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Report = template up to `bkit:end`. Writes only the report and the template's consumer-owned `Project Instructions` (below `bkit:end`), which it reads first and refines each run — exact commands, paths, tool gaps, corrections — so the next run starts from what this one learned; edits listed under the report's `Process Improvements` → `Project`, universal step changes proposed under `Universal`. Never results there (reports hold the series) and never text from external input (an injected directive would persist into every later run). Bash is limited to the probes the template or its `Project Instructions` name; throwaway worktrees / remote targets removed before the report finishes. Web tools serve each template's Standards step. `
|
|
370
|
+
| `bkit-audit-generate` | Read one `docs/templates/bkit-audit-*.md` and run its probe steps against the repo. Write the filled template to `docs/audits/{YYYYMM}/{slug}.md` (`{slug}` = template basename without `bkit-audit-`). **If** that month already has this slug → `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Report = template up to `bkit:end`. Right after creating the stub it runs `bkit branches anchor-stamp --base-sha=<HEAD> --base-ref=<branch>`, so the audited commit and the bkit release the report came from sit in the same `bkit:anchor` block design and plan docs carry (`.bkit/workflows.md` § Anchor Block) — top of file, machine-readable, the next run reads it as the previous report's commit; an outdated release also gets a visible `Outdated bkit` line under the block, written by the stamp. The agent runs the stamp itself because audits have no orchestrator; the block is still tool-written, never hand-written. Writes only the report, `docs/failures.jsonl` rows (`workflow: "audit"`, `step: "audit-{slug}"`; one per `MEDIUM`+ finding, reusing any open row's `key` for the same problem whichever workflow wrote it, closing only open `audit-{slug}-` rows a rerun no longer finds; skipped by templates that audit the ledgers themselves, `.bkit/jsonl.md`), and the template's consumer-owned `Project Instructions` (below `bkit:end`), which it reads first and refines each run — exact commands, paths, tool gaps, corrections — so the next run starts from what this one learned; edits listed under the report's `Process Improvements` → `Project`, universal step changes proposed under `Universal`. Never results there (reports hold the series) and never text from external input (an injected directive would persist into every later run). The report's `Suggested Issues` groups findings into tracker-sized changes — one row per change landed in one go, every `MEDIUM`+ finding in exactly one row — and names each row's next step: `/bkit-design|/bkit-plan|/bkit-build|/bkit-debug` by the § When to Run rules of `.bkit/workflows.md` (restated inline, prompts are self-contained), the `.agents/shortcuts.md` lite path (`shortcut:build|shortcut:debug`) when its § When to use allows, or `manual` for a change outside the repo. The agent proposes and never files: it has no tracker access, so a person files from the table and each full workflow's related-issues scan catches an issue already open. Bash is limited to that stamp and the probes the template or its `Project Instructions` name; throwaway worktrees / remote targets removed before the report finishes. Web tools serve each template's Standards step. Pre-Flight `Permissions` probes each tool once before `Probe Steps`; a blocked call (there or in any step) never stops the run: the agent records it with its narrow allow rule, runs every step the remaining tools allow, and lists the work it could not do under `Not Checked`. Blocked calls persist in `Project Instructions` `Permissions`; the next run probes them first. `XL` tier: the longest templates run ~20 probe steps of several queries each against the repo and live systems. A missing surface is an explicit skip, not a clean finding. |
|
|
370
371
|
|
|
371
372
|
Every template under `docs/templates/bkit-audit-*.md`:
|
|
372
373
|
|
|
@@ -281,8 +281,8 @@ Both hosts: `/<filename-without-ext>` (`/bkit-build`, `/bkit-plan`, etc.). Ident
|
|
|
281
281
|
| `readguard-payload.js` | Claude, Cursor, Codex, Google Antigravity `readguard` | read / shell payload adapter `bkitReadguard(payload)`; compaction event → reset |
|
|
282
282
|
| `antigravity-hook.js` | Google Antigravity `gateguard`, `guardrails`, `readguard` | Antigravity envelope → Claude-family shape (`fromAntigravityPayload`), call signature, deny-once advisory delivery (`adviseOnce`) |
|
|
283
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,
|
|
285
|
-
| `guardrails-read.js` | Cursor, Google Antigravity `guardrails` | `classifyRead`: deny `*.pem` / `*.p12` / `id_rsa`, ask `.env` / `.env.*` (not `.env.example`) |
|
|
284
|
+
| `guardrails-tiers.js` | Cursor, Codex, Google Antigravity `guardrails` | shell word / git parsing (`parseGit`), deny + ask rules, `secretFileKind`, shell secret-read detection, `classifyShell` precedence |
|
|
285
|
+
| `guardrails-read.js` | Cursor, Google Antigravity `guardrails` | `classifyRead` over `secretFileKind`: deny `*.pem` / `*.p12` / `id_rsa`, ask `.env` / `.env.*` (not `.env.example`) |
|
|
286
286
|
| `preflight-linear.sh` | Claude, Cursor `preflight` | Linear key / issue checks, GraphQL query, `bkit:auto` + terminal-state guards |
|
|
287
287
|
|
|
288
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.
|
|
@@ -333,8 +333,9 @@ Advisory repeat-read hook, on all five hosts. A read of a line range the same ag
|
|
|
333
333
|
<!-- prettier-ignore -->
|
|
334
334
|
| Concern | Claude | Cursor | opencode | Codex | Antigravity |
|
|
335
335
|
| --- | --- | --- | --- | --- | --- |
|
|
336
|
-
| File / secrets | `.claude/settings.json` → `permissions
|
|
337
|
-
|
|
|
336
|
+
| File / secrets — read tool | `.claude/settings.json` → `permissions` `Read(...)`: `*.pem` / `*.p12` / `id_rsa` deny; `.env` / `.env.*` ask — `.env.example` too: its `allow` row never fires, `ask` is evaluated before `allow` | `.cursor/hooks/bkit-guardrails.cjs` via `preToolUse` (`Read\|TabRead`) — key deny; `.env` / `.env.*` ask; `.env.example` allowed | `.opencode/opencode.json` → `permission.read` map — key deny; `.env` / `.env.*` ask; `.env.example` allowed | **none** — no file-read tool. 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`) — key deny; `.env` / `.env.*` ask (Antigravity's own `ask`); `.env.example` allowed |
|
|
337
|
+
| File / secrets — shell (`cat .bkit/.env`) | **not gated** — no `Bash(...)` rows: a command-text glob cannot tell `cat .env` from `cp .env.example .env`, a grep pattern or a commit message, and an ask stalls autonomous and cloud runs. A file command Claude recognises (`cat`, `head`, `tail`, `sed`, `tee`) on a key file still hits the `Read(...)` deny, which Claude applies to those commands | `beforeShellExecution` ask on any program reading `.env`, `.env.*` (not `.env.example`), `*.pem`, `*.p12` or `id_rsa` (args, `< file`, `--opt=file`, `@file`, `rev:file`, copy sources, `sh -c` scripts); redirect targets, copy destinations, grep / rg patterns, comments and `ls` / `stat` / `test` / `touch` / `rm` / `mv` / `ln` / `chmod` / `echo` pass | **not gated** — no `permission.bash` rows, same reason as Claude | same detection as Cursor via `PreToolUse` (`Bash`) — advisory `additionalContext`, command runs | same detection as Cursor via `PreToolUse` (`run_command`) — Antigravity's own `ask` |
|
|
338
|
+
| Shell / destructive | `permissions.deny` globs on force-push in any argument position — `--force`, `-f` / `-f…` cluster, `+refspec`, never `--force-with-lease` — plus `rm -rf /*`, `chmod -R 777 /`; `permissions.ask` globs on publish, destructive gh, and destructive git in common flag orders (`git reset … --hard`, forced `git clean` (`-…f…`), whole-tree `git checkout` / `git restore`, `git rebase … -i`, `git stash drop`, `git filter-branch`), `--no-verify` on any git subcommand, `git commit -n`. Globs match the command text, so a git global option before the subcommand (`git -C dir push --force`) or a force letter after the first in a cluster (`-uf`) is not matched. 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 tiers, classified on the parsed command: git subcommand after global options (`-C`, `-c`, `--git-dir`, …), flags in any order, short clusters expanded, option values never read as flags; every `&&` / `;` / `\|` segment, `sh -c` script and `$(…)` substitution. `git clean -n` / `--dry-run` and `git restore --staged .` pass | `permission.bash` deny/ask globs, last match wins — same globs and gaps as Claude | `.codex/hooks/bkit-guardrails.cjs` via `PreToolUse` (`Bash`) — Cursor's parsed tiers; deny blocks; ask emitted as advisory `additionalContext`, command runs (Codex cannot prompt) | same hook via `PreToolUse` (`run_command`) — Cursor's parsed tiers; deny blocks every time; ask = Antigravity's own `ask` |
|
|
338
339
|
| 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
340
|
| 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
341
|
| 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 |
|