@cbartens/bkit 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
package/.bkit/README.md CHANGED
@@ -1,34 +1,46 @@
1
1
  # bkit — Agent Workflow System
2
2
 
3
- <!-- bkit:managed v6.0.0 — do not edit; run `bkit upgrade` to refresh -->
3
+ <!-- bkit:managed v6.1.0 — do not edit; run `bkit upgrade` to refresh -->
4
4
 
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).
5
+ > [!CAUTION]
6
+ > **Purpose:** What bkit does, the environment and tracker setup, the upgrade paste, the ongoing CLI and the friction-sharing paste. First-time install and the full auth setup are in `.bkit/install.md`. Workflow internals are in `.bkit/workflows.md`, and subagent metadata (effort, model, tools, `maxTurns`) is in `.bkit/prompts.md`.
7
+ >
8
+ > **Rules:**
9
+ >
10
+ > - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
11
+ > - This file ships to every project that installs bkit. Describe the current setup only.
12
+ > - Leave out internal labels, such as tracker issue numbers, ledger keys and review-finding ids, and leave out project history. Decisions go in `docs/decisions.jsonl`, and incidents go in `docs/knowledge.jsonl`.
13
+ > - Give a topic that another `.bkit/*.md` doc owns a short summary here and a pointer to that doc. Keep the detail in that doc only.
6
14
 
7
- README: what bkit does, env / tracker setup, upgrade paste + ongoing CLI. First-time install/auth deep-dive: `.bkit/install.md`. Workflow internals: `.bkit/workflows.md`; subagent metadata (effort, model, tools, `maxTurns`): `.bkit/prompts.md`.
15
+ **bkit** wires Claude, Codex, Antigravity, Cursor and OpenCode into a five-phase cycle integrated with the issue tracker: `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`. Hosts are additive, with one flag each: `--claude`, `--codex`, `--antigravity`, `--cursor` and `--opencode=<provider>`. The OpenCode providers are `openrouter`, `ollama`, and `opencode-zen` + `opencode-go` (OpenCode's own gateways, which authenticate with `BKIT_OPENCODE_API_KEY`). Every host runs the same harness. State lives in the repo, so a feature moves between hosts mid-run (see `.bkit/providers.md` § Supported hosts).
8
16
 
9
17
  ---
10
18
 
11
19
  ## How a workflow runs (end-to-end example)
12
20
 
13
- Typical cycle for `ISSUE-123` "Add feature X":
21
+ Here is a typical cycle for `ISSUE-123` "Add feature X":
14
22
 
15
- 1. **Tracker issue** with **`bkit:auto`** label + non-terminal state (`Backlog`, `In Progress`).
16
- 2. **Trigger** — tracker comment (`@cursor /bkit-plan ISSUE-123`) or slash command (`/bkit-plan ISSUE-123`).
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`, cut from `origin/dev` (local `dev` when it holds unpushed commits on top). Copies each `bkit.workflows.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.workflows.worktree.install: false`.
19
- 5. **Phase steps** — dispatches subagents (`@bkit-plan-generate`, then `@bkit-plan-review-1` ‖ `-2` ‖ `@bkit-plan-scope-check` in parallel, etc.). Each writes `docs/plans/{YYYYMM}/logs/{FID}/` (`{YYYYMM}` = canonical month bucket at design start), appends fenced section to tracker comment.
20
- 6. **Phase summary** — `bkit workflows summary` writes it from the run's status rows; verdict (`PASS` / `CONCERNS` / `FAIL`); commit `chore(issue-123-…): summary bkit [skip ci]` (design/plan) or `chore(issue-123-…): summary` (build/debug/ship) → push.
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.
22
- 8. **Human review** — design/plan at `docs/plans/{YYYYMM}/{FID}-{design,plan}.md` (canonical). Reviewer re-triggers or progresses to `/bkit-build`.
23
- 9. **`/bkit-build`** — re-creates worktree, executes plan test-first (each task's tests fail before its code, then pass), lint/typecheck/unit tests, opens PR to `dev`.
24
- 10. **CI** on PR. Red → `/bkit-debug` (PR mode: `gh run view --log-failed`). Green → `/bkit-ship`.
25
- 11. **`/bkit-ship`** — squash-merge PR, `@bkit-ship-update-docs` then the ship summary on `dev`, prune worktree, issue `In Review` (`bkit:merged`; bkit never auto-closes). Plans stay at `docs/plans/{YYYYMM}/` — no archive move.
23
+ 1. **Tracker issue** — the issue has the `bkit:auto` label and a non-terminal state (`Backlog`, `In Progress`).
24
+ 2. **Trigger** — a tracker comment (`@cursor /bkit-plan ISSUE-123`) or a slash command (`/bkit-plan ISSUE-123`) starts the workflow.
25
+ 3. **Workflow Step 1** — the workflow reads the issue, resolves the feature id, takes the `.lock`, sets `bkit:plan` and `In Progress`, and posts its start comment.
26
+ 4. **Step 2 — worktree** — the workflow creates a git worktree at `.worktrees/issue-123-add-feature/` on `feat/issue-123-add-feature`. It cuts the branch from `origin/dev`, or from local `dev` when that branch holds unpushed commits on top. Then it:
27
+ - Copies each `bkit.workflows.worktree.copy` path from the main checkout. This `package.json` setting defaults to `.env`, `.env.local`. Paths are exact, and folders copy recursively. A missing path is logged, and is never fatal.
28
+ - Links `.bkit/.env` (bkit's own token file) to the main checkout's copy, so the worktree can sign in.
29
+ - Runs `direnv allow` when the worktree's `.envrc` matches the main checkout's.
30
+ - Runs `pnpm install --frozen-lockfile`, unless `bkit.workflows.worktree.install: false`.
31
+ 5. **Phase steps** — the workflow dispatches subagents: `@bkit-plan-generate`, then `@bkit-plan-review-1`, `-2` and `@bkit-plan-scope-check` in parallel, and so on. Each one writes to `docs/plans/{YYYYMM}/logs/{FID}/`. The orchestrator posts each completed step as a new tracker comment. `{YYYYMM}` is the canonical month bucket, taken at design start.
32
+ 6. **Phase summary** — `bkit workflows summary` writes the summary from the run's status rows, with a verdict (`PASS` / `CONCERNS` / `FAIL`). The workflow commits it as `chore(issue-123-…): summary bkit [skip ci]` for design / plan, or as `chore(issue-123-…): summary` for build/debug/ship, and then pushes.
33
+ 7. **Close Workflow** — the tracker issue moves to `In Review`, and the phase label stays. `/bkit-design` / `/bkit-plan` prune the worktree and delete `feat/issue-123-…`, which is merged into `dev`. `/bkit-build` / `/bkit-debug` keep the worktree.
34
+ 8. **Human review** — the design / plan sits at its canonical path, `docs/plans/{YYYYMM}/{FID}-{design,plan}.md`. The reviewer re-triggers the workflow or moves on to `/bkit-build`.
35
+ 9. **`/bkit-build`** — re-creates the worktree and executes the plan test-first: a tests agent writes each group's planned tests, the engine proves them failing, and a separate code agent makes them pass. It runs the deepest declared local gate, including integration when declared, and opens a PR to `dev`.
36
+ 10. **CI** — runs on the PR. Red → `/bkit-debug`, in PR mode (`gh run view --log-failed`). Green → `/bkit-ship`.
37
+ 11. **`/bkit-ship`** — updates docs and writes the ship summary in the feature worktree, prunes skills, pushes bookkeeping and validates the covered CI head before squash-merging the PR. It verifies merge CI, lands the close record on `dev`, removes the worktree, and moves the issue to `In Review` with `bkit:merged`. bkit never closes an issue automatically. Plans stay at `docs/plans/{YYYYMM}/`, with no archive move.
26
38
 
27
- Throughout: workflows hold `.lock`, write `status.jsonl` (resume SoT), own tracker MCP calls — subagents are leaves (no tracker access), writes scoped by `tools:` allowlist.
39
+ Throughout the run, the workflow holds `.lock`, writes `status.jsonl` (the source of truth for resuming) and owns the tracker MCP calls. Subagents are leaves: they have no tracker access, and their `tools:` allowlist scopes their writes.
28
40
 
29
- Every point where a run can ask you has two settings under `bkit.workflows` in `package.json`: `ask` (stop and ask, or carry on with the recommendation) and a hard limit (`maxAttempts`, or `maxTurns` for the design grill). Defaults: `ask: true` everywhere, 2 attempts, 6 grill turns. A limit used up always ends in the Failure Path, and a question never resets a count. With `ask: false`, or in a headless GitHub Actions run, the run takes each recommendation and records any `Accept` as assumed; `/bkit-ship` asks you to confirm assumed items and writes the ones you don't confirm as `needs-decision` deferrals. `.bkit/workflows.md` § Ask points.
41
+ Every point where a run can ask you has two settings under `bkit.workflows` in `package.json`: `ask` (stop and ask, or carry on with the recommendation) and a hard limit (`maxAttempts`, or `maxTurns` for the design grill). The defaults are `ask: true` everywhere, 2 attempts and 6 grill turns. A limit used up always ends in the Failure Path, and a question never resets a count. With `ask: false`, or in a headless GitHub Actions run, the run takes each recommendation and records any `Accept` as assumed. `/bkit-ship` then asks you to confirm the assumed items, and writes the ones you don't confirm as `needs-decision` deferrals. See `.bkit/workflows.md` § Ask points.
30
42
 
31
- Plans are sized by `bkit.workflows.tasks` in `package.json`: up to `bkit.workflows.tasks.maxPerGroup` tasks (default 3) and `bkit.workflows.tasks.maxTestsPerGroup` TEST FIRST tests (default 15) per group; per task `bkit.workflows.tasks.maxTestsPerTask` tests (default 10) across `bkit.workflows.tasks.maxTestFilesPerTask` test files (default 3). Install and upgrade write the defaults when missing; a value already set is never touched; a value that is not a whole number of 1 or more falls back to its default and `bkit check` says so. `.bkit/workflows.md` § Test-first.
43
+ Plans are sized by `bkit.workflows.tasks` in `package.json`. Each group holds up to `bkit.workflows.tasks.maxPerGroup` tasks (default 5) and up to `bkit.workflows.tasks.maxTestsPerGroup` `TEST FIRST` tests (default 25). Each task holds up to `bkit.workflows.tasks.maxTestsPerTask` tests (default 10), across up to `bkit.workflows.tasks.maxTestFilesPerTask` test files (default 3). Install and upgrade write the defaults when they are missing, and never touch a value already set. A value that is not a whole number of 1 or more falls back to its default, and `bkit check` says so. See `.bkit/workflows.md` § Test-first.
32
44
 
33
45
  ---
34
46
 
@@ -43,36 +55,36 @@ Plans are sized by `bkit.workflows.tasks` in `package.json`: up to `bkit.workflo
43
55
  | Debug | `/bkit-debug` | 11 | Remediation commit on feature branch | No |
44
56
  | Ship | `/bkit-ship` | 14 | Squash-merged PR, issue `In Review` + `bkit:merged` (plans stay canonical at `docs/plans/{YYYYMM}/`) | Yes |
45
57
 
46
- **Where an issue starts.** Issue body + comments = every workflow's first input; shapes and machine-read lines: `.bkit/trackers.md` § Issue shapes; example forms: `.bkit/templates.md` § Issue forms.
58
+ **Where an issue starts.** The issue body and its comments are every workflow's first input. Issue shapes and the lines a machine reads are in `.bkit/trackers.md` § Issue shapes, and example forms are in `.bkit/templates.md` § Issue forms.
47
59
 
48
60
  <!-- prettier-ignore -->
49
61
  | Issue | Start with |
50
62
  | --- | --- |
51
63
  | Idea — how it should work still open | `/bkit-design` |
52
- | Change — what to build and "done" known | `/bkit-plan`; or `/bkit-build` / `build:lite` with no plan (`/bkit-build` first writes `{FID}-plan.md` from the issue, then checks each `TEST FIRST` red; an existing plan wins over the issue; `build:lite` checks nothing) |
64
+ | Change — what to build and "done" known | `/bkit-plan`, or `/bkit-build` with no plan. With no plan, `/bkit-build` first writes `{FID}-plan.md` from the issue, then checks that each `TEST FIRST` is red. An existing plan wins over the issue. |
53
65
  | Bug — a test or CI run already fails | `/bkit-debug`, on the branch the fix lands on |
54
66
  | Bug — nothing fails yet | `/bkit-debug [repro]` (writes a failing test first, then fixes) |
55
67
 
56
- **Per-step detail, verdict routing, retry / timeout constants, label flips, status.jsonl shape, comment lifecycle:** `.bkit/workflows.md`.
68
+ Per-step detail, verdict routing, retry / timeout constants, label flips, the status.jsonl shape and the comment lifecycle are in `.bkit/workflows.md`.
57
69
 
58
- **Per-subagent scope, effort tier, tool surface, `maxTurns`, model assignment:** `.bkit/prompts.md`.
70
+ Per-subagent scope, effort tier, tool surface, `maxTurns` and model assignment are in `.bkit/prompts.md`.
59
71
 
60
72
  ---
61
73
 
62
74
  ## Audits
63
75
 
64
- No `/bkit-audit` command and no phase label. More than 30 procedures ship as `docs/templates/bkit-audit-*.md`. Invoke `@bkit-audit-generate` and name exactly one template.
76
+ Audits have no `/bkit-audit` command and no phase label. More than 30 procedures ship as `docs/templates/bkit-audit-*.md`. To run one, invoke `@bkit-audit-generate` and name exactly one template.
65
77
 
66
78
  <!-- prettier-ignore -->
67
79
  | Item | Contract |
68
80
  | --- | --- |
69
81
  | 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. |
70
82
  | 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`. |
71
- | 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. |
72
- | 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. |
73
- | 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. |
83
+ | Issue comment | When the invocation names an issue (`#123`, `ABC-123`) and a tracker is wired, the final summary lands on that issue as one comment, stopped runs included. The agent never files, edits or relabels issues. |
84
+ | Audit parent | Each template has one standing issue. Every run of that template reports to it, and the issues a run files become sub-issues of the standing issue (`.bkit/trackers.md` § Issue shapes). When no issue is named and a tracker is wired, the agent searches for the standing issue and posts the summary there. When none is open, the final message suggests one, ready to file, plus the saved summary to post as its first comment. |
85
+ | 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 the issue names which findings to plan (for example only `CRITICAL` and `HIGH`). The rest of each report stays context. |
74
86
 
75
- 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).
87
+ Each template's `Purpose` is its scope. The main ones cover security, privacy, accessibility, architecture, performance, reliability, testing, database, LLM and cost. The full catalogue is in `.bkit/prompts.md` § Audit (Ad-hoc).
76
88
 
