@cbartens/bkit 5.2.4 → 5.4.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 +27 -11
- package/.bkit/core/.agents/context.md +1 -1
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
- package/.bkit/core/.agents/rules.md +18 -1
- package/.bkit/core/.bkit/README.md +26 -10
- package/.bkit/core/.bkit/cloud.md +40 -39
- package/.bkit/core/.bkit/comparison.md +68 -345
- package/.bkit/core/.bkit/install.md +16 -9
- package/.bkit/core/.bkit/lite.md +73 -0
- package/.bkit/core/.bkit/pipeline.md +346 -0
- package/.bkit/core/.bkit/prompts.md +90 -74
- package/.bkit/core/.bkit/providers.md +42 -23
- package/.bkit/core/.bkit/templates.md +138 -19
- package/.bkit/core/.bkit/trackers.md +49 -4
- package/.bkit/core/.bkit/workflows.md +144 -123
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +26 -21
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-llm.md +22 -15
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
- package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +7 -7
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +12 -9
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +14 -12
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -8
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +8 -6
- package/.bkit/core/engine/checks/after/auth.ts +9 -9
- package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
- package/.bkit/core/engine/checks/after/github.ts +29 -120
- package/.bkit/core/engine/checks/after/index.ts +2 -2
- package/.bkit/core/engine/checks/after/managed.ts +8 -28
- package/.bkit/core/engine/checks/after/tools.ts +3 -15
- package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
- package/.bkit/core/engine/checks/before/index.ts +7 -43
- package/.bkit/core/engine/checks/before/mcp.ts +17 -8
- package/.bkit/core/engine/checks/before/repo.ts +9 -12
- package/.bkit/core/engine/checks/status-holes.ts +4 -6
- package/.bkit/core/engine/checks/tips/catalogue.ts +76 -24
- package/.bkit/core/engine/checks/tips/detect.ts +45 -2
- package/.bkit/core/engine/checks/tips/index.ts +77 -26
- package/.bkit/core/engine/cli.ts +57 -27
- package/.bkit/core/engine/commands/analysis.ts +36 -26
- package/.bkit/core/engine/commands/comply.ts +42 -32
- package/.bkit/core/engine/commands/harvest.ts +12 -12
- package/.bkit/core/engine/commands/install/doctor.ts +57 -28
- package/.bkit/core/engine/commands/install/install.ts +73 -130
- package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
- package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +45 -18
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +12 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +386 -286
- package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
- package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +15 -4
- package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
- package/.bkit/core/engine/commands/workflow/roadmap.ts +49 -53
- package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
- package/.bkit/core/engine/commands/workflow/status.ts +33 -11
- package/.bkit/core/engine/commands/workflow/steps.ts +25 -15
- package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
- package/.bkit/core/engine/commands/workflow/workflows.ts +436 -267
- package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +24 -6
- package/.bkit/core/engine/install/cloud-env.ts +10 -31
- package/.bkit/core/engine/install/manifest.ts +14 -7
- package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
- package/.bkit/core/engine/install/modules/claude.ts +20 -28
- package/.bkit/core/engine/install/modules/cloud.ts +5 -2
- package/.bkit/core/engine/install/modules/codex.ts +15 -29
- package/.bkit/core/engine/install/modules/core.ts +106 -70
- package/.bkit/core/engine/install/modules/cursor.ts +6 -20
- package/.bkit/core/engine/install/modules/index.ts +7 -1
- package/.bkit/core/engine/install/modules/opencode.ts +48 -70
- package/.bkit/core/engine/install/network-allowlist.ts +73 -0
- package/.bkit/core/engine/install/placeholders.ts +16 -35
- package/.bkit/core/engine/install/write.ts +59 -12
- package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
- package/.bkit/core/engine/render/hosts.ts +47 -67
- package/.bkit/core/engine/render/models.ts +29 -11
- package/.bkit/core/engine/shared/branches.ts +13 -0
- package/.bkit/core/engine/shared/egress.ts +3 -3
- package/.bkit/core/engine/shared/json.ts +18 -1
- package/.bkit/core/engine/shared/package-json.ts +63 -0
- package/.bkit/core/engine/shared/package-roots.ts +0 -10
- package/.bkit/core/engine/shared/protected-paths.ts +5 -130
- package/.bkit/core/engine/shared/settings.ts +44 -0
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/hooks/antigravity-hook.js +1 -0
- package/.bkit/core/hooks/guardrails-shell.js +186 -40
- package/.bkit/core/hooks/guardrails-tiers.js +5 -78
- package/.bkit/core/prompts/bkit-audit-generate.md +103 -7
- package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
- package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
- package/.bkit/core/prompts/bkit-design-spike.md +1 -1
- package/.bkit/core/prompts/bkit-design-summary.md +2 -2
- package/.bkit/core/prompts/bkit-design-update.md +1 -1
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
- package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
- package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
- package/.bkit/core/prompts/bkit-plan-update.md +1 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
- package/.bkit/core/workflows/bkit-auto.md +2 -2
- package/.bkit/core/workflows/bkit-build.md +10 -10
- package/.bkit/core/workflows/bkit-debug.md +80 -44
- package/.bkit/core/workflows/bkit-design.md +22 -13
- package/.bkit/core/workflows/bkit-plan.md +33 -16
- package/.bkit/core/workflows/bkit-ship.md +87 -98
- package/.bkit/shared/.claude/bkit-cloud.md +58 -25
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.cursor/mcp.json +2 -1
- package/.bkit/shared/.opencode/opencode.json +19 -1
- package/.bkit/shared/docs/deployments.md +49 -29
- package/.bkit/shared/docs/security.md +8 -6
- package/.bkit/shared/docs/testing.md +9 -5
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.cursor/Dockerfile +30 -16
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
- package/.bkit/templates/.github/renovate.json5 +91 -12
- package/.bkit/templates/.github/workflows/bkit-ci.yml +73 -55
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
- package/.bkit/templates/.husky/pre-commit +6 -0
- package/.bkit/templates/.husky/pre-push +15 -3
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/.oxlintrc.json +21 -0
- package/.bkit/templates/docs/capabilities.md +1 -1
- package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
- package/CHANGELOG.md +98 -3
- package/README.md +252 -122
- package/dist/checks/after/auth.js +10 -11
- package/dist/checks/after/ci-yml.js +11 -14
- package/dist/checks/after/github.js +32 -125
- package/dist/checks/after/index.js +3 -2
- package/dist/checks/after/managed.js +8 -24
- package/dist/checks/after/tools.js +3 -16
- package/dist/checks/before/context-fetch.js +1 -21
- package/dist/checks/before/index.js +6 -42
- package/dist/checks/before/mcp.js +14 -9
- package/dist/checks/before/repo.js +8 -11
- package/dist/checks/status-holes.js +5 -7
- package/dist/checks/tips/catalogue.js +65 -18
- package/dist/checks/tips/detect.js +41 -2
- package/dist/checks/tips/index.js +61 -25
- package/dist/cli.js +52 -26
- package/dist/commands/analysis.js +21 -5
- package/dist/commands/comply.js +40 -31
- package/dist/commands/harvest.js +12 -13
- package/dist/commands/install/doctor.js +55 -23
- package/dist/commands/install/install.js +72 -122
- package/dist/commands/install/uninstall.js +165 -31
- package/dist/commands/install/upgrade.js +46 -39
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +41 -16
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +10 -3
- package/dist/commands/workflow/branches.js +303 -248
- package/dist/commands/workflow/counters.js +17 -7
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/fids.js +39 -0
- package/dist/commands/workflow/issues.js +63 -27
- package/dist/commands/workflow/ledgers.js +3 -1
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +8 -5
- package/dist/commands/workflow/repo.js +2 -2
- package/dist/commands/workflow/roadmap.js +50 -57
- package/dist/commands/workflow/runs.js +5 -5
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +19 -11
- package/dist/commands/workflow/tests.js +16 -3
- package/dist/commands/workflow/workflows.js +390 -249
- package/dist/commands/workflow/workstreams.js +4 -2
- package/dist/commands/workflow/worktrees.js +15 -6
- package/dist/install/cloud-env.js +10 -23
- package/dist/install/manifest.js +14 -7
- package/dist/install/modules/antigravity.js +15 -26
- package/dist/install/modules/claude.js +17 -21
- package/dist/install/modules/cloud.js +6 -2
- package/dist/install/modules/codex.js +15 -29
- package/dist/install/modules/core.js +95 -63
- package/dist/install/modules/cursor.js +6 -9
- package/dist/install/modules/index.js +6 -1
- package/dist/install/modules/opencode.js +41 -72
- package/dist/install/network-allowlist.js +62 -0
- package/dist/install/placeholders.js +16 -35
- package/dist/install/write.js +55 -15
- package/dist/ledgers/telemetry.js +5 -4
- package/dist/render/hosts.js +30 -55
- package/dist/render/models.js +20 -9
- package/dist/shared/branches.js +11 -0
- package/dist/shared/egress.js +0 -2
- package/dist/shared/json.js +14 -0
- package/dist/shared/package-json.js +61 -0
- package/dist/shared/package-roots.js +0 -8
- package/dist/shared/protected-paths.js +5 -122
- package/dist/shared/settings.js +23 -1
- package/dist/shared/timeouts.js +8 -7
- package/package.json +21 -17
- package/.bkit/core/.agents/shortcuts.md +0 -73
|
@@ -1,372 +1,40 @@
|
|
|
1
|
-
# bkit — Comparison
|
|
1
|
+
# bkit — Comparison with Other Frameworks & Agentic Design Patterns
|
|
2
2
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
5
|
> [!CAUTION]
|
|
6
|
-
> **Purpose:** Human-facing reference. bkit vs other AI development frameworks,
|
|
6
|
+
> **Purpose:** Human-facing reference. bkit vs other AI development frameworks, bkit vs Antonio Gulli's _Agentic Design Patterns_. Evaluation, outreach — not agent workflow doc-matrix. Five-phase pipeline + every subagent + every audit template: `.bkit/pipeline.md`.
|
|
7
7
|
>
|
|
8
8
|
> **Rules:**
|
|
9
9
|
>
|
|
10
10
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
11
11
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
12
12
|
> - Keep prose factual; house / write-good linters apply to `*.md`; no hype adjectives.
|
|
13
|
-
> -
|
|
14
|
-
> -
|
|
15
|
-
> -
|
|
13
|
+
> - Framework table cells: each project's own repo / docs only, never roundups or AI summaries; no star counts; refresh the as-of month with the table.
|
|
14
|
+
> - Headings linked from outside carry a fixed `<a id>` above them; keep the id when rewording the heading.
|
|
15
|
+
> - Table cells about bkit (subagent counts, audit count, model pairings) → match `.bkit/pipeline.md` and `.bkit/core/.bkit/prompts.md` § Models.
|
|
16
16
|
|
|
17
17
|
**Contents**
|
|
18
18
|
|
|
19
19
|
- [What this is](#what-this-is)
|
|
20
|
-
- [
|
|
21
|
-
- [Pipeline map](#pipeline-map-key-steps-only) · [CI test scaffold](#ci-test-scaffold-runs-on-every-pr--push)
|
|
22
|
-
- [Design](#phase-1--bkit-design) · [Plan](#phase-2--bkit-plan) · [Build](#phase-3--bkit-build) · [Debug](#phase-4--bkit-debug) · [Ship](#phase-5--bkit-ship)
|
|
23
|
-
- [Audits: every template](#audits)
|
|
24
|
-
- [Part 2 — Comparison to agentic design patterns](#part-2--comparison-to-agentic-design-patterns)
|
|
25
|
-
- [Where bkit goes beyond the catalogue](#where-bkit-goes-beyond-the-catalogue) · [Known gaps](#known-gaps-scoped-as-opportunities)
|
|
26
|
-
- [Part 3 — Compared with other AI development frameworks](#part-3--compared-with-other-ai-development-frameworks)
|
|
20
|
+
- [Compared with other AI development frameworks](#frameworks)
|
|
27
21
|
- [Agents and CI](#agents-and-ci)
|
|
22
|
+
- [Compared with agentic design patterns](#patterns)
|
|
23
|
+
- [Where bkit goes beyond the catalogue](#beyond-the-book) · [Known gaps](#known-gaps)
|
|
28
24
|
|
|
29
25
|
## What this is
|
|
30
26
|
|
|
31
|
-
bkit turns a single coding-agent request into gated, peer-reviewed engineering
|
|
27
|
+
bkit turns a single coding-agent request into gated, peer-reviewed engineering: five commands (`/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`), 49 single-purpose subagents, 35 audit templates, same pipeline on Claude Code, Cursor, Codex, Google Antigravity and opencode. Every subagent in execution order and every audit template: [`.bkit/pipeline.md`](pipeline.md).
|
|
32
28
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
Part 1: every phase subagent in execution order, then the main audit templates. Part 2: bkit vs Gulli agentic patterns. Part 3: bkit vs 10 other AI development frameworks, one table, then agents and CI in detail.
|
|
29
|
+
This doc: bkit vs 10 other AI development frameworks (one table, then agents and CI in detail), then bkit vs Gulli's agentic patterns.
|
|
36
30
|
|
|
37
31
|
Not related to [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code), a separate project with the same name. This bkit = `@cbartens/bkit`, [github.com/cbartens/bkit](https://github.com/cbartens/bkit).
|
|
38
32
|
|
|
39
33
|
---
|
|
40
34
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
Each phase lists subagents in execution order. "Parallel" = same-time run, merged after; distinct lenses = multi-perspective review. Orchestrator steps (git, worktree, tracker) noted but not listed as subagents.
|
|
44
|
-
|
|
45
|
-
### Pipeline map (key steps only)
|
|
46
|
-
|
|
47
|
-
```
|
|
48
|
-
┌────────────────────── bkit-auto (opt-in cloud router) ─────────────────┐
|
|
49
|
-
│ workflow_run on feat/** → ship (CI green) / debug (CI red) │
|
|
50
|
-
│ workflow_dispatch → ship|debug|plan|build (design: local only) │
|
|
51
|
-
│ Dispatches the matching /bkit-* skill — runs unattended in cloud │
|
|
52
|
-
│ (Claude Code on the web / Cursor cloud agents / opencode). │
|
|
53
|
-
│ Opt-in: `bkit install --auto=claude|cursor|opencode`. See `.bkit/cloud.md`. │
|
|
54
|
-
└────────────────────────────────────────────────────────────────────────┘
|
|
55
|
-
│
|
|
56
|
-
▼
|
|
57
|
-
|
|
58
|
-
/bkit-design ───── output: detailed design ───────────────────────────────────
|
|
59
|
-
1. grill (human interview, one decision frontier per round;
|
|
60
|
-
skipped headless: recommended answers recorded as assumed)
|
|
61
|
-
2. fetch related (semantic tracker search, rank order → related-issues.md)
|
|
62
|
-
3. brainstorm × 3 (parallel, distinct lenses, no sibling reads)
|
|
63
|
-
• pragmatic • optimal-tradeoff • risk / pre-mortem
|
|
64
|
-
4. generate design (synthesise across lenses + related issues)
|
|
65
|
-
5. review × 2 (parallel, cross-tier models)
|
|
66
|
-
• feasibility (web) • operability (failure modes, observability, on-call)
|
|
67
|
-
6. spike (only if review flags load-bearing unknowns:
|
|
68
|
-
throwaway probe code, confined to the run's log folder)
|
|
69
|
-
7. update design (fold reviews + spike back in)
|
|
70
|
-
8. organise (decompose into workstreams + DAG)
|
|
71
|
-
9. summary (tracker-facing)
|
|
72
|
-
|
|
73
|
-
/bkit-plan ───── output: detailed plan ───────────────────────────────────────
|
|
74
|
-
1. generate plan
|
|
75
|
-
2. fetch context (tracker: related issues; ledgers: prior deferrals,
|
|
76
|
-
prior failures, strongest term-overlap first, top 40
|
|
77
|
-
→ feeds all three reviewers below)
|
|
78
|
-
3. review × 3 (parallel, distinct lenses)
|
|
79
|
-
• tightness + design-coverage • dependency-correctness • regression-risk
|
|
80
|
-
4. update plan (merge critiques, max-wins on CRITICAL)
|
|
81
|
-
5. scope-check × 2 (parallel)
|
|
82
|
-
• internal-completeness • scope audit (cross-family)
|
|
83
|
-
6. update plan (merge scope findings)
|
|
84
|
-
7. complexity-check (single vs split)
|
|
85
|
-
8. complexity-split (only if SPLIT)
|
|
86
|
-
9. summary (tracker-facing)
|
|
87
|
-
|
|
88
|
-
/bkit-build ─── output: code, PR to dev, CI takes over ──────────────────────
|
|
89
|
-
1. plan-current (plan still executable against code landed since it was written?)
|
|
90
|
-
2. install-skills
|
|
91
|
-
3. execute build (producer — implement tasks)
|
|
92
|
-
4. verify build (critic — verify each task; tick only on confirmed artifacts)
|
|
93
|
-
↶ producer-critic loop, capped 3 attempts
|
|
94
|
-
5. gaps-remediate (fix verifier gaps, re-verify)
|
|
95
|
-
6. verify build (holistic second pass across whole plan)
|
|
96
|
-
7. challenge × 2 (parallel, distinct lenses, no sibling reads)
|
|
97
|
-
• bug-hunting • security
|
|
98
|
-
8. challenge-reconcile (merge findings, severity + verdict max-wins)
|
|
99
|
-
9. challenge-remediate (classify-gate: architectural → FAIL; else fix + test)
|
|
100
|
-
10. challenge-tests (edge-case tests for changed files)
|
|
101
|
-
11. run tests (local tier: lint + typecheck + unit + slop:delta + bkit check;
|
|
102
|
-
no integration / e2e / @live — those run in CI)
|
|
103
|
-
↳ on test failure → /bkit-debug (debug-failure-diagnose + remediate)
|
|
104
|
-
12. summary (tracker-facing + PR link)
|
|
105
|
-
→ PR opened; CI runs the full multi-tier scaffold (see "CI test scaffold" below)
|
|
106
|
-
|
|
107
|
-
/bkit-debug ─── side-rail, invoked on test/CI failure ────────────────────────
|
|
108
|
-
1. run tests (broader tier than build: lint + typecheck + unit
|
|
109
|
-
+ integration + e2e + optional @live canary —
|
|
110
|
-
reproduces against the deployed boundary)
|
|
111
|
-
2. fetch context (only if tests FAIL; CI: failed jobs/steps + error
|
|
112
|
-
annotations + failed-step logs; e2e test reports; local
|
|
113
|
-
test output; diff vs last-passing CI; runtime logs via
|
|
114
|
-
context-fetch blocks; tracker: related issues by error
|
|
115
|
-
signature → feeds diagnose below)
|
|
116
|
-
Normal mode (localisable failure):
|
|
117
|
-
3. diagnose (reads docs/knowledge.jsonl for prior failures;
|
|
118
|
-
Standard → Pivot → Final strategy escalation)
|
|
119
|
-
4. remediate (apply diagnosis fix)
|
|
120
|
-
5. re-run tests
|
|
121
|
-
6. summary
|
|
122
|
-
↳ if diagnose can't localise, or loop exhausts 3 strategies → Soak mode
|
|
123
|
-
Soak mode (non-localisable / runtime-only failure):
|
|
124
|
-
1. soak loop (one accumulating context per iteration:
|
|
125
|
-
instrument OR smallest evidence-backed fix;
|
|
126
|
-
strips all scaffolding before declaring a fix)
|
|
127
|
-
Escape hatch:
|
|
128
|
-
abort-handover (unrecoverable failure → human handover doc + stop)
|
|
129
|
-
|
|
130
|
-
/bkit-ship ─── output: squash-merged PR, hard stop before main ──────────────
|
|
131
|
-
1. conflict-resolve (only if rebase sentinels exist)
|
|
132
|
-
2. deferred-sweep (pre-merge completeness gate; FAIL blocks merge)
|
|
133
|
-
3. run tests (wait for CI on squash-merge SHA; bkit-tests-check
|
|
134
|
-
must be green — every planned tier ran and passed;
|
|
135
|
-
a planned bkit-tests-live-web failure reds it)
|
|
136
|
-
4. merge (orchestrator-only guarded git op)
|
|
137
|
-
↳ on post-merge failure → /bkit-debug (diagnose + remediate)
|
|
138
|
-
5. update-docs / summary (parallel)
|
|
139
|
-
6. prune skills + worktree cleanup + close (orchestrator-only)
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
### CI test scaffold (runs on every PR + push)
|
|
143
|
-
|
|
144
|
-
The template `bkit-ci.yml` (copied into `.bkit/templates/`, adopted and owned by the consumer) is static: two lanes run in parallel and the `bkit-tests-check` capstone joins them as the single branch-protection check. No planner. The capstone fails unless both lanes concluded `success`, and fails a unit lane that reports zero executed tests.
|
|
145
|
-
|
|
146
|
-
```
|
|
147
|
-
bkit-tests-static (typecheck, format, prose lint, slop, actionlint, bkit check)
|
|
148
|
-
bkit-tests-unit (unit tests; writes the executed-test count)
|
|
149
|
-
│
|
|
150
|
-
▼
|
|
151
|
-
bkit-tests-check (capstone: needs both lanes; sole required check)
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
Add the lanes the repo has (integration, E2E, migration, live) as further `needs:` of the capstone. Full tier rules: `docs/testing.md`.
|
|
155
|
-
|
|
156
|
-
Hard stops after Design, Plan, and Ship (production merge needs explicit human approval). Shared subagents cross-invoked: `bkit-debug-failure-diagnose` / `bkit-debug-failure-remediate` run inside Build and Ship failure paths as well as the Debug phase.
|
|
157
|
-
|
|
158
|
-
With `bkit-auto` enabled, the loop is unattended: Build opens a PR → CI runs → on green `bkit-auto` dispatches `/bkit-ship`, on red it dispatches `/bkit-debug`; debug re-pushes, CI re-runs, auto-routes again — no local session required until a human gate fires.
|
|
159
|
-
|
|
160
|
-
### Phase 1 — `/bkit-design`
|
|
161
|
-
|
|
162
|
-
Output: reviewed design (`docs/plans/{YYYYMM}/{FID}-design.md`). Hard stop for human approval.
|
|
163
|
-
|
|
164
|
-
<!-- prettier-ignore -->
|
|
165
|
-
| Subagent | Lens / focus | What it does |
|
|
166
|
-
| --- | --- | --- |
|
|
167
|
-
| `bkit-design-brainstorm-ideate-1` | Pragmatic | Independent design exploration. Opus, high effort. Forbidden from reading siblings (circular-reasoning guard). |
|
|
168
|
-
| `bkit-design-brainstorm-ideate-2` | Optimal-tradeoff | Same task, different lens. Cross-tier / native-pool diversity (Sonnet on Claude, Composer on Cursor vs Grok siblings). |
|
|
169
|
-
| `bkit-design-brainstorm-ideate-3` | Risk / pre-mortem | Same task, failure-mode lens. Opus, high effort. |
|
|
170
|
-
| `bkit-design-generate` | Synthesiser | Merges three brainstorms into one design. xhigh effort. Merges across lenses rather than collapsing to consensus. |
|
|
171
|
-
| `bkit-design-review-1` | Feasibility (web) | Adversarial review with live web search; checks ecosystem feasibility per capability. Opus, high. |
|
|
172
|
-
| `bkit-design-review-2` | Operability (cross-tier) | Parallel review on a different model tier: failure modes, observability, on-call ergonomics. |
|
|
173
|
-
| `bkit-design-spike` | Probe unknowns | Only when a review flags load-bearing unknowns: settles them with throwaway probe code, confined to the run's log folder. |
|
|
174
|
-
| `bkit-design-update` | Apply review | Folds both reviews (and the spike, if run) back into the design. |
|
|
175
|
-
| `bkit-design-organise` | Structure | Cleans and organises the final design doc. High effort. |
|
|
176
|
-
| `bkit-design-summary` | Summarise | Writes the tracker-facing summary (capped, scannable). |
|
|
177
|
-
|
|
178
|
-
### Phase 2 — `/bkit-plan`
|
|
179
|
-
|
|
180
|
-
Output: executable plan (`{FID}-plan.md`, split into `-plan-N.md` if too large). Consumes design. Hard stop.
|
|
181
|
-
|
|
182
|
-
<!-- prettier-ignore -->
|
|
183
|
-
| Subagent | Lens / focus | What it does |
|
|
184
|
-
| --- | --- | --- |
|
|
185
|
-
| `bkit-plan-generate` | Generate | Turns the design into a tasked plan. xhigh effort. |
|
|
186
|
-
| `bkit-plan-review-1` | Tightness + design-coverage | Read-only critique; flags vague or missing `Done when:` as CRITICAL. Opus, high. Parallel. |
|
|
187
|
-
| `bkit-plan-review-2` | Dependency-correctness | Same scope, dependency lens. Depth-sensitive — pinned to Opus even at medium effort. |
|
|
188
|
-
| `bkit-plan-review-3` | Regression-risk | Same scope, regression lens. Opus, high. Parallel. |
|
|
189
|
-
| `bkit-plan-update` | Apply review (merge) | Merges all three critiques, max-wins on CRITICAL findings. xhigh effort. |
|
|
190
|
-
| `bkit-plan-scope-check-1` | Internal-completeness | Mechanical scope audit — verifies template structure and criteria slots. Parallel. |
|
|
191
|
-
| `bkit-plan-scope-check-2` | Scope audit (cross-family) | Second scope audit in parallel for independent coverage. |
|
|
192
|
-
| `bkit-plan-update` | Apply scope fixes | Second merge pass folding scope-check findings in. |
|
|
193
|
-
| `bkit-plan-complexity-check` | Single → split classifier | Decides whether the plan is too big for one build and must be split. |
|
|
194
|
-
| `bkit-plan-complexity-split` | Splitter | If SPLIT: divides the plan into sequenced sub-plans. High effort. |
|
|
195
|
-
| `bkit-plan-summary` | Summarise | Tracker-facing summary. |
|
|
196
|
-
|
|
197
|
-
### Phase 3 — `/bkit-build`
|
|
198
|
-
|
|
199
|
-
Output: PR to `dev`. Heaviest phase — most steps verify rather than produce. CI takes over after PR.
|
|
200
|
-
|
|
201
|
-
<!-- prettier-ignore -->
|
|
202
|
-
| Subagent | Lens / focus | What it does |
|
|
203
|
-
| --- | --- | --- |
|
|
204
|
-
| `bkit-build-plan-current` | Plan freshness | Judges whether changes landed since the plan was written leave it executable; findings feed execute. |
|
|
205
|
-
| `bkit-build-install-skills` | Setup | Installs the skills the plan needs for this build. |
|
|
206
|
-
| `bkit-build-plan-execute` | Producer | Implements the plan tasks. L-tier; iterates edit → lint/typecheck/test → edit. |
|
|
207
|
-
| `bkit-build-plan-verify` | Critic | Verifies each task against the plan; ticks boxes only on confirmed artifacts. Producer-critic loop, capped at 3 attempts. |
|
|
208
|
-
| `bkit-build-plan-gaps-remediate` | Gap-fixer | Fills gaps the verifier found, then re-verifies. |
|
|
209
|
-
| `bkit-build-plan-verify` | Holistic critic | Second, whole-of-plan verification pass across everything built. |
|
|
210
|
-
| `bkit-build-challenge-1` | Bug-hunting | Adversarial review of the full diff. Opus, high. Forbidden from reading its sibling. Parallel. |
|
|
211
|
-
| `bkit-build-challenge-2` | Security | Same diff, security lens. Depth-sensitive (Opus on Claude). Parallel. |
|
|
212
|
-
| `bkit-build-challenge-reconcile` | Merge findings | Unifies both challenges. `Severity` and verdict max-wins; downgrades need explicit justification. xhigh. |
|
|
213
|
-
| `bkit-build-challenge-remediate` | Fixer (classify-gate) | Any architectural finding → FAIL (no silent fixes); else applies mechanical fixes and re-runs tests. |
|
|
214
|
-
| `bkit-build-challenge-tests` | Test author | Adds edge-case tests for changed files; runs the test suite. |
|
|
215
|
-
| `bkit-debug-failure-diagnose` | Diagnostician | (If tests fail) diagnoses with Standard / Pivot / Final strategy escalation. Shared with debug. xhigh. |
|
|
216
|
-
| `bkit-debug-failure-remediate` | Fixer | (If tests fail) applies the diagnosed fix. |
|
|
217
|
-
| `bkit-build-summary` | Summarise | Tracker-facing summary plus PR link. |
|
|
218
|
-
|
|
219
|
-
### Phase 4 — `/bkit-debug`
|
|
220
|
-
|
|
221
|
-
Output: remediated commit on feature branch. Two modes — normal (diagnose → remediate localisable failure) and soak (one accumulating-context instrument-or-fix loop for non-localisable / runtime-only failures). Normal escalates to soak when diagnose can't localise, or normal loop exhausts three strategies; observation logging (`[DEBUG-OBSERVE]`) inside soak, stripped before fix ships.
|
|
222
|
-
|
|
223
|
-
**Context fetch.** Per failed attempt, `/bkit-debug` runs each `context-fetch` bash block below `<!-- bkit:end -->` in `.agents/context.md` — failing CI logs, the diff since the last green run, end-to-end reports, runtime errors (Sentry, Vercel, Supabase, Stripe and more) and web search (Tavily) — writing one artifact per context and narrating `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` before fetching. Fail-soft and block-driven: bkit hardcodes no CI host, workflow filename or test framework, and a context with no block is never read as a clean result.
|
|
224
|
-
|
|
225
|
-
**Normal mode**
|
|
226
|
-
|
|
227
|
-
<!-- prettier-ignore -->
|
|
228
|
-
| Subagent | Lens / focus | What it does |
|
|
229
|
-
| --- | --- | --- |
|
|
230
|
-
| `bkit-debug-failure-diagnose` | Diagnostician | Reproduces and diagnoses. Accumulates per-attempt context; escalates Standard → Pivot → Final. xhigh. |
|
|
231
|
-
| `bkit-debug-failure-remediate` | Fixer | Applies whatever the strategy-aware diagnosis produced. L-tier with test loop. |
|
|
232
|
-
| `bkit-debug-summary` | Summarise | Tracker-facing summary. |
|
|
233
|
-
|
|
234
|
-
**Soak mode**
|
|
235
|
-
|
|
236
|
-
<!-- prettier-ignore -->
|
|
237
|
-
| Subagent | Lens / focus | What it does |
|
|
238
|
-
| --- | --- | --- |
|
|
239
|
-
| `bkit-debug-failure-soak` | Instrument-or-fix loop | One accumulating context against the failing boundary; each iteration either adds `[DEBUG-OBSERVE]` instrumentation or applies the smallest evidence-backed fix, stripping all scaffolding before declaring a fix. xhigh; bounded by `SOAK_ATTEMPT` (reset per soak entry). |
|
|
240
|
-
|
|
241
|
-
**Escape hatch**
|
|
242
|
-
|
|
243
|
-
<!-- prettier-ignore -->
|
|
244
|
-
| Subagent | Lens / focus | What it does |
|
|
245
|
-
| --- | --- | --- |
|
|
246
|
-
| `bkit-debug-abort-handover` | Handover | On unrecoverable failure: writes a human handover doc and stops cleanly. Shared across phases. |
|
|
247
|
-
|
|
248
|
-
### Phase 5 — `/bkit-ship`
|
|
249
|
-
|
|
250
|
-
Output: squash-merged PR, updated docs, pruned skills, torn-down worktree. Safety-critical — hard guards on production branch, explicit human approval to touch `main`.
|
|
251
|
-
|
|
252
|
-
<!-- prettier-ignore -->
|
|
253
|
-
| Subagent | Lens / focus | What it does |
|
|
254
|
-
| --- | --- | --- |
|
|
255
|
-
| `bkit-ship-conflict-resolve` | Conflict resolver | Resolves merge conflicts against the integration branch. Medium effort, with test gate. |
|
|
256
|
-
| `bkit-ship-deferred-sweep` | Pre-merge completeness gate | Builds the intended-delivery set from plan `Acceptance Scenario` sections + `Done when` lines; FAILs the merge if any unplanned gap (silent `TODO`, skipped test) is found. Declared deferrals resurfaced, never blocking. Gates only what the repo can prove — plan gate checkboxes, `Verification Plan` boxes and `Manual Verification` steps are build-phase process, never gated, and no plan precondition or merge condition blocks however a log or summary restates it. |
|
|
257
|
-
| `bkit-debug-failure-diagnose` | Diagnostician | (If post-merge checks fail) diagnoses the regression. Shared with debug. |
|
|
258
|
-
| `bkit-debug-failure-remediate` | Fixer | (If post-merge checks fail) applies the fix. |
|
|
259
|
-
| `bkit-ship-update-docs` | Docs | Updates knowledge / decisions / completed docs. High effort. Parallel with summary. |
|
|
260
|
-
| `bkit-ship-summary` | Summarise | Final tracker-facing summary. Parallel with docs. |
|
|
261
|
-
|
|
262
|
-
Orchestrator-only ship steps: regression guard, merge, switch-to-dev with `--ff-only` pull + divergence re-assert, skill pruning, worktree cleanup, close. Guarded git / tracker ops orchestrator performs directly, not subagents.
|
|
263
|
-
|
|
264
|
-
### Audits
|
|
265
|
-
|
|
266
|
-
No command and no phase label. One subagent, one template per run.
|
|
267
|
-
|
|
268
|
-
<!-- prettier-ignore -->
|
|
269
|
-
| Subagent | Lens / focus | What it does |
|
|
270
|
-
| --- | --- | --- |
|
|
271
|
-
| `bkit-audit-generate` | One template | Runs `docs/templates/bkit-audit-*.md`. Writes `docs/audits/{YYYYMM}/{slug}.md` (`{slug}` = basename without `bkit-audit-`; same slug already in that month → `{slug}-{TIMESTAMP}.md`). Report is the template through `bkit:end`. Refines that template's `Project Instructions` below `bkit:end`. |
|
|
272
|
-
|
|
273
|
-
`/bkit-plan` reads a design doc, one or more reports, or both. The invocation names which findings are in scope. The rest of each report stays context.
|
|
274
|
-
|
|
275
|
-
All 35 templates, by area. Template file = `docs/templates/bkit-audit-{template}.md`.
|
|
276
|
-
|
|
277
|
-
<!-- prettier-ignore -->
|
|
278
|
-
| Area | Audit | Template | What it finds |
|
|
279
|
-
| --- | --- | --- | --- |
|
|
280
|
-
| **Security and privacy** | Security | `security` | Holes in sign-in, permissions, secrets and input checks, plus documented protections that never run. |
|
|
281
|
-
| | Red team | `red-team` | Attacks a test copy of the app, never production, one hostile request at a time. Keeps each request and response, then cleans up. |
|
|
282
|
-
| | Privacy | `privacy` | Where personal data goes and how long it stays, whether deleting an account removes the person, whether the privacy policy matches the code. |
|
|
283
|
-
| **Code quality** | Architecture | `architecture` | Code that breaks the intended layers: server code reaching the client, modules tied together with no visible import. |
|
|
284
|
-
| | Duplication | `duplication` | One behaviour built more than once: copied rules, competing mechanisms, restated types, merges that should not have happened. |
|
|
285
|
-
| | Dead code | `dead-code` | Code, settings, routes, events, tables and assets that look live and never run. |
|
|
286
|
-
| | Slop | `slop` | Every switched-off check: disabled lint rules, casts that hide type errors, skipped tests, config opt-outs. |
|
|
287
|
-
| | Documentation | `documentation` | Docs that disagree with the code, links that land nowhere, facts agents rely on that nobody wrote down. |
|
|
288
|
-
| | Dependencies | `dependencies` | Pending dependency updates merged as one verified batch; security advisories, licences, end-of-life packages, supply-chain settings. |
|
|
289
|
-
| **Tests and CI** | Testing | `testing` | Tests that can't fail, don't run, or skip what the product must and must never do. |
|
|
290
|
-
| | Coverage | `coverage` | How much code the tests reach, against the minimum CI enforces, and the next minimum to set. |
|
|
291
|
-
| | Flaky tests | `flakes` | Tests that pass only on retry or fail on one platform, and the change that makes each one reliable. |
|
|
292
|
-
| | Gates | `gates` | Problems audits keep finding by hand that an automatic check could block, and the order to add those checks. |
|
|
293
|
-
| | Annotations | `annotations` | Warnings buried in green CI runs: silent failures, deprecations with a deadline, ignored lint warnings. |
|
|
294
|
-
| | CI performance | `ci-performance` | The lane that makes CI slow or expensive, and what each change would save. |
|
|
295
|
-
| **Running in production** | Reliability | `reliability` | What breaks when a service is slow, down or answers twice: missing timeouts, unsafe retries, races, failures no alert reports. |
|
|
296
|
-
| | Database | `database` | Who can read and write what, migrations, data integrity, capacity, and whether a restore works. |
|
|
297
|
-
| | Logs | `logs` | Error-tracker issues and logs sorted into real bugs, noise at the wrong level, and failures that never got reported. |
|
|
298
|
-
| | App performance | `app-performance` | Web, phone and server speed, measured against published targets and your own budgets. |
|
|
299
|
-
| | Config | `config` | Settings outside the code that disagree across environments, dashboards, repo and docs; anything with an expiry date. |
|
|
300
|
-
| | Cost | `cost` | Vendor plans that don't fit your usage, what drives each bill, whether a spike shows up before the invoice. |
|
|
301
|
-
| **Users and reach** | Accessibility | `accessibility` | What automated accessibility checks miss against WCAG 2.2 AA, plus the manual checks nothing automates. |
|
|
302
|
-
| | Usability | `usability` | Screens that don't match their design or the other platforms, and main flows a person can't finish. |
|
|
303
|
-
| | Analytics | `analytics` | Product events that don't fire, differ between web and phone, fire before consent, or carry personal data. |
|
|
304
|
-
| | AI search & SEO | `aio-seo` | Whether search engines and AI answer engines can find, read and describe your public pages. |
|
|
305
|
-
| | App Store | `app-store` | What keeps an iOS or Android app listed: deadlines, privacy declarations, permissions, signing, review readiness, crashes, ratings. |
|
|
306
|
-
| **AI features** | LLM | `llm` | What each AI model call can make happen, and what stops it when the input is hostile: prompts, tool limits, output checks, evals. |
|
|
307
|
-
| | Models | `models` | Whether each AI call uses the best current model for the job, whether models and fallbacks still exist, whether one list holds them all. |
|
|
308
|
-
| | Prompts | `prompts` | Product prompts that are unclear, badly structured, or off the model maker's current guide. |
|
|
309
|
-
| **Project upkeep** | Issues | `issues` | Size and priority for every open issue, by rules a later run applies the same way; board, parent, milestone and blocking links. |
|
|
310
|
-
| | Deferrals | `deferrals` | Postponed work sorted into done, replaced, tracked, parked, or in scope and never finished. |
|
|
311
|
-
| | Failures | `failures` | Known bugs sorted into still reachable, already fixed, misdescribed, unconfirmed, or a repeat of an earlier one. |
|
|
312
|
-
| | Repo | `repo` | Leftovers and layout: stale worktrees, branches and stashes, ignored files, files in the wrong place. |
|
|
313
|
-
| | Agents | `agents` | Each AI tool's setup: which instructions load, permissions, hooks, tool servers, model choices, untrusted input each agent reads. |
|
|
314
|
-
| | Adoption | `adoption` | Whether every file bkit installed is used and used correctly: install current, docs filled in, audits run on schedule, each template adopted or declined with a reason. |
|
|
315
|
-
|
|
316
|
-
Agent-facing scope per template: `.bkit/prompts.md` § Audit (Ad-hoc).
|
|
317
|
-
|
|
318
|
-
---
|
|
319
|
-
|
|
320
|
-
## Part 2 — Comparison to agentic design patterns
|
|
35
|
+
<a id="frameworks"></a>
|
|
321
36
|
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
22 patterns assessed: 13 fully implemented, 7 partial (scoped to code-shipping), 2 intentionally N/A. No foundational patterns missing.
|
|
325
|
-
|
|
326
|
-
<!-- prettier-ignore -->
|
|
327
|
-
| Pattern (Gulli) | bkit status | Where / note |
|
|
328
|
-
| --- | --- | --- |
|
|
329
|
-
| Prompt Chaining | Already does | Every workflow is prompt chaining at slash-command granularity. |
|
|
330
|
-
| Routing | Already does | `Verdict` routing (PASS/CONCERNS/FAIL), strategy escalation, CI-router dispatch to ship vs debug. |
|
|
331
|
-
| Parallelization | Already does | Parallel pairs and triplets, with a tighter constraint than the book: no sibling reads, plus cross-model pairing on design brainstorm / design review / plan scope-check. |
|
|
332
|
-
| Reflection (producer-critic) | Already does | Build execute → verify → remediate loop; plan and design generate → review → update. |
|
|
333
|
-
| Tool Use | Already does | Per-role minimum-capability tool allowlists — stricter than the book's additive model. |
|
|
334
|
-
| Planning | Already does | `/bkit-plan` is a first-class artifact with a template and durable checkbox state. |
|
|
335
|
-
| Multi-Agent Collaboration | Already does | 48 subagents, orchestrator-as-coordinator; subagents are leaves (no nested orchestration). |
|
|
336
|
-
| Model Context Protocol (MCP) | Already does | Tracker MCP held at the workflow layer only — cleaner separation than the book's examples. |
|
|
337
|
-
| Exception Handling & Recovery | Already does | Universal failure path, bounded retries (3), 3600s timeouts, runaway-turn caps, human handover. |
|
|
338
|
-
| Human-in-the-Loop | Already does | Mandatory hard stops after design / plan / ship; "recommend, do not decide." |
|
|
339
|
-
| Resource-Aware Optimization | Already does | Effort-to-model tiering with explicit per-agent pins. |
|
|
340
|
-
| Context Engineering | Already does | Phase doc-matrix, lazy-load, output caps, stubbed-output pattern; consumer `context-fetch` blocks add CI, diff, e2e, runtime and web signal in debug. |
|
|
341
|
-
| Memory Management | Partial | Filesystem and grep episodic memory (`status.jsonl`, knowledge / decisions). No vector retrieval, by scale choice. |
|
|
342
|
-
| Learning & Adaptation | Partial | `friction.jsonl` drives human-reviewed prompt edits; entries carry confidence, scope, and last-confirmed fields. No auto prompt-tuning — deliberate, to keep humans in the loop. |
|
|
343
|
-
| Goal Setting & Monitoring | Already does | Issue = goal, phase labels = state, verdicts = criteria. Per-task `Done when:` in the plan template; verifier ticks only on confirmed artifacts; deferred-sweep FAILs merge on any unplanned gap; `stats.jsonl` tracks every run. |
|
|
344
|
-
| Knowledge Retrieval (RAG) | Partial | Deterministic doc-matrix retrieval plus web search in design review. No embedding RAG (Grep wins at repo scale). |
|
|
345
|
-
| Reasoning Techniques | Partial | Extended thinking (CoT) plus parallel-pair-reconcile (a form of self-consistency). No formal ToT or ReAct trace. |
|
|
346
|
-
| Guardrails / Safety | Partial | Tool sandbox, destructive-git bans, locks, verdict checks, and an advisory edit-investigation plus gate-config hook (GateGuard), and an advisory repeat-read hook (ReadGuard). `bkit steps finish` validates each step's verdict and artifacts structurally. No content-level output validators (e.g. safety classifiers). |
|
|
347
|
-
| Evaluation & Monitoring | Partial | `friction` / `knowledge` logs, CI gates, and a catalog-parity drift check. No automated regression-fixture eval harness yet. |
|
|
348
|
-
| Exploration & Discovery | Partial | Divergent brainstorm triplet plus feasibility search. No temperature-spread or vote-of-K. |
|
|
349
|
-
| Inter-Agent Communication (A2A) | N/A by design | Agents communicate only via filesystem artifacts — deliberate, to preserve leaf-only and resume guarantees. |
|
|
350
|
-
| Prioritization | N/A by design | Features run in parallel, one worktree each; per-feature `.lock` blocks a second run of the same feature, repo-global `.dev.lock` serialises only `dev` writes. Ordering across features = human / tracker. |
|
|
351
|
-
|
|
352
|
-
### Where bkit goes beyond the catalogue
|
|
353
|
-
|
|
354
|
-
- **Producer-critic with circular-reasoning guard.** Sibling reviewers cannot read each other's output. Book permits self-reflection.
|
|
355
|
-
- **Cross-model diversity where breadth beats depth.** Design brainstorm, design review, plan scope-check groups pair Opus + Sonnet (Grok + Composer on Cursor) → two reasoners review same work. Depth-sensitive lenses (plan review, build challenge) stay on top tier.
|
|
356
|
-
- **Resume-from-state as single source of truth.** `status.jsonl` makes every run inspectable and restartable; book treats this only obliquely under memory.
|
|
357
|
-
- **Human-in-the-loop as non-negotiable.** Hard stops after design / plan / ship; book treats HITL as one option.
|
|
358
|
-
- **Fail-soft external context in debug.** Provider-agnostic `context-fetch` blocks (CI logs, diff, e2e, runtime, web) feed `/bkit-debug`; each self-skips to a narrated `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` state, so a context with no block is never read as a clean result.
|
|
359
|
-
- **Explicit per-agent model pins.** Immune to session-default drift.
|
|
360
|
-
- **Provider- and host-portable execution.** Per-agent pins → `bkit install --codex` / `--antigravity` / `--opencode=<provider>` add Codex, Google Antigravity and opencode hosts alongside Claude/Cursor — harness unchanged; inference backend moves. Same five-phase gated parallel pipeline on four BYO-key providers (OpenRouter, Ollama, opencode Zen + Go gateways) plus Google via Antigravity. Curated per-agent pins; models mirror Claude tier by default, CoT reasoners swapped for convergent-reasoning agents (debug/risk). See `.bkit/providers.md` § Hosts + Providers.
|
|
361
|
-
- **Cross-host/provider continuity.** State in `status.jsonl`, plan/design docs under `docs/plans/`, tracker issue — not vendor session. Every host renders from same `.bkit/` source → phase or resumed run moves across IDE/provider mid-feature with identical gates, hooks, per-agent pins: exhaust Claude weekly limit or free-tier quota → continue on another host, no re-setup. Single-vendor frameworks tie run to starting session.
|
|
362
|
-
|
|
363
|
-
### Known gaps, scoped as opportunities
|
|
364
|
-
|
|
365
|
-
Most partials = deliberate scope. Two remain: automated eval harness with regression fixtures for closed friction items; optional self-consistency vote (quorum-of-N) for high-stakes reviews. Neither requires leaf-agent architecture change.
|
|
366
|
-
|
|
367
|
-
---
|
|
368
|
-
|
|
369
|
-
## Part 3 — Compared with other AI development frameworks
|
|
37
|
+
## Compared with other AI development frameworks
|
|
370
38
|
|
|
371
39
|
As of October 2026. A cross-section of 10: the closest process frameworks, the two main spec toolkits, the largest skills pack, an autonomous agent platform and an agentic IDE. Each column read from the project's own repo and docs. ✅ yes · ◐ partly · — no · ? not documented.
|
|
372
40
|
|
|
@@ -444,4 +112,59 @@ bkit's biggest difference from the field is how tightly its agents and its check
|
|
|
444
112
|
|
|
445
113
|
---
|
|
446
114
|
|
|
447
|
-
|
|
115
|
+
<a id="patterns"></a>
|
|
116
|
+
|
|
117
|
+
## Compared with agentic design patterns
|
|
118
|
+
|
|
119
|
+
Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Building Intelligent Systems_. Practitioner catalogue of agentic-AI patterns. Table maps all 21 named patterns + Context Engineering against bkit.
|
|
120
|
+
|
|
121
|
+
22 patterns assessed: 13 fully implemented, 7 partial (scoped to code-shipping), 2 intentionally N/A. No foundational patterns missing.
|
|
122
|
+
|
|
123
|
+
<!-- prettier-ignore -->
|
|
124
|
+
| Pattern (Gulli) | bkit status | Where / note |
|
|
125
|
+
| --- | --- | --- |
|
|
126
|
+
| Prompt Chaining | Already does | Every workflow is prompt chaining at slash-command granularity. |
|
|
127
|
+
| Routing | Already does | `Verdict` routing (PASS/CONCERNS/FAIL), strategy escalation, CI-router dispatch to ship vs debug. |
|
|
128
|
+
| Parallelization | Already does | Parallel pairs and triplets, with a tighter constraint than the book: no sibling reads, plus cross-model pairing on design brainstorm / design review / plan scope-check. |
|
|
129
|
+
| Reflection (producer-critic) | Already does | Build execute → verify → remediate loop; plan and design generate → review → update. |
|
|
130
|
+
| Tool Use | Already does | Per-role minimum-capability tool allowlists — stricter than the book's additive model. |
|
|
131
|
+
| Planning | Already does | `/bkit-plan` is a first-class artifact with a template and durable checkbox state. |
|
|
132
|
+
| Multi-Agent Collaboration | Already does | 49 subagents, orchestrator-as-coordinator; subagents are leaves (no nested orchestration). |
|
|
133
|
+
| Model Context Protocol (MCP) | Already does | Tracker MCP held at the workflow layer only — cleaner separation than the book's examples. |
|
|
134
|
+
| Exception Handling & Recovery | Already does | Universal failure path, bounded retries (3), 3600s timeouts, runaway-turn caps, human handover. |
|
|
135
|
+
| Human-in-the-Loop | Already does | Mandatory hard stops after design / plan / ship; "recommend, do not decide." |
|
|
136
|
+
| Resource-Aware Optimization | Already does | Effort-to-model tiering with explicit per-agent pins. |
|
|
137
|
+
| Context Engineering | Already does | Phase doc-matrix, lazy-load, output caps, stubbed-output pattern; consumer `context-fetch` blocks add CI, diff, e2e, runtime and web signal in debug. |
|
|
138
|
+
| Memory Management | Partial | Filesystem and grep episodic memory (`status.jsonl`, knowledge / decisions). No vector retrieval, by scale choice. |
|
|
139
|
+
| Learning & Adaptation | Partial | `friction.jsonl` drives human-reviewed prompt edits; entries carry confidence, scope, and last-confirmed fields. No auto prompt-tuning — deliberate, to keep humans in the loop. |
|
|
140
|
+
| Goal Setting & Monitoring | Already does | Issue = goal, phase labels = state, verdicts = criteria. Per-task `Done when:` in the plan template; verifier ticks only on confirmed artifacts; deferred-sweep FAILs merge on any unplanned gap; `stats.jsonl` tracks every run. |
|
|
141
|
+
| Knowledge Retrieval (RAG) | Partial | Deterministic doc-matrix retrieval plus web search in design review. No embedding RAG (Grep wins at repo scale). |
|
|
142
|
+
| Reasoning Techniques | Partial | Extended thinking (CoT) plus parallel-pair-reconcile (a form of self-consistency). No formal ToT or ReAct trace. |
|
|
143
|
+
| Guardrails / Safety | Partial | Tool sandbox, destructive-git bans, locks, verdict checks, and an advisory edit-investigation plus gate-config hook (GateGuard), and an advisory repeat-read hook (ReadGuard). `bkit steps finish` validates each step's verdict and artifacts structurally. No content-level output validators (e.g. safety classifiers). |
|
|
144
|
+
| Evaluation & Monitoring | Partial | `friction` / `knowledge` logs, CI gates, and a catalog-parity drift check. No automated regression-fixture eval harness yet. |
|
|
145
|
+
| Exploration & Discovery | Partial | Divergent brainstorm triplet plus feasibility search. No temperature-spread or vote-of-K. |
|
|
146
|
+
| Inter-Agent Communication (A2A) | N/A by design | Agents communicate only via filesystem artifacts — deliberate, to preserve leaf-only and resume guarantees. |
|
|
147
|
+
| Prioritization | N/A by design | Features run in parallel, one worktree each; per-feature `.lock` blocks a second run of the same feature; every `dev` write is built in a throwaway `origin/dev` checkout and rebuilt when `dev` moved, so features never wait on each other. Ordering across features = human / tracker. |
|
|
148
|
+
|
|
149
|
+
<a id="beyond-the-book"></a>
|
|
150
|
+
|
|
151
|
+
### Where bkit goes beyond the catalogue
|
|
152
|
+
|
|
153
|
+
- **Producer-critic with circular-reasoning guard.** Sibling reviewers cannot read each other's output. Book permits self-reflection.
|
|
154
|
+
- **Cross-model diversity where breadth beats depth.** Design brainstorm, design review, plan scope-check groups pair Opus + Sonnet (Grok + Composer on Cursor) → two reasoners review same work. Depth-sensitive lenses (plan review, build challenge) stay on top tier.
|
|
155
|
+
- **Resume-from-state as single source of truth.** `status.jsonl` makes every run inspectable and restartable; book treats this only obliquely under memory.
|
|
156
|
+
- **Human-in-the-loop as non-negotiable.** Hard stops after design / plan / ship; book treats HITL as one option.
|
|
157
|
+
- **Fail-soft external context in debug.** Provider-agnostic `context-fetch` blocks (CI logs, diff, e2e, runtime, web) feed `/bkit-debug`; each self-skips to a narrated `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` state, so a context with no block is never read as a clean result.
|
|
158
|
+
- **Explicit per-agent model pins.** Immune to session-default drift.
|
|
159
|
+
- **Provider- and host-portable execution.** Per-agent pins → `bkit install --codex` / `--antigravity` / `--opencode=<provider>` add Codex, Google Antigravity and opencode hosts alongside Claude/Cursor — harness unchanged; inference backend moves. Same five-phase gated parallel pipeline on four BYO-key providers (OpenRouter, Ollama, opencode Zen + Go gateways) plus Google via Antigravity. Curated per-agent pins; models mirror Claude tier by default, CoT reasoners swapped for convergent-reasoning agents (debug/risk). See `.bkit/providers.md` § Hosts + Providers.
|
|
160
|
+
- **Cross-host/provider continuity.** State in `status.jsonl`, plan/design docs under `docs/plans/`, tracker issue — not vendor session. Every host renders from same `.bkit/` source → phase or resumed run moves across IDE/provider mid-feature with identical gates, hooks, per-agent pins: exhaust Claude weekly limit or free-tier quota → continue on another host, no re-setup. Single-vendor frameworks tie run to starting session.
|
|
161
|
+
|
|
162
|
+
<a id="known-gaps"></a>
|
|
163
|
+
|
|
164
|
+
### Known gaps, scoped as opportunities
|
|
165
|
+
|
|
166
|
+
Most partials = deliberate scope. Two remain: automated eval harness with regression fixtures for closed friction items; optional self-consistency vote (quorum-of-N) for high-stakes reviews. Neither requires leaf-agent architecture change.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
Sources: each compared project's own repo and docs; the Gulli differential review of _Agentic Design Patterns_; bkit workflow and prompt definitions (`.bkit/core/workflows/*`, `.bkit/core/.bkit/prompts.md`).
|
|
@@ -88,8 +88,9 @@ bkit install --antigravity # Google Antigravity host + core
|
|
|
88
88
|
bkit install --opencode=opencode-go # additive opencode host (opencode-native gateway) + core
|
|
89
89
|
# opencode provider: openrouter | ollama | opencode-zen | opencode-go
|
|
90
90
|
|
|
91
|
-
# A bare install errors — name at least one module:
|
|
91
|
+
# A bare install errors — name at least one module, or a tracker:
|
|
92
92
|
bkit install # ✗ error: requires ≥1 module flag
|
|
93
|
+
bkit install --tracker=github # tracker alone: re-renders every installed host
|
|
93
94
|
|
|
94
95
|
# Ongoing sync — re-render everything installed at the CURRENT version (offline)
|
|
95
96
|
bkit upgrade
|
|
@@ -114,7 +115,7 @@ Install and upgrade create two **relative symlinks** into the installed package,
|
|
|
114
115
|
- A real directory at either path is never clobbered (advisory `payload-link-real-dir`) — remove it yourself and re-run install to get the link. A platform that refuses symlinks (Windows without Developer Mode) falls back to a junction, then to advisory `payload-link-failed` — never a failure.
|
|
115
116
|
- `bkit uninstall` removes the links (symlinks only — consumer content stays).
|
|
116
117
|
|
|
117
|
-
> **⚠️ Moving bkit versions: use `bkit upgrade --latest` (or `--to=<version>`).** Bumps `@cbartens/bkit` **and** resyncs `.agents/` payload + `.bkit/version` pin in one atomic step — two can never drift apart. Bare `pnpm add @cbartens/bkit` (or Renovate/Dependabot bump) only refreshes `package.json` + lockfile — does **not** resync; skipping resync reds CI on `bkit check` drift gate. If you bump package separately, run `bkit upgrade` afterward and commit resync alongside version bump in same PR.
|
|
118
|
+
> **⚠️ Moving bkit versions: use `bkit upgrade --latest` (or `--to=<version>`).** Bumps `@cbartens/bkit` **and** resyncs `.agents/` payload + `.bkit/version` pin in one atomic step — two can never drift apart. Bare `pnpm add @cbartens/bkit` (or Renovate/Dependabot bump) only refreshes `package.json` + lockfile — does **not** resync; skipping resync reds CI on `bkit check` drift gate. If you bump package separately, run `bkit upgrade` afterward and commit resync alongside version bump in same PR. A target equal to the installed version re-renders in place, unless `package.json` declares `@cbartens/bkit` by a non-registry spec (`file:` tarball, `link:`, `workspace:`, `npm:` alias, git, URL, path) — then it still runs `pnpm add` to swap in the published package.
|
|
118
119
|
|
|
119
120
|
### Local env setup
|
|
120
121
|
|
|
@@ -240,7 +241,7 @@ After writes, bkit re-runs credential and environment checks — some only accur
|
|
|
240
241
|
|
|
241
242
|
Phase 1 and Phase 3 findings merged and deduplicated by `id` (Phase 3 wins on conflict — re-detection more accurate post-write). Zero findings → no banner.
|
|
242
243
|
|
|
243
|
-
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only) — same advisory set as `bkit install` minus writes. Changes no managed file (regenerates `.bkit/advisories.md` artifact) and **exits 1 when any managed-file write would occur** in installed module — Tier-2 JSON deep-containment or markered-block drift, whole-file byte-equal mismatch, **host agent/command mirror content drift** (would-write / orphan delete), or when any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carries a stale managed-version marker (`bkit-managed-stale`). Gate covers the **installed** module set ({core, claude, cursor, codex, antigravity} plus **opencode**, each detected by sentinel files: a host's `agents/` dir; antigravity any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host; `bkit status` uses the same detection). A missing `bkit:gate:*` name counts as a write. antigravity gated: `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and root `GEMINI.md`. opencode gated: `.opencode/opencode.json` (provider block + the recorded tracker's `mcp` entry + permission sandbox; another tracker's
|
|
244
|
+
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only) — same advisory set as `bkit install` minus writes. Changes no managed file (regenerates `.bkit/advisories.md` artifact) and **exits 1 when any managed-file write would occur** in installed module — Tier-2 JSON deep-containment or markered-block drift, whole-file byte-equal mismatch, **host agent/command mirror content drift** (would-write / orphan delete), or when any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carries a stale managed-version marker (`bkit-managed-stale`). Gate covers the **installed** module set ({core, claude, cursor, codex, antigravity} plus **opencode**, each detected by sentinel files: a host's `agents/` dir; antigravity any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host; `bkit status` uses the same detection). A missing `bkit:gate:*` name counts as a write. antigravity gated: `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and root `GEMINI.md`. opencode gated: `.opencode/opencode.json` (provider block + the recorded tracker's `mcp` entry + permission sandbox; another tracker's `mcp` entry the consumer edited, kept by a tracker switch, is not drift — `mcp-extra-server-linear--opencode-opencode-json` advises removing it) and the `bkit-gateguard.js` / `bkit-readguard.js` plugins drift fail `check` — render inputs fall back to installed provider (`package.json` `bkit.opencodeProvider`, authoritative for `opencode-zen` / `opencode-go`; all installed providers tracked in `bkit.opencodeProviders: string[]`) and recorded tracker, so clean install across providers checks green (no false drift). Remaining **opt-in** module (cloud) is not drift-gated. A missing bkit-owned hook file also fails `check`, one line per file naming it and the `bkit install` flag that restores it: the hook files of every installed host (`.claude/hooks/*`, `.cursor/hooks/*`, `.codex/hooks/*`, `.agents/plugins/bkit/hooks/*`, `.opencode/plugin/bkit-gateguard.js`, `.opencode/plugin/bkit-readguard.js`) — the hook commands skip a missing file (`test -f … || true`), so without this the guard would be off with no signal. Updater configs are not bkit files, so `bkit check` does not report them. Phase 3 stays read-only through read-only detector paths, not by being skipped.
|
|
244
245
|
|
|
245
246
|
**`bkit upgrade`** (not `--dry-run`) ends with the same read-only pass as `bkit check`: prints the checklist and rewrites `.bkit/advisories.md` (`Mode: upgrade`). Drift and blockers it finds are reported only — upgrade's exit code is unchanged.
|
|
246
247
|
|
|
@@ -296,6 +297,10 @@ Two capabilities **opt-in** — never wired by plain host/tooling install. Defau
|
|
|
296
297
|
|
|
297
298
|
Use one. `bkit.depUpdater: "none"` skips the install-time absence advisory. Setup: `docs/deployments.md` § Dependency updaters.
|
|
298
299
|
|
|
300
|
+
**Security scan.** Updater only offers fixes once a fixed release exists. To fail CI on known-vulnerable packages, risky config or committed secrets, copy `.bkit/templates/.github/workflows/bkit-trivy.yml` and own it. No advisory; `bkit tips` suggests it. Setup: `.bkit/templates.md` § Trivy.
|
|
301
|
+
|
|
302
|
+
**Test lint.** JS / TS repos, to fail `lint` on a test that cannot fail (no assertion, branch inside a test, unawaited promise): copy and own `.bkit/templates/.oxlintrc.json`, add `oxlint` + `oxlint-tsgolint`, set `lint` to `oxlint -c .oxlintrc.json --type-aware --deny-warnings`. No advisory; `bkit tips` suggests it. Setup: `.bkit/templates.md` § Oxlint.
|
|
303
|
+
|
|
299
304
|
**All templates.** Copy and own, never installed. Catalog and install steps: `.bkit/templates.md`.
|
|
300
305
|
|
|
301
306
|
**Why opt-in, not part of a default install:**
|
|
@@ -306,7 +311,7 @@ Use one. `bkit.depUpdater: "none"` skips the install-time absence advisory. Setu
|
|
|
306
311
|
**How to decide:**
|
|
307
312
|
|
|
308
313
|
1. Run `bkit install --claude --cursor` (or whichever modules you want). Post-install banner lists `tracker-setup-none`, `dep-updater-absent`, `cloud-router-none` if undecided.
|
|
309
|
-
2. Pick tracker: `bkit install --tracker=github` (or `linear`). Persisted to `bkit.issueTracker`; future installs preserve (switching free).
|
|
314
|
+
2. Pick tracker: `bkit install --tracker=github` (or `linear`). Needs no host flag; re-renders every installed host. Persisted to `bkit.issueTracker`; future installs preserve (switching free).
|
|
310
315
|
3. Copy one updater example (table above). Land Renovate config on the default branch before installing the App.
|
|
311
316
|
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. Persisted to `bkit.cloudAgents`; install prints secrets + permissions + dashboard checklist (`bkit-auto-setup`). Shipped `bkit-cloud.yml` carries claude job (`ANTHROPIC_API_KEY` repo secret) and opencode job (`OPENCODE_PROVIDER_KEY`), each runtime-gated.
|
|
312
317
|
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.issueTracker` / `bkit.depUpdater` / `bkit.cloudAgents`). Advisory stays quiet.
|
|
@@ -317,23 +322,25 @@ Tracker and cloud agents reverse by re-running install with the other flag. Upda
|
|
|
317
322
|
|
|
318
323
|
## Setup tips
|
|
319
324
|
|
|
320
|
-
`bkit tips` prints what the repo has not set up yet — tracker, tokens, templates, cost settings — most useful first, each with a plain-English line and a sentence to ask your agent. Each workflow runs it with its own name at its close and appends the
|
|
325
|
+
`bkit tips` prints what the repo has not set up yet — tracker, tokens, templates, cost settings — most useful first, each with a plain-English line and a sentence to ask your agent. Each workflow runs it with its own name at its close and appends what it prints under `## bkit Tips`; `@bkit-audit-generate` does the same with `audit`, and the roadmap and `.jsonl` ledger updaters with `utility`. `@bkit-utility-update-documentation` has no Bash, so prints no tip.
|
|
321
326
|
|
|
322
327
|
```bash
|
|
323
328
|
bkit tips # top three
|
|
324
329
|
bkit tips --workflow=debug # the one tip that matters most in /bkit-debug
|
|
330
|
+
bkit tips --workflow=audit # the one tip that matters most at an audit's close
|
|
325
331
|
bkit tips --all # every firing tip
|
|
326
332
|
```
|
|
327
333
|
|
|
328
334
|
<!-- prettier-ignore -->
|
|
329
335
|
| Rule | Behaviour |
|
|
330
336
|
| --- | --- |
|
|
331
|
-
| Order | One fixed priority list. `--workflow=<name>` moves the tips that matter in that workflow to the front: tracker, GitHub token, `.bkit/.env` and direnv matter in every workflow, so they lead until fixed; then e.g. context-fetch for debug, Husky / slop-scan for build, CI workflow / cloud for ship
|
|
337
|
+
| Order | One fixed priority list. `--workflow=<name>` moves the tips that matter in that workflow to the front: tracker, GitHub token, `.bkit/.env` and direnv matter in every workflow, so they lead until fixed; then e.g. context-fetch for debug, Husky / slop-scan / Oxlint for build, CI workflow / cloud for ship, Serena / CI workflow / graphify / updater / Trivy for `audit`, Serena for `utility`. |
|
|
332
338
|
| Detection | Local only — files, settings, environment; no network. A tip clears once its local half exists; dashboard steps live in the tip text. |
|
|
333
339
|
| Reuse | A tip for a gap an advisory already detects calls that advisory's detector — tip and advisory never disagree. |
|
|
334
340
|
| Artifact | `bkit install` / `check` / `upgrade` / `doctor` list every firing tip, with its id, in `.bkit/advisories.md` § Setup tips and the console banner: line, why, caution, ask-your-agent sentence, agent steps. |
|
|
335
|
-
|
|
|
336
|
-
|
|
|
341
|
+
| Star line | `Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!` (markdown link) closes bare `bkit tips`, after the tips and outside the cap; in a phase workflow it follows the tip, and the silence line follows it. Never under `--workflow=audit` / `utility` (those agents often run back to back), in `.bkit/advisories.md` or the console banner. |
|
|
342
|
+
| Silence | Root `package.json` `bkit.ignoreAdvisories`: a tip id (a workflow's `## bkit Tips` ends with `` Want to silence these tips? Ask your agent to "add `<id>` and `bkit-star` to `bkit.ignoreAdvisories` in package.json". ``, naming what it showed), or an advisory id the tip reuses, silences the tip and those advisories together; both show in the suppressed block. `bkit-star` (or the older `star`) silences the star line. |
|
|
343
|
+
| Exit | Always 0. Prints nothing when no tip fires and no star line shows. |
|
|
337
344
|
|
|
338
345
|
## Doctor
|
|
339
346
|
|
|
@@ -388,7 +395,7 @@ bkit uninstall --nuke --yes
|
|
|
388
395
|
| --- | --- |
|
|
389
396
|
| `fully-managed` | Always deleted (bkit owns 100% of the file). |
|
|
390
397
|
| `markered-text` | bkit block stripped; consumer content above/below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
|
|
391
|
-
| `byte-equal-text` | Deleted only if current hash matches the hash `.bkit/version` recorded when bkit last wrote it (`canonicalHashes`). Consumer modifications → preserved. `canonicalHashes` is internal state `bkit check` does not verify: a hand-edited or corrupted entry makes uninstall keep that file as consumer-modified (`--force` deletes it anyway) and upgrade's whole-file diff report a conflict instead of updating it. |
|
|
398
|
+
| `byte-equal-text` | Deleted only if current hash matches the hash `.bkit/version` recorded when bkit last wrote it (`canonicalHashes`). Consumer modifications → preserved. `canonicalHashes` is internal state `bkit check` does not verify: a hand-edited or corrupted entry makes uninstall keep that file as consumer-modified (`--force` deletes it anyway) and upgrade's whole-file diff report a conflict instead of updating it. Rendered `.bkit/*.md` skip that diff: upgrade always re-renders them, and `bkit check` flags a hand edit. |
|
|
392
399
|
| `json` | bkit's keys stripped; consumer keys preserved. `.mcp.json` / `.cursor/mcp.json`: only bkit's tracker entry is removed, and only while it still equals the template. `.opencode/opencode.json`: every `mcp` tracker entry (`github`, `linear`) and every `provider` block of a supported provider is removed while it still equals what install renders — all the earlier installs left, not just the active one; an edited entry is kept whole. File deleted when nothing is left. |
|
|
393
400
|
|
|
394
401
|
### Idempotency
|