@cbartens/bkit 5.4.0 → 5.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +19 -7
- package/.bkit/core/.agents/rules.md +24 -9
- package/.bkit/core/.bkit/README.md +18 -6
- package/.bkit/core/.bkit/cloud.md +46 -15
- package/.bkit/core/.bkit/comparison.md +2 -2
- package/.bkit/core/.bkit/install.md +19 -18
- package/.bkit/core/.bkit/pipeline.md +3 -1
- package/.bkit/core/.bkit/prompts.md +38 -20
- package/.bkit/core/.bkit/providers.md +6 -6
- package/.bkit/core/.bkit/templates.md +44 -13
- package/.bkit/core/.bkit/trackers.md +99 -35
- package/.bkit/core/.bkit/workflows.md +50 -45
- package/.bkit/core/AGENTS.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-issues.md +22 -6
- package/.bkit/core/engine/checks/after/auth.ts +88 -45
- package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
- package/.bkit/core/engine/checks/after/github.ts +42 -78
- package/.bkit/core/engine/checks/after/index.ts +1 -6
- 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/tips/catalogue.ts +15 -2
- package/.bkit/core/engine/checks/tips/index.ts +5 -2
- package/.bkit/core/engine/cli.ts +7 -5
- package/.bkit/core/engine/commands/ci/ci.ts +107 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
- package/.bkit/core/engine/commands/workflow/issues.ts +61 -63
- package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
- package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
- package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
- package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
- package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
- package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
- 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 +153 -4
- package/.bkit/core/engine/install/modules/opencode.ts +5 -0
- 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 +130 -11
- package/.bkit/core/hooks/guardrails-tiers.js +1 -1
- package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
- 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-abort-handover.md +2 -0
- 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 +4 -1
- package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
- package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
- 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 +59 -17
- package/.bkit/core/workflows/bkit-debug.md +64 -20
- package/.bkit/core/workflows/bkit-design.md +83 -28
- package/.bkit/core/workflows/bkit-plan.md +61 -20
- package/.bkit/core/workflows/bkit-ship.md +48 -18
- package/.bkit/shared/.bkit/.env.example +8 -0
- package/.bkit/shared/.claude/settings.json +3 -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 +6 -7
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/testing.md +13 -5
- package/.bkit/templates/.github/renovate.json5 +1 -1
- package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -115
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
- package/.bkit/templates/.husky/pre-commit +4 -4
- package/.bkit/templates/.husky/pre-push +107 -18
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
- package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
- package/CHANGELOG.md +67 -1
- package/README.md +16 -6
- package/dist/checks/after/auth.js +81 -45
- package/dist/checks/after/ci-yml.js +0 -1
- package/dist/checks/after/github.js +41 -76
- package/dist/checks/after/index.js +2 -7
- 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/tips/catalogue.js +14 -2
- package/dist/checks/tips/index.js +4 -2
- package/dist/cli.js +7 -5
- package/dist/commands/ci/ci.js +100 -0
- package/dist/commands/install/uninstall.js +42 -0
- package/dist/commands/workflow/fids.js +22 -15
- package/dist/commands/workflow/issues.js +53 -61
- package/dist/commands/workflow/ledgers.js +26 -11
- package/dist/commands/workflow/prs.js +3 -1
- package/dist/commands/workflow/repo.js +6 -0
- package/dist/commands/workflow/roadmap.js +3 -1
- package/dist/commands/workflow/steps.js +2 -2
- package/dist/commands/workflow/workflows.js +9 -4
- package/dist/commands/workflow/worktrees.js +74 -13
- package/dist/install/manifest.js +30 -10
- package/dist/install/modules/cloud.js +3 -1
- package/dist/install/modules/core.js +157 -5
- package/dist/install/modules/opencode.js +6 -0
- 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 +59 -7
- package/package.json +14 -3
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.1 — do not edit; run `bkit upgrade` to refresh -->
|
|
4
4
|
|
|
5
5
|
**bkit** wires Claude Code, Cursor, Codex, Google Antigravity and opencode into five-phase tracker-integrated cycle: `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`. Hosts additive, one flag each: `--claude`, `--cursor`, `--codex`, `--antigravity`, `--opencode=<provider>` — opencode providers: `openrouter`, `ollama`, `opencode-zen` + `opencode-go` (opencode-native gateways; auth via `BKIT_OPENCODE_API_KEY`). Same harness on every host; state lives in the repo, so a feature moves between hosts mid-run (see `.bkit/providers.md` § Hosts + Providers).
|
|
6
6
|
|
|
@@ -15,7 +15,7 @@ Typical cycle for `ISSUE-123` "Add feature X":
|
|
|
15
15
|
1. **Tracker issue** with **`bkit:auto`** label + non-terminal state (`Backlog`, `In Progress`).
|
|
16
16
|
2. **Trigger** — tracker comment (`@cursor /bkit-plan ISSUE-123`) or slash command (`/bkit-plan ISSUE-123`).
|
|
17
17
|
3. **Workflow Step 1** — preflight checks `bkit:auto`, acquires `.lock`, sets `bkit:plan` + `In Progress`, creates workflow comment.
|
|
18
|
-
4. **Step 2 — worktree** — git worktree at `.worktrees/issue-123-add-feature/` on `feat/issue-123-add-feature
|
|
18
|
+
4. **Step 2 — worktree** — git worktree at `.worktrees/issue-123-add-feature/` on `feat/issue-123-add-feature`, cut from `origin/dev` (local `dev` when it holds unpushed commits on top). Copies each `bkit.worktree.copy` path from the main checkout (a `package.json` setting; default `.env`, `.env.local`; exact paths, folders copy recursively; a missing one is logged, never fatal), runs `direnv allow` when the worktree's `.envrc` matches the main checkout's, then `pnpm install --frozen-lockfile` unless `bkit.worktree.install: false`.
|
|
19
19
|
5. **Phase steps** — dispatches subagents (`@bkit-plan-generate`, then `@bkit-plan-review-1` ‖ `-2` ‖ `-3` parallel triplet, etc.). Each writes `docs/plans/{YYYYMM}/logs/{FID}/` (`{YYYYMM}` = canonical month bucket at design start), appends fenced section to tracker comment.
|
|
20
20
|
6. **Phase summary** — verdict (`PASS` / `CONCERNS` / `FAIL`); commit `chore(issue-123-…): summary bkit [skip ci]` (design/plan) or `chore(issue-123-…): summary` (build/debug/ship) → push.
|
|
21
21
|
7. **Close Workflow** — tracker `In Review`; phase label persists. `/bkit-design` / `/bkit-plan`: prune worktree, delete `feat/issue-123-…` (merged into `dev`). `/bkit-build` / `/bkit-debug`: worktree persists.
|
|
@@ -65,6 +65,7 @@ No `/bkit-audit` command and no phase label. More than 30 procedures ship as `do
|
|
|
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
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. |
|
|
68
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. |
|
|
69
70
|
|
|
70
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).
|
|
@@ -125,6 +126,16 @@ BKIT_ANTHROPIC_API_KEY=""
|
|
|
125
126
|
BKIT_GH_TOKEN=""
|
|
126
127
|
```
|
|
127
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
|
+
|
|
128
139
|
<!-- prettier-ignore -->
|
|
129
140
|
| Variable | Tracker | Where read | Purpose |
|
|
130
141
|
| --- | --- | --- | --- |
|
|
@@ -134,9 +145,10 @@ BKIT_GH_TOKEN=""
|
|
|
134
145
|
| `BKIT_ANTHROPIC_API_KEY` | all | Claude Code (headless / CI) | Required when Claude invoked outside interactive session (cloud automation, CI). |
|
|
135
146
|
| `BKIT_CURSOR_API_KEY` | all | Cursor Cloud Agent dashboard / programmatic invocation | Required for non-interactive Cursor sessions. |
|
|
136
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. |
|
|
137
149
|
| `LINEAR_WEBHOOK_SECRET` | linear | Linear → Cursor integration backend | Verifies webhook signatures on `@cursor` mentions. Set in Linear ↔ Cursor integration config. |
|
|
138
150
|
|
|
139
|
-
`
|
|
151
|
+
`GITHUB_ISSUE_ID` (GitHub) and `LINEAR_ISSUE_ID` (Linear) set automatically by workflow context — do not set manually.
|
|
140
152
|
|
|
141
153
|
### Tracker workspace setup
|
|
142
154
|
|
|
@@ -269,7 +281,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
|
269
281
|
| `.bkit/.env.example` | claude | `.bkit/shared/.bkit/.env.example` | Tier 1 (fully managed). Real values go in `.bkit/.env`. |
|
|
270
282
|
| `.cursor/commands/bkit-*.md` | cursor | `.bkit/core/workflows/` (T1+T2 transforms) | Host pass — always overwrite |
|
|
271
283
|
| `.cursor/agents/bkit-*.md` | cursor | `.bkit/core/prompts/` (T3 transforms) | Host pass — always overwrite |
|
|
272
|
-
| `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`. |
|
|
273
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. |
|
|
274
286
|
| `.cursor/hooks.json` | cursor | `.bkit/shared/.cursor/hooks.json` | Tier 1 (fully managed) |
|
|
275
287
|
| `.cursor/mcp.json` | cursor | `.bkit/shared/.cursor/mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only |
|
|
@@ -290,7 +302,7 @@ The cloud workflow and the Cursor Background Agent files are templates the `--au
|
|
|
290
302
|
|
|
291
303
|
### Optional post-install decisions (tracker + cloud agents)
|
|
292
304
|
|
|
293
|
-
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.
|
|
294
306
|
|
|
295
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.
|
|
296
308
|
|
|
@@ -348,7 +360,7 @@ Slash commands at repo root:
|
|
|
348
360
|
|
|
349
361
|
Claude reads issue, comments, plan files via tracker MCP.
|
|
350
362
|
|
|
351
|
-
**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.
|
|
352
364
|
|
|
353
365
|
### From Cursor (interactive — local)
|
|
354
366
|
|
|
@@ -360,7 +372,7 @@ Cursor 2.4+ honours `.cursor/commands/bkit-*.md` and `.cursor/agents/bkit-*.md`:
|
|
|
360
372
|
|
|
361
373
|
Orchestrator reads `.cursor/commands/` workflow. Subagents via `Task`, `model:` from frontmatter (no host override).
|
|
362
374
|
|
|
363
|
-
**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.
|
|
364
376
|
|
|
365
377
|
---
|
|
366
378
|
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Local project rules / overrides → `Project Rules` below bkit-managed block; universal rules stay in-block.
|
|
16
|
+
> - Where project services live (repo, boards, service org / project ids) → `Project Settings`, last section; facts only — NEVER rules, NEVER change workflows, gates or permissions.
|
|
16
17
|
|
|
17
18
|
## bkit Rules
|
|
18
19
|
|
|
@@ -72,16 +73,15 @@
|
|
|
72
73
|
- **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.
|
|
73
74
|
- **Discovered bugs:** NEVER silently drop discovered bugs, ALWAYS append rows to `docs/failures.jsonl` in `.bkit/jsonl.md` format; check existing entries first.
|
|
74
75
|
- **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.
|
|
75
|
-
- **Tracker MCPs:** Issue reads / updates via configured MCP ONLY; use CLI / HTTP shell-outs as backup / fallback ONLY.
|
|
76
|
-
- **Tracker comments:** NEVER mention @claude or @cursor in comment body.
|
|
77
|
-
- **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.
|
|
78
76
|
- **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, 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.
|
|
78
|
+
- **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.
|
|
79
79
|
- **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:*`.
|
|
80
80
|
- **Tracker failure label:** Any workflow Failure Path → add `bkit:failed` alongside workflow label.
|
|
81
|
-
- **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.
|
|
82
|
-
- **Tracker issue settings:** Title MAX 70 characters or two lines on mobile; ALWAYS set labels, project, priority, size, and milestone; check similar issues if unclear.
|
|
83
81
|
- **Tracker issue mentions:** NEVER mention issue IDs on their own; ALWAYS mention issue IDs together with their title and URL.
|
|
84
|
-
- **Tracker work comments:** ANY
|
|
82
|
+
- **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.
|
|
83
|
+
- **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.
|
|
84
|
+
- **Tracker MCPs:** Issue reads / updates via configured MCP ONLY; use CLI / HTTP shell-outs as backup / fallback ONLY.
|
|
85
85
|
|
|
86
86
|
#### Git, CI & Merges
|
|
87
87
|
|
|
@@ -93,7 +93,7 @@
|
|
|
93
93
|
- **Code commits:** Ensure code commit is HEAD so CI runs.
|
|
94
94
|
- **Secrets:** NEVER stage `.env*`, credentials, tokens, API keys. `git status` review before every commit.
|
|
95
95
|
- **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).
|
|
96
|
-
- **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.
|
|
96
|
+
- **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.
|
|
97
97
|
- **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.
|
|
98
98
|
- **Pre-push:** `--no-verify` PROHIBITED. Fix failures locally. If unfixable → document and STOP.
|
|
99
99
|
- **Force push:** PROHIBITED on shared branches (`dev` / `main`). Personal branches ONLY with `--force-with-lease` — the sole exception to `Destructive git PROHIBITED`.
|
|
@@ -117,7 +117,7 @@
|
|
|
117
117
|
- **Provider data:** Logs, errors, database → prefer enabled `.agents/context.md` context-fetch blocks or provider's CLI over MCP.
|
|
118
118
|
- **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.
|
|
119
119
|
- **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.
|
|
120
|
-
- **Local pre-push:** `pnpm bkit:gate:static-unit`, then `bkit check`. Gate scripts MUST not run tests needing a deployed boundary
|
|
120
|
+
- **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.
|
|
121
121
|
- **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.
|
|
122
122
|
- **CI on push to `dev` / `main`:** PR lanes plus remote migration apply inside migration lane + `@live` canary (both wait on migration ≠ failure).
|
|
123
123
|
- **Name the suites you ran:** NEVER report "all tests green" or a bare task count as evidence. State the tiers — `unit`, `integration`, `e2e`, `@live`.
|
|
@@ -126,7 +126,8 @@
|
|
|
126
126
|
- **Debug on demand:** Re-runs failing E2E / `@live` tier tests against deployed boundary. NEVER purely local runs.
|
|
127
127
|
- **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.
|
|
128
128
|
- **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).
|
|
129
|
-
- **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.
|
|
129
|
+
- **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.worktree.copy` 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. `bkit worktrees setup` does the copy, the install and `direnv allow` itself.
|
|
130
|
+
- **Shared local stack:** worktrees share every local service with fixed names / ports (Docker database, emulator) → start / reset / stop / test against them ONLY through the repo's locked scripts (`.bkit/templates.md` § Local stack lock); NEVER run the raw CLI (e.g. `supabase db reset`, `docker compose down`); a fix hint printing a raw command = bug.
|
|
130
131
|
|
|
131
132
|
#### Security & Data
|
|
132
133
|
|
|
@@ -166,3 +167,17 @@
|
|
|
166
167
|
### Universal Rules
|
|
167
168
|
|
|
168
169
|
### Orchestrator Rules
|
|
170
|
+
|
|
171
|
+
## Project Settings
|
|
172
|
+
|
|
173
|
+
Non-secret identifiers agents pass to MCP servers and CLIs; tokens stay in env files. One row per value; delete unused rows.
|
|
174
|
+
|
|
175
|
+
<!-- Examples:
|
|
176
|
+
| Service | Setting | Value |
|
|
177
|
+
| --- | --- | --- |
|
|
178
|
+
| GitHub | Repository | `acme/web` |
|
|
179
|
+
| GitHub | Project board | https://github.com/orgs/acme/projects/1 |
|
|
180
|
+
| Sentry | Org / project | `acme` / `web` |
|
|
181
|
+
| Supabase | Project ref (preview / production) | `abcdefghijklmnopqrst` / `tsrqponmlkjihgfedcba` |
|
|
182
|
+
| Vercel | Team / project | `acme` / `web` |
|
|
183
|
+
-->
|
|
@@ -15,7 +15,7 @@ Typical cycle for `ISSUE-123` "Add feature X":
|
|
|
15
15
|
1. **Tracker issue** with **`bkit:auto`** label + non-terminal state (`Backlog`, `In Progress`).
|
|
16
16
|
2. **Trigger** — tracker comment (`@cursor /bkit-plan ISSUE-123`) or slash command (`/bkit-plan ISSUE-123`).
|
|
17
17
|
3. **Workflow Step 1** — preflight checks `bkit:auto`, acquires `.lock`, sets `bkit:plan` + `In Progress`, creates workflow comment.
|
|
18
|
-
4. **Step 2 — worktree** — git worktree at `.worktrees/issue-123-add-feature/` on `feat/issue-123-add-feature
|
|
18
|
+
4. **Step 2 — worktree** — git worktree at `.worktrees/issue-123-add-feature/` on `feat/issue-123-add-feature`, cut from `origin/dev` (local `dev` when it holds unpushed commits on top). Copies each `bkit.worktree.copy` path from the main checkout (a `package.json` setting; default `.env`, `.env.local`; exact paths, folders copy recursively; a missing one is logged, never fatal), runs `direnv allow` when the worktree's `.envrc` matches the main checkout's, then `pnpm install --frozen-lockfile` unless `bkit.worktree.install: false`.
|
|
19
19
|
5. **Phase steps** — dispatches subagents (`@bkit-plan-generate`, then `@bkit-plan-review-1` ‖ `-2` ‖ `-3` parallel triplet, etc.). Each writes `docs/plans/{YYYYMM}/logs/{FID}/` (`{YYYYMM}` = canonical month bucket at design start), appends fenced section to tracker comment.
|
|
20
20
|
6. **Phase summary** — verdict (`PASS` / `CONCERNS` / `FAIL`); commit `chore(issue-123-…): summary bkit [skip ci]` (design/plan) or `chore(issue-123-…): summary` (build/debug/ship) → push.
|
|
21
21
|
7. **Close Workflow** — tracker `In Review`; phase label persists. `/bkit-design` / `/bkit-plan`: prune worktree, delete `feat/issue-123-…` (merged into `dev`). `/bkit-build` / `/bkit-debug`: worktree persists.
|
|
@@ -65,6 +65,7 @@ No `/bkit-audit` command and no phase label. More than 30 procedures ship as `do
|
|
|
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
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. |
|
|
68
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. |
|
|
69
70
|
|
|
70
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).
|
|
@@ -125,6 +126,16 @@ BKIT_ANTHROPIC_API_KEY=""
|
|
|
125
126
|
BKIT_GH_TOKEN=""
|
|
126
127
|
```
|
|
127
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
|
+
|
|
128
139
|
<!-- prettier-ignore -->
|
|
129
140
|
| Variable | Tracker | Where read | Purpose |
|
|
130
141
|
| --- | --- | --- | --- |
|
|
@@ -134,9 +145,10 @@ BKIT_GH_TOKEN=""
|
|
|
134
145
|
| `BKIT_ANTHROPIC_API_KEY` | all | Claude Code (headless / CI) | Required when Claude invoked outside interactive session (cloud automation, CI). |
|
|
135
146
|
| `BKIT_CURSOR_API_KEY` | all | Cursor Cloud Agent dashboard / programmatic invocation | Required for non-interactive Cursor sessions. |
|
|
136
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. |
|
|
137
149
|
| `LINEAR_WEBHOOK_SECRET` | linear | Linear → Cursor integration backend | Verifies webhook signatures on `@cursor` mentions. Set in Linear ↔ Cursor integration config. |
|
|
138
150
|
|
|
139
|
-
`
|
|
151
|
+
`GITHUB_ISSUE_ID` (GitHub) and `LINEAR_ISSUE_ID` (Linear) set automatically by workflow context — do not set manually.
|
|
140
152
|
|
|
141
153
|
### Tracker workspace setup
|
|
142
154
|
|
|
@@ -269,7 +281,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
|
269
281
|
| `.bkit/.env.example` | claude | `.bkit/shared/.bkit/.env.example` | Tier 1 (fully managed). Real values go in `.bkit/.env`. |
|
|
270
282
|
| `.cursor/commands/bkit-*.md` | cursor | `.bkit/core/workflows/` (T1+T2 transforms) | Host pass — always overwrite |
|
|
271
283
|
| `.cursor/agents/bkit-*.md` | cursor | `.bkit/core/prompts/` (T3 transforms) | Host pass — always overwrite |
|
|
272
|
-
| `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`. |
|
|
273
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. |
|
|
274
286
|
| `.cursor/hooks.json` | cursor | `.bkit/shared/.cursor/hooks.json` | Tier 1 (fully managed) |
|
|
275
287
|
| `.cursor/mcp.json` | cursor | `.bkit/shared/.cursor/mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only |
|
|
@@ -290,7 +302,7 @@ The cloud workflow and the Cursor Background Agent files are templates the `--au
|
|
|
290
302
|
|
|
291
303
|
### Optional post-install decisions (tracker + cloud agents)
|
|
292
304
|
|
|
293
|
-
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.
|
|
294
306
|
|
|
295
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.
|
|
296
308
|
|
|
@@ -348,7 +360,7 @@ Slash commands at repo root:
|
|
|
348
360
|
|
|
349
361
|
Claude reads issue, comments, plan files via tracker MCP.
|
|
350
362
|
|
|
351
|
-
**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.
|
|
352
364
|
|
|
353
365
|
### From Cursor (interactive — local)
|
|
354
366
|
|
|
@@ -360,7 +372,7 @@ Cursor 2.4+ honours `.cursor/commands/bkit-*.md` and `.cursor/agents/bkit-*.md`:
|
|
|
360
372
|
|
|
361
373
|
Orchestrator reads `.cursor/commands/` workflow. Subagents via `Task`, `model:` from frontmatter (no host override).
|
|
362
374
|
|
|
363
|
-
**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.
|
|
364
376
|
|
|
365
377
|
---
|
|
366
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
|
|
|
@@ -177,12 +177,12 @@ SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/da
|
|
|
177
177
|
| Issues | Read & write | `gh issue` |
|
|
178
178
|
| Actions | Read & write | `gh run view` logs, `gh workflow run` |
|
|
179
179
|
| Workflows | Read & write | `gh workflow` (edit `.github/workflows/*`) |
|
|
180
|
-
| Projects (org) | Read & write | GitHub Projects v2 board status sync (`bkit.
|
|
180
|
+
| Projects (org) | Read & write | GitHub Projects v2 board status sync (`bkit.github.project`) — org-owned boards only; see note |
|
|
181
181
|
| Metadata | Read | mandatory, auto-included |
|
|
182
182
|
|
|
183
183
|
`gh` does **not** read `BKIT_GH_TOKEN` — pipe once after session start: `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` (e.g. in `.claude/hooks/bkit-cloud-bootstrap.sh`). Locally, `gh auth login` and leave `GH_TOKEN` unset so keyring not overridden.
|
|
184
184
|
|
|
185
|
-
> **Projects v2 board sync (`bkit.
|
|
185
|
+
> **Projects v2 board sync (`bkit.github.project`):** **Projects** permission is **Organization** permission (table row above) — appears only when token **resource owner is the org**, _not_ personal account; org may require token **approved**. Under token UI **Organizations** tab, not Repository permissions; governs `…/orgs/{org}/projectsV2/…`. User-owned (personal-account) boards unreachable by fine-grained PATs — see below.
|
|
186
186
|
|
|
187
187
|
#### When classic is still required
|
|
188
188
|
|
|
@@ -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.
|
|
@@ -62,7 +62,7 @@ Run these in order on a brand-new consumer repo.
|
|
|
62
62
|
| --- | --- | --- |
|
|
63
63
|
| 1 | `pnpm add -D @cbartens/bkit` — no token, no registry mapping | this section |
|
|
64
64
|
| 2 | Run `bkit install --claude --cursor` to seed both hosts (writes `.bkit/.env.example`; `.envrc` is a template in `.bkit/templates/`) | this section |
|
|
65
|
-
| 3 | Set up direnv + `.bkit/.env` for `BKIT_GH_TOKEN` (GitHub MCP)
|
|
65
|
+
| 3 | Set up direnv + `.bkit/.env` for `BKIT_GH_TOKEN` (GitHub MCP), `BKIT_LINEAR_API_KEY` or `BKIT_JIRA_API_TOKEN` — no registry token | [§ Local env setup](#local-env-setup) |
|
|
66
66
|
| 4 | Push to a feature branch and verify CI runs green | — |
|
|
67
67
|
|
|
68
68
|
No CI step, secret, `.npmrc` mapping or Vercel env is needed — CI reaches npmjs anonymously.
|
|
@@ -104,7 +104,7 @@ bkit check
|
|
|
104
104
|
|
|
105
105
|
**Module flags** (composable; symmetric install ↔ uninstall): `--claude` `--cursor` `--codex` `--antigravity` `--opencode=<provider>`. The CI workflow, the Vale config, the tool configs, the git hooks, the slop-scan type-suppression plugin (`scripts/slop/bkit-slop-type-suppression.mjs`), and the tool `package.json` scripts and devDeps are templates you copy from `.bkit/templates/` (`.bkit/templates.md`). Core, implicit on every install, seeds the `bkit:gate:*` / `bkit:deps:*` scripts every workflow runs (add-if-missing; a name already present is never touched); point their values at your stack, see `.bkit/README.md` § Required tools. Any other module flag is an unknown-flag error.
|
|
106
106
|
|
|
107
|
-
**Opt-in flags:** `--tracker=github|linear`, `--auto=claude|cursor|opencode` (cloud agents), `--opencode=<provider>` (additive opencode execution host — `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). Dependency updaters: copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
|
|
107
|
+
**Opt-in flags:** `--tracker=github|linear|jira`, `--auto=claude|cursor|opencode` (cloud agents), `--opencode=<provider>` (additive opencode execution host — `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). Dependency updaters: copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
|
|
108
108
|
|
|
109
109
|
### Payload view links — `.bkit/core` + `.bkit/shared`
|
|
110
110
|
|
|
@@ -119,7 +119,7 @@ Install and upgrade create two **relative symlinks** into the installed package,
|
|
|
119
119
|
|
|
120
120
|
### Local env setup
|
|
121
121
|
|
|
122
|
-
Two flows — pick one. Both put `BKIT_GH_TOKEN` in shell for the GitHub MCP server; Linear repos also need `BKIT_LINEAR_API_KEY`. Use `gh auth login` for CLI.
|
|
122
|
+
Two flows — pick one. Both put `BKIT_GH_TOKEN` in shell for the GitHub MCP server; Linear repos also need `BKIT_LINEAR_API_KEY`, Jira repos `BKIT_JIRA_API_TOKEN` (`.bkit/trackers.md` § jira — setup and notes). Use `gh auth login` for CLI.
|
|
123
123
|
|
|
124
124
|
#### Flow A — Shell export (quickest, no extra deps)
|
|
125
125
|
|
|
@@ -127,6 +127,7 @@ Two flows — pick one. Both put `BKIT_GH_TOKEN` in shell for the GitHub MCP ser
|
|
|
127
127
|
# Add to ~/.zshrc (or ~/.bashrc)
|
|
128
128
|
export BKIT_GH_TOKEN=<PAT — fine-grained (one owner) or classic (multiple owners)> # GitHub MCP
|
|
129
129
|
export BKIT_LINEAR_API_KEY=<Linear personal API key> # Linear MCP + preflight
|
|
130
|
+
export BKIT_JIRA_API_TOKEN=<Atlassian MCP V2 scoped token> # Jira MCP
|
|
130
131
|
|
|
131
132
|
# Reload
|
|
132
133
|
source ~/.zshrc # or: source ~/.bashrc
|
|
@@ -150,7 +151,7 @@ echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc
|
|
|
150
151
|
# 3. One-time per consumer repo (after `bkit install`)
|
|
151
152
|
cp .bkit/templates/.envrc .envrc # unless you already have one
|
|
152
153
|
cp .bkit/.env.example .bkit/.env
|
|
153
|
-
# Edit .bkit/.env: set BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY
|
|
154
|
+
# Edit .bkit/.env: set BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY or BKIT_JIRA_API_TOKEN
|
|
154
155
|
direnv allow # trust the .envrc
|
|
155
156
|
|
|
156
157
|
# 4. Verify
|
|
@@ -166,7 +167,7 @@ After step 4, restart open Claude Code / Cursor sessions in this repo so new env
|
|
|
166
167
|
|
|
167
168
|
bkit ships repo-side scaffolding for both cloud agents. Opt-in `bkit install --auto=claude` writes no file; the per-session install hook (`.claude/hooks/bkit-cloud-bootstrap.sh`), the phase-routed `.github/workflows/bkit-cloud.yml` and the Cursor cloud image files (`.cursor/Dockerfile`, `.cursor/environment.json`) are templates in `.bkit/templates/` that you copy and own. (`.cursor/hooks.json` — Linear preflight wiring — ships with `--cursor`, not `--auto`.) Install without `--auto` ships zero cloud footprint. **Online-dashboard** half (Claude env in `claude.ai/code`, Cursor env vars in `Cursor → Settings → Background Agents`) configured once per machine / account.
|
|
168
169
|
|
|
169
|
-
For **post-CI auto-routing** (ship-vs-debug after CI), bkit ships a single `.github/workflows/bkit-cloud.yml` template with TWO runtime-gated dispatch jobs — **claude** job (`claude-code-action`, runs when the `ANTHROPIC_API_KEY` repo secret is set) and **opencode** job (`opencode run` CLI, runs when `OPENCODE_PROVIDER_KEY` set) — plus `/bkit-auto` slash command both clouds invoke from single source (Cursor wires via dashboard trigger; no GHA on Cursor side). `bkit install --auto=opencode` requires `tracker=github`.
|
|
170
|
+
For **post-CI auto-routing** (ship-vs-debug after CI), bkit ships a single `.github/workflows/bkit-cloud.yml` template with TWO runtime-gated dispatch jobs — **claude** job (`claude-code-action`, runs when the `ANTHROPIC_API_KEY` repo secret is set, or keyless via the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables) and **opencode** job (`opencode run` CLI, runs when `OPENCODE_PROVIDER_KEY` set) — plus `/bkit-auto` slash command both clouds invoke from single source (Cursor wires via dashboard trigger; no GHA on Cursor side). `bkit install --auto=opencode` requires `tracker=github`.
|
|
170
171
|
|
|
171
172
|
Full recipe + paste-in setup script + env-var inventory + Cursor dashboard config + consumer customisation patterns: `.bkit/cloud.md`. Host-delta matrix: `.bkit/providers.md` § Runtime environment.
|
|
172
173
|
|
|
@@ -225,16 +226,16 @@ After writes, bkit re-runs credential and environment checks — some only accur
|
|
|
225
226
|
| --- | --- |
|
|
226
227
|
| `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. |
|
|
227
228
|
| `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. |
|
|
228
|
-
| `tracker-setup-none` / `-github` / `-linear` | Optional post-install decision — which issue tracker is wired (`bkit.issueTracker`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
229
|
-
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.
|
|
230
|
-
| `github-project-status-field-id-format` | `bkit.githubProject` is configured but `statusFieldId` holds a GraphQL node id (`PVTSSF_…`) or non-number — `projects_write` needs the numeric field id, so board sync silently no-ops. Re-derive via `gh api /orgs/<org>/projectsV2/<number>/fields`. |
|
|
229
|
+
| `tracker-setup-none` / `-github` / `-linear` / `-jira` | Optional post-install decision — which issue tracker is wired (`bkit.issueTracker`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
230
|
+
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.github.project` absent or not a board URL, and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.github.project: false`. |
|
|
231
231
|
| `dep-updater-absent` | No Renovate or Dependabot config. Copy one example and own it. `bkit.depUpdater: "none"` silences this. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
232
232
|
| `dep-updater-both` | Both updater configs are present. Keep one. |
|
|
233
|
-
| `cloud-router-none` / `cloud-router` | Optional post-install decision — post-CI auto-routing (`bkit.cloudAgents`). `none` (undecided) nudges `bkit install --auto=<variant
|
|
233
|
+
| `cloud-router-none` / `cloud-router` | Optional post-install decision — post-CI auto-routing (`bkit.cloudAgents`). `none` (undecided) nudges `bkit install --auto=<variant>`, except under the jira tracker (local runs only); `cloud-router` is informational once `bkit-cloud.yml` is present. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
234
234
|
| `actions-write-permissions-missing` | `bkit-cloud.yml` present but repo Actions permissions are read-only / PR creation disabled — `actions/checkout` + `gh pr create` 403. Repo-level check; org policy can override. |
|
|
235
235
|
| `opencode-setup` | opencode host installed (`--opencode=<provider>`) — names the provider key to set (e.g. `BKIT_OPENROUTER_API_KEY`; `BKIT_OPENCODE_API_KEY` for `opencode-zen` / `opencode-go`), confirms the pre-seeded base URL, and notes all four providers ship curated per-agent pins (re-pin via `.bkit/prompts.md` § Model Overrides). Verify with `bkit doctor` + `bkit status`. |
|
|
236
236
|
| `vale-package-not-synced` | vale on PATH but `.vale/styles/write-good/` absent |
|
|
237
237
|
| `gate-missing-called-scripts` | A `bkit:gate:*` script still at bkit's default chains a script `package.json` does not declare (e.g. `typecheck`, `format:check`, `test`). Add it (`.bkit/templates.md` lists the tool scripts and devDeps) or rewrite the gate. |
|
|
238
|
+
| `gate-commit-repeats-push` | `bkit:gate:format` (pre-commit) runs a script the push gate runs again (e.g. `lint:prose`), so it runs on every commit and again on the push. Drop it from `bkit:gate:format`. |
|
|
238
239
|
| `gate-noop` | A `bkit:gate:*` script is empty or cannot fail (`true`, `:`, `exit 0`, `echo …`), so every agent run and push passes it. Warn-only, at install, `bkit check` and `bkit upgrade`, on every branch. Point it at real checks, or delete it and run `bkit upgrade` to restore bkit's default. |
|
|
239
240
|
| `gate-tier-not-wired` | `package.json` declares a deeper test tier (`test:integration`, `test:e2e`, `test:live`) that no `bkit:gate:*` script runs; the advisory prints the gate line to add. |
|
|
240
241
|
| `test-file-script-missing` | `package.json` does not declare `bkit:test:file`, so `/bkit-build` reports test-first as not enforced. The advisory prints the script contract and a Vitest line. |
|
|
@@ -283,7 +284,7 @@ Two capabilities **opt-in** — never wired by plain host/tooling install. Defau
|
|
|
283
284
|
<!-- prettier-ignore -->
|
|
284
285
|
| Decision | Default | Opt-in command | Advisory when unset |
|
|
285
286
|
| --- | --- | --- | --- |
|
|
286
|
-
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (`BKIT_GH_TOKEN`)
|
|
287
|
+
| **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_TOKEN` + `bkit.jira.site` / `bkit.jira.project`) | `tracker-setup-none` |
|
|
287
288
|
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude + opencode jobs, secret-gated) and the Cursor Dockerfile/environment.json | `cloud-router-none` |
|
|
288
289
|
|
|
289
290
|
**Dependency updater.** Copy one example and own it.
|
|
@@ -306,14 +307,14 @@ Use one. `bkit.depUpdater: "none"` skips the install-time absence advisory. Setu
|
|
|
306
307
|
**Why opt-in, not part of a default install:**
|
|
307
308
|
|
|
308
309
|
- **Tracker** wires real credentials and MCP servers into workflows — consumer must choose provider; bkit can't guess.
|
|
309
|
-
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template (auto-dispatches bkit-ship on CI pass, bkit-debug on CI fail; plan/build via `workflow_dispatch`; design is local-only) plus cloud env scaffolding (`.claude/hooks/bkit-cloud-bootstrap.sh`, and the `.cursor/Dockerfile` + `.cursor/environment.json` templates). Workflow carries claude job and opencode job, each runtime-gated on provider secret — inert without key: claude needs the `ANTHROPIC_API_KEY` repo secret (+ Claude GitHub App), opencode needs `OPENCODE_PROVIDER_KEY`. Both need GitHub Actions write permissions, GitHub tracker, and (Cursor half) dashboard trigger — tracker itself opt-in. Env scaffolding inert until Claude/Cursor cloud env wired in dashboard. Autonomous routing by default, wired to unconfigured tracker, is wrong default — install without `--auto` ships zero cloud footprint.
|
|
310
|
+
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template (auto-dispatches bkit-ship on CI pass, bkit-debug on CI fail; plan/build via `workflow_dispatch`; design is local-only) plus cloud env scaffolding (`.claude/hooks/bkit-cloud-bootstrap.sh`, and the `.cursor/Dockerfile` + `.cursor/environment.json` templates). Workflow carries claude job and opencode job, each runtime-gated on provider secret — inert without key: claude needs the `ANTHROPIC_API_KEY` repo secret or the federation repo variables (+ Claude GitHub App), opencode needs `OPENCODE_PROVIDER_KEY`. Both need GitHub Actions write permissions, GitHub tracker, and (Cursor half) dashboard trigger — tracker itself opt-in. Env scaffolding inert until Claude/Cursor cloud env wired in dashboard. Autonomous routing by default, wired to unconfigured tracker, is wrong default — install without `--auto` ships zero cloud footprint.
|
|
310
311
|
|
|
311
312
|
**How to decide:**
|
|
312
313
|
|
|
313
314
|
1. Run `bkit install --claude --cursor` (or whichever modules you want). Post-install banner lists `tracker-setup-none`, `dep-updater-absent`, `cloud-router-none` if undecided.
|
|
314
|
-
2. Pick tracker: `bkit install --tracker=github` (or `linear`). Needs no host flag; re-renders every installed host. Persisted to `bkit.issueTracker`; future installs preserve (switching free).
|
|
315
|
+
2. Pick tracker: `bkit install --tracker=github` (or `linear` / `jira`). Needs no host flag; re-renders every installed host. Persisted to `bkit.issueTracker`; future installs preserve (switching free).
|
|
315
316
|
3. Copy one updater example (table above). Land Renovate config on the default branch before installing the App.
|
|
316
|
-
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. Persisted to `bkit.cloudAgents`; install prints secrets + permissions + dashboard checklist (`bkit-auto-setup`). Shipped `bkit-cloud.yml` carries claude job (`ANTHROPIC_API_KEY` repo secret) and opencode job (`OPENCODE_PROVIDER_KEY`), each runtime-gated.
|
|
317
|
+
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. Persisted to `bkit.cloudAgents`; install prints secrets + permissions + dashboard checklist (`bkit-auto-setup`). Shipped `bkit-cloud.yml` carries claude job (`ANTHROPIC_API_KEY` repo secret or federation repo variables — `.bkit/cloud.md` § Claude — workload identity federation) and opencode job (`OPENCODE_PROVIDER_KEY`), each runtime-gated.
|
|
317
318
|
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.issueTracker` / `bkit.depUpdater` / `bkit.cloudAgents`). Advisory stays quiet.
|
|
318
319
|
|
|
319
320
|
Tracker and cloud agents reverse by re-running install with the other flag. Updater files stay until you delete them.
|
|
@@ -322,7 +323,7 @@ Tracker and cloud agents reverse by re-running install with the other flag. Upda
|
|
|
322
323
|
|
|
323
324
|
## Setup tips
|
|
324
325
|
|
|
325
|
-
`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
|
|
326
|
+
`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`.
|
|
326
327
|
|
|
327
328
|
```bash
|
|
328
329
|
bkit tips # top three
|
|
@@ -338,8 +339,8 @@ bkit tips --all # every firing tip
|
|
|
338
339
|
| Detection | Local only — files, settings, environment; no network. A tip clears once its local half exists; dashboard steps live in the tip text. |
|
|
339
340
|
| Reuse | A tip for a gap an advisory already detects calls that advisory's detector — tip and advisory never disagree. |
|
|
340
341
|
| Artifact | `bkit install` / `check` / `upgrade` / `doctor` list every firing tip, with its id, in `.bkit/advisories.md` § Setup tips and the console banner: line, why, caution, ask-your-agent sentence, agent steps. |
|
|
341
|
-
| Star line | `Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!` (markdown link) closes bare `bkit tips`, after the tips and outside the cap; in a phase workflow it follows the tip, and the silence line follows it. Never under `--workflow=audit` / `utility` (those agents often run back to back), in `.bkit/advisories.md` or the console banner. |
|
|
342
|
-
| Silence | Root `package.json` `bkit.ignoreAdvisories`: a tip id (a workflow's `## bkit Tips` ends with `` Want to silence these tips
|
|
342
|
+
| Star line | `Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!` (markdown link) closes bare `bkit tips`, after the tips and outside the cap; in a phase workflow it follows the tip with `Do you like bkit?` in bold, and the silence line follows it. Never under `--workflow=audit` / `utility` (those agents often run back to back), in `.bkit/advisories.md` or the console banner. |
|
|
343
|
+
| Silence | Root `package.json` `bkit.ignoreAdvisories`: a tip id (a workflow's `## bkit Tips` ends with `` **Want to silence these tips?** Ask your agent to "add `<id>` and `bkit-star` to `bkit.ignoreAdvisories` in package.json". ``, naming what it showed), or an advisory id the tip reuses, silences the tip and those advisories together; both show in the suppressed block. `bkit-star` (or the older `star`) silences the star line. |
|
|
343
344
|
| Exit | Always 0. Prints nothing when no tip fires and no star line shows. |
|
|
344
345
|
|
|
345
346
|
## Doctor
|
|
@@ -353,7 +354,7 @@ bkit doctor
|
|
|
353
354
|
|
|
354
355
|
Use `bkit doctor` to:
|
|
355
356
|
|
|
356
|
-
- Check `BKIT_GH_TOKEN` presence in shell (GitHub MCP auth) and the cloud-router (`ANTHROPIC_API_KEY`
|
|
357
|
+
- Check `BKIT_GH_TOKEN` presence in shell (GitHub MCP auth) and the cloud-router claude credential (`ANTHROPIC_API_KEY` repo secret or federation repo variables; flags a key shadowing federation and an adopted `bkit-cloud.yml` too old for federation).
|
|
357
358
|
- Surface `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
|
|
358
359
|
- Preview all advisories `bkit install` would show post-install, without triggering writes.
|
|
359
360
|
- Verify environment ready before `bkit install` on new machine.
|
|
@@ -396,7 +397,7 @@ bkit uninstall --nuke --yes
|
|
|
396
397
|
| `fully-managed` | Always deleted (bkit owns 100% of the file). |
|
|
397
398
|
| `markered-text` | bkit block stripped; consumer content above/below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
|
|
398
399
|
| `byte-equal-text` | Deleted only if current hash matches the hash `.bkit/version` recorded when bkit last wrote it (`canonicalHashes`). Consumer modifications → preserved. `canonicalHashes` is internal state `bkit check` does not verify: a hand-edited or corrupted entry makes uninstall keep that file as consumer-modified (`--force` deletes it anyway) and upgrade's whole-file diff report a conflict instead of updating it. Rendered `.bkit/*.md` skip that diff: upgrade always re-renders them, and `bkit check` flags a hand edit. |
|
|
399
|
-
| `json` | bkit's keys stripped; consumer keys preserved. `.mcp.json` / `.cursor/mcp.json`: only bkit's tracker entry is removed, and only while it still equals the template. `.opencode/opencode.json`: every `mcp` tracker entry (`github`, `linear`) and every `provider` block of a supported provider is removed while it still equals what install renders — all the earlier installs left, not just the active one; an edited entry is kept whole. File deleted when nothing is left. |
|
|
400
|
+
| `json` | bkit's keys stripped; consumer keys preserved. `.mcp.json` / `.cursor/mcp.json`: only bkit's tracker entry is removed, and only while it still equals the template. `.opencode/opencode.json`: every `mcp` tracker entry (`github`, `linear`, `jira`) and every `provider` block of a supported provider is removed while it still equals what install renders — all the earlier installs left, not just the active one; an edited entry is kept whole. File deleted when nothing is left. |
|
|
400
401
|
|
|
401
402
|
### Idempotency
|
|
402
403
|
|