@cbartens/bkit 5.2.0 → 5.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.bkit/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # bkit — Agent Workflow System
2
2
 
3
- <!-- bkit:managed v5.2.0 — do not edit; run `bkit upgrade` to refresh -->
3
+ <!-- bkit:managed v5.2.1 — 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
 
@@ -30,7 +30,7 @@ Three cloud stacks — each agent pairs with one tracker. Pick row for agent you
30
30
 
31
31
  **Unified file — additive coexistence:** Claude + opencode share one `bkit-cloud.yml`: a `context` job resolves the phase once, then two runner jobs, each runtime-gated on its secret (`ANTHROPIC_API_KEY` claude, `OPENCODE_PROVIDER_KEY` opencode). Both jobs can fire on same CI event — both secrets → both agents; one secret → one agent. Cursor separate (no GH Action; native triggers). **Cursor cloud ↔ Linear.**
32
32
 
33
- **Manual dispatch (Claude or opencode, path A):** GitHub → **Actions** → **bkit-cloud** → **Run workflow** → `phase` (`ship` / `debug` / `plan` / `build`) + `issue`. On-demand/smoke-test for `plan` / `build`; `ship` / `debug` normally CI-fired. `design` runs locally — its Grill step interviews the human; a headless run (`runtimeHeadless` = true: GitHub runner, Cursor cloud agent, unknown runtime) skips the interview and records each recommended answer as `Assumed, not confirmed`. Dispatched `/bkit-auto` orchestrator → matching phase skill → brief from GitHub issue (MCP).
33
+ **Manual dispatch (Claude or opencode, path A):** GitHub → **Actions** → **bkit-cloud** → **Run workflow** → `phase` (`ship` / `debug` / `design` / `plan` / `build`) + `issue`. On-demand/smoke-test for `design` / `plan` / `build`; `ship` / `debug` normally CI-fired. Dispatched `design` runs headless (`runtimeHeadless` = true on a GitHub runner): Grill asks nothing and records each recommended answer as `Assumed, not confirmed`. Dispatched `/bkit-auto` orchestrator → matching phase skill → brief from GitHub issue (MCP).
34
34
 
35
35
  ### Reactive comment handlers (`claude.yml` + `opencode.yml`) — separately managed, not bkit
36
36
 
@@ -409,6 +409,8 @@ bkit ships no compaction setting; each host auto-summarises near the model's ful
409
409
 
410
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
411
 
412
+ **Compression proxies:** bkit ships none (caveman, Headroom). On 456 real Claude Code transcripts they saved ~1–3% of token cost: both keep the prompt cache intact, so each tool result is compressed once on arrival and reused, and tool results ≥ 2 KB are 27% of cost. Headroom's Kompress text model rewrote code (`=> void` → `void`). Method, results, scripts to measure own sessions: [comparison](https://github.com/cbartens/bkit/blob/main/tests/compression/bkit-caveman-headroom-compression-proxy-comparison.md). bkit cuts reading instead, losslessly: § ReadGuard + `Code reads` / `Narrow text search first` in `.agents/rules.md`.
413
+
412
414
  ## MCP project scope
413
415
 
414
416
  A remote MCP server that can see a whole account makes agents look up account and project IDs before every task. Lock its URL to one project and those lookup tools disappear; calls default to that project. Lock it in every host file that declares the server (`.mcp.json`, `.cursor/mcp.json`, `.opencode/opencode.json`, `.codex/config.toml`).
@@ -130,7 +130,7 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
130
130
  - **Design / plan close on HARD STOP** — human review required before next phase.
131
131
  - **No archive step in ship:** artifacts at canonical `docs/plans/{YYYYMM}/` from design start — nothing to move at close.
132
132
  - **Debug three attempt counters = mode-matched pairs**.
