docs(spec): bstack substrate completion roadmap (v0.4.0 → v1.0.0)#31
Merged
Conversation
Phase 0 of the substrate completion arc — the architectural spec itself.
No code changes. No VERSION bump. This is the canonical reference every
future bstack release through v1.0.0 will cite for "what does done look
like".
What's in the spec:
- 8 architectural contracts: Plant, Controller, Setpoint, Gate,
Primitive, Hook, Companion Skill, Release. Each has explicit
invariants (IDs like PC-1, CC-1, SC-1, GC-1, RC-1).
- 5 categories of gaps in v0.3.1: measurement, enforcement,
installation, evolution, federation. Each gap cites a concrete
file or behavior.
- 9 closure phases (Phase 0 docs, Phases 1-8 features, Phase 9
v1.0 stability pact). Each phase is one PR with concrete
deliverables + tests + version target.
- SLO targets for every CLI operation introduced.
- Risks + mitigations matrix.
- Naming registry for the dispatcher subcommand surface (Appendix C).
Files:
- NEW specs/2026-05-18-substrate-completion.md — canonical spec
(~800 lines, full reasoning + contracts + phases + glossary)
- NEW references/substrate-completion-overview.md — agent-readable
summary (~80 lines) for grep / quick recall
- EDIT SKILL.md — add roadmap pointer below the primitives table
This spec follows P18 (Audience): markdown because it's both
agent-readable (loaded by future agents on bstack work) AND
human-readable (reviewer reads it on this PR). GitHub renders
markdown well; HTML would not be agent-loadable.
Spec is grounded in v0.3.1 state. Every cited file path exists.
Every primitive cited has a row in the table. Every gap cites a
concrete file or behavior. Per the L3 stability budget
(λ₃ ≈ 0.006), governance changes must be rare + deliberate;
publishing this spec is the deliberate step that scopes the
next ~8 releases.
Out of scope (deliberately excluded in §9): hosted SaaS, multi-tenant
auth, agent-vs-agent at scale, formal verification per primitive,
custom LLM hosting, GUI, curl-pipe-bash installer.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This was referenced May 18, 2026
broomva
added a commit
that referenced
this pull request
May 25, 2026
…3 strategy migration (#53) Phase 6a of the Broomva skills packaging strategy. Adds the registry support needed for the new broomva/skills monorepo (Tier-2 vendoring) and fixes the stale strategy entries that pointed at per-skill broomva/<name> repos that never existed as standalones. ## Schema additive bump (companion-skills.v1.json) New optional field `skillPath` per skill entry. When a skill lives inside a monorepo (e.g. broomva/skills), `skillPath` is the relative path to its SKILL.md within that repo (pattern: `skills/<name>/SKILL.md`). Combined with `repo`, install becomes `npx skills add <repo> --skill <name>`. The field is purely additive — existing entries that omit `skillPath` continue to work as standalone per-skill installs. Schema version remains 1 (no breaking change). Downstream `bstack doctor` runs on schema_version: 1 fixtures continue to validate. ## companion-skills.yaml entries ### Strategy block (8 entries → 9 entries, all rewritten) Old: each entry pointed at `repo: broomva/<name>` (8 broken targets — those per-skill repos never existed as standalones; the skills always lived bundled in broomva/strategy-skills/.skills/<name>/). New: all 9 entries (including the previously-unregistered `premortem`) point at `repo: broomva/skills, skillPath: skills/<name>/SKILL.md`, the real monorepo location after Phase-3 migration (broomva/skills PR #3 merge af42d83). ### New workflow & lifecycle block (2 entries) `handoff` (category: lifecycle) and `make-spec` (category: design) — the two Tier-3 → Tier-2 graduations from broomva/skills PR #2 (merge f21515e). Both require min_bstack_version: 0.21.0 (the version this release bumps to, which adds skillPath schema support). ### Net entry count: 32 → 35 (+3 net: +1 premortem, +2 handoff/make-spec) ## skills-roster.md install commands All 9 strategy entries' install commands updated from `npx skills add broomva/strategy-skills` (bundled — still works for backward compat) to `npx skills add broomva/skills --skill <name>` (canonical going forward). Added new "Workflow & Lifecycle (Tier-2 monorepo)" section with handoff + make-spec entries (#30 + #31). ## VERSION 0.20.0 → 0.21.0 (additive minor pre-1.0). ## Test plan - [x] Schema JSON validates (jq parse) ✓ - [x] YAML parses cleanly ✓ - [x] All 9 strategy entries have skillPath matching `^skills/[a-z0-9][a-z0-9-]*/SKILL\.md$` regex ✓ - [x] handoff + make-spec entries have skillPath ✓ - [x] No entry has both `skillPath` and a non-`broomva/skills` repo (semantically valid) ✓ - [x] CHANGELOG entry added with migration notes for downstream consumers ✓ - [ ] Post-merge: `bstack doctor` against schema fixtures (no offline runner here) ## Related - broomva/skills PR #2 — monorepo creation + handoff + make-spec (merge f21515e) - broomva/skills PR #3 — strategy migration (merge af42d83) - broomva/strategy-skills PR #1 — redirect stub (merge 34e8d05) - Strategy: broomva/workspace docs/specs/2026-05-25-skills-packaging-strategy.html §8 Phase 3 + Phase 6a
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 0 of the substrate completion arc — the architectural spec itself. No code changes. No VERSION bump. This is the canonical reference every future bstack release through v1.0.0 will cite for "what does done look like".
Scope
This PR is docs-only. It establishes the architectural contracts the bstack substrate provides + consumes, catalogues the gaps remaining as of v0.3.1, and lays out a 9-phase closure plan from v0.4.0 → v1.0.0.
What's in the spec
8 architectural contracts (each with explicit invariants)
Each contract has a YAML/schema target shape + a numbered invariant table (PC-1..PC-6, CC-1..CC-4, SC-1..SC-4, GC-1..GC-4, etc.).
Gap catalog (27 gaps total)
5 categories × severity matrix:
Every gap cites a concrete file or behavior in v0.3.1.
9 closure phases
Each phase is one PR. Each phase has concrete deliverables + tests + SLO targets + risks.
Plus
Files
specs/2026-05-18-substrate-completion.md(~800 lines) — canonical specreferences/substrate-completion-overview.md(~80 lines) — agent-readable summary for grep / quick recallSKILL.md— roadmap pointer below the primitives tableP18 Audience decision
Spec is markdown (not HTML) because it's both agent-readable (loaded by future agents working on bstack) and human-readable (reviewer reads it on this PR). GitHub renders markdown well; HTML would not be agent-loadable for the cited use case. This is the explicit P18 rule for both-audiences artifacts.
Stability discipline grounding
Per the L3 stability budget (λ₃ ≈ 0.006 measured), governance changes must be rare + deliberate. Publishing this spec is the deliberate step that scopes the next ~8 releases. Each phase ships independently and clears the L3 budget through:
Test plan
Out of scope (this PR explicitly)
🤖 Generated with Claude Code