@cbartens/bkit 0.0.0-stage → 5.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 +421 -0
- package/.bkit/core/.agents/context.md +95 -0
- package/.bkit/core/.agents/docs.md +62 -0
- package/.bkit/core/.agents/rules.md +147 -0
- package/.bkit/core/.agents/skills.md +43 -0
- package/.bkit/core/.bkit/LICENSE.md +151 -0
- package/.bkit/core/.bkit/README.md +421 -0
- package/.bkit/core/.bkit/cloud.md +502 -0
- package/.bkit/core/.bkit/comparison.md +318 -0
- package/.bkit/core/.bkit/install.md +496 -0
- package/.bkit/core/.bkit/jsonl.md +497 -0
- package/.bkit/core/.bkit/prompts.md +474 -0
- package/.bkit/core/.bkit/providers.md +598 -0
- package/.bkit/core/.bkit/templates.md +471 -0
- package/.bkit/core/.bkit/trackers.md +95 -0
- package/.bkit/core/.bkit/workflows.md +1546 -0
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
- package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
- package/.bkit/core/AGENTS.md +77 -0
- package/.bkit/core/LICENSE.md +149 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
- package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
- package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
- package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
- package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
- package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
- package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
- package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
- package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
- package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
- package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
- package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
- package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
- package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
- package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
- package/.bkit/core/docs/templates/bkit-plan.md +476 -0
- package/.bkit/core/engine/checks/after/auth.ts +247 -0
- package/.bkit/core/engine/checks/after/ci-yml.ts +739 -0
- package/.bkit/core/engine/checks/after/github.ts +424 -0
- package/.bkit/core/engine/checks/after/index.ts +556 -0
- package/.bkit/core/engine/checks/after/managed.ts +217 -0
- package/.bkit/core/engine/checks/after/tools.ts +427 -0
- package/.bkit/core/engine/checks/after/vercel.ts +101 -0
- package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
- package/.bkit/core/engine/checks/before/env.ts +201 -0
- package/.bkit/core/engine/checks/before/files.ts +202 -0
- package/.bkit/core/engine/checks/before/index.ts +206 -0
- package/.bkit/core/engine/checks/before/mcp.ts +127 -0
- package/.bkit/core/engine/checks/before/repo.ts +77 -0
- package/.bkit/core/engine/checks/before/version.ts +67 -0
- package/.bkit/core/engine/checks/status-holes.ts +479 -0
- package/.bkit/core/engine/cli.ts +871 -0
- package/.bkit/core/engine/commands/analysis.ts +550 -0
- package/.bkit/core/engine/commands/ci/ci.ts +483 -0
- package/.bkit/core/engine/commands/comply.ts +415 -0
- package/.bkit/core/engine/commands/harvest.ts +459 -0
- package/.bkit/core/engine/commands/install/check.ts +70 -0
- package/.bkit/core/engine/commands/install/doctor.ts +247 -0
- package/.bkit/core/engine/commands/install/install.ts +528 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +972 -0
- package/.bkit/core/engine/commands/install/upgrade.ts +1026 -0
- package/.bkit/core/engine/commands/launch.ts +139 -0
- package/.bkit/core/engine/commands/lib.ts +494 -0
- package/.bkit/core/engine/commands/registry.ts +53 -0
- package/.bkit/core/engine/commands/setup/setup.ts +184 -0
- package/.bkit/core/engine/commands/telemetry.ts +32 -0
- package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
- package/.bkit/core/engine/commands/workflow/context.ts +961 -0
- package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
- package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
- package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
- package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
- package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
- package/.bkit/core/engine/commands/workflow/status.ts +455 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
- package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
- package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
- package/.bkit/core/engine/install/cloud-env.ts +925 -0
- package/.bkit/core/engine/install/managed-block.ts +212 -0
- package/.bkit/core/engine/install/manifest.ts +448 -0
- package/.bkit/core/engine/install/modules/claude.ts +362 -0
- package/.bkit/core/engine/install/modules/cloud.ts +174 -0
- package/.bkit/core/engine/install/modules/codex.ts +219 -0
- package/.bkit/core/engine/install/modules/core.ts +600 -0
- package/.bkit/core/engine/install/modules/cursor.ts +231 -0
- package/.bkit/core/engine/install/modules/index.ts +242 -0
- package/.bkit/core/engine/install/modules/opencode.ts +573 -0
- package/.bkit/core/engine/install/placeholders.ts +108 -0
- package/.bkit/core/engine/install/template-copies.ts +119 -0
- package/.bkit/core/engine/install/version-file.ts +284 -0
- package/.bkit/core/engine/install/write.ts +467 -0
- package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
- package/.bkit/core/engine/ledgers/status.ts +213 -0
- package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
- package/.bkit/core/engine/render/hosts.ts +372 -0
- package/.bkit/core/engine/render/models.ts +323 -0
- package/.bkit/core/engine/render/parts.ts +38 -0
- package/.bkit/core/engine/render/trackers.ts +170 -0
- package/.bkit/core/engine/shared/egress.ts +345 -0
- package/.bkit/core/engine/shared/json.ts +16 -0
- package/.bkit/core/engine/shared/log-prefix.ts +9 -0
- package/.bkit/core/engine/shared/package-json.ts +29 -0
- package/.bkit/core/engine/shared/package-manager.ts +38 -0
- package/.bkit/core/engine/shared/package-roots.ts +163 -0
- package/.bkit/core/engine/shared/protected-paths.ts +164 -0
- package/.bkit/core/engine/shared/settings.ts +72 -0
- package/.bkit/core/engine/shared/timeouts.ts +20 -0
- package/.bkit/core/engine/tools/wording.ts +748 -0
- package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
- package/.bkit/core/hooks/gateguard-engine.js +193 -0
- package/.bkit/core/hooks/guardrails-shell.js +154 -0
- package/.bkit/core/hooks/guardrails-tiers.js +68 -0
- package/.bkit/core/hooks/preflight-linear.sh +73 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
- package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
- package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
- package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
- package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
- package/.bkit/core/prompts/bkit-build-summary.md +93 -0
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
- package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
- package/.bkit/core/prompts/bkit-design-generate.md +110 -0
- package/.bkit/core/prompts/bkit-design-organise.md +85 -0
- package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
- package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
- package/.bkit/core/prompts/bkit-design-spike.md +97 -0
- package/.bkit/core/prompts/bkit-design-summary.md +106 -0
- package/.bkit/core/prompts/bkit-design-update.md +66 -0
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
- package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
- package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
- package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
- package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
- package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
- package/.bkit/core/prompts/bkit-plan-update.md +68 -0
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
- package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
- package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
- package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
- package/.bkit/core/workflows/bkit-auto.md +121 -0
- package/.bkit/core/workflows/bkit-build.md +802 -0
- package/.bkit/core/workflows/bkit-debug.md +642 -0
- package/.bkit/core/workflows/bkit-design.md +495 -0
- package/.bkit/core/workflows/bkit-plan.md +510 -0
- package/.bkit/core/workflows/bkit-ship.md +650 -0
- package/.bkit/shared/.bkit/.env.example +108 -0
- package/.bkit/shared/.claude/bkit-cloud.md +117 -0
- package/.bkit/shared/.claude/settings.json +88 -0
- package/.bkit/shared/.codex/hooks.json +26 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
- package/.bkit/shared/.cursor/hooks.json +26 -0
- package/.bkit/shared/.cursor/mcp.json +15 -0
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
- package/.bkit/shared/.gitattributes +37 -0
- package/.bkit/shared/.mcp.json +16 -0
- package/.bkit/shared/.opencode/opencode.json +62 -0
- package/.bkit/shared/CLAUDE.md +11 -0
- package/.bkit/shared/LICENSE.md +22 -0
- package/.bkit/shared/docs/architecture.md +19 -0
- package/.bkit/shared/docs/data-schema.md +19 -0
- package/.bkit/shared/docs/deployments.md +438 -0
- package/.bkit/shared/docs/design.md +39 -0
- package/.bkit/shared/docs/noise.md +19 -0
- package/.bkit/shared/docs/observability.md +25 -0
- package/.bkit/shared/docs/security.md +42 -0
- package/.bkit/shared/docs/setup.md +30 -0
- package/.bkit/shared/docs/technology.md +18 -0
- package/.bkit/shared/docs/testing.md +413 -0
- package/.bkit/shared/gitignore +92 -0
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +192 -0
- package/.bkit/templates/.cursor/Dockerfile +68 -0
- package/.bkit/templates/.cursor/environment.json +6 -0
- package/.bkit/templates/.cursor/settings.json +11 -0
- package/.bkit/templates/.envrc +7 -0
- package/.bkit/templates/.github/dependabot.yml +52 -0
- package/.bkit/templates/.github/renovate.json5 +239 -0
- package/.bkit/templates/.github/workflows/bkit-ci.yml +1082 -0
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +566 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +107 -0
- package/.bkit/templates/.graphifyignore +108 -0
- package/.bkit/templates/.husky/pre-commit +16 -0
- package/.bkit/templates/.husky/pre-push +91 -0
- package/.bkit/templates/.lintstagedrc.json +3 -0
- package/.bkit/templates/.prettierignore +41 -0
- package/.bkit/templates/.serena/project.yml +243 -0
- package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
- package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
- package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
- package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
- package/.bkit/templates/.vale.ini +67 -0
- package/.bkit/templates/LICENSE.md +22 -0
- package/.bkit/templates/context/bkit-cloudrun.md +84 -0
- package/.bkit/templates/context/bkit-expo.md +186 -0
- package/.bkit/templates/context/bkit-github.md +79 -0
- package/.bkit/templates/context/bkit-inngest.md +45 -0
- package/.bkit/templates/context/bkit-maestro.md +76 -0
- package/.bkit/templates/context/bkit-playwright.md +62 -0
- package/.bkit/templates/context/bkit-resend.md +36 -0
- package/.bkit/templates/context/bkit-sentry.md +65 -0
- package/.bkit/templates/context/bkit-serena.md +33 -0
- package/.bkit/templates/context/bkit-stripe.md +36 -0
- package/.bkit/templates/context/bkit-supabase.md +59 -0
- package/.bkit/templates/context/bkit-tavily.md +49 -0
- package/.bkit/templates/context/bkit-vercel.md +64 -0
- package/.bkit/templates/docs/capabilities.md +72 -0
- package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
- package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
- package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
- package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
- package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
- package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
- package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
- package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
- package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
- package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
- package/.bkit/templates/slop-scan.config.json +120 -0
- package/CHANGELOG.md +1486 -0
- package/LICENSE.md +161 -0
- package/README.md +185 -2
- package/dist/checks/after/auth.js +232 -0
- package/dist/checks/after/ci-yml.js +718 -0
- package/dist/checks/after/github.js +400 -0
- package/dist/checks/after/index.js +447 -0
- package/dist/checks/after/managed.js +187 -0
- package/dist/checks/after/tools.js +351 -0
- package/dist/checks/after/vercel.js +102 -0
- package/dist/checks/before/context-fetch.js +426 -0
- package/dist/checks/before/env.js +173 -0
- package/dist/checks/before/files.js +185 -0
- package/dist/checks/before/index.js +162 -0
- package/dist/checks/before/mcp.js +111 -0
- package/dist/checks/before/repo.js +71 -0
- package/dist/checks/before/version.js +60 -0
- package/dist/checks/status-holes.js +393 -0
- package/dist/cli.js +692 -0
- package/dist/commands/analysis.js +325 -0
- package/dist/commands/ci/ci.js +438 -0
- package/dist/commands/comply.js +310 -0
- package/dist/commands/harvest.js +354 -0
- package/dist/commands/install/check.js +61 -0
- package/dist/commands/install/doctor.js +207 -0
- package/dist/commands/install/install.js +461 -0
- package/dist/commands/install/uninstall.js +815 -0
- package/dist/commands/install/upgrade.js +771 -0
- package/dist/commands/launch.js +118 -0
- package/dist/commands/lib.js +362 -0
- package/dist/commands/registry.js +50 -0
- package/dist/commands/setup/setup.js +158 -0
- package/dist/commands/telemetry.js +29 -0
- package/dist/commands/workflow/branches.js +1265 -0
- package/dist/commands/workflow/context.js +846 -0
- package/dist/commands/workflow/counters.js +227 -0
- package/dist/commands/workflow/fids.js +224 -0
- package/dist/commands/workflow/issues.js +585 -0
- package/dist/commands/workflow/ledgers.js +472 -0
- package/dist/commands/workflow/locks.js +364 -0
- package/dist/commands/workflow/prs.js +904 -0
- package/dist/commands/workflow/repo.js +199 -0
- package/dist/commands/workflow/roadmap.js +495 -0
- package/dist/commands/workflow/runs.js +1717 -0
- package/dist/commands/workflow/runtime.js +257 -0
- package/dist/commands/workflow/skills.js +110 -0
- package/dist/commands/workflow/status.js +392 -0
- package/dist/commands/workflow/steps.js +1093 -0
- package/dist/commands/workflow/tests.js +144 -0
- package/dist/commands/workflow/workflows.js +1342 -0
- package/dist/commands/workflow/workstreams.js +141 -0
- package/dist/commands/workflow/worktrees.js +473 -0
- package/dist/install/cloud-env.js +819 -0
- package/dist/install/managed-block.js +182 -0
- package/dist/install/manifest.js +376 -0
- package/dist/install/modules/claude.js +288 -0
- package/dist/install/modules/cloud.js +152 -0
- package/dist/install/modules/codex.js +193 -0
- package/dist/install/modules/core.js +511 -0
- package/dist/install/modules/cursor.js +186 -0
- package/dist/install/modules/index.js +152 -0
- package/dist/install/modules/opencode.js +504 -0
- package/dist/install/placeholders.js +87 -0
- package/dist/install/template-copies.js +106 -0
- package/dist/install/version-file.js +204 -0
- package/dist/install/write.js +342 -0
- package/dist/ledgers/clamp-log.js +27 -0
- package/dist/ledgers/status.js +156 -0
- package/dist/ledgers/telemetry.js +637 -0
- package/dist/render/hosts.js +339 -0
- package/dist/render/models.js +288 -0
- package/dist/render/parts.js +33 -0
- package/dist/render/trackers.js +135 -0
- package/dist/shared/egress.js +299 -0
- package/dist/shared/json.js +16 -0
- package/dist/shared/log-prefix.js +7 -0
- package/dist/shared/package-json.js +22 -0
- package/dist/shared/package-manager.js +32 -0
- package/dist/shared/package-roots.js +145 -0
- package/dist/shared/protected-paths.js +153 -0
- package/dist/shared/settings.js +44 -0
- package/dist/shared/timeouts.js +19 -0
- package/dist/tools/wording.js +680 -0
- package/package.json +101 -4
|
@@ -0,0 +1,421 @@
|
|
|
1
|
+
# bkit — Agent Workflow System
|
|
2
|
+
|
|
3
|
+
{{BKIT_MANAGED_MARKER}}
|
|
4
|
+
|
|
5
|
+
**bkit** wires Claude Code (and Cursor) into five-phase tracker-integrated cycle: `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`. Hosts additive: `.claude/` + `.cursor/` always render (direct Anthropic); `bkit install --opencode=<provider>` adds opencode for non-Anthropic backends — four providers: `openrouter`, `ollama`, `opencode-zen` + `opencode-go` (opencode-native gateways; auth via `BKIT_OPENCODE_API_KEY`) — same harness, inference backend only changes (see `.bkit/providers.md` § Hosts + Providers).
|
|
6
|
+
|
|
7
|
+
README: what bkit does, env / tracker setup, upgrade paste + ongoing CLI. First-time install/auth deep-dive: `.bkit/install.md`. Workflow internals: `.bkit/workflows.md`; subagent metadata (effort, model, tools, `maxTurns`): `.bkit/prompts.md`.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## How a workflow runs (end-to-end example)
|
|
12
|
+
|
|
13
|
+
Typical cycle for `ISSUE-123` "Add feature X":
|
|
14
|
+
|
|
15
|
+
1. **Tracker issue** with **`bkit:auto`** label + non-terminal state (`Backlog`, `In Progress`).
|
|
16
|
+
2. **Trigger** — tracker comment (`@cursor /bkit-plan ISSUE-123`) or slash command (`/bkit-plan ISSUE-123`).
|
|
17
|
+
3. **Workflow Step 1** — preflight checks `bkit:auto`, acquires `.lock`, sets `bkit:plan` + `In Progress`, creates workflow comment.
|
|
18
|
+
4. **Step 2 — worktree** — git worktree at `.worktrees/issue-123-add-feature/` on `feat/issue-123-add-feature`. 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), 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, 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.
|
|
26
|
+
|
|
27
|
+
Throughout: workflows hold `.lock`, write `status.jsonl` (resume SoT), own tracker MCP calls — subagents are leaves (no tracker access), writes scoped by `tools:` allowlist.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## The five phases
|
|
32
|
+
|
|
33
|
+
<!-- prettier-ignore -->
|
|
34
|
+
| Phase | Command | Steps | Output | Hard stop? |
|
|
35
|
+
| --- | --- | --- | --- | --- |
|
|
36
|
+
| Design | `/bkit-design` | 10 | `docs/plans/{YYYYMM}/{FID}-design.md` | Yes — review before plan |
|
|
37
|
+
| Plan | `/bkit-plan` | 12 | `docs/plans/{YYYYMM}/{FID}-plan.md` (+ `-N.md` if split) | Yes — review before build |
|
|
38
|
+
| Build | `/bkit-build` | 17 | PR to `dev` | No — CI continues |
|
|
39
|
+
| Debug | `/bkit-debug` | 10 | Remediation commit on feature branch | No |
|
|
40
|
+
| Ship | `/bkit-ship` | 13 | Squash-merged PR, issue `In Review` + `bkit:merged` (plans stay canonical at `docs/plans/{YYYYMM}/`) | Yes |
|
|
41
|
+
|
|
42
|
+
**Per-step detail, verdict routing, retry / timeout constants, label flips, status.jsonl shape, comment lifecycle:** `.bkit/workflows.md`.
|
|
43
|
+
|
|
44
|
+
**Per-subagent scope, effort tier, tool surface, `maxTurns`, model assignment:** `.bkit/prompts.md`.
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Audits
|
|
49
|
+
|
|
50
|
+
No `/bkit-audit` command and no phase label. More than 30 procedures ship as `docs/templates/bkit-audit-*.md`. Invoke `@bkit-audit-generate` and name exactly one template.
|
|
51
|
+
|
|
52
|
+
<!-- prettier-ignore -->
|
|
53
|
+
| Item | Contract |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| 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. |
|
|
56
|
+
| 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`. |
|
|
57
|
+
| Plan input | `/bkit-plan` takes a design doc, one or more reports, or both. The session prompt or issue names which findings to plan (for example only `CRITICAL` and `HIGH`). The rest of each report stays context. |
|
|
58
|
+
|
|
59
|
+
Each template's `Purpose` is its scope. Main ones: security, privacy, accessibility, architecture, performance, reliability, testing, database, LLM, cost. Full catalogue: `.bkit/prompts.md` § Audit (Ad-hoc).
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Prerequisites
|
|
64
|
+
|
|
65
|
+
### Required tools
|
|
66
|
+
|
|
67
|
+
<!-- prettier-ignore -->
|
|
68
|
+
| Tool | Version | Used for |
|
|
69
|
+
| --- | --- | --- |
|
|
70
|
+
| Node | >= 20 (`engines.node`) | Runs the bkit CLI. |
|
|
71
|
+
| `pnpm` | matches `package.json` `packageManager` | Required in every consumer repo, whatever the stack: bkit installs and upgrades itself with pnpm, which makes the repo a pnpm repo. Runs the worktree install (`pnpm install --frozen-lockfile`) and the `bkit:gate:*` scripts. Non-Node stack → stub `package.json` whose `bkit:gate:*` scripts wrap the stack's own commands (e.g. `ruff check && pytest`). Also bkit CLI (`bkit install`; `pnpm tsx .bkit/core/engine/cli.ts` in bkit dev). |
|
|
72
|
+
| `gh` | latest, authenticated | PR create / view / merge in `/bkit-build`, `/bkit-debug`, `/bkit-ship` |
|
|
73
|
+
| `git` >= 2.5 | — | Worktree operations |
|
|
74
|
+
| `jq` | latest | Reads the JSON that `bkit` commands print, in workflow Bash |
|
|
75
|
+
| Claude Code CLI | latest | Local-IDE workflow execution |
|
|
76
|
+
| Cursor (optional) | 2.4+ | Cloud Agent execution; honours `tools:` frontmatter allowlist |
|
|
77
|
+
|
|
78
|
+
### Shell alias
|
|
79
|
+
|
|
80
|
+
bkit = devDependency — add once for `bkit <verb>`:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
# Add to ~/.zshrc (or ~/.bashrc), then: source ~/.zshrc
|
|
84
|
+
alias bkit='pnpm bkit'
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`bkit doctor` emits `bkit-not-on-path` if alias absent. For `bkit cursor` / `bkit opencode` (GUI launchers), run from repo root in external terminal — not inside running app.
|
|
88
|
+
|
|
89
|
+
### Environment variables
|
|
90
|
+
|
|
91
|
+
Add to shell, Cursor Cloud Agent dashboard, `apps/web/.env.example` for contributors. Exact set depends on `bkit install --tracker=<name>`:
|
|
92
|
+
|
|
93
|
+
**GitHub tracker (default — `bkit install --tracker=github`):**
|
|
94
|
+
|
|
95
|
+
```env
|
|
96
|
+
# ==========================================
|
|
97
|
+
# BKIT: CURSOR CLAUDE GITHUB INTEGRATION
|
|
98
|
+
# ==========================================
|
|
99
|
+
BKIT_CURSOR_API_KEY=""
|
|
100
|
+
BKIT_ANTHROPIC_API_KEY=""
|
|
101
|
+
BKIT_GH_TOKEN=""
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
**Linear tracker (`bkit install --tracker=linear`):**
|
|
105
|
+
|
|
106
|
+
```env
|
|
107
|
+
# ==========================================
|
|
108
|
+
# BKIT: LINEAR CURSOR CLAUDE GITHUB INTEGRATION
|
|
109
|
+
# ==========================================
|
|
110
|
+
BKIT_LINEAR_API_KEY=""
|
|
111
|
+
LINEAR_WEBHOOK_SECRET=""
|
|
112
|
+
BKIT_CURSOR_API_KEY=""
|
|
113
|
+
BKIT_ANTHROPIC_API_KEY=""
|
|
114
|
+
BKIT_GH_TOKEN=""
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
<!-- prettier-ignore -->
|
|
118
|
+
| Variable | Tracker | Where read | Purpose |
|
|
119
|
+
| --- | --- | --- | --- |
|
|
120
|
+
| `BKIT_GH_TOKEN` | all | GitHub MCP server (`Authorization: Bearer`) | Issue/label/PR writes via MCP. Fine-grained PAT (Contents, PRs, Issues, Actions, Workflows, Metadata — R/W). |
|
|
121
|
+
| `GH_TOKEN` | all | `gh` CLI inside **CI workflow Bash only** (`GH_TOKEN: ${{ github.token }}`) | Not seeded in `.bkit/.env` — local `gh` uses `gh auth login` keyring. |
|
|
122
|
+
| `GITHUB_ISSUE_ID` | github | Injected from PR body `<!-- bkit:issue=#NNN -->` | Linked GitHub issue. Injected automatically — do not set manually. |
|
|
123
|
+
| `BKIT_ANTHROPIC_API_KEY` | all | Claude Code (headless / CI) | Required when Claude invoked outside interactive session (cloud automation, CI). |
|
|
124
|
+
| `BKIT_CURSOR_API_KEY` | all | Cursor Cloud Agent dashboard / programmatic invocation | Required for non-interactive Cursor sessions. |
|
|
125
|
+
| `BKIT_LINEAR_API_KEY` | linear | Preflight hooks (`.{claude,cursor}/hooks/bkit-preflight.sh`); workflow Linear MCP via OAuth fallback | Query issue state + labels for `Auto` gate; fail-fast if absent. |
|
|
126
|
+
| `LINEAR_WEBHOOK_SECRET` | linear | Linear → Cursor integration backend | Verifies webhook signatures on `@cursor` mentions. Set in Linear ↔ Cursor integration config. |
|
|
127
|
+
|
|
128
|
+
`LINEAR_ISSUE_ID` (Linear) and `GITHUB_ISSUE_ID` (GitHub) set automatically by workflow context — do not set manually.
|
|
129
|
+
|
|
130
|
+
### Tracker workspace setup
|
|
131
|
+
|
|
132
|
+
One custom label (`Auto`), plus integration label families. Setup depends on configured tracker.
|
|
133
|
+
|
|
134
|
+
#### Bkit custom label (`Auto`)
|
|
135
|
+
|
|
136
|
+
- **`Auto`** — issues approved for agent work. Preflight refuses if absent or terminal state (`Done` / `Cancelled` / closed). Add before any cloud / automation session.
|
|
137
|
+
- **GitHub:** issue label `bkit:auto`. `bkit install --tracker=github` seeds via GitHub MCP on first run.
|
|
138
|
+
- **Linear:** Linear label `Auto`. Add manually to workspace.
|
|
139
|
+
|
|
140
|
+
#### Phase labels (GitHub tracker)
|
|
141
|
+
|
|
142
|
+
`bkit.issueTracker = "github"` → Cursor reads PR phase label for dispatch: `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`. Cursor GitHub App on repo/org required. `/bkit-design` / `/bkit-plan` have no PR — local-IDE-only on Cursor cloud.
|
|
143
|
+
|
|
144
|
+
#### Linear ↔ Cursor integration labels (Linear tracker only)
|
|
145
|
+
|
|
146
|
+
Three **parent labels** (`branch`, `model`, `repo`) — sub-labels set Cursor Cloud Agent session context. Present sub-label → Cursor follows; else integration defaults.
|
|
147
|
+
|
|
148
|
+
<!-- prettier-ignore -->
|
|
149
|
+
| Parent | Example sub-labels in this workspace | What it controls |
|
|
150
|
+
| --- | --- | --- |
|
|
151
|
+
| `branch` | `dev` | git branch the agent works on |
|
|
152
|
+
| `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 |
|
|
153
|
+
| `repo` | `<owner>/<consumer-repo>` | repo the agent operates in |
|
|
154
|
+
|
|
155
|
+
Per-agent model assignments: `.bkit/prompts.md` § Models; Cursor reads subagent frontmatter `model:` directly. Linear `model:*` sub-labels = **orchestrator-session** model only. Keep in sync with `.bkit/providers.md` § Cursor model catalog.
|
|
156
|
+
|
|
157
|
+
Full Linear ↔ Cursor setup: <https://linear.app/docs/cursor>.
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Distribution & install
|
|
162
|
+
|
|
163
|
+
`.agents/` = **canonical**. `bkit install` regenerates host outputs (`.claude/**`, `.cursor/**`) and rewrites bkit-managed blocks across consumer repo.
|
|
164
|
+
|
|
165
|
+
First-time install, `BKIT_GH_TOKEN_INSTALL` / `.npmrc` / GHA / Vercel auth, uninstall: `.bkit/install.md`. Ongoing ops below.
|
|
166
|
+
|
|
167
|
+
### Upgrade — paste into your AI
|
|
168
|
+
|
|
169
|
+
Prefer `bkit upgrade --latest` (bumps package **and** resyncs managed files) — do **not** only `pnpm add`. Replace `<ENV-FILE-PATH>` if token not already loaded (direnv / `.bkit/.env`).
|
|
170
|
+
|
|
171
|
+
````text
|
|
172
|
+
Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
|
|
173
|
+
1. Ensure `BKIT_GH_TOKEN_INSTALL` is available for the GitHub Packages bump. If not already in the environment, load without leaking (`source` is a shell builtin — not file I/O). `source` and the command MUST be the SAME Bash invocation:
|
|
174
|
+
```bash
|
|
175
|
+
set -a; source <ENV-FILE-PATH> 2>/dev/null; set +a; \
|
|
176
|
+
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" && \
|
|
177
|
+
bkit upgrade --latest
|
|
178
|
+
```
|
|
179
|
+
If token already exported (direnv / shell profile), skip `source`:
|
|
180
|
+
```bash
|
|
181
|
+
bkit upgrade --latest
|
|
182
|
+
```
|
|
183
|
+
If `bkit` not on PATH: `pnpm bkit upgrade --latest`. Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
|
|
184
|
+
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.
|
|
185
|
+
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.
|
|
186
|
+
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).
|
|
187
|
+
````
|
|
188
|
+
|
|
189
|
+
### Ongoing CLI
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
bkit upgrade # re-render at CURRENT installed version (offline)
|
|
193
|
+
bkit upgrade --latest # bump @cbartens/bkit + resync in one step (or --to=<version>)
|
|
194
|
+
bkit check # drift gate — exits non-zero on drift
|
|
195
|
+
bkit doctor # advisories only; exits 0; no managed-file writes
|
|
196
|
+
bkit install --claude --cursor # (re)seed hosts; name ≥1 module
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
> **⚠️ Version bumps:** use `bkit upgrade --latest` (or `--to=<version>`). Bare `pnpm add @cbartens/bkit` / Renovate bumps refresh lockfile only — run `bkit upgrade` after and commit resync with the bump, or `bkit check` reds CI.
|
|
200
|
+
|
|
201
|
+
### Dogfood path (this repo only)
|
|
202
|
+
|
|
203
|
+
bkit repo runs install script via `tsx` instead of published bin:
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
pnpm tsx .bkit/core/engine/cli.ts install
|
|
207
|
+
pnpm tsx .bkit/core/engine/cli.ts check
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
CI drift gate (`.github/workflows/bkit-ci.yml`) fails PR if generated files diverge from `install` output.
|
|
211
|
+
|
|
212
|
+
## File ownership
|
|
213
|
+
|
|
214
|
+
bkit owns some files outright, owns one part of others, and ships the rest as templates it never applies.
|
|
215
|
+
|
|
216
|
+
<!-- prettier-ignore -->
|
|
217
|
+
| Kind | Semantics | Files |
|
|
218
|
+
| --- | --- | --- |
|
|
219
|
+
| **Tier 1 — Fully managed** | Idempotent rewrite of whole file on every install. A consumer edit is overwritten. Uninstall deletes the file while it still matches the hash bkit recorded. | `.cursor/hooks.json`, `.bkit/*.md` (except `prompts.md`, Tier 2), `.bkit/.env.example`, `.cursor/allowlist.json`, `.cursor/cli.json` |
|
|
220
|
+
| **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. 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` |
|
|
221
|
+
| **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` |
|
|
222
|
+
| **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` |
|
|
223
|
+
| **Templates** | Never written into your repo. Install and upgrade copy them, raw, into `.bkit/templates/`; you copy what you want and own it. Catalog: `.bkit/templates.md`. | `.github/workflows/bkit-ci.yml`, `.github/workflows/bkit-cloud.yml`, `.husky/*`, `.vale.ini`, `.vale/styles/House/*`, `.lintstagedrc.json`, `slop-scan.config.json`, `.prettierignore`, `.envrc`, `.cursor/{settings.json,environment.json,Dockerfile}`, dependency-updater examples, the per-provider context-fetch blocks (`context/bkit-*.md`), `scripts/slop/bkit-slop-type-suppression.mjs`, `LICENSE.md`. Also the tool `package.json` scripts (`typecheck`, `lint`, `format:check`, `lint:prose`, `lint:slop`, `slop:delta`, `prepare`) and devDeps (prettier, slop-scan, lint-staged, husky): `.bkit/templates.md` lists them, install never adds them. |
|
|
224
|
+
|
|
225
|
+
**Marker syntax** format-specific:
|
|
226
|
+
|
|
227
|
+
- Markdown: `<!-- bkit:start -->` / `<!-- bkit:end -->`
|
|
228
|
+
- Shell / `.gitignore` / `.gitattributes`: `# <!-- bkit:start -->` / `# <!-- bkit:end -->`
|
|
229
|
+
- JS / TS ES modules: `// bkit:start` / `// bkit:end` (HTML comments are a syntax error in an ES module)
|
|
230
|
+
|
|
231
|
+
Comment prefixes (`# `, `// `) before markers preserved on block updates.
|
|
232
|
+
|
|
233
|
+
**Managed-version marker.** Every non-JSON file bkit writes carries `bkit:managed vX.Y.Z` — first line inside the `bkit:start` block, or near the top of a whole file — in its comment syntax: `<!-- … -->` (markdown), `# <!-- … -->` (shell, `.gitignore`, `.gitattributes`, `.env.example`, TOML), `// …` (JS). The marker names the licence those files are under (PolyForm Noncommercial 1.0.0 / Small Business 1.0.0) and the licences index URL, so a copy passed on in a public repo carries the terms URL with it; the full texts and the Required Notice travel at `.bkit/LICENSE.md`. Install and upgrade restamp it; `bkit check` reports `bkit-managed-stale` for a marker that differs from the installed version (blocker on `main` / `dev`, advisory on feature branches). Templates carry no marker and no block.
|
|
234
|
+
|
|
235
|
+
**Hook scripts.** Install generates each host's `bkit-preflight.sh`, `gateguard` and `guardrails` hook from its template plus the code the hosts share (`.bkit/core/hooks/`, `.bkit/providers.md` § Hooks). bkit's block in `.claude/hooks/bkit-gateguard.cjs`, `.cursor/hooks/bkit-gateguard.cjs`, `.opencode/plugin/bkit-gateguard.js` and the `bkit-guardrails.cjs` hooks is a pure advisory engine — no stdin read, no stdout write, no top-level call — so it cannot collide with a consumer's own emitter. Delivery is per host: Claude / Cursor / Codex inject the checklist before the edit, opencode appends it to the tool result in `execute.after` (`BKIT_GATEGUARD=deny` is the only pre-edit block) — see `.bkit/providers.md` § Hooks. A consumer file with no markers gets the block appended; wire its exported function into your driver.
|
|
236
|
+
|
|
237
|
+
### What install writes
|
|
238
|
+
|
|
239
|
+
<!-- prettier-ignore -->
|
|
240
|
+
| Path | Module | Source | Tier |
|
|
241
|
+
| --- | --- | --- | --- |
|
|
242
|
+
| `.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`. |
|
|
243
|
+
| `.bkit/version` | core | package.json version | Written last (partial installs detectable) |
|
|
244
|
+
| `.gitignore` | core | `.bkit/shared/gitignore` | Tier 2 html-comment |
|
|
245
|
+
| `AGENTS.md` | core | `.bkit/core/AGENTS.md` | Tier 2 html-comment |
|
|
246
|
+
| `CLAUDE.md` | claude | `.bkit/shared/CLAUDE.md` | Tier 2 html-comment |
|
|
247
|
+
| `docs/*.md` (blocks) | core | `.bkit/shared/docs/` | Tier 2 html-comment |
|
|
248
|
+
| `docs/templates/bkit-*.md` | core | `.bkit/core/docs/templates/` | Tier 2 html-comment |
|
|
249
|
+
| `.gitattributes` | core | `.bkit/shared/.gitattributes` | Tier 2 html-comment (`merge=union` for the append-only ledgers) |
|
|
250
|
+
| `.bkit/templates/**` | — | the whole `.bkit/templates/` root | Raw copies, refreshed on every install and upgrade; never hashed. Upgrade prints the changed paths. |
|
|
251
|
+
| `.bkit/{cloud,comparison,install,jsonl,LICENSE,providers,prompts,trackers,workflows,README}.md` | core | `.bkit/core/.bkit/` | Tier 1 (canonical-overwrite). The reference docs agents read at runtime, plus `LICENSE.md`: the PolyForm pair and Required Notice that travel with every file bkit writes (PolyForm's Notices section). |
|
|
252
|
+
| `.claude/commands/bkit-*.md` | claude | `.bkit/core/workflows/` (byte-identical) | Host pass — always overwrite |
|
|
253
|
+
| `.claude/agents/bkit-*.md` | claude | `.bkit/core/prompts/` (byte-identical) | Host pass — always overwrite |
|
|
254
|
+
| `.claude/settings.json` | claude | `.bkit/shared/.claude/settings.json` | Tier 2 JSON deep-containment. Permission allow/deny/ask + SessionStart / PreToolUse hook wiring. |
|
|
255
|
+
| `.claude/hooks/bkit-preflight.sh` | claude | `.bkit/core/.claude/hooks/` | Tier 2 html-comment (`# ` prefix) |
|
|
256
|
+
| `.claude/hooks/bkit-gateguard.cjs` | claude | `.bkit/core/.claude/hooks/` | Tier 2 slash-comment |
|
|
257
|
+
| `.mcp.json` | claude | `.bkit/shared/.mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only; absent file → the tracker-filtered render |
|
|
258
|
+
| `.bkit/.env.example` | claude | `.bkit/shared/.bkit/.env.example` | Tier 1 (fully managed). Real values go in `.bkit/.env`. |
|
|
259
|
+
| `.cursor/commands/bkit-*.md` | cursor | `.bkit/core/workflows/` (T1+T2 transforms) | Host pass — always overwrite |
|
|
260
|
+
| `.cursor/agents/bkit-*.md` | cursor | `.bkit/core/prompts/` (T3 transforms) | Host pass — always overwrite |
|
|
261
|
+
| `package.json#scripts.bkit:gate:format` / `bkit:gate:static` / `bkit:gate:static-unit` / `bkit:gate:install-static-unit-build` | core | hardcoded defaults | Seeded (add-if-missing; install and upgrade). What hooks, workflows and prompts run; the name states which tiers. The tool scripts the defaults chain (`typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta`) and their devDeps are templates: `.bkit/templates.md`. |
|
|
262
|
+
| `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. |
|
|
263
|
+
| `.cursor/hooks.json` | cursor | `.bkit/shared/.cursor/hooks.json` | Tier 1 (fully managed) |
|
|
264
|
+
| `.cursor/mcp.json` | cursor | `.bkit/shared/.cursor/mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only |
|
|
265
|
+
| `.cursor/rules/bkit-rules.mdc` | cursor | `.bkit/shared/.cursor/rules/bkit-rules.mdc` | Tier 2 html-comment |
|
|
266
|
+
| `.cursor/hooks/bkit-preflight.sh` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 html-comment (`# ` prefix) |
|
|
267
|
+
| `.cursor/hooks/bkit-guardrails.cjs` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 slash-comment. Destructive-op + curl/wget host gates. |
|
|
268
|
+
| `.cursor/hooks/bkit-gateguard.cjs` | cursor | `.bkit/core/.cursor/hooks/` | Tier 2 slash-comment |
|
|
269
|
+
| `.cursor/allowlist.json` | cursor | derived from bkit's shipped egress registry, union `.agents/context.md` allowed-domains | Tier 1 (canonical-overwrite). Curl/wget host allowlist `bkit-guardrails.cjs` reads at runtime. |
|
|
270
|
+
| `.cursor/cli.json` | cursor | derived from `.agents/context.md` mcp-servers | Tier 1 (canonical-overwrite). Cursor CLI / cloud-agent `Mcp(<server>:*)` allows. |
|
|
271
|
+
| `.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>`**. |
|
|
272
|
+
| `.opencode/commands/bkit-*.md` | opencode | `.bkit/core/workflows/` | Host pass — always overwrite |
|
|
273
|
+
| `.opencode/agents/bkit-*.md` | opencode | `.bkit/core/prompts/` | Host pass — always overwrite |
|
|
274
|
+
| `.opencode/plugin/bkit-gateguard.js` | opencode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment |
|
|
275
|
+
| `.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). |
|
|
276
|
+
|
|
277
|
+
The cloud workflow and the Cursor Background Agent files are templates the `--auto` setup advisory points at.
|
|
278
|
+
|
|
279
|
+
### Optional post-install decisions (tracker + cloud agents)
|
|
280
|
+
|
|
281
|
+
Two capabilities **opt-in**, excluded from default install: **issue tracker** (`--tracker=github|linear`), **cloud agents** (`--auto=claude|cursor|opencode`: records the choice and points at the copy-and-own templates — `bkit-cloud.yml`, `.claude/hooks/bkit-cloud-bootstrap.sh`, and the Cursor `Dockerfile`/`environment.json`; default install ships zero cloud footprint). Default wires neither; post-install advisory emits `tracker-setup-none` / `cloud-router-none`. Choices persist in `package.json` (`bkit.issueTracker`, `bkit.cloudAgents`); `"none"` silences the nudge. Cloud router split: each job inert without model-auth secret (`BKIT_ANTHROPIC_API_KEY` claude, `OPENCODE_PROVIDER_KEY` opencode) + GHA write permissions + (Cursor) dashboard trigger; depends on opt-in GitHub tracker.
|
|
282
|
+
|
|
283
|
+
**Dependency updaters.** Copy one example and own it: `.bkit/templates/.github/renovate.json5`, `.bkit/templates/.github/workflows/bkit-renovate.yml` (self-hosted runner only), or `.bkit/templates/.github/dependabot.yml`. `bkit.depUpdater: "none"` skips the install-time absence advisory. `bkit check` emits `dep-updater-absent` and `dep-updater-both`. See `docs/deployments.md` § Dependency updaters.
|
|
284
|
+
|
|
285
|
+
**All templates.** Copy and own, never installed. Catalog and install steps: `.bkit/templates.md`.
|
|
286
|
+
|
|
287
|
+
### dogfood rule — updater PRs against workflows (only if you opt in)
|
|
288
|
+
|
|
289
|
+
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:
|
|
290
|
+
|
|
291
|
+
1. Before merge, edit matching `.bkit/templates/.github/workflows/*.yml` with same SHA bump (one `Edit` per file).
|
|
292
|
+
2. Run `pnpm test` (`.bkit/core/engine/audits/templates/templates-content.test.ts` snapshot regenerates via `pnpm vitest run .bkit/core/engine/audits/templates/templates-content.test.ts -u` if bkit-ci.yml shape changed; commit snapshot).
|
|
293
|
+
3. Push template-side change to updater PR branch (or follow-up commit on `dev` if branch read-only).
|
|
294
|
+
|
|
295
|
+
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.
|
|
296
|
+
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## Triggering workflows
|
|
300
|
+
|
|
301
|
+
Three paths: Linear comment (cloud), Claude Code (interactive local), Cursor (interactive local). Same workflow from `.bkit/core/workflows/` — compute source and orchestrator model differ.
|
|
302
|
+
|
|
303
|
+
### From a tracker comment (cloud — Cursor Cloud Agent)
|
|
304
|
+
|
|
305
|
+
**Linear tracker:** `@cursor` in Linear comment with slash command + issue ID:
|
|
306
|
+
|
|
307
|
+
```
|
|
308
|
+
@cursor /bkit-plan ISSUE-123
|
|
309
|
+
@cursor /bkit-build ISSUE-123
|
|
310
|
+
@cursor /bkit-ship ISSUE-123
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
`@cursor` = **Cursor's standard Linear integration** — not bkit hook; bkit runs no Linear webhook. Native integration spawns Cloud Agent, posts session URL as Linear comment; agent runs bkit workflow because Cursor cloud agents read root `AGENTS.md`, routing `/bkit-*` to `.bkit/core/workflows/`. Progress in subsequent comments per step.
|
|
314
|
+
|
|
315
|
+
**GitHub tracker:** PR-label trigger — Cursor Automations "Pull request label changed". `bkit:auto` on PR (from `bkit-build`) triggers dispatch; phase label (`bkit:plan`, `bkit:build`, etc.) selects workflow. Issue comments via GitHub MCP. `/bkit-design` / `/bkit-plan` no PR → local-IDE-only on Cursor cloud for GitHub tracker.
|
|
316
|
+
|
|
317
|
+
**Requirements (Linear):** `Auto` label + non-terminal state. `BKIT_LINEAR_API_KEY`, `BKIT_CURSOR_API_KEY`, `BKIT_ANTHROPIC_API_KEY`, `BKIT_GH_TOKEN` in Cursor Cloud Agent dashboard.
|
|
318
|
+
|
|
319
|
+
**Requirements (GitHub):** `BKIT_GH_TOKEN`, `BKIT_CURSOR_API_KEY`, `BKIT_ANTHROPIC_API_KEY` in dashboard. Cursor GitHub App on repo/org. `GITHUB_ISSUE_ID` from PR body `<!-- bkit:issue=#NNN -->` — no manual setup.
|
|
320
|
+
|
|
321
|
+
### From Claude Code (interactive — local)
|
|
322
|
+
|
|
323
|
+
Slash commands at repo root:
|
|
324
|
+
|
|
325
|
+
```
|
|
326
|
+
/bkit-design ISSUE-123 # produce a design doc
|
|
327
|
+
/bkit-plan ISSUE-123 # produce an implementation plan
|
|
328
|
+
/bkit-build ISSUE-123 # execute the plan in a worktree, open a PR
|
|
329
|
+
/bkit-debug ISSUE-123 # diagnose and remediate CI failures
|
|
330
|
+
/bkit-ship ISSUE-123 # merge the PR for the current branch, archive, close the issue
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
Claude reads issue, comments, plan files via tracker MCP.
|
|
334
|
+
|
|
335
|
+
**Requirements:** `BKIT_GH_TOKEN`, active Claude Code session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` when `bkit.issueTracker = "linear"`. Session model = orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column) — set via `/model` before invoking; not duplicated here.
|
|
336
|
+
|
|
337
|
+
### From Cursor (interactive — local)
|
|
338
|
+
|
|
339
|
+
Cursor 2.4+ honours `.cursor/commands/bkit-*.md` and `.cursor/agents/bkit-*.md`:
|
|
340
|
+
|
|
341
|
+
```
|
|
342
|
+
/bkit-plan ISSUE-123
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
Orchestrator reads `.cursor/commands/` workflow. Subagents via `Task`, `model:` from frontmatter (no host override).
|
|
346
|
+
|
|
347
|
+
**Requirements:** `BKIT_GH_TOKEN` (GitHub, default) or `BKIT_LINEAR_API_KEY` (Linear). Cursor account in good standing.
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## Adding or updating skills
|
|
352
|
+
|
|
353
|
+
> **Skills must be installed before first use** — initial setup in `docs/setup.md`. Inventory and registry rules: `.agents/skills.md`.
|
|
354
|
+
|
|
355
|
+
Skills = third-party instruction sets loaded at invocation.
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
npx skills find [query] # search the registry
|
|
359
|
+
npx skills add <owner/repo> -y # install project-locally into .agents/skills/
|
|
360
|
+
npx skills update # update all installed
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
Installed list: `.agents/skills.md`. Skills in `.agents/skills/` not listed → pruned by ship workflow archive step.
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## Key files
|
|
368
|
+
|
|
369
|
+
<!-- prettier-ignore -->
|
|
370
|
+
| File | Purpose |
|
|
371
|
+
| --- | --- |
|
|
372
|
+
| `.agents/rules.md` | Universal agent rules — read first by every workflow |
|
|
373
|
+
| `.bkit/workflows.md` | Workflow pipeline reference (steps, verdicts, contracts) |
|
|
374
|
+
| `.bkit/prompts.md` | Per-subagent description, effort tier, model, `maxTurns`. Audit template catalogue (§ Audit (Ad-hoc)). |
|
|
375
|
+
| `.agents/docs.md` | Document index and phase-matrix (what to read per phase) |
|
|
376
|
+
| `.agents/skills.md` | Installed skills registry |
|
|
377
|
+
| `.bkit/providers.md` | Host differences (Claude/Cursor/opencode), transform rules, additive install, provider model IDs, pin process (§ Selecting pins), network allowlist encodings (`.cursor/allowlist.json` vs baked settings) |
|
|
378
|
+
| `.bkit/friction.jsonl` | Friction ledger — orchestrator-observed recovery moments. Created on first append by a phase workflow, not by install; drained by `bkit harvest` only. Row shape: `.bkit/jsonl.md`. |
|
|
379
|
+
| `docs/plans/{YYYYMM}/` | Canonical month bucket — `{FID}-design.md`, `{FID}-plan.md` (+ `-N.md` if split). Files never move; `{YYYYMM}` = creation month at design start. Created by the design phase. |
|
|
380
|
+
| `docs/templates/bkit-audit-*.md` | Read-only audit procedures, one per lens. Run with `@bkit-audit-generate`. |
|
|
381
|
+
| `docs/audits/{YYYYMM}/` | Audit reports. Input to `/bkit-plan`, with or without a design. |
|
|
382
|
+
| `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. |
|
|
383
|
+
| `.bkit/issues.jsonl` | Issue-state ledger — appended at every phase close. Append-only. |
|
|
384
|
+
| `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` |
|
|
385
|
+
| `docs/deferrals.jsonl` | Deferred items |
|
|
386
|
+
|
|
387
|
+
### In the installed package, not your repo
|
|
388
|
+
|
|
389
|
+
`bkit install` does not copy these out of `node_modules`. Read them at the path below — a
|
|
390
|
+
bare `.bkit/comparison.md` or `.bkit/core/prompts/` in your own repo will not resolve.
|
|
391
|
+
|
|
392
|
+
<!-- prettier-ignore -->
|
|
393
|
+
| File | Purpose |
|
|
394
|
+
| --- | --- |
|
|
395
|
+
| `.bkit/install.md` | First-time install, auth (`BKIT_GH_TOKEN_INSTALL` / `.npmrc` / GHA / Vercel), install lifecycle, uninstall |
|
|
396
|
+
| `.bkit/comparison.md` | Pipeline reference + comparison to agentic design patterns / peer frameworks |
|
|
397
|
+
| `node_modules/@cbartens/bkit/.bkit/core/workflows/` | Canonical slash-command source (rendered into `.claude/commands/`, `.cursor/commands/`, `.opencode/commands/`) |
|
|
398
|
+
| `node_modules/@cbartens/bkit/.bkit/core/prompts/` | Canonical subagent source (rendered into `.claude/agents/`, `.cursor/agents/`, `.opencode/agents/`) |
|
|
399
|
+
| `node_modules/@cbartens/bkit/.bkit/{core,shared}/` | Sources `bkit install` writes from (see § What install writes) |
|
|
400
|
+
| `node_modules/@cbartens/bkit/.bkit/templates/` | Copy-and-own templates copied raw into the consumer's `.bkit/templates/` (see `.bkit/templates.md`) |
|
|
401
|
+
| `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) |
|
|
402
|
+
|
|
403
|
+
---
|
|
404
|
+
|
|
405
|
+
## Editing workflows or prompts
|
|
406
|
+
|
|
407
|
+
Edit `.bkit/core/workflows/` (orchestrators) or `.bkit/core/prompts/` (subagents), then re-run install:
|
|
408
|
+
|
|
409
|
+
```bash
|
|
410
|
+
# Edit source
|
|
411
|
+
vim .bkit/core/workflows/bkit-build.md
|
|
412
|
+
|
|
413
|
+
# Regenerate (run dist binary; faster than tsx and matches what consumers run)
|
|
414
|
+
pnpm build && node dist/cli.js install
|
|
415
|
+
|
|
416
|
+
# Commit both source and generated output together
|
|
417
|
+
git add .bkit/core/workflows/bkit-build.md .claude/commands/bkit-build.md .cursor/commands/bkit-build.md
|
|
418
|
+
git commit -m "chore: update build command"
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
New subagent? Update `.bkit/core/.bkit/prompts.md` (the package source; install mirrors it to `.bkit/prompts.md`) with row (frontmatter rationale + `maxTurns` calibration + model assignment) before re-run install — single source of truth for agent metadata; CI drift gate enforces consistency.
|