133
- - **Runtime capability table:** `bkit runtime detect` classifies the runtime (`LOCAL` / `GITHUB_ACTION` / `CLOUD_CLAUDE` / `CLOUD_CURSOR` / `UNKNOWN`) and emits `runtimeWorktrees` / `runtimeDevPushes` / `runtimeGithubCli` (the `runtime-resolved` row's keys; ship holds two as `{RUNTIME_DEVPUSHES}` / `{RUNTIME_WORKTREES}`) plus `runtimeHeadless`, derived from `runtime` and never stored on the row (`bkit runtime assert` re-derives it; design Step 3 holds it as `{RUNTIME_HEADLESS}`). Headless = `GITHUB_ACTION` / `CLOUD_CURSOR` / `UNKNOWN`: a runner and a triggered Cursor agent have no human to answer, and an unplaceable runtime gets the safe answer — skipping the Grill interview degrades it to assumed answers, while waiting for a human who is absent stalls the run. `LOCAL` and `CLOUD_CLAUDE` (an app session) are attended; `BKIT_RUNTIME` overrides either way. `CLOUD_CURSOR` is detected via a `.bkit/.runtime-cursor` marker written by `.cursor/hooks/bkit-preflight.sh` when `is_background_agent` is true (Cursor exposes that only on stdin JSON to the hook, not as an env var). `RUNTIME_DEVPUSHES` is a conservative DEFAULT, never probed — a `git push --dry-run` sends no ref-update, so a protected branch's pre-receive hook never fires and a false-positive would strand a cloud session on a `dev` checkout. `runtimeGithubCli` is the one live probe (`gh auth status`). An explicit falsy primitive (`CI=false`, `GITHUB_ACTIONS=false`) means ABSENCE, not ambiguity — treating it as ambiguous would cost a laptop its worktree model; only a non-truthy, non-falsy value goes `UNKNOWN`.
133
+ - **Runtime capability table:** `bkit runtime detect` classifies the runtime (`LOCAL` / `GITHUB_ACTION` / `CLOUD_CLAUDE` / `CLOUD_CURSOR` / `UNKNOWN`) and emits `runtimeWorktrees` / `runtimeDevPushes` / `runtimeGithubCli` (the `runtime-resolved` row's keys; ship holds two as `{RUNTIME_DEVPUSHES}` / `{RUNTIME_WORKTREES}`) plus `runtimeHeadless`, derived from `runtime` and never stored on the row (`bkit runtime assert` re-derives it; design Step 3 holds it as `{RUNTIME_HEADLESS}`). Headless = `GITHUB_ACTION` only: a runner job ends when the agent ends its turn, so no reply reaches it. Every other runtime counts as attended; `BKIT_RUNTIME` overrides. `CLOUD_CURSOR` is detected via a `.bkit/.runtime-cursor` marker written by `.cursor/hooks/bkit-preflight.sh` when `is_background_agent` is true (Cursor exposes that only on stdin JSON to the hook, not as an env var). `RUNTIME_DEVPUSHES` is a conservative DEFAULT, never probed — a `git push --dry-run` sends no ref-update, so a protected branch's pre-receive hook never fires and a false-positive would strand a cloud session on a `dev` checkout. `runtimeGithubCli` is the one live probe (`gh auth status`). An explicit falsy primitive (`CI=false`, `GITHUB_ACTIONS=false`) means ABSENCE, not ambiguity — treating it as ambiguous would cost a laptop its worktree model; only a non-truthy, non-falsy value goes `UNKNOWN`.
134
134
  - **Local happy path is byte-identical across the three runtimes:** every runtime branch is additive. `RUNTIME_DEVPUSHES=true` (laptop, GH-Actions runner) runs the local block verbatim — local `merge --squash -X ours`, `docs({FID}): {phase} DONE bkit [skip ci]`, direct `dev` push, worktree teardown. Only `RUNTIME_DEVPUSHES != true` (claude.ai cloud, `unknown`) takes the PR-merge branch. Never replace a working local call site to serve a cloud runtime; branch around it.
135
135
  - **PR-mode design/plan closes MUST push before `bkit prs open`:** PR creation and `gh pr merge` act on the REMOTE, so a close commit that is only committed locally never enters the PR and never reaches `dev`. The `RUNTIME_DEVPUSHES=true` branch pushes `dev` directly and is unaffected; the `false` branch produces two local commits (`chore({FID}): close-workflow` carrying the `status.jsonl` rows and close telemetry, then `docs({FID}): {phase} roadmap update` carrying `.bkit/issues.jsonl` + `docs/roadmap.md`) and needs an explicit `bkit branches push --mode=feature` to publish them. Placed after the STRAY guard so nothing unvetted is published, and before `bkit prs open --existing=reuse`. Build/debug close pushes the feature branch already. Omitting it silently loses every design/plan close on the PR path.
136
136
  - **`bkit workflows close` runs in the worktree, before the squash, in both close modes:** the `workflow-done` row and the telemetry rows ride the `chore({FID}): close-workflow` commit on `feat/{FID}`, so the squash (local) or the PR (cloud) carries them to `dev`. `status.jsonl` and `.bkit/stats.jsonl` are `merge=union`, so the squash concatenates them with `dev`'s copies.
@@ -812,7 +812,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
812
812
  | --- | --- | --- | --- | --- |
813
813
  | 1 — Start Workflow | — | tracker issue | `.lock`, tracker comment | Fetch `origin/dev`. Resolve `{ISSUE_ID}` from the session prompt (no match → stop; never create), set label `bkit:design`, state `In Progress`. no commits on `dev` — `status.jsonl` init + `start-workflow` step entry deferred to Step 2 inside the worktree. |
814
814
  | 2 — Worktree Setup | — | repo | `.worktrees/{FID}`, `bkit.worktree.copy` files, `design-input-{RUN}.md` | `bkit worktrees setup`: create `feat/{FID}` off a freshly fetched `origin/dev`, resume it, or adopt the current branch in place; dependencies installed (install failure → **Failure Path**). `baseSha` → `runtime-resolved` row (§ Anchor Block). |
815
- | 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each round asks the whole frontier (every decision whose prerequisites are settled), numbered, each with a recommended answer worded so "yes" accepts it; plain text, no host question tool. Orchestrator looks up facts; only decisions go to the human. Stops on an empty frontier plus human confirmation, a human stop, or 10 rounds. Agreed answers → `Settled`; unanswered at stop → `Assumed, not confirmed`; "don't know" → `Open`. An earlier run's `Settled` entries stay settled. `grill=false` in the session prompt skips the interview; the artifact then reads `Skipped (grill=false).` `runtimeHeadless` = true (read via `bkit runtime assert`) → no question asked, no turn ended: the tree is walked taking each recommended answer as given, every new answer lands in `Assumed, not confirmed`, and the artifact carries a `Headless run ({RUNTIME})` line. The ideate triplet, generate and both reviewers read the section through `design-input-{RUN}.md`. Waiting time is exempt from the 3600s timeout. Not offered by `bkit-cloud.yml` `workflow_dispatch`; a copy-and-own `bkit-cloud.yml` still offering `design` runs it headless. |
815
+ | 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each round asks the whole frontier (every decision whose prerequisites are settled), numbered, each with a recommended answer worded so "yes" accepts it; plain text, no host question tool. Orchestrator looks up facts; only decisions go to the human. Stops on an empty frontier plus human confirmation, a human stop, or 10 rounds. Agreed answers → `Settled`; unanswered at stop → `Assumed, not confirmed`; "don't know" → `Open`. An earlier run's `Settled` entries stay settled. `grill=false` in the session prompt skips the interview; the artifact then reads `Skipped (grill=false).` `runtimeHeadless` = true (read via `bkit runtime assert`) → no question asked, no turn ended: the tree is walked taking each recommended answer as given, every new answer lands in `Assumed, not confirmed`, and the artifact carries a `Headless run ({RUNTIME})` line. The ideate triplet, generate and both reviewers read the section through `design-input-{RUN}.md`. Waiting time is exempt from the 3600s timeout. A `bkit-cloud.yml` `workflow_dispatch` run is headless. |
816
816
  | 4 — Brainstorm & Ideate | `@bkit-design-brainstorm-ideate-1` ‖ `-2` ‖ `-3` (parallel triplet) | `design-input-{RUN}.md` | `design-brainstorm-ideate-1.md`, `-2.md`, `-3.md` | Pragmatic / optimal-tradeoff / risk-premortem lenses; effort-tier diversity (`high`/`medium`/`high`); sibling-blind. `BRAINSTORM_VERDICT` = worst of three. |
817
817
  | 5 — Generate Design | `@bkit-design-generate` | `design-input-{RUN}.md` (carries the `Grill decisions` section), all three brainstorms, `related-issues.md`, superseded `{YYYYMM}/{FID}-design.md` (if any) | `design-v1-draft.md` (versioned draft) | First write of deliverable design doc. Superseded design = context only, never a constraint; supplied HERE only — not to the sibling-blind ideate triplet. |
818
818
  | 6 — Design Review | `@bkit-design-review-1` ‖ `@bkit-design-review-2` (parallel) | `design-v1-draft.md`, `design-input-{RUN}.md` | `design-review-1.md`, `design-review-2.md` (opinion-only logs) | Effort-tier diversity (high vs medium); sibling-blind. `REVIEW_VERDICT` = worst of two. FAIL → Failure Path. `SPIKE` = `Spike` header from `design-review-1.md` only. |
@@ -18,7 +18,7 @@
18
18
  // GITHUB_ACTIONS or CI truthy GITHUB_ACTION
19
19
  // otherwise LOCAL
20
20
  //
21
- // `runtimeHeadless` (no human attends the session) is derived from `runtime`, never
21
+ // `runtimeHeadless` (no human can reply into the session) is derived from `runtime`, never
22
22
  // stored on the row.
23
23
 
24
24
  import * as fs from "node:fs";
@@ -112,9 +112,8 @@ export function classify(env: NodeJS.ProcessEnv, root: string, log: (m: string)
112
112
  const capable = (runtime: Runtime) =>
113
113
  runtime === "LOCAL" || runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR";
114
114
 
115
- /** No human attends the session: a runner, a triggered Cursor agent, or a runtime bkit cannot place. */
116
- const headless = (runtime: unknown) =>
117
- runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR" || runtime === "UNKNOWN";
115
+ /** No human can reply into the session: a GitHub Actions run. */
116
+ const headless = (runtime: unknown) => runtime === "GITHUB_ACTION";
118
117
 
119
118
  /** The full table: classification, default capabilities, and the one live gh probe. */
120
119
  export function detect(cwd: string, root: string, log: (m: string) => void): RuntimeTable {
@@ -176,8 +175,7 @@ const TABLE_OUTPUT = {
176
175
  runtime: RUNTIMES.join(" | "),
177
176
  runtimeWorktrees: "may mint git worktrees (default per runtime)",
178
177
  runtimeDevPushes: "may push dev (a default, never probed)",
179
- runtimeHeadless:
180
- "no human attends the session (GITHUB_ACTION | CLOUD_CURSOR | UNKNOWN); derived from runtime",
178
+ runtimeHeadless: "no human can reply into the session (GITHUB_ACTION only); derived from runtime",
181
179
  runtimeGithubCli: "gh auth status succeeded",
182
180
  runtimeGithubCliExit: "gh auth status exit code (127 when gh is not on PATH)",
183
181
  runtimeGithubCliErr: "last non-empty line of gh auth status stderr",
@@ -18,9 +18,8 @@ name: bkit-cloud
18
18
  # - workflow_run (CI completion on dev): success -> no-op (regression check passed),
19
19
  # failure -> /bkit-debug {FID} (FID recovered from squash-merge commit scope;
20
20
  # loop-bounded by MAX_DEV_DISPATCH_ATTEMPTS). [skip ci] close commits never trigger CI.
21
- # - workflow_dispatch: pick ANY phase (ship|debug|plan|build) for an issue.
22
- # plan/build have no tracker-event trigger; they run only via dispatch.
23
- # design is not offered: its Grill step interviews a human, so it runs locally only.
21
+ # - workflow_dispatch: pick ANY phase (ship|debug|design|plan|build) for an issue.
22
+ # design/plan/build have no tracker-event trigger; they run only via dispatch.
24
23
  #
25
24
  # Required secrets (claude job): ANTHROPIC_API_KEY + Claude GitHub App (one-time
26
25
  # `/install-github-app` — grants `id-token: write` OIDC for claude-code-action@v1).
@@ -43,6 +42,7 @@ on:
43
42
  options:
44
43
  - ship
45
44
  - debug
45
+ - design
46
46
  - plan
47
47
  - build
48
48
  issue:
@@ -465,7 +465,7 @@ jobs:
465
465
  # `cloud` run to dev's `status.jsonl`, and the dispatched phase skill creates its
466
466
  # own `feat/{FID}` worktree under `.worktrees/`. ship/debug then read+write
467
467
  # their branch-local `status.jsonl` on `feat/{FID}` (worktree-prefer at Step 1);
468
- # plan/build start from dev. NDJSON + `*.jsonl merge=union` keeps it merge-safe.
468
+ # design/plan/build start from dev. NDJSON + `*.jsonl merge=union` keeps it merge-safe.
469
469
  ref: dev
470
470
  fetch-depth: 0
471
471
  # The auto-provided GITHUB_TOKEN inherits the `permissions:` block above.
@@ -493,7 +493,7 @@ jobs:
493
493
  uses: anthropics/claude-code-action@58985842b834ed26087302ba27d07bc24ca8697a # v1.0.244
494
494
  with:
495
495
  # Orchestrator contract: `/bkit-auto <phase> <arg>` where <arg> is the open
496
- # PR number (ship/debug) or the tracker issue number/id (plan/build).
496
+ # PR number (ship/debug) or the tracker issue number/id (design/plan/build).
497
497
  # The context job validated arg against its allowlist.
498
498
  prompt: "/bkit-auto ${{ needs.context.outputs.phase }} ${{ needs.context.outputs.arg }}"
499
499
  # Lock the runner-side session to the same tool surface bkit grants the local
package/CHANGELOG.md CHANGED
@@ -8,6 +8,14 @@ Format: `## [version] — YYYY-MM-DD`
8
8
 
9
9
  ## [Unreleased]
10
10
 
11
+ ## [5.2.1] — 2026-10-15
12
+
13
+ ### Changed
14
+
15
+ - **`/bkit-design` Grill interviews in every runtime except a GitHub Actions run.** `runtimeHeadless` is true only for `GITHUB_ACTION`; `CLOUD_CURSOR` and `UNKNOWN` now count as attended, so Grill asks and waits. `grill=false` still skips; `BKIT_RUNTIME` still overrides.
16
+ - **`bkit-cloud.yml` offers `design` again** in `workflow_dispatch`. A dispatched design runs headless: Grill records its recommended answers as `Assumed, not confirmed` instead of waiting.
17
+ - **Docs: why bkit ships no compression proxy** (#545). `.bkit/providers.md` and the README FAQ: caveman and Headroom saved ~1–3% of token cost on 456 real Claude Code transcripts, and Headroom's text model rewrote code; bkit narrows reads instead.
18
+
11
19
  ## [5.2.0] — 2026-10-15
12
20
 
13
21
  ### Added
package/README.md CHANGED
@@ -224,6 +224,9 @@ No. [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code) i
224
224
  **How does it compare with other tools?**
225
225
  Feature by feature against the main AI development frameworks, from spec toolkits to autonomous agents: [`.bkit/comparison.md`](.bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks).
226
226
 
227
+ **Why doesn't bkit ship a compression proxy like caveman or Headroom?**
228
+ We measured both on 456 real Claude Code transcripts. They saved about 1–3% of token cost. Both protect Claude's prompt cache, so they only shrink tool output as it arrives, and that output was 27% of the cost. Headroom's text model also rewrote code along the way. bkit cuts reading instead, which loses nothing: agents find the definition first and read only those lines, and a hook flags re-reads of files that haven't changed. Method, results and scripts to measure your own sessions: [the comparison](tests/compression/bkit-caveman-headroom-compression-proxy-comparison.md).
229
+
227
230
  <details>
228
231
  <summary><strong>For engineers: what's under the hood</strong></summary>
229
232
 
@@ -18,7 +18,7 @@
18
18
  // GITHUB_ACTIONS or CI truthy GITHUB_ACTION
19
19
  // otherwise LOCAL
20
20
  //
21
- // `runtimeHeadless` (no human attends the session) is derived from `runtime`, never
21
+ // `runtimeHeadless` (no human can reply into the session) is derived from `runtime`, never
22
22
  // stored on the row.
23
23
  import * as fs from "node:fs";
24
24
  import * as path from "node:path";
@@ -85,8 +85,8 @@ export function classify(env, root, log) {
85
85
  * session's proxy only lets it push the current branch, so it gets neither.
86
86
  */
87
87
  const capable = (runtime) => runtime === "LOCAL" || runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR";
88
- /** No human attends the session: a runner, a triggered Cursor agent, or a runtime bkit cannot place. */
89
- const headless = (runtime) => runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR" || runtime === "UNKNOWN";
88
+ /** No human can reply into the session: a GitHub Actions run. */
89
+ const headless = (runtime) => runtime === "GITHUB_ACTION";
90
90
  /** The full table: classification, default capabilities, and the one live gh probe. */
91
91
  export function detect(cwd, root, log) {
92
92
  const runtime = classify(process.env, root, log);
@@ -141,7 +141,7 @@ const TABLE_OUTPUT = {
141
141
  runtime: RUNTIMES.join(" | "),
142
142
  runtimeWorktrees: "may mint git worktrees (default per runtime)",
143
143
  runtimeDevPushes: "may push dev (a default, never probed)",
144
- runtimeHeadless: "no human attends the session (GITHUB_ACTION | CLOUD_CURSOR | UNKNOWN); derived from runtime",
144
+ runtimeHeadless: "no human can reply into the session (GITHUB_ACTION only); derived from runtime",
145
145
  runtimeGithubCli: "gh auth status succeeded",
146
146
  runtimeGithubCliExit: "gh auth status exit code (127 when gh is not on PATH)",
147
147
  runtimeGithubCliErr: "last non-empty line of gh auth status stderr",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cbartens/bkit",
3
- "version": "5.2.0",
3
+ "version": "5.2.1",
4
4
  "private": false,
5
5
  "description": "From vibe coding to production code. A senior engineering team's process, ready-made: AI agents design, plan, build, review, fix and ship your features on Claude Code, Cursor, Codex, Google Antigravity and opencode.",
6
6
  "keywords": [