@cbartens/bkit 5.5.1 → 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.
- package/.bkit/README.md +167 -154
- package/.bkit/core/.agents/context.md +95 -29
- package/.bkit/core/.agents/docs.md +18 -15
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
- package/.bkit/core/.agents/rules.md +112 -102
- package/.bkit/core/.agents/skills.md +63 -15
- package/.bkit/core/.bkit/README.md +167 -154
- package/.bkit/core/.bkit/authoring.md +747 -0
- package/.bkit/core/.bkit/cli.md +407 -0
- package/.bkit/core/.bkit/cloud.md +283 -195
- package/.bkit/core/.bkit/comparison.md +45 -43
- package/.bkit/core/.bkit/install.md +166 -95
- package/.bkit/core/.bkit/jsonl.md +339 -196
- package/.bkit/core/.bkit/pipeline.md +142 -145
- package/.bkit/core/.bkit/prompts.md +295 -264
- package/.bkit/core/.bkit/providers.md +460 -277
- package/.bkit/core/.bkit/router.md +69 -0
- package/.bkit/core/.bkit/templates.md +530 -256
- package/.bkit/core/.bkit/trackers.md +116 -65
- package/.bkit/core/.bkit/workflows.md +742 -618
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
- package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
- package/.bkit/core/AGENTS.md +6 -80
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
- package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
- package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
- package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
- package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
- package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
- package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
- package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
- package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
- package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
- package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
- package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
- package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
- package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
- package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
- package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
- package/.bkit/core/docs/templates/bkit-plan.md +158 -281
- package/.bkit/core/engine/checks/after/auth.ts +40 -37
- package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
- package/.bkit/core/engine/checks/after/github.ts +95 -17
- package/.bkit/core/engine/checks/after/index.ts +21 -8
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +125 -123
- package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
- package/.bkit/core/engine/checks/before/env.ts +3 -3
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +25 -1
- package/.bkit/core/engine/checks/before/repo.ts +208 -2
- package/.bkit/core/engine/checks/status-holes.ts +916 -123
- package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
- package/.bkit/core/engine/checks/tips/detect.ts +66 -0
- package/.bkit/core/engine/checks/tips/index.ts +52 -11
- package/.bkit/core/engine/cli.ts +251 -130
- package/.bkit/core/engine/commands/analysis.ts +282 -199
- package/.bkit/core/engine/commands/ci/ci.ts +363 -29
- package/.bkit/core/engine/commands/ci/pins.ts +172 -0
- package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
- 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 +86 -55
- package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
- package/.bkit/core/engine/commands/land.ts +139 -18
- package/.bkit/core/engine/commands/lib.ts +381 -22
- package/.bkit/core/engine/commands/registry.ts +10 -2
- package/.bkit/core/engine/commands/setup/setup.ts +8 -7
- package/.bkit/core/engine/commands/stats.ts +260 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
- package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
- package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
- package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
- package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
- package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
- package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
- package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
- package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
- package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
- package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
- package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
- package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
- package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
- package/.bkit/core/engine/commands/workflow/status.ts +329 -33
- package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
- package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
- package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
- package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
- package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
- package/.bkit/core/engine/install/cloud-env.ts +251 -121
- package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
- package/.bkit/core/engine/install/manifest.ts +67 -17
- package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
- package/.bkit/core/engine/install/modules/cloud.ts +24 -16
- package/.bkit/core/engine/install/modules/codex.ts +15 -2
- package/.bkit/core/engine/install/modules/core.ts +1196 -45
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +18 -6
- package/.bkit/core/engine/install/template-notes.ts +130 -0
- package/.bkit/core/engine/install/version-file.ts +9 -4
- package/.bkit/core/engine/install/write.ts +5 -0
- package/.bkit/core/engine/ledgers/compact.ts +124 -0
- package/.bkit/core/engine/ledgers/journal.ts +291 -0
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +249 -21
- package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
- package/.bkit/core/engine/render/hosts.ts +118 -14
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/dep-updater.ts +60 -0
- package/.bkit/core/engine/shared/egress.ts +8 -1
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/package-manager.ts +9 -0
- package/.bkit/core/engine/shared/settings.ts +243 -31
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/shared/timeouts.ts +2 -0
- package/.bkit/core/engine/tools/cli-doc.ts +111 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
- package/.bkit/core/engine/tools/instructions.ts +1802 -0
- package/.bkit/core/hooks/antigravity-hook.js +25 -10
- package/.bkit/core/hooks/gateguard-engine.js +54 -29
- package/.bkit/core/hooks/guardrails-shell.js +4 -5
- package/.bkit/core/hooks/guardrails-tiers.js +10 -4
- package/.bkit/core/hooks/preflight-linear.sh +9 -9
- package/.bkit/core/hooks/preflight-rules.sh +8 -0
- package/.bkit/core/hooks/readguard-engine.js +29 -10
- package/.bkit/core/hooks/session-rules-advisory.js +61 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
- package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
- package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
- package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
- package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
- package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
- package/.bkit/core/prompts/bkit-design-generate.md +80 -46
- package/.bkit/core/prompts/bkit-design-organise.md +83 -32
- package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
- package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
- package/.bkit/core/prompts/bkit-design-spike.md +64 -40
- package/.bkit/core/prompts/bkit-design-update.md +53 -28
- package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
- package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
- package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
- package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
- package/.bkit/core/prompts/bkit-plan-update.md +86 -31
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
- package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
- package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
- package/.bkit/core/workflows/bkit-auto.md +89 -58
- package/.bkit/core/workflows/bkit-build.md +967 -517
- package/.bkit/core/workflows/bkit-debug.md +555 -387
- package/.bkit/core/workflows/bkit-design.md +319 -283
- package/.bkit/core/workflows/bkit-plan.md +319 -342
- package/.bkit/core/workflows/bkit-ship.md +525 -328
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/bkit-cloud.md +12 -10
- package/.bkit/shared/.claude/settings.json +14 -0
- package/.bkit/shared/.codex/bkit-cloud.md +98 -0
- package/.bkit/shared/.codex/hooks.json +20 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
- 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 +12 -1
- package/.bkit/shared/CLAUDE.md +6 -2
- package/.bkit/shared/GEMINI.md +5 -2
- package/.bkit/shared/docs/architecture.md +4 -7
- package/.bkit/shared/docs/data-schema.md +4 -7
- package/.bkit/shared/docs/deployments.md +241 -168
- package/.bkit/shared/docs/design.md +11 -12
- package/.bkit/shared/docs/noise.md +8 -7
- package/.bkit/shared/docs/observability.md +5 -8
- package/.bkit/shared/docs/security.md +35 -17
- package/.bkit/shared/docs/setup.md +29 -18
- package/.bkit/shared/docs/technology.md +3 -6
- package/.bkit/shared/docs/testing.md +289 -174
- package/.bkit/shared/gitignore +6 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
- package/.bkit/templates/.cursor/Dockerfile +12 -8
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
- package/.bkit/templates/.github/renovate.json5 +34 -6
- package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
- package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
- package/.bkit/templates/.husky/pre-commit +2 -2
- package/.bkit/templates/.husky/pre-push +96 -36
- package/.bkit/templates/.prettierignore +6 -0
- package/.bkit/templates/.vale.ini +27 -27
- package/.bkit/templates/context/bkit-cloudrun.md +23 -15
- package/.bkit/templates/context/bkit-expo.md +70 -52
- package/.bkit/templates/context/bkit-github.md +93 -56
- package/.bkit/templates/context/bkit-inngest.md +21 -15
- package/.bkit/templates/context/bkit-maestro.md +22 -16
- package/.bkit/templates/context/bkit-playwright.md +23 -17
- package/.bkit/templates/context/bkit-resend.md +12 -10
- package/.bkit/templates/context/bkit-sentry.md +30 -20
- package/.bkit/templates/context/bkit-serena.md +8 -7
- package/.bkit/templates/context/bkit-stripe.md +14 -13
- package/.bkit/templates/context/bkit-supabase.md +16 -13
- package/.bkit/templates/context/bkit-tavily.md +14 -11
- package/.bkit/templates/context/bkit-vercel.md +27 -18
- package/.bkit/templates/docs/capabilities.md +15 -14
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
- package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
- package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
- package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
- package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
- package/.bkit/templates/slop-scan.config.json +9 -2
- package/CHANGELOG.md +231 -0
- package/README.md +278 -89
- package/dist/checks/after/auth.js +36 -33
- package/dist/checks/after/ci-yml.js +91 -30
- package/dist/checks/after/github.js +91 -17
- package/dist/checks/after/index.js +22 -11
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +111 -114
- package/dist/checks/before/context-fetch.js +218 -33
- package/dist/checks/before/env.js +3 -3
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +20 -3
- package/dist/checks/before/repo.js +197 -2
- package/dist/checks/status-holes.js +739 -114
- package/dist/checks/tips/catalogue.js +70 -19
- package/dist/checks/tips/detect.js +62 -0
- package/dist/checks/tips/index.js +51 -9
- package/dist/cli.js +234 -124
- package/dist/commands/analysis.js +174 -141
- package/dist/commands/ci/ci.js +302 -25
- package/dist/commands/ci/pins.js +142 -0
- package/dist/commands/ci/push-gate.js +194 -0
- 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 +82 -55
- package/dist/commands/install/upgrade.js +21 -11
- package/dist/commands/land.js +137 -17
- package/dist/commands/lib.js +295 -21
- package/dist/commands/registry.js +10 -2
- package/dist/commands/setup/setup.js +8 -7
- package/dist/commands/stats.js +175 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +1873 -152
- package/dist/commands/workflow/challenge.js +609 -0
- package/dist/commands/workflow/completeness.js +97 -0
- package/dist/commands/workflow/context.js +1045 -46
- package/dist/commands/workflow/counters.js +385 -86
- package/dist/commands/workflow/decisions.js +484 -0
- package/dist/commands/workflow/disk.js +214 -56
- package/dist/commands/workflow/fids.js +706 -33
- package/dist/commands/workflow/issues.js +349 -59
- package/dist/commands/workflow/ledgers.js +1123 -37
- package/dist/commands/workflow/locks.js +26 -2
- package/dist/commands/workflow/plan-blocks.js +501 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/plans.js +205 -0
- package/dist/commands/workflow/prs.js +154 -35
- package/dist/commands/workflow/repo.js +58 -8
- package/dist/commands/workflow/roadmap.js +58 -23
- package/dist/commands/workflow/run-facts.js +421 -0
- package/dist/commands/workflow/runs.js +670 -72
- package/dist/commands/workflow/runtime.js +15 -1
- package/dist/commands/workflow/skills.js +1 -0
- package/dist/commands/workflow/status.js +282 -34
- package/dist/commands/workflow/step-table.js +308 -0
- package/dist/commands/workflow/steps.js +703 -96
- package/dist/commands/workflow/summary-findings.js +117 -0
- package/dist/commands/workflow/summary.js +388 -0
- package/dist/commands/workflow/tasks.js +378 -0
- package/dist/commands/workflow/test-blocks.js +231 -0
- package/dist/commands/workflow/tests-changed.js +172 -0
- package/dist/commands/workflow/tests.js +1695 -305
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +1014 -222
- package/dist/commands/workflow/worktrees.js +432 -26
- package/dist/install/cloud-env.js +233 -99
- package/dist/install/context-ci-workflow.js +85 -0
- package/dist/install/manifest.js +64 -17
- package/dist/install/modules/antigravity.js +3 -2
- package/dist/install/modules/cloud.js +25 -16
- package/dist/install/modules/codex.js +12 -2
- package/dist/install/modules/core.js +1090 -48
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +13 -7
- package/dist/install/template-notes.js +116 -0
- package/dist/install/version-file.js +9 -4
- package/dist/ledgers/compact.js +87 -0
- package/dist/ledgers/journal.js +233 -0
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +176 -13
- package/dist/ledgers/telemetry.js +1010 -125
- package/dist/render/hosts.js +104 -14
- package/dist/render/models.js +12 -0
- package/dist/shared/bkit-latest.js +26 -4
- package/dist/shared/branches.js +3 -1
- package/dist/shared/dep-updater.js +49 -0
- package/dist/shared/egress.js +8 -1
- package/dist/shared/json.js +20 -7
- package/dist/shared/package-manager.js +6 -0
- package/dist/shared/settings.js +181 -24
- package/dist/shared/text.js +333 -0
- package/dist/shared/timeouts.js +2 -0
- package/dist/tools/cli-doc.js +97 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +720 -0
- package/dist/tools/instructions.js +1623 -0
- package/package.json +156 -51
- package/.bkit/core/.bkit/lite.md +0 -73
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
- 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-plan-execute.md +0 -76
- 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/bkit-local-stack-lock.sh +0 -194
- package/dist/commands/harvest.js +0 -353
- package/dist/commands/workflow/workstreams.js +0 -143
- package/dist/tools/wording.js +0 -680
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
- /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
- /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
|
@@ -2,29 +2,45 @@
|
|
|
2
2
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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.
|
|
14
|
+
|
|
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
|
-
|
|
21
|
+
Here is a typical cycle for `ISSUE-123` "Add feature X":
|
|
22
|
+
|
|
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.
|
|
38
|
+
|
|
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.
|
|
14
40
|
|
|
15
|
-
|
|
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.worktree.copy` path from the main checkout (a `package.json` setting; default `.env`, `.env.local`; exact paths, folders copy recursively; a missing one is logged, never fatal), runs `direnv allow` when the worktree's `.envrc` matches the main checkout's, then `pnpm install --frozen-lockfile` unless `bkit.worktree.install: false`.
|
|
19
|
-
5. **Phase steps** — dispatches subagents (`@bkit-plan-generate`, then `@bkit-plan-review-1` ‖ `-2` ‖ `-3` parallel triplet, etc.). Each writes `docs/plans/{YYYYMM}/logs/{FID}/` (`{YYYYMM}` = canonical month bucket at design start), appends fenced section to tracker comment.
|
|
20
|
-
6. **Phase summary** — verdict (`PASS` / `CONCERNS` / `FAIL`); commit `chore(issue-123-…): summary bkit [skip ci]` (design/plan) or `chore(issue-123-…): summary` (build/debug/ship) → push.
|
|
21
|
-
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` ‖ `@bkit-ship-summary` (parallel) on `dev`, prune worktree, issue `In Review` (`bkit:merged`; bkit never auto-closes). Plans stay at `docs/plans/{YYYYMM}/` — no archive move.
|
|
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.
|
|
26
42
|
|
|
27
|
-
|
|
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.
|
|
28
44
|
|
|
29
45
|
---
|
|
30
46
|
|
|
@@ -33,42 +49,42 @@ Throughout: workflows hold `.lock`, write `status.jsonl` (resume SoT), own track
|
|
|
33
49
|
<!-- prettier-ignore -->
|
|
34
50
|
| Phase | Command | Steps | Output | Hard stop? |
|
|
35
51
|
| --- | --- | --- | --- | --- |
|
|
36
|
-
| Design | `/bkit-design` |
|
|
37
|
-
| Plan | `/bkit-plan` |
|
|
38
|
-
| Build | `/bkit-build` |
|
|
52
|
+
| Design | `/bkit-design` | 12 | `docs/plans/{YYYYMM}/{FID}-design.md` | Yes — review before plan |
|
|
53
|
+
| Plan | `/bkit-plan` | 8 | `docs/plans/{YYYYMM}/{FID}-plan.md` | Yes — review before build |
|
|
54
|
+
| Build | `/bkit-build` | 15 | PR to `dev` | No — CI continues |
|
|
39
55
|
| Debug | `/bkit-debug` | 11 | Remediation commit on feature branch | No |
|
|
40
|
-
| Ship | `/bkit-ship` |
|
|
56
|
+
| Ship | `/bkit-ship` | 14 | Squash-merged PR, issue `In Review` + `bkit:merged` (plans stay canonical at `docs/plans/{YYYYMM}/`) | Yes |
|
|
41
57
|
|
|
42
|
-
**Where an issue starts.**
|
|
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.
|
|
43
59
|
|
|
44
60
|
<!-- prettier-ignore -->
|
|
45
61
|
| Issue | Start with |
|
|
46
62
|
| --- | --- |
|
|
47
63
|
| Idea — how it should work still open | `/bkit-design` |
|
|
48
|
-
| Change — what to build and "done" known | `/bkit-plan
|
|
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. |
|
|
49
65
|
| Bug — a test or CI run already fails | `/bkit-debug`, on the branch the fix lands on |
|
|
50
66
|
| Bug — nothing fails yet | `/bkit-debug [repro]` (writes a failing test first, then fixes) |
|
|
51
67
|
|
|
52
|
-
|
|
68
|
+
Per-step detail, verdict routing, retry / timeout constants, label flips, the status.jsonl shape and the comment lifecycle are in `.bkit/workflows.md`.
|
|
53
69
|
|
|
54
|
-
|
|
70
|
+
Per-subagent scope, effort tier, tool surface, `maxTurns` and model assignment are in `.bkit/prompts.md`.
|
|
55
71
|
|
|
56
72
|
---
|
|
57
73
|
|
|
58
74
|
## Audits
|
|
59
75
|
|
|
60
|
-
|
|
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.
|
|
61
77
|
|
|
62
78
|
<!-- prettier-ignore -->
|
|
63
79
|
| Item | Contract |
|
|
64
80
|
| --- | --- |
|
|
65
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. |
|
|
66
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`. |
|
|
67
|
-
| Issue comment |
|
|
68
|
-
| Audit parent |
|
|
69
|
-
| Plan input | `/bkit-plan` takes a design doc, one or more reports, or both. The issue names a report with an `**Audit reports:**` line
|
|
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. |
|
|
70
86
|
|
|
71
|
-
Each template's `Purpose` is its scope.
|
|
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).
|
|
72
88
|
|
|
73
89
|
---
|
|
74
90
|
|
|
@@ -80,27 +96,27 @@ Each template's `Purpose` is its scope. Main ones: security, privacy, accessibil
|
|
|
80
96
|
| Tool | Version | Used for |
|
|
81
97
|
| --- | --- | --- |
|
|
82
98
|
| Node | >= 24 (`engines.node`) | Runs the bkit CLI. |
|
|
83
|
-
| `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.
|
|
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). |
|
|
84
100
|
| `gh` | latest, authenticated | PR create / view / merge in `/bkit-build`, `/bkit-debug`, `/bkit-ship` |
|
|
85
101
|
| `git` >= 2.5 | — | Worktree operations |
|
|
86
102
|
| `jq` | latest | Reads the JSON that `bkit` commands print, in workflow Bash |
|
|
87
|
-
| Claude
|
|
103
|
+
| Claude CLI | latest | Local-IDE workflow execution |
|
|
88
104
|
| Cursor (optional) | 2.4+ | Cloud Agent execution; honours `tools:` frontmatter allowlist |
|
|
89
105
|
|
|
90
106
|
### Shell alias
|
|
91
107
|
|
|
92
|
-
bkit
|
|
108
|
+
bkit is a devDependency. Add this alias once to run `bkit <verb>`:
|
|
93
109
|
|
|
94
110
|
```bash
|
|
95
111
|
# Add to ~/.zshrc (or ~/.bashrc), then: source ~/.zshrc
|
|
96
112
|
alias bkit='pnpm bkit'
|
|
97
113
|
```
|
|
98
114
|
|
|
99
|
-
`bkit doctor` emits `bkit-not-on-path`
|
|
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.
|
|
100
116
|
|
|
101
117
|
### Environment variables
|
|
102
118
|
|
|
103
|
-
Add to shell, Cursor Cloud Agent dashboard, `apps/web/.env.example` for contributors.
|
|
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>`:
|
|
104
120
|
|
|
105
121
|
**GitHub tracker (default — `bkit install --tracker=github`):**
|
|
106
122
|
|
|
@@ -132,7 +148,7 @@ BKIT_GH_TOKEN=""
|
|
|
132
148
|
# ==========================================
|
|
133
149
|
# BKIT: JIRA GITHUB INTEGRATION
|
|
134
150
|
# ==========================================
|
|
135
|
-
|
|
151
|
+
BKIT_JIRA_API_KEY=""
|
|
136
152
|
BKIT_GH_TOKEN=""
|
|
137
153
|
```
|
|
138
154
|
|
|
@@ -140,33 +156,33 @@ BKIT_GH_TOKEN=""
|
|
|
140
156
|
| Variable | Tracker | Where read | Purpose |
|
|
141
157
|
| --- | --- | --- | --- |
|
|
142
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`). |
|
|
143
|
-
| `GH_TOKEN` | all | `gh` CLI inside
|
|
144
|
-
| `GITHUB_ISSUE_ID` | github | Injected from PR body `<!-- bkit:issue=#NNN -->` | Linked GitHub issue. Injected automatically
|
|
145
|
-
| `BKIT_ANTHROPIC_API_KEY` | all | Claude
|
|
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). |
|
|
146
162
|
| `BKIT_CURSOR_API_KEY` | all | Cursor Cloud Agent dashboard / programmatic invocation | Required for non-interactive Cursor sessions. |
|
|
147
|
-
| `BKIT_LINEAR_API_KEY` | linear | Preflight hooks (`.{claude,cursor}/hooks/bkit-preflight.sh`); workflow Linear MCP via OAuth fallback |
|
|
148
|
-
| `
|
|
149
|
-
| `LINEAR_WEBHOOK_SECRET` | linear | Linear → Cursor integration backend | Verifies webhook signatures on `@cursor` mentions. Set in Linear
|
|
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. |
|
|
150
166
|
|
|
151
|
-
`GITHUB_ISSUE_ID` (GitHub) and `LINEAR_ISSUE_ID` (Linear)
|
|
167
|
+
The workflow context sets `GITHUB_ISSUE_ID` (GitHub) and `LINEAR_ISSUE_ID` (Linear) automatically. Do not set them manually.
|
|
152
168
|
|
|
153
169
|
### Tracker workspace setup
|
|
154
170
|
|
|
155
|
-
|
|
171
|
+
bkit uses one custom label (`Auto`), plus families of integration labels. The setup depends on the configured tracker.
|
|
156
172
|
|
|
157
173
|
#### Bkit custom label (`Auto`)
|
|
158
174
|
|
|
159
|
-
- **`Auto`** — issues approved for agent work.
|
|
160
|
-
- **GitHub:** issue label `bkit:auto`. `bkit install --tracker=github` seeds
|
|
161
|
-
- **Linear:** Linear label `Auto`. Add
|
|
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.
|
|
162
178
|
|
|
163
179
|
#### Phase labels (GitHub tracker)
|
|
164
180
|
|
|
165
|
-
`bkit.
|
|
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.
|
|
166
182
|
|
|
167
|
-
#### Linear
|
|
183
|
+
#### Linear + Cursor integration labels (Linear tracker only)
|
|
168
184
|
|
|
169
|
-
Three **parent labels** (`branch`, `model`, `repo`)
|
|
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.
|
|
170
186
|
|
|
171
187
|
<!-- prettier-ignore -->
|
|
172
188
|
| Parent | Example sub-labels in this workspace | What it controls |
|
|
@@ -175,59 +191,68 @@ Three **parent labels** (`branch`, `model`, `repo`) — sub-labels set Cursor Cl
|
|
|
175
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 |
|
|
176
192
|
| `repo` | `<owner>/<consumer-repo>` | repo the agent operates in |
|
|
177
193
|
|
|
178
|
-
Per-agent model assignments
|
|
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.
|
|
179
195
|
|
|
180
|
-
|
|
196
|
+
The full Linear + Cursor setup is at <https://linear.app/docs/cursor>.
|
|
181
197
|
|
|
182
198
|
---
|
|
183
199
|
|
|
184
200
|
## Distribution & install
|
|
185
201
|
|
|
186
|
-
`.agents/`
|
|
202
|
+
`.agents/` is canonical. `bkit install` regenerates the host outputs (`.claude/**`, `.cursor/**`) and rewrites the bkit-managed blocks across the consumer repo.
|
|
187
203
|
|
|
188
|
-
First-time install and
|
|
204
|
+
First-time install, upgrade and uninstall are in `.bkit/install.md`. Ongoing operations follow below.
|
|
189
205
|
|
|
190
|
-
### Upgrade
|
|
206
|
+
### Upgrade
|
|
191
207
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
````text
|
|
195
|
-
Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
|
|
196
|
-
1. Bump and resync in one step (no token — npmjs is public). If `bkit` is not on PATH, use `pnpm bkit`:
|
|
197
|
-
```bash
|
|
198
|
-
bkit upgrade --latest
|
|
199
|
-
```
|
|
200
|
-
Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
|
|
201
|
-
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.
|
|
202
|
-
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.
|
|
203
|
-
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).
|
|
204
|
-
````
|
|
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.
|
|
205
209
|
|
|
206
210
|
### Ongoing CLI
|
|
207
211
|
|
|
208
|
-
|
|
209
|
-
bkit upgrade # re-render at CURRENT installed version (offline)
|
|
210
|
-
bkit upgrade --latest # bump @cbartens/bkit + resync in one step (or --to=<version>)
|
|
211
|
-
bkit check # drift gate — exits non-zero on drift
|
|
212
|
-
bkit doctor # advisories only; exits 0; no managed-file writes
|
|
213
|
-
bkit tips [--all] # what is not set up yet, most useful first; exits 0
|
|
214
|
-
bkit install --claude --cursor # (re)seed hosts; name ≥1 module
|
|
215
|
-
```
|
|
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`.
|
|
216
213
|
|
|
217
|
-
**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
|
|
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).
|
|
218
215
|
|
|
219
|
-
>
|
|
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.
|
|
220
217
|
|
|
221
|
-
###
|
|
218
|
+
### Share friction with bkit
|
|
222
219
|
|
|
223
|
-
bkit
|
|
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.
|
|
224
221
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
|
|
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
|
+
````
|
|
231
256
|
|
|
232
257
|
## File ownership
|
|
233
258
|
|
|
@@ -236,23 +261,24 @@ bkit owns some files outright, owns one part of others, and ships the rest as te
|
|
|
236
261
|
<!-- prettier-ignore -->
|
|
237
262
|
| Kind | Semantics | Files |
|
|
238
263
|
| --- | --- | --- |
|
|
239
|
-
| **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. | `.
|
|
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` |
|
|
240
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` |
|
|
241
|
-
| **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` |
|
|
242
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` |
|
|
243
|
-
| **
|
|
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. |
|
|
244
270
|
|
|
245
|
-
**Marker syntax** format
|
|
271
|
+
**Marker syntax** depends on the file format:
|
|
246
272
|
|
|
247
273
|
- Markdown: `<!-- bkit:start -->` / `<!-- bkit:end -->`
|
|
248
274
|
- Shell / `.gitignore` / `.gitattributes`: `# <!-- bkit:start -->` / `# <!-- bkit:end -->`
|
|
249
|
-
- JS / TS ES modules: `// bkit:start` / `// bkit:end
|
|
275
|
+
- JS / TS ES modules: `// bkit:start` / `// bkit:end`, because HTML comments are a syntax error in an ES module.
|
|
250
276
|
|
|
251
|
-
|
|
277
|
+
Block updates keep the comment prefixes (`# `, `// `) before the markers.
|
|
252
278
|
|
|
253
|
-
**Managed-version marker.** Every non-JSON file bkit writes carries `bkit:managed vX.Y.Z`
|
|
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.
|
|
254
280
|
|
|
255
|
-
**Hook scripts.** Install generates each host's `bkit-preflight.sh`, `gateguard`, `readguard` and `
|
|
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.
|
|
256
282
|
|
|
257
283
|
### What install writes
|
|
258
284
|
|
|
@@ -261,7 +287,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
|
261
287
|
| --- | --- | --- | --- |
|
|
262
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`. |
|
|
263
289
|
| `.bkit/version` | core | package.json version | Written last (partial installs detectable) |
|
|
264
|
-
| `.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. |
|
|
265
291
|
| `.gitignore` | core | `.bkit/shared/gitignore` | Tier 2 html-comment |
|
|
266
292
|
| `AGENTS.md` | core | `.bkit/core/AGENTS.md` | Tier 2 html-comment |
|
|
267
293
|
| `CLAUDE.md` | claude | `.bkit/shared/CLAUDE.md` | Tier 2 html-comment |
|
|
@@ -270,7 +296,7 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
|
270
296
|
| `.gitattributes` | core | `.bkit/shared/.gitattributes` | Tier 2 html-comment (`merge=union` for the append-only ledgers) |
|
|
271
297
|
| `.bkit/templates/**` | — | the whole `.bkit/templates/` root | Raw copies, refreshed on every install and upgrade; never hashed. Upgrade prints the changed paths. |
|
|
272
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. |
|
|
273
|
-
| `.bkit/{cloud,comparison,install,jsonl,LICENSE,
|
|
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. |
|
|
274
300
|
| `.claude/commands/bkit-*.md` | claude | `.bkit/core/workflows/` (byte-identical) | Host pass — always overwrite |
|
|
275
301
|
| `.claude/agents/bkit-*.md` | claude | `.bkit/core/prompts/` (byte-identical) | Host pass — always overwrite |
|
|
276
302
|
| `.claude/settings.json` | claude | `.bkit/shared/.claude/settings.json` | Tier 2 JSON deep-containment. Permission allow/deny/ask + SessionStart / PreToolUse hook wiring. |
|
|
@@ -281,56 +307,43 @@ Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
|
281
307
|
| `.bkit/.env.example` | claude | `.bkit/shared/.bkit/.env.example` | Tier 1 (fully managed). Real values go in `.bkit/.env`. |
|
|
282
308
|
| `.cursor/commands/bkit-*.md` | cursor | `.bkit/core/workflows/` (T1+T2 transforms) | Host pass — always overwrite |
|
|
283
309
|
| `.cursor/agents/bkit-*.md` | cursor | `.bkit/core/prompts/` (T3 transforms) | Host pass — always overwrite |
|
|
284
|
-
| `package.json#scripts.bkit:gate:format` / `bkit:gate:min` / `bkit:gate:static` / `bkit:gate:static-unit` / `bkit:gate:install-static-unit-build` | core | hardcoded defaults | Seeded (add-if-missing; install and upgrade). What hooks, workflows and prompts run; the name states which tiers. The tool scripts the defaults chain (`typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta`) and their devDeps are templates: `.bkit/templates.md`. |
|
|
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`. |
|
|
285
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. |
|
|
286
|
-
|
|
|
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. |
|
|
313
|
+
| `.cursor/hooks.json` | cursor | `.bkit/shared/.cursor/hooks.json` | Tier 2 JSON deep-containment |
|
|
287
314
|
| `.cursor/mcp.json` | cursor | `.bkit/shared/.cursor/mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only |
|
|
288
315
|
| `.cursor/rules/bkit-rules.mdc` | cursor | `.bkit/shared/.cursor/rules/bkit-rules.mdc` | Tier 2 html-comment |
|
|
289
316
|
| `.cursor/hooks/bkit-preflight.sh` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 html-comment (`# ` prefix) |
|
|
290
|
-
| `.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. |
|
|
291
318
|
| `.cursor/hooks/bkit-gateguard.cjs` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 slash-comment |
|
|
292
319
|
| `.cursor/hooks/bkit-readguard.cjs` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 slash-comment. Repeat-read advisory. |
|
|
293
320
|
| `.cursor/cli.json` | cursor | derived from `.agents/context.md` mcp-servers | Tier 1 (canonical-overwrite). Cursor CLI / cloud-agent `Mcp(<server>:*)` allows. |
|
|
294
|
-
| `.opencode/opencode.json` |
|
|
295
|
-
| `.opencode/commands/bkit-*.md` |
|
|
296
|
-
| `.opencode/agents/bkit-*.md` |
|
|
297
|
-
| `.opencode/plugin/bkit-gateguard.js` |
|
|
298
|
-
| `.opencode/plugin/bkit-readguard.js` |
|
|
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. |
|
|
299
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). |
|
|
300
327
|
|
|
301
328
|
The cloud workflow and the Cursor Background Agent files are templates the `--auto` setup advisory points at.
|
|
302
329
|
|
|
303
330
|
### Optional post-install decisions (tracker + cloud agents)
|
|
304
331
|
|
|
305
|
-
Two capabilities
|
|
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`.
|
|
306
333
|
|
|
307
|
-
|
|
334
|
+
### Updater PRs against your workflows
|
|
308
335
|
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
**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.
|
|
312
|
-
|
|
313
|
-
**All templates.** Copy and own, never installed. Catalog and install steps: `.bkit/templates.md`.
|
|
314
|
-
|
|
315
|
-
### dogfood rule — updater PRs against workflows (only if you opt in)
|
|
316
|
-
|
|
317
|
-
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:
|
|
318
|
-
|
|
319
|
-
1. Before merge, edit matching `.bkit/templates/.github/workflows/*.yml` with same SHA bump (one `Edit` per file).
|
|
320
|
-
2. Run `pnpm test` (`.bkit/core/engine/audits/templates/template-action-pins.test.ts` fails when a template pin drifts from the repo's).
|
|
321
|
-
3. Push template-side change to updater PR branch (or follow-up commit on `dev` if branch read-only).
|
|
322
|
-
|
|
323
|
-
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.
|
|
324
337
|
|
|
325
338
|
---
|
|
326
339
|
|
|
327
340
|
## Triggering workflows
|
|
328
341
|
|
|
329
|
-
|
|
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.
|
|
330
343
|
|
|
331
344
|
### From a tracker comment (cloud — Cursor Cloud Agent)
|
|
332
345
|
|
|
333
|
-
**Linear tracker:** `@cursor` in Linear comment with slash command
|
|
346
|
+
**Linear tracker:** write `@cursor` in a Linear comment, with the slash command and the issue ID:
|
|
334
347
|
|
|
335
348
|
```
|
|
336
349
|
@cursor /bkit-plan ISSUE-123
|
|
@@ -338,29 +351,34 @@ Three paths: Linear comment (cloud), Claude Code (interactive local), Cursor (in
|
|
|
338
351
|
@cursor /bkit-ship ISSUE-123
|
|
339
352
|
```
|
|
340
353
|
|
|
341
|
-
`@cursor`
|
|
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.
|
|
342
355
|
|
|
343
|
-
**GitHub tracker:** PR
|
|
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.
|
|
344
357
|
|
|
345
|
-
**Requirements (Linear):** `Auto` label
|
|
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.
|
|
346
359
|
|
|
347
|
-
**Requirements (GitHub):** `BKIT_GH_TOKEN`, `BKIT_CURSOR_API_KEY
|
|
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.
|
|
348
361
|
|
|
349
|
-
### From Claude
|
|
362
|
+
### From Claude (interactive — local)
|
|
350
363
|
|
|
351
|
-
|
|
364
|
+
Run the slash commands at the repo root:
|
|
352
365
|
|
|
353
366
|
```
|
|
354
367
|
/bkit-design ISSUE-123 # produce a design doc
|
|
355
368
|
/bkit-plan ISSUE-123 # produce an implementation plan
|
|
356
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
|
|
357
371
|
/bkit-debug ISSUE-123 # diagnose and remediate CI failures
|
|
358
|
-
/bkit-ship ISSUE-123 # merge the PR for the current branch,
|
|
372
|
+
/bkit-ship ISSUE-123 # merge the PR for the current branch, set the issue In Review
|
|
359
373
|
```
|
|
360
374
|
|
|
361
|
-
Claude reads issue, comments
|
|
375
|
+
Claude reads the issue, its comments and the plan files through the tracker MCP.
|
|
376
|
+
|
|
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.
|
|
362
378
|
|
|
363
|
-
**
|
|
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.
|
|
364
382
|
|
|
365
383
|
### From Cursor (interactive — local)
|
|
366
384
|
|
|
@@ -370,25 +388,17 @@ Cursor 2.4+ honours `.cursor/commands/bkit-*.md` and `.cursor/agents/bkit-*.md`:
|
|
|
370
388
|
/bkit-plan ISSUE-123
|
|
371
389
|
```
|
|
372
390
|
|
|
373
|
-
|
|
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.
|
|
374
392
|
|
|
375
|
-
**Requirements:** `BKIT_GH_TOKEN` (GitHub, default) or `BKIT_LINEAR_API_KEY` (Linear) or `
|
|
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.
|
|
376
394
|
|
|
377
395
|
---
|
|
378
396
|
|
|
379
397
|
## Adding or updating skills
|
|
380
398
|
|
|
381
|
-
>
|
|
382
|
-
|
|
383
|
-
Skills = third-party instruction sets loaded at invocation.
|
|
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.
|
|
384
400
|
|
|
385
|
-
|
|
386
|
-
npx skills find [query] # search the registry (check publisher / installs / stars)
|
|
387
|
-
npx skills add <owner/repo>@<skill> -y # install one named skill, project-locally into .agents/skills/
|
|
388
|
-
npx skills update # update all installed
|
|
389
|
-
```
|
|
390
|
-
|
|
391
|
-
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.
|
|
392
402
|
|
|
393
403
|
---
|
|
394
404
|
|
|
@@ -400,34 +410,37 @@ Installed list: `.agents/skills.md`. Skills in `.agents/skills/` not listed →
|
|
|
400
410
|
| `.agents/rules.md` | Universal agent rules — read first by every workflow |
|
|
401
411
|
| `.bkit/workflows.md` | Workflow pipeline reference (steps, verdicts, contracts) |
|
|
402
412
|
| `.bkit/prompts.md` | Per-subagent description, effort tier, model, `maxTurns`. Audit template catalogue (§ Audit (Ad-hoc)). |
|
|
413
|
+
| `.bkit/authoring.md` | Authoring rules for every agent-read markdown file — docs, prompts, workflows; punctuation and capitals (§ Notation) |
|
|
403
414
|
| `.agents/docs.md` | Document index and phase-matrix (what to read per phase) |
|
|
404
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 |
|
|
405
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) |
|
|
406
|
-
| `.bkit/friction.jsonl` | Friction ledger — orchestrator-observed recovery moments. Created on first append by a phase workflow, not by install; drained by
|
|
407
|
-
| `
|
|
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`. |
|
|
422
|
+
| `.bkit/stats.jsonl` | Stats ledger — `outcome` / `compliance` / `counter` rows appended at every workflow close. Append-only. Row shape: `.bkit/jsonl.md`. |
|
|
423
|
+
| `.bkit/stats.md` | This repo's stats report, written by `bkit stats` from `.bkit/stats.jsonl`, `.bkit/friction.jsonl` and `docs/deferrals.jsonl`. Committed; holds no timestamp, so it changes only when the ledgers do. |
|
|
424
|
+
| `docs/plans/{YYYYMM}/` | Canonical month bucket — `{FID}-design.md`, `{FID}-plan.md`. Files never move; `{YYYYMM}` = creation month at design start. Created by the design phase. |
|
|
408
425
|
| `docs/templates/bkit-audit-*.md` | Read-only audit procedures, one per lens. Run with `@bkit-audit-generate`. |
|
|
409
426
|
| `docs/audits/{YYYYMM}/` | Audit reports. Input to `/bkit-plan`, with or without a design. |
|
|
410
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. |
|
|
411
428
|
| `.bkit/issues.jsonl` | Issue-state ledger — appended at every phase close. Append-only. |
|
|
412
|
-
| `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` |
|
|
413
430
|
| `docs/deferrals.jsonl` | Deferred items |
|
|
414
431
|
|
|
415
432
|
### In the installed package, not your repo
|
|
416
433
|
|
|
417
|
-
`bkit install` does not copy these out of `node_modules`. Read them at the path below
|
|
418
|
-
|
|
419
|
-
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.
|
|
420
437
|
|
|
421
438
|
<!-- prettier-ignore -->
|
|
422
439
|
| File | Purpose |
|
|
423
440
|
| --- | --- |
|
|
424
|
-
| `.bkit/install.md` | First-time install and upgrade, install lifecycle, uninstall |
|
|
425
|
-
| `.bkit/pipeline.md` | Pipeline reference: every subagent in execution order, CI scaffold, every audit template |
|
|
426
|
-
| `.bkit/comparison.md` | Comparison to peer frameworks / agentic design patterns |
|
|
427
441
|
| `node_modules/@cbartens/bkit/.bkit/core/workflows/` | Canonical slash-command source (rendered into `.claude/commands/`, `.cursor/commands/`, `.opencode/commands/`) |
|
|
428
442
|
| `node_modules/@cbartens/bkit/.bkit/core/prompts/` | Canonical subagent source (rendered into `.claude/agents/`, `.cursor/agents/`, `.opencode/agents/`) |
|
|
429
443
|
| `node_modules/@cbartens/bkit/.bkit/{core,shared}/` | Sources `bkit install` writes from (see § What install writes) |
|
|
430
|
-
| `node_modules/@cbartens/bkit/.bkit/templates/` | Copy-and-own templates copied raw into the consumer's `.bkit/templates/` (see `.bkit/templates.md`) |
|
|
431
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) |
|
|
432
445
|
|
|
433
446
|
---
|
|
@@ -448,4 +461,4 @@ git add .bkit/core/workflows/bkit-build.md .claude/commands/bkit-build.md .curso
|
|
|
448
461
|
git commit -m "chore: update build command"
|
|
449
462
|
```
|
|
450
463
|
|
|
451
|
-
|
|
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.
|