77
89
  ---
78
90
 
@@ -84,27 +96,27 @@ Each template's `Purpose` is its scope. Main ones: security, privacy, accessibil
84
96
  | Tool | Version | Used for |
85
97
  | --- | --- | --- |
86
98
  | Node | >= 24 (`engines.node`) | Runs the bkit CLI. |
87
- | `pnpm` | matches `package.json` `packageManager` | Required in every consumer repo, whatever the stack: bkit installs and upgrades itself with pnpm, which makes the repo a pnpm repo. Runs the worktree install (`pnpm install --frozen-lockfile`) and the `bkit:gate:*` scripts. Non-Node stack → stub `package.json` whose `bkit:gate:*` scripts wrap the stack's own commands (e.g. `ruff check && pytest`). Also bkit CLI (`bkit install`; `pnpm tsx .bkit/core/engine/cli.ts` in bkit dev). |
99
+ | `pnpm` | matches `package.json` `packageManager` | Required in every consumer repo, whatever the stack: bkit installs and upgrades itself with pnpm, which makes the repo a pnpm repo. Runs the worktree install (`pnpm install --frozen-lockfile`) and the `bkit:gate:*` scripts. A non-Node stack uses a stub `package.json` whose `bkit:gate:*` scripts wrap the stack's own commands (e.g. `ruff check && pytest`). It also runs the bkit CLI (`bkit install`, or `pnpm tsx .bkit/core/engine/cli.ts` in bkit dev). |
88
100
  | `gh` | latest, authenticated | PR create / view / merge in `/bkit-build`, `/bkit-debug`, `/bkit-ship` |
89
101
  | `git` >= 2.5 | — | Worktree operations |
90
102
  | `jq` | latest | Reads the JSON that `bkit` commands print, in workflow Bash |
91
- | Claude Code CLI | latest | Local-IDE workflow execution |
103
+ | Claude CLI | latest | Local-IDE workflow execution |
92
104
  | Cursor (optional) | 2.4+ | Cloud Agent execution; honours `tools:` frontmatter allowlist |
93
105
 
94
106
  ### Shell alias
95
107
 
96
- bkit = devDependency — add once for `bkit <verb>`:
108
+ bkit is a devDependency. Add this alias once to run `bkit <verb>`:
97
109
 
98
110
  ```bash
99
111
  # Add to ~/.zshrc (or ~/.bashrc), then: source ~/.zshrc
100
112
  alias bkit='pnpm bkit'
101
113
  ```
