@cbartens/bkit 5.5.0 → 6.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +30 -20
- package/.bkit/core/.agents/docs.md +1 -0
- package/.bkit/core/.agents/rules.md +51 -26
- package/.bkit/core/.bkit/README.md +29 -19
- package/.bkit/core/.bkit/authoring.md +117 -0
- package/.bkit/core/.bkit/cloud.md +11 -11
- package/.bkit/core/.bkit/comparison.md +5 -5
- package/.bkit/core/.bkit/install.md +20 -20
- package/.bkit/core/.bkit/jsonl.md +202 -122
- package/.bkit/core/.bkit/lite.md +1 -1
- package/.bkit/core/.bkit/pipeline.md +49 -52
- package/.bkit/core/.bkit/prompts.md +106 -167
- package/.bkit/core/.bkit/providers.md +29 -32
- package/.bkit/core/.bkit/templates.md +44 -18
- package/.bkit/core/.bkit/trackers.md +60 -28
- package/.bkit/core/.bkit/workflows.md +399 -359
- package/.bkit/core/AGENTS.md +16 -22
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
- package/.bkit/core/docs/templates/bkit-plan.md +97 -226
- package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
- package/.bkit/core/engine/checks/after/github.ts +101 -72
- package/.bkit/core/engine/checks/after/index.ts +10 -12
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +47 -92
- package/.bkit/core/engine/checks/before/env.ts +2 -2
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +18 -1
- package/.bkit/core/engine/checks/before/repo.ts +168 -2
- package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
- package/.bkit/core/engine/checks/tips/detect.ts +34 -0
- package/.bkit/core/engine/checks/tips/index.ts +10 -7
- package/.bkit/core/engine/cli.ts +20 -53
- package/.bkit/core/engine/commands/analysis.ts +171 -140
- package/.bkit/core/engine/commands/ci/ci.ts +6 -6
- package/.bkit/core/engine/commands/comply.ts +77 -103
- package/.bkit/core/engine/commands/install/doctor.ts +2 -2
- package/.bkit/core/engine/commands/install/install.ts +57 -18
- package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
- package/.bkit/core/engine/commands/land.ts +18 -12
- package/.bkit/core/engine/commands/lib.ts +79 -17
- package/.bkit/core/engine/commands/registry.ts +4 -0
- package/.bkit/core/engine/commands/setup/setup.ts +7 -7
- package/.bkit/core/engine/commands/stats.ts +204 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
- package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
- package/.bkit/core/engine/commands/workflow/context.ts +853 -29
- package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
- package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
- package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
- package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
- package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
- package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
- package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
- package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
- package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
- package/.bkit/core/engine/commands/workflow/status.ts +142 -29
- package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
- package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
- package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
- package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
- package/.bkit/core/engine/install/manifest.ts +11 -9
- package/.bkit/core/engine/install/modules/cloud.ts +21 -13
- package/.bkit/core/engine/install/modules/core.ts +325 -7
- package/.bkit/core/engine/install/modules/opencode.ts +2 -2
- package/.bkit/core/engine/install/version-file.ts +6 -2
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +92 -15
- package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
- package/.bkit/core/engine/render/hosts.ts +4 -0
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/egress.ts +7 -0
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/settings.ts +202 -33
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
- package/.bkit/core/engine/tools/instructions.ts +1751 -0
- package/.bkit/core/hooks/gateguard-engine.js +24 -23
- package/.bkit/core/hooks/guardrails-shell.js +2 -3
- package/.bkit/core/hooks/guardrails-tiers.js +7 -1
- package/.bkit/core/hooks/readguard-engine.js +2 -2
- package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
- package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
- package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
- package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
- package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
- package/.bkit/core/prompts/bkit-design-generate.md +33 -13
- package/.bkit/core/prompts/bkit-design-organise.md +25 -12
- package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
- package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
- package/.bkit/core/prompts/bkit-design-spike.md +30 -13
- package/.bkit/core/prompts/bkit-design-update.md +33 -19
- package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
- package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
- package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
- package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
- package/.bkit/core/prompts/bkit-plan-update.md +61 -24
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
- package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
- package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
- package/.bkit/core/workflows/bkit-auto.md +54 -46
- package/.bkit/core/workflows/bkit-build.md +577 -458
- package/.bkit/core/workflows/bkit-debug.md +348 -333
- package/.bkit/core/workflows/bkit-design.md +201 -237
- package/.bkit/core/workflows/bkit-plan.md +210 -321
- package/.bkit/core/workflows/bkit-ship.md +328 -278
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/settings.json +11 -0
- package/.bkit/shared/.cursor/mcp.json +1 -1
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
- package/.bkit/shared/.gitattributes +1 -1
- package/.bkit/shared/.mcp.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -0
- package/.bkit/shared/CLAUDE.md +2 -2
- package/.bkit/shared/GEMINI.md +2 -2
- package/.bkit/shared/docs/architecture.md +1 -1
- package/.bkit/shared/docs/data-schema.md +1 -1
- package/.bkit/shared/docs/deployments.md +16 -28
- package/.bkit/shared/docs/design.md +1 -1
- package/.bkit/shared/docs/noise.md +1 -1
- package/.bkit/shared/docs/observability.md +2 -2
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/setup.md +1 -1
- package/.bkit/shared/docs/technology.md +1 -1
- package/.bkit/shared/docs/testing.md +27 -10
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
- package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
- package/.bkit/templates/.husky/pre-push +52 -13
- package/.bkit/templates/.prettierignore +7 -0
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
- package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
- package/CHANGELOG.md +142 -0
- package/README.md +58 -34
- package/dist/checks/after/ci-yml.js +39 -29
- package/dist/checks/after/github.js +99 -72
- package/dist/checks/after/index.js +11 -13
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +40 -83
- package/dist/checks/before/env.js +2 -2
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +15 -2
- package/dist/checks/before/repo.js +163 -2
- package/dist/checks/tips/catalogue.js +14 -5
- package/dist/checks/tips/detect.js +32 -0
- package/dist/checks/tips/index.js +7 -5
- package/dist/cli.js +19 -47
- package/dist/commands/analysis.js +109 -100
- package/dist/commands/ci/ci.js +6 -6
- package/dist/commands/comply.js +54 -91
- package/dist/commands/install/doctor.js +2 -2
- package/dist/commands/install/install.js +50 -19
- package/dist/commands/install/uninstall.js +59 -28
- package/dist/commands/land.js +16 -12
- package/dist/commands/lib.js +51 -16
- package/dist/commands/registry.js +4 -0
- package/dist/commands/setup/setup.js +7 -7
- package/dist/commands/stats.js +136 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +656 -56
- package/dist/commands/workflow/challenge.js +556 -0
- package/dist/commands/workflow/context.js +709 -30
- package/dist/commands/workflow/counters.js +208 -75
- package/dist/commands/workflow/decisions.js +441 -0
- package/dist/commands/workflow/disk.js +2 -2
- package/dist/commands/workflow/fids.js +689 -33
- package/dist/commands/workflow/issues.js +362 -99
- package/dist/commands/workflow/ledgers.js +762 -27
- package/dist/commands/workflow/locks.js +24 -2
- package/dist/commands/workflow/plan-blocks.js +437 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/prs.js +142 -32
- package/dist/commands/workflow/repo.js +52 -7
- package/dist/commands/workflow/roadmap.js +9 -7
- package/dist/commands/workflow/run-facts.js +426 -0
- package/dist/commands/workflow/runs.js +144 -43
- package/dist/commands/workflow/runtime.js +12 -1
- package/dist/commands/workflow/status.js +130 -29
- package/dist/commands/workflow/step-table.js +276 -0
- package/dist/commands/workflow/steps.js +171 -80
- package/dist/commands/workflow/summary.js +275 -0
- package/dist/commands/workflow/tests.js +834 -136
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +834 -195
- package/dist/commands/workflow/workstreams.js +11 -5
- package/dist/commands/workflow/worktrees.js +221 -22
- package/dist/install/manifest.js +11 -9
- package/dist/install/modules/cloud.js +22 -13
- package/dist/install/modules/core.js +326 -7
- package/dist/install/modules/opencode.js +2 -2
- package/dist/install/version-file.js +6 -2
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +61 -8
- package/dist/ledgers/telemetry.js +905 -124
- package/dist/render/hosts.js +4 -0
- package/dist/render/models.js +12 -0
- package/dist/shared/branches.js +3 -1
- package/dist/shared/egress.js +7 -0
- package/dist/shared/json.js +20 -7
- package/dist/shared/settings.js +147 -26
- package/dist/shared/text.js +333 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +721 -0
- package/dist/tools/instructions.js +1579 -0
- package/package.json +114 -23
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- package/.bkit/core/engine/tools/wording.ts +0 -748
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
- package/.bkit/core/prompts/bkit-build-summary.md +0 -94
- package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
- package/.bkit/core/prompts/bkit-design-summary.md +0 -107
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
- package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
- package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
- package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
- package/dist/commands/harvest.js +0 -353
- package/dist/tools/wording.js +0 -680
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Authoring Rules
|
|
2
|
+
|
|
3
|
+
{{BKIT_MANAGED_MARKER}}
|
|
4
|
+
|
|
5
|
+
> [!CAUTION]
|
|
6
|
+
> **Purpose:** One set of authoring rules for every agent-read markdown file — docs, prompts, workflows. § All Agent-Read Files binds every file; the later sections add the rules for one kind of file.
|
|
7
|
+
>
|
|
8
|
+
> **Rules:**
|
|
9
|
+
>
|
|
10
|
+
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
11
|
+
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
12
|
+
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
13
|
+
> - Ships to consumers: describe the current setup only. NEVER an internal identifier (tracker issue number, ledger key, review-finding id) and NEVER project history — decisions belong in `docs/decisions.jsonl`, incidents in `docs/knowledge.jsonl`.
|
|
14
|
+
> - A rule binding more than one kind of file goes in § All Agent-Read Files or § Prompts and Workflows, never in two places.
|
|
15
|
+
|
|
16
|
+
## All Agent-Read Files
|
|
17
|
+
|
|
18
|
+
Binds `.bkit/core/prompts/*.md`, `.bkit/core/workflows/*.md`, `.agents/**`, `.bkit/**`, `docs/**`, `AGENTS.md` and `CLAUDE.md`.
|
|
19
|
+
|
|
20
|
+
- **Dense:** → `.agents/rules.md` `Format`.
|
|
21
|
+
- **Current state:** describe current state / rules, not reasons / history; state what to do, not why. only exceptions: docs where purpose is the record.
|
|
22
|
+
- **Notation:** one job per mark — § `Notation`.
|
|
23
|
+
- **ASCII operators:** ASCII comparison / logic only — `!=`, `>=`, `<=`, `=>` — and `x` for times / dimensions. never Unicode math glyphs. Flow-arrow `→` in procedural conditionals / dispatch tables is **sole intentional non-ASCII glyph** — uniform documented flow notation (clearer than `->`, overloaded as member-access). Do not convert `→`.
|
|
24
|
+
- **Removal = delete:** drop instruction outright; never leave removal explanations.
|
|
25
|
+
|
|
26
|
+
### Notation
|
|
27
|
+
|
|
28
|
+
One job per mark; capitals and bold carry one meaning each. Binds every file § All Agent-Read Files binds; the docs `Rules` headers point here instead of restating it.
|
|
29
|
+
|
|
30
|
+
<!-- prettier-ignore -->
|
|
31
|
+
| Mark | Its only job |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| `→` | "then / goes to": the result of a condition, the next step, key to value, or a pointer to a file. A line holding only a jump (`→ Step 11.`) is allowed. |
|
|
34
|
+
| `.` | Ends a statement. It is the only thing that ends an `**If**` condition's scope. |
|
|
35
|
+
| `;` | Adds another instruction under the same rule or the same condition. Also splits lists of `A → B` pairs. |
|
|
36
|
+
| `,` | Separates list items only. never adds a second action after `→` — use `;`. |
|
|
37
|
+
| `:` | Introduces a breakdown or a label (`**Label:**`, `**If** X:` followed by sub-cases). |
|
|
38
|
+
| `—` | Attaches an explanation to the thing just named (term — what it is, step headings, empty table cells). never stands in for "because", "so" or "but": write the word, which costs the same tokens. |
|
|
39
|
+
| `-` | Hyphen for compound words and number ranges (`2-3`). never a dash, never an en dash `–`. |
|
|
40
|
+
| `/` | "Any of these, treated the same". Spaced between words (`build / debug`). Unspaced only in fixed terms (`I/O`, `CI/CD`, `try/catch`), rates (`1/run`) and inside backticks. Closed value sets are one tight backticked union (`DONE\|BLOCKED`), never a spaced slash between separately backticked values. Binds all three folders, not just prompts. |
|
|
41
|
+
| `()` | A short note on the word just before it: its members, a definition, a reference, an example or a scope limit. never a branch (`else …`, `**If**`), never a second instruction, never a reason. If the note needs one of those, it becomes its own sentence. |
|
|
42
|
+
|
|
43
|
+
**Capitals.** A word takes capitals only when it marks a hard limit: an action that is destructive, irreversible or security-sensitive, or a required field / machine-parsed invariant the run cannot proceed without. Closed list: `NEVER`, `ALWAYS`, `MUST`, `ONLY`, `PROHIBITED`. Everything else is lowercase, scope quantifiers and joining words included (`all`, `any`, `every`, `not`, `before`, `once`, `new`). One capitalised word per clause; never inside a label, a parenthetical or a description, never on a joining word.
|
|
44
|
+
|
|
45
|
+
**`NEVER` vs `do not`.** `NEVER` = forbidden everywhere, at all times (a hard limit). `do not` = forbidden in this step. The mixed-case `do NOT` is retired.
|
|
46
|
+
|
|
47
|
+
**Reason clauses.** At most one short reason clause, and only on a hard limit whose boundary a model would otherwise misread or over-apply — the single exception to § `Dense instructions only`. Elsewhere write the rule plainly.
|
|
48
|
+
|
|
49
|
+
**Bold.** Structure only, never emphasis: clause and field labels, conditional operators (`**If**`, `**Else**`, `**and**`, `**or**`), jump targets and terminal markers (`**STOP**`, `**Failure Path**`), and the prompt I/O markers (`**Create**`, `**Read**`, `**Update**`). No italics for emphasis. Bold and capitals together only on stop / route markers.
|
|
50
|
+
|
|
51
|
+
**Grammar.** Write normal English sentences, with articles and singular or plural as the meaning needs. Keep text dense by cutting filler, reasons, repetition and restating, never by dropping grammar words. When the number of items matters, say `each {item}` or `one {thing} per {item}` (`append one row per flaky test`). A subject and its pronoun agree in number (`files … them`, `a file … it`).
|
|
52
|
+
|
|
53
|
+
## Docs
|
|
54
|
+
|
|
55
|
+
Binds `.agents/**`, `.bkit/*.md` and `docs/*.md`; § All Agent-Read Files applies on top.
|
|
56
|
+
|
|
57
|
+
- **Rules header:** every doc opens with a `> [!CAUTION]` box holding `**Purpose:**` and `**Rules:**`; read the box of the file you edit and follow it.
|
|
58
|
+
- **One home per topic:** check the `.agents/docs.md` index first and confirm the topic belongs in this doc, not another. Two docs covering the same topic is a bug — pick a canonical home, link from the other.
|
|
59
|
+
- **Index:** a new doc gets one row in `.agents/docs.md` — phase columns and a one-line scope; pointers only, never text copied from the doc.
|
|
60
|
+
- **Shared wording:** every sentence 2+ shipped docs carry inside their `bkit:start` / `bkit:end` blocks, header bullets included, lives in `.bkit/instructions.md` § Clauses. Edit the clause, then run `pnpm instructions:sync`. Enforced by `.bkit/core/engine/tools/instructions.test.ts`.
|
|
61
|
+
|
|
62
|
+
## Prompts and Workflows
|
|
63
|
+
|
|
64
|
+
`.bkit/core/prompts/*.md` (subagents) and `.bkit/core/workflows/*.md` (orchestrators) are AI-only execution surfaces; every byte is paid on every run. § All Agent-Read Files applies on top; § Prompts Only and § Workflows Only add the rules for one kind.
|
|
65
|
+
|
|
66
|
+
- **These files are their own template:** always `grep` the folder of the file you edit (`.bkit/core/prompts/` or `.bkit/core/workflows/`) for closest existing cases and copy shapes verbatim before inventing wording / formatting (phrasing, variables, operators, conditionals, routes, jump targets, bolding, backticks, indentation, line breaks, punctuation, spacing). Match shapes for repeated sections: contract clauses, process steps, output format blocks, verdict mappings in prompts; subagent invocations, `bash` blocks, conditional routes, comment fences, gate checklists in workflows.
|
|
67
|
+
- **Procedural conditionals:** Flow-gating conditional → bold `**If** {condition} → {action}.` (`**Else** → {action}.` for branches), any syntactic shape. Test: reordering reads as "If {X}, {Y}" naturally → it is one. Excludes inline qualifiers (`if any`, `if defined`), dispatch tables (`PASS = …`, `STANDARD → …`), iteration (`For each …`), bash in backticks; workflows also exclude output-template placeholders.
|
|
68
|
+
- **Slash separator:** Alternation slash always spaced — `task / gate`, `CRITICAL / HIGH`. Fixed abbreviations (`I/O`) and anything inside backticks (paths, commands, enum unions) keep the bare form.
|
|
69
|
+
- **Variable references:** One name, one marker — the marker says who resolves it, and when. `{VAR}` = orchestrator substitutes before the text is used (paths, JSON, commit msgs, Context payloads, output templates). `$VAR` = bash expands at run time; it must be assigned in the same fenced block (shell state does not persist between blocks). Model-held value needed inside bash → assign it once at the top of the block (`VERDICT="{VERDICT}"`), then use `$VERDICT` below. `{lower}` / `{plain words}` = free text the writing agent fills in — never asserted non-empty. `{{VAR}}` = install-time token substituted by `bkit install` — distinct, do not unify. Enum sets are one tight backticked union in canonical order (`PASS|CONCERNS|FAIL`) — never spaced slashes or pipes; the spaced-slash rule does not apply inside backticks. Operators outside (`VERIFY_ATTEMPT` = 0). never `${VAR}` outside bash fences, except inline shell quoted as an instruction (`OWNER="${OWNER_REPO%/*}"`). § Prompts Only and § Workflows Only hold the rules that differ between the two.
|
|
70
|
+
- **Header blocks:** After `**Role:**` / `**Scope:**`, every prompt has three blocks, in this order: `**Protocol:**`, `**Contract:**`, `**Rules:**`. Each opens with a column-0 label line carrying its fixed lead-in (the `protocol-lead`, `contract-lead` and `rules-lead` clauses in `.bkit/instructions.md`), then one bullet per line. No `> [!CAUTION]` box. Workflows are orchestrator prompts and take the same three blocks.
|
|
71
|
+
- **Protocol:** how to work through this file; a line belongs here only when it would read the same in a file with a completely different job. `**Rules file:**` first, then `**Order:**`, `**No improv:**`; workflows add `**Narrate:**`, ``**`Failures`:**``, `**Placeholders:**`, `**Commands:**`, `**Timeouts:**`, `**CI wait turn-loop:**`.
|
|
72
|
+
- **Contract:** the deal between this agent and whoever runs it: the orchestrator for a prompt; the person who started it and the bkit engine (status rows, locks, tracker updates) for a workflow. What it is handed, what it may and may not do, what it must hand back, and the rules for filling in its deliverable: `**Read / Update / Create:**`, `**Mandate:**`, `**No commits:**`, then every line specific to this agent's job. A workflow's tracker groups (`<!-- bkit:tracker {name} start -->` to `end`) sit inside it.
|
|
73
|
+
- **Rules:** `.agents/rules.md` bullets copied word for word, in `rules.md` order. Nothing else.
|
|
74
|
+
- **Which block:** a line copied from `.agents/rules.md` → Rules. **Else** a line about the deal → Contract. **Else** → Protocol. A line saying what a bkit rule says, in any words, is that rule → the agent carries the rule in Rules and the line goes. A Protocol or Contract bullet copying a bkit rule's text, whole or cut short, fails `.bkit/core/engine/tools/instructions.ts`; a bullet sharing only a rule's label passes. Each header clause names its block (`- block:` in `.bkit/instructions.md`); the check fails a carrier holding it in another block.
|
|
75
|
+
- **Dense instructions only:** No rationale, commentary, parentheticals explaining why, or inline comments justifying behaviour — one exception: a single reason clause on a hard limit a model would otherwise misread (§ `Notation`). Every byte is paid on every run; explanations, decisions, trade-offs, history and commentary live in the catalogue of the file's kind (`.bkit/prompts.md`, `.bkit/workflows.md`).
|
|
76
|
+
- **Banned shapes:** a parenthetical explaining why a clause exists or a gate exists, an inline comment justifying behaviour or a step's behaviour, a note on what a previous version did, `we don't do X because Y`.
|
|
77
|
+
- **Cross-file alignment:** Check for shared instructions and change in all prompts / workflows using them. Each prompt copies, word for word, the bkit rules its agent acts on into its `**Rules:**` block (the rule's `- carry:` line in `.bkit/instructions.md` names the prompts).
|
|
78
|
+
- **Shared wording:** every sentence shared by 2+ prompts or 2+ workflows, header bullets included, and the header sentences workflows share with prompts live in `.bkit/instructions.md` § Clauses; a shared line carrying per-workflow detail is a `{{slot}}` template there. Edit the master (`.agents/rules.md` or the clause), then run `pnpm instructions:sync`. Enforced by `.bkit/core/engine/tools/instructions.test.ts`.
|
|
79
|
+
- **Self-contained:** every file must stand alone; inline all instructions; no file references. Exceptions: prompts — `.agents/rules.md`, `.agents/docs.md`, `.bkit/lite.md`, `*.jsonl` ledgers, supplied templates (plan, audit), read for shape only; workflows — subagent context.
|
|
80
|
+
|
|
81
|
+
## Prompts Only
|
|
82
|
+
|
|
83
|
+
Binds `.bkit/core/prompts/*.md`; § Prompts and Workflows applies on top. Per-agent frontmatter, models and catalogue rows → `.bkit/prompts.md`.
|
|
84
|
+
|
|
85
|
+
- **Standalone-runnable:** Works outside any workflow. Inputs via orchestrator-supplied Read paths. Multi-agent coordination: `**Parallel:**` + `**Lens discipline:**` Contract clauses.
|
|
86
|
+
- **Generic Role, specific Process:** `Role:` / `description:` anchor seniority titles ("Senior X", "Veteran X"). Lens behaviour in Process. Sibling lenses may name their lens in `Role:` / `description:`; siblings share seniority anchor. Same-audit diversity pairs (only model differs) → identical `Role:` lines.
|
|
87
|
+
- **Bold in body:** Only the `**Create**` / `**Read**` / `**Update**` I/O markers and the conditional operators (`**If**`, `**Else**`, `**and**`, `**or**`); § `Notation` holds the bold rule. Contract clause labels (`- **Mandate:**`) are the sole addition; bold inside a code span is literal output, not formatting.
|
|
88
|
+
- **Variable references:** `{lower.dotted}` = config key read from `package.json`. `<shape>` inside an output template describes the type of a value (`<integer >= 0>`), not a substitution. Closed-vocabulary tokens are backticked in prose, names and values alike (`` `severity` ``, `` `CRITICAL` ``, `` `OPTIONAL` ``, `` `PASS` ``, `` `DONE` ``), whether or not the literal is being compared. Field labels match their own Output format block verbatim, lowercase. Emphasis words stay bare; § `Notation` sets their capitals. Fenced output-format blocks stay literal: never add backticks inside them. Doc section citations name the title only (`docs/templates/bkit-plan.md` § `Open Questions & Assumptions`) — never carry the `##` heading marker.
|
|
89
|
+
- **Output section shape** content drives format:
|
|
90
|
+
- **Short structured fields** (single-phrase values, enum picks, one-sentence answers) → flat bracket: `[Field1 (hint), Field2 (hint), Field3 (hint)]`. One line, comma-separated.
|
|
91
|
+
- **Freeform, multi-finding, or multi-paragraph** (prose, prioritised lists, per-item findings, tables) → own heading + bracketed instruction: `## Section\n\n[Instructions describing what goes here; initially set to PENDING.]`
|
|
92
|
+
- Mixed (short fields + freeform) → H3 sub-headings under one H2; each follows rule above.
|
|
93
|
+
- **Conditionals inside `[…]`** carry the same bold form as procedural conditionals — never a bare `If X: …` or `If X then …`. Two shapes only. **Section gate** (whole section applies only under a verdict) leads, names the field, values bare: ``[**If** `Verdict` = CONCERNS or FAIL → {content}. **Else** → `None`.]``. **Empty case** (section always applies, may have nothing to report) trails: ``[{content}. **If** none → `None`; initially set to PENDING.]``. `→` carries the consequent, so `:` stays free for the per-item breakdown inside `{content}`.
|
|
94
|
+
- **Shape, not rules:** `[…]` states WHAT a section holds — fields, columns, format, empty case, `PENDING` init. Rules deciding content (defaults, allowed / banned values, trace requirements, verdict triggers) live in Process only; never restate them in Output format.
|
|
95
|
+
- **Output Lens line:** Parallel-sibling outputs: one `Lens:` line under H1 (deliverable name). Pattern: `Lens: {Name} — {comma-separated qualifiers}.` or compact `Lens: {field list}.` Single-line, no blank inside; blank line before next heading.
|
|
96
|
+
- **Template is shape, prompt owns rules:** a supplied template holds headings, tables, placeholders, checkbox labels, owner callouts and the lines engine code parses; every rule for filling, reviewing or acting on it lives in the prompt that acts on it, as a labelled Contract bullet worded the same in every prompt that carries it (`.bkit/instructions.md` § Template Instructions names the carriers). An audit template also keeps its own probe steps and template-specific rules.
|
|
97
|
+
- **Enforced elsewhere:** step numbers by `.bkit/core/engine/audits/repo/shipped-docs-refs.test.ts`, the managed-version marker by `.bkit/core/engine/audits/workflows/prompt-notation.test.ts`, shared sentences, the header blocks, the `**Rules file:**` bullet, and the `.agents/rules.md` group headings by `.bkit/core/engine/tools/instructions.test.ts` — the GateGuard advisory omits them because a test is the gate.
|
|
98
|
+
- **No step numbers:** never cite a step number — this prompt's own, the workflow's, or a supplied template's step / gate. Numbering shifts the moment a step is inserted. Name the action or section instead, or signal through `Verdict` and let the orchestrator route.
|
|
99
|
+
- **Managed-version marker:** `bkit install` / `upgrade` stamps ``<!-- bkit:managed vX.Y.Z — do not edit; run `bkit upgrade` to refresh -->`` into each rendered agent after the frontmatter, one blank line below (`stampManagedVersion`). never add the version line to a source prompt. `bkit check` flags `bkit-managed-stale` on marker drift: a hard blocker on `main` / `dev` and on PRs into them, an advisory on feature branches.
|
|
100
|
+
|
|
101
|
+
## Workflows Only
|
|
102
|
+
|
|
103
|
+
Binds `.bkit/core/workflows/*.md`; § Prompts and Workflows applies on top. Step catalogue, anatomy and per-phase tables → `.bkit/workflows.md`.
|
|
104
|
+
|
|
105
|
+
- **Bash decides, prose routes:** fenced block determines outcome → prose branches on **exit code** (`**If** exit non-zero → **Failure Path**.`) — never domain restatement (`**If** an open PR exists → …`). Internal constraints: imperative lead-in (`— NEVER onto a branch with an open PR:`), not `**If**`. 1 process branch → inline; 2+ branches → labeled decision / route block.
|
|
106
|
+
- **Labeled decision blocks:** 2+ branches → labeled heading-row + `-` bullets (one per branch) — never inline one line, never across numbered sub-steps. Labels: `Route:` (next Step / Failure Path); `Decide \`VAR\`:` (variable value). Single-branch (`**If** {X} → **Failure Path**`) stays inline.
|
|
107
|
+
- **Sibling-blind subagent Context:** `Context:` stays generic; agent prompts own lens via Process. Canonical: "You are a subagent in the {Phase} phase running in parallel with N other agents"; reconcilers: "Inputs carry distinct lenses — merge across them, max-wins on CRITICAL findings".
|
|
108
|
+
- **Bold is structural:** Conditional operators (`**If**`, `**Else**`, `**and**`, `**or**`, `**Run only if**`, `**Skip if**`), jump targets and terminal markers (`**Failure Path**`, `**STOP**`, named paths and guards; `Step N` stays unbolded), and block field labels (`**Subagent:**`, `**Tracker:**`, `**PROHIBITED:**`); § `Notation` holds the bold rule. Never bold an ordinary word for emphasis. Lowercase `**if**` is always wrong — the operator is `**If**`.
|
|
109
|
+
- **Variable references:** Standalone prose mention: backticked, sigil optional. Literal enum plain (**If** `VERDICT` = PASS). Fenced output blocks and unfenced output-template fragments: plain. Enforced by `.bkit/core/engine/audits/workflows/block-locality-audit.test.ts`.
|
|
110
|
+
- **Argument placeholders:** never `$0` to `$9` or `$ARGUMENTS`, fenced or not, because the host substitutes slash-command arguments (`$N` = `$ARGUMENTS[N]`, zero-based) into these files before the model reads them. Awk field reference → `$(N)`. never the host `\$N` escape (Claude Code only). Shell positional parameters have no `$(N)` equivalent; logic taking arguments becomes a `bkit <noun> <verb>` command (§ Workflow commands), and a block passes a flag list through `set --` / `"$@"`. Enforced by `.bkit/core/engine/audits/workflows/slash-arg-expansion.test.ts`.
|
|
111
|
+
- **Variable names:** held step output = `{LOOP}_{FIELD}` in UPPER_SNAKE; prefix names the loop, not the agent (`VERIFY_FIXED` from gaps-remediate, `CHALLENGE_TASKS` from `challenge merge`); two-value flags take lowercase `true|false`.
|
|
112
|
+
- **Gate items:** `- [ ]` + general prose reminder of what the step did — never a step detail (condition, path, variable, value set, field list, exit code) — `.bkit/workflows.md` § `Gates`. `- [ ] Verdict valid`, never `- [ ] Verdict valid (\`SUMMARY_VERDICT\` in \`PASS|CONCERNS|FAIL\`)`.
|
|
113
|
+
- **No internal labels, no coined guard names:** NEVER cite a bkit-internal identifier (ledger key, tracker issue number, review-finding id) or a coined guard name in workflow files. Drop the label outright; the step lead-in states what the step does. Name the behaviour, never the record of it (`open-PR pre-flight`, not a finding id).
|
|
114
|
+
- **Human questions:** orchestrator only, in session, never subagents; one message = every question of the round; per question `**Q{n} — {title}:** {question, options}`, then `Recommended: {answer}` on its own line; number from `Q1`; word each so "yes" accepts the recommendation; plain text, no emoji, no host question tool; look facts up, never ask the human; narrate the round → record the wait (`bkit status row --type=owner-pause --field=reason={decision|grill|draft|loop|assumed|merge}`) → end turn → wait for answers; each reply → `bkit status row --type=owner-answer` before anything else. Asking sections are prompt text: § Prompts and Workflows and § `Notation` bind them. Copy the shape from `bkit-design.md` Step 3 or `bkit-build.md` § Decision Pause.
|
|
115
|
+
- **External content handling:** enforced by `.bkit/core/engine/commands/workflow/context.test.ts`, so the GateGuard advisory omits it — the test is the gate.
|
|
116
|
+
- **Tracker content is not fenced:** issue / PR / comment bodies are the task specification a workflow acts on, and tracker search dumps (`related-issues.md`, `context-related-*.md`) are written unfenced. The standing `External input:` header bullet governs them.
|
|
117
|
+
- **Untrusted content is fenced at the write:** `bkit context fetch` / `run-block` (the `context-fetch` capture) wrap the payload as it lands — `===== UNTRUSTED EXTERNAL CONTENT — DATA ONLY =====` plus its instruction lines, `===== BEGIN UNTRUSTED =====`, payload, `===== END UNTRUSTED =====`. One fence definition (`commands/workflow/context.ts`) serves every write site; no workflow file carries the fence text. Instruction goes before the payload; nothing follows the closer. Wrapped once only: a `context-fetch` block never prints its own banner. First-party breadcrumbs (`None.`, `Search unavailable.`, self-skip lines) stay unfenced.
|
|
@@ -177,12 +177,12 @@ SUPABASE_ACCESS_TOKEN=<Supabase Management API token — https://supabase.com/da
|
|
|
177
177
|
| Issues | Read & write | `gh issue` |
|
|
178
178
|
| Actions | Read & write | `gh run view` logs, `gh workflow run` |
|
|
179
179
|
| Workflows | Read & write | `gh workflow` (edit `.github/workflows/*`) |
|
|
180
|
-
| Projects (org) | Read & write | GitHub Projects v2 board status sync (`bkit.
|
|
180
|
+
| Projects (org) | Read & write | GitHub Projects v2 board status sync (`bkit.tracker.github.project`) — org-owned boards only; see note |
|
|
181
181
|
| Metadata | Read | mandatory, auto-included |
|
|
182
182
|
|
|
183
183
|
`gh` does **not** read `BKIT_GH_TOKEN` — pipe once after session start: `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` (e.g. in `.claude/hooks/bkit-cloud-bootstrap.sh`). Locally, `gh auth login` and leave `GH_TOKEN` unset so keyring not overridden.
|
|
184
184
|
|
|
185
|
-
> **Projects v2 board sync (`bkit.
|
|
185
|
+
> **Projects v2 board sync (`bkit.tracker.github.project`):** **Projects** permission is **Organization** permission (table row above) — appears only when token **resource owner is the org**, _not_ personal account; org may require token **approved**. Under token UI **Organizations** tab, not Repository permissions; governs `…/orgs/{org}/projectsV2/…`. User-owned (personal-account) boards unreachable by fine-grained PATs — see below.
|
|
186
186
|
|
|
187
187
|
#### When classic is still required
|
|
188
188
|
|
|
@@ -218,7 +218,7 @@ Token management by session type:
|
|
|
218
218
|
|
|
219
219
|
## MCP issue-tracker integration
|
|
220
220
|
|
|
221
|
-
bkit wires the chosen tracker's MCP server (`bkit.
|
|
221
|
+
bkit wires the chosen tracker's MCP server (`bkit.tracker.default`) into `.mcp.json` at repo root (project-shared, read by Claude Code `/mcp` UI). Cursor reads same shape from `.cursor/mcp.json`. All **remote HTTP MCPs** — no docker. GitHub: `BKIT_GH_TOKEN` PAT in the `Authorization` header — no OAuth. Linear: OAuth on first use — Claude Code launches browser auth on first server touch, stores token in own secret store. Jira: `BKIT_JIRA_API_KEY` scoped token in the `Authorization` header — no OAuth.
|
|
222
222
|
|
|
223
223
|
> Note: `mcpServers` in `.claude/settings.json` silently ignored by Claude Code — definitions only from `.mcp.json` (project) or `claude mcp add` (user scope). `mcp__<name>__*` in `.claude/settings.json` `permissions.allow` are tool-permission allowlists — different concern, remain there.
|
|
224
224
|
|
|
@@ -233,7 +233,7 @@ bkit wires the chosen tracker's MCP server (`bkit.issueTracker`) into `.mcp.json
|
|
|
233
233
|
"jira": {
|
|
234
234
|
"type": "http",
|
|
235
235
|
"url": "https://mcp.atlassian.com/v2/mcp",
|
|
236
|
-
"headers": { "Authorization": "Bearer ${
|
|
236
|
+
"headers": { "Authorization": "Bearer ${BKIT_JIRA_API_KEY}" }
|
|
237
237
|
}
|
|
238
238
|
}
|
|
239
239
|
```
|
|
@@ -241,14 +241,14 @@ bkit wires the chosen tracker's MCP server (`bkit.issueTracker`) into `.mcp.json
|
|
|
241
241
|
`"type": "http"` required — without it Claude Code defaults to stdio transport and rejects entry for missing `command`.
|
|
242
242
|
|
|
243
243
|
- **GitHub** — official GitHub MCP at `api.githubcopilot.com` (not gated by Copilot subscription). Surface: `issue_write`, `add_issue_comment`, `label_write`, `projects_write`, etc. Used under GitHub provider. Endpoint does **not** support OAuth DCR → auth via `Authorization: Bearer ${BKIT_GH_TOKEN}` (MCP-only env var — see § Environment variables and KN-CORE-8).
|
|
244
|
-
- **Linear** — full Linear workspace surface (`get_issue`, `save_issue`, `save_comment`, `list_*`). Used when `bkit.
|
|
245
|
-
- **Jira** — Atlassian Rovo MCP at `mcp.atlassian.com/v2/mcp`. Surface: `getJiraIssue`, `editJiraIssue`, `transitionJiraIssue`, `addOrEditJiraIssueComment`, `searchJiraIssuesUsingJql`, `executeRead` / `executeWrite`. Used when `bkit.
|
|
244
|
+
- **Linear** — full Linear workspace surface (`get_issue`, `save_issue`, `save_comment`, `list_*`). Used when `bkit.tracker.default` = `linear`. OAuth (Dynamic Client Registration) — browser flow on first use, no env var.
|
|
245
|
+
- **Jira** — Atlassian Rovo MCP at `mcp.atlassian.com/v2/mcp`. Surface: `getJiraIssue`, `editJiraIssue`, `transitionJiraIssue`, `addOrEditJiraIssueComment`, `searchJiraIssuesUsingJql`, `executeRead` / `executeWrite`. Used when `bkit.tracker.default` = `jira`. Auth via `Authorization: Bearer ${BKIT_JIRA_API_KEY}` — a scoped **Atlassian MCP V2** token; org admin must allow API-token sign-in (`.bkit/trackers.md` § jira — setup and notes).
|
|
246
246
|
|
|
247
247
|
**Auth flow per server:**
|
|
248
248
|
|
|
249
249
|
- **GitHub:** Claude Code substitutes `${BKIT_GH_TOKEN}` from environment at session start. Unset → server fails. Set in shell (`export BKIT_GH_TOKEN=...`) or cloud dashboard.
|
|
250
250
|
- **Linear:** Claude Code prompts browser authorize on first use; token in Claude's secret store. No further action.
|
|
251
|
-
- **Jira:** Claude Code substitutes `${
|
|
251
|
+
- **Jira:** Claude Code substitutes `${BKIT_JIRA_API_KEY}` from environment at session start. Unset or classic token → every Jira call fails.
|
|
252
252
|
|
|
253
253
|
**`gh auth login` required for gh CLI surface** (PR creation, branch ops, git push). Locally, keyring — do not export `GH_TOKEN` from `.bkit/.env`. Cloud/headless: `bkit-cloud-bootstrap.sh` runs `printf '%s' "$BKIT_GH_TOKEN" | gh auth login --with-token` at SessionStart (guarded by the `bkit runtime detect` gh probe, no-ops on Actions runner where `GITHUB_TOKEN` auths) — no manual step. Same PAT value fine; different env-var name keeps local `gh` on keyring.
|
|
254
254
|
|
|
@@ -396,7 +396,7 @@ When bkit reference Dockerfile changes (e.g. vale bump):
|
|
|
396
396
|
|
|
397
397
|
# Post-CI auto-routing
|
|
398
398
|
|
|
399
|
-
After `bkit-build` Step
|
|
399
|
+
After `bkit-build` Step 15 close-workflow pushes CI-trigger commit (`chore({FID}): close-workflow`, no skip tags) and exits, post-CI router decides ship vs. debug and dispatches matching skill in fresh cloud session — no operator action between CI completion and dispatched session.
|
|
400
400
|
|
|
401
401
|
Routing **logic** in single bkit-managed slash-command orchestrator (`.bkit/core/workflows/bkit-auto.md`, mirrored to `.claude/commands/bkit-auto.md` + `.cursor/commands/bkit-auto.md` on each `pnpm bkit install`). Routing **trigger** wired separately per IDE — different event surfaces.
|
|
402
402
|
|
|
@@ -435,7 +435,7 @@ Flip **both** org and repo before first router run — else `actions/checkout` 4
|
|
|
435
435
|
| `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` variables | `claude` | Keyless alternative: the action trades the job's GitHub OIDC token for a short-lived Claude API token. | IDs, not secrets — repo **variables**. Optional `ANTHROPIC_SERVICE_ACCOUNT_ID` / `ANTHROPIC_WORKSPACE_ID`. § Claude — workload identity federation. |
|
|
436
436
|
| `OPENCODE_PROVIDER_KEY` | `opencode` | Fanned out to every cloud provider's env var name (`BKIT_OPENROUTER_API_KEY`, `BKIT_OLLAMA_API_KEY`, `BKIT_OPENCODE_API_KEY`) so the `.opencode/opencode.json` `{env:VAR}` reference resolves whichever provider is installed. | Provider API key for whichever provider you configured. |
|
|
437
437
|
|
|
438
|
-
A `context` job (`Check runner credentials` step) checks both credentials and resolves phase + arg once, no-op unless `package.json` `bkit.
|
|
438
|
+
A `context` job (`Check runner credentials` step) checks both credentials and resolves phase + arg once, no-op unless `package.json` `bkit.tracker.default` is `github` or unset (Linear cloud runs start from Cursor's Linear integration; Jira runs locally only); each runner job needs it and runs only when its own credential is set. Claude credential = `ANTHROPIC_API_KEY`, or **both** federation variables (one alone → `::notice::` naming the missing one, claude no-op). Only claude credential → claude job only. Only `OPENCODE_PROVIDER_KEY` → opencode only. Both → both jobs (additive coexistence). **No `BKIT_LINEAR_API_KEY`** — `bkit-cloud.yml` GitHub-tracker only for both jobs. Workflow grants `id-token: write` per-job for claude only (Claude GitHub App + federation token exchange; opencode no OIDC).
|
|
439
439
|
|
|
440
440
|
## Claude — workload identity federation
|
|
441
441
|
|
|
@@ -496,8 +496,8 @@ Skip conditions emit single GitHub-comment no-op line and exit 0 — only real f
|
|
|
496
496
|
|
|
497
497
|
## Operating notes
|
|
498
498
|
|
|
499
|
-
- **Loop bound (pre-merge `feat/**`):** `/bkit-debug` enforces `
|
|
500
|
-
- **Loop bound (`dev`):** `
|
|
499
|
+
- **Loop bound (pre-merge `feat/**`):** `/bkit-debug` enforces `bkit.workflows.debug.fix` and `.soak` `maxAttempts` internally, counted across every debug run of the feature; the router never counts attempts. Once fix attempts are used up debug switches to soak; once soak attempts are used up it takes the Failure Path (handover) and stops.
|
|
500
|
+
- **Loop bound (`dev`):** `bkit.workflows.debug.fix.maxAttempts` + `bkit.workflows.debug.soak.maxAttempts` (2 + 2 by default) distinct failed CI SHAs per `{FID}`, all-time — every debug run makes at least one attempt, so more dispatches could never run one. The router reads both from `package.json` with `jq` (bkit is not installed at that point), falling back to 2 for a missing or bad value as the engine does. This is the surface that needs a cross-session cap: `/bkit-debug` adopts `dev` in place, so its fix push re-reds `dev` CI and re-triggers this same router. Checked and written by the ctx step of `bkit-cloud.yml`'s `context` job immediately before dispatch, so a run that could not record its own attempts is still bounded. The counter row (`type: "dev-dispatch"`) is committed to `dev` with `[skip ci]` before dispatch, and its presence on `origin/dev` is verified after one retry — a row landing nowhere durable would degrade the cap to unbounded. Exhausted → no-op + `::notice::` for operator review (delete the rows in `status.jsonl` to reset).
|
|
501
501
|
- **GHA 6 h cap:** `3 x ~3600s` per debug attempt = well under GHA runner ceiling. Ship is short.
|
|
502
502
|
- **Concurrency:** `cancel-in-progress` is `true` for `feat/**` (latest-wins) and `false` for `dev`, so an in-flight `/bkit-debug` finishes instead of being cancelled mid-run with a half-written `status.jsonl` or a held worktree lock. GHA queues at most one pending run per group; the queued run re-checks the dispatch cap when it starts, so the same `{FID}` needs no manual re-trigger. Cursor dashboard trigger → "latest-supersedes." Ship squash-merge atomic — mid-run cancels cannot corrupt PR state.
|
|
503
503
|
- **`bkit-auto-dev` is one concurrency group for all FIDs.** GHA resolves `concurrency.group` from trigger-payload context before the ctx step derives the `{FID}`, so the group cannot be keyed on it. Two different FIDs failing `dev` CI near-simultaneously → queue-collapse can drop the older, different FID's pending run. The stale-run guard detects it (its head SHA no longer matches the most-recent-completed `dev` CI run) and writes a `dev-dispatch-dropped` row to the job summary plus a `::warning::`, rather than discarding it silently. Job summary, not a committed `status.jsonl`: this branch is only reached because `dev` already advanced, so committing the row would usually be a non-fast-forward and be lost in exactly the case it records.
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
|
|
25
25
|
## What this is
|
|
26
26
|
|
|
27
|
-
bkit turns a single coding-agent request into gated, peer-reviewed engineering: five commands (`/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`),
|
|
27
|
+
bkit turns a single coding-agent request into gated, peer-reviewed engineering: five commands (`/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`), 39 single-purpose subagents, 35 audit templates, same pipeline on Claude Code, Cursor, Codex, Google Antigravity and opencode. Every subagent in execution order and every audit template: [`.bkit/pipeline.md`](pipeline.md).
|
|
28
28
|
|
|
29
29
|
This doc: bkit vs 10 other AI development frameworks (one table, then agents and CI in detail), then bkit vs Gulli's agentic patterns.
|
|
30
30
|
|
|
@@ -125,11 +125,11 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
|
|
|
125
125
|
| --- | --- | --- |
|
|
126
126
|
| Prompt Chaining | Already does | Every workflow is prompt chaining at slash-command granularity. |
|
|
127
127
|
| Routing | Already does | `Verdict` routing (PASS/CONCERNS/FAIL), strategy escalation, CI-router dispatch to ship vs debug. |
|
|
128
|
-
| Parallelization | Already does | Parallel pairs and triplets, with a tighter constraint than the book: no sibling reads, plus cross-model pairing on design brainstorm / design review
|
|
128
|
+
| Parallelization | Already does | Parallel pairs and triplets, with a tighter constraint than the book: no sibling reads, plus cross-model pairing on design brainstorm / design review. |
|
|
129
129
|
| Reflection (producer-critic) | Already does | Build execute → verify → remediate loop; plan and design generate → review → update. |
|
|
130
130
|
| Tool Use | Already does | Per-role minimum-capability tool allowlists — stricter than the book's additive model. |
|
|
131
131
|
| Planning | Already does | `/bkit-plan` is a first-class artifact with a template and durable checkbox state. |
|
|
132
|
-
| Multi-Agent Collaboration | Already does |
|
|
132
|
+
| Multi-Agent Collaboration | Already does | 39 subagents, orchestrator-as-coordinator; subagents are leaves (no nested orchestration). |
|
|
133
133
|
| Model Context Protocol (MCP) | Already does | Tracker MCP held at the workflow layer only — cleaner separation than the book's examples. |
|
|
134
134
|
| Exception Handling & Recovery | Already does | Universal failure path, bounded retries (3), 3600s timeouts, runaway-turn caps, human handover. |
|
|
135
135
|
| Human-in-the-Loop | Already does | Mandatory hard stops after design / plan / ship; "recommend, do not decide." |
|
|
@@ -137,7 +137,7 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
|
|
|
137
137
|
| Context Engineering | Already does | Phase doc-matrix, lazy-load, output caps, stubbed-output pattern; consumer `context-fetch` blocks add CI, diff, e2e, runtime and web signal in debug. |
|
|
138
138
|
| Memory Management | Partial | Filesystem and grep episodic memory (`status.jsonl`, knowledge / decisions). No vector retrieval, by scale choice. |
|
|
139
139
|
| Learning & Adaptation | Partial | `friction.jsonl` drives human-reviewed prompt edits; entries carry confidence, scope, and last-confirmed fields. No auto prompt-tuning — deliberate, to keep humans in the loop. |
|
|
140
|
-
| Goal Setting & Monitoring | Already does | Issue = goal, phase labels = state, verdicts = criteria. Per-task `
|
|
140
|
+
| Goal Setting & Monitoring | Already does | Issue = goal, phase labels = state, verdicts = criteria. Per-task `DONE WHEN:` in the plan template; verifier ticks only on confirmed artifacts; deferred-sweep FAILs merge on any unplanned gap; `stats.jsonl` tracks every run. |
|
|
141
141
|
| Knowledge Retrieval (RAG) | Partial | Deterministic doc-matrix retrieval plus web search in design review. No embedding RAG (Grep wins at repo scale). |
|
|
142
142
|
| Reasoning Techniques | Partial | Extended thinking (CoT) plus parallel-pair-reconcile (a form of self-consistency). No formal ToT or ReAct trace. |
|
|
143
143
|
| Guardrails / Safety | Partial | Tool sandbox, destructive-git bans, locks, verdict checks, and an advisory edit-investigation plus gate-config hook (GateGuard), and an advisory repeat-read hook (ReadGuard). `bkit steps finish` validates each step's verdict and artifacts structurally. No content-level output validators (e.g. safety classifiers). |
|
|
@@ -151,7 +151,7 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
|
|
|
151
151
|
### Where bkit goes beyond the catalogue
|
|
152
152
|
|
|
153
153
|
- **Producer-critic with circular-reasoning guard.** Sibling reviewers cannot read each other's output. Book permits self-reflection.
|
|
154
|
-
- **Cross-model diversity where breadth beats depth.** Design brainstorm
|
|
154
|
+
- **Cross-model diversity where breadth beats depth.** Design brainstorm and design review groups pair Opus + Sonnet (Grok + Composer on Cursor) → two reasoners review same work. Depth-sensitive lenses (plan review, plan scope check, build challenge) stay on top tier.
|
|
155
155
|
- **Resume-from-state as single source of truth.** `status.jsonl` makes every run inspectable and restartable; book treats this only obliquely under memory.
|
|
156
156
|
- **Human-in-the-loop as non-negotiable.** Hard stops after design / plan / ship; book treats HITL as one option.
|
|
157
157
|
- **Fail-soft external context in debug.** Provider-agnostic `context-fetch` blocks (CI logs, diff, e2e, runtime, web) feed `/bkit-debug`; each self-skips to a narrated `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` state, so a context with no block is never read as a clean result.
|
|
@@ -62,7 +62,7 @@ Run these in order on a brand-new consumer repo.
|
|
|
62
62
|
| --- | --- | --- |
|
|
63
63
|
| 1 | `pnpm add -D @cbartens/bkit` — no token, no registry mapping | this section |
|
|
64
64
|
| 2 | Run `bkit install --claude --cursor` to seed both hosts (writes `.bkit/.env.example`; `.envrc` is a template in `.bkit/templates/`) | this section |
|
|
65
|
-
| 3 | Set up direnv + `.bkit/.env` for `BKIT_GH_TOKEN` (GitHub MCP), `BKIT_LINEAR_API_KEY` or `
|
|
65
|
+
| 3 | Set up direnv + `.bkit/.env` for `BKIT_GH_TOKEN` (GitHub MCP), `BKIT_LINEAR_API_KEY` or `BKIT_JIRA_API_KEY` — no registry token | [§ Local env setup](#local-env-setup) |
|
|
66
66
|
| 4 | Push to a feature branch and verify CI runs green | — |
|
|
67
67
|
|
|
68
68
|
No CI step, secret, `.npmrc` mapping or Vercel env is needed — CI reaches npmjs anonymously.
|
|
@@ -119,7 +119,7 @@ Install and upgrade create two **relative symlinks** into the installed package,
|
|
|
119
119
|
|
|
120
120
|
### Local env setup
|
|
121
121
|
|
|
122
|
-
Two flows — pick one. Both put `BKIT_GH_TOKEN` in shell for the GitHub MCP server; Linear repos also need `BKIT_LINEAR_API_KEY`, Jira repos `
|
|
122
|
+
Two flows — pick one. Both put `BKIT_GH_TOKEN` in shell for the GitHub MCP server; Linear repos also need `BKIT_LINEAR_API_KEY`, Jira repos `BKIT_JIRA_API_KEY` (`.bkit/trackers.md` § jira — setup and notes). Use `gh auth login` for CLI.
|
|
123
123
|
|
|
124
124
|
#### Flow A — Shell export (quickest, no extra deps)
|
|
125
125
|
|
|
@@ -127,7 +127,7 @@ Two flows — pick one. Both put `BKIT_GH_TOKEN` in shell for the GitHub MCP ser
|
|
|
127
127
|
# Add to ~/.zshrc (or ~/.bashrc)
|
|
128
128
|
export BKIT_GH_TOKEN=<PAT — fine-grained (one owner) or classic (multiple owners)> # GitHub MCP
|
|
129
129
|
export BKIT_LINEAR_API_KEY=<Linear personal API key> # Linear MCP + preflight
|
|
130
|
-
export
|
|
130
|
+
export BKIT_JIRA_API_KEY=<Atlassian MCP V2 scoped token> # Jira MCP
|
|
131
131
|
|
|
132
132
|
# Reload
|
|
133
133
|
source ~/.zshrc # or: source ~/.bashrc
|
|
@@ -151,7 +151,7 @@ echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc
|
|
|
151
151
|
# 3. One-time per consumer repo (after `bkit install`)
|
|
152
152
|
cp .bkit/templates/.envrc .envrc # unless you already have one
|
|
153
153
|
cp .bkit/.env.example .bkit/.env
|
|
154
|
-
# Edit .bkit/.env: set BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY or
|
|
154
|
+
# Edit .bkit/.env: set BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY or BKIT_JIRA_API_KEY
|
|
155
155
|
direnv allow # trust the .envrc
|
|
156
156
|
|
|
157
157
|
# 4. Verify
|
|
@@ -226,12 +226,12 @@ After writes, bkit re-runs credential and environment checks — some only accur
|
|
|
226
226
|
| --- | --- |
|
|
227
227
|
| `bkit-managed-duplicate` | A managed markdown file holds an older unmarked copy of its block outside `bkit:start`/`bkit:end`: the block's `# ` title plus 10+ of its long lines verbatim, fenced code ignored. Install never updates that copy. Names each file and title line; delete the copy. |
|
|
228
228
|
| `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset/empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
|
|
229
|
-
| `tracker-setup-none` / `-github` / `-linear` / `-jira` | Optional post-install decision — which issue tracker is wired (`bkit.
|
|
230
|
-
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.
|
|
231
|
-
| `github-project-
|
|
232
|
-
| `dep-updater-absent` | No Renovate or Dependabot config. Copy one example and own it. `bkit.
|
|
229
|
+
| `tracker-setup-none` / `-github` / `-linear` / `-jira` | Optional post-install decision — which issue tracker is wired (`bkit.tracker.default`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
230
|
+
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.tracker.github.project` empty, absent or not a board URL, and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.tracker.github.project: false`. |
|
|
231
|
+
| `github-project-token-scope` | A board is configured but `BKIT_GH_TOKEN` cannot reach it: a classic token lacks the `project` scope, or a fine-grained token's board query returns nothing. Board moves fall back to the MCP. Checked live via `gh`; skipped on cloud / CI. |
|
|
232
|
+
| `dep-updater-absent` | No Renovate or Dependabot config. Copy one example and own it. `bkit.dependencies.updater: "none"` silences this. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
233
233
|
| `dep-updater-both` | Both updater configs are present. Keep one. |
|
|
234
|
-
| `cloud-router-none` / `cloud-router` | Optional post-install decision — post-CI auto-routing (`bkit.
|
|
234
|
+
| `cloud-router-none` / `cloud-router` | Optional post-install decision — post-CI auto-routing (`bkit.cloud.agent`). `none` (undecided) nudges `bkit install --auto=<variant>`, except under the jira tracker (local runs only); `cloud-router` is informational once `bkit-cloud.yml` is present. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
235
235
|
| `actions-write-permissions-missing` | `bkit-cloud.yml` present but repo Actions permissions are read-only / PR creation disabled — `actions/checkout` + `gh pr create` 403. Repo-level check; org policy can override. |
|
|
236
236
|
| `opencode-setup` | opencode host installed (`--opencode=<provider>`) — names the provider key to set (e.g. `BKIT_OPENROUTER_API_KEY`; `BKIT_OPENCODE_API_KEY` for `opencode-zen` / `opencode-go`), confirms the pre-seeded base URL, and notes all four providers ship curated per-agent pins (re-pin via `.bkit/prompts.md` § Model Overrides). Verify with `bkit doctor` + `bkit status`. |
|
|
237
237
|
| `vale-package-not-synced` | vale on PATH but `.vale/styles/write-good/` absent |
|
|
@@ -243,7 +243,7 @@ After writes, bkit re-runs credential and environment checks — some only accur
|
|
|
243
243
|
|
|
244
244
|
Phase 1 and Phase 3 findings merged and deduplicated by `id` (Phase 3 wins on conflict — re-detection more accurate post-write). Zero findings → no banner.
|
|
245
245
|
|
|
246
|
-
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only) — same advisory set as `bkit install` minus writes. Changes no managed file (regenerates `.bkit/advisories.md` artifact) and **exits 1 when any managed-file write would occur** in installed module — Tier-2 JSON deep-containment or markered-block drift, whole-file byte-equal mismatch, **host agent/command mirror content drift** (would-write / orphan delete), or when any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carries a stale managed-version marker (`bkit-managed-stale`). Gate covers the **installed** module set ({core, claude, cursor, codex, antigravity} plus **opencode**, each detected by sentinel files: a host's `agents/` dir; antigravity any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host; `bkit status` uses the same detection). A missing `bkit:gate:*` name counts as a write. antigravity gated: `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and root `GEMINI.md`. opencode gated: `.opencode/opencode.json` (provider block + the recorded tracker's `mcp` entry + permission sandbox; another tracker's `mcp` entry the consumer edited, kept by a tracker switch, is not drift — `mcp-extra-server-linear--opencode-opencode-json` advises removing it) and the `bkit-gateguard.js` / `bkit-readguard.js` plugins drift fail `check` — render inputs fall back to installed provider (`package.json` `bkit.
|
|
246
|
+
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only) — same advisory set as `bkit install` minus writes. Changes no managed file (regenerates `.bkit/advisories.md` artifact) and **exits 1 when any managed-file write would occur** in installed module — Tier-2 JSON deep-containment or markered-block drift, whole-file byte-equal mismatch, **host agent/command mirror content drift** (would-write / orphan delete), or when any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carries a stale managed-version marker (`bkit-managed-stale`). Gate covers the **installed** module set ({core, claude, cursor, codex, antigravity} plus **opencode**, each detected by sentinel files: a host's `agents/` dir; antigravity any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host; `bkit status` uses the same detection). A missing `bkit:gate:*` name counts as a write. antigravity gated: `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and root `GEMINI.md`. opencode gated: `.opencode/opencode.json` (provider block + the recorded tracker's `mcp` entry + permission sandbox; another tracker's `mcp` entry the consumer edited, kept by a tracker switch, is not drift — `mcp-extra-server-linear--opencode-opencode-json` advises removing it) and the `bkit-gateguard.js` / `bkit-readguard.js` plugins drift fail `check` — render inputs fall back to installed provider (`package.json` `bkit.providers.opencode.default`, authoritative for `opencode-zen` / `opencode-go`; all installed providers tracked in `bkit.providers.opencode.installed: string[]`) and recorded tracker, so clean install across providers checks green (no false drift). Remaining **opt-in** module (cloud) is not drift-gated. A missing bkit-owned hook file also fails `check`, one line per file naming it and the `bkit install` flag that restores it: the hook files of every installed host (`.claude/hooks/*`, `.cursor/hooks/*`, `.codex/hooks/*`, `.agents/plugins/bkit/hooks/*`, `.opencode/plugin/bkit-gateguard.js`, `.opencode/plugin/bkit-readguard.js`) — the hook commands skip a missing file (`test -f … || true`), so without this the guard would be off with no signal. Updater configs are not bkit files, so `bkit check` does not report them. Phase 3 stays read-only through read-only detector paths, not by being skipped.
|
|
247
247
|
|
|
248
248
|
**`bkit upgrade`** (not `--dry-run`) ends with the same read-only pass as `bkit check`: prints the checklist and rewrites `.bkit/advisories.md` (`Mode: upgrade`). Drift and blockers it finds are reported only — upgrade's exit code is unchanged.
|
|
249
249
|
|
|
@@ -265,7 +265,7 @@ Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` line
|
|
|
265
265
|
```json
|
|
266
266
|
{
|
|
267
267
|
"bkit": {
|
|
268
|
-
"
|
|
268
|
+
"advisories": { "ignore": ["tagged-tests-no-ci-home"] }
|
|
269
269
|
}
|
|
270
270
|
}
|
|
271
271
|
```
|
|
@@ -280,12 +280,12 @@ Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` line
|
|
|
280
280
|
|
|
281
281
|
## Optional post-install decisions
|
|
282
282
|
|
|
283
|
-
Two capabilities **opt-in** — never wired by plain host/tooling install. Default install never enables them; post-install advisory banner nudges you to choose, once. Each recorded in `package.json` (`bkit.
|
|
283
|
+
Two capabilities **opt-in** — never wired by plain host/tooling install. Default install never enables them; post-install advisory banner nudges you to choose, once. Each recorded in `package.json` (`bkit.tracker.default`, `bkit.cloud.agent`) so the nudge knows whether you've decided or deliberately opted out.
|
|
284
284
|
|
|
285
285
|
<!-- prettier-ignore -->
|
|
286
286
|
| Decision | Default | Opt-in command | Advisory when unset |
|
|
287
287
|
| --- | --- | --- | --- |
|
|
288
|
-
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (`BKIT_GH_TOKEN`) `--tracker=linear` (`BKIT_LINEAR_API_KEY`) or `--tracker=jira` (`
|
|
288
|
+
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (`BKIT_GH_TOKEN`) `--tracker=linear` (`BKIT_LINEAR_API_KEY`) or `--tracker=jira` (`BKIT_JIRA_API_KEY` + `bkit.tracker.jira.site` / `bkit.tracker.jira.project`) | `tracker-setup-none` |
|
|
289
289
|
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude + opencode jobs, secret-gated) and the Cursor Dockerfile/environment.json | `cloud-router-none` |
|
|
290
290
|
|
|
291
291
|
**Dependency updater.** Copy one example and own it.
|
|
@@ -297,7 +297,7 @@ Two capabilities **opt-in** — never wired by plain host/tooling install. Defau
|
|
|
297
297
|
| Renovate self-hosted runner | `.bkit/templates/.github/workflows/bkit-renovate.yml` |
|
|
298
298
|
| Dependabot | `.bkit/templates/.github/dependabot.yml` |
|
|
299
299
|
|
|
300
|
-
Use one. `bkit.
|
|
300
|
+
Use one. `bkit.dependencies.updater: "none"` skips the install-time absence advisory. Setup: `docs/deployments.md` § Dependency updaters.
|
|
301
301
|
|
|
302
302
|
**Security scan.** Updater only offers fixes once a fixed release exists. To fail CI on known-vulnerable packages, risky config or committed secrets, copy `.bkit/templates/.github/workflows/bkit-trivy.yml` and own it. No advisory; `bkit tips` suggests it. Setup: `.bkit/templates.md` § Trivy.
|
|
303
303
|
|
|
@@ -313,10 +313,10 @@ Use one. `bkit.depUpdater: "none"` skips the install-time absence advisory. Setu
|
|
|
313
313
|
**How to decide:**
|
|
314
314
|
|
|
315
315
|
1. Run `bkit install --claude --cursor` (or whichever modules you want). Post-install banner lists `tracker-setup-none`, `dep-updater-absent`, `cloud-router-none` if undecided.
|
|
316
|
-
2. Pick tracker: `bkit install --tracker=github` (or `linear` / `jira`). Needs no host flag; re-renders every installed host. Persisted to `bkit.
|
|
316
|
+
2. Pick tracker: `bkit install --tracker=github` (or `linear` / `jira`). Needs no host flag; re-renders every installed host. Persisted to `bkit.tracker.default`; future installs preserve (switching free).
|
|
317
317
|
3. Copy one updater example (table above). Land Renovate config on the default branch before installing the App.
|
|
318
|
-
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. Persisted to `bkit.
|
|
319
|
-
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.
|
|
318
|
+
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. Persisted to `bkit.cloud.agent`; install prints secrets + permissions + dashboard checklist (`bkit-auto-setup`). Shipped `bkit-cloud.yml` carries claude job (`ANTHROPIC_API_KEY` repo secret or federation repo variables — `.bkit/cloud.md` § Claude — workload identity federation) and opencode job (`OPENCODE_PROVIDER_KEY`), each runtime-gated.
|
|
319
|
+
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.tracker.default` / `bkit.dependencies.updater` / `bkit.cloud.agent`). Advisory stays quiet. The `""` install seeds means undecided and keeps the nudge.
|
|
320
320
|
|
|
321
321
|
Tracker and cloud agents reverse by re-running install with the other flag. Updater files stay until you delete them.
|
|
322
322
|
|
|
@@ -340,8 +340,8 @@ bkit tips --all # every firing tip
|
|
|
340
340
|
| Detection | Local only — files, settings, environment; no network. A tip clears once its local half exists; dashboard steps live in the tip text. |
|
|
341
341
|
| Reuse | A tip for a gap an advisory already detects calls that advisory's detector — tip and advisory never disagree. |
|
|
342
342
|
| Artifact | `bkit install` / `check` / `upgrade` / `doctor` list every firing tip, with its id, in `.bkit/advisories.md` § Setup tips and the console banner: line, why, caution, ask-your-agent sentence, agent steps. |
|
|
343
|
-
| Star line | `Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!` (markdown link) closes bare `bkit tips`, after the tips and outside the cap; in a phase workflow it follows the tip, and the silence line follows it. Never under `--workflow=audit` / `utility` (those agents often run back to back), in `.bkit/advisories.md` or the console banner. |
|
|
344
|
-
| Silence | Root `package.json` `bkit.
|
|
343
|
+
| Star line | `Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!` (markdown link) closes bare `bkit tips`, after the tips and outside the cap; in a phase workflow it follows the tip with `Do you like bkit?` in bold, and the silence line follows it. Never under `--workflow=audit` / `utility` (those agents often run back to back), in `.bkit/advisories.md` or the console banner. |
|
|
344
|
+
| Silence | Root `package.json` `bkit.advisories.ignore`: a tip id (a workflow's `## bkit Tips` ends with `` **Want to silence these tips?** Ask your agent to "add `<id>` and `bkit-star` to `bkit.advisories.ignore` in package.json". ``, naming what it showed), or an advisory id the tip reuses, silences the tip and those advisories together; both show in the suppressed block. `bkit-star` (or the older `star`) silences the star line. |
|
|
345
345
|
| Exit | Always 0. Prints nothing when no tip fires and no star line shows. |
|
|
346
346
|
|
|
347
347
|
## Doctor
|
|
@@ -379,7 +379,7 @@ bkit uninstall --dry-run
|
|
|
379
379
|
|
|
380
380
|
# Uninstall specific modules (targeted — leaves core + the other modules intact)
|
|
381
381
|
bkit uninstall --claude # removes the claude host only
|
|
382
|
-
bkit uninstall --auto # clears the
|
|
382
|
+
bkit uninstall --auto # clears the bkit.cloud.agent key (cloud files are copy-and-own)
|
|
383
383
|
|
|
384
384
|
# Force-delete byte-equal-text files even if consumer modified them
|
|
385
385
|
bkit uninstall --force
|