@cbartens/bkit 5.0.0 → 5.0.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 +10 -14
- package/.bkit/core/.bkit/README.md +9 -13
- package/.bkit/core/.bkit/cloud.md +15 -24
- package/.bkit/core/.bkit/comparison.md +4 -1
- package/.bkit/core/.bkit/install.md +54 -149
- package/.bkit/core/.bkit/jsonl.md +5 -5
- package/.bkit/core/.bkit/templates.md +2 -3
- package/.bkit/core/.bkit/workflows.md +7 -3
- package/.bkit/core/engine/checks/after/auth.ts +16 -114
- package/.bkit/core/engine/checks/after/ci-yml.ts +36 -74
- package/.bkit/core/engine/checks/after/index.ts +156 -182
- package/.bkit/core/engine/checks/after/suppression.ts +53 -0
- package/.bkit/core/engine/checks/before/env.ts +4 -18
- package/.bkit/core/engine/checks/before/files.ts +2 -0
- package/.bkit/core/engine/cli.ts +4 -8
- package/.bkit/core/engine/commands/install/doctor.ts +9 -2
- package/.bkit/core/engine/commands/install/install.ts +24 -2
- package/.bkit/core/engine/commands/install/uninstall.ts +23 -0
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -3
- package/.bkit/core/engine/commands/lib.ts +4 -3
- package/.bkit/core/engine/install/cloud-env.ts +0 -1
- package/.bkit/core/engine/install/modules/cloud.ts +2 -3
- package/.bkit/core/engine/install/modules/core.ts +33 -13
- package/.bkit/core/engine/install/payload-links.ts +150 -0
- package/.bkit/core/engine/install/template-copies.ts +1 -1
- package/.bkit/core/engine/shared/egress.ts +1 -1
- package/.bkit/core/workflows/bkit-debug.md +19 -12
- package/.bkit/shared/.bkit/.env.example +2 -24
- package/.bkit/shared/docs/deployments.md +2 -7
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/gitignore +5 -0
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +0 -5
- package/.bkit/templates/.cursor/Dockerfile +1 -1
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/renovate.json5 +0 -15
- package/.bkit/templates/.github/workflows/bkit-ci.yml +2 -22
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +0 -2
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +0 -5
- package/CHANGELOG.md +17 -0
- package/README.md +5 -6
- package/dist/checks/after/auth.js +16 -108
- package/dist/checks/after/ci-yml.js +30 -67
- package/dist/checks/after/index.js +136 -152
- package/dist/checks/after/suppression.js +39 -0
- package/dist/checks/before/env.js +4 -14
- package/dist/checks/before/files.js +2 -0
- package/dist/cli.js +4 -8
- package/dist/commands/install/doctor.js +4 -2
- package/dist/commands/install/install.js +16 -2
- package/dist/commands/install/uninstall.js +24 -0
- package/dist/commands/install/upgrade.js +14 -3
- package/dist/commands/lib.js +4 -3
- package/dist/install/cloud-env.js +0 -1
- package/dist/install/modules/cloud.js +2 -3
- package/dist/install/modules/core.js +33 -13
- package/dist/install/payload-links.js +119 -0
- package/dist/install/template-copies.js +1 -1
- package/dist/shared/egress.js +1 -1
- package/package.json +2 -2
- package/.bkit/core/engine/checks/after/vercel.ts +0 -101
- package/dist/checks/after/vercel.js +0 -102
package/.bkit/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# bkit — Agent Workflow System
|
|
2
2
|
|
|
3
|
-
<!-- bkit:managed v5.0.
|
|
3
|
+
<!-- bkit:managed v5.0.1 — PolyForm Noncommercial 1.0.0 / Small Business 1.0.0 (https://polyformproject.org/licenses/) — do not edit; run `bkit upgrade` to refresh -->
|
|
4
4
|
|
|
5
5
|
**bkit** wires Claude Code (and Cursor) into five-phase tracker-integrated cycle: `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`. Hosts additive: `.claude/` + `.cursor/` always render (direct Anthropic); `bkit install --opencode=<provider>` adds opencode for non-Anthropic backends — four providers: `openrouter`, `ollama`, `opencode-zen` + `opencode-go` (opencode-native gateways; auth via `BKIT_OPENCODE_API_KEY`) — same harness, inference backend only changes (see `.bkit/providers.md` § Hosts + Providers).
|
|
6
6
|
|
|
@@ -162,25 +162,19 @@ Full Linear ↔ Cursor setup: <https://linear.app/docs/cursor>.
|
|
|
162
162
|
|
|
163
163
|
`.agents/` = **canonical**. `bkit install` regenerates host outputs (`.claude/**`, `.cursor/**`) and rewrites bkit-managed blocks across consumer repo.
|
|
164
164
|
|
|
165
|
-
First-time install
|
|
165
|
+
First-time install and upgrade, uninstall: `.bkit/install.md`. Ongoing ops below.
|
|
166
166
|
|
|
167
167
|
### Upgrade — paste into your AI
|
|
168
168
|
|
|
169
|
-
Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`.
|
|
169
|
+
Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`.
|
|
170
170
|
|
|
171
171
|
````text
|
|
172
172
|
Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
|
|
173
|
-
1.
|
|
174
|
-
```bash
|
|
175
|
-
set -a; source <ENV-FILE-PATH> 2>/dev/null; set +a; \
|
|
176
|
-
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" && \
|
|
177
|
-
bkit upgrade --latest
|
|
178
|
-
```
|
|
179
|
-
If token already exported (direnv / shell profile), skip `source`:
|
|
173
|
+
1. Bump and resync in one step (no token — npmjs is public). If `bkit` is not on PATH, use `pnpm bkit`:
|
|
180
174
|
```bash
|
|
181
175
|
bkit upgrade --latest
|
|
182
176
|
```
|
|
183
|
-
|
|
177
|
+
Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
|
|
184
178
|
2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why.
|
|
185
179
|
3. Read the template changes `bkit upgrade` printed (or `git diff .bkit/templates`), then `.bkit/templates.md`. bkit never applies templates, so adoption is your job: adopt each change unless it would break existing functionality. For any change not adopted, state which and why.
|
|
186
180
|
4. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
|
|
@@ -248,6 +242,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
|
248
242
|
| `docs/templates/bkit-*.md` | core | `.bkit/core/docs/templates/` | Tier 2 html-comment |
|
|
249
243
|
| `.gitattributes` | core | `.bkit/shared/.gitattributes` | Tier 2 html-comment (`merge=union` for the append-only ledgers) |
|
|
250
244
|
| `.bkit/templates/**` | — | the whole `.bkit/templates/` root | Raw copies, refreshed on every install and upgrade; never hashed. Upgrade prints the changed paths. |
|
|
245
|
+
| `.bkit/{core,shared}` | core | symlink into `node_modules/@cbartens/bkit/.bkit/{core,shared}` | View link, not a copy — browse the payload in-repo; always the installed version. Gitignored (dangles on a fresh clone / CI; install recreates). A real directory is never clobbered; `bkit uninstall` removes the link. |
|
|
251
246
|
| `.bkit/{cloud,comparison,install,jsonl,LICENSE,providers,prompts,trackers,workflows,README}.md` | core | `.bkit/core/.bkit/` | Tier 1 (canonical-overwrite). The reference docs agents read at runtime, plus `LICENSE.md`: the PolyForm pair and Required Notice that travel with every file bkit writes (PolyForm's Notices section). |
|
|
252
247
|
| `.claude/commands/bkit-*.md` | claude | `.bkit/core/workflows/` (byte-identical) | Host pass — always overwrite |
|
|
253
248
|
| `.claude/agents/bkit-*.md` | claude | `.bkit/core/prompts/` (byte-identical) | Host pass — always overwrite |
|
|
@@ -386,13 +381,14 @@ Installed list: `.agents/skills.md`. Skills in `.agents/skills/` not listed →
|
|
|
386
381
|
|
|
387
382
|
### In the installed package, not your repo
|
|
388
383
|
|
|
389
|
-
`bkit install` does not copy these out of `node_modules`. Read them at the path below —
|
|
390
|
-
|
|
384
|
+
`bkit install` does not copy these out of `node_modules`. Read them at the path below — or
|
|
385
|
+
in-repo through the `.bkit/core` / `.bkit/shared` view links install creates (symlinks into
|
|
386
|
+
the package, so editors resolve them to the `node_modules/…` paths).
|
|
391
387
|
|
|
392
388
|
<!-- prettier-ignore -->
|
|
393
389
|
| File | Purpose |
|
|
394
390
|
| --- | --- |
|
|
395
|
-
| `.bkit/install.md` | First-time install
|
|
391
|
+
| `.bkit/install.md` | First-time install and upgrade, install lifecycle, uninstall |
|
|
396
392
|
| `.bkit/comparison.md` | Pipeline reference + comparison to agentic design patterns / peer frameworks |
|
|
397
393
|
| `node_modules/@cbartens/bkit/.bkit/core/workflows/` | Canonical slash-command source (rendered into `.claude/commands/`, `.cursor/commands/`, `.opencode/commands/`) |
|
|
398
394
|
| `node_modules/@cbartens/bkit/.bkit/core/prompts/` | Canonical subagent source (rendered into `.claude/agents/`, `.cursor/agents/`, `.opencode/agents/`) |
|
|
@@ -162,25 +162,19 @@ Full Linear ↔ Cursor setup: <https://linear.app/docs/cursor>.
|
|
|
162
162
|
|
|
163
163
|
`.agents/` = **canonical**. `bkit install` regenerates host outputs (`.claude/**`, `.cursor/**`) and rewrites bkit-managed blocks across consumer repo.
|
|
164
164
|
|
|
165
|
-
First-time install
|
|
165
|
+
First-time install and upgrade, uninstall: `.bkit/install.md`. Ongoing ops below.
|
|
166
166
|
|
|
167
167
|
### Upgrade — paste into your AI
|
|
168
168
|
|
|
169
|
-
Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`.
|
|
169
|
+
Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`.
|
|
170
170
|
|
|
171
171
|
````text
|
|
172
172
|
Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
|
|
173
|
-
1.
|
|
174
|
-
```bash
|
|
175
|
-
set -a; source <ENV-FILE-PATH> 2>/dev/null; set +a; \
|
|
176
|
-
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" && \
|
|
177
|
-
bkit upgrade --latest
|
|
178
|
-
```
|
|
179
|
-
If token already exported (direnv / shell profile), skip `source`:
|
|
173
|
+
1. Bump and resync in one step (no token — npmjs is public). If `bkit` is not on PATH, use `pnpm bkit`:
|
|
180
174
|
```bash
|
|
181
175
|
bkit upgrade --latest
|
|
182
176
|
```
|
|
183
|
-
|
|
177
|
+
Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
|
|
184
178
|
2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why.
|
|
185
179
|
3. Read the template changes `bkit upgrade` printed (or `git diff .bkit/templates`), then `.bkit/templates.md`. bkit never applies templates, so adoption is your job: adopt each change unless it would break existing functionality. For any change not adopted, state which and why.
|
|
186
180
|
4. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
|
|
@@ -248,6 +242,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
|
248
242
|
| `docs/templates/bkit-*.md` | core | `.bkit/core/docs/templates/` | Tier 2 html-comment |
|
|
249
243
|
| `.gitattributes` | core | `.bkit/shared/.gitattributes` | Tier 2 html-comment (`merge=union` for the append-only ledgers) |
|
|
250
244
|
| `.bkit/templates/**` | — | the whole `.bkit/templates/` root | Raw copies, refreshed on every install and upgrade; never hashed. Upgrade prints the changed paths. |
|
|
245
|
+
| `.bkit/{core,shared}` | core | symlink into `node_modules/@cbartens/bkit/.bkit/{core,shared}` | View link, not a copy — browse the payload in-repo; always the installed version. Gitignored (dangles on a fresh clone / CI; install recreates). A real directory is never clobbered; `bkit uninstall` removes the link. |
|
|
251
246
|
| `.bkit/{cloud,comparison,install,jsonl,LICENSE,providers,prompts,trackers,workflows,README}.md` | core | `.bkit/core/.bkit/` | Tier 1 (canonical-overwrite). The reference docs agents read at runtime, plus `LICENSE.md`: the PolyForm pair and Required Notice that travel with every file bkit writes (PolyForm's Notices section). |
|
|
252
247
|
| `.claude/commands/bkit-*.md` | claude | `.bkit/core/workflows/` (byte-identical) | Host pass — always overwrite |
|
|
253
248
|
| `.claude/agents/bkit-*.md` | claude | `.bkit/core/prompts/` (byte-identical) | Host pass — always overwrite |
|
|
@@ -386,13 +381,14 @@ Installed list: `.agents/skills.md`. Skills in `.agents/skills/` not listed →
|
|
|
386
381
|
|
|
387
382
|
### In the installed package, not your repo
|
|
388
383
|
|
|
389
|
-
`bkit install` does not copy these out of `node_modules`. Read them at the path below —
|
|
390
|
-
|
|
384
|
+
`bkit install` does not copy these out of `node_modules`. Read them at the path below — or
|
|
385
|
+
in-repo through the `.bkit/core` / `.bkit/shared` view links install creates (symlinks into
|
|
386
|
+
the package, so editors resolve them to the `node_modules/…` paths).
|
|
391
387
|
|
|
392
388
|
<!-- prettier-ignore -->
|
|
393
389
|
| File | Purpose |
|
|
394
390
|
| --- | --- |
|
|
395
|
-
| `.bkit/install.md` | First-time install
|
|
391
|
+
| `.bkit/install.md` | First-time install and upgrade, install lifecycle, uninstall |
|
|
396
392
|
| `.bkit/comparison.md` | Pipeline reference + comparison to agentic design patterns / peer frameworks |
|
|
397
393
|
| `node_modules/@cbartens/bkit/.bkit/core/workflows/` | Canonical slash-command source (rendered into `.claude/commands/`, `.cursor/commands/`, `.opencode/commands/`) |
|
|
398
394
|
| `node_modules/@cbartens/bkit/.bkit/core/prompts/` | Canonical subagent source (rendered into `.claude/agents/`, `.cursor/agents/`, `.opencode/agents/`) |
|
|
@@ -49,15 +49,15 @@ Three cloud stacks — each agent pairs with one tracker. Pick row for agent you
|
|
|
49
49
|
<!-- prettier-ignore -->
|
|
50
50
|
| Configuration | Lives in the repo (bkit-managed) | Lives in the online dashboard (manual, one-time) |
|
|
51
51
|
| --- | --- | --- |
|
|
52
|
-
| **Claude Code on the web** | `.claude/hooks/bkit-preflight.sh` (tracker opt-in guard) + `.claude/hooks/bkit-cloud-bootstrap.sh` (per-session install — copy-and-own template, adopt it from `.bkit/templates/`) | `claude.ai/code` → environment selector → **+ Add environment**: name, **setup script** (paste from § Setup script), **environment variables** (`BKIT_GH_TOKEN`, `
|
|
53
|
-
| **Cursor Cloud Agents** | `.cursor/Dockerfile` + `.cursor/environment.json` (`install` / `start` / `terminals[]` / `env`), both copied from bkit's templates and owned by the repo, + `.cursor/hooks.json` (wires preflight `failClosed: true`) + `.cursor/hooks/bkit-preflight.sh` (Linear guard) | Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab, as **Runtime Secret**s: `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN
|
|
52
|
+
| **Claude Code on the web** | `.claude/hooks/bkit-preflight.sh` (tracker opt-in guard) + `.claude/hooks/bkit-cloud-bootstrap.sh` (per-session install — copy-and-own template, adopt it from `.bkit/templates/`) | `claude.ai/code` → environment selector → **+ Add environment**: name, **setup script** (paste from § Setup script), **environment variables** (`BKIT_GH_TOKEN`, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` — Claude pairs with the **GitHub** tracker, so no `BKIT_LINEAR_API_KEY`), **network access** (`Trusted`) |
|
|
53
|
+
| **Cursor Cloud Agents** | `.cursor/Dockerfile` + `.cursor/environment.json` (`install` / `start` / `terminals[]` / `env`), both copied from bkit's templates and owned by the repo, + `.cursor/hooks.json` (wires preflight `failClosed: true`) + `.cursor/hooks/bkit-preflight.sh` (Linear guard) | Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab, as **Runtime Secret**s: `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN`. (`LINEAR_ISSUE_ID` injected per-session by the integration — don't hardcode.) |
|
|
54
54
|
|
|
55
55
|
**Rule of thumb:** env vars / auth tokens → online dashboard (out of git). Scripts / Dockerfile / install hooks → repo.
|
|
56
56
|
|
|
57
57
|
**Alignment guarantees bkit enforces:**
|
|
58
58
|
|
|
59
59
|
- Same vale version (3.9.1) pre-installed on both clouds.
|
|
60
|
-
- pnpm via corepack on both. Pastes pre-warm bkit's pin (`10.34.
|
|
60
|
+
- pnpm via corepack on both. Pastes pre-warm bkit's pin (`10.34.4`), but corepack resolves **each repo's own `packageManager`** in-repo — one setup script serves any pnpm pin; pre-warm version not load-bearing.
|
|
61
61
|
- gh CLI on both: web setup script installs latest binary (same `github.com` release-download style as vale); GitHub-Actions runner ships pre-installed. Auth shared via `bkit-cloud-bootstrap.sh` (`gh auth login --with-token` with `BKIT_GH_TOKEN`, skipped when `GITHUB_TOKEN` already auths on runner).
|
|
62
62
|
- Same opt-in-guard pattern — opt-in label `bkit:auto` — wrapped in `<!-- bkit:start --> ... <!-- bkit:end -->` (bkit-managed in consumer repos). Label `bkit:auto` on both trackers.
|
|
63
63
|
|
|
@@ -95,7 +95,7 @@ Open `claude.ai/code` → environment selector → **+ Add environment**. Three
|
|
|
95
95
|
## In-repo side
|
|
96
96
|
|
|
97
97
|
- `.claude/hooks/bkit-preflight.sh` — Tracker opt-in guard. Skips silently when tracker issue ID env var unset (IDE sessions). Non-zero exit informational only on Claude (`SessionStart` cannot block); agent reads `HARD STOP` text from `additionalContext`.
|
|
98
|
-
- `.claude/hooks/bkit-cloud-bootstrap.sh` —
|
|
98
|
+
- `.claude/hooks/bkit-cloud-bootstrap.sh` — runs `pnpm install --frozen-lockfile` + `vale sync` when `CLAUDE_CODE_REMOTE=true`; then, through the just-installed bkit (`bkit runtime detect` gh probe, `bkit context list-blocks` provision recipes, read with `jq`), gh auth and context-fetch CLI provisioning — skipped with a loud log line when bkit or `jq` is missing. No-op locally.
|
|
99
99
|
- Both registered in `.claude/settings.json` under `hooks.SessionStart`.
|
|
100
100
|
|
|
101
101
|
Ships with repo — don't paste into app.
|
|
@@ -106,13 +106,13 @@ Ships with repo — don't paste into app.
|
|
|
106
106
|
|
|
107
107
|
Name environment **after the repo** — one env per repo, secrets isolated (§ Sharing across repos). Setup script identical across repos.
|
|
108
108
|
|
|
109
|
-
Identical across repos: **setup-script body**, **network policy**, bkit **baseline token names** (`BKIT_GH_TOKEN`, `
|
|
109
|
+
Identical across repos: **setup-script body**, **network policy**, bkit **baseline token names** (`BKIT_GH_TOKEN`, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`) — only values change. Rest of env-vars box is **this repo's own**, copied from env-var files per `.envrc` (§ Environment variables).
|
|
110
110
|
|
|
111
111
|
### Network access
|
|
112
112
|
|
|
113
113
|
Always `Custom` — the rendered list carries bkit's own shipped hosts (trackers, registries, agent + provider APIs, the search host a `context=web` block calls) whether or not the repo declares anything. Select **Custom**, tick **Also include default list of common package managers** (EXTENDS trusted defaults — package registries, GitHub, cloud SDKs — never replaces them), paste domains bkit renders into `.claude/bkit-cloud.md` § Network access into **Allowed domains**. Declare only what bkit cannot see: log-backend/API hosts the implicit CLI blocks reach (`vercel` / `gcloud`) plus app production + preview/dev domains — apex-only, expanded by `bkit install` to `<domain>` + `*.<domain>` and unioned with the derived set. Under `Trusted` those hosts unreachable → cloud `/bkit-debug` gets no runtime logs; e2e can't hit deployment.
|
|
114
114
|
|
|
115
|
-
No `allowed-domains` block still needs `Custom`: `Trusted` does not reach bkit's own tracker MCP, provider catalog or search hosts. Ticking **Also include default list of common package managers** keeps npm,
|
|
115
|
+
No `allowed-domains` block still needs `Custom`: `Trusted` does not reach bkit's own tracker MCP, provider catalog or search hosts. Ticking **Also include default list of common package managers** keeps npm, the vale tarball on `objects.githubusercontent.com`, Docker Hub and PyPI. Raise to `Full` only for open-internet tasks.
|
|
116
116
|
|
|
117
117
|
### Environment variables
|
|
118
118
|
|
|
@@ -120,7 +120,6 @@ Minimum:
|
|
|
120
120
|
|
|
121
121
|
```
|
|
122
122
|
BKIT_GH_TOKEN=<fine-grained PAT — see permissions below>
|
|
123
|
-
BKIT_GH_TOKEN_INSTALL=<classic PAT with read:packages>
|
|
124
123
|
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70
|
|
125
124
|
```
|
|
126
125
|
|
|
@@ -133,12 +132,6 @@ VERCEL_TOKEN=<Vercel access token — https://vercel.com/account/settings/tokens
|
|
|
133
132
|
SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/dashboard/account/tokens>
|
|
134
133
|
```
|
|
135
134
|
|
|
136
|
-
Release-only:
|
|
137
|
-
|
|
138
|
-
```
|
|
139
|
-
GITHUB_TOKEN=<classic PAT with write:packages + repo>
|
|
140
|
-
```
|
|
141
|
-
|
|
142
135
|
#### `BKIT_GH_TOKEN` — fine-grained PAT permissions
|
|
143
136
|
|
|
144
137
|
Use **fine-grained** PAT scoped to target repo (or each consumer repo, comma-separated). Mandatory expiry, repo-scoped blast radius — wins given env vars are plaintext.
|
|
@@ -160,7 +153,6 @@ Use **fine-grained** PAT scoped to target repo (or each consumer repo, comma-sep
|
|
|
160
153
|
|
|
161
154
|
#### When classic is still required
|
|
162
155
|
|
|
163
|
-
- **`pnpm publish` to GitHub Packages.** Fine-grained packages support has edge cases on user-owned packages. Classic PAT (`write:packages` + `repo`) in `GITHUB_TOKEN`, separate from `BKIT_GH_TOKEN`. Release-flow sessions only.
|
|
164
156
|
- **Cross-repo work in single cloud session.** Fine-grained PATs only see allowlist; classic sees everything your user can.
|
|
165
157
|
- **User-owned (personal-account) Projects v2 boards.** Fine-grained PATs expose Projects only as _organization_ permission — personal boards unreachable. Classic PAT with `project` scope, or move board under org.
|
|
166
158
|
|
|
@@ -207,15 +199,15 @@ Auto mode drops blanket `Bash(*)` on entry (narrow rows survive) → cloud auto-
|
|
|
207
199
|
|
|
208
200
|
Token management by session type:
|
|
209
201
|
|
|
210
|
-
- **Local sessions** — bkit writes `.bkit/.env.example` (token placeholders); `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy `.bkit/templates/.envrc`. Copy `.env.example` → `.bkit/.env`, fill tokens, `direnv allow`. direnv auto-exports `BKIT_GH_TOKEN`, `
|
|
202
|
+
- **Local sessions** — bkit writes `.bkit/.env.example` (token placeholders); `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy `.bkit/templates/.envrc`. Copy `.env.example` → `.bkit/.env`, fill tokens, `direnv allow`. direnv auto-exports `BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY` on repo entry — no manual `source` or shell-rc export. `.bkit/.env` gitignored; never commit.
|
|
211
203
|
|
|
212
204
|
```bash
|
|
213
205
|
cp .bkit/.env.example .bkit/.env
|
|
214
|
-
# edit .bkit/.env — fill in BKIT_GH_TOKEN,
|
|
206
|
+
# edit .bkit/.env — fill in BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY
|
|
215
207
|
direnv allow
|
|
216
208
|
```
|
|
217
209
|
|
|
218
|
-
- **Cloud sessions** (Claude Code on the web, Cursor Cloud Agents) — `.bkit/.env` absent in cloud containers. Set same names (`BKIT_GH_TOKEN`, `
|
|
210
|
+
- **Cloud sessions** (Claude Code on the web, Cursor Cloud Agents) — `.bkit/.env` absent in cloud containers. Set same names (`BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY`) in respective dashboards: Claude app → environment selector → Environment variables; Cursor Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents`) → your environment → **Secrets** tab (as **Runtime Secret**s). Dashboard lists in sections below = canonical reference for names.
|
|
219
211
|
|
|
220
212
|
**Beyond bkit tokens** — populate rest from _that repo's_ env-var files `.envrc` sources (e.g. `.bkit/.env`, then app `.env.local`). Don't hand-pick from memory; **copy from those files, following `.envrc`**:
|
|
221
213
|
|
|
@@ -252,7 +244,7 @@ bkit wires two MCP servers into `.mcp.json` at repo root (project-shared, read b
|
|
|
252
244
|
|
|
253
245
|
**`gh auth login` required for gh CLI surface** (PR creation, branch ops, git push). Locally, keyring — do not export `GH_TOKEN` from `.bkit/.env`. Cloud/headless: `bkit-cloud-bootstrap.sh` runs `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` at SessionStart (guarded by the `bkit runtime detect` gh probe, no-ops on Actions runner where `GITHUB_TOKEN` auths) — no manual step. Same PAT value fine; different env-var name keeps local `gh` on keyring.
|
|
254
246
|
|
|
255
|
-
**Cloud sessions** (Claude on the web, Cursor Cloud Agents): Linear MCP OAuth on first touch, same as local. GitHub MCP reads `BKIT_GH_TOKEN` from dashboard — set alongside `BKIT_LINEAR_API_KEY
|
|
247
|
+
**Cloud sessions** (Claude on the web, Cursor Cloud Agents): Linear MCP OAuth on first touch, same as local. GitHub MCP reads `BKIT_GH_TOKEN` from dashboard — set alongside `BKIT_LINEAR_API_KEY`.
|
|
256
248
|
|
|
257
249
|
## After saving the Claude env
|
|
258
250
|
|
|
@@ -294,7 +286,7 @@ Everything in repo under `.cursor/`. bkit ships canonical content for all four f
|
|
|
294
286
|
| File | Role | bkit ownership |
|
|
295
287
|
| --- | --- | --- |
|
|
296
288
|
| `.cursor/Dockerfile` | Cloud image — vale + gh + Node 20 (template default) + pnpm (corepack-pinned); browsers etc. added by the consumer | Template: copy from `.bkit/templates/.cursor/Dockerfile`; yours after |
|
|
297
|
-
| `.cursor/environment.json` | Build pointer + per-snapshot `install` hook (`pnpm
|
|
289
|
+
| `.cursor/environment.json` | Build pointer + per-snapshot `install` hook (`pnpm install --frozen-lockfile` + `vale sync` if `.vale.ini`) | Template: copy from `.bkit/templates/.cursor/environment.json`; yours after |
|
|
298
290
|
| `.cursor/hooks.json` | Wires `sessionStart` → `bkit-preflight.sh` (`failClosed: true`) | Tier 2 contained JSON |
|
|
299
291
|
| `.cursor/hooks/bkit-preflight.sh` | Tracker opt-in guard — `bkit:auto` label + non-terminal status. Skips silently on IDE sessions | Tier 2 contained (bkit:start/end markers) |
|
|
300
292
|
|
|
@@ -320,7 +312,7 @@ GitHub dispatch uses Cursor Automations "Pull request label changed" trigger —
|
|
|
320
312
|
BKIT_GH_TOKEN=<fine-grained PAT — same permissions as the Claude side>
|
|
321
313
|
```
|
|
322
314
|
|
|
323
|
-
`GITHUB_ISSUE_ID` injected per-session — do not hardcode. No `BKIT_LINEAR_API_KEY
|
|
315
|
+
`GITHUB_ISSUE_ID` injected per-session — do not hardcode. No `BKIT_LINEAR_API_KEY` or `LINEAR_ISSUE_ID` for tracker calls (MCP auth = browser OAuth; `gh` uses `gh auth login` locally or `--with-token` in cloud bootstrap).
|
|
324
316
|
|
|
325
317
|
## How Linear dispatch works
|
|
326
318
|
|
|
@@ -338,7 +330,6 @@ Set in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your
|
|
|
338
330
|
```
|
|
339
331
|
BKIT_LINEAR_API_KEY=<Linear personal API key — bkit-preflight.sh calls the GraphQL API>
|
|
340
332
|
BKIT_GH_TOKEN=<fine-grained PAT — same permissions as the Claude side>
|
|
341
|
-
BKIT_GH_TOKEN_INSTALL=<classic PAT with read:packages — consumer repos only>
|
|
342
333
|
```
|
|
343
334
|
|
|
344
335
|
`LINEAR_ISSUE_ID` injected per-session by Cursor / Linear integration — do not hardcode.
|
|
@@ -372,7 +363,7 @@ Each repo gets **own** Claude environment, named after repo. Reason: **secrets,
|
|
|
372
363
|
Shared across repos (copy, don't re-derive) — non-secret only:
|
|
373
364
|
|
|
374
365
|
- **Setup script** — generic binaries only (vale, gh, pnpm via corepack); repo-specific install deferred to committed `bkit-cloud-bootstrap.sh` (lockfile → `pnpm install`, `.vale.ini` → `vale sync`). One body fits every repo.
|
|
375
|
-
- **bkit baseline token _names_** (`BKIT_GH_TOKEN`, `
|
|
366
|
+
- **bkit baseline token _names_** (`BKIT_GH_TOKEN`, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`) + **network policy** (`Trusted`) — same everywhere, values differ. Repo _other_ env vars **not** shared: copy from own env files per `.envrc` — drop `unset`s, skip `BKIT_ANTHROPIC_API_KEY` (§ Environment variables).
|
|
376
367
|
- **Non-secret selectors** (`VERCEL_SCOPE`, `SUPABASE_PROJECT_ID`) stay committed in-repo (§ Environment variables), never in dashboard.
|
|
377
368
|
|
|
378
369
|
## Cursor — byte-identical Dockerfile
|
|
@@ -392,7 +383,7 @@ When bkit reference Dockerfile changes (e.g. vale bump):
|
|
|
392
383
|
## What every consumer repo needs to do
|
|
393
384
|
|
|
394
385
|
1. `pnpm bkit install` — bkit-managed toolchain updates land in the written payload; `.claude/hooks/bkit-cloud-bootstrap.sh` is a copy-and-own template, so diff it against `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` when `bkit upgrade` lists that path and merge what you want. `.cursor/Dockerfile` is your copy of a template: diff it against `.bkit/templates/.cursor/Dockerfile` when `bkit upgrade` lists that path.
|
|
395
|
-
2. Set `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN
|
|
386
|
+
2. Set `BKIT_LINEAR_API_KEY`, `BKIT_GH_TOKEN` as **Runtime Secret**s in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab). Paste-ready values are in `.cursor/bkit-cloud.md`.
|
|
396
387
|
3. Add Claude environment **named after repo** at `claude.ai/code`; paste recipe from § Claude Code on the web (one environment per repo — secrets per-repo).
|
|
397
388
|
4. Customise `.cursor/Dockerfile` Node major / Playwright / extra system deps. Keep the `bkit toolchain` section as the template ships it, so a template diff stays readable.
|
|
398
389
|
|
|
@@ -438,7 +429,7 @@ Flip **both** org and repo before first router run — else `actions/checkout` 4
|
|
|
438
429
|
|
|
439
430
|
A `context` job checks both secrets and resolves phase + arg once; each runner job needs it and runs only when its own secret is set. Only `ANTHROPIC_API_KEY` → claude job only. Only `OPENCODE_PROVIDER_KEY` → opencode only. Both → both jobs (additive coexistence). **No `BKIT_LINEAR_API_KEY`** — `bkit-cloud.yml` GitHub-tracker only for both jobs. Workflow grants `id-token: write` per-job for claude only (opencode no OIDC).
|
|
440
431
|
|
|
441
|
-
|
|
432
|
+
Slash command body already in checked-out repo (mirrored to `.claude/commands/bkit-auto.md` and `.opencode/commands/bkit-auto.md` at dev time via `bkit install`). Repo git/gh ops use auto-provided `github.token` scoped by workflow `permissions:` block.
|
|
442
433
|
|
|
443
434
|
## Branch-aware routing
|
|
444
435
|
|
|
@@ -197,6 +197,8 @@ Output: PR to `dev`. Heaviest phase — most steps verify rather than produce. C
|
|
|
197
197
|
|
|
198
198
|
Output: remediated commit on feature branch. Two modes — normal (diagnose → remediate localisable failure) and soak (one accumulating-context instrument-or-fix loop for non-localisable / runtime-only failures). Normal escalates to soak when diagnose can't localise, or normal loop exhausts three strategies; observation logging (`[DEBUG-OBSERVE]`) inside soak, stripped before fix ships.
|
|
199
199
|
|
|
200
|
+
**Context fetch.** Per failed attempt, `/bkit-debug` runs each `context-fetch` bash block below `<!-- bkit:end -->` in `.agents/context.md` — failing CI logs, the diff since the last green run, end-to-end reports, runtime errors (Sentry, Vercel, Supabase, Stripe and more) and web search (Tavily) — writing one artifact per context and narrating `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` before fetching. Fail-soft and block-driven: bkit hardcodes no CI host, workflow filename or test framework, and a context with no block is never read as a clean result.
|
|
201
|
+
|
|
200
202
|
**Normal mode**
|
|
201
203
|
|
|
202
204
|
<!-- prettier-ignore -->
|
|
@@ -287,7 +289,7 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
|
|
|
287
289
|
| Exception Handling & Recovery | Already does | Universal failure path, bounded retries (3), 3600s timeouts, runaway-turn caps, human handover. |
|
|
288
290
|
| Human-in-the-Loop | Already does | Mandatory hard stops after design / plan / ship; "recommend, do not decide." |
|
|
289
291
|
| Resource-Aware Optimization | Already does | Effort-to-model tiering with explicit per-agent pins. |
|
|
290
|
-
| Context Engineering | Already does | Phase doc-matrix, lazy-load, output caps, stubbed-output pattern. |
|
|
292
|
+
| Context Engineering | Already does | Phase doc-matrix, lazy-load, output caps, stubbed-output pattern; consumer `context-fetch` blocks add CI, diff, e2e, runtime and web signal in debug. |
|
|
291
293
|
| Memory Management | Partial | Filesystem and grep episodic memory (`status.jsonl`, knowledge / decisions). No vector retrieval, by scale choice. |
|
|
292
294
|
| Learning & Adaptation | Partial | `friction.jsonl` drives human-reviewed prompt edits; entries carry confidence, scope, and last-confirmed fields. No auto prompt-tuning — deliberate, to keep humans in the loop. |
|
|
293
295
|
| Goal Setting & Monitoring | Partial | Issue = goal, phase labels = state, verdicts = criteria. No measurable per-task Definition of Done yet. |
|
|
@@ -305,6 +307,7 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
|
|
|
305
307
|
- **Cross-model diversity where breadth beats depth.** Design brainstorm, design review, plan scope-check groups pair Opus + Sonnet (Grok + Composer on Cursor) → two reasoners review same work. Depth-sensitive lenses (plan review, build challenge) stay on top tier.
|
|
306
308
|
- **Resume-from-state as single source of truth.** `status.jsonl` makes every run inspectable and restartable; book treats this only obliquely under memory.
|
|
307
309
|
- **Human-in-the-loop as non-negotiable.** Hard stops after design / plan / ship; book treats HITL as one option.
|
|
310
|
+
- **Fail-soft external context in debug.** Provider-agnostic `context-fetch` blocks (CI logs, diff, e2e, runtime, web) feed `/bkit-debug`; each self-skips to a narrated `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` state, so a context with no block is never read as a clean result.
|
|
308
311
|
- **Explicit per-agent model pins.** Immune to session-default drift.
|
|
309
312
|
- **Provider- and host-portable execution.** Per-agent pins → `bkit install --opencode=<provider>` adds opencode host alongside Claude/Cursor — harness unchanged; inference backend moves. Same five-phase gated parallel pipeline on four providers (OpenRouter, Ollama, opencode Zen + Go gateways). Curated per-agent pins; models mirror Claude tier by default, CoT reasoners swapped for convergent-reasoning agents (debug/risk). See `.bkit/providers.md` § Hosts + Providers.
|
|
310
313
|
- **Cross-host/provider continuity.** State in `status.jsonl`, plan/design docs under `docs/plans/`, tracker issue — not vendor session. Every host renders from same `.bkit/` source → phase or resumed run moves across IDE/provider mid-feature with identical gates, hooks, per-agent pins: exhaust Claude weekly limit or free-tier quota → continue on another host, no re-setup. Single-vendor frameworks tie run to starting session.
|