@cbartens/bkit 5.3.0 → 5.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +20 -7
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/rules.md +14 -9
- package/.bkit/core/.bkit/README.md +19 -6
- package/.bkit/core/.bkit/cloud.md +77 -46
- package/.bkit/core/.bkit/comparison.md +3 -3
- package/.bkit/core/.bkit/install.md +21 -18
- package/.bkit/core/.bkit/lite.md +6 -6
- package/.bkit/core/.bkit/pipeline.md +6 -3
- package/.bkit/core/.bkit/prompts.md +14 -10
- package/.bkit/core/.bkit/providers.md +7 -7
- package/.bkit/core/.bkit/templates.md +46 -10
- package/.bkit/core/.bkit/trackers.md +92 -38
- package/.bkit/core/.bkit/workflows.md +140 -116
- package/.bkit/core/AGENTS.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +25 -8
- package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
- package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/engine/checks/after/auth.ts +88 -45
- package/.bkit/core/engine/checks/after/github.ts +18 -5
- package/.bkit/core/engine/checks/after/index.ts +1 -1
- package/.bkit/core/engine/checks/after/tools.ts +1 -1
- package/.bkit/core/engine/checks/before/env.ts +28 -18
- package/.bkit/core/engine/checks/before/mcp.ts +4 -2
- package/.bkit/core/engine/checks/status-holes.ts +0 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
- package/.bkit/core/engine/checks/tips/index.ts +49 -27
- package/.bkit/core/engine/cli.ts +27 -18
- package/.bkit/core/engine/commands/ci/ci.ts +107 -0
- package/.bkit/core/engine/commands/comply.ts +25 -16
- package/.bkit/core/engine/commands/install/install.ts +11 -4
- package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +10 -8
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +7 -3
- package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
- package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
- package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
- package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
- package/.bkit/core/engine/commands/workflow/status.ts +33 -11
- package/.bkit/core/engine/commands/workflow/steps.ts +26 -17
- package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
- package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
- package/.bkit/core/engine/install/manifest.ts +31 -10
- package/.bkit/core/engine/install/modules/cloud.ts +3 -1
- package/.bkit/core/engine/install/modules/core.ts +97 -4
- package/.bkit/core/engine/install/modules/opencode.ts +5 -0
- package/.bkit/core/engine/install/placeholders.ts +13 -17
- package/.bkit/core/engine/install/write.ts +37 -1
- package/.bkit/core/engine/render/trackers.ts +35 -23
- package/.bkit/core/engine/shared/egress.ts +6 -0
- package/.bkit/core/engine/shared/settings.ts +96 -1
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/hooks/guardrails-tiers.js +1 -1
- package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-design-generate.md +2 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
- package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
- package/.bkit/core/workflows/bkit-auto.md +19 -6
- package/.bkit/core/workflows/bkit-build.md +64 -22
- package/.bkit/core/workflows/bkit-debug.md +72 -28
- package/.bkit/core/workflows/bkit-design.md +101 -37
- package/.bkit/core/workflows/bkit-plan.md +82 -31
- package/.bkit/core/workflows/bkit-ship.md +127 -108
- package/.bkit/shared/.bkit/.env.example +8 -0
- package/.bkit/shared/.claude/bkit-cloud.md +12 -12
- package/.bkit/shared/.claude/settings.json +4 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
- package/.bkit/shared/.cursor/mcp.json +11 -4
- package/.bkit/shared/.mcp.json +11 -4
- package/.bkit/shared/.opencode/opencode.json +2 -0
- package/.bkit/shared/docs/deployments.md +44 -29
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/testing.md +3 -3
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
- package/.bkit/templates/.github/renovate.json5 +1 -1
- package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
- package/.bkit/templates/.husky/pre-commit +10 -4
- package/.bkit/templates/.husky/pre-push +69 -12
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
- package/CHANGELOG.md +85 -1
- package/README.md +102 -100
- package/dist/checks/after/auth.js +81 -45
- package/dist/checks/after/github.js +17 -5
- package/dist/checks/after/index.js +1 -1
- package/dist/checks/after/tools.js +1 -1
- package/dist/checks/before/env.js +24 -17
- package/dist/checks/before/mcp.js +4 -2
- package/dist/checks/status-holes.js +0 -1
- package/dist/checks/tips/catalogue.js +28 -2
- package/dist/checks/tips/index.js +44 -28
- package/dist/cli.js +27 -19
- package/dist/commands/ci/ci.js +100 -0
- package/dist/commands/comply.js +20 -13
- package/dist/commands/install/install.js +10 -4
- package/dist/commands/install/uninstall.js +42 -0
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +9 -6
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +300 -243
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/fids.js +22 -15
- package/dist/commands/workflow/issues.js +90 -41
- package/dist/commands/workflow/ledgers.js +26 -11
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +8 -3
- package/dist/commands/workflow/repo.js +5 -0
- package/dist/commands/workflow/roadmap.js +52 -57
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +20 -13
- package/dist/commands/workflow/workflows.js +397 -251
- package/dist/commands/workflow/workstreams.js +3 -2
- package/dist/commands/workflow/worktrees.js +11 -1
- package/dist/install/manifest.js +30 -10
- package/dist/install/modules/cloud.js +3 -1
- package/dist/install/modules/core.js +95 -5
- package/dist/install/modules/opencode.js +6 -0
- package/dist/install/placeholders.js +13 -19
- package/dist/install/write.js +26 -2
- package/dist/render/trackers.js +34 -20
- package/dist/shared/egress.js +6 -0
- package/dist/shared/settings.js +44 -0
- package/dist/shared/timeouts.js +8 -7
- package/package.json +11 -2
package/.bkit/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# bkit — Agent Workflow System
|
|
2
2
|
|
|
3
|
-
<!-- bkit:managed v5.
|
|
3
|
+
<!-- bkit:managed v5.5.0 — 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
|
|
|
@@ -45,7 +45,7 @@ Throughout: workflows hold `.lock`, write `status.jsonl` (resume SoT), own track
|
|
|
45
45
|
| Issue | Start with |
|
|
46
46
|
| --- | --- |
|
|
47
47
|
| Idea — how it should work still open | `/bkit-design` |
|
|
48
|
-
| Change — what to build and "done" known | `/bkit-plan`; or `/bkit-build` / `lite
|
|
48
|
+
| Change — what to build and "done" known | `/bkit-plan`; or `/bkit-build` / `build:lite` with no plan (issue = plan; `/bkit-build` checks each `Test first` red, `build:lite` does not) |
|
|
49
49
|
| Bug — a test or CI run already fails | `/bkit-debug`, on the branch the fix lands on |
|
|
50
50
|
| Bug — nothing fails yet | `/bkit-debug [repro]` (writes a failing test first, then fixes) |
|
|
51
51
|
|
|
@@ -64,6 +64,8 @@ No `/bkit-audit` command and no phase label. More than 30 procedures ship as `do
|
|
|
64
64
|
| --- | --- |
|
|
65
65
|
| Report | `docs/audits/{YYYYMM}/{slug}.md`. `{slug}` = template basename without `bkit-audit-`. Same slug already in that month → `{slug}-{TIMESTAMP}.md` (`date -u +%Y%m%dT%H%M%SZ`). Never overwrite. |
|
|
66
66
|
| Writes | The report (template through `bkit:end`) and that template's `Project Instructions` below `bkit:end`. Product code, config, and other docs stay untouched. Fixing findings starts at `/bkit-plan`. |
|
|
67
|
+
| Issue comment | Invocation names an issue (`#123`, `ABC-123`) and a tracker is wired → the final summary lands on it as one comment, stopped runs included. Never files, edits, or relabels issues. |
|
|
68
|
+
| Audit parent | One standing issue per template; every run of that template reports to it and its filed issues become its sub-issues (`.bkit/trackers.md` § Issue shapes). No issue named + tracker wired → the agent searches for it and posts the summary there; none open → the final message suggests one, ready to file, plus the saved summary to post as its first comment. |
|
|
67
69
|
| Plan input | `/bkit-plan` takes a design doc, one or more reports, or both. The issue names a report with an `**Audit reports:**` line; the session prompt or issue names which findings to plan (for example only `CRITICAL` and `HIGH`). The rest of each report stays context. |
|
|
68
70
|
|
|
69
71
|
Each template's `Purpose` is its scope. Main ones: security, privacy, accessibility, architecture, performance, reliability, testing, database, LLM, cost. Full catalogue: `.bkit/prompts.md` § Audit (Ad-hoc).
|
|
@@ -124,6 +126,16 @@ BKIT_ANTHROPIC_API_KEY=""
|
|
|
124
126
|
BKIT_GH_TOKEN=""
|
|
125
127
|
```
|
|
126
128
|
|
|
129
|
+
**Jira tracker (`bkit install --tracker=jira`, local runs only):**
|
|
130
|
+
|
|
131
|
+
```env
|
|
132
|
+
# ==========================================
|
|
133
|
+
# BKIT: JIRA GITHUB INTEGRATION
|
|
134
|
+
# ==========================================
|
|
135
|
+
BKIT_JIRA_API_TOKEN=""
|
|
136
|
+
BKIT_GH_TOKEN=""
|
|
137
|
+
```
|
|
138
|
+
|
|
127
139
|
<!-- prettier-ignore -->
|
|
128
140
|
| Variable | Tracker | Where read | Purpose |
|
|
129
141
|
| --- | --- | --- | --- |
|
|
@@ -133,9 +145,10 @@ BKIT_GH_TOKEN=""
|
|
|
133
145
|
| `BKIT_ANTHROPIC_API_KEY` | all | Claude Code (headless / CI) | Required when Claude invoked outside interactive session (cloud automation, CI). |
|
|
134
146
|
| `BKIT_CURSOR_API_KEY` | all | Cursor Cloud Agent dashboard / programmatic invocation | Required for non-interactive Cursor sessions. |
|
|
135
147
|
| `BKIT_LINEAR_API_KEY` | linear | Preflight hooks (`.{claude,cursor}/hooks/bkit-preflight.sh`); workflow Linear MCP via OAuth fallback | Query issue state + labels for `Auto` gate; fail-fast if absent. |
|
|
148
|
+
| `BKIT_JIRA_API_TOKEN` | jira | Jira MCP server (`Authorization: Bearer`) | Atlassian MCP V2 scoped API token; site admin enables API-token sign-in for the Rovo MCP server first. Setup: `.bkit/trackers.md` § jira. |
|
|
136
149
|
| `LINEAR_WEBHOOK_SECRET` | linear | Linear → Cursor integration backend | Verifies webhook signatures on `@cursor` mentions. Set in Linear ↔ Cursor integration config. |
|
|
137
150
|
|
|
138
|
-
`
|
|
151
|
+
`GITHUB_ISSUE_ID` (GitHub) and `LINEAR_ISSUE_ID` (Linear) set automatically by workflow context — do not set manually.
|
|
139
152
|
|
|
140
153
|
### Tracker workspace setup
|
|
141
154
|
|
|
@@ -268,7 +281,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
|
268
281
|
| `.bkit/.env.example` | claude | `.bkit/shared/.bkit/.env.example` | Tier 1 (fully managed). Real values go in `.bkit/.env`. |
|
|
269
282
|
| `.cursor/commands/bkit-*.md` | cursor | `.bkit/core/workflows/` (T1+T2 transforms) | Host pass — always overwrite |
|
|
270
283
|
| `.cursor/agents/bkit-*.md` | cursor | `.bkit/core/prompts/` (T3 transforms) | Host pass — always overwrite |
|
|
271
|
-
| `package.json#scripts.bkit:gate:format` / `bkit:gate:static` / `bkit:gate:static-unit` / `bkit:gate:install-static-unit-build` | core | hardcoded defaults | Seeded (add-if-missing; install and upgrade). What hooks, workflows and prompts run; the name states which tiers. The tool scripts the defaults chain (`typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta`) and their devDeps are templates: `.bkit/templates.md`. |
|
|
284
|
+
| `package.json#scripts.bkit:gate:format` / `bkit:gate:min` / `bkit:gate:static` / `bkit:gate:static-unit` / `bkit:gate:install-static-unit-build` | core | hardcoded defaults | Seeded (add-if-missing; install and upgrade). What hooks, workflows and prompts run; the name states which tiers. The tool scripts the defaults chain (`typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta`) and their devDeps are templates: `.bkit/templates.md`. |
|
|
272
285
|
| `package.json#scripts.bkit:deps:outdated` / `bkit:deps:audit` | core | hardcoded defaults | Seeded (add-if-missing; install and upgrade). Read-only dependency inspection the remediate / diagnose agents call. |
|
|
273
286
|
| `.cursor/hooks.json` | cursor | `.bkit/shared/.cursor/hooks.json` | Tier 1 (fully managed) |
|
|
274
287
|
| `.cursor/mcp.json` | cursor | `.bkit/shared/.cursor/mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only |
|
|
@@ -289,7 +302,7 @@ The cloud workflow and the Cursor Background Agent files are templates the `--au
|
|
|
289
302
|
|
|
290
303
|
### Optional post-install decisions (tracker + cloud agents)
|
|
291
304
|
|
|
292
|
-
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.
|
|
305
|
+
Two capabilities **opt-in**, excluded from default install: **issue tracker** (`--tracker=github|linear|jira`), **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.
|
|
293
306
|
|
|
294
307
|
**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.
|
|
295
308
|
|
|
@@ -347,7 +360,7 @@ Slash commands at repo root:
|
|
|
347
360
|
|
|
348
361
|
Claude reads issue, comments, plan files via tracker MCP.
|
|
349
362
|
|
|
350
|
-
**Requirements:** `BKIT_GH_TOKEN`, active Claude Code session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` when `bkit.issueTracker = "linear"`. Session model = orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column) — set via `/model` before invoking; not duplicated here.
|
|
363
|
+
**Requirements:** `BKIT_GH_TOKEN`, active Claude Code session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` when `bkit.issueTracker = "linear"`; `BKIT_JIRA_API_TOKEN` when `"jira"`. Session model = orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column) — set via `/model` before invoking; not duplicated here.
|
|
351
364
|
|
|
352
365
|
### From Cursor (interactive — local)
|
|
353
366
|
|
|
@@ -359,7 +372,7 @@ Cursor 2.4+ honours `.cursor/commands/bkit-*.md` and `.cursor/agents/bkit-*.md`:
|
|
|
359
372
|
|
|
360
373
|
Orchestrator reads `.cursor/commands/` workflow. Subagents via `Task`, `model:` from frontmatter (no host override).
|
|
361
374
|
|
|
362
|
-
**Requirements:** `BKIT_GH_TOKEN` (GitHub, default) or `BKIT_LINEAR_API_KEY` (Linear). Cursor account in good standing.
|
|
375
|
+
**Requirements:** `BKIT_GH_TOKEN` (GitHub, default) or `BKIT_LINEAR_API_KEY` (Linear) or `BKIT_JIRA_API_TOKEN` (Jira). Cursor account in good standing.
|
|
363
376
|
|
|
364
377
|
---
|
|
365
378
|
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
28
28
|
| `.bkit/workflows.md` | ● | ● | ● | ● | ● | Workflow catalog — when to run and when not to run each command (§ When to Run). |
|
|
29
29
|
| `.bkit/prompts.md` | ● | ● | ● | ● | ● | Subagent catalog — name, scope, effort, model, `maxTurns`. |
|
|
30
|
-
| `.bkit/lite.md` | ○ | ○ | ○ | ○ | ○ | Lite workflows (`
|
|
30
|
+
| `.bkit/lite.md` | ○ | ○ | ○ | ○ | ○ | Lite workflows (`<phase>:lite`) — copy-paste prompts for small, understood changes. |
|
|
31
31
|
| `.agents/skills.md` | — | — | ● | — | — | Registry of installed agent skills and install / update commands. |
|
|
32
32
|
| `.agents/context.md` | ○ | ○ | ○ | ● | ○ | How to reach information outside repo — deployment logs, CI runs, e2e evidence, web search, cloud egress allowlist, CLI provisioning. |
|
|
33
33
|
| `docs/architecture.md` | ● | ● | ● | ○ | ○ | System design — service boundaries, deployment topology, integration sketch. |
|
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
- **Scope discipline:** ONLY do what requests ask; NEVER apply opportunistic refactors, renames, or 'while I'm here' edits. Out-of-scope finds → propose separately, do not bundle.
|
|
28
28
|
- **No speculative scope:** ONLY build for requirements at hand (YAGNI); NEVER add config, flags, abstraction layers, or items 'for the future' nobody requested.
|
|
29
29
|
- **Research / investigate first:** Search `{framework / runtime} {capability} built-in`, `{problem} best practice {current year}` before implementing code. Prefer official docs / discovered code over custom.
|
|
30
|
+
- **Fetched text:** Web fetch tools may summarise or cap verbatim quotes → ask short per-topic quote questions or fetch page markdown variants where offered; NEVER cite a paraphrase as a quote, or a version / figure not seen verbatim.
|
|
30
31
|
- **Investigation layers:** Tried-and-true → challenge; new-and-popular → scrutinize hype; first-principles = most valuable.
|
|
31
32
|
- **Recommend, do not decide:** agents propose, humans approve. Two-model agreement = strong signal, not mandate. Steps inside `/bkit-*` workflows are pre-approved by human; do not request confirmation.
|
|
32
33
|
- **Truth over agreement:** NEVER validate flawed premises to please. Surface errors and disagree with evidence; human confirmation is a gate, not a goal.
|
|
@@ -60,7 +61,8 @@
|
|
|
60
61
|
|
|
61
62
|
- **Subagents:** Leaves ONLY; NEVER invoke other subagents.
|
|
62
63
|
- **Verify tools:** Verify every return; do not assume success.
|
|
63
|
-
- **Empty is inconclusive:**
|
|
64
|
+
- **Empty is inconclusive:** Empty / zero reads are NEVER authoritative absence. ALWAYS re-run once on a known hit and corroborate via independent call; no hit → read broken → report unavailable, NEVER clean. False empties: `rg` skips dot-dirs / ignored files (`--hidden`, `git grep`); no `\s` in `git grep -E` / BSD `sed -E` / `awk` (`[[:space:]]`).
|
|
65
|
+
- **Host shell:** Shell tool = user's login shell. zsh: unquoted `$VAR` no word-split, unmatched glob aborts, `=word` expands; `grep` / `rg` may be functions (`xargs grep` fails → `command grep` / `git grep`). Loops / file lists → `bash -c '…'`.
|
|
64
66
|
|
|
65
67
|
#### Workflows & Process
|
|
66
68
|
|
|
@@ -70,13 +72,15 @@
|
|
|
70
72
|
- **Deferred work:** NEVER silently drop deferred work, ALWAYS append rows to `docs/deferrals.jsonl` in `.bkit/jsonl.md` format; check existing entries first. All rows MUST carry `reason` from closed enum; no valid justification = not valid deferral → finish work.
|
|
71
73
|
- **Discovered bugs:** NEVER silently drop discovered bugs, ALWAYS append rows to `docs/failures.jsonl` in `.bkit/jsonl.md` format; check existing entries first.
|
|
72
74
|
- **Flaky tests:** Any tests passing ONLY on retry / failing intermittently, ALWAYS append rows to `docs/failures.jsonl` in `.bkit/jsonl.md` format; check existing entries first.
|
|
73
|
-
- **Tracker MCPs:** Issue reads / updates via configured MCP ONLY; use CLI / HTTP shell-outs as backup / fallback ONLY.
|
|
74
|
-
- **Tracker comments:** NEVER mention @claude or @cursor in comment body.
|
|
75
|
-
- **Tracker context cut:** Use `###### bkit:ignore-earlier` on its own line in issue bodies or comments to drop all earlier content from workflow inputs; ALWAYS requires human confirmation; NEVER include unprompted in any output.
|
|
76
75
|
- **Tracker issue creation:** NEVER create issues yourself; ONLY suggest; create ONLY after explicit human confirmation; body per `.bkit/trackers.md` § Issue shapes.
|
|
77
|
-
- **Tracker issue settings:** Title MAX 70 characters or two lines on mobile; ALWAYS set labels, project, priority, size, and
|
|
76
|
+
- **Tracker issue settings:** Title MAX 70 characters or two lines on mobile; ALWAYS set labels, project, project status, priority, size, milestone, parent, and every open blocking issue as blocked-by; priority and size per `docs/templates/bkit-audit-issues.md` § Ranking Rules and § Size Scale, NEVER by label alone; blocked-by in machine-read form per `.bkit/trackers.md` § Issue shapes, NEVER prose only; check similar issues if unclear.
|
|
77
|
+
- **Tracker next labels:** Issue without workflow label → ALWAYS exactly one `next:design` / `next:plan` / `next:build` / `next:debug` / `next:ship`; append `:lite` for lite workflow (`next:build:lite`) per `.bkit/lite.md` § When to use. NEVER alongside workflow label.
|
|
78
|
+
- **Tracker workflow labels:** Add `bkit:design` / `bkit:plan` / `bkit:build` / `bkit:debug` / `bkit:ship` ONLY when issue starts that workflow (full or lite); mutually exclusive — next workflow start drops previous; `/bkit-ship` close swaps `bkit:ship` → `bkit:merged`. NEVER add by hand to signal intent; use `next:*`.
|
|
79
|
+
- **Tracker failure label:** Any workflow Failure Path → add `bkit:failed` alongside workflow label.
|
|
78
80
|
- **Tracker issue mentions:** NEVER mention issue IDs on their own; ALWAYS mention issue IDs together with their title and URL.
|
|
79
|
-
- **Tracker work comments:** ANY
|
|
81
|
+
- **Tracker work comments:** ANY issue worked on outside `/bkit-*` workflows → ALWAYS post ONE comment per related issue at end of every major turn (files changed / commit / PR / finding / blocked stop) with work done, outcome, links; SKIP turns with no work (Q&A, clarifying questions). NEVER paste diffs / restate code. NEVER mention @claude or @cursor in comment body.
|
|
82
|
+
- **Tracker context cut:** Use `###### bkit:ignore-earlier` on its own line in issue bodies or comments to drop all earlier content from workflow inputs; ALWAYS requires human confirmation; NEVER include unprompted in any output.
|
|
83
|
+
- **Tracker MCPs:** Issue reads / updates via configured MCP ONLY; use CLI / HTTP shell-outs as backup / fallback ONLY.
|
|
80
84
|
|
|
81
85
|
#### Git, CI & Merges
|
|
82
86
|
|
|
@@ -88,7 +92,7 @@
|
|
|
88
92
|
- **Code commits:** Ensure code commit is HEAD so CI runs.
|
|
89
93
|
- **Secrets:** NEVER stage `.env*`, credentials, tokens, API keys. `git status` review before every commit.
|
|
90
94
|
- **Pushes:** ALWAYS ask before every push; one approval covers one push, NEVER later ones. Before asking, show `git log origin/{branch}..HEAD`. Exception: `/bkit-*` workflow steps mandating push (see Orchestrator Rules).
|
|
91
|
-
- **Destructive git PROHIBITED:** NEVER run any of these: `git reset` (any flavour), `git checkout -- .`, `git restore .`, `git clean` (any flavour), `git rebase -i`, `git stash drop`, `git push --force` (any flavour). In-progress rebase resolution (`git checkout --theirs|--ours {conflicted}`, `git rebase --continue` / `--abort`) is not covered.
|
|
95
|
+
- **Destructive git PROHIBITED:** NEVER run any of these: `git reset` (any flavour), `git checkout -- .`, `git restore .`, `git clean` (any flavour), `git rebase -i`, `git stash drop`, `git stash clear`, `git push --force` (any flavour). In-progress rebase resolution (`git checkout --theirs|--ours {conflicted}`, `git rebase --continue` / `--abort`) is not covered.
|
|
92
96
|
- **Other parallel agents:** Unexpected changes in `git status` belong to other agent, not you; NEVER revert, reformat, stash, or "clean up" them; NEVER `git stash`, switch branches, or `git checkout` / `git restore` files you did not touch.
|
|
93
97
|
- **Pre-push:** `--no-verify` PROHIBITED. Fix failures locally. If unfixable → document and STOP.
|
|
94
98
|
- **Force push:** PROHIBITED on shared branches (`dev` / `main`). Personal branches ONLY with `--force-with-lease` — the sole exception to `Destructive git PROHIBITED`.
|
|
@@ -97,6 +101,7 @@
|
|
|
97
101
|
- **Merge bodies:** All squash-merges landing code MUST pass explicit bodies; do not accept defaults; do not allow default concatenating of commit subjects silently inheriting `[skip ci]` markers and suppressing CI.
|
|
98
102
|
- **Production merge:** Any merge into default production branch (`main`) requires PR with explicit human confirmation.
|
|
99
103
|
- **Polls / loops:** NEVER use blocking foreground `sleep` to poll; runtimes may not honour. ALWAYS use bounded, `timeout` wrapped bash poll (bash) or agent-side per-turn yield loop (control flow). Legitimate retry / backoff sleeps are exempt.
|
|
104
|
+
- **Shallow history:** Before reading git history (log, blame, bisect, churn, history scans) → `git rev-parse --is-shallow-repository`; `true` → state boundary commit, older history unread; NEVER report partial history as complete.
|
|
100
105
|
- **MCP fallback:** All substitutions of unavailable `gh` commands with MCP tools MUST be bounded (max 1 transition per run), recorded (`transport-fallback` rows), and success-asserted via independent re-reads. NEVER improvise unrecorded substitutions.
|
|
101
106
|
|
|
102
107
|
#### Testing & Debugging
|
|
@@ -111,7 +116,7 @@
|
|
|
111
116
|
- **Provider data:** Logs, errors, database → prefer enabled `.agents/context.md` context-fetch blocks or provider's CLI over MCP.
|
|
112
117
|
- **Local tests first:** ALWAYS exhaust local test suite and targeted repro before remote CI. Deployed-boundary / `@live` that cannot reproduce locally → review existing evidence first.
|
|
113
118
|
- **Existing evidence first:** ALWAYS search / read existing reports / logs / artifacts before requesting new remote CI runs; request new runs ONLY when existing evidence insufficient, stale, or absent.
|
|
114
|
-
- **Local pre-push:** `pnpm bkit:gate:static-unit`, then `bkit check`. Gate scripts MUST not run tests needing a deployed boundary
|
|
119
|
+
- **Local pre-push:** `pnpm bkit:gate:static-unit-integration` when declared, else `pnpm bkit:gate:static-unit`, then `bkit check`. Gate scripts MUST not run tests needing a deployed boundary or remote service; local services (a database in Docker) are fine.
|
|
115
120
|
- **CI on PR to `dev` / `main`:** Static, unit, integration (incl. service / DB-backed), E2E, ALWAYS-on migration lane in repos with migrations (replay when planned) — parallel lanes + `bkit-tests-check` capstone. E2E `needs:` migration when that lane owns remote migration apply. no `@live` tests.
|
|
116
121
|
- **CI on push to `dev` / `main`:** PR lanes plus remote migration apply inside migration lane + `@live` canary (both wait on migration ≠ failure).
|
|
117
122
|
- **Name the suites you ran:** NEVER report "all tests green" or a bare task count as evidence. State the tiers — `unit`, `integration`, `e2e`, `@live`.
|
|
@@ -120,7 +125,7 @@
|
|
|
120
125
|
- **Debug on demand:** Re-runs failing E2E / `@live` tier tests against deployed boundary. NEVER purely local runs.
|
|
121
126
|
- **Slop gate:** When the gate runs `slop:delta`: ONLY fix net-new findings, NEVER the baseline. NEVER delete /move / merge files or rewire callers to clear structural findings.
|
|
122
127
|
- **Check secrets first:** ALWAYS probe direnv for presence first `direnv exec . sh -c '[ -n "${VAR}" ] && echo set || echo unset'` before asking for secrets / tokens / env vars. ONLY ask when `unset` (`Secrets in output`: report names, NEVER values).
|
|
123
|
-
- **New worktree:** `git worktree add` does NOT carry direnv trust → run `direnv allow` BEFORE first test / verify / build command.
|
|
128
|
+
- **New worktree:** `git worktree add` does NOT carry direnv trust → run `direnv allow` BEFORE first test / verify / build command. Hand-made worktrees also lack gitignored inputs (env files, installed dependencies, build outputs, tool assets) → bring in BEFORE first build: copy `package.json` `bkit.worktreeCopy` entries, link read-only inputs, copy or reinstall written ones; red from missing input = setup, not change under test. Remove links before `git worktree remove`; NEVER `--force` a worktree holding real work.
|
|
124
129
|
|
|
125
130
|
#### Security & Data
|
|
126
131
|
|
|
@@ -45,7 +45,7 @@ Throughout: workflows hold `.lock`, write `status.jsonl` (resume SoT), own track
|
|
|
45
45
|
| Issue | Start with |
|
|
46
46
|
| --- | --- |
|
|
47
47
|
| Idea — how it should work still open | `/bkit-design` |
|
|
48
|
-
| Change — what to build and "done" known | `/bkit-plan`; or `/bkit-build` / `lite
|
|
48
|
+
| Change — what to build and "done" known | `/bkit-plan`; or `/bkit-build` / `build:lite` with no plan (issue = plan; `/bkit-build` checks each `Test first` red, `build:lite` does not) |
|
|
49
49
|
| Bug — a test or CI run already fails | `/bkit-debug`, on the branch the fix lands on |
|
|
50
50
|
| Bug — nothing fails yet | `/bkit-debug [repro]` (writes a failing test first, then fixes) |
|
|
51
51
|
|
|
@@ -64,6 +64,8 @@ No `/bkit-audit` command and no phase label. More than 30 procedures ship as `do
|
|
|
64
64
|
| --- | --- |
|
|
65
65
|
| Report | `docs/audits/{YYYYMM}/{slug}.md`. `{slug}` = template basename without `bkit-audit-`. Same slug already in that month → `{slug}-{TIMESTAMP}.md` (`date -u +%Y%m%dT%H%M%SZ`). Never overwrite. |
|
|
66
66
|
| Writes | The report (template through `bkit:end`) and that template's `Project Instructions` below `bkit:end`. Product code, config, and other docs stay untouched. Fixing findings starts at `/bkit-plan`. |
|
|
67
|
+
| Issue comment | Invocation names an issue (`#123`, `ABC-123`) and a tracker is wired → the final summary lands on it as one comment, stopped runs included. Never files, edits, or relabels issues. |
|
|
68
|
+
| Audit parent | One standing issue per template; every run of that template reports to it and its filed issues become its sub-issues (`.bkit/trackers.md` § Issue shapes). No issue named + tracker wired → the agent searches for it and posts the summary there; none open → the final message suggests one, ready to file, plus the saved summary to post as its first comment. |
|
|
67
69
|
| Plan input | `/bkit-plan` takes a design doc, one or more reports, or both. The issue names a report with an `**Audit reports:**` line; the session prompt or issue names which findings to plan (for example only `CRITICAL` and `HIGH`). The rest of each report stays context. |
|
|
68
70
|
|
|
69
71
|
Each template's `Purpose` is its scope. Main ones: security, privacy, accessibility, architecture, performance, reliability, testing, database, LLM, cost. Full catalogue: `.bkit/prompts.md` § Audit (Ad-hoc).
|
|
@@ -124,6 +126,16 @@ BKIT_ANTHROPIC_API_KEY=""
|
|
|
124
126
|
BKIT_GH_TOKEN=""
|
|
125
127
|
```
|
|
126
128
|
|
|
129
|
+
**Jira tracker (`bkit install --tracker=jira`, local runs only):**
|
|
130
|
+
|
|
131
|
+
```env
|
|
132
|
+
# ==========================================
|
|
133
|
+
# BKIT: JIRA GITHUB INTEGRATION
|
|
134
|
+
# ==========================================
|
|
135
|
+
BKIT_JIRA_API_TOKEN=""
|
|
136
|
+
BKIT_GH_TOKEN=""
|
|
137
|
+
```
|
|
138
|
+
|
|
127
139
|
<!-- prettier-ignore -->
|
|
128
140
|
| Variable | Tracker | Where read | Purpose |
|
|
129
141
|
| --- | --- | --- | --- |
|
|
@@ -133,9 +145,10 @@ BKIT_GH_TOKEN=""
|
|
|
133
145
|
| `BKIT_ANTHROPIC_API_KEY` | all | Claude Code (headless / CI) | Required when Claude invoked outside interactive session (cloud automation, CI). |
|
|
134
146
|
| `BKIT_CURSOR_API_KEY` | all | Cursor Cloud Agent dashboard / programmatic invocation | Required for non-interactive Cursor sessions. |
|
|
135
147
|
| `BKIT_LINEAR_API_KEY` | linear | Preflight hooks (`.{claude,cursor}/hooks/bkit-preflight.sh`); workflow Linear MCP via OAuth fallback | Query issue state + labels for `Auto` gate; fail-fast if absent. |
|
|
148
|
+
| `BKIT_JIRA_API_TOKEN` | jira | Jira MCP server (`Authorization: Bearer`) | Atlassian MCP V2 scoped API token; site admin enables API-token sign-in for the Rovo MCP server first. Setup: `.bkit/trackers.md` § jira. |
|
|
136
149
|
| `LINEAR_WEBHOOK_SECRET` | linear | Linear → Cursor integration backend | Verifies webhook signatures on `@cursor` mentions. Set in Linear ↔ Cursor integration config. |
|
|
137
150
|
|
|
138
|
-
`
|
|
151
|
+
`GITHUB_ISSUE_ID` (GitHub) and `LINEAR_ISSUE_ID` (Linear) set automatically by workflow context — do not set manually.
|
|
139
152
|
|
|
140
153
|
### Tracker workspace setup
|
|
141
154
|
|
|
@@ -268,7 +281,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
|
268
281
|
| `.bkit/.env.example` | claude | `.bkit/shared/.bkit/.env.example` | Tier 1 (fully managed). Real values go in `.bkit/.env`. |
|
|
269
282
|
| `.cursor/commands/bkit-*.md` | cursor | `.bkit/core/workflows/` (T1+T2 transforms) | Host pass — always overwrite |
|
|
270
283
|
| `.cursor/agents/bkit-*.md` | cursor | `.bkit/core/prompts/` (T3 transforms) | Host pass — always overwrite |
|
|
271
|
-
| `package.json#scripts.bkit:gate:format` / `bkit:gate:static` / `bkit:gate:static-unit` / `bkit:gate:install-static-unit-build` | core | hardcoded defaults | Seeded (add-if-missing; install and upgrade). What hooks, workflows and prompts run; the name states which tiers. The tool scripts the defaults chain (`typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta`) and their devDeps are templates: `.bkit/templates.md`. |
|
|
284
|
+
| `package.json#scripts.bkit:gate:format` / `bkit:gate:min` / `bkit:gate:static` / `bkit:gate:static-unit` / `bkit:gate:install-static-unit-build` | core | hardcoded defaults | Seeded (add-if-missing; install and upgrade). What hooks, workflows and prompts run; the name states which tiers. The tool scripts the defaults chain (`typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta`) and their devDeps are templates: `.bkit/templates.md`. |
|
|
272
285
|
| `package.json#scripts.bkit:deps:outdated` / `bkit:deps:audit` | core | hardcoded defaults | Seeded (add-if-missing; install and upgrade). Read-only dependency inspection the remediate / diagnose agents call. |
|
|
273
286
|
| `.cursor/hooks.json` | cursor | `.bkit/shared/.cursor/hooks.json` | Tier 1 (fully managed) |
|
|
274
287
|
| `.cursor/mcp.json` | cursor | `.bkit/shared/.cursor/mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only |
|
|
@@ -289,7 +302,7 @@ The cloud workflow and the Cursor Background Agent files are templates the `--au
|
|
|
289
302
|
|
|
290
303
|
### Optional post-install decisions (tracker + cloud agents)
|
|
291
304
|
|
|
292
|
-
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.
|
|
305
|
+
Two capabilities **opt-in**, excluded from default install: **issue tracker** (`--tracker=github|linear|jira`), **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.
|
|
293
306
|
|
|
294
307
|
**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.
|
|
295
308
|
|
|
@@ -347,7 +360,7 @@ Slash commands at repo root:
|
|
|
347
360
|
|
|
348
361
|
Claude reads issue, comments, plan files via tracker MCP.
|
|
349
362
|
|
|
350
|
-
**Requirements:** `BKIT_GH_TOKEN`, active Claude Code session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` when `bkit.issueTracker = "linear"`. Session model = orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column) — set via `/model` before invoking; not duplicated here.
|
|
363
|
+
**Requirements:** `BKIT_GH_TOKEN`, active Claude Code session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` when `bkit.issueTracker = "linear"`; `BKIT_JIRA_API_TOKEN` when `"jira"`. Session model = orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column) — set via `/model` before invoking; not duplicated here.
|
|
351
364
|
|
|
352
365
|
### From Cursor (interactive — local)
|
|
353
366
|
|
|
@@ -359,7 +372,7 @@ Cursor 2.4+ honours `.cursor/commands/bkit-*.md` and `.cursor/agents/bkit-*.md`:
|
|
|
359
372
|
|
|
360
373
|
Orchestrator reads `.cursor/commands/` workflow. Subagents via `Task`, `model:` from frontmatter (no host override).
|
|
361
374
|
|
|
362
|
-
**Requirements:** `BKIT_GH_TOKEN` (GitHub, default) or `BKIT_LINEAR_API_KEY` (Linear). Cursor account in good standing.
|
|
375
|
+
**Requirements:** `BKIT_GH_TOKEN` (GitHub, default) or `BKIT_LINEAR_API_KEY` (Linear) or `BKIT_JIRA_API_TOKEN` (Jira). Cursor account in good standing.
|
|
363
376
|
|
|
364
377
|
---
|
|
365
378
|
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
5
|
> [!CAUTION]
|
|
6
|
-
> **Purpose:** Canonical reference for Claude Code on the web (mobile / web), Cursor Cloud Agents, and opencode cloud runners. Claude + opencode → **GitHub** tracker (unified `bkit-cloud.yml`); Cursor → **Linear
|
|
6
|
+
> **Purpose:** Canonical reference for Claude Code on the web (mobile / web), Cursor Cloud Agents, and opencode cloud runners. Claude + opencode → **GitHub** tracker (unified `bkit-cloud.yml`); Cursor → **Linear**; **Jira** → local runs only (no Jira-side cloud trigger). Not interchangeable per repo — pick agent matching your tracker (see § Cloud-agent support matrix).
|
|
7
7
|
>
|
|
8
8
|
> **Rules:**
|
|
9
9
|
>
|
|
@@ -28,9 +28,9 @@ Three cloud stacks — each agent pairs with one tracker. Pick row for agent you
|
|
|
28
28
|
| **opencode** (GitHub runner) | **A)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **B)** GitHub CI pass/fail → `bkit-cloud.yml` opencode job (requires `OPENCODE_PROVIDER_KEY` secret) · **C)** reactive `/oc` comment handler (self-installed, not bkit — see § Reactive comment handlers) | **GitHub** | **Linear** |
|
|
29
29
|
| **Cursor** (native agent) | **A)** Cursor's built-in cloud-agent launch · **B)** Cursor's GitHub integration on PR events (CI pass/fail) · **C)** Linear → Cursor integration | **Linear** (+ GitHub PR events) | **GitHub Projects / Issues** |
|
|
30
30
|
|
|
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
|
|
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 credential (claude: `ANTHROPIC_API_KEY` secret or federation variables; opencode: `OPENCODE_PROVIDER_KEY`). Both jobs can fire on same CI event — both credentials → both agents; one → 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` / `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
|
|
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, records each recommended answer as `Assumed, not confirmed`, and records the draft acceptance scenario as not reviewed by a human. 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
|
|
|
@@ -115,6 +115,39 @@ Always `Custom` — the rendered list carries bkit's own shipped hosts (trackers
|
|
|
115
115
|
|
|
116
116
|
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.
|
|
117
117
|
|
|
118
|
+
### Setup script
|
|
119
|
+
|
|
120
|
+
`bkit install` generates copy-paste-ready setup script into `.claude/bkit-cloud.md` § Setup script — resolved for this repo, with cache-bust line, base-tool installs, any `context-fetch:provision` recipes. **Paste that**, not hand-copied snippet: stale copy drifts (hard-pinned pnpm can seed version known to break `bkit` download; `apt install gh` unreliable — gh not in default repos).
|
|
121
|
+
|
|
122
|
+
What it does and why split from in-repo hook:
|
|
123
|
+
|
|
124
|
+
- **`# cache-bust <date>-<n>`** first line generator writes (`bkit install` / `bkit upgrade` re-stamp). Snapshot keyed on setup script exact text — only job is to change: new date (or bumped same-day counter) forces fresh snapshot on next paste, re-pulling any unpinned tool a `context-fetch:provision` recipe installs, plus base-image drift even when rest byte-identical. Leave in place — do not hand-edit.
|
|
125
|
+
- **Base tools (Node, vale, gh, jq)** install once into snapshot from upstream releases, each pinned to a version and checked with `sha256sum -c` before it is unpacked or made executable (the `# renovate:` comment above each `*_VERSION` lets Renovate bump the pin) — Node 24 from the nodejs.org `linux-x64` tarball into `/usr/local`, then `/usr/local/bin` prepended to `PATH` so corepack and every later step run on it (bkit needs Node >=24; image ships 20 + 22); `gh` from the `cli/cli` release tarball (not `apt`), `jq` because `curl`-based context-fetch blocks pipe through it. Node, gh and vale pins match `.cursor/Dockerfile`. Binaries cloud lacks but laptop has — not repo-level hook.
|
|
126
|
+
- **pnpm corepack pre-warm** seeds one pnpm into snapshot via `corepack enable` (no hard-pinned version). In-repo, corepack resolves repo's `packageManager` (fetching if differs) — one setup script serves any pnpm pin; pre-warm is warm cache.
|
|
127
|
+
- `pnpm install` and `vale sync` **not** here — belong in `.claude/hooks/bkit-cloud-bootstrap.sh` for resumed sessions when lockfile/styles drifted; each repo installs own deps.
|
|
128
|
+
|
|
129
|
+
Keep total runtime under ~5 minutes or snapshot won't build.
|
|
130
|
+
|
|
131
|
+
#### Workspace trust + auto-mode config
|
|
132
|
+
|
|
133
|
+
`permissions.allow` / `permissions.additionalDirectories` in `.claude/settings.json` **grant** capability — applied only after the workspace trust dialog, never shown in a cloud (`-p` / SDK) session. `deny` / `ask` unaffected (restrict-only). Untrusted → every `allow` row ignored; sole notice one stderr line no cloud session surfaces.
|
|
134
|
+
|
|
135
|
+
Setup script writes both host-side, after the `jq` install:
|
|
136
|
+
|
|
137
|
+
<!-- prettier-ignore -->
|
|
138
|
+
| Written | Where | Why setup script |
|
|
139
|
+
| --- | --- | --- |
|
|
140
|
+
| `projects[<repo path>].hasTrustDialogAccepted = true` | `~/.claude.json` | Settings resolve **before** `SessionStart` (hook too late); `.claude/` is a protected path (in-session write refused). Setup script = root, pre-clone, pre-Claude, snapshotted. |
|
|
141
|
+
| `autoMode.environment` — `"$defaults"` first, `Host containment` entry, network-allowlist hosts | `~/.claude/settings.json` | Classifier reads `autoMode` from user / managed settings **only** — never `.claude/settings.json` / `.claude/settings.local.json`. Not shippable in-repo. |
|
|
142
|
+
|
|
143
|
+
Both `jq`-merge, never clobber; `autoMode.environment` seeded `//=` (consumer list never overwritten). Omit `"$defaults"` → **whole built-in list discarded** for that section (incl. `Trusted repo`); renderer always emits it.
|
|
144
|
+
|
|
145
|
+
Neither file is committable: `~/.claude/settings.json` resolves outside the repo tree; a git-**tracked** `.claude/settings.local.json` counts as repository-supplied, same trust gate.
|
|
146
|
+
|
|
147
|
+
Baked path `/home/user/<repo-name>` = observation of the current image, **not** a contract (no env var names the repo root). `.claude/hooks/bkit-cloud-bootstrap.sh` re-checks the discovered git root each session and warns on mismatch — diagnosis only, no repair. Fix: re-paste setup script.
|
|
148
|
+
|
|
149
|
+
Auto mode drops blanket `Bash(*)` on entry (narrow rows survive) → cloud auto-mode sessions run on classifier verdicts + `autoMode.environment`, not the allow list. Default classifier trust = working repo + remotes; every context-fetch host external until named. `Host containment` default assumes an open-internet dev machine.
|
|
150
|
+
|
|
118
151
|
### Environment variables
|
|
119
152
|
|
|
120
153
|
Minimum:
|
|
@@ -163,39 +196,6 @@ SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/da
|
|
|
163
196
|
- Earlier auto-compaction: set `autoCompactWindow` in committed `.claude/settings.json` (`.bkit/providers.md` § Context compaction) — applies to cloud sessions as-is; no env var.
|
|
164
197
|
- **Env vars set in Claude app are not visible inside setup script.** Injected only after Claude Code starts → `SessionStart` hooks + interactive shell, not snapshot build. Tool needing token to bootstrap must inline it — leak you want to avoid. Avoided today: vale / gh / corepack don't need auth.
|
|
165
198
|
|
|
166
|
-
### Setup script
|
|
167
|
-
|
|
168
|
-
`bkit install` generates copy-paste-ready setup script into `.claude/bkit-cloud.md` § Setup script — resolved for this repo, with cache-bust line, base-tool installs, any `context-fetch:provision` recipes. **Paste that**, not hand-copied snippet: stale copy drifts (hard-pinned pnpm can seed version known to break `bkit` download; `apt install gh` unreliable — gh not in default repos).
|
|
169
|
-
|
|
170
|
-
What it does and why split from in-repo hook:
|
|
171
|
-
|
|
172
|
-
- **`# cache-bust <date>-<n>`** first line generator writes (`bkit install` / `bkit upgrade` re-stamp). Snapshot keyed on setup script exact text — only job is to change: new date (or bumped same-day counter) forces fresh snapshot on next paste, re-pulling any unpinned tool a `context-fetch:provision` recipe installs, plus base-image drift even when rest byte-identical. Leave in place — do not hand-edit.
|
|
173
|
-
- **Base tools (Node, vale, gh, jq)** install once into snapshot from upstream releases, each pinned to a version and checked with `sha256sum -c` before it is unpacked or made executable (the `# renovate:` comment above each `*_VERSION` lets Renovate bump the pin) — Node 24 from the nodejs.org `linux-x64` tarball into `/usr/local`, then `/usr/local/bin` prepended to `PATH` so corepack and every later step run on it (bkit needs Node >=24; image ships 20 + 22); `gh` from the `cli/cli` release tarball (not `apt`), `jq` because `curl`-based context-fetch blocks pipe through it. Node, gh and vale pins match `.cursor/Dockerfile`. Binaries cloud lacks but laptop has — not repo-level hook.
|
|
174
|
-
- **pnpm corepack pre-warm** seeds one pnpm into snapshot via `corepack enable` (no hard-pinned version). In-repo, corepack resolves repo's `packageManager` (fetching if differs) — one setup script serves any pnpm pin; pre-warm is warm cache.
|
|
175
|
-
- `pnpm install` and `vale sync` **not** here — belong in `.claude/hooks/bkit-cloud-bootstrap.sh` for resumed sessions when lockfile/styles drifted; each repo installs own deps.
|
|
176
|
-
|
|
177
|
-
Keep total runtime under ~5 minutes or snapshot won't build.
|
|
178
|
-
|
|
179
|
-
#### Workspace trust + auto-mode config
|
|
180
|
-
|
|
181
|
-
`permissions.allow` / `permissions.additionalDirectories` in `.claude/settings.json` **grant** capability — applied only after the workspace trust dialog, never shown in a cloud (`-p` / SDK) session. `deny` / `ask` unaffected (restrict-only). Untrusted → every `allow` row ignored; sole notice one stderr line no cloud session surfaces.
|
|
182
|
-
|
|
183
|
-
Setup script writes both host-side, after the `jq` install:
|
|
184
|
-
|
|
185
|
-
<!-- prettier-ignore -->
|
|
186
|
-
| Written | Where | Why setup script |
|
|
187
|
-
| --- | --- | --- |
|
|
188
|
-
| `projects[<repo path>].hasTrustDialogAccepted = true` | `~/.claude.json` | Settings resolve **before** `SessionStart` (hook too late); `.claude/` is a protected path (in-session write refused). Setup script = root, pre-clone, pre-Claude, snapshotted. |
|
|
189
|
-
| `autoMode.environment` — `"$defaults"` first, `Host containment` entry, network-allowlist hosts | `~/.claude/settings.json` | Classifier reads `autoMode` from user / managed settings **only** — never `.claude/settings.json` / `.claude/settings.local.json`. Not shippable in-repo. |
|
|
190
|
-
|
|
191
|
-
Both `jq`-merge, never clobber; `autoMode.environment` seeded `//=` (consumer list never overwritten). Omit `"$defaults"` → **whole built-in list discarded** for that section (incl. `Trusted repo`); renderer always emits it.
|
|
192
|
-
|
|
193
|
-
Neither file is committable: `~/.claude/settings.json` resolves outside the repo tree; a git-**tracked** `.claude/settings.local.json` counts as repository-supplied, same trust gate.
|
|
194
|
-
|
|
195
|
-
Baked path `/home/user/<repo-name>` = observation of the current image, **not** a contract (no env var names the repo root). `.claude/hooks/bkit-cloud-bootstrap.sh` re-checks the discovered git root each session and warns on mismatch — diagnosis only, no repair. Fix: re-paste setup script.
|
|
196
|
-
|
|
197
|
-
Auto mode drops blanket `Bash(*)` on entry (narrow rows survive) → cloud auto-mode sessions run on classifier verdicts + `autoMode.environment`, not the allow list. Default classifier trust = working repo + remotes; every context-fetch host external until named. `Host containment` default assumes an open-internet dev machine.
|
|
198
|
-
|
|
199
199
|
## Environment variables
|
|
200
200
|
|
|
201
201
|
Token management by session type:
|
|
@@ -218,34 +218,41 @@ Token management by session type:
|
|
|
218
218
|
|
|
219
219
|
## MCP issue-tracker integration
|
|
220
220
|
|
|
221
|
-
bkit wires
|
|
221
|
+
bkit wires the chosen tracker's MCP server (`bkit.issueTracker`) into `.mcp.json` at repo root (project-shared, read by Claude Code `/mcp` UI). Cursor reads same shape from `.cursor/mcp.json`. All **remote HTTP MCPs** — no docker. GitHub: `BKIT_GH_TOKEN` PAT in the `Authorization` header — no OAuth. Linear: OAuth on first use — Claude Code launches browser auth on first server touch, stores token in own secret store. Jira: `BKIT_JIRA_API_TOKEN` scoped token in the `Authorization` header — no OAuth.
|
|
222
222
|
|
|
223
223
|
> Note: `mcpServers` in `.claude/settings.json` silently ignored by Claude Code — definitions only from `.mcp.json` (project) or `claude mcp add` (user scope). `mcp__<name>__*` in `.claude/settings.json` `permissions.allow` are tool-permission allowlists — different concern, remain there.
|
|
224
224
|
|
|
225
225
|
```json
|
|
226
226
|
"mcpServers": {
|
|
227
|
-
"linear": { "type": "http", "url": "https://mcp.linear.app/mcp" },
|
|
228
227
|
"github": {
|
|
229
228
|
"type": "http",
|
|
230
229
|
"url": "https://api.githubcopilot.com/mcp/",
|
|
231
230
|
"headers": { "Authorization": "Bearer ${BKIT_GH_TOKEN}" }
|
|
231
|
+
},
|
|
232
|
+
"linear": { "type": "http", "url": "https://mcp.linear.app/mcp" },
|
|
233
|
+
"jira": {
|
|
234
|
+
"type": "http",
|
|
235
|
+
"url": "https://mcp.atlassian.com/v2/mcp",
|
|
236
|
+
"headers": { "Authorization": "Bearer ${BKIT_JIRA_API_TOKEN}" }
|
|
232
237
|
}
|
|
233
238
|
}
|
|
234
239
|
```
|
|
235
240
|
|
|
236
241
|
`"type": "http"` required — without it Claude Code defaults to stdio transport and rejects entry for missing `command`.
|
|
237
242
|
|
|
238
|
-
- **Linear** — full Linear workspace surface (`get_issue`, `save_issue`, `save_comment`, `list_*`). Used when `bkit.issueTracker` = `linear`. OAuth (Dynamic Client Registration) — browser flow on first use, no env var.
|
|
239
243
|
- **GitHub** — official GitHub MCP at `api.githubcopilot.com` (not gated by Copilot subscription). Surface: `issue_write`, `add_issue_comment`, `label_write`, `projects_write`, etc. Used under GitHub provider. Endpoint does **not** support OAuth DCR → auth via `Authorization: Bearer ${BKIT_GH_TOKEN}` (MCP-only env var — see § Environment variables and KN-CORE-8).
|
|
244
|
+
- **Linear** — full Linear workspace surface (`get_issue`, `save_issue`, `save_comment`, `list_*`). Used when `bkit.issueTracker` = `linear`. OAuth (Dynamic Client Registration) — browser flow on first use, no env var.
|
|
245
|
+
- **Jira** — Atlassian Rovo MCP at `mcp.atlassian.com/v2/mcp`. Surface: `getJiraIssue`, `editJiraIssue`, `transitionJiraIssue`, `addOrEditJiraIssueComment`, `searchJiraIssuesUsingJql`, `executeRead` / `executeWrite`. Used when `bkit.issueTracker` = `jira`. Auth via `Authorization: Bearer ${BKIT_JIRA_API_TOKEN}` — a scoped **Atlassian MCP V2** token; org admin must allow API-token sign-in (`.bkit/trackers.md` § jira — setup and notes).
|
|
240
246
|
|
|
241
247
|
**Auth flow per server:**
|
|
242
248
|
|
|
243
|
-
- **Linear:** Claude Code prompts browser authorize on first use; token in Claude's secret store. No further action.
|
|
244
249
|
- **GitHub:** Claude Code substitutes `${BKIT_GH_TOKEN}` from environment at session start. Unset → server fails. Set in shell (`export BKIT_GH_TOKEN=...`) or cloud dashboard.
|
|
250
|
+
- **Linear:** Claude Code prompts browser authorize on first use; token in Claude's secret store. No further action.
|
|
251
|
+
- **Jira:** Claude Code substitutes `${BKIT_JIRA_API_TOKEN}` from environment at session start. Unset or classic token → every Jira call fails.
|
|
245
252
|
|
|
246
253
|
**`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.
|
|
247
254
|
|
|
248
|
-
**Cloud sessions** (Claude on the web, Cursor Cloud Agents): Linear MCP OAuth on first touch, same as local.
|
|
255
|
+
**Cloud sessions** (Claude on the web, Cursor Cloud Agents): GitHub MCP reads `BKIT_GH_TOKEN` from dashboard — set alongside `BKIT_LINEAR_API_KEY` under Linear. Linear MCP OAuth on first touch, same as local. Jira: no cloud sessions (local runs only).
|
|
249
256
|
|
|
250
257
|
## After saving the Claude env
|
|
251
258
|
|
|
@@ -398,7 +405,7 @@ Routing **logic** in single bkit-managed slash-command orchestrator (`.bkit/core
|
|
|
398
405
|
<!-- prettier-ignore -->
|
|
399
406
|
| | Lives in the repo (bkit-managed) | Lives in the online dashboard / GitHub (manual, one-time) |
|
|
400
407
|
| --- | --- | --- |
|
|
401
|
-
| **Claude** | `.github/workflows/bkit-cloud.yml` — `claude` job (opt-in via `bkit install --auto=claude`; GitHub-tracker only). Two-tier gate: (1) free tier — job `if: contains(head_commit.message, 'bkit [auto route]')` (zero runner minutes for non-opted-in commits); (2) cheap tier — in-job `gh issue view {ISSUE} --json labels` re-checks `bkit:auto` (live kill switch); then dispatches `claude-code-action` as the Claude GitHub App (OIDC, `id-token: write`). | GitHub repo secret
|
|
408
|
+
| **Claude** | `.github/workflows/bkit-cloud.yml` — `claude` job (opt-in via `bkit install --auto=claude`; GitHub-tracker only). Two-tier gate: (1) free tier — job `if: contains(head_commit.message, 'bkit [auto route]')` (zero runner minutes for non-opted-in commits); (2) cheap tier — in-job `gh issue view {ISSUE} --json labels` re-checks `bkit:auto` (live kill switch); then dispatches `claude-code-action` as the Claude GitHub App (OIDC, `id-token: write`). | Claude credential: GitHub repo secret `ANTHROPIC_API_KEY` (`.bkit/.env` holds the same value as `BKIT_ANTHROPIC_API_KEY`) **or** keyless federation repo variables (§ Claude — workload identity federation). Claude GitHub App required (`/install-github-app`). The linked **GitHub issue** must carry `bkit:auto`. |
|
|
402
409
|
| **opencode** | Same `.github/workflows/bkit-cloud.yml` — `opencode` job (opt-in via `bkit install --auto=opencode`; GitHub-tracker only). Same two-tier gate (same file, separate job). Dispatches via `opencode run "/bkit-auto $PHASE $ARG"`. No `id-token: write` — no OIDC; uses `github.token` for repo ops. | GitHub repo secret: `OPENCODE_PROVIDER_KEY` (set to your provider API key). Provider model committed in `.opencode/opencode.json`. The linked **GitHub issue** must carry `bkit:auto`. |
|
|
403
410
|
| **Cursor** | Nothing — Cursor cloud agents have native triggers. | Cursor → Cloud Agents dashboard → Triggers → + Add trigger. Event: CI workflow completion on `feat/**` branches. Prompt (paste **literally**, no edits): `/bkit-auto $CI_STATUS $PR_NUMBER`. Concurrency: latest-supersedes. |
|
|
404
411
|
|
|
@@ -419,15 +426,39 @@ Flip **both** org and repo before first router run — else `actions/checkout` 4
|
|
|
419
426
|
|
|
420
427
|
`workflow_run`-triggered runs do **not** inherit parent CI workflow's `permissions:` block (only fork-PR tokens get narrowed) — parent CI at `contents: read` fine.
|
|
421
428
|
|
|
422
|
-
## bkit-cloud.yml — required GitHub repo
|
|
429
|
+
## bkit-cloud.yml — required GitHub repo credentials
|
|
423
430
|
|
|
424
431
|
<!-- prettier-ignore -->
|
|
425
|
-
| Secret | Job | Why | Scope |
|
|
432
|
+
| Secret / variable | Job | Why | Scope |
|
|
426
433
|
| --- | --- | --- | --- |
|
|
427
|
-
| `ANTHROPIC_API_KEY` | `claude` | `claude-code-action` authenticates against Anthropic. | API key with Claude Code access. |
|
|
434
|
+
| `ANTHROPIC_API_KEY` secret | `claude` | `claude-code-action` authenticates against Anthropic. | API key with Claude Code access. Omit when using federation. |
|
|
435
|
+
| `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` variables | `claude` | Keyless alternative: the action trades the job's GitHub OIDC token for a short-lived Claude API token. | IDs, not secrets — repo **variables**. Optional `ANTHROPIC_SERVICE_ACCOUNT_ID` / `ANTHROPIC_WORKSPACE_ID`. § Claude — workload identity federation. |
|
|
428
436
|
| `OPENCODE_PROVIDER_KEY` | `opencode` | Fanned out to every cloud provider's env var name (`BKIT_OPENROUTER_API_KEY`, `BKIT_OLLAMA_API_KEY`, `BKIT_OPENCODE_API_KEY`) so the `.opencode/opencode.json` `{env:VAR}` reference resolves whichever provider is installed. | Provider API key for whichever provider you configured. |
|
|
429
437
|
|
|
430
|
-
A `context` job checks both
|
|
438
|
+
A `context` job (`Check runner credentials` step) checks both credentials and resolves phase + arg once, no-op unless `package.json` `bkit.issueTracker` is `github` or unset (Linear cloud runs start from Cursor's Linear integration; Jira runs locally only); each runner job needs it and runs only when its own credential is set. Claude credential = `ANTHROPIC_API_KEY`, or **both** federation variables (one alone → `::notice::` naming the missing one, claude no-op). Only claude credential → 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 (Claude GitHub App + federation token exchange; opencode no OIDC).
|
|
439
|
+
|
|
440
|
+
## Claude — workload identity federation
|
|
441
|
+
|
|
442
|
+
Keyless claude job: no long-lived `ANTHROPIC_API_KEY` stored in GitHub. `claude-code-action` asks GitHub for the job's OIDC token (issuer `https://token.actions.githubusercontent.com`, audience `https://api.anthropic.com`), Anthropic checks it against a federation rule, returns a short-lived Claude API token. Action refreshes it in the background on long runs.
|
|
443
|
+
|
|
444
|
+
**Setup (one-time):**
|
|
445
|
+
|
|
446
|
+
1. Claude Console → **Settings → Workload identity → Connect workload → GitHub Actions**. Creates the federation issuer, a service account, and a federation rule.
|
|
447
|
+
2. Scope the rule to this repo's default branch — `bkit-cloud.yml` runs from it (`workflow_run` + `workflow_dispatch`):
|
|
448
|
+
- `subject_prefix`: `repo:<owner>/<repo>:ref:refs/heads/<default-branch>`
|
|
449
|
+
- claims: `repository_owner` = `<owner>`, `ref` = `refs/heads/<default-branch>`
|
|
450
|
+
- to limit the rule to `bkit-cloud.yml`, add claim `workflow_ref` = `<owner>/<repo>/.github/workflows/bkit-cloud.yml@refs/heads/<default-branch>`. GitHub's token carries it; Anthropic's docs do not list it as matchable. Without it, every workflow on the default branch matches the rule.
|
|
451
|
+
3. Set repo **variables** (IDs, not secrets):
|
|
452
|
+
```sh
|
|
453
|
+
gh variable set ANTHROPIC_FEDERATION_RULE_ID --body='fdrl_...'
|
|
454
|
+
gh variable set ANTHROPIC_ORGANIZATION_ID --body='<organization-uuid>'
|
|
455
|
+
# optional: ANTHROPIC_SERVICE_ACCOUNT_ID (svac_...), ANTHROPIC_WORKSPACE_ID
|
|
456
|
+
```
|
|
457
|
+
4. Delete the key if one is set: `gh secret delete ANTHROPIC_API_KEY`. **A set key wins over federation** — the action uses the key and federation never runs. `bkit check` flags both-set (`anthropic-api-key-shadows-federation`).
|
|
458
|
+
|
|
459
|
+
**Adopted copy predates federation:** variables set but `.github/workflows/bkit-cloud.yml` lacks the `anthropic_federation_rule_id:` input → claude job sees no credential. `bkit check` flags it (`anthropic-federation-template-stale`); re-copy from `.bkit/templates/.github/workflows/bkit-cloud.yml`, re-apply local edits (`runs-on`).
|
|
460
|
+
|
|
461
|
+
**401 from token exchange:** Anthropic returns `401 Authentication failed` whichever check failed. Console → Workload identity → authentication history shows the deny reason per attempt; `match_subject_prefix` = the run's `sub` doesn't match the rule's `subject_prefix` — fix or widen the rule. A job on a non-default branch or an `environment:` has a different subject (`...:ref:refs/heads/<branch>` / `...:environment:<name>`).
|
|
431
462
|
|
|
432
463
|
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.
|
|
433
464
|
|
|
@@ -50,7 +50,7 @@ Kind: **Framework** runs a fixed multi-phase process · **Spec toolkit** writes
|
|
|
50
50
|
| **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 |
|
|
51
51
|
| **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 |
|
|
52
52
|
| **CI**<br>a test pipeline for your project | ✅ fails on skipped lane / zero tests | — | ◐ basic `test.yml` | — | — | — | — | — | ◐ example | — | ◐ AI PR review only |
|
|
53
|
-
| **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 |
|
|
53
|
+
| **Tracker** | GitHub, Linear, Jira | — | ◐ GitHub | GitHub, Linear, Jira | — by design | GitHub, Jira, Linear, Notion, Trello | ◐ tasks → GitHub issues | ? | ◐ GitHub, GitLab | GitHub, Jira | GitHub, GitLab, Jira, Linear |
|
|
54
54
|
| **Memory**<br>lessons and decisions later runs read | ✅ | — | ✅ outside repo | ✅ `docs/solutions/` | ✅ | ◐ | ◐ constitution | ◐ living specs | ◐ | ✅ | ◐ opt-in |
|
|
55
55
|
| **Docs**<br>project docs kept current | ✅ | — | ✅ | ◐ | ◐ | ◐ | ◐ | ◐ specs | ◐ | ◐ | ◐ AGENTS.md |
|
|
56
56
|
| **Parallel**<br>several features at once, isolated | ✅ | ◐ | ◐ via Conductor | ◐ | ✅ | ◐ | ◐ via extensions | ◐ | ✅ 10 cloud sandboxes | ◐ | ✅ containers |
|
|
@@ -74,7 +74,7 @@ Where others are ahead of bkit:
|
|
|
74
74
|
|
|
75
75
|
Where bkit stands apart, per the table:
|
|
76
76
|
|
|
77
|
-
- **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.
|
|
77
|
+
- **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 / Jira tracker, and file-based memory.
|
|
78
78
|
- **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).
|
|
79
79
|
- **Merge discipline:** merges into `dev` only after the capstone check, never `main`. OpenHands merges with no human; most stop at a PR.
|
|
80
80
|
- **Debug with outside evidence:** connectors pull CI logs, runtime errors and web results into diagnosis; soak mode for runtime-only bugs; handover when unfixable.
|
|
@@ -144,7 +144,7 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
|
|
|
144
144
|
| Evaluation & Monitoring | Partial | `friction` / `knowledge` logs, CI gates, and a catalog-parity drift check. No automated regression-fixture eval harness yet. |
|
|
145
145
|
| Exploration & Discovery | Partial | Divergent brainstorm triplet plus feasibility search. No temperature-spread or vote-of-K. |
|
|
146
146
|
| Inter-Agent Communication (A2A) | N/A by design | Agents communicate only via filesystem artifacts — deliberate, to preserve leaf-only and resume guarantees. |
|
|
147
|
-
| Prioritization | N/A by design | Features run in parallel, one worktree each; per-feature `.lock` blocks a second run of the same feature
|
|
147
|
+
| Prioritization | N/A by design | Features run in parallel, one worktree each; per-feature `.lock` blocks a second run of the same feature; every `dev` write is built in a throwaway `origin/dev` checkout and rebuilt when `dev` moved, so features never wait on each other. Ordering across features = human / tracker. |
|
|
148
148
|
|
|
149
149
|
<a id="beyond-the-book"></a>
|
|
150
150
|
|