@cbartens/bkit 6.1.1 → 6.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +14 -12
- package/.bkit/core/.agents/docs.md +1 -11
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
- package/.bkit/core/.agents/rules.md +22 -9
- package/.bkit/core/.bkit/README.md +13 -11
- package/.bkit/core/.bkit/authoring.md +58 -13
- package/.bkit/core/.bkit/cli.md +42 -32
- package/.bkit/core/.bkit/cloud.md +93 -30
- package/.bkit/core/.bkit/install.md +55 -16
- package/.bkit/core/.bkit/jsonl.md +24 -7
- package/.bkit/core/.bkit/pipeline.md +8 -8
- package/.bkit/core/.bkit/prompts.md +160 -43
- package/.bkit/core/.bkit/providers.md +97 -36
- package/.bkit/core/.bkit/templates.md +162 -34
- package/.bkit/core/.bkit/trackers.md +39 -6
- package/.bkit/core/.bkit/workflows.md +344 -136
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
- package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
- 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 +1 -1
- 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 +2 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
- package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -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 +1 -1
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +38 -8
- package/.bkit/core/engine/checks/after/auth.ts +118 -47
- package/.bkit/core/engine/checks/after/github.ts +89 -37
- package/.bkit/core/engine/checks/after/index.ts +15 -3
- package/.bkit/core/engine/checks/after/tools.ts +245 -1
- package/.bkit/core/engine/checks/before/files.ts +59 -1
- package/.bkit/core/engine/checks/before/index.ts +8 -0
- package/.bkit/core/engine/checks/status-holes.ts +20 -26
- package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
- package/.bkit/core/engine/checks/tips/detect.ts +36 -3
- package/.bkit/core/engine/checks/tips/index.ts +1 -1
- package/.bkit/core/engine/cli.ts +13 -13
- package/.bkit/core/engine/commands/ci/ci.ts +64 -11
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- package/.bkit/core/engine/commands/install/install.ts +28 -25
- package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
- package/.bkit/core/engine/commands/land.ts +2 -3
- package/.bkit/core/engine/commands/lib.ts +394 -39
- package/.bkit/core/engine/commands/registry.ts +1 -1
- package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
- package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
- package/.bkit/core/engine/commands/workflow/context.ts +71 -10
- package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
- package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
- package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
- package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
- package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
- package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
- package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
- package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
- package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
- package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
- package/.bkit/core/engine/commands/workflow/status.ts +324 -11
- package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
- package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
- package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
- package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
- package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
- package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
- package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
- package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
- package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
- package/.bkit/core/engine/install/cloud-env.ts +38 -10
- package/.bkit/core/engine/install/managed-block.ts +105 -0
- package/.bkit/core/engine/install/manifest.ts +7 -1
- package/.bkit/core/engine/install/modules/claude.ts +6 -2
- package/.bkit/core/engine/install/modules/cloud.ts +84 -95
- package/.bkit/core/engine/install/modules/codex.ts +10 -2
- package/.bkit/core/engine/install/modules/core.ts +148 -14
- package/.bkit/core/engine/install/modules/opencode.ts +18 -23
- package/.bkit/core/engine/install/network-allowlist.ts +8 -3
- package/.bkit/core/engine/install/project-docs.ts +650 -0
- package/.bkit/core/engine/install/template-copies.ts +58 -5
- package/.bkit/core/engine/install/write.ts +128 -7
- package/.bkit/core/engine/ledgers/journal.ts +18 -10
- package/.bkit/core/engine/ledgers/migrate.ts +20 -8
- package/.bkit/core/engine/ledgers/status.ts +604 -8
- package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
- package/.bkit/core/engine/render/trackers.ts +3 -1
- package/.bkit/core/engine/shared/package-manager.ts +7 -3
- package/.bkit/core/engine/shared/settings.ts +12 -1
- package/.bkit/core/engine/shared/text.ts +14 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
- package/.bkit/core/engine/tools/instructions.ts +116 -20
- package/.bkit/core/hooks/antigravity-hook.js +20 -4
- package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
- package/.bkit/core/hooks/gateguard-engine.js +249 -23
- package/.bkit/core/hooks/guardrails-deny.js +167 -0
- package/.bkit/core/hooks/guardrails-read.js +3 -3
- package/.bkit/core/hooks/guardrails-shell.js +1122 -167
- package/.bkit/core/hooks/guardrails-tiers.js +247 -176
- package/.bkit/core/hooks/preflight-tracker.sh +219 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
- package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
- package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
- package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
- package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
- package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
- package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
- package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
- package/.bkit/core/prompts/bkit-design-generate.md +6 -4
- package/.bkit/core/prompts/bkit-design-organise.md +4 -3
- package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
- package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
- package/.bkit/core/prompts/bkit-design-spike.md +4 -3
- package/.bkit/core/prompts/bkit-design-update.md +6 -4
- package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
- package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
- package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
- package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
- package/.bkit/core/prompts/bkit-plan-update.md +22 -8
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
- package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
- package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
- package/.bkit/core/workflows/bkit-auto.md +23 -11
- package/.bkit/core/workflows/bkit-build.md +331 -100
- package/.bkit/core/workflows/bkit-debug.md +135 -64
- package/.bkit/core/workflows/bkit-design.md +58 -32
- package/.bkit/core/workflows/bkit-plan.md +73 -45
- package/.bkit/core/workflows/bkit-ship.md +233 -167
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
- package/.bkit/shared/.bkit/.env.example +5 -0
- package/.bkit/shared/.claude/bkit-cloud.md +7 -7
- package/.bkit/shared/.claude/settings.json +5 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
- package/.bkit/shared/.cursor/hooks.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
- package/.bkit/templates/.cursor/Dockerfile +7 -7
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
- package/.bkit/templates/.github/dependabot.yml +5 -0
- package/.bkit/templates/.github/renovate.json5 +5 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
- package/.bkit/templates/.husky/pre-push +123 -6
- package/.bkit/templates/context/bkit-serena.md +1 -1
- package/.bkit/templates/docs/architecture.md +98 -0
- package/.bkit/templates/docs/capabilities.md +33 -37
- package/.bkit/templates/docs/components.md +142 -0
- package/.bkit/templates/docs/data-schema.md +87 -0
- package/.bkit/{shared → templates}/docs/deployments.md +128 -142
- package/.bkit/templates/docs/design.md +117 -0
- package/.bkit/templates/docs/noise.md +54 -0
- package/.bkit/templates/docs/observability.md +99 -0
- package/.bkit/templates/docs/security.md +137 -0
- package/.bkit/templates/docs/setup.md +93 -0
- package/.bkit/templates/docs/technology.md +70 -0
- package/.bkit/{shared → templates}/docs/testing.md +200 -87
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +64 -0
- package/DETAILS.md +24 -19
- package/README.md +1 -1
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +77 -35
- package/dist/checks/after/index.js +12 -3
- package/dist/checks/after/tools.js +224 -1
- package/dist/checks/before/files.js +59 -1
- package/dist/checks/before/index.js +7 -1
- package/dist/checks/status-holes.js +20 -21
- package/dist/checks/tips/catalogue.js +99 -10
- package/dist/checks/tips/detect.js +35 -3
- package/dist/checks/tips/index.js +1 -1
- package/dist/cli.js +13 -13
- package/dist/commands/ci/ci.js +56 -12
- package/dist/commands/ci/push-gate.js +79 -44
- package/dist/commands/install/install.js +23 -22
- package/dist/commands/install/uninstall.js +36 -30
- package/dist/commands/install/upgrade.js +10 -2
- package/dist/commands/land.js +2 -3
- package/dist/commands/lib.js +323 -25
- package/dist/commands/workflow/branches.js +312 -72
- package/dist/commands/workflow/challenge.js +66 -13
- package/dist/commands/workflow/context.js +46 -10
- package/dist/commands/workflow/counters.js +231 -23
- package/dist/commands/workflow/decisions.js +221 -106
- package/dist/commands/workflow/disk.js +2 -1
- package/dist/commands/workflow/feature-base.js +60 -0
- package/dist/commands/workflow/issues.js +243 -15
- package/dist/commands/workflow/junit.js +137 -0
- package/dist/commands/workflow/ledgers.js +726 -112
- package/dist/commands/workflow/locks.js +150 -29
- package/dist/commands/workflow/loops.js +67 -0
- package/dist/commands/workflow/open-decision.js +199 -0
- package/dist/commands/workflow/plan-blocks.js +6 -0
- package/dist/commands/workflow/plans.js +1 -1
- package/dist/commands/workflow/prs.js +272 -16
- package/dist/commands/workflow/repo.js +1 -1
- package/dist/commands/workflow/run-facts.js +6 -0
- package/dist/commands/workflow/runs.js +747 -155
- package/dist/commands/workflow/runtime.js +8 -4
- package/dist/commands/workflow/status.js +259 -13
- package/dist/commands/workflow/step-table.js +41 -15
- package/dist/commands/workflow/steps.js +530 -26
- package/dist/commands/workflow/summary-findings.js +1 -1
- package/dist/commands/workflow/summary.js +289 -8
- package/dist/commands/workflow/tasks.js +294 -27
- package/dist/commands/workflow/tests-base.js +266 -0
- package/dist/commands/workflow/tests-changed.js +130 -56
- package/dist/commands/workflow/tests-jump.js +77 -0
- package/dist/commands/workflow/tests.js +608 -131
- package/dist/commands/workflow/tracker.js +920 -112
- package/dist/commands/workflow/workflows.js +80 -59
- package/dist/commands/workflow/worktrees.js +387 -58
- package/dist/install/cloud-env.js +32 -10
- package/dist/install/managed-block.js +101 -0
- package/dist/install/manifest.js +7 -1
- package/dist/install/modules/claude.js +6 -2
- package/dist/install/modules/cloud.js +73 -86
- package/dist/install/modules/codex.js +9 -2
- package/dist/install/modules/core.js +133 -14
- package/dist/install/modules/opencode.js +18 -23
- package/dist/install/network-allowlist.js +8 -3
- package/dist/install/project-docs.js +551 -0
- package/dist/install/template-copies.js +55 -5
- package/dist/install/write.js +117 -5
- package/dist/ledgers/journal.js +10 -8
- package/dist/ledgers/migrate.js +20 -9
- package/dist/ledgers/status.js +461 -8
- package/dist/ledgers/telemetry.js +71 -13
- package/dist/render/trackers.js +3 -1
- package/dist/shared/package-manager.js +7 -2
- package/dist/shared/settings.js +8 -0
- package/dist/shared/text.js +13 -0
- package/dist/tools/instructions-sources.js +1 -0
- package/dist/tools/instructions.js +97 -24
- package/package.json +22 -15
- package/.bkit/core/hooks/preflight-linear.sh +0 -73
- package/.bkit/shared/docs/architecture.md +0 -16
- package/.bkit/shared/docs/data-schema.md +0 -16
- package/.bkit/shared/docs/design.md +0 -38
- package/.bkit/shared/docs/noise.md +0 -20
- package/.bkit/shared/docs/observability.md +0 -22
- package/.bkit/shared/docs/security.md +0 -62
- package/.bkit/shared/docs/setup.md +0 -52
- package/.bkit/shared/docs/technology.md +0 -15
- /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
- /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
5
|
> [!CAUTION]
|
|
6
|
-
> **Purpose:** The canonical reference for Claude on the web (mobile / web), Codex Cloud, Cursor Cloud Agents and OpenCode cloud runners. Environments do not depend on the tracker: every generated `<host>/bkit-cloud.md` carries the same env block (`BKIT_GH_TOKEN` plus whatever `.envrc` resolves, tracker keys included) for any tracker.
|
|
6
|
+
> **Purpose:** The canonical reference for Claude on the web (mobile / web), Codex Cloud, Cursor Cloud Agents and OpenCode cloud runners. Environments do not depend on the tracker: every generated `<host>/bkit-cloud.md` carries the same env block (`BKIT_GH_TOKEN` plus whatever `.envrc` resolves, tracker keys included) for any tracker. Any agent pairs with any wired tracker: Claude, OpenCode and Codex dispatch from one unified `bkit-cloud.yml` (one agent per run), and Cursor uses its native triggers. Codex Cloud tasks have no bkit dispatch, so you launch those runs by hand (§ Cloud-agent support matrix).
|
|
7
7
|
>
|
|
8
8
|
> **Rules:**
|
|
9
9
|
>
|
|
@@ -19,19 +19,19 @@
|
|
|
19
19
|
|
|
20
20
|
## Cloud-agent support matrix (read first)
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Every agent works with any wired tracker (GitHub, Linear or Jira), and the environments (`<host>/bkit-cloud.md`) work with any tracker. Install refuses only tracker `none`. Pick the row for the agent you run:
|
|
23
23
|
|
|
24
24
|
<!-- prettier-ignore -->
|
|
25
|
-
| Agent (the agent, not the editor) | Ways to launch a cloud agent |
|
|
26
|
-
| --- | --- | --- |
|
|
27
|
-
| **Claude** (terminal — any IDE host) | **A)** Claude iOS / desktop app → Claude-on-web env (`.claude/hooks/bkit-cloud-bootstrap.sh` + the env defined in `claude.ai/code`) · **B)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **C)** GitHub CI pass / fail → `bkit-cloud.yml` claude job · **D)** `@claude` mention on a GitHub issue / PR (needs `/install-github-app`, the base requirement for `cloud=claude`) |
|
|
28
|
-
| **Codex** (Codex Cloud) | **A)** ChatGPT Codex → task on the env from `.codex/bkit-cloud.md` (manual; no bkit dispatch)
|
|
29
|
-
| **Cursor** (native agent) | **A)** Cursor's built-in cloud-agent launch · **B)** Cursor's GitHub integration on PR events (CI pass / fail) · **C)**
|
|
30
|
-
| **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 `
|
|
25
|
+
| Agent (the agent, not the editor) | Ways to launch a cloud agent | not supported |
|
|
26
|
+
| --- | --- | --- |
|
|
27
|
+
| **Claude** (terminal — any IDE host) | **A)** Claude iOS / desktop app → Claude-on-web env (`.claude/hooks/bkit-cloud-bootstrap.sh` + the env defined in `claude.ai/code`) · **B)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **C)** GitHub CI pass / fail → `bkit-cloud.yml` claude job · **D)** `@claude` mention on a GitHub issue / PR (needs `/install-github-app`, the base requirement for `cloud=claude`) | none |
|
|
28
|
+
| **Codex** (Codex Cloud and GitHub runner) | **A)** ChatGPT Codex → task on the env from `.codex/bkit-cloud.md` (manual; no bkit dispatch) · **B)** manual `workflow_dispatch` on `bkit-cloud.yml` (pick phase + issue) · **C)** CI pass / fail → `bkit-cloud.yml` codex job (`openai/codex-action`; requires the `BKIT_OPENAI_API_KEY` secret; install with `--auto=codex --codex`) | Codex Cloud tasks started by bkit |
|
|
29
|
+
| **Cursor** (native agent) | **A)** Cursor's built-in cloud-agent launch · **B)** Cursor's GitHub integration on PR events (CI pass / fail) · **C)** tracker integration (Cursor's Linear integration) | bkit-triggered runner jobs |
|
|
30
|
+
| **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 one provider `BKIT_` secret: `BKIT_OPENCODE_API_KEY`, `BKIT_OPENROUTER_API_KEY` or `BKIT_OLLAMA_API_KEY`) · **C)** reactive `/oc` comment handler (self-installed, not bkit's: § Reactive comment handlers) | none |
|
|
31
31
|
|
|
32
|
-
**Unified file —
|
|
32
|
+
**Unified file — one agent per run:** Claude, OpenCode and Codex share one `bkit-cloud.yml`. A `context` job resolves the phase once and its `Select agent job` step reads `bkit.cloud.agent` from `package.json`. Only the job that names the recorded agent starts, and only when its `BKIT_` credential is set: the claude job on `BKIT_ANTHROPIC_API_KEY` or the federation variables, the opencode job on one provider `BKIT_` key, and the codex job on `BKIT_OPENAI_API_KEY`. A credential set for another agent is ignored, and the log names it. Cursor is separate: it has no GitHub Action and uses its native triggers.
|
|
33
33
|
|
|
34
|
-
**Manual dispatch (Claude
|
|
34
|
+
**Manual dispatch (Claude, OpenCode or Codex):** GitHub → **Actions** → **bkit-cloud** → **Run workflow**, then pick `phase` (`ship` / `debug` / `design` / `plan` / `build`) and `issue`. Use it on demand, or as a smoke test, for `design` / `plan` / `build`. `ship` / `debug` normally fire from CI. A 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. A dispatched `/bkit-auto` orchestrator hands off to the matching phase skill, which takes its brief from the GitHub issue through the MCP.
|
|
35
35
|
|
|
36
36
|
### Reactive comment handlers (`claude.yml` + `opencode.yml`) — separately managed, not bkit
|
|
37
37
|
|
|
@@ -43,7 +43,7 @@ Dispatch pairs each agent with one tracker, while the environments (`<host>/bkit
|
|
|
43
43
|
| `.github/workflows/claude.yml` | `/install-github-app` (Claude CLI → official Claude GitHub App) | OIDC as the App (`bkit-cloud.yml` grants `id-token: write`; no App installed → OIDC error at boot) | comment `@claude /bkit-plan` (or any phase) on an issue / PR |
|
|
44
44
|
| `.github/workflows/opencode.yml` | `opencode github install` (OpenCode CLI) | your provider key (`BKIT_OPENCODE_API_KEY` / `BKIT_OPENROUTER_API_KEY` / etc.) — no App, no OIDC | comment `/oc` or `/opencode` on an issue / PR |
|
|
45
45
|
|
|
46
|
-
You maintain these files, not bkit. `opencode.yml` hardcodes a `model:` and a provider-secret `env:`. Keep both in sync with your installed OpenCode provider. `bkit check` and postinstall raise a non-fatal advisory when they drift. Fix the file by hand, because bkit will not rewrite it. `claude.yml` has no equivalent check, because its `@claude` handler is fixed to Claude as its provider. For Claude, the `@claude` path is the base requirement for `cloud=claude`. Enable it with `bkit install --auto=claude
|
|
46
|
+
You maintain these files, not bkit. `opencode.yml` hardcodes a `model:` and a provider-secret `env:`. Keep both in sync with your installed OpenCode provider. `bkit check` and postinstall raise a non-fatal advisory when they drift. Fix the file by hand, because bkit will not rewrite it. `claude.yml` has no equivalent check, because its `@claude` handler is fixed to Claude as its provider. For Claude, the `@claude` path is the base requirement for `cloud=claude`. Enable it with `bkit install --auto=claude`. The App also gives the runner a GitHub identity for the `mcp__github__*` surface.
|
|
47
47
|
|
|
48
48
|
## What lives where (orient first)
|
|
49
49
|
|
|
@@ -100,7 +100,7 @@ Open `claude.ai/code` → environment selector → **+ Add environment**. It has
|
|
|
100
100
|
## In-repo side
|
|
101
101
|
|
|
102
102
|
- `.claude/hooks/bkit-preflight.sh` — the tracker opt-in guard plus the rules-read advisory, as one JSON document (`.bkit/providers.md` § Rules-read advisory). When the tracker issue ID env var is unset, as in an IDE session, it prints the advisory alone and exits 0. On Claude a non-zero exit is informational only, because `SessionStart` cannot block. The agent reads the `HARD STOP` text from `additionalContext`.
|
|
103
|
-
- `.claude/hooks/bkit-cloud-bootstrap.sh` — when `CLAUDE_CODE_REMOTE=true`, runs `pnpm install --frozen-lockfile` and `vale sync`, then gh auth, then context-fetch CLI provisioning through the just-installed bkit (`bkit context provision`). When bkit is missing, it skips provisioning with a loud log line. A failed recipe's `.bkit/.unavailable` line goes to stdout, and so into the session's context. Locally the hook does nothing.
|
|
103
|
+
- `.claude/hooks/bkit-cloud-bootstrap.sh` — when `CLAUDE_CODE_REMOTE=true`, runs `pnpm install --frozen-lockfile` and `vale sync`, then gh auth, then context-fetch CLI provisioning through the just-installed bkit (`bkit context provision`). When bkit is missing, it skips provisioning with a loud log line. A failed recipe's `.bkit/.unavailable` line goes to stdout, and so into the session's context. Locally the hook does nothing. It also compares the `BKIT_CLOUD_ALLOWLIST_FINGERPRINT` env var with the `fingerprint` in `.bkit/allowlist.json` and warns when the variable is unset, malformed or different, or when the expected fingerprint is unavailable, then continues. Each warning is also printed as one line on stdout, so it reaches the session's context; a malformed value is never printed. A match is an operator assertion, so the deployed dashboard list stays unverified. `bkit check` reports `cloud-bootstrap-fingerprint-missing` when an adopted copy never reads the variable.
|
|
104
104
|
- Both are registered in `.claude/settings.json` under `hooks.SessionStart`.
|
|
105
105
|
|
|
106
106
|
These ship with the repo. Do not paste them into the app.
|
|
@@ -120,6 +120,9 @@ Always choose `Custom`, because the rendered list carries bkit's own shipped hos
|
|
|
120
120
|
1. Select **Custom**.
|
|
121
121
|
2. Tick **Also include default list of common package managers**. It extends the trusted defaults (package registries, GitHub, cloud SDKs) and never replaces them.
|
|
122
122
|
3. Paste the domains bkit renders into `.claude/bkit-cloud.md` § Network access into **Allowed domains**.
|
|
123
|
+
4. Set `BKIT_CLOUD_ALLOWLIST_FINGERPRINT` in the environment's variables to the "Allowlist fingerprint" printed under that list. The same value is the `fingerprint` in `.bkit/allowlist.json`. After any `allowed-domains` change, run `bkit upgrade`, re-paste the list and update the variable.
|
|
124
|
+
|
|
125
|
+
The fingerprint covers the whole pasted list, consumer `allowed-domains` included. Every cloud's dashboard list (Claude, Cursor and Codex) is an unverified operator assertion: bkit cannot read it, so a matching stamp proves only that you copied the current value. The Cursor and Codex paste notes print a derived-set stamp only, which ignores consumer `allowed-domains`, so it does not describe the full list those dashboards hold, and no bootstrap compares it.
|
|
123
126
|
|
|
124
127
|
Declare only what bkit cannot see: the log-backend and API hosts that the implicit CLI blocks reach (`vercel` / `gcloud`), plus the app's production and preview / dev domains. Declare apex domains only. `bkit install` expands each one to `<domain>` + `*.<domain>` and unions them with the derived set. Under `Trusted` those hosts are unreachable, so a cloud `/bkit-debug` gets no runtime logs and e2e tests can't reach the deployment.
|
|
125
128
|
|
|
@@ -327,6 +330,13 @@ ChatGPT → **Settings > Codex Cloud > Environments** → **Create environment**
|
|
|
327
330
|
- **Network secrets** (Key / Value / **Allowed domains**): Programs see a placeholder. The proxy substitutes the real value only on requests to allowed domains, during setup and tasks. This fits a token used only in HTTP headers to known hosts, and breaks any token a program reads directly (`gh auth login --with-token`).
|
|
328
331
|
- **Personal vault** shares a secret across **All environments** or **Selected environments**, for a token several repos reuse.
|
|
329
332
|
|
|
333
|
+
## Test slots
|
|
334
|
+
|
|
335
|
+
The tests lock treats a Codex Cloud task as a local run, because no runtime marker names it, so a VM with 8 or more vCPUs gets 2 slots at half width each.
|
|
336
|
+
|
|
337
|
+
- **If** the VM has 8 or more vCPUs → add `BKIT_TEST_SLOTS=1` to **Environment variables**, which gives one slot at full width.
|
|
338
|
+
- **Else** (the standard 2- and 4-vCPU VMs) → add nothing.
|
|
339
|
+
|
|
330
340
|
## Hooks in cloud tasks
|
|
331
341
|
|
|
332
342
|
Repo skills (`.agents/skills/bkit-*`, `$bkit-design`) load in cloud tasks. Codex's cloud docs do not say whether `.codex/hooks.json` runs there, so GateGuard, ReadGuard, guardrails and the rules advisory are unproven in cloud tasks. Review cloud diffs as unguarded. Locally they fire only once the `.codex/` layer is trusted (`.bkit/providers.md` § Codex CLI — three deviations).
|
|
@@ -367,7 +377,7 @@ GitHub dispatch uses the Cursor Automations "Pull request label changed" trigger
|
|
|
367
377
|
|
|
368
378
|
**Trigger flow:**
|
|
369
379
|
|
|
370
|
-
1. `bkit-build` writes `bkit:auto` as a static PR label (the opt-in marker). The matching GitHub issue must also carry `bkit:auto
|
|
380
|
+
1. `bkit-build` writes `bkit:auto` as a static PR label (the opt-in marker). The matching GitHub issue must also carry `bkit:auto`. `.cursor/hooks/bkit-preflight.sh` checks it when a background session starts and blocks that session when the label is absent. Removing the label later does not stop a session that is already running.
|
|
371
381
|
2. The workflow adds the phase label (`bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`) to the PR. Cursor reads the label for workflow dispatch.
|
|
372
382
|
3. Cursor Automations fires on "Pull request label changed" → spawns a Background Agent session against the repo. The Automation's prompt must contain `bkit-auto`, because `AGENTS.md` routes only a `bkit-{command}` prompt, and `.bkit/router.md` reads the phase from the issue's labels.
|
|
373
383
|
4. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, a non-zero exit hard-stops the agent.
|
|
@@ -392,6 +402,37 @@ BKIT_GH_TOKEN=<PAT — fine-grained for one owner, classic across owners; same p
|
|
|
392
402
|
3. `sessionStart` fires `bkit-preflight.sh`. With `failClosed: true`, a non-zero exit hard-stops the agent before work.
|
|
393
403
|
4. Preflight skips IDE sessions (`is_background_agent !== true`), so the local Cursor IDE is unaffected.
|
|
394
404
|
|
|
405
|
+
## Session guard per tracker
|
|
406
|
+
|
|
407
|
+
`.cursor/hooks/bkit-preflight.sh` (Cursor background sessions) and `.claude/hooks/bkit-preflight.sh` (Claude sessions that carry `GITHUB_ISSUE_ID`) share one tracker part, `preflight-tracker.sh`. It checks once, at session start, whether the issue lost `bkit:auto` or is finished, judged by the tracker's state category (the `terminal` fact of `bkit issues fetch`), not by a state name. On Cursor a failed check blocks the session (`failClosed` in `.cursor/hooks.json`). On Claude a SessionStart hook cannot block, so the hook prints a HARD STOP instruction into the agent's context and the agent decides whether to obey:
|
|
408
|
+
|
|
409
|
+
- **GitHub:** the issue's labels and open / closed state.
|
|
410
|
+
- **Linear:** the issue's labels and state type (`completed` or `canceled` is finished). Needs `BKIT_LINEAR_API_KEY`.
|
|
411
|
+
- **Jira:** the issue's labels and status category (`Done` is finished). Needs `BKIT_JIRA_API_KEY`. On Cursor, the guard hard-stops when the `bkit` binary is not present at `sessionStart`.
|
|
412
|
+
|
|
413
|
+
A session that carries no issue id is unguarded: the guard prints a line saying so and exits 0. A `GITHUB_ISSUE_ID` that is not digits only, and a `bkit.tracker.default` that names no tracker bkit knows (for example `GitHub`), fail the guard; `bkit check` reports the unknown name as `tracker-setup-unknown`. Codex Cloud tasks are unguarded, because hooks there are unproven (§ Codex Cloud → Hooks in cloud tasks).
|
|
414
|
+
|
|
415
|
+
**What removing `bkit:auto` stops:**
|
|
416
|
+
|
|
417
|
+
<!-- prettier-ignore -->
|
|
418
|
+
| Place | Effect |
|
|
419
|
+
| --- | --- |
|
|
420
|
+
| `bkit_gate` job in `.github/workflows/bkit-cloud.yml` | Stops. It reads the labels before an agent job starts and starts nothing when `bkit:auto` is absent (`label-absent`). |
|
|
421
|
+
| Session-start hook (`.cursor/hooks/bkit-preflight.sh`) | Cursor background sessions: blocks the session at start. |
|
|
422
|
+
| Session-start hook (`.claude/hooks/bkit-preflight.sh`) | Advises only: the agent is told to stop and can ignore it. |
|
|
423
|
+
| Build Step 16 and debug Step 11, last sub-step | Stops nothing: the label is re-read after the push, when the run is finished, and the final message says the label was removed. |
|
|
424
|
+
| `/bkit-auto` | Never reads the label. |
|
|
425
|
+
|
|
426
|
+
A run that is already working keeps going when the label is removed.
|
|
427
|
+
|
|
428
|
+
## Not yet verified live
|
|
429
|
+
|
|
430
|
+
These paths are built and covered by recorded-reply or fixture tests, and have not run against a live service. Report a failure through `/bkit-debug`:
|
|
431
|
+
|
|
432
|
+
- Linear and Jira router dispatch (the `context` job label read, not yet verified live).
|
|
433
|
+
- The codex router job (`openai/codex-action` dispatch with `BKIT_OPENAI_API_KEY`, not yet verified live).
|
|
434
|
+
- The Cursor Jira guard, with the `bkit` binary present at `sessionStart` (not yet verified live).
|
|
435
|
+
|
|
395
436
|
## Required env vars (Cursor side)
|
|
396
437
|
|
|
397
438
|
Set these in the Cloud Agents dashboard (`cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab) as **Runtime Secret**s (loaded as env vars, redacted from the agent's transcript), not in `.cursor/environment.json`:
|
|
@@ -446,7 +487,7 @@ The rule is the same as for Claude: a per-repo environment with per-repo secrets
|
|
|
446
487
|
|
|
447
488
|
## Cursor — byte-identical Dockerfile
|
|
448
489
|
|
|
449
|
-
Cursor resolves the environment in this order: (1) `.cursor/environment.json` in the repo, (2) a personal saved environment in the Cursor account, (3) a team saved environment.
|
|
490
|
+
Cursor resolves the environment in this order: (1) `.cursor/environment.json` in the repo, (2) a personal saved environment in the Cursor account, (3) a team saved environment. Three sharing patterns exist:
|
|
450
491
|
|
|
451
492
|
1. **In-repo copy (bkit default).** Each consumer repo carries `.cursor/Dockerfile` + `.cursor/environment.json`, copied from bkit's templates and owned by the repo. Cursor environments are functionally equivalent across consumers, and bkit ships base-toolchain updates as template changes the consumer adopts.
|
|
452
493
|
2. **Personal saved environment (cross-repo).** Don't commit `.cursor/environment.json`. Configure a single environment in the Cursor account dashboard, and Cursor falls back to it for any session. Like any cross-repo environment, it holds one secret set for all repos. Prefer the per-repo default (#1) when repos have distinct secrets.
|
|
@@ -479,9 +520,10 @@ The routing logic lives in a single bkit-managed slash-command orchestrator (`.b
|
|
|
479
520
|
<!-- prettier-ignore -->
|
|
480
521
|
| | Lives in the repo (bkit-managed) | Lives in the online dashboard / GitHub (manual, one-time) |
|
|
481
522
|
| --- | --- | --- |
|
|
482
|
-
| **Claude** | `.github/workflows/bkit-cloud.yml` — `claude` job (opt-in via `bkit install --auto=claude`;
|
|
523
|
+
| **Claude** | `.github/workflows/bkit-cloud.yml` — `claude` job (opt-in via `bkit install --auto=claude`; any wired tracker). 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 — the `context` job reads the issue's labels through `bkit issues fetch` on the tracker the repo records and 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 `BKIT_ANTHROPIC_API_KEY` (the same name `.bkit/.env` uses) or keyless federation repo variables (§ Claude — workload identity federation). Claude GitHub App required (`/install-github-app`). The linked tracker issue must carry `bkit:auto`. |
|
|
483
524
|
| **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. |
|
|
484
|
-
| **OpenCode** | Same `.github/workflows/bkit-cloud.yml` — `opencode` job (opt-in via `bkit install --auto=opencode`;
|
|
525
|
+
| **OpenCode** | Same `.github/workflows/bkit-cloud.yml` — `opencode` job (opt-in via `bkit install --auto=opencode`; any wired tracker). 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: the installed provider's `BKIT_` key (`BKIT_OPENCODE_API_KEY`, `BKIT_OPENROUTER_API_KEY` or `BKIT_OLLAMA_API_KEY`). Provider model committed in `.opencode/opencode.json`. The linked tracker issue must carry `bkit:auto`. |
|
|
526
|
+
| **Codex** | Same `.github/workflows/bkit-cloud.yml` — `codex` job (opt-in via `bkit install --auto=codex --codex`; any wired tracker). Same two-tier gate (same file, separate job). Dispatches `/bkit-auto $PHASE $ARG` through `openai/codex-action` with `sandbox: danger-full-access` (the runner is the sandbox) and a codex-home that trusts the workspace. | GitHub repo secret: `BKIT_OPENAI_API_KEY`. The linked tracker issue must carry `bkit:auto`. |
|
|
485
527
|
|
|
486
528
|
**Why the dashboard prompt never needs re-pasting:** Cursor substitutes `$CI_STATUS` and `$PR_NUMBER` from the event payload at dispatch, so the pasted string is generic and timeless. When bkit's routing logic evolves, only the mirrored `.cursor/commands/bkit-auto.md` changes, and the dashboard stays untouched.
|
|
487
529
|
|
|
@@ -505,22 +547,43 @@ Flip the setting on both the org and the repo before the first router run. Other
|
|
|
505
547
|
<!-- prettier-ignore -->
|
|
506
548
|
| Secret / variable | Job | Why | Scope |
|
|
507
549
|
| --- | --- | --- | --- |
|
|
508
|
-
| `
|
|
550
|
+
| `BKIT_ANTHROPIC_API_KEY` secret | `claude` | `claude-code-action` authenticates against Anthropic. | API key with Claude access. Omit when using federation. |
|
|
509
551
|
| `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. |
|
|
510
|
-
| `
|
|
552
|
+
| `BKIT_OPENCODE_API_KEY` / `BKIT_OPENROUTER_API_KEY` / `BKIT_OLLAMA_API_KEY` secret | `opencode` | The job passes each provider key under its own name, so the `.opencode/opencode.json` `{env:VAR}` reference resolves whichever provider is installed. | Set the key of the provider you configured. |
|
|
553
|
+
| `BKIT_OPENAI_API_KEY` secret | `codex` | `openai/codex-action` authenticates against OpenAI. | OpenAI API key. |
|
|
554
|
+
| `BKIT_LINEAR_API_KEY` secret | `context`, agent jobs | The label read and the agent's tracker verbs under `bkit.tracker.default` = `linear`. | Linear API key; step-scoped, never job-wide. |
|
|
555
|
+
| `BKIT_JIRA_API_KEY` secret | `context`, agent jobs | Same, under `bkit.tracker.default` = `jira` (Jira needs the key only; site and email come from `package.json`). | Jira API token; step-scoped. |
|
|
511
556
|
|
|
512
|
-
A `context` job (`Check runner credentials`
|
|
557
|
+
A `context` job (`Check runner credentials` and `Select agent job` steps) checks the credentials and resolves the phase + arg once. It reads the issue id from the branch or commit through `bkit fids parse` and the `bkit:auto` label through `bkit issues fetch`, both from the consumer's own bkit installed from its lockfile, on whichever tracker `bkit.tracker.default` names (GitHub, Linear or Jira). Each runner job needs `context`, and exactly one starts: the one `bkit.cloud.agent` names, when its credential is set.
|
|
513
558
|
|
|
514
|
-
- The Claude credential is `
|
|
515
|
-
-
|
|
516
|
-
-
|
|
517
|
-
-
|
|
559
|
+
- The Claude credential is `BKIT_ANTHROPIC_API_KEY`, or both federation variables. With only one of the two variables set, the job prints a `::notice::` naming the missing one, and the claude job does nothing.
|
|
560
|
+
- Recorded agent `claude`, `opencode` or `codex` with its credential set → only that job runs.
|
|
561
|
+
- Recorded agent with no credential → nothing starts; the log names the missing secret.
|
|
562
|
+
- Recorded agent `cursor` or none → no router job starts.
|
|
563
|
+
- A credential set for another agent is ignored, and the log lists it.
|
|
564
|
+
|
|
565
|
+
The tracker keys are read at step scope, never job-wide. The workflow grants `id-token: write` per job, for claude only (Claude GitHub App + federation token exchange). OpenCode and Codex have no OIDC.
|
|
566
|
+
|
|
567
|
+
**Codex runner notes:** the `drop-sudo` step in `openai/codex-action` is irreversible, so a reused self-hosted runner loses sudo for later jobs: use an ephemeral runner. The action puts its own Node 24 on PATH. The job runs unguarded diffs (`sandbox: danger-full-access`), because the runner is the sandbox and the phase needs git, network and the repo's dependencies. Repo dependencies install before the action.
|
|
568
|
+
|
|
569
|
+
**Gate outcomes (log and job summary):** the `context` job writes one `### bkit-cloud gate` row (`tracker | issue | verdict | reason | jobs`) and a log line. Every unreadable outcome starts no agent and exits green.
|
|
570
|
+
|
|
571
|
+
<!-- prettier-ignore -->
|
|
572
|
+
| Verdict / reason | Cause | Action |
|
|
573
|
+
| --- | --- | --- |
|
|
574
|
+
| `pass` | The issue carries `bkit:auto`. | None. |
|
|
575
|
+
| `label-absent` | The issue lost `bkit:auto` (kill switch). | Re-add the label to resume. |
|
|
576
|
+
| `no-issue` | No tracker issue is recorded for the run. | Link the issue (`bkit:fid=` marker or branch FID). |
|
|
577
|
+
| `no-agent` | `bkit.cloud.agent` names no router job, or its credential is missing; the `jobs` column names the missing secret. | Set the named `BKIT_` secret, or run `bkit install --auto=<agent>`. |
|
|
578
|
+
| `unreadable` `bkit-unavailable` | `node_modules/.bin/bkit` is absent: the lockfile install failed. | Fix the install step. |
|
|
579
|
+
| `unreadable` `reason=auth` | The tracker refused the read; the line names the secret (`BKIT_LINEAR_API_KEY`, `BKIT_JIRA_API_KEY` or `GH_TOKEN`) and whether it is set. | Rotate or set that secret. |
|
|
580
|
+
| `unreadable` `reason=<other>` / `exit-<N>` / `output-unparseable` | Service down, issue not found, or output the router cannot parse. | Re-run once the tracker answers. |
|
|
518
581
|
|
|
519
|
-
|
|
582
|
+
The codex job writes a `### bkit-cloud codex` summary row: the action outcome, commits and comments landed since it started (`-` when unknown).
|
|
520
583
|
|
|
521
584
|
## Claude — workload identity federation
|
|
522
585
|
|
|
523
|
-
The keyless claude job stores no long-lived `
|
|
586
|
+
The keyless claude job stores no long-lived `BKIT_ANTHROPIC_API_KEY` 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 and returns a short-lived Claude API token. The action refreshes it in the background on long runs.
|
|
524
587
|
|
|
525
588
|
**Setup (one-time):**
|
|
526
589
|
|
|
@@ -535,7 +598,7 @@ The keyless claude job stores no long-lived `ANTHROPIC_API_KEY` in GitHub. `clau
|
|
|
535
598
|
gh variable set ANTHROPIC_ORGANIZATION_ID --body='<organization-uuid>'
|
|
536
599
|
# optional: ANTHROPIC_SERVICE_ACCOUNT_ID (svac_...), ANTHROPIC_WORKSPACE_ID
|
|
537
600
|
```
|
|
538
|
-
4. Delete the key if one is set: `gh secret delete
|
|
601
|
+
4. Delete the key if one is set: `gh secret delete BKIT_ANTHROPIC_API_KEY`. **A set key wins over federation:** the action uses the key, and federation never runs. `bkit check` flags both being set (`anthropic-api-key-shadows-federation`).
|
|
539
602
|
|
|
540
603
|
**Adopted copy predates federation:** The variables are set, but `.github/workflows/bkit-cloud.yml` lacks the `anthropic_federation_rule_id:` input, so the claude job sees no credential. `bkit check` flags it (`anthropic-federation-template-stale`). Re-copy from `.bkit/templates/.github/workflows/bkit-cloud.yml`, then re-apply your local edits (`runs-on`).
|
|
541
604
|
|
|
@@ -569,8 +632,8 @@ The slash command takes two args: `$CI_STATUS` in `success|failure|pass|fail` (n
|
|
|
569
632
|
1. With a PR-number arg, it reads `gh pr view $ARG` for `headRefName`, `headRefOid`, `state`, and refuses non-open PRs. With a slug arg, it skips the PR lookup entirely.
|
|
570
633
|
2. It extracts `{FID}` from the head branch (`feat/{FID}` convention). With a slug arg, `{ARG}` is the `{FID}`, allowlist-asserted before use. On the `dev` surface the workflow recovers it from the squash-merge commit scope (`feat({FID}): …`, tracker-agnostic), and falls back to the linked PR body's `bkit:fid=` marker. If either path fails → no-op, no dispatch.
|
|
571
634
|
3. Stale-run guard. Pre-merge, it compares the latest CI run's `headSha` against the PR's current `headRefOid`. Post-merge on `dev`, it compares the most recently completed `dev` CI run's `headSha` against the triggering run's head SHA. A `git rev-parse origin/dev` comparison would mismatch on every legitimate dispatch, because ship's terminal close commit lands on `dev` while that CI run is still going. Close commits carry `[skip ci]`, so they never trigger CI and never become that most-recent-completed head. An empty run list fails open (dispatches).
|
|
572
|
-
4. Opt-in gate:
|
|
573
|
-
5. It appends a `bkit-auto → /bkit-{ship,debug}` line to the
|
|
635
|
+
4. Opt-in gate: not checked in this file. The `bkit_gate` job in `bkit-cloud.yml` reads the `bkit:auto` label of the linked tracker issue (GitHub, Linear or Jira) before the router job starts, and starts nothing when it is absent.
|
|
636
|
+
5. It appends a `bkit-auto → /bkit-{ship,debug}` line to the issue / PR comment thread.
|
|
574
637
|
6. It invokes `/bkit-ship {FID}` (CI pass) or `/bkit-debug {FID} DEBUG_MODE=pr` (CI fail) through the `Skill` / `Task` tool. The dispatched skill owns the session lifecycle from there.
|
|
575
638
|
|
|
576
639
|
Skip conditions emit a single GitHub-comment no-op line and exit 0. Only real failures (missing args, GitHub API unreachable, malformed state) take the Failure Path.
|
|
@@ -585,8 +648,8 @@ Skip conditions emit a single GitHub-comment no-op line and exit 0. Only real fa
|
|
|
585
648
|
- The counter row (`type: "dev-dispatch"`) is committed to `dev` with `[skip ci]` before dispatch, and its presence on `origin/dev` is verified after one retry. A row that lands nowhere durable would make the cap unbounded.
|
|
586
649
|
- When the cap is used up → no-op + `::notice::` for operator review. Delete the rows in `status.jsonl` to reset it.
|
|
587
650
|
- **GitHub Actions runtime limit:** The host's job limit still applies. bkit bounds attempts and command waits, and sets no universal workflow-step deadline; the attempt count alone does not bound the job's duration.
|
|
588
|
-
- **Concurrency:** `cancel-in-progress` is `true` for `feat/**`
|
|
589
|
-
- **`bkit-auto-dev` is one concurrency group for all FIDs.** GHA resolves `concurrency.group` from the trigger-payload context before the ctx step derives the `{FID}`, so the group cannot be keyed on it. When two different FIDs fail `dev` CI near-simultaneously,
|
|
651
|
+
- **Concurrency:** `cancel-in-progress` is `true` for `feat/**` and `false` for `dev`, at the workflow level and on the Codex job. On `feat/**` a newer run replaces the one in flight (latest wins), so one branch never has two runs working and pushing at once. On `dev` a run in flight finishes, so an in-flight `/bkit-debug` is never cancelled mid-run with a half-written `status.jsonl` or a held worktree lock; GHA keeps at most one pending run per group, a newer pending run drops an older one, and the queued run's ctx step re-checks staleness and the dispatch cap when it starts, so the same `{FID}` needs no manual re-trigger. A run that will do nothing (a fork, a cancelled or skipped CI run, a commit without `bkit [auto route]`, a green `dev` run) gets its own `skip-{run id}` group, so it never queues behind or displaces a working run. The Cursor dashboard trigger is "latest-supersedes." The ship squash-merge is atomic, so mid-run cancels cannot corrupt PR state.
|
|
652
|
+
- **`bkit-auto-dev` is one concurrency group for all FIDs.** GHA resolves `concurrency.group` from the trigger-payload context before the ctx step derives the `{FID}`, so the group cannot be keyed on it. When two different FIDs fail `dev` CI near-simultaneously, the newer pending run replaces the older, different FID's pending run. The stale-run guard detects it (its head SHA no longer matches the most-recent-completed `dev` CI run) and writes a `dev-dispatch-dropped` row to the job summary plus a `::warning::`, rather than discarding it silently. The row goes to the job summary, not a committed `status.jsonl`, because this branch is reached only when `dev` has already advanced. Committing the row would usually be a non-fast-forward, and the row would be lost in exactly the case it records.
|
|
590
653
|
- **Both clouds together:** Nothing stops Claude + Cursor from dispatching against the same PR, and they would race. Pick one IDE per repo as the auto-router. The recommendation is Claude via GHA, which is runner-resident and Anthropic-maintained. Leave Cursor for ad-hoc Linear-dispatch work.
|
|
591
654
|
|
|
592
655
|
# Caveats (both clouds)
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
|
|
17
17
|
## Quick install / upgrade — paste into your AI
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Two paste blocks follow: install (first time) and upgrade (already on bkit). Both end the same way: apply advisories, reconcile templates, and verify with `bkit check`.
|
|
20
20
|
|
|
21
21
|
### Install — first time
|
|
22
22
|
|
|
@@ -117,7 +117,7 @@ bkit check
|
|
|
117
117
|
- The CI workflow, the Vale config, the tool configs, the git hooks, the slop-scan type-suppression plugin (`scripts/slop/bkit-slop-type-suppression.mjs`), and the tool `package.json` scripts and devDeps are templates you copy from `.bkit/templates/` (`.bkit/templates.md`).
|
|
118
118
|
- Core, implicit on every install, seeds the `bkit:gate:*` / `bkit:deps:*` scripts every workflow runs. It adds them only if missing, and never touches a name that is already present. Point their values at your stack (see `.bkit/README.md` § Required tools).
|
|
119
119
|
|
|
120
|
-
**Opt-in flags:** `--tracker=github|linear|jira`, `--auto=claude|cursor
|
|
120
|
+
**Opt-in flags:** `--tracker=github|linear|jira`, `--auto=claude|opencode|codex|cursor` (cloud agents), `--opencode=<provider>` (additive OpenCode execution host: `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). For dependency updaters, copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
|
|
121
121
|
|
|
122
122
|
### Payload view links — `.bkit/core` + `.bkit/shared`
|
|
123
123
|
|
|
@@ -132,7 +132,7 @@ Install and upgrade create two relative symlinks into the installed package, so
|
|
|
132
132
|
|
|
133
133
|
### Local env setup
|
|
134
134
|
|
|
135
|
-
|
|
135
|
+
Two flows exist. Pick one. Both put `BKIT_GH_TOKEN` in the shell for the GitHub MCP server. Linear repos also need `BKIT_LINEAR_API_KEY`, and Jira repos need `BKIT_JIRA_API_KEY` (`.bkit/trackers.md` § jira — setup and notes). Use `gh auth login` for the CLI.
|
|
136
136
|
|
|
137
137
|
#### Flow A — Shell export (quickest, no extra deps)
|
|
138
138
|
|
|
@@ -187,13 +187,14 @@ bkit ships repo-side scaffolding for both cloud agents:
|
|
|
187
187
|
|
|
188
188
|
You configure the online-dashboard half (the Claude env in `claude.ai/code`, the Cursor env vars in `Cursor → Settings → Background Agents`) once per machine / account.
|
|
189
189
|
|
|
190
|
-
For post-CI auto-routing (ship-vs-debug after CI), bkit ships a single `.github/workflows/bkit-cloud.yml` template with
|
|
190
|
+
For post-CI auto-routing (ship-vs-debug after CI), bkit ships a single `.github/workflows/bkit-cloud.yml` template with one dispatch job per router agent, plus a `/bkit-auto` slash command that every cloud invokes from a single source. Only the job `bkit.cloud.agent` names starts, and only when its credential is set. The gate reads the `bkit:auto` label on the tracker the repo records (GitHub, Linear or Jira):
|
|
191
191
|
|
|
192
|
-
- The **claude** job (`claude-code-action`) runs when the `
|
|
193
|
-
- The **OpenCode** job (`opencode run` CLI) runs when `
|
|
192
|
+
- The **claude** job (`claude-code-action`) runs when the `BKIT_ANTHROPIC_API_KEY` repo secret is set, or keyless through the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables.
|
|
193
|
+
- The **OpenCode** job (`opencode run` CLI) runs when the installed provider's `BKIT_` key is set.
|
|
194
|
+
- The **codex** job (`openai/codex-action`) runs when `BKIT_OPENAI_API_KEY` is set.
|
|
194
195
|
- Cursor wires the slash command through a dashboard trigger, with no GHA on the Cursor side.
|
|
195
196
|
|
|
196
|
-
|
|
197
|
+
Every `--auto` variant works with GitHub, Linear or Jira as the tracker; only `tracker=none` refuses.
|
|
197
198
|
|
|
198
199
|
`.bkit/cloud.md` holds the full recipe, the paste-in setup script, the env-var inventory, the Cursor dashboard config and the consumer customisation patterns. The host-delta matrix is in `.bkit/providers.md` § Runtime environment.
|
|
199
200
|
|
|
@@ -220,6 +221,7 @@ In this example, `hooks.SessionStart` is bkit-declared scope (from the template)
|
|
|
220
221
|
|
|
221
222
|
- Consumer keys outside the template tree survive every `bkit install` byte-identically.
|
|
222
223
|
- `bkit install` uses `deepContains(template, consumer)`, which checks that every template leaf is present. On drift, it deep-merges with the template winning, and consumer-only siblings are preserved.
|
|
224
|
+
- Lists merge too. A list of plain values (such as `permissions.allow`) keeps the template's entries in template order, then appends consumer-only entries. A list of objects (hook groups) replaces a consumer group that holds a hook `command` the template group also holds, and keeps every other consumer group after the template's groups. A second install is a no-op.
|
|
223
225
|
- `bkit check` surfaces the `tier2-json-drift` advisory when `deepContains` fails, and exits 1 (CI drift gate). It writes nothing. The consumer reviews and re-runs `bkit install` to reconverge.
|
|
224
226
|
- `.cursor/hooks.json` uses Cursor v1 keyed-object schema: `{"version": 1, "hooks": {"sessionStart": [...], "sessionStop": [...]}}`.
|
|
225
227
|
|
|
@@ -252,7 +254,7 @@ After the writes, bkit re-runs the credential and environment checks, because so
|
|
|
252
254
|
| --- | --- |
|
|
253
255
|
| `bkit-managed-duplicate` | A managed markdown file holds an older unmarked copy of its block outside `bkit:start`/`bkit:end`: the block's `# ` title plus 10+ of its long lines verbatim, fenced code ignored. Install never updates that copy. Names each file and title line; delete the copy. |
|
|
254
256
|
| `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset / empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
|
|
255
|
-
| `tracker-setup-none` / `-github` / `-linear` / `-jira` | Optional post-install decision — which issue tracker is wired (`bkit.tracker.default`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
257
|
+
| `tracker-setup-none` / `-github` / `-linear` / `-jira` / `-unknown` | Optional post-install decision — which issue tracker is wired (`bkit.tracker.default`). `none` nudges `bkit install --tracker=…`. `-unknown` is a blocker: the value names no tracker bkit knows (for example `GitHub`), and the session-start tracker guard fails on it. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
256
258
|
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.tracker.github.project` empty, absent or not a board URL, and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.tracker.github.project: false`. |
|
|
257
259
|
| `github-project-token-scope` | A board is configured but `BKIT_GH_TOKEN` cannot reach it: a classic token lacks the `project` scope, or a fine-grained token's board query returns nothing. Board moves fall back to the MCP. Checked live via `gh`; skipped on cloud / CI. |
|
|
258
260
|
| `dep-updater-absent` | No Renovate or Dependabot config. Copy one example and own it. `bkit.dependencies.updater: "none"` silences this. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
@@ -287,7 +289,7 @@ Phase 1 and Phase 3 findings are merged and deduplicated by `id`. Phase 3 wins o
|
|
|
287
289
|
The gate covers the installed module set ({core, claude, cursor, codex, antigravity} plus OpenCode). Each module is detected by sentinel files: for a host, its `agents/` dir, and for antigravity, any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host. `bkit status` uses the same detection.
|
|
288
290
|
|
|
289
291
|
- **antigravity gated:** `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and the root `GEMINI.md`.
|
|
290
|
-
- **OpenCode gated:** Drift in `.opencode/opencode.json` (the provider block + the recorded tracker's `mcp` entry + the permission sandbox) and in the `bkit-gateguard.js` / `bkit-readguard.js` / `bkit-rules.js` plugins fails `check`.
|
|
292
|
+
- **OpenCode gated:** Drift in `.opencode/opencode.json` (the provider block + the recorded tracker's `mcp` entry + the permission sandbox) and in the `bkit-gateguard.js` / `bkit-guardrails.js` / `bkit-readguard.js` / `bkit-rules.js` plugins fails `check`.
|
|
291
293
|
- Another tracker's `mcp` entry that the consumer edited, kept by a tracker switch, is not drift. `mcp-extra-server-linear--opencode-opencode-json` advises removing it.
|
|
292
294
|
- Render inputs fall back to the installed provider (`package.json` `bkit.providers.opencode.default`, authoritative for `opencode-zen` / `opencode-go`; all installed providers are tracked in `bkit.providers.opencode.installed: string[]`) and the recorded tracker, so a clean install across providers checks green, with no false drift.
|
|
293
295
|
- The remaining opt-in module (cloud) is not drift-gated.
|
|
@@ -329,6 +331,10 @@ Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` line
|
|
|
329
331
|
| Visibility | The console banner and `.bkit/advisories.md` carry one suppressed-advisory line per dismissal (`N advisory` / `N advisories`), so a stale opt-out cannot hide a finding silently. |
|
|
330
332
|
| Coverage | Per package: `tagged-tests-no-ci-home` and `test-integration-env-not-asserted`. Repo root: every setup tip id and every advisory a tip reuses (§ Setup tips). No other advisory is suppressible; an id matching no advisory or tip is ignored. |
|
|
331
333
|
|
|
334
|
+
## Project document ownership
|
|
335
|
+
|
|
336
|
+
Project docs (`docs/{architecture,technology,security,data-schema,testing,deployments,observability,design,noise,setup}.md`) belong to the project. Install and upgrade never write them except to strip the old `bkit:start` / `bkit:end` wrapper and `bkit:managed` notice from a copy a pre-6.2 release made, then register present docs in `.agents/docs.md` `## Project Documents`. Ambiguous wrappers are kept and reported. Uninstall leaves the docs and their index rows alone. The starters live in `.bkit/templates/docs/`; see `.bkit/templates.md` § Project documents.
|
|
337
|
+
|
|
332
338
|
## Optional post-install decisions
|
|
333
339
|
|
|
334
340
|
Two capabilities are opt-in, and a plain host / tooling install never wires them. The default install never enables them, and the post-install advisory banner nudges you to choose, once. Each choice is recorded in `package.json` (`bkit.tracker.default`, `bkit.cloud.agent`), so the nudge knows whether you've decided or deliberately opted out.
|
|
@@ -337,7 +343,7 @@ Two capabilities are opt-in, and a plain host / tooling install never wires them
|
|
|
337
343
|
| Decision | Default | Opt-in command | Advisory when unset |
|
|
338
344
|
| --- | --- | --- | --- |
|
|
339
345
|
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (`BKIT_GH_TOKEN`) `--tracker=linear` (`BKIT_LINEAR_API_KEY`) or `--tracker=jira` (`BKIT_JIRA_API_KEY` + `bkit.tracker.jira.site` / `bkit.tracker.jira.project`) | `tracker-setup-none` |
|
|
340
|
-
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor
|
|
346
|
+
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|opencode\|codex\|cursor` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude, OpenCode and codex jobs; the recorded agent's job runs when its secret is set) and the Cursor Dockerfile/environment.json | `cloud-router-none` |
|
|
341
347
|
|
|
342
348
|
**Dependency updater.** Copy one example and own it.
|
|
343
349
|
|
|
@@ -350,7 +356,7 @@ Two capabilities are opt-in, and a plain host / tooling install never wires them
|
|
|
350
356
|
|
|
351
357
|
Use one, and record it in `bkit.dependencies.updater` (`"renovate"` / `"dependabot"`). Install and upgrade fill an empty value from the config present. `"none"` skips the install-time absence advisory. `bkit check` emits `dep-updater-absent` and `dep-updater-both`, and blocks on `dep-updater-unset` / `dep-updater-mismatch` when the value and the configs disagree. Setup: `docs/deployments.md` § Dependency updaters.
|
|
352
358
|
|
|
353
|
-
**Security scan.** An updater only offers fixes once a fixed release exists. To fail CI on known-vulnerable packages, risky config or committed secrets, copy `.bkit/templates/.github/workflows/bkit-trivy.yml` and own it. It also runs daily, and you accept findings in `.trivyignore.yaml`.
|
|
359
|
+
**Security scan.** An updater only offers fixes once a fixed release exists. To fail CI on known-vulnerable packages, risky config or committed secrets, copy `.bkit/templates/.github/workflows/bkit-trivy.yml` and own it. It also runs daily, and you accept findings in `.trivyignore.yaml`. bkit has no advisory for it, and `bkit tips` suggests it. Setup: `.bkit/templates.md` § Trivy.
|
|
354
360
|
|
|
355
361
|
**Test lint.** In JS / TS repos, to fail `lint` on a test that cannot fail (no assertion, a branch inside a test, an unawaited promise):
|
|
356
362
|
|
|
@@ -358,7 +364,7 @@ Use one, and record it in `bkit.dependencies.updater` (`"renovate"` / `"dependab
|
|
|
358
364
|
2. Add `oxlint` + `oxlint-tsgolint`.
|
|
359
365
|
3. Set `lint` to `oxlint -c .oxlintrc.json --type-aware --deny-warnings`.
|
|
360
366
|
|
|
361
|
-
|
|
367
|
+
bkit has no advisory for it, and `bkit tips` suggests it. Setup: `.bkit/templates.md` § Oxlint.
|
|
362
368
|
|
|
363
369
|
**All templates.** You copy and own them, and they are never installed. Catalog and install steps: `.bkit/templates.md`.
|
|
364
370
|
|
|
@@ -366,8 +372,8 @@ There is no advisory, and `bkit tips` suggests it. Setup: `.bkit/templates.md`
|
|
|
366
372
|
|
|
367
373
|
- **Tracker** wires real credentials and MCP servers into workflows, so the consumer must choose the provider. bkit can't guess.
|
|
368
374
|
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template plus the cloud env scaffolding (`.claude/hooks/bkit-cloud-bootstrap.sh`, and the `.cursor/Dockerfile` + `.cursor/environment.json` templates). The template auto-dispatches bkit-ship on CI pass and bkit-debug on CI fail, and runs design / plan / build only through `workflow_dispatch`.
|
|
369
|
-
- The workflow carries a claude
|
|
370
|
-
-
|
|
375
|
+
- The workflow carries a claude, an OpenCode and a codex job. Only the recorded agent's job starts, and it is inert without its key. claude needs the `BKIT_ANTHROPIC_API_KEY` repo secret or the federation repo variables (+ the Claude GitHub App). OpenCode needs its provider's `BKIT_` key. codex needs `BKIT_OPENAI_API_KEY`.
|
|
376
|
+
- Each needs GitHub Actions write permissions and a wired tracker (GitHub, Linear or Jira, with its `BKIT_` key under Linear / Jira); Cursor needs a dashboard trigger. The tracker itself is opt-in.
|
|
371
377
|
- The env scaffolding is inert until the Claude / Cursor cloud env is wired in the dashboard.
|
|
372
378
|
- Autonomous routing by default, wired to an unconfigured tracker, is the wrong default, so an install without `--auto` ships zero cloud footprint.
|
|
373
379
|
|
|
@@ -376,13 +382,46 @@ There is no advisory, and `bkit tips` suggests it. Setup: `.bkit/templates.md`
|
|
|
376
382
|
1. Run `bkit install --claude --cursor` (or whichever modules you want). If you have not decided yet, the post-install banner lists `tracker-setup-none`, `dep-updater-absent` and `cloud-router-none`.
|
|
377
383
|
2. Pick a tracker: `bkit install --tracker=github` (or `linear` / `jira`). It needs no host flag, and it re-renders every installed host. The choice is persisted to `bkit.tracker.default`, and future installs preserve it (switching is free).
|
|
378
384
|
3. Copy one updater example (table above). Land the Renovate config on the default branch before installing the App. The next `bkit install` / `bkit upgrade` sets `bkit.dependencies.updater` to it.
|
|
379
|
-
4. Enable cloud agents: `bkit install --auto=claude|cursor
|
|
385
|
+
4. Enable cloud agents: `bkit install --auto=claude|opencode|codex|cursor` (codex also needs `--codex`). The choice is persisted to `bkit.cloud.agent`, and install prints the secrets + permissions + dashboard checklist (`bkit-auto-setup`). The shipped `bkit-cloud.yml` carries a claude job (`BKIT_ANTHROPIC_API_KEY` repo secret or federation repo variables, see `.bkit/cloud.md` § Claude — workload identity federation), an OpenCode job (the provider's `BKIT_` key) and a codex job (`BKIT_OPENAI_API_KEY`); only the recorded agent's job starts.
|
|
380
386
|
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.tracker.default` / `bkit.dependencies.updater` / `bkit.cloud.agent`). The advisory then stays quiet. The `""` that install seeds means undecided, and keeps the nudge.
|
|
381
387
|
|
|
382
388
|
To reverse the tracker or cloud-agent choice, re-run install with the other flag. Updater files stay until you delete them.
|
|
383
389
|
|
|
384
390
|
**GitHub notifications.** bkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".
|
|
385
391
|
|
|
392
|
+
## Agent hosts and remote access
|
|
393
|
+
|
|
394
|
+
Run each host (`claude`, `codex`, `opencode`) in its own terminal window, not inside an IDE or a desktop app.
|
|
395
|
+
|
|
396
|
+
- Separate processes let you restart one host without quitting the others.
|
|
397
|
+
- Terminal sessions inherit the direnv-loaded `.bkit/.env`. GUI-launched apps do not (`.bkit/providers.md` § macOS GUI-isolation).
|
|
398
|
+
- On macOS, use [Ghostty](https://ghostty.org).
|
|
399
|
+
|
|
400
|
+
### Remote access
|
|
401
|
+
|
|
402
|
+
This section matters mostly for OpenCode, because Claude / Codex / Cursor ship their own mobile / desktop clients. Reach an OpenCode host terminal from another device over a private mesh VPN. Suggested services:
|
|
403
|
+
|
|
404
|
+
- [Tailscale](https://tailscale.com/), a mesh VPN. Its free Personal plan covers device-to-device access.
|
|
405
|
+
- [OpenLens](https://apps.apple.com/us/app/openlens-opencode-client/id6759910797), an OpenCode iOS client.
|
|
406
|
+
|
|
407
|
+
Set it up as follows:
|
|
408
|
+
|
|
409
|
+
- Bind:
|
|
410
|
+
- Run `opencode service set hostname 0.0.0.0` for all interfaces, or set the tailnet IP for tailnet only.
|
|
411
|
+
- Run `opencode service set port <port>`.
|
|
412
|
+
- Run `opencode service start` to apply.
|
|
413
|
+
- The loopback-only default keeps the service off the LAN. Tailnet ACLs still apply.
|
|
414
|
+
- HTTPS proxy: `tailscale serve --bg <port>` serves the port at `https://<host>.<tailnet>.ts.net`.
|
|
415
|
+
- It requires tailnet HTTPS certificates to be enabled (on the DNS page).
|
|
416
|
+
- It publishes machine names to the certificate-transparency log (free).
|
|
417
|
+
- Auth: HTTP Basic, with username `opencode`.
|
|
418
|
+
- The password is in `~/.config/opencode/service.json`, mirrored at `~/.local/state/opencode/service.json`. It persists across restarts.
|
|
419
|
+
- Run `opencode service set password <value>` to rotate it.
|
|
420
|
+
- NEVER commit the password.
|
|
421
|
+
- Client CLI: `OPENCODE_PASSWORD=<password> opencode --server https://<host>.<tailnet>.ts.net`.
|
|
422
|
+
- Browser / app pairing: `opencode pair --url https://<host>.<tailnet>.ts.net` returns a one-time link with a 5-minute expiry.
|
|
423
|
+
- Pin the port. The service port is dynamic, but `serve` targets a fixed port, so pin it or the proxy breaks on restart.
|
|
424
|
+
|
|
386
425
|
## Setup tips
|
|
387
426
|
|
|
388
427
|
`bkit tips` prints what the repo has not set up yet — tracker, tokens, templates, cost settings — most useful first, each with a plain-English line and a sentence to ask your agent. Each workflow runs it with its own name at its close and appends what it prints under `## bkit Tips`; `@bkit-audit-generate` does the same with `audit`, and every `@bkit-utility-update-*` agent with `utility`.
|
|
@@ -416,7 +455,7 @@ bkit doctor
|
|
|
416
455
|
|
|
417
456
|
Use `bkit doctor` to:
|
|
418
457
|
|
|
419
|
-
- Check that `BKIT_GH_TOKEN` is present in the shell (GitHub MCP auth), and check the cloud-router
|
|
458
|
+
- Check that `BKIT_GH_TOKEN` is present in the shell (GitHub MCP auth), and check the cloud-router credential of the recorded agent (claude: `BKIT_ANTHROPIC_API_KEY` repo secret or federation repo variables; opencode: a provider `BKIT_` key; codex: `BKIT_OPENAI_API_KEY`). It also flags a key shadowing federation, a secret still under its old name, and an adopted `bkit-cloud.yml` older than the shipped router.
|
|
420
459
|
- Surface the `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
|
|
421
460
|
- Preview all the advisories `bkit install` would show after install, without triggering writes.
|
|
422
461
|
- Verify the environment is ready before `bkit install` on a new machine.
|
|
@@ -59,7 +59,7 @@ for name in ["decisions", "knowledge"]:
|
|
|
59
59
|
|
|
60
60
|
## Write Idiom
|
|
61
61
|
|
|
62
|
-
**Engine and workflow writers:** `bkit ledgers append --ledger=<decisions|deferrals|failures|knowledge|friction|stats> --rows=<file|->`. The rows are a JSON array without `schema` / `ts` / `bkit`.
|
|
62
|
+
**Engine and workflow writers:** `bkit ledgers append --ledger=<decisions|deferrals|failures|knowledge|friction|stats> --rows=<file|->`. The rows are a JSON array without `schema` / `ts` / `bkit`. Add `--operation=<id>` to name the request: the same id with the same rows returns the original `receipt` (`offset`, `bytes`, each row's `key` and `ts`, `replayed: true`) and writes nothing, the same id with other rows is refused, and a new id on an existing `key` is a deliberate later update with its own lineage. A lost response is retried with the same id; an append that left a partial write exits non-zero as uncertain and truncates nothing. Every append, compact and union holds the ledger's `<file>.bkit-lock`; a lock that does not release is reported, never reclaimed.
|
|
63
63
|
|
|
64
64
|
- **Fills:** `schema: 3`, a minted `ts` per row, `repo` when absent, and `bkit.version` from `.bkit/version`. On `deferral` / `failure` / `knowledge` / `decision` rows, it also fills `firstTs` and `updates` from the entry's earlier rows (§ Compaction), replacing any supplied values.
|
|
65
65
|
- **Checks** every row before writing any: validation, and the author against § Ledgers & Writers. One refused row → exit 8, and nothing is written.
|
|
@@ -95,7 +95,7 @@ Each `kind` goes to one file. Its writers:
|
|
|
95
95
|
| `friction` | `.bkit/friction.jsonl` | orchestrator workflows (design / plan / build / debug / ship / auto) on observed friction; utility orchestrator (a direct chat outside any workflow that meets friction); the engine itself, as the active workflow, on a bkit command's undeclared non-zero exit (`category: "tool-failure"`, `scope: "bkit-repo"`, in the active run's own book root; `BKIT_ENGINE_JOURNAL=off` disables it), and from `status row --type=owner-pause` on each owner pause (`category: "human-confirm"`, same book root and kill switch) |
|
|
96
96
|
| `deferral` | `docs/deferrals.jsonl` | `@bkit-design-generate`, `@bkit-plan-generate`, `@bkit-plan-update`, `@bkit-debug-abort-handover`, `@bkit-ship-deferred-sweep` (adjudication only), `@bkit-utility-update-deferrals` (close / triage / locator), build orchestrator (`LOW` challenge finding → `low-severity`, through `bkit challenge merge`), ship orchestrator (assumed accept nobody confirmed → `needs-decision`, through `bkit decisions pending --defer`), utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
|
|
97
97
|
| `failure` | `docs/failures.jsonl` | any agent on a discovered bug; `@bkit-debug-abort-handover`; `@bkit-audit-generate` (`MEDIUM`+ findings; rerun closes rows it no longer finds); `@bkit-utility-update-failures` (close / triage / locator) |
|
|
98
|
-
| `knowledge` | `docs/knowledge.jsonl` | `@bkit-build-plan-tests`, `@bkit-build-plan-tasks`, `@bkit-build-plan-gaps-remediate`, `@bkit-debug-failure-remediate` (after verified fix), `@bkit-utility-update-knowledge` (supersede / correct)
|
|
98
|
+
| `knowledge` | `docs/knowledge.jsonl` | any agent on a discovered gotcha; `@bkit-build-plan-tests`, `@bkit-build-plan-tasks`, `@bkit-build-plan-gaps-remediate`, `@bkit-debug-failure-remediate` (after verified fix), `@bkit-utility-update-knowledge` (supersede / correct) |
|
|
99
99
|
| `decision` | `docs/decisions.jsonl` | `@bkit-debug-failure-remediate` (forced arch), `@bkit-plan-generate`, `@bkit-plan-update` (decision changed by review), `@bkit-utility-update-decisions` (supersede / correct), build orchestrator (Decision Pause accept), design orchestrator (owner's answer to an open question after close), plan orchestrator (open question answered after close), ship orchestrator (assumed accept confirmed by the owner, through `bkit decisions apply --by=owner`), utility orchestrator (a direct chat outside any workflow, the owner deciding in it); orchestrators ONLY after explicit human approval |
|
|
100
100
|
| `feature` | `.bkit/issues.jsonl` | design / plan / build / debug orchestrators at their phase close; ship Step 6 into the worktree ledger (rides the PR); `ABANDONED` only by a human, or an agent on explicit human instruction |
|
|
101
101
|
|
|
@@ -118,7 +118,7 @@ Every row opens with the same top section, in this order:
|
|
|
118
118
|
| `key` | `string?` | Keyed kinds only (`friction` / `deferral` / `failure` / `knowledge` / `decision` / `feature` / `chat` / `run`). See § Key & References. |
|
|
119
119
|
| `repo` | `string` | Origin repo slug, e.g. `cbartens/bkit`; its fingerprint on `chat` / `run` rows (§ Per-Kind Fields). |
|
|
120
120
|
| `bkit` | `{version}` | `version` = bkit version that emitted the row (`null` on `chat` / `run` when none found). `chat` adds its bkit-use fields. |
|
|
121
|
-
| `by` | `{workflow?, step, subagent?, model?}` | Who wrote it — § Who Wrote It. `workflow`: `design` / `plan` / `build` / `debug` / `ship` / `auto` / `audit`; `utility` for a direct chat outside any workflow; `chat-stats` on `chat` (the harvest script's scan); the run's workflow on `run`. |
|
|
121
|
+
| `by` | `{workflow?, step, subagent?, model?, modelSource?, configuredModel?, host?}` | Who wrote it — § Who Wrote It. `workflow`: `design` / `plan` / `build` / `debug` / `ship` / `auto` / `audit`; `utility` for a direct chat outside any workflow; `chat-stats` on `chat` (the harvest script's scan); the run's workflow on `run`. |
|
|
122
122
|
| `references` | `string[]?` | Pointers that place the row: feature ids, tracker ids, PRs, commit SHAs, paths, a sibling `ts`. See § Key & References. |
|
|
123
123
|
|
|
124
124
|
Values in every kind:
|
|
@@ -165,7 +165,7 @@ These blocks have the same name and the same shape on `outcome` and `run`:
|
|
|
165
165
|
| Row written by | `by.workflow` | `by.step` | `by.subagent` | `by.model` |
|
|
166
166
|
| --- | --- | --- | --- | --- |
|
|
167
167
|
| **The orchestrator** (a workflow itself) | `ship` | `ship-close-workflow` | (absent) | (absent) |
|
|
168
|
-
| **A subagent** it invoked | `build` | the step that invoked it, e.g. `build-plan-gaps-remediate` | `bkit-build-plan-gaps-remediate` | that prompt's own `model:` |
|
|
168
|
+
| **A subagent** it invoked | `build` | the step that invoked it, e.g. `build-plan-gaps-remediate` | `bkit-build-plan-gaps-remediate` | the model that ran it: the one the host reported when the append names its invocation, else that prompt's own `model:` |
|
|
169
169
|
| **A direct chat** outside any workflow | `utility` | `manual` | (absent) | (absent) |
|
|
170
170
|
|
|
171
171
|
Subagent: set these on every row you append, from your prompt file:
|
|
@@ -177,6 +177,8 @@ Subagent: set these on every row you append, from your prompt file:
|
|
|
177
177
|
|
|
178
178
|
Orchestrator: omit `by.subagent` and `by.model`.
|
|
179
179
|
|
|
180
|
+
An append that names its invocation fills `by` from it. `by.model` is then the model the host reported, and it is absent when `by.modelSource` = `unavailable` (`observed` when the host reported one). `by.configuredModel` holds the prompt's pinned `model:`, and `by.host` names the host.
|
|
181
|
+
|
|
180
182
|
## Key & References
|
|
181
183
|
|
|
182
184
|
`key` = a stable slug, written once. A recurrence is a same-`key` append.
|
|
@@ -193,7 +195,7 @@ Orchestrator: omit `by.subagent` and `by.model`.
|
|
|
193
195
|
|
|
194
196
|
- A pointer is a feature id / `{FID}`, a tracker id (`ISSUE-217`), a PR, a commit SHA, a file path, or a row's `key` in the same or another ledger.
|
|
195
197
|
- Keep each item as the source wrote it. A trailing qualifier (`ISSUE-142 §A2`) is meaning, not noise.
|
|
196
|
-
-
|
|
198
|
+
- No separate identity field exists: `key` is the identity, and `references` holds pointers only.
|
|
197
199
|
- Omit the field when there is nothing to point at.
|
|
198
200
|
- Pointers between ledgers never need rewriting: a correction is a same-`key` append. When a correction affects rows in other ledgers that point at it, the ledger updater (`@bkit-utility-update-decisions`, `-knowledge`, `-deferrals`, `-failures`) reports those rows under `Cross-Ledger Impact`. Each row's own ledger writer appends any change.
|
|
199
201
|
|
|
@@ -262,7 +264,7 @@ On the kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `dec
|
|
|
262
264
|
|
|
263
265
|
1. `remediation` names specific files and a bounded edit, not a new architecture.
|
|
264
266
|
2. The surface is inside files the cycle already touched.
|
|
265
|
-
3.
|
|
267
|
+
3. No external blocker exists: no missing decision, credential, upstream fix or confirmation.
|
|
266
268
|
4. The row is `scope-declared` with no pre-existing declaration: the row is the only place the work was called out of scope.
|
|
267
269
|
|
|
268
270
|
Test 4 carries the weight. A genuine deferral was declared out of scope before the work started. An unjustified one was declared at the moment of avoidance. The ledger holds both timestamps.
|
|
@@ -388,6 +390,21 @@ An identity match means the same thing, not an automatic skip:
|
|
|
388
390
|
- **Nothing changed** → skip.
|
|
389
391
|
- **Something changed** → append (§ Updating a Row).
|
|
390
392
|
|
|
393
|
+
## `ci-handoff` and correction rows
|
|
394
|
+
|
|
395
|
+
These are rows in a run's `status.jsonl`; the status fold ignores types it does not know, so they never change a step's state. A runless (standalone) invocation has no status log: it keeps its correction events in `<outbox>/invocation-context/<id>.corrections.jsonl` next to the receipt, and its two-retry budget is per invocation.
|
|
396
|
+
|
|
397
|
+
<!-- prettier-ignore -->
|
|
398
|
+
| `type` | Written by | Fields |
|
|
399
|
+
| --- | --- | --- |
|
|
400
|
+
| `ci-handoff` | `bkit runs handoff`, `bkit runs dispatch --invocation` | the target (`provider`, `repo`, `pr`, `head`, `branch`), the cumulative observation (`result`, `attempts`, `errors`) and an optional re-trigger checkpoint `intended`, `commit-created`, `push-completed` or `receipt-completed` (the receipt) |
|
|
401
|
+
| `correction-rejected` | `bkit ledgers append --correction-of` | the rejected `operation`, the `scope` and the engine's rejection code |
|
|
402
|
+
| `correction-candidate` | `bkit counters correction` | the candidate `operation` that spent one retry in the `scope`, and its `requestHash` |
|
|
403
|
+
| `correction-succeeded` | `bkit ledgers append --correction-of` | the verified `operation` and the `scope` it closed |
|
|
404
|
+
|
|
405
|
+
- **Phase and totals** are derived by the engine from these rows; a caller never supplies an attempt count.
|
|
406
|
+
- **Other targets:** a `ci-handoff` row for another repo, PR, head or branch is counted as stale and never resumes the gate.
|
|
407
|
+
|
|
391
408
|
## `engine-action` rows
|
|
392
409
|
|
|
393
410
|
This is not a ledger but a row in a run's `status.jsonl` (`.bkit/workflows.md` § `status.jsonl`). An engine action unsafe to repeat — a tracker comment, a marker commit, a CI re-trigger, a PR open — appends one once it is done, and checks for it first, so a re-run of the same block does not act twice. Actions safe to repeat (a label already set) record nothing.
|
|
@@ -416,7 +433,7 @@ This is not a ledger but a row in a run's `status.jsonl` (`.bkit/workflows.md`
|
|
|
416
433
|
|
|
417
434
|
## Examples
|
|
418
435
|
|
|
419
|
-
The rows are indented here for readability. On disk, each row is a single physical line (§ Write Idiom).
|
|
436
|
+
The rows are indented here for readability. On disk, each row is a single physical line (§ Write Idiom). One example per ledger follows. Each shows the kind's fields, with the optional ones included where they apply to its workflow (§ Per-Kind Fields). The `build` block appears in the `run` example.
|
|
420
437
|
|
|
421
438
|
`.bkit/stats.jsonl` (`compliance` / `outcome` / `counter`); `harvest/stats.jsonl` (`chat` / `run`):
|
|
422
439
|
|