102
114
 
103
- `bkit doctor` emits `bkit-not-on-path` if alias absent. For `bkit cursor` / `bkit opencode` (GUI launchers), run from repo root in external terminal — not inside running app.
115
+ `bkit doctor` emits `bkit-not-on-path` when the alias is missing. Run `bkit cursor` / `bkit opencode` (the GUI launchers) from the repo root in an external terminal, not inside the running app.
104
116
 
105
117
  ### Environment variables
106
118
 
107
- Add to shell, Cursor Cloud Agent dashboard, `apps/web/.env.example` for contributors. Exact set depends on `bkit install --tracker=<name>`:
119
+ Add these to your shell, to the Cursor Cloud Agent dashboard, and to `apps/web/.env.example` for contributors. The exact set depends on `bkit install --tracker=<name>`:
108
120
 
109
121
  **GitHub tracker (default — `bkit install --tracker=github`):**
110
122
 
@@ -144,33 +156,33 @@ BKIT_GH_TOKEN=""
144
156
  | Variable | Tracker | Where read | Purpose |
145
157
  | --- | --- | --- | --- |
146
158
  | `BKIT_GH_TOKEN` | all | GitHub MCP server (`Authorization: Bearer`) | Issue/label/PR writes via MCP. Fine-grained PAT when every target repo sits under one owner (Contents, PRs, Issues, Actions, Workflows, Metadata — R/W); classic PAT when one token must span owners (scopes `repo`, `workflow`, `read:org`, `project`, `security_events`). |
147
- | `GH_TOKEN` | all | `gh` CLI inside **CI workflow Bash only** (`GH_TOKEN: ${{ github.token }}`) | Not seeded in `.bkit/.env` — local `gh` uses `gh auth login` keyring. |
148
- | `GITHUB_ISSUE_ID` | github | Injected from PR body `<!-- bkit:issue=#NNN -->` | Linked GitHub issue. Injected automatically — do not set manually. |
149
- | `BKIT_ANTHROPIC_API_KEY` | all | Claude Code (headless / CI) | Required when Claude invoked outside interactive session (cloud automation, CI). |
159
+ | `GH_TOKEN` | all | `gh` CLI inside CI workflow Bash only (`GH_TOKEN: ${{ github.token }}`) | Not seeded in `.bkit/.env`. Local `gh` uses the `gh auth login` keyring. |
160
+ | `GITHUB_ISSUE_ID` | github | Injected from PR body `<!-- bkit:issue=#NNN -->` | Linked GitHub issue. Injected automatically, so do not set it manually. |
161
+ | `BKIT_ANTHROPIC_API_KEY` | all | Claude (headless / CI) | Required when Claude is invoked outside an interactive session (cloud automation, CI). |
150
162
  | `BKIT_CURSOR_API_KEY` | all | Cursor Cloud Agent dashboard / programmatic invocation | Required for non-interactive Cursor sessions. |
