@cbartens/bkit 5.5.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 +2 -2
- package/.bkit/core/.agents/rules.md +17 -1
- package/.bkit/core/.bkit/README.md +1 -1
- package/.bkit/core/.bkit/cloud.md +2 -2
- package/.bkit/core/.bkit/install.md +3 -4
- package/.bkit/core/.bkit/prompts.md +29 -14
- package/.bkit/core/.bkit/templates.md +34 -9
- package/.bkit/core/.bkit/trackers.md +10 -1
- package/.bkit/core/.bkit/workflows.md +10 -9
- package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
- package/.bkit/core/engine/checks/after/github.ts +24 -73
- package/.bkit/core/engine/checks/after/index.ts +0 -5
- package/.bkit/core/engine/checks/after/tools.ts +1 -1
- package/.bkit/core/engine/checks/tips/index.ts +5 -2
- package/.bkit/core/engine/commands/workflow/issues.ts +26 -47
- package/.bkit/core/engine/commands/workflow/repo.ts +2 -0
- package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
- package/.bkit/core/engine/install/modules/core.ts +77 -6
- package/.bkit/core/engine/shared/settings.ts +46 -14
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
- package/.bkit/core/prompts/bkit-design-generate.md +2 -0
- package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
- package/.bkit/core/workflows/bkit-build.md +3 -3
- package/.bkit/core/workflows/bkit-debug.md +3 -3
- package/.bkit/core/workflows/bkit-design.md +3 -3
- package/.bkit/core/workflows/bkit-plan.md +3 -3
- package/.bkit/core/workflows/bkit-ship.md +3 -3
- package/.bkit/shared/docs/deployments.md +5 -17
- package/.bkit/shared/docs/testing.md +11 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -83
- package/.bkit/templates/.husky/pre-push +48 -9
- 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/prettier/bkit-insert-ignore.mjs +49 -29
- package/CHANGELOG.md +30 -0
- package/README.md +9 -0
- package/dist/checks/after/ci-yml.js +0 -1
- package/dist/checks/after/github.js +24 -71
- package/dist/checks/after/index.js +1 -6
- package/dist/checks/after/tools.js +1 -1
- package/dist/checks/tips/index.js +4 -2
- package/dist/commands/workflow/issues.js +25 -46
- package/dist/commands/workflow/repo.js +1 -0
- package/dist/commands/workflow/worktrees.js +74 -13
- package/dist/install/modules/core.js +81 -6
- package/dist/shared/settings.js +23 -10
- package/package.json +4 -2
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
package/.bkit/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# bkit — Agent Workflow System
|
|
2
2
|
|
|
3
|
-
<!-- bkit:managed v5.5.
|
|
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.
|
|
@@ -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
|
|
|
@@ -125,7 +126,8 @@
|
|
|
125
126
|
- **Debug on demand:** Re-runs failing E2E / `@live` tier tests against deployed boundary. NEVER purely local runs.
|
|
126
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.
|
|
127
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).
|
|
128
|
-
- **New worktree:** `git worktree add` does NOT carry direnv trust → run `direnv allow` BEFORE first test / verify / build command. Hand-made worktrees also lack gitignored inputs (env files, installed dependencies, build outputs, tool assets) → bring in BEFORE first build: copy `package.json` `bkit.
|
|
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.
|
|
129
131
|
|
|
130
132
|
#### Security & Data
|
|
131
133
|
|
|
@@ -165,3 +167,17 @@
|
|
|
165
167
|
### Universal Rules
|
|
166
168
|
|
|
167
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.
|
|
@@ -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
|
|
|
@@ -227,8 +227,7 @@ After writes, bkit re-runs credential and environment checks — some only accur
|
|
|
227
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. |
|
|
228
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. |
|
|
229
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.
|
|
231
|
-
| `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`. |
|
|
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`. |
|
|
232
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). |
|
|
233
232
|
| `dep-updater-both` | Both updater configs are present. Keep one. |
|
|
234
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). |
|
|
@@ -340,8 +339,8 @@ bkit tips --all # every firing tip
|
|
|
340
339
|
| Detection | Local only — files, settings, environment; no network. A tip clears once its local half exists; dashboard steps live in the tip text. |
|
|
341
340
|
| Reuse | A tip for a gap an advisory already detects calls that advisory's detector — tip and advisory never disagree. |
|
|
342
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. |
|
|
343
|
-
| 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. |
|
|
344
|
-
| 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. |
|
|
345
344
|
| Exit | Always 0. Prints nothing when no tip fires and no star line shows. |
|
|
346
345
|
|
|
347
346
|
## Doctor
|
|
@@ -93,7 +93,7 @@ maxTurns: <int> # safety cap on agent turns (NOT runtime budget)
|
|
|
93
93
|
| Effort | Claude model | Rationale |
|
|
94
94
|
| --- | --- | --- |
|
|
95
95
|
| `low` | `claude-haiku-5-5` | Default Haiku rung. No agent runs here today: the `*-summary` writers pin `claude-haiku-5-5` at `high` (they decide each phase's verdict; `low` → `high` buys +11.4 CursorBench points for $0.24/task). |
|
|
96
|
-
| `medium` | `claude-sonnet-5-5` | Single-shot writers, scope audits, light utilities. Source modifiers with test loops pin `claude-sonnet-5-5` at `high` (Anthropic: `medium` for well-specified agentic tasks, `high` for harder or longer ones). |
|
|
96
|
+
| `medium` | `claude-sonnet-5-5` | Single-shot writers, scope audits, light utilities. Source modifiers with test loops and multi-doc writers pin `claude-sonnet-5-5` at `high` (Anthropic: `medium` for well-specified agentic tasks, `high` for harder or longer ones). |
|
|
97
97
|
| `high` | `claude-opus-5-5` | Adversarial review, observability. 1M context. |
|
|
98
98
|
| `xhigh` | `claude-opus-5-5` | Top-of-pipeline synthesizers. Same model ID as `high`; differs by `effort: xhigh` thinking-budget allocation. |
|
|
99
99
|
| `max` | `claude-opus-5-5` | Same model as `xhigh`; differs by `effort: max` thinking-budget allocation. Reserved tier — escalate from `xhigh` only after observed truncation. |
|
|
@@ -120,7 +120,7 @@ Pinning `model:` locks agent model regardless of orchestrator session. Without p
|
|
|
120
120
|
| --- | --- | --- |
|
|
121
121
|
| `name` | `@name` invocation in `commands/*.md` requires exact match | Never deviate. |
|
|
122
122
|
| `description` | Surfaces in picker and `Agent` tool catalog; one-sentence scope statement only — H1 inside the markdown body carries the deliverable name (`# Build Skills Installed`, `# Plan Review`, etc.). | Keep terse; never duplicate the H1. |
|
|
123
|
-
| `effort` | Maps to a Claude model via the table above, with depth-sensitive lenses (`bkit-plan-review-2`, `bkit-plan-scope-check-1`) pinning opus even at `medium` effort, and
|
|
123
|
+
| `effort` | Maps to a Claude model via the table above, with depth-sensitive lenses (`bkit-plan-review-2`, `bkit-plan-scope-check-1`) pinning opus even at `medium` effort, and three groups pinning a cheaper model at `high`: `*-summary` (haiku), source modifiers with test loops (sonnet) and multi-doc writers (sonnet). Parallel fan-outs (triplets `-1`/`-2`/`-3` for ideate + plan-review; pairs `-1`/`-2` for review / scope-check / challenge / ship-update-docs+summary) mix `high`/`medium` effort to spread reasoning depth on Claude. On Cursor, the same fan-outs use different `model:` values for cross-family diversity. | `high` for adversarial / generative / cross-codebase work, phase-verdict summarizers, source modifiers with test loops and multi-doc writers. `xhigh` for whole-doc rewrites and Final-strategy diagnostics. |
|
|
124
124
|
| `model` | Explicit Claude model pin per the effort mapping table above. Locks the model independent of the orchestrator's session default — without it, subagents inherit user's Claude Code default and `xhigh` thinking depth + 1M context disappear if the user runs Sonnet. | Brittle by version (must update on every model rev), but explicit and discoverable. Never use family alias (`opus` / `sonnet`) — they don't lock context-window variant. |
|
|
125
125
|
| `tools` | Minimum capability sandbox. Enforced on Claude (native). Cursor: `bkit install` T3 transform passes the field through verbatim, but Cursor CLI 2026.10.01 does not enforce it (measured: a `tools: [Read]` subagent still has `Shell`, `Write`, `StrReplace`, and every MCP tool via `CallDynamicTool`). Removing `Edit`/`Bash` makes an agent provably non-mutating on Claude only. | Add `WebFetch`/`WebSearch` only for genuine ecosystem research (`bkit-design-review-1/2`) or to pin a probe against vendor docs before running it (`bkit-design-spike`). |
|
|
126
126
|
| `permissionMode: acceptEdits` | End-to-end runs of `/design`/`/plan`/`/build`/`/debug`/`/ship` would break if mid-workflow prompt blocked an agent. Bash auto-approve surface lives in `.claude/settings.json` (`workflows.md` § Permissions) | Never deviate inside the pipeline; one-off ad-hoc invocations may use stricter modes. |
|
|
@@ -132,8 +132,8 @@ Pinning `model:` locks agent model regardless of orchestrator session. Without p
|
|
|
132
132
|
| Tier | Use for | Example agents |
|
|
133
133
|
| --- | --- | --- |
|
|
134
134
|
| `low` | Pure synthesis with no verdict riding on it. | (none currently) |
|
|
135
|
-
| `medium` | Single-shot writers, scope audits, skill curators
|
|
136
|
-
| `high` | Adversarial review, parallel-fan-out high-effort slots, observability instrumentation, feasibility research, ledger / roadmap judgement against the codebase. Also phase-verdict summaries (`*-summary`, haiku model)
|
|
135
|
+
| `medium` | Single-shot writers, scope audits, skill curators. Some `medium`-effort agents pin opus (depth-sensitive lens) — see Models table footnote. | `bkit-debug-abort-handover`, `bkit-plan-complexity-check`, `bkit-plan-scope-check-1`, `bkit-plan-scope-check-2`, `bkit-plan-review-2`, `bkit-design-brainstorm-ideate-2`, `bkit-design-review-2`, `bkit-build-install-skills`, `bkit-utility-compress-markdown` |
|
|
136
|
+
| `high` | Adversarial review, parallel-fan-out high-effort slots, observability instrumentation, feasibility research, ledger / roadmap judgement against the codebase. Also phase-verdict summaries (`*-summary`, haiku model), source modifiers with test loops — fix executors included, even with clear input — and multi-doc writers (sonnet model). | `*-summary`, `bkit-build-plan-execute`, `bkit-build-plan-gaps-remediate`, `bkit-build-challenge-remediate`, `bkit-build-challenge-tests`, `bkit-debug-failure-reproduce`, `bkit-debug-failure-remediate`, `bkit-ship-conflict-resolve`, `bkit-build-plan-verify`, `bkit-build-plan-current`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-design-brainstorm-ideate-1`, `bkit-design-brainstorm-ideate-3`, `bkit-design-organise`, `bkit-design-review-1`, `bkit-design-spike`, `bkit-plan-review-1`, `bkit-plan-review-3`, `bkit-plan-complexity-split`, `bkit-ship-update-docs`, `bkit-utility-update-documentation`, `bkit-ship-deferred-sweep`, `bkit-utility-update-deferrals`, `bkit-utility-update-failures`, `bkit-utility-update-decisions`, `bkit-utility-update-knowledge`, `bkit-utility-update-roadmap`, `bkit-utility-update-tracker` |
|
|
137
137
|
| `xhigh` | Top-of-pipeline synthesizers and highest-leverage adversarial / diagnostic agents — depth here compounds downstream. Model-gated (Opus-only on current models); pin `model: opus` if dispatched from a Sonnet orchestrator. | `bkit-design-generate`, `bkit-plan-generate`, `bkit-plan-update`, `bkit-design-update`, `bkit-audit-generate`, `bkit-build-challenge-reconcile`, `bkit-debug-failure-diagnose`, `bkit-debug-failure-soak` |
|
|
138
138
|
| `max` | Reserved — only if `xhigh` proves insufficient on a recurring failure mode. Costliest tier; one-shot orchestrator-level work only. Lazy-escalate from `xhigh` based on observed truncation, never preemptively. | (none currently) |
|
|
139
139
|
|
|
@@ -142,12 +142,13 @@ Pinning `model:` locks agent model regardless of orchestrator session. Without p
|
|
|
142
142
|
<!-- prettier-ignore -->
|
|
143
143
|
| Pattern | Tools | Agents |
|
|
144
144
|
| --- | --- | --- |
|
|
145
|
-
| Pure summarizer | `Read, Write, Edit` | `bkit-build-summary`, `bkit-debug-summary`, `bkit-design-summary`, `bkit-plan-summary`, `bkit-ship-summary
|
|
145
|
+
| Pure summarizer | `Read, Write, Edit` | `bkit-build-summary`, `bkit-debug-summary`, `bkit-design-summary`, `bkit-plan-summary`, `bkit-ship-summary` |
|
|
146
|
+
| Handover writer (with shell) | `Read, Write, Edit, Bash` | `bkit-debug-abort-handover` |
|
|
146
147
|
| Read-only reviewer | `Read, Grep, Glob, Write` | `bkit-design-brainstorm-ideate-*`, `bkit-plan-complexity-check` |
|
|
147
|
-
| Stub-replace reviewer | `Read, Grep, Glob, Write, Edit` | `bkit-plan-review-*`, `bkit-plan-scope-check-*`, `bkit-plan-complexity-split`, `bkit-
|
|
148
|
+
| Stub-replace reviewer | `Read, Grep, Glob, Write, Edit` | `bkit-plan-review-*`, `bkit-plan-scope-check-*`, `bkit-plan-complexity-split`, `bkit-utility-compress-markdown` |
|
|
148
149
|
| Stub-replace + log-append reviewer | `Read, Grep, Glob, Write, Edit, Bash` | `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-build-plan-verify`, `bkit-build-plan-current`, `bkit-ship-deferred-sweep` |
|
|
149
150
|
| Doc rewriter (cp + Edit) | `Read, Grep, Glob, Edit, Bash` | `bkit-design-update`, `bkit-plan-update`, `bkit-build-challenge-reconcile` |
|
|
150
|
-
| Doc writer (with shell) | `Read, Grep, Glob, Write, Edit, Bash` | `bkit-design-organise`, `bkit-ship-update-docs`, `bkit-utility-update-documentation` |
|
|
151
|
+
| Doc writer (with shell) | `Read, Grep, Glob, Write, Edit, Bash` | `bkit-design-generate`, `bkit-plan-generate`, `bkit-design-organise`, `bkit-ship-update-docs`, `bkit-utility-update-documentation` |
|
|
151
152
|
| Source modifier (with test gate) | `Read, Grep, Glob, Write, Edit, Bash` | `bkit-build-plan-execute`, `bkit-build-plan-gaps-remediate`, `bkit-build-challenge-remediate`, `bkit-build-challenge-tests`, `bkit-debug-failure-reproduce`, `bkit-debug-failure-remediate`, `bkit-ship-conflict-resolve` |
|
|
152
153
|
| Skill-installer / Bash-only utility | `Read, Grep, Glob, Bash` | `bkit-build-install-skills` |
|
|
153
154
|
| Tracker reader (read-only MCP) | `Read, Grep, Glob, Write, Edit, Bash` + per tracker: github `mcp__github__list_issues, mcp__github__issue_read`; linear `mcp__linear__list_issues, mcp__linear__get_issue`; jira `mcp__jira__searchJiraIssuesUsingJql, mcp__jira__getJiraIssue`; none — | `bkit-utility-update-roadmap` |
|
|
@@ -171,8 +172,8 @@ Pinning `model:` locks agent model regardless of orchestrator session. Without p
|
|
|
171
172
|
| --- | --- | --- | --- | --- |
|
|
172
173
|
| **S** | **50** | 3-10 turns | Pure synthesizers reading 1-3 run artifacts and writing one verdict. | `*-summary` |
|
|
173
174
|
| **M** | **100** | 5-25 turns | Reviewers and generators reading a few docs and writing one, scope / complexity checks, single-pass utilities, install, handover writers. | `bkit-design-brainstorm-ideate-*`, `bkit-design-review-*`, `bkit-design-generate`, `bkit-design-organise`, `bkit-plan-review-*`, `bkit-plan-complexity-check`, `bkit-plan-complexity-split`, `bkit-plan-scope-check-*`, `bkit-build-install-skills`, `bkit-debug-abort-handover`, `bkit-utility-compress-markdown` |
|
|
174
|
-
| **L** | **200** | 30-60 turns | Source modifiers with test loops, plan executor — iterative edit→`pnpm bkit:gate:static-unit`→edit cycles; probe-code runners; investigators sweeping a diff, its callers or the codebase; whole-doc rewriters; per-cycle doc sync. | `bkit-build-plan-execute`, `bkit-build-plan-gaps-remediate`, `bkit-build-challenge-remediate`, `bkit-debug-failure-remediate`, `bkit-debug-failure-soak`, `bkit-ship-conflict-resolve`, `bkit-design-spike`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-build-challenge-reconcile`, `bkit-build-challenge-tests`, `bkit-build-plan-verify`, `bkit-build-plan-current`, `bkit-debug-failure-reproduce`, `bkit-debug-failure-diagnose`, `bkit-ship-deferred-sweep`, `bkit-plan-
|
|
175
|
-
| **XL** | **400** | 60-180 turns | Whole-surface sweeps: every probe step of one audit template against repo and live systems; every row of a jsonl ledger, the roadmap board or the doc catalog re-checked against code, docs and tracker. | `bkit-audit-generate`, `bkit-utility-update-*` |
|
|
175
|
+
| **L** | **200** | 30-60 turns | Source modifiers with test loops, plan executor — iterative edit→`pnpm bkit:gate:static-unit`→edit cycles; probe-code runners; investigators sweeping a diff, its callers or the codebase; whole-doc rewriters; per-cycle doc sync. | `bkit-build-plan-execute`, `bkit-build-plan-gaps-remediate`, `bkit-build-challenge-remediate`, `bkit-debug-failure-remediate`, `bkit-debug-failure-soak`, `bkit-ship-conflict-resolve`, `bkit-design-spike`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-build-challenge-reconcile`, `bkit-build-challenge-tests`, `bkit-build-plan-verify`, `bkit-build-plan-current`, `bkit-debug-failure-reproduce`, `bkit-debug-failure-diagnose`, `bkit-ship-deferred-sweep`, `bkit-plan-update`, `bkit-design-update`, `bkit-ship-update-docs` |
|
|
176
|
+
| **XL** | **400** | 60-180 turns | Whole-surface sweeps: every probe step of one audit template against repo and live systems; every row of a jsonl ledger, the roadmap board or the doc catalog re-checked against code, docs and tracker; every citation in a plan's design, audit and issue inputs re-checked against code before the plan is written. | `bkit-audit-generate`, `bkit-plan-generate`, `bkit-utility-update-*` |
|
|
176
177
|
|
|
177
178
|
**Tier assignment is canonical** — per-agent rows in § Models. Cap hit at any tier → agent stuck (retry loop, infinite re-read) — orchestrator verdict-validation retry handles partial recovery.
|
|
178
179
|
|
|
@@ -208,7 +209,7 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
208
209
|
| `bkit-design-summary` | `claude-haiku-5-5` | `composer-2.5` | `z-ai/glm-5.3-flash` | `deepseek-v4.1-flash` | `glm-5.3-flash` | `deepseek-v4.1-flash` | `gpt-6-luna` | `gemini-3.8-flash` | `high` | 50 | summary writer |
|
|
209
210
|
| `bkit-design-generate` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `xhigh` | 100 | generate design from brainstorms (top-of-pipeline synthesizer; whole-doc rewrite) |
|
|
210
211
|
| `bkit-plan-complexity-check` | `claude-sonnet-5-5` | `composer-2.5` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-5.6-terra` | `gemini-3.8-pro` | `medium` | 100 | complexity check |
|
|
211
|
-
| `bkit-plan-generate` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `xhigh` |
|
|
212
|
+
| `bkit-plan-generate` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `xhigh` | 400 | plan draft generator (top-of-pipeline synthesizer) |
|
|
212
213
|
| `bkit-audit-generate` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `xhigh` | 400 | audit report from one template (top-of-pipeline synthesizer) |
|
|
213
214
|
| `bkit-plan-review-1` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `high` | 100 | review slot 1 (tightness + design-coverage) |
|
|
214
215
|
| `bkit-plan-review-2` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `medium` | 100 | review slot 2 (dependency-correctness + design-coverage; depth-sensitive lens — both opus) |
|
|
@@ -236,7 +237,7 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
236
237
|
| `bkit-debug-failure-soak` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `moonshotai/kimi-k3` | `kimi-k3` | `kimi-k3` | `kimi-k3` | `gpt-6-astra` | `gemini-3.8-pro` | `xhigh` | 200 | soak fix — one accumulating-context instrument-or-fix step per iteration against the live boundary (orchestrator re-runs tests + loops) |
|
|
237
238
|
| `bkit-debug-summary` | `claude-haiku-5-5` | `composer-2.5` | `z-ai/glm-5.3-flash` | `deepseek-v4.1-flash` | `glm-5.3-flash` | `deepseek-v4.1-flash` | `gpt-6-luna` | `gemini-3.8-flash` | `high` | 50 | summary writer |
|
|
238
239
|
| `bkit-ship-summary` | `claude-haiku-5-5` | `composer-2.5` | `z-ai/glm-5.3-flash` | `deepseek-v4.1-flash` | `glm-5.3-flash` | `deepseek-v4.1-flash` | `gpt-6-luna` | `gemini-3.8-flash` | `high` | 50 | summary writer |
|
|
239
|
-
| `bkit-ship-update-docs` | `claude-
|
|
240
|
+
| `bkit-ship-update-docs` | `claude-sonnet-5-5` | `composer-2.5` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-5.6-terra` | `gemini-3.8-pro` | `high` | 200 | sync cataloged docs (multi-doc writer) |
|
|
240
241
|
| `bkit-ship-conflict-resolve` | `claude-sonnet-5-5` | `composer-2.5` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-5.6-terra` | `gemini-3.8-pro` | `high` | 200 | mechanical rebase-conflict resolver (source modifier with test loop) |
|
|
241
242
|
| `bkit-ship-deferred-sweep` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `high` | 200 | pre-merge completeness gate — intended-vs-actual + declared-deferral resurface |
|
|
242
243
|
| `bkit-utility-update-deferrals` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `high` | 400 | deferrals update |
|
|
@@ -246,7 +247,7 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
246
247
|
| `bkit-utility-update-roadmap` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `high` | 400 | roadmap analysis |
|
|
247
248
|
| `bkit-utility-update-tracker` | `claude-opus-5-5` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-6-astra` | `gemini-3.8-pro` | `high` | 400 | tracker update |
|
|
248
249
|
| `bkit-utility-compress-markdown` | `claude-sonnet-5-5` | `composer-2.5` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-5.6-terra` | `gemini-3.8-pro` | `medium` | 100 | token-optimize markdown |
|
|
249
|
-
| `bkit-utility-update-documentation` | `claude-sonnet-5-5` | `composer-2.5` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-5.6-terra` | `gemini-3.8-pro` | `
|
|
250
|
+
| `bkit-utility-update-documentation` | `claude-sonnet-5-5` | `composer-2.5` | `deepseek/deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `gpt-5.6-terra` | `gemini-3.8-pro` | `high` | 400 | doc sync (multi-doc writer) |
|
|
250
251
|
|
|
251
252
|
**Effort vs maxTurns vs model — three independent knobs:**
|
|
252
253
|
|
|
@@ -294,6 +295,20 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
294
295
|
|
|
295
296
|
**Inlining-drift risk.** Sonnet more prone than Opus to inlining subagent work when tractable (review / scope-check); `rules.md` § Orchestrators + per-command CAUTION mitigate. Observed → bump command to Opus (not higher Sonnet reasoning). Cursor Cloud automation: `composer-2.5` for metadata / API plumbing; launched agent runs orchestrator model from table.
|
|
296
297
|
|
|
298
|
+
**Claude Code session setup** — orchestrator runs on the session model + effort; subagents ignore both (`model:` / `effort:` frontmatter wins over session level).
|
|
299
|
+
|
|
300
|
+
<!-- prettier-ignore -->
|
|
301
|
+
| Goal | How |
|
|
302
|
+
| --- | --- |
|
|
303
|
+
| Model per phase | Launch on the `Anthropic` cell above before the first prompt: `claude --model claude-opus-5-5` → `/bkit-design`, `/bkit-plan`, `/bkit-debug`; `claude --model claude-sonnet-5-5` → `/bkit-build`, `/bkit-ship`. Mid-session `/model` re-reads the whole conversation uncached (cache is per model). |
|
|
304
|
+
| Fable, by hand | `claude --model claude-fable-5-1` (2.5× `claude-opus-5-5`), outside any `/bkit-*` run: (1) refine a fuzzy idea into a brief before `/bkit-design` → start `/bkit-design` in a fresh `claude-opus-5-5` session; (2) `/bkit-debug` stuck on a bug → work it from `docs/plans/{YYYYMM}/logs/{FID}/debug-handover.md`, `/effort xhigh`. No orchestrator or agent pins Fable. |
|
|
305
|
+
| Effort `medium` | Claude Code default for `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5` — set nothing. Top-level `effortLevel` in `~/.claude/settings.json` does NOT apply to these models; a level `/effort` saves lands in `~/.claude/settings.json` `modelSettings.<model>.effortLevel` and does. bkit ships no `effortLevel`. |
|
|
306
|
+
| One session | `claude --effort <level>` at launch, or `/effort <level>` in-session. |
|
|
307
|
+
| One repo | `"effortLevel": "<level>"` in `.claude/settings.local.json` (you only) or `.claude/settings.json` (whole team) — applies to every model, outranks `~/.claude/settings.json`. |
|
|
308
|
+
|
|
309
|
+
- NEVER set `CLAUDE_CODE_EFFORT_LEVEL` — outranks subagent `effort:` frontmatter → every subagent runs one level, § Effort tiers ladder gone.
|
|
310
|
+
- NEVER set `maxEffortLevel` below `xhigh` — caps subagent `effort:` frontmatter → `xhigh` agents (§ Effort tiers) run at the cap.
|
|
311
|
+
|
|
297
312
|
## Design Phase
|
|
298
313
|
|
|
299
314
|
<!-- prettier-ignore -->
|
|
@@ -315,7 +330,7 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
315
330
|
<!-- prettier-ignore -->
|
|
316
331
|
| Agent | Scope |
|
|
317
332
|
| --- | --- |
|
|
318
|
-
| `bkit-plan-generate` | Read design and / or audit reports + template + docs → write new plan draft. Design absent and audits present is valid. Neither present → the issue is the source: a change-shape issue's `Narrative`, `Success Criteria`, `Edge Cases`, matrix rows and tasks carry over verbatim (template § `Spec`). Audit contract: if input includes audit-scope directives, plan covers only those findings; the rest of each report is context only, not backlog. Workstream contract: if input includes `**Workstream:**` directive, plan covers only that workstream's `## Scope` content unless stated otherwise; surface `**Requires:**` at top of plan. Process = one step per major template section in **dependency (authoring) order, not template document order** — derived sections (Breaking Changes, Supersession, Security, Docs, Rollback) follow Architecture rather than preceding it: Context → Acceptance Scenario → Derived Test Matrix → Open Questions → Pre-Flight → Alternatives → Data Schema → Reuse Inventory → Architecture (+ `decisions.jsonl`) → Breaking Changes → Supersession → Security → Docs → Rollback → Out of Scope → Suggested Scope Expansion → Agent Execution Runbook (pick tests from matrix only; each row → exactly one task; every task has `**Done when:**`) → Verification. Human-confirmation checkboxes stay unchecked at generate. Every `Open Questions & Assumptions` question carries 2-3 concrete options with trade-offs, a `Recommended` option and a `Default if unanswered` (design's answer carried forward where it has one); a bare question is not acceptable output. `Out of Scope` entries must be `Exempt` (genuinely-additive), else a runbook task. `Suggested Scope Expansion` filled per template (candidates, not tasks); no tracker / ledger scan here — surface overlaps come from the orchestrator Fetch Context step via `bkit-plan-review-1`. |
|
|
333
|
+
| `bkit-plan-generate` | Read design and / or audit reports + template + docs → write new plan draft. Design absent and audits present is valid. Neither present → the issue is the source: a change-shape issue's `Narrative`, `Success Criteria`, `Edge Cases`, matrix rows and tasks carry over verbatim (template § `Spec`). Audit contract: if input includes audit-scope directives, plan covers only those findings; the rest of each report is context only, not backlog. Workstream contract: if input includes `**Workstream:**` directive, plan covers only that workstream's `## Scope` content unless stated otherwise; surface `**Requires:**` at top of plan. Process = one step per major template section in **dependency (authoring) order, not template document order** — derived sections (Breaking Changes, Supersession, Security, Docs, Rollback) follow Architecture rather than preceding it: Context → Acceptance Scenario → Derived Test Matrix → Open Questions → Pre-Flight → Alternatives → Data Schema → Reuse Inventory → Architecture (+ `decisions.jsonl`) → Breaking Changes → Supersession → Security → Docs → Rollback → Out of Scope → Suggested Scope Expansion → Agent Execution Runbook (pick tests from matrix only; each row → exactly one task; every task has `**Done when:**`) → Verification. Human-confirmation checkboxes stay unchecked at generate. Each section group lands in the draft before reading for the next group starts, so a turn-cap stop leaves finished groups on disk, not an all-`PENDING` stub. Every `Open Questions & Assumptions` question carries 2-3 concrete options with trade-offs, a `Recommended` option and a `Default if unanswered` (design's answer carried forward where it has one); a bare question is not acceptable output. `Out of Scope` entries must be `Exempt` (genuinely-additive), else a runbook task. `Suggested Scope Expansion` filled per template (candidates, not tasks); no tracker / ledger scan here — surface overlaps come from the orchestrator Fetch Context step via `bkit-plan-review-1`. |
|
|
319
334
|
| `bkit-plan-review-1` | Read-only critique — tightness lens; effort slot 1 (`high`). Parallel with `-2` and `-3`. Missing or vague `**Done when:**` on any task → CRITICAL. `Blocking` out-of-scope deferral (in-scope work parked in `Out of Scope`) → CRITICAL. Audits `Open Questions & Assumptions` format — question missing options, `Recommended` or `Default if unanswered` → OPTIONAL (mirrors `bkit-design-review-2` on the design side). Surfaces `Suggested Scope Expansion` candidates from the `related-*.md` context. FAIL only for broken template structure (sections missing / reordered) — content gaps, drift included, are CRITICAL → CONCERNS so `bkit-plan-update` repairs them; `-2` shares the mapping. |
|
|
320
335
|
| `bkit-plan-review-2` | Same scope — dependency-correctness lens; effort slot 2 (`medium` effort, opus model — depth-sensitive lens). Plans carry no dependency fields, so the graph is derived: what each task produces and consumes, read against runbook order (template: build order). A consumer before its producer, or a prerequisite no task produces and the repo lacks, is CRITICAL. Reading declared `Requires:` / `After:` fields instead found no edges on every real plan and passed unchecked. |
|
|
321
336
|
| `bkit-plan-review-3` | Same scope — regression-risk lens; effort slot 3 (`high`). |
|
|
@@ -354,7 +369,7 @@ Canonical per-agent metadata — **single source of truth for model per agent**.
|
|
|
354
369
|
| `bkit-debug-failure-diagnose` | Investigate test / CI failure → diagnosis log; no fixes. Standard / Pivot / Final by attempt. Folds `docs/knowledge.jsonl` by `key`, highest `ts` wins → reads only winning rows where `status` is `ACTIVE` or absent → cites matching entries in `## Prior Knowledge` → uses them to seed hypotheses. Output uses append-only ReAct `Hypothesis {N}` blocks; refuted hypotheses must remain. |
|
|
355
370
|
| `bkit-debug-failure-remediate` | Apply diagnosis fix; lint / typecheck / test gate; may append `knowledge.jsonl`/`decisions.jsonl`. |
|
|
356
371
|
| `bkit-debug-failure-soak` | One accumulating context across iterations (reads its prior `debug-failure-soak-*-log.md`); applies the single next instrument-or-fix step against the failing boundary; refuses to theorise; adds `[DEBUG-OBSERVE]` scaffolding and strips every marker before declaring a fix (no-leak). Wired into `/bkit-debug` § Failure Remediate Soak (`DEBUG_MODE` = SOAK); the orchestrator re-runs the tests and loops it within `SOAK_ATTEMPT` (`MAX_SOAK_ATTEMPT`, reset to 0 on each SOAK entry). Flat append-only `DONE`/`BLOCKED` log. |
|
|
357
|
-
| `bkit-debug-abort-handover` | Read all prior diagnose / remediate / verify logs → handover doc + `deferrals.jsonl` append. Called from build / debug / ship Failure Paths. |
|
|
372
|
+
| `bkit-debug-abort-handover` | Read all prior diagnose / remediate / verify logs → handover doc + `failures.jsonl` / `deferrals.jsonl` append. Called from build / debug / ship Failure Paths. |
|
|
358
373
|
| `bkit-debug-summary` | Read-only verdict on debug loop outcome. |
|
|
359
374
|
|
|
360
375
|
## Ship Phase
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
|
|
15
15
|
## What each template is for
|
|
16
16
|
|
|
17
|
-
Adoption order = `bkit tips` order. Sections below: install steps and traps.
|
|
17
|
+
Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a repo shows a stack every worktree shares) → adopt it once a second worktree touches that stack. Sections below: install steps and traps.
|
|
18
18
|
|
|
19
19
|
<!-- prettier-ignore -->
|
|
20
20
|
| Template | What it's for | Skip it and |
|
|
@@ -38,6 +38,7 @@ Adoption order = `bkit tips` order. Sections below: install steps and traps.
|
|
|
38
38
|
| Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
|
|
39
39
|
| tmp/ prune | Each push deletes scratch files agents left in `tmp/` untouched for a week. | `tmp/` keeps growing; old logs and scratch files are never cleared. |
|
|
40
40
|
| Disk prune | Your own cleanup steps (build caches, Docker, simulators) run on commit, on push, and before a worktree is made on a low disk. bkit deletes nothing itself. | Caches fill the disk until no worktree can be made; every workflow stops. |
|
|
41
|
+
| Local stack lock | One run at a time on local services every worktree shares (Docker database, emulator); a second run waits and names the run holding them. | A reset or stop from one worktree wipes the stack under another worktree's test run; the failures look like real bugs. |
|
|
41
42
|
| Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
|
|
42
43
|
| Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
|
|
43
44
|
|
|
@@ -47,7 +48,7 @@ Adoption order = `bkit tips` order. Sections below: install steps and traps.
|
|
|
47
48
|
| Tool | Copy from | To | Output you commit |
|
|
48
49
|
| --- | --- | --- | --- |
|
|
49
50
|
| CI workflow | `.bkit/templates/.github/workflows/bkit-ci.yml` | `.github/workflows/bkit-ci.yml` | that file |
|
|
50
|
-
| CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/resolve-push-base.mjs
|
|
51
|
+
| CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/resolve-push-base.mjs` + `.test.mjs`, CI's push base, also run by pre-push; `check-accepted-divergences.mjs` + `accepted-divergences.json`; `check-dependency-audit.mjs` + `accepted-advisories.json`). `check-capstone.mjs` + `check-capstone.test.mjs` are required with `bkit-ci.yml`, not optional |
|
|
51
52
|
| Cloud-agent workflow | `.bkit/templates/.github/workflows/bkit-cloud.yml` | `.github/workflows/bkit-cloud.yml` | that file |
|
|
52
53
|
| Git hooks (Husky) | `.bkit/templates/.husky/pre-commit`, `.bkit/templates/.husky/pre-push` | `.husky/pre-commit`, `.husky/pre-push` | both files |
|
|
53
54
|
| Prettier ignore list | `.bkit/templates/.prettierignore` | `.prettierignore` | that file |
|
|
@@ -69,6 +70,7 @@ Adoption order = `bkit tips` order. Sections below: install steps and traps.
|
|
|
69
70
|
| Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
|
|
70
71
|
| tmp/ prune | `.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs` | `scripts/cleanup/` | that file |
|
|
71
72
|
| Disk prune | `.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs`, `bkit-disk-prune.machine.mjs` | `scripts/cleanup/bkit-disk-prune.mjs`, `~/.config/bkit/disk-prune.mjs` | `scripts/cleanup/bkit-disk-prune.mjs` only |
|
|
73
|
+
| Local stack lock | `.bkit/templates/scripts/ci/bkit-local-stack-lock.sh` | `scripts/ci/` | that file |
|
|
72
74
|
| Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
|
|
73
75
|
| Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
|
|
74
76
|
|
|
@@ -86,7 +88,7 @@ Placeholders. Copies keep them raw; replace each in your copy:
|
|
|
86
88
|
- `bkit install` / `bkit upgrade` refresh `.bkit/templates/` to the package's templates, unsubstituted. `bkit check` fails on a stale copy. `bkit uninstall` removes the folder, never an adopted copy.
|
|
87
89
|
- **What changed on upgrade.** `bkit upgrade` lists changed / added / removed template paths. For each one you adopted: `diff .bkit/templates/<path> <path>`, merge what you want (placeholder lines differ by design). `git diff .bkit/templates` in the upgrade commit = the package change.
|
|
88
90
|
- Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc) → ignore `.bkit/templates/`. The `.prettierignore`, `.vale.ini`, `slop-scan.config.json` and `.oxlintrc.json` templates already do; check your adopted copy does too.
|
|
89
|
-
- Templates are written in Node unless the tool they wrap already needs another runtime (graphify and Serena: Python + shell launchers; git hooks: POSIX `sh
|
|
91
|
+
- Templates are written in Node unless the tool they wrap already needs another runtime (graphify and Serena: Python + shell launchers; git hooks: POSIX `sh`; local stack lock: bash + perl, as shell runners source it).
|
|
90
92
|
- `bkit.depUpdater: "none"` → skips install-time absence advisory for updaters.
|
|
91
93
|
- No manifest key for any template. `docs/templates/bkit-audit-adoption.md` lists every template each run: adopted and wired, or not adopted and why.
|
|
92
94
|
|
|
@@ -183,7 +185,7 @@ Parallel lanes `bkit-tests-static` (typecheck, lint, prettier, Vale, slop, actio
|
|
|
183
185
|
|
|
184
186
|
- Install: nothing beyond the gate tool scripts above, a `test` script, and `packageManager` in `package.json` (`pnpm/action-setup` reads it; do not add `with: version:`).
|
|
185
187
|
- Adapt: `{{DEFAULT_BRANCH}}`, `{{NODE_VERSION}}`. Non-Node repo → replace the Node / pnpm setup, install and check steps with your stack's.
|
|
186
|
-
- Capstone: `bkit-tests-check` `needs:` every lane and runs on `!cancelled()`, never `always()`. Each lane you adopt from the reference goes into its `needs:` and its assert, or that lane's failure cannot red the merge. Its assert is `scripts/ci/check-capstone.mjs` (copy it and `check-capstone.test.mjs` from `.bkit/templates/scripts/ci/` with the workflow; REQUIRED — the step reds with a copy-the-script message when the file is missing, and never skips). The script reds on a lane that did not succeed, a lane that ran when the plan said skip, a lane that succeeded with 0 tests or a non-numeric count, and a plan that does not parse. It reads each lane's executed-test count once the lane writes one (the `Run Unit Tests` step comment shows the vitest form); `EMPTY_COUNT: warn` makes an unreported count a warning, a count of 0 a failure. Each lane you adopt goes into `LANES` and its `<LANE>_RESULT` / `<LANE>_RAN`
|
|
188
|
+
- Capstone: `bkit-tests-check` `needs:` every lane and runs on `!cancelled()`, never `always()`. Each lane you adopt from the reference goes into its `needs:` and its assert, or that lane's failure cannot red the merge. Its assert is `scripts/ci/check-capstone.mjs` (copy it and `check-capstone.test.mjs` from `.bkit/templates/scripts/ci/` with the workflow; REQUIRED — the step reds with a copy-the-script message when the file is missing, and never skips). The script reds on a lane that did not succeed, a lane that ran when the plan said skip, a lane that succeeded with 0 tests or a non-numeric count, and a plan that does not parse. It reads each lane's executed-test count once the lane writes one (the `Run Unit Tests` step comment shows the vitest form); `EMPTY_COUNT: warn` makes an unreported count a warning, a count of 0 a failure. Each lane you adopt goes into `LANES` and its `<LANE>_RESULT` / `<LANE>_RAN` variables. Renaming the job → set `bkit.capstoneJob`.
|
|
187
189
|
- Adopt a scaffold lane only when its tier exists (`docs/testing.md`). Each `# bkit-stub:<id> —` header raises an install advisory until you enable or delete that stub.
|
|
188
190
|
- Keep the `name: bkit-ci` line, or rename `workflows: [bkit-ci]` in `bkit-cloud.yml` and set `bkit.ciWorkflow` to the new file name.
|
|
189
191
|
- Keep `fetch-depth: 0` on the static lane: `slop:delta` checks the PR base out as a worktree.
|
|
@@ -199,7 +201,7 @@ Post-CI router: CI pass on `feat/**` → `/bkit-ship`, fail → `/bkit-debug`; f
|
|
|
199
201
|
|
|
200
202
|
## Git hooks — Husky
|
|
201
203
|
|
|
202
|
-
`pre-commit` runs `bkit:gate:format`; `pre-push` runs `bkit:gate:static-unit-integration` when package.json declares it, else `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits; `bkit:gate:min` on a min push),
|
|
204
|
+
`pre-commit` runs `bkit:gate:format`; `pre-push` runs `bkit check` first, so a drifted install fails in seconds, then `bkit:gate:static-unit-integration` when package.json declares it, else `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits; `bkit:gate:min` on a min push), plus the CI-suppressing-token guards and the `tmp/` prune (§ tmp/ prune). Each hook ends by starting the disk prune (§ Disk prune). Workflows care: they commit and push without `--no-verify`, so a failing hook stops a workflow. One exception: the throwaway `.worktrees/_land-{FID}` checkout that lands bookkeeping on `dev` (docs, logs, ledgers, `[skip ci]`) runs no hooks and logs that it skipped them. Reference: https://typicode.github.io/husky/.
|
|
203
205
|
|
|
204
206
|
```bash
|
|
205
207
|
pnpm add -D husky@^9.1.7 # plus "prepare": "husky" (§ Gate tool scripts)
|
|
@@ -211,6 +213,7 @@ chmod +x .husky/pre-commit .husky/pre-push
|
|
|
211
213
|
- Min push: every file changed since each pushed commit left `origin/dev` (else `origin/main`) matches `bkit.minPushPaths` (`package.json` globs: `*` one folder, `**` any depth; default `docs/plans/**`, `docs/*.jsonl`, `.bkit/*.jsonl`; `[]` = off) → `bkit:gate:min` replaces the full gate; `MIN_PUSH=1`. `bkit ci min-push` decides from files, never `[skip ci]` (a typed label; GitHub reads the last commit only). No files / unreadable range / no ref list → full gate.
|
|
212
214
|
- Min-push paths: files no code, build or test reads. Never `docs/**` (a doc can be test input). A test reading a ledger → into `bkit:gate:min`.
|
|
213
215
|
- `[skip ci]` guards: feature branch → blocked only while a PR is open (workflows push `[skip ci]` code heads mid-run). `dev` / `main` → blocked unless a min push: GitHub skips CI for the whole push.
|
|
216
|
+
- Slop base: `dev` push + `scripts/ci/lanes/resolve-push-base.mjs` copied → the hook runs it with `--local --branch=dev --head=<pushed sha>` and exports `SLOP_BASE_REF` = CI's push base (head of the last green CI push run on `dev`, else `origin/dev`), printing the base and its source. Pre-push and CI slop then share a base, so a finding an earlier red push landed fails locally too. Run lookup fails (`gh` missing, logged out) → loud `WARNING`, base `origin/dev`, push goes on. Other branches, or no copy → `bkit ci slop` merge-base default. A repo-owned pre-push check that diffs against CI's base (migration immutability) reads `SLOP_BASE_REF` when set.
|
|
214
217
|
- Slow repo extras (Docker, database, build) → wrap in `if [ "$MIN_PUSH" != "1" ]; then … fi`.
|
|
215
218
|
- Traps: hooks run on every workflow commit; keep them to seconds (pre-commit) and deterministic checks that reach no deployed service (pre-push). Integration runs at pre-push once `bkit:gate:static-unit-integration` is declared (a local database in Docker is fine); E2E and `@live` belong in CI.
|
|
216
219
|
- Run each check once: nothing in `bkit:gate:format` that the push gate runs again (`gate-commit-repeats-push` advisory), and `pnpm test` (the unit tier) matches no `*.integration.test.*` file — a unit config with no integration exclude runs those tests in the unit gate and again in the integration gate.
|
|
@@ -255,7 +258,7 @@ vale sync
|
|
|
255
258
|
|
|
256
259
|
## slop-scan — `slop-scan.config.json`
|
|
257
260
|
|
|
258
|
-
`lint:slop` reports; `slop:delta` (`bkit ci slop`, in `bkit:gate:static`) fails on net-new findings against the base. Reference: https://github.com/benvinegar/slop-scan.
|
|
261
|
+
`lint:slop` reports; `slop:delta` (`bkit ci slop`, in `bkit:gate:static`) fails on net-new findings against the base: `--base` / bare argument, else `$SLOP_BASE_REF`, else the merge-base with `origin/dev` (else `origin/main`). CI passes its planner base; pre-push on a `dev` push exports the same base as `SLOP_BASE_REF` (§ Git hooks), so both compare against the last green CI push run. Reference: https://github.com/benvinegar/slop-scan.
|
|
259
262
|
|
|
260
263
|
```bash
|
|
261
264
|
pnpm add -D slop-scan@^0.3.0
|
|
@@ -497,7 +500,7 @@ export GRAPHIFY_OUT=docs/graphify-out
|
|
|
497
500
|
graphify-out/
|
|
498
501
|
```
|
|
499
502
|
|
|
500
|
-
-
|
|
503
|
+
- Copy `scripts/graphify/bkit-graph-pre-push.sh`; the `.husky/pre-push` template runs it above the gates (skipped while the script is absent and on a min push), so a stale register blocks in ~30s, not after the full gate. Your hook lacks the `Capability register` block → paste it from the template, above the gates. Push to dev → `check-at` on the pushed commit in a throwaway checkout → blocked on mismatch; uncommitted edits (a concurrent session's included) cannot change the answer. graphify not installed → loud "NOT checked" warning, push goes on (CI still checks). Other branches → warn-only staleness note. Reads `PUSH_DEV_SHA` from the bkit pre-push template's stdin loop; older hook copy → re-copy that loop from `.bkit/templates/.husky/pre-push`.
|
|
501
504
|
- `.github/workflows/bkit-ci.yml` ships `Check Capability Register` (push events): installs the `spec` release, runs `pnpm graph:check` → stale register fails CI. Self-skips without `scripts/graphify/bkit-graphify.sh`.
|
|
502
505
|
- graphify's MCP server is opt-in: install `graphifyy[mcp]` (`mcp` + `starlette`; HTTP transport also needs `uvicorn`) and pass the graph path explicitly — `graphify-mcp` defaults to `graphify-out/graph.json`, not the pinned `docs/graphify-out/graph.json`. Snapshot-dated answers suit audit/orientation, never build or debug.
|
|
503
506
|
- `.graphifyignore` merges `.gitignore`.
|
|
@@ -599,9 +602,9 @@ Prettier aligns markdown tables with no config toggle; one edited cell re-pads e
|
|
|
599
602
|
| `node scripts/prettier/bkit-insert-ignore.mjs --check` | Write nothing; exit 1 if any file would change. Gate form. |
|
|
600
603
|
|
|
601
604
|
- Walks skip `skills/` trees (vendored), `docs/audits/`, `docs/plans/` (records, kept as written). A file named on the command line is always processed. New and edited records get it at commit: § lint-staged names each staged file.
|
|
602
|
-
- Skips tables inside ``` / ~~~ fences and tables already wrapped.
|
|
605
|
+
- Skips tables inside ``` / ~~~ fences, inside multi-line `<!-- -->` comments, and tables already wrapped. A comment opens on a line starting with `<!--` and runs to the first line holding `-->`; a one-line comment hides nothing.
|
|
603
606
|
- A pipe inside an inline-code span is escaped to `\|` only when that restores the separator's column count; an existing `\|` stays literal.
|
|
604
|
-
- Exit 1 on damage it cannot repair, with or without `--check`: `truncated-row` (more cells than the separator; GFM drops the overflow) and `unrendered-table` (header ≠ separator count; GFM renders raw text). A bare pipe in cell prose is indistinguishable from a delimiter → escape it as `\|` by hand.
|
|
607
|
+
- Exit 1 on damage it cannot repair, with or without `--check`: `truncated-row` (more cells than the separator; GFM drops the overflow) and `unrendered-table` (header ≠ separator count; GFM renders raw text). A bare pipe in cell prose is indistinguishable from a delimiter → escape it as `\|` by hand. Under `docs/audits/` and `docs/plans/` the same damage prints as a `WARN` and exits 0: records hold text quoted from elsewhere (issue comments, CI logs) that nobody can fix in place.
|
|
605
608
|
|
|
606
609
|
## tmp/ prune — old scratch files
|
|
607
610
|
|
|
@@ -644,3 +647,25 @@ cp .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs ~/.config/bkit/di
|
|
|
644
647
|
- Worktrees: `bkit worktrees setup` create / resume under `bkit.disk.minFreeGb` → runs `max` steps, waits. Still under → exit 12, nothing created; stderr lists what `max` steps still cover. No step file → no check.
|
|
645
648
|
- One sweep per machine at a time (`disk-prune.lock` beside the log). Failed step → logged, next runs. CI / cloud → nothing runs.
|
|
646
649
|
- Hand run: `pnpm bkit disk prune --mode=max --dry-run` → each step + its `paths` size; without `--dry-run` → runs now. Exit 1 = a step failed or a step file did not load.
|
|
650
|
+
|
|
651
|
+
## Local stack lock — one run at a time on a shared stack
|
|
652
|
+
|
|
653
|
+
Every worktree of a repo uses the same local services when their names and ports come from the repo's config (a Docker database, an emulator). A run that starts, resets or stops the stack, or tests against it, takes a machine-wide lock first; a second run waits and prints who holds it. bash + `/usr/bin/perl`, no dependencies.
|
|
654
|
+
|
|
655
|
+
```bash
|
|
656
|
+
mkdir -p scripts/ci
|
|
657
|
+
cp .bkit/templates/scripts/ci/bkit-local-stack-lock.sh scripts/ci/
|
|
658
|
+
```
|
|
659
|
+
|
|
660
|
+
<!-- prettier-ignore -->
|
|
661
|
+
| Wire into | How | Holds the lock |
|
|
662
|
+
| --- | --- | --- |
|
|
663
|
+
| `package.json` scripts that start / reset / stop the stack | `"db:reset": "bash scripts/ci/bkit-local-stack-lock.sh run db:reset -- <reset command>"` | for the command; its exit status passes on |
|
|
664
|
+
| local runners that test against the stack | `. scripts/ci/bkit-local-stack-lock.sh`, then `take_local_stack_lock "<who>"` before the first stack command; non-zero → exit | until the runner exits or calls `release_local_stack_lock` |
|
|
665
|
+
|
|
666
|
+
- Functions: `take_local_stack_lock` waits; `try_local_stack_lock` returns 1 at once while another run holds it; `release_local_stack_lock` frees it early; `local_stack_lock_holder` prints the holder. Safe under `set -e`.
|
|
667
|
+
- Name: `BKIT_LOCAL_STACK` when set, else the main checkout's folder name (`git rev-parse --git-common-dir`) → every worktree finds the same lock. A throwaway stack with its own names and ports sets its own `BKIT_LOCAL_STACK` and never waits on the shared one. Outside a git checkout with no `BKIT_LOCAL_STACK` → refuses, exit 1.
|
|
668
|
+
- Lock file: `~/.cache/bkit/local-stack-lock/<name>.lock` (`$XDG_CACHE_HOME/bkit/` when set), outside every checkout.
|
|
669
|
+
- Never stale: a small perl process holds the lock (flock) and exits within a second of its caller, however the caller ends.
|
|
670
|
+
- Wait: `LOCAL_STACK_LOCK_WAIT_S` seconds (default 3600), a note naming the holder once a minute, then exit 1 naming it. A runner started by the holder (`LOCAL_STACK_LOCK_OWNER`) does not wait. `CI=true` / `CI=1` → no-op.
|
|
671
|
+
- Fix hints and docs name the locked scripts, never the raw command (`supabase db reset`, `docker compose down`): the raw command skips the lock. `.agents/rules.md` § Shared local stack.
|
|
@@ -150,7 +150,16 @@ Workflows read issue body + comments (`bkit issues text`), never title (title
|
|
|
150
150
|
|
|
151
151
|
## github — Projects v2 board (optional)
|
|
152
152
|
|
|
153
|
-
`issue-update-status` reads `package.json` `bkit.
|
|
153
|
+
`issue-update-status` reads `package.json` `bkit.github` = `{ project, progress, review }` (non-secret, committed), same shape as `bkit.linear` / `bkit.jira`:
|
|
154
|
+
|
|
155
|
+
<!-- prettier-ignore -->
|
|
156
|
+
| Key | Value | Default |
|
|
157
|
+
| --- | --- | --- |
|
|
158
|
+
| `project` | Board URL as the browser shows it: `https://github.com/orgs/<org>/projects/<n>` or `https://github.com/users/<login>/projects/<n>`; a trailing `/views/<n>` is fine. `false` = board sync off (silences `github-project-board-sync-unconfigured`). | absent → board sync skipped |
|
|
159
|
+
| `progress` | Status option **name** set when a phase starts | `In progress` |
|
|
160
|
+
| `review` | Status option **name** set on hand-off | `In review` |
|
|
161
|
+
|
|
162
|
+
Defaults match GitHub's Kanban and Team planning board templates. `/orgs/` → MCP `owner_type: "org"`, `/users/` → `"user"`. Requires `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) + `BKIT_GH_TOKEN` that reaches the board: fine-grained PAT with org Projects R/W for an org board; classic PAT with `project` for a personal board or a token spanning owners. `update_project_item` finds the item by `item_owner` / `item_repo` / `issue_number` and sets Status by option name. Best-effort, never gates; failure → retry once after 5s, then continue. `Done` is **never written** — ship terminal sets `review`, and a human moves the item to Done on acceptance (§ `issue-update-merged` in `.bkit/workflows.md`).
|
|
154
163
|
|
|
155
164
|
## linear — notes
|
|
156
165
|
|
|
@@ -169,7 +169,7 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
|
|
|
169
169
|
- **Related-issues scan** (issue-scan): numbered step at design ideate-entry, plan fetch-context, debug fetch-context; tracker group → under `none` collapses to `_No tracker connected, skip step._` (number preserved). Best-effort: github / linear semantic search — fetch 15, drop own issue, keep 10; jira keyword JQL (`{QUERY_KW}`, 2-4 terms, one `text ~` per term, ORed, own issue excluded, 10) — one comment fetch per hit; `Search unavailable.` on error; never gates, never auto-expands scope (advisory dedup / conflicting-design / prior-incident). All states: closed issues carry strongest dedup signals. Per hit: `## #{number} — {title} ({state})` + `RELATED_ISSUE_TEXT` (issue-path wording, `RELATED_` prefix), appended to `RELATED_ISSUES`; file written once after last hit; design → `related-issues.md` (generate reads `(if present)`, condenses to `## Related Issues` one-liners or `None`); a design hit whose `bkit issues text` exits non-zero (comments did not parse) is skipped and named under its heading (`Skipped: comments did not parse.`), and the design carries on — related issues are background. Plan: `{QUERY}` in plain sub-step → `related-deferrals.md` / `related-failures.md`; `{QUERY_NL}` (jira `{QUERY_KW}`) in the tracker group → `related-issues.md`; read by `bkit-plan-review-1/2/3`. Debug → `context-related-${DEBUG_ATTEMPT}.md` (`context-*` glob; excluded from `FETCH_VERDICT`). Plan runs fresh scan (standalone plan coverage). No `fields` parameter on github / linear — the search returns all fields on every hit and must keep doing so; restricting to a subset trades away the content the sweep exists to surface. Artifact is uncapped by decision (§ Context artifact clamping).
|
|
170
170
|
- **Query shape — two variables, not one.** `{QUERY_NL}` = one natural-language sentence, consumed only by the search call; no `sort` / `order` / `orderBy`, no `in:title,body` qualifier (inert in a semantic query), results kept in rank order through the drop-own-issue and keep-first-10 steps or the ranking is discarded before use. The response carries an order but no score, so a relevance THRESHOLD is not implementable — rank position is the only signal. `{QUERY}` = the 3–6 keyword list, plan-only, consumed ONLY by the ledger awk: that awk splits on whitespace and counts distinct term hits with a `>=2 terms` rule, so feeding it a sentence makes every stopword match every line and degrades the scan to "print everything".
|
|
171
171
|
- **Ledger scans** (plan only, run under `none`): awk counts query-term hits per line (`>=2` distinct terms, or the sole term when one; case-insensitive substring), sorts by hit count desc then line number desc (append-only ledgers → line order is time order), keeps the top 40 per file and footers the total. `cut -f3-` rejoins fields 3..N with tabs, so a literal tab inside a JSONL line survives intact. Backstopped by the `ledger` clamp profile.
|
|
172
|
-
- **Projects v2 board sync** (`issue-update-status`): best-effort, never gates; retry once after 5s on failure. `bkit issues labels --board=progress|review --issue= --owner-repo=` builds the
|
|
172
|
+
- **Projects v2 board sync** (`issue-update-status`): best-effort, never gates; retry once after 5s on failure. `bkit issues labels --board=progress|review --issue= --owner-repo=` builds the two payloads (`addItem`, `updateItem`) from `bkit.github.project`; `board` null + `boardSkipped` when opted out, not configured or not a board URL. `updateItem` names the item by `item_owner` / `item_repo` / `issue_number` and sets `Status` to the option named `bkit.github.progress` / `review` (`In progress` / `In review`). Linear / Jira: no-op (state / status carries it).
|
|
173
173
|
- **Blocked-by edges:** GitHub: `###### bkit:blocked-by start` / `end` pair in issue body. Linear: native `blockedBy` (append-only; unchanged edges = no-op). Jira: native `Blocks` link (`inwardIssue` = blocker; repeat = no-op).
|
|
174
174
|
- **No tracker-issue creation:** Workflows never create tracker issues. `issue_write` method is `update`. Linear `save_issue` always includes `id`. Jira: no `createJiraIssue` grant. Step 1 resolves an existing issue reference from the session prompt; no match → log `No issue ID in the session prompt.` and stop (not **Failure Path**). Design Step 11 posts `## Suggested Workstreams` as an advisory comment on the parent issue. A human files any follow-up issues.
|
|
175
175
|
- **issue-update-review** (phase-close): **update state only — never change label on close.** GitHub: no-op (phase label until ship `issue-update-merged`). Linear: `save_issue({ id, state: "{TRACKER_STATE}" })` (`bkit.linear.review`) — no `labels` (partial update would drop `bkit:auto`/`bkit:debug`); a team without that state → `Unapplied`, issue stays started (`.bkit/trackers.md` § linear — notes). Jira: transition to `bkit.jira.review`, no label edit; unreachable → `Unapplied` (`.bkit/trackers.md` § jira — setup and notes).
|
|
@@ -201,7 +201,7 @@ Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares skeleton
|
|
|
201
201
|
3. Execution Protocol caution block (header bullets — see below)
|
|
202
202
|
4. Failure Path
|
|
203
203
|
5. Step 1 — Start Workflow (`bkit repo info --fetch`, FID, `bkit locks acquire`, tracker init, first-step comment post — status init deferred to Step 2; ZERO commits on `dev`)
|
|
204
|
-
6. Step 2 — Worktree Setup (`bkit worktrees setup`: create / resume / adopt; create / resume under `bkit.disk.minFreeGb` free → `max` disk-prune steps first, still under → exit 12 (`.bkit/templates.md` § Disk prune); copy `bkit.worktree.copy` (default `.env`, `.env.local`), install unless `bkit.worktree.install` is false; `bkit workflows start` + `bkit runtime row`; save input; `start-workflow` + `worktree-setup` step entries committed on `feat/{FID}`)
|
|
204
|
+
6. Step 2 — Worktree Setup (`bkit worktrees setup`: create / resume / adopt; create / resume under `bkit.disk.minFreeGb` free → `max` disk-prune steps first, still under → exit 12 (`.bkit/templates.md` § Disk prune); copy `bkit.worktree.copy` (default `.env`, `.env.local`), `direnv allow` a `.envrc` identical to the main checkout's, install unless `bkit.worktree.install` is false; `bkit workflows start` + `bkit runtime row`; save input; `start-workflow` + `worktree-setup` step entries committed on `feat/{FID}`)
|
|
205
205
|
7. Phase-specific steps (subagent invocations, gates, per-step new comment post)
|
|
206
206
|
8. Summary step (subagent → commit → push → verdict)
|
|
207
207
|
9. Close Workflow (`bkit workflows close`, lock release, state → hand-off via `issue-update-review`; ship terminal `bkit:merged` + In Review via `issue-update-merged` (issue left OPEN — human reviews + closes); non-ship phases update state only, phase label unchanged; **final return** = verbatim `{phase}-summary.md` to user, then a plain-English offer, as the last actions)
|
|
@@ -752,7 +752,7 @@ Every command has `## 🤖 Failure Path` before Step 1. Any step / tool / gate f
|
|
|
752
752
|
|
|
753
753
|
### Rebase Conflict Tiering
|
|
754
754
|
|
|
755
|
-
`/bkit-build`, `/bkit-debug`, `/bkit-design`, `/bkit-plan` Step 2 rebase a resumed feature worktree onto `origin/dev` (`bkit worktrees setup`); `/bkit-ship` never rebases its branch — Step 4 integrates (B1 server-side, B2 conflict-resolve). Three-tier recovery:
|
|
755
|
+
`/bkit-build`, `/bkit-debug`, `/bkit-design`, `/bkit-plan` Step 2 rebase a resumed feature worktree onto its base, `origin/dev` or local `dev` when it is ahead (`bkit worktrees setup`); `/bkit-ship` never rebases its branch — Step 4 integrates (B1 server-side, B2 conflict-resolve). Three-tier recovery:
|
|
756
756
|
|
|
757
757
|
<!-- prettier-ignore -->
|
|
758
758
|
| Tier | Conflict shape | Recovery | Mechanism |
|
|
@@ -841,7 +841,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
|
|
|
841
841
|
| Step | Subagent(s) | Read | Write | Notes |
|
|
842
842
|
| --- | --- | --- | --- | --- |
|
|
843
843
|
| 1 — Start Workflow | — | tracker issue | `.lock`, tracker comment | Fetch `origin/dev`. Resolve `{ISSUE_ID}` from the session prompt (no match → stop; never create), set label `bkit:design`, state `In Progress`. no commits on `dev` — `status.jsonl` init + `start-workflow` step entry deferred to Step 2 inside the worktree. |
|
|
844
|
-
| 2 — Worktree Setup | — | repo | `.worktrees/{FID}`, `bkit.worktree.copy` files, `design-input-{RUN}.md` | `bkit worktrees setup`: create `feat/{FID}` off a freshly fetched `origin/dev
|
|
844
|
+
| 2 — Worktree Setup | — | repo | `.worktrees/{FID}`, `bkit.worktree.copy` files, `design-input-{RUN}.md` | `bkit worktrees setup`: create `feat/{FID}` off a freshly fetched `origin/dev` (local `dev` when it is ahead), resume it, or adopt the current branch in place; dependencies installed (install failure → **Failure Path**). `baseSha` → `runtime-resolved` row (§ Anchor Block). |
|
|
845
845
|
| 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each round asks the whole frontier (every decision whose prerequisites are settled), numbered, each with a recommended answer worded so "yes" accepts it; plain text, no host question tool. Orchestrator looks up facts; only decisions go to the human. Decision rounds stop on an empty frontier, a human stop, or 9 rounds. The last round asked is always the draft scenario round, counted in the 10-round cap: the orchestrator drafts the acceptance scenario (`Narrative`, `Success Criteria`, `Key Edge Cases`, `Process Sketch` — the four parts of the design's `Acceptance Scenario`) from the whole context — session prompt, issue description and comments, answers, looked-up facts — shows it in full, and asks one question per part it inferred plus a final accept question; an answer that opens new decisions returns to the decision rounds while rounds remain. Agreed answers → `Settled`; unanswered at stop → `Assumed, not confirmed`; "don't know" → `Open`. The draft lands under `### Draft Acceptance Scenario` behind a `DRAFT only` first line saying whether a human reviewed it; a human stop skips the draft round and records the draft unreviewed. `bkit-design-generate` starts its `Acceptance Scenario` from the draft and records each change as a `Decisions` row, with no further confirmation item: the human reviews the scenario again at the plan's `Acceptance Scenario confirmed` box. The plan reads the design, never the draft. An earlier run's `Settled` entries stay settled and its draft is the starting draft. `grill=false` in the session prompt skips the interview; the artifact then reads `Skipped (grill=false).` `runtimeHeadless` = true (read via `bkit runtime assert`) → no question asked, no turn ended: the tree is walked taking each recommended answer as given, every new answer lands in `Assumed, not confirmed`, the draft scenario is written unreviewed, and the artifact carries a `Headless run ({RUNTIME})` line. The ideate triplet, generate and both reviewers read the section through `design-input-{RUN}.md`. Waiting time is exempt from the 3600s timeout. A `bkit-cloud.yml` `workflow_dispatch` run is headless. |
|
|
846
846
|
| 4 — Brainstorm & Ideate | `@bkit-design-brainstorm-ideate-1` ‖ `-2` ‖ `-3` (parallel triplet) | `design-input-{RUN}.md` | `design-brainstorm-ideate-1.md`, `-2.md`, `-3.md` | Pragmatic / optimal-tradeoff / risk-premortem lenses; effort-tier diversity (`high`/`medium`/`high`); sibling-blind. `BRAINSTORM_VERDICT` = worst of three. |
|
|
847
847
|
| 5 — Generate Design | `@bkit-design-generate` | `design-input-{RUN}.md` (carries the `Grill decisions` section), all three brainstorms, `related-issues.md`, superseded `{YYYYMM}/{FID}-design.md` (if any) | `design-v1-draft.md` (versioned draft) | First write of deliverable design doc. Superseded design = context only, never a constraint; supplied HERE only — not to the sibling-blind ideate triplet. |
|
|
@@ -1023,15 +1023,16 @@ All phase workflows run in `.worktrees/{FID}` (gitignored). One worktree per FID
|
|
|
1023
1023
|
<!-- prettier-ignore -->
|
|
1024
1024
|
| Mode | When | Does |
|
|
1025
1025
|
| --- | --- | --- |
|
|
1026
|
-
| `created` | `--worktrees`, no `.worktrees/{FID}` | `git worktree prune`; adds the existing local `feat/{FID}`, else tracks `origin/feat/{FID}`, else cuts `feat/{FID}` off a freshly fetched `origin/dev` (explicit refspec — a clone whose fetch refspec skips `dev` still gets a current base; origin unreachable → exit 4, nothing minted). Writes the `.worktree-owned` marker in `{OUTBOX}` |
|
|
1027
|
-
| `resumed` | `--worktrees`, `.worktrees/{FID}` registered | `git fetch origin dev` + `git rebase
|
|
1026
|
+
| `created` | `--worktrees`, no `.worktrees/{FID}` | `git worktree prune`; adds the existing local `feat/{FID}`, else tracks `origin/feat/{FID}`, else cuts `feat/{FID}` off the base: a freshly fetched `origin/dev` (explicit refspec — a clone whose fetch refspec skips `dev` still gets a current base; origin unreachable → exit 4, nothing minted), or local `dev` when it is a fast-forward of `origin/dev` — dev pushes wait for a human, so local `dev` routinely holds commits `origin/dev` lacks; push `dev` before the feature PR. Local `dev` diverged from `origin/dev` → `origin/dev`, narrated. Writes the `.worktree-owned` marker in `{OUTBOX}` |
|
|
1027
|
+
| `resumed` | `--worktrees`, `.worktrees/{FID}` registered | `git fetch origin dev` + `git rebase` onto the same base (ship: no fetch, no rebase). Conflict → exit 3, rebase left in progress (§ Rebase Conflict Tiering); a rebase that cannot start → exit 9. A plain directory at the path → exit 10, never rebases the main checkout |
|
|
1028
1028
|
| `adopted` | no `--worktrees` (cloud), or the session already sits on the branch | works in place on the current branch, `worktreePath` = repo root; no copy, no install |
|
|
1029
1029
|
|
|
1030
1030
|
Then, for `created` / `resumed` worktrees only:
|
|
1031
1031
|
|
|
1032
1032
|
- **Copy:** each `package.json` `bkit.worktree.copy` entry (default `.env`, `.env.local`; files or folders) from the main checkout; `copied` / `copyMissing` list them and every missing entry is narrated — never a hard-coded app path. An entry pointing outside the main checkout is skipped.
|
|
1033
1033
|
- **Install:** every workflow (`bkit.worktree.install`, default true), frozen lockfile through the package manager — required because per-package `node_modules` symlinks are not inherited by worktrees, and without the install there is no `.husky/_`, so commits and pushes in the worktree skip the hooks. Install failure → exit 5; a package manager that could not run → exit 6; both → **Failure Path** in every workflow.
|
|
1034
|
-
- `
|
|
1034
|
+
- **direnv:** a worktree `.envrc` byte-identical to the main checkout's gets `direnv allow` (`direnvAllowed`), so the worktree carries the trust given there and nothing more. A differing `.envrc`, direnv missing or failing → narrated, never fatal; a human reads it and runs `direnv allow`. No git hook can do it: `core.hooksPath` (`.husky/_`) exists only after the install.
|
|
1035
|
+
- `logDir` created; `baseRef` = the base above; `baseSha` = `git merge-base {baseRef} HEAD` (design / plan anchor).
|
|
1035
1036
|
|
|
1036
1037
|
Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a detached HEAD, or ship unable to switch to its branch.
|
|
1037
1038
|
|
|
@@ -1042,7 +1043,7 @@ Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a d
|
|
|
1042
1043
|
<!-- prettier-ignore -->
|
|
1043
1044
|
| Workflow | Branch | Reason |
|
|
1044
1045
|
| --- | --- | --- |
|
|
1045
|
-
| `/bkit-design`, `/bkit-plan`, `/bkit-build` | `feat/{FID}` — local, else `origin`, else cut off `origin/dev` | One branch per feature; every phase starts from current `dev`. |
|
|
1046
|
+
| `/bkit-design`, `/bkit-plan`, `/bkit-build` | `feat/{FID}` — local, else `origin`, else cut off `origin/dev` (local `dev` when it is ahead) | One branch per feature; every phase starts from current `dev`. |
|
|
1046
1047
|
| `/bkit-ship` | `--branch=` (the prompt names it), else `feat/{FID}` when it exists locally or on `origin`, else the session branch when it is not `dev` / `main`, else `feat/{FID}` off `origin/dev` | The prompt is the authority on what to ship (§ Branch eligibility). |
|
|
1047
1048
|
| `/bkit-debug` | existing `feat/{FID}`, else the session's current branch in place (`dev` included; `main` refused) | A remediation branch of its own would strand the fix off the surface whose CI actually failed, and mint a new one on every run. |
|
|
1048
1049
|
|
|
@@ -1101,7 +1102,7 @@ Issue state semantics (GitHub `open`/`closed` + Projects v2; Linear / Jira `prog
|
|
|
1101
1102
|
| `issue-update-review` | Close Workflow of `/bkit-design`, `/bkit-plan`, `/bkit-build`, `/bkit-debug`. Hand-off state (GitHub no-op — phase label carries signal; Linear / Jira `review`). |
|
|
1102
1103
|
| `issue-update-merged` | `/bkit-ship` Step 14. Ship terminal — drop phase labels, add `bkit:merged`; GitHub left **open**, Linear / Jira `review`. bkit never closes / never sets Done — a human closes on acceptance (merge != acceptance). |
|
|
1103
1104
|
| `issue-update-failed` | Failure Path. Adds `bkit:failed` additive label. |
|
|
1104
|
-
| `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step 14 → "In review" (never "Done" — the board mirrors the issue, which stays open for human close). GitHub Projects v2 board (`bkit.
|
|
1105
|
+
| `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step 14 → "In review" (never "Done" — the board mirrors the issue, which stays open for human close). GitHub Projects v2 board (`bkit.github.project`; skipped if unset/absent). Linear / Jira no-op (issue state already carries it). |
|
|
1105
1106
|
|
|
1106
1107
|
### Comment lifecycle
|
|
1107
1108
|
|
|
@@ -78,7 +78,6 @@ export function detectCiYmlMissingActionlint(cwd: string): PreflightFinding | nu
|
|
|
78
78
|
action:
|
|
79
79
|
"Add an actionlint step among the static checks in .github/workflows/bkit-ci.yml (before the test/build group):\n\n" +
|
|
80
80
|
" - name: Run actionlint\n" +
|
|
81
|
-
" if: steps.cache.outputs.skip != 'true'\n" +
|
|
82
81
|
" run: |\n" +
|
|
83
82
|
' curl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.12/scripts/download-actionlint.bash -o "$RUNNER_TEMP/download-actionlint.bash"\n' +
|
|
84
83
|
' bash "$RUNNER_TEMP/download-actionlint.bash" 1.7.12 "$RUNNER_TEMP"\n' +
|