151
- | `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. |
152
- | `BKIT_JIRA_API_KEY` | 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. |
153
- | `LINEAR_WEBHOOK_SECRET` | linear | Linear → Cursor integration backend | Verifies webhook signatures on `@cursor` mentions. Set in Linear ↔ Cursor integration config. |
163
+ | `BKIT_LINEAR_API_KEY` | linear | Preflight hooks (`.{claude,cursor}/hooks/bkit-preflight.sh`); workflow Linear MCP via OAuth fallback | Queries issue state and labels for the `Auto` gate. Fails fast if absent. |
164
+ | `BKIT_JIRA_API_KEY` | jira | Jira MCP server (`Authorization: Bearer`) | An Atlassian MCP V2 scoped API token. A site admin first enables API-token sign-in for the Rovo MCP server. Setup: `.bkit/trackers.md` § jira. |
165
+ | `LINEAR_WEBHOOK_SECRET` | linear | Linear → Cursor integration backend | Verifies webhook signatures on `@cursor` mentions. Set in the Linear + Cursor integration config. |
154
166
 
155
- `GITHUB_ISSUE_ID` (GitHub) and `LINEAR_ISSUE_ID` (Linear) set automatically by workflow context — do not set manually.
167
+ The workflow context sets `GITHUB_ISSUE_ID` (GitHub) and `LINEAR_ISSUE_ID` (Linear) automatically. Do not set them manually.
156
168
 
157
169
  ### Tracker workspace setup
158
170
 
159
- One custom label (`Auto`), plus integration label families. Setup depends on configured tracker.
171
+ bkit uses one custom label (`Auto`), plus families of integration labels. The setup depends on the configured tracker.
160
172
 
161
173
  #### Bkit custom label (`Auto`)
162
174
 
163
- - **`Auto`** — issues approved for agent work. Preflight refuses if absent or terminal state (`Done` / `Cancelled` / closed). Add before any cloud / automation session.
164
- - **GitHub:** issue label `bkit:auto`. `bkit install --tracker=github` seeds via GitHub MCP on first run.
165
- - **Linear:** Linear label `Auto`. Add manually to workspace.
175
+ - **`Auto`** — marks issues approved for agent work. The preflight refuses an issue that lacks it or is in a terminal state (`Done` / `Cancelled` / closed). Add it before any cloud / automation session.
176
+ - **GitHub:** the issue label `bkit:auto`. `bkit install --tracker=github` seeds it through the GitHub MCP on the first run.
177
+ - **Linear:** the Linear label `Auto`. Add it to the workspace manually.
166
178
 
167
179
  #### Phase labels (GitHub tracker)
168
180
 
169
- `bkit.tracker.default = "github"` → Cursor reads PR phase label for dispatch: `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`. Cursor GitHub App on repo/org required. `/bkit-design` / `/bkit-plan` have no PR — local-IDE-only on Cursor cloud.
181
+ When `bkit.tracker.default = "github"`, Cursor reads the PR's phase label to dispatch: `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`. The Cursor GitHub App is required on the repo / org. `/bkit-design` / `/bkit-plan` have no PR, so they are local-IDE-only on Cursor cloud.
170
182
 
171
- #### Linear ↔ Cursor integration labels (Linear tracker only)
183
+ #### Linear + Cursor integration labels (Linear tracker only)
172
184
 
173
- Three **parent labels** (`branch`, `model`, `repo`) — sub-labels set Cursor Cloud Agent session context. Present sub-label → Cursor follows; else integration defaults.
185
+ Three **parent labels** (`branch`, `model`, `repo`) take sub-labels that set the Cursor Cloud Agent's session context. When a sub-label is present, Cursor follows it. Otherwise the integration's defaults apply.
174
186
 
175
187
  <!-- prettier-ignore -->
176
188
  | Parent | Example sub-labels in this workspace | What it controls |
@@ -179,60 +191,68 @@ Three **parent labels** (`branch`, `model`, `repo`) — sub-labels set Cursor Cl
179
191
  | `model` | `cursor-grok-4.5-high`, `composer-2.5` (defaults); API Opus etc. via `prompts.md` § Model Overrides paste block | Cursor model the orchestrator runs on |
180
192
  | `repo` | `<owner>/<consumer-repo>` | repo the agent operates in |
181
193
 
182
- Per-agent model assignments: `.bkit/prompts.md` § Models; Cursor reads subagent frontmatter `model:` directly. Linear `model:*` sub-labels = **orchestrator-session** model only. Keep in sync with `.bkit/providers.md` § Cursor model catalog.
194
+ Per-agent model assignments are in `.bkit/prompts.md` § Models. Cursor reads each subagent's frontmatter `model:` directly. Linear `model:*` sub-labels set the orchestrator session's model only. Keep them in sync with `.bkit/providers.md` § Cursor model catalog.
183
195
 
184
- Full Linear ↔ Cursor setup: <https://linear.app/docs/cursor>.
196
+ The full Linear + Cursor setup is at <https://linear.app/docs/cursor>.
185
197
 
186
198
  ---
187
199
 
188
200
  ## Distribution & install
189
201
 
190
- `.agents/` = **canonical**. `bkit install` regenerates host outputs (`.claude/**`, `.cursor/**`) and rewrites bkit-managed blocks across consumer repo.
202
+ `.agents/` is canonical. `bkit install` regenerates the host outputs (`.claude/**`, `.cursor/**`) and rewrites the bkit-managed blocks across the consumer repo.
191
203
 
192
- First-time install and upgrade, uninstall: `.bkit/install.md`. Ongoing ops below.
204
+ First-time install, upgrade and uninstall are in `.bkit/install.md`. Ongoing operations follow below.
193
205
 
194
- ### Upgrade — paste into your AI
206
+ ### Upgrade
195
207
 
196
- Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`.
197
-
198
- ````text
199
- Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
200
- 1. Bump and resync in one step (no token — npmjs is public). If `bkit` is not on PATH, use `pnpm bkit`:
201
- ```bash
202
- bkit upgrade --latest
203
- ```
204
- Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
205
- 2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why.
206
- 3. Read the template changes `bkit upgrade` printed (or `git diff .bkit/templates`), then `.bkit/templates.md`. bkit never applies templates, so adoption is your job: adopt each change unless it would break existing functionality. For any change not adopted, state which and why.
207
- 4. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
208
- ````
208
+ `bkit upgrade --latest` bumps the package and resyncs the managed files. `pnpm add` alone refreshes the package only. The paste block for your AI is in `.bkit/install.md` § Upgrade — already installed.
209
209
 
210
210
  ### Ongoing CLI
211
211
 
212
- ```bash
213
- bkit upgrade # re-render at CURRENT installed version (offline)
214
- bkit upgrade --latest # bump @cbartens/bkit + resync in one step (or --to=<version>)
215
- bkit check # drift gate — exits non-zero on drift
216
- bkit doctor # advisories only; exits 0; no managed-file writes
217
- bkit tips [--all] # what is not set up yet, most useful first; exits 0
218
- bkit stats # this repo's stats report, agent context peaks included → .bkit/stats.md (commit it); exits 0
219
- bkit install --claude --cursor # (re)seed hosts; name ≥1 module
220
- ```
212
+ Every `bkit` command with its flags (`bkit install`, `bkit upgrade`, `bkit check`, `bkit doctor`, `bkit tips`, `bkit stats`, and the `bkit <noun> <verb>` commands) is in `.bkit/cli.md`.
221
213
 
222
- **Outdated-version warning:** Step 1 of every phase workflow (`bkit repo info`) and every design / plan / audit doc stamp compare `.bkit/version` `pinnedVersion` with the newest published `@cbartens/bkit`; older → a warning naming the upgrade command, and stamped docs carry a visible `Outdated bkit` line under their `bkit:anchor` block. Never a stop. Registry asked at most once a day (cache: `<git common dir>/bkit-latest-version.json`); offline → no warning. `BKIT_NO_UPDATE_CHECK=1` skips the lookup (air-gapped machines, CI).
214
+ **Outdated-version warning:** Step 1 of every phase workflow (`bkit repo info`) and every design / plan / audit doc stamp compare `.bkit/version` `pinnedVersion` with the newest published `@cbartens/bkit`. When the pinned version is older, a warning names the upgrade command, and stamped docs carry a visible `Outdated bkit` line under their `bkit:anchor` block. The warning never stops a run. The registry is asked at most once a day, and the answer is cached in `<git common dir>/bkit-latest-version.json`. Offline, there is no warning. `BKIT_NO_UPDATE_CHECK=1` skips the lookup (air-gapped machines, CI).
223
215
 
224
- > **⚠️ Version bumps:** use `bkit upgrade --latest` (or `--to=<version>`). Bare `pnpm add @cbartens/bkit` / Renovate bumps refresh lockfile only — run `bkit upgrade` after and commit resync with the bump, or `bkit check` reds CI.
216
+ > **Version bumps:** use `bkit upgrade --latest` (or `--to=<version>`). A bare `pnpm add @cbartens/bkit` / Renovate bump refreshes only the lockfile. Run `bkit upgrade` after it, and commit the resync with the bump. Otherwise `bkit check` turns CI red.
225
217
 
226
- ### Dogfood path (this repo only)
218
+ ### Share friction with bkit
227
219
 
228
- bkit repo runs install script via `tsx` instead of published bin:
220
+ Workflows note each place bkit itself got in the way in `.bkit/friction.jsonl`, and `bkit stats` sums up your runs in `.bkit/stats.md`. Both stay in your repo. Copy this block to send them to bkit's makers as one public issue. Your agent removes anything that names your project and shows you the text before posting. `bkit tips` offers it again only when new friction arrives.
229
221
 
230
- ```bash
231
- pnpm tsx .bkit/core/engine/cli.ts install
232
- pnpm tsx .bkit/core/engine/cli.ts check
233
- ```
234
-
235
- CI drift gate (`.github/workflows/bkit-ci.yml`) fails PR if generated files diverge from `install` output.
222
+ ````text
223
+ Share this repo's bkit friction and stats with bkit's makers as one new issue on https://github.com/cbartens/bkit/issues.
224
+ 1. Refresh the stats. If `bkit` is not on PATH, use `pnpm bkit`:
225
+ ```bash
226
+ bkit stats
227
+ ```
228
+ 2. List the friction entries not shared yet, stripped to the fields bkit needs. The command keeps the newest row of each `key`, and keeps an entry only when it is `OPEN` and not `consumer` scope, because a `consumer` entry is about this project, not bkit:
229
+ ```bash
230
+ jq -R -n -c '[inputs | fromjson? | select(.kind == "friction")] | group_by(.key) | map(max_by(.ts)) | .[] | select((.status // "OPEN") == "OPEN" and .scope != "consumer") | {key, category, scope, severity, summary, description, remediation, recurrenceCount, version: .bkit.version, workflow: .by.workflow, step: .by.step} | with_entries(select(.value != null))' .bkit/friction.jsonl
231
+ ```
232
+ **If** nothing is listed → stop and say so.
233
+ 3. Clean every listed entry and `.bkit/stats.md`:
234
+ - Replace with `<redacted>` each thing that names this project or its people: repo, company and product names, people and handles, issue and PR numbers, URLs, hostnames, email addresses, and file paths outside bkit's own folders (`.bkit/`, `.agents/` and the host folders such as `.claude/`).
235
+ - Delete every key, token and password.
236
+ - **If** an entry still gives the project away, or no longer makes sense once cleaned → leave it out, and note why.
237
+ 4. Write the issue to `tmp/bkit-friction-report.md`:
238
+ - Title: `Friction report: {N} entries from bkit {version}`, where `{N}` = the entries in the body and `{version}` = `pinnedVersion` in `.bkit/version`. Example: `Friction report: 12 entries from bkit 6.0.0`.
239
+ - Body, in this order: the line `Friction and stats from a project using bkit {version}.`, a `jsonl` code block with the cleaned entries, then `.bkit/stats.md` from its first `##` heading on.
240
+ - **If** the body is over 60,000 characters, because the issue page rejects a body over 65,536:
241
+ - Leave out the lowest-severity entries first until it fits.
242
+ - Add a line to the body saying how many entries were left out for length.
243
+ 5. Show me the full title, the full body, and each entry left out with why.
244
+ - Post ONLY after I say yes.
245
+ - **If** I say no → stop. Post nothing and mark nothing.
246
+ 6. Post the issue to `cbartens/bkit` with the first of these that works:
247
+ - The GitHub MCP `issue_write` tool.
248
+ - `gh issue create --repo cbartens/bkit --title "<title>" --body-file tmp/bkit-friction-report.md`.
249
+ - **Else** → give me the file and https://github.com/cbartens/bkit/issues/new so I paste it myself, then ask me for the issue link.
250
+ 7. Mark each entry as shared, so `bkit tips` stops offering it. Append one same-`key` row per entry, the posted ones and the left-out ones, as `.bkit/jsonl.md` § Updating a Row describes, with `bkit ledgers append --ledger=friction --rows=-`:
251
+ - `status` = `TRIAGED`.
252
+ - `references` = the old `references` plus the issue link for a posted entry, or plus `not shared: {why}` for a left-out entry.
253
+ - `by` = `{"workflow": "utility", "step": "share-friction"}`.
254
+ 8. End with: the issue link, the entries shared, and each entry left out with why.
255
+ ````
236
256
 
237
257
  ## File ownership
238
258
 
@@ -241,24 +261,24 @@ bkit owns some files outright, owns one part of others, and ships the rest as te
241
261
  <!-- prettier-ignore -->
242
262
  | Kind | Semantics | Files |
243
263
  | --- | --- | --- |
244
- | **Tier 1 — Fully managed** | Idempotent rewrite of whole file on every install. A consumer edit is overwritten. Uninstall deletes the file while it still matches the hash bkit recorded. | `.cursor/hooks.json`, `.bkit/*.md` (except `prompts.md` and `lite.md`, Tier 2), `.bkit/.env.example`, `.bkit/allowlist.json`, `.cursor/cli.json` |
264
+ | **Tier 1 — Fully managed** | Idempotent rewrite of whole file on every install. A consumer edit is overwritten. Uninstall deletes the file while it still matches the hash bkit recorded. | `.bkit/*.md` (except `prompts.md`, Tier 2), `.bkit/.env.example`, `.bkit/allowlist.json`, `.cursor/cli.json` |
245
265
  | **Tier 2 — Managed-block** | bkit owns content between `bkit:start`/`bkit:end` markers. Consumer owns everything outside. File absent → write whole file. File present without markers → append block at EOF, unless the markdown file already holds an older unmarked copy of the block (its `# ` title plus 10+ long lines verbatim) → warn + skip. A full uninstall strips the block and deletes a file left with nothing else; `docs/templates/bkit-*.md` are bkit's whole and are deleted. | `docs/*.md`, `docs/templates/bkit-*.md`, `.gitignore`, `.agents/rules.md`, `.agents/context.md`, `.agents/docs.md`, `.agents/skills.md`, `AGENTS.md`, `CLAUDE.md`, `.claude/hooks/bkit-preflight.sh`, `.cursor/hooks/bkit-preflight.sh`, `.claude/hooks/bkit-gateguard.cjs`, `.cursor/hooks/bkit-gateguard.cjs`, `.opencode/plugin/bkit-gateguard.js`, `.cursor/hooks/bkit-guardrails.cjs`, `.codex/hooks/bkit-gateguard.cjs`, `.codex/hooks/bkit-guardrails.cjs` |
246
- | **Shared JSON** | bkit owns the keys its template sets; every other key is yours. `.mcp.json` / `.cursor/mcp.json`: bkit owns exactly one entry, `mcpServers.<tracker>`, and resets it to the template on every install and upgrade. | `.claude/settings.json`, `.opencode/opencode.json`, `.mcp.json`, `.cursor/mcp.json` |
266
+ | **Shared JSON** | bkit owns the keys its template sets; every other key is yours. `.mcp.json` / `.cursor/mcp.json`: bkit owns exactly one entry, `mcpServers.<tracker>`, and resets it to the template on every install and upgrade. | `.claude/settings.json`, `.cursor/hooks.json`, `.opencode/opencode.json`, `.mcp.json`, `.cursor/mcp.json` |
247
267
  | **Seeded package.json scripts** | Every install and upgrade adds a missing name with bkit's default; a name already present is never touched, whatever its value. `bkit check` reports a missing name. Uninstall leaves them. | `scripts.bkit:gate:format` / `bkit:gate:static` / `bkit:gate:static-unit` / `bkit:gate:install-static-unit-build` / `bkit:deps:outdated` / `bkit:deps:audit` |
248
- | **Seeded bkit settings** | Every install and upgrade writes every `bkit` setting, so each one is visible where you look for it. A missing key gets its default; a choice not made yet (tracker, cloud agents, board, opencode provider) gets `""` or `[]`, which reads the same as absent. A key already present is never touched, whatever its value; nested blocks get their missing keys. `bkit check` reports a missing key. | every key under `bkit`: `SEEDED_BKIT_DEFAULTS` in `.bkit/core/engine/install/modules/core.ts` |
249
- | **Templates** | Never written into your repo. Install and upgrade copy them, raw, into `.bkit/templates/`; you copy what you want and own it. Catalog: `.bkit/templates.md`. | `.github/workflows/bkit-ci.yml`, `.github/workflows/bkit-cloud.yml`, `.husky/*`, `.vale.ini`, `.vale/styles/House/*`, `.lintstagedrc.json`, `slop-scan.config.json`, `.oxlintrc.json`, `.prettierignore`, `.envrc`, `.cursor/{settings.json,environment.json,Dockerfile}`, dependency-updater examples, `.github/workflows/bkit-trivy.yml`, the per-provider context-fetch blocks (`context/bkit-*.md`), `scripts/slop/bkit-slop-type-suppression.mjs`. Also the tool `package.json` scripts (`typecheck`, `lint`, `format:check`, `lint:prose`, `lint:slop`, `slop:delta`, `prepare`) and devDeps (prettier, slop-scan, lint-staged, husky): `.bkit/templates.md` lists them, install never adds them. |
268
+ | **Seeded bkit settings** | Every install and upgrade writes every `bkit` setting, so each one is visible where you look for it. A missing key gets its default; a choice not made yet (tracker, cloud agents, board, OpenCode provider) gets `""` or `[]`, which reads the same as absent. A key already present is never touched, whatever its value; nested blocks get their missing keys. `bkit check` reports a missing key. | every key under `bkit`: `SEEDED_BKIT_DEFAULTS` in `.bkit/core/engine/install/modules/core.ts` |
269
+ | **Templates** | Never written into your repo. Install and upgrade copy them, raw, into `.bkit/templates/`; you copy what you want and own it. Catalog: `.bkit/templates.md`. | `.github/workflows/bkit-ci.yml`, `.github/workflows/bkit-cloud.yml`, `.husky/*`, `.vale.ini`, `.vale/styles/Bkit/*`, `.lintstagedrc.json`, `slop-scan.config.json`, `.oxlintrc.json`, `.prettierignore`, `.envrc`, `.cursor/{settings.json,environment.json,Dockerfile}`, dependency-updater examples, `.github/workflows/bkit-trivy.yml`, the per-provider context-fetch blocks (`context/bkit-*.md`), `scripts/slop/bkit-slop-type-suppression.mjs`. Also the tool `package.json` scripts (`typecheck`, `lint`, `format:check`, `bkit:lint:prose`, `lint:slop`, `bkit:slop:delta`, `prepare`) and devDeps (prettier, slop-scan, lint-staged, husky): `.bkit/templates.md` lists them, install never adds them. |
250
270
 
251
- **Marker syntax** format-specific:
271
+ **Marker syntax** depends on the file format:
252
272
 
253
273
  - Markdown: `<!-- bkit:start -->` / `<!-- bkit:end -->`
254
274
  - Shell / `.gitignore` / `.gitattributes`: `# <!-- bkit:start -->` / `# <!-- bkit:end -->`
255
- - JS / TS ES modules: `// bkit:start` / `// bkit:end` (HTML comments are a syntax error in an ES module)
275
+ - JS / TS ES modules: `// bkit:start` / `// bkit:end`, because HTML comments are a syntax error in an ES module.
256
276
 
257
- Comment prefixes (`# `, `// `) before markers preserved on block updates.
277
+ Block updates keep the comment prefixes (`# `, `// `) before the markers.
258
278
 
259
- **Managed-version marker.** Every non-JSON file bkit writes carries `bkit:managed vX.Y.Z` — first line inside the `bkit:start` block, or near the top of a whole file — in its comment syntax: `<!-- … -->` (markdown), `# <!-- … -->` (shell, `.gitignore`, `.gitattributes`, `.env.example`, TOML), `// …` (JS). The full MIT text and copyright notice travel at `.bkit/LICENSE.md`. Install and upgrade restamp it; `bkit check` reports `bkit-managed-stale` for a marker that differs from the installed version (blocker on `main` / `dev`, advisory on feature branches). Templates carry no marker and no block.
279
+ **Managed-version marker.** Every non-JSON file bkit writes carries `bkit:managed vX.Y.Z` in its comment syntax, as the first line inside the `bkit:start` block or near the top of a whole file: `<!-- … -->` (markdown), `# <!-- … -->` (shell, `.gitignore`, `.gitattributes`, `.env.example`, TOML), `// …` (JS). The full MIT text and copyright notice travel at `.bkit/LICENSE.md`. Install and upgrade restamp the marker. `bkit check` reports `bkit-managed-stale` for a marker that differs from the installed version: a blocker on `main` / `dev`, and an advisory on feature branches. Templates carry no marker and no block.
260
280
 
261
- **Hook scripts.** Install generates each host's `bkit-preflight.sh`, `gateguard`, `readguard` and `guardrails` hook from its template plus the code the hosts share (`.bkit/core/hooks/`, `.bkit/providers.md` § Hooks). bkit's block in the `bkit-gateguard` / `bkit-readguard` hooks and plugins and the `bkit-guardrails.cjs` hooks is a pure advisory engine — no stdin read, no stdout write, no top-level call — so it cannot collide with a consumer's own emitter. Delivery is per host: Claude / Cursor / Codex inject the checklist before the edit, opencode appends it to the tool result in `execute.after` (`BKIT_GATEGUARD=deny` is the only pre-edit block) — see `.bkit/providers.md` § Hooks. A consumer file with no markers gets the block appended; wire its exported function into your driver.
281
+ **Hook scripts.** Install generates each host's `bkit-preflight.sh`, `gateguard`, `readguard`, `guardrails` and `rules` hook from its template plus the code the hosts share (`.bkit/core/hooks/`, `.bkit/providers.md` § Hooks). bkit's block in the `bkit-gateguard` / `bkit-readguard` / `bkit-rules` hooks and plugins and the `bkit-guardrails.cjs` hooks is a pure advisory engine. It reads no stdin, writes no stdout and makes no top-level call, so it cannot collide with a consumer's own emitter. Delivery differs by host. Claude / Codex / Cursor inject the checklist before the edit. OpenCode appends it to the tool result in `execute.after` (`BKIT_GATEGUARD=deny` is the only pre-edit block). The rules-read advisory rides the two `bkit-preflight.sh` hooks at session start and the `bkit-rules` hook at the first tool call. See `.bkit/providers.md` § Hooks. A consumer file with no markers gets the block appended. Wire its exported function into your driver.
262
282
 
263
283
  ### What install writes
264
284
 
@@ -267,7 +287,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
267
287
  | --- | --- | --- | --- |
268
288
  | `.agents/{rules,docs,context,skills}.md` | core | `.bkit/core/.agents/` | Tier 2 html-comment (via the core payload pass — not the additive `.agents/` copy). Consumer `context-fetch`, `allowed-domains` and `mcp-servers` blocks live below `bkit:end` in `context.md`; `Project Skills` below `bkit:end` in `skills.md`. |
269
289
  | `.bkit/version` | core | package.json version | Written last (partial installs detectable) |
270
- | `.bkit/allowlist.json` | core | derived from bkit's shipped egress registry, union `.agents/context.md` allowed-domains | Tier 1 (canonical-overwrite). Curl/wget host allowlist every host's `bkit-guardrails.cjs` reads at runtime. |
290
+ | `.bkit/allowlist.json` | core | derived from bkit's shipped egress registry, union `.agents/context.md` allowed-domains | Tier 1 (canonical-overwrite). Curl / wget host allowlist every host's `bkit-guardrails.cjs` reads at runtime. |
271
291
  | `.gitignore` | core | `.bkit/shared/gitignore` | Tier 2 html-comment |
272
292
  | `AGENTS.md` | core | `.bkit/core/AGENTS.md` | Tier 2 html-comment |
273
293
  | `CLAUDE.md` | claude | `.bkit/shared/CLAUDE.md` | Tier 2 html-comment |
@@ -276,7 +296,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
276
296
  | `.gitattributes` | core | `.bkit/shared/.gitattributes` | Tier 2 html-comment (`merge=union` for the append-only ledgers) |
277
297
  | `.bkit/templates/**` | — | the whole `.bkit/templates/` root | Raw copies, refreshed on every install and upgrade; never hashed. Upgrade prints the changed paths. |
278
298
  | `.bkit/{core,shared}` | core | symlink into `node_modules/@cbartens/bkit/.bkit/{core,shared}` | View link, not a copy — browse the payload in-repo; always the installed version. Gitignored (dangles on a fresh clone / CI; install recreates). A real directory is never clobbered; `bkit uninstall` removes the link. |
279
- | `.bkit/{authoring,cloud,comparison,install,jsonl,LICENSE,lite,pipeline,providers,prompts,trackers,workflows,README}.md` | core | `.bkit/core/.bkit/` | Tier 1 (canonical-overwrite); `prompts.md` and `lite.md` Tier 2 html-comment. The reference docs agents read at runtime, plus `LICENSE.md`: the MIT text and copyright notice that travel with every file bkit writes. |
299
+ | `.bkit/{authoring,cloud,comparison,install,jsonl,LICENSE,pipeline,providers,prompts,router,trackers,workflows,README}.md` | core | `.bkit/core/.bkit/` | Tier 1 (canonical-overwrite); `prompts.md` Tier 2 html-comment. The reference docs agents read at runtime (`router.md`: the workflow router `AGENTS.md` sends `bkit-{command}` prompts to), plus `LICENSE.md`: the MIT text and copyright notice that travel with every file bkit writes. |
280
300
  | `.claude/commands/bkit-*.md` | claude | `.bkit/core/workflows/` (byte-identical) | Host pass — always overwrite |
281
301
  | `.claude/agents/bkit-*.md` | claude | `.bkit/core/prompts/` (byte-identical) | Host pass — always overwrite |
282
302
  | `.claude/settings.json` | claude | `.bkit/shared/.claude/settings.json` | Tier 2 JSON deep-containment. Permission allow/deny/ask + SessionStart / PreToolUse hook wiring. |
@@ -287,57 +307,43 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
287
307
  | `.bkit/.env.example` | claude | `.bkit/shared/.bkit/.env.example` | Tier 1 (fully managed). Real values go in `.bkit/.env`. |
288
308
  | `.cursor/commands/bkit-*.md` | cursor | `.bkit/core/workflows/` (T1+T2 transforms) | Host pass — always overwrite |
289
309
  | `.cursor/agents/bkit-*.md` | cursor | `.bkit/core/prompts/` (T3 transforms) | Host pass — always overwrite |
290
- | `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`. |
310
+ | `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`, `bkit:lint:prose`, `bkit:slop:delta`) and their devDeps are templates: `.bkit/templates.md`. |
291
311
  | `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. |
292
312
  | `package.json#bkit` (every key) | core | `SEEDED_BKIT_DEFAULTS` | Seeded (add-if-missing, nested blocks included; install and upgrade). Defaults where a key has one; `""` / `[]` for a choice not made yet. |
293
- | `.cursor/hooks.json` | cursor | `.bkit/shared/.cursor/hooks.json` | Tier 1 (fully managed) |
313
+ | `.cursor/hooks.json` | cursor | `.bkit/shared/.cursor/hooks.json` | Tier 2 JSON deep-containment |
294
314
  | `.cursor/mcp.json` | cursor | `.bkit/shared/.cursor/mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only |
295
315
  | `.cursor/rules/bkit-rules.mdc` | cursor | `.bkit/shared/.cursor/rules/bkit-rules.mdc` | Tier 2 html-comment |
296
316
  | `.cursor/hooks/bkit-preflight.sh` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 html-comment (`# ` prefix) |
297
- | `.cursor/hooks/bkit-guardrails.cjs` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 slash-comment. Destructive-op + curl/wget host gates. |
317
+ | `.cursor/hooks/bkit-guardrails.cjs` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 slash-comment. Destructive-op + curl / wget host gates. |
298
318
  | `.cursor/hooks/bkit-gateguard.cjs` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 slash-comment |
299
319
  | `.cursor/hooks/bkit-readguard.cjs` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 slash-comment. Repeat-read advisory. |
300
320
  | `.cursor/cli.json` | cursor | derived from `.agents/context.md` mcp-servers | Tier 1 (canonical-overwrite). Cursor CLI / cloud-agent `Mcp(<server>:*)` allows. |
301
- | `.opencode/opencode.json` | opencode | `.bkit/shared/.opencode/opencode.json` | Tier 2 JSON deep-containment; `@@OPENCODE_*@@` sentinels rendered to the chosen tracker + provider. **Opt-in via `bkit install --opencode=<provider>`**. |
302
- | `.opencode/commands/bkit-*.md` | opencode | `.bkit/core/workflows/` | Host pass — always overwrite |
303
- | `.opencode/agents/bkit-*.md` | opencode | `.bkit/core/prompts/` | Host pass — always overwrite |
304
- | `.opencode/plugin/bkit-gateguard.js` | opencode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment |
305
- | `.opencode/plugin/bkit-readguard.js` | opencode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment. Repeat-read advisory. |
321
+ | `.opencode/opencode.json` | OpenCode | `.bkit/shared/.opencode/opencode.json` | Tier 2 JSON deep-containment; `@@OPENCODE_*@@` sentinels rendered to the chosen tracker + provider. Opt-in via `bkit install --opencode=<provider>`. |
322
+ | `.opencode/commands/bkit-*.md` | OpenCode | `.bkit/core/workflows/` | Host pass — always overwrite |
323
+ | `.opencode/agents/bkit-*.md` | OpenCode | `.bkit/core/prompts/` | Host pass — always overwrite |
324
+ | `.opencode/plugin/bkit-gateguard.js` | OpenCode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment |
325
+ | `.opencode/plugin/bkit-readguard.js` | OpenCode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment. Repeat-read advisory. |
306
326
  | `.claude/hooks/bkit-cloud-bootstrap.sh` | — | `.bkit/templates/.claude/hooks/` | Copy-and-own template: no module writes it; adopt it from `.bkit/templates/` (the SessionStart entry runs it only when present). |
307
327
 
308
328
  The cloud workflow and the Cursor Background Agent files are templates the `--auto` setup advisory points at.
309
329
 
310
330
  ### Optional post-install decisions (tracker + cloud agents)
311
331
 
312
- 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.tracker.default`, `bkit.cloud.agent`; install seeds `""` = undecided); `"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.
313
-
314
- **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.dependencies.updater: "none"` skips the install-time absence advisory. `bkit check` emits `dep-updater-absent` and `dep-updater-both`. See `docs/deployments.md` § Dependency updaters.
332
+ Two capabilities are opt-in and left out of the default install: the **issue tracker** (`--tracker=github|linear|jira`) and **cloud agents** (`--auto=claude|cursor|opencode`). The default install ships zero cloud footprint. While a choice is undecided, its advisory fires (`tracker-setup-none` / `cloud-router-none`). Setting `"none"` in `bkit.tracker.default` / `bkit.cloud.agent` silences it. The dependency updater, security scan and test lint are copy-and-own templates. The choices, the defaults and how to decide are in `.bkit/install.md` § Optional post-install decisions. The template catalog is in `.bkit/templates.md`.
315
333
 
316
- **Security scan.** `.bkit/templates/.github/workflows/bkit-trivy.yml` fails CI on a HIGH or CRITICAL vulnerable package, risky config or committed secret, and runs daily. Copy it and own it; accept findings in `.trivyignore.yaml`. `bkit check` does not report its absence; `bkit tips` suggests it. See `.bkit/templates.md` § Trivy.
334
+ ### Updater PRs against your workflows
317
335
 
318
- **Test lint.** `.bkit/templates/.oxlintrc.json`: five Oxlint rules on JS / TS test files; `lint` fails on a test that cannot fail. Copy and own; set `lint` to `oxlint -c .oxlintrc.json --type-aware --deny-warnings`. Absent → `bkit check` silent, `bkit tips` suggests it. `.bkit/templates.md` § Oxlint.
319
-
320
- **All templates.** Copy and own, never installed. Catalog and install steps: `.bkit/templates.md`.
321
-
322
- ### dogfood rule — updater PRs against workflows (only if you opt in)
323
-
324
- bkit dogfoods templates: `.bkit/templates/.github/workflows/*.yml` (canonical) and `.github/workflows/*.yml` (bkit copy) must stay byte-equal where they overlap. Updater scans `.github/workflows/` only, not template path. Applies only if bkit-repo opted into updater. When updater PR opens against bkit workflows:
325
-
326
- 1. Before merge, edit matching `.bkit/templates/.github/workflows/*.yml` with same SHA bump (one `Edit` per file).
327
- 2. Run `pnpm test` (`.bkit/core/engine/audits/templates/template-action-pins.test.ts` fails when a template pin drifts from the repo's).
328
- 3. Push template-side change to updater PR branch (or follow-up commit on `dev` if branch read-only).
329
-
330
- Consumers: `.github/workflows/bkit-ci.yml` and `bkit-cloud.yml` are your copies of templates, so updater bumps survive install and upgrade. New pins in the templates arrive in `.bkit/templates/` on `bkit upgrade`; adopt them like any other template change.
336
+ `.github/workflows/bkit-ci.yml` and `bkit-cloud.yml` are your own copies of templates, so updater bumps survive install and upgrade. New pins in the templates arrive in `.bkit/templates/` on `bkit upgrade`. Adopt them like any other template change.
331
337
 
332
338
  ---
333
339
 
334
340
  ## Triggering workflows
335
341
 
336
- Three paths: Linear comment (cloud), Claude Code (interactive local), Cursor (interactive local). Same workflow from `.bkit/core/workflows/` — compute source and orchestrator model differ.
342
+ There are three paths: a Linear comment (cloud), Claude (interactive, local) and Cursor (interactive, local). All three run the same workflow from `.bkit/core/workflows/`. The compute source and the orchestrator model differ.
337
343
 
338
344
  ### From a tracker comment (cloud — Cursor Cloud Agent)
339
345
 
340
- **Linear tracker:** `@cursor` in Linear comment with slash command + issue ID:
346
+ **Linear tracker:** write `@cursor` in a Linear comment, with the slash command and the issue ID:
341
347
 
342
348
  ```
343
349
  @cursor /bkit-plan ISSUE-123
@@ -345,29 +351,34 @@ Three paths: Linear comment (cloud), Claude Code (interactive local), Cursor (in
345
351
  @cursor /bkit-ship ISSUE-123
346
352
  ```
347
353
 
348
- `@cursor` = **Cursor's standard Linear integration** — not bkit hook; bkit runs no Linear webhook. Native integration spawns Cloud Agent, posts session URL as Linear comment; agent runs bkit workflow because Cursor cloud agents read root `AGENTS.md`, routing `/bkit-*` to `.bkit/core/workflows/`. Progress in subsequent comments per step.
354
+ `@cursor` is Cursor's standard Linear integration, not a bkit hook. bkit runs no Linear webhook. The native integration spawns a Cloud Agent and posts the session URL as a Linear comment. The agent runs the bkit workflow because Cursor cloud agents read the root `AGENTS.md`, which routes `/bkit-*` to `.bkit/core/workflows/`. Progress for each step appears in later comments.
349
355
 
350
- **GitHub tracker:** PR-label trigger — Cursor Automations "Pull request label changed". `bkit:auto` on PR (from `bkit-build`) triggers dispatch; phase label (`bkit:plan`, `bkit:build`, etc.) selects workflow. Issue comments via GitHub MCP. `/bkit-design` / `/bkit-plan` no PR → local-IDE-only on Cursor cloud for GitHub tracker.
356
+ **GitHub tracker:** a PR label triggers the run, through the Cursor Automations trigger "Pull request label changed". `bkit:auto` on the PR (from `bkit-build`) triggers dispatch, and the phase label (`bkit:plan`, `bkit:build`, etc.) selects the workflow. Issue comments go through the GitHub MCP. `/bkit-design` / `/bkit-plan` have no PR, so with the GitHub tracker they are local-IDE-only on Cursor cloud.
351
357
 
352
- **Requirements (Linear):** `Auto` label + non-terminal state. `BKIT_LINEAR_API_KEY`, `BKIT_CURSOR_API_KEY`, `BKIT_ANTHROPIC_API_KEY`, `BKIT_GH_TOKEN` in Cursor Cloud Agent dashboard.
358
+ **Requirements (Linear):** the `Auto` label and a non-terminal state. `BKIT_LINEAR_API_KEY`, `BKIT_CURSOR_API_KEY`, `BKIT_ANTHROPIC_API_KEY` and `BKIT_GH_TOKEN` in the Cursor Cloud Agent dashboard.
353
359
 
354
- **Requirements (GitHub):** `BKIT_GH_TOKEN`, `BKIT_CURSOR_API_KEY`, `BKIT_ANTHROPIC_API_KEY` in dashboard. Cursor GitHub App on repo/org. `GITHUB_ISSUE_ID` from PR body `<!-- bkit:issue=#NNN -->` — no manual setup.
360
+ **Requirements (GitHub):** `BKIT_GH_TOKEN`, `BKIT_CURSOR_API_KEY` and `BKIT_ANTHROPIC_API_KEY` in the dashboard. The Cursor GitHub App on the repo/org. `GITHUB_ISSUE_ID` comes from the PR body's `<!-- bkit:issue=#NNN -->`, with no manual setup.
355
361
 
356
- ### From Claude Code (interactive — local)
362
+ ### From Claude (interactive — local)
357
363
 
358
- Slash commands at repo root:
364
+ Run the slash commands at the repo root:
359
365
 
360
366
  ```
361
367
  /bkit-design ISSUE-123 # produce a design doc
362
368
  /bkit-plan ISSUE-123 # produce an implementation plan
363
369
  /bkit-build ISSUE-123 # execute the plan in a worktree, open a PR
370
+ /bkit-build ISSUE-123 publish=false # build locally and hold: no push, no PR, no CI; land it later with /bkit-ship
364
371
  /bkit-debug ISSUE-123 # diagnose and remediate CI failures
365
- /bkit-ship ISSUE-123 # merge the PR for the current branch, archive, close the issue
372
+ /bkit-ship ISSUE-123 # merge the PR for the current branch, set the issue In Review
366
373
  ```
367
374
 
368
- Claude reads issue, comments, plan files via tracker MCP.
375
+ Claude reads the issue, its comments and the plan files through the tracker MCP.
369
376
 
370
- **Requirements:** `BKIT_GH_TOKEN`, active Claude Code session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` when `bkit.tracker.default = "linear"`; `BKIT_JIRA_API_KEY` when `"jira"`. Session model = orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column) — set via `/model` before invoking; not duplicated here.
377
+ **Held build:** `publish=false`, or `package.json` `bkit.workflows.build.publish.local: false`, stops a local `/bkit-build` before the push, and `/bkit-ship <ref>` lands it later. Cloud runs always publish. `.bkit/workflows.md` § `/bkit-build` — 16 steps, **Publish resolution**, says what a held run keeps and skips.
378
+
379
+ **Manual batch of held builds:** merge the held `feat/{FID}` branches into one branch off `dev` yourself, push it and open one PR. You own the push, the PR, the CI gate, the sweep and the docs sync. One head commit means post-merge auto-debug sees only the last FID. Never batch migrations.
380
+
381
+ **Requirements:** `BKIT_GH_TOKEN` and an active Claude session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` as well when `bkit.tracker.default = "linear"`, and `BKIT_JIRA_API_KEY` when it is `"jira"`. The session model is the orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column). Set it with `/model` before you invoke a command. This file does not repeat the pin.
371
382
 
372
383
  ### From Cursor (interactive — local)
373
384
 
@@ -377,25 +388,17 @@ Cursor 2.4+ honours `.cursor/commands/bkit-*.md` and `.cursor/agents/bkit-*.md`:
377
388
  /bkit-plan ISSUE-123
378
389
  ```
379
390
 
380
- Orchestrator reads `.cursor/commands/` workflow. Subagents via `Task`, `model:` from frontmatter (no host override).
391
+ The orchestrator reads the workflow in `.cursor/commands/`. It runs subagents through `Task`, and each subagent takes its `model:` from its frontmatter, with no host override.
381
392
 
382
- **Requirements:** `BKIT_GH_TOKEN` (GitHub, default) or `BKIT_LINEAR_API_KEY` (Linear) or `BKIT_JIRA_API_KEY` (Jira). Cursor account in good standing.
393
+ **Requirements:** `BKIT_GH_TOKEN` (GitHub, default) or `BKIT_LINEAR_API_KEY` (Linear) or `BKIT_JIRA_API_KEY` (Jira). A Cursor account in good standing.
383
394
 
384
395
  ---
385
396
 
386
397
  ## Adding or updating skills
387
398
 
388
- > **Skills must be installed before first use** — initial setup in `docs/setup.md`. Inventory and registry rules: `.agents/skills.md`.
399
+ > Permanent skills, installation checks and activation boundaries live in `.agents/skills.md`. Follow its § Install / Update before first use and after a bkit upgrade.
389
400
 
390
- Skills = third-party instruction sets loaded at invocation.
391
-
392
- ```bash
393
- npx skills find [query] # search the registry (check publisher / installs / stars)
394
- npx skills add <owner/repo>@<skill> -y # install one named skill, project-locally into .agents/skills/
395
- npx skills update # update all installed
396
- ```
397
-
398
- Installed list: `.agents/skills.md`. Skills in `.agents/skills/` not listed → pruned by ship workflow archive step.
401
+ Skills are third-party instruction sets, loaded for a matching task. The registry declares which skills survive Ship Step 7 (Prune Skills); the skill files and `skills-lock.json` record their installation. Adding a registry row alone does not install a skill.
399
402
 
400
403
  ---
401
404
 
@@ -410,6 +413,10 @@ Installed list: `.agents/skills.md`. Skills in `.agents/skills/` not listed →
410
413
  | `.bkit/authoring.md` | Authoring rules for every agent-read markdown file — docs, prompts, workflows; punctuation and capitals (§ Notation) |
411
414
  | `.agents/docs.md` | Document index and phase-matrix (what to read per phase) |
412
415
  | `.agents/skills.md` | Installed skills registry |
416
+ | `.bkit/templates/` | Copy-and-own templates, copied whole from the package at every install. Copy one to its landing path to adopt it (`.bkit/templates.md`). |
417
+ | `.bkit/install.md` | First-time install and upgrade, install lifecycle, uninstall |
418
+ | `.bkit/pipeline.md` | Pipeline reference: every subagent in execution order, CI scaffold, every audit template |
419
+ | `.bkit/comparison.md` | Comparison to peer frameworks / agentic design patterns |
413
420
  | `.bkit/providers.md` | Host differences (Claude/Cursor/opencode), transform rules, additive install, provider model IDs, pin process (§ Selecting pins), network allowlist encodings (`.bkit/allowlist.json` vs baked settings) |
414
421
  | `.bkit/friction.jsonl` | Friction ledger — orchestrator-observed recovery moments. Created on first append by a phase workflow, not by install; drained only by bkit's harvest (run from the bkit repo). Row shape: `.bkit/jsonl.md`. |
415
422
  | `.bkit/stats.jsonl` | Stats ledger — `outcome` / `compliance` / `counter` rows appended at every workflow close. Append-only. Row shape: `.bkit/jsonl.md`. |
@@ -419,25 +426,21 @@ Installed list: `.agents/skills.md`. Skills in `.agents/skills/` not listed →
419
426
  | `docs/audits/{YYYYMM}/` | Audit reports. Input to `/bkit-plan`, with or without a design. |
420
427
  | `docs/plans/{YYYYMM}/logs/{FID}/` | Per-run workflow logs (status, subagent outputs). Delete-eligible — bulk cleanup `rm -rf docs/plans/{YYYYMM}/logs/`. Canonical artifacts unaffected. |
421
428
  | `.bkit/issues.jsonl` | Issue-state ledger — appended at every phase close. Append-only. |
422
- | `docs/roadmap.md` | Phase-sectioned board + analysis. No tracker list — a wired tracker shows its own issues. Two consumer `## Notes` blocks (above the bkit list, last after analysis) survive every regenerate. Consumer-owned — never seeded/overwritten by `bkit install` |
429
+ | `docs/roadmap.md` | Phase-sectioned board + analysis. No tracker list — a wired tracker shows its own issues. Two consumer `## Notes` blocks (above the bkit list, last after analysis) survive every regenerate. Consumer-owned — never seeded / overwritten by `bkit install` |
423
430
  | `docs/deferrals.jsonl` | Deferred items |
424
431
 
425
432
  ### In the installed package, not your repo
426
433
 
427
- `bkit install` does not copy these out of `node_modules`. Read them at the path below — or
428
- in-repo through the `.bkit/core` / `.bkit/shared` view links install creates (symlinks into
429
- the package, so editors resolve them to the `node_modules/…` paths).
434
+ `bkit install` does not copy these out of `node_modules`. Read them at the path below, or in
435
+ the repo through the `.bkit/core` / `.bkit/shared` view links that install creates. The view
436
+ links are symlinks into the package, so editors resolve them to the `node_modules/…` paths.
430
437
 
431
438
  <!-- prettier-ignore -->
432
439
  | File | Purpose |
433
440
  | --- | --- |
434
- | `.bkit/install.md` | First-time install and upgrade, install lifecycle, uninstall |
435
- | `.bkit/pipeline.md` | Pipeline reference: every subagent in execution order, CI scaffold, every audit template |
436
- | `.bkit/comparison.md` | Comparison to peer frameworks / agentic design patterns |
437
441
  | `node_modules/@cbartens/bkit/.bkit/core/workflows/` | Canonical slash-command source (rendered into `.claude/commands/`, `.cursor/commands/`, `.opencode/commands/`) |
438
442
  | `node_modules/@cbartens/bkit/.bkit/core/prompts/` | Canonical subagent source (rendered into `.claude/agents/`, `.cursor/agents/`, `.opencode/agents/`) |
439
443
  | `node_modules/@cbartens/bkit/.bkit/{core,shared}/` | Sources `bkit install` writes from (see § What install writes) |
440
- | `node_modules/@cbartens/bkit/.bkit/templates/` | Copy-and-own templates copied raw into the consumer's `.bkit/templates/` (see `.bkit/templates.md`) |
441
444
  | `node_modules/@cbartens/bkit/dist/cli.js` | Install engine — renders host outputs and applies templates (`.bkit/core/engine/cli.ts` is the TypeScript source, not shipped as such) |
442
445
 
443
446
  ---
@@ -458,4 +461,4 @@ git add .bkit/core/workflows/bkit-build.md .claude/commands/bkit-build.md .curso
458
461
  git commit -m "chore: update build command"
459
462
  ```
460
463
 
461
- New subagent? Update `.bkit/core/.bkit/prompts.md` (the package source; install mirrors it to `.bkit/prompts.md`) with row (frontmatter rationale + `maxTurns` calibration + model assignment) before re-run install — single source of truth for agent metadata; CI drift gate enforces consistency.
464
+ For a new subagent, add its row to `.bkit/core/.bkit/prompts.md` before you re-run install, with its frontmatter rationale, `maxTurns` calibration and model assignment. That file is the package source, and install mirrors it to `.bkit/prompts.md`. It is the single source of truth for agent metadata, and the CI drift gate enforces consistency.