bstack

bstack — the Broomva Stack (primitives primer)

A portable harness metalayer for AI-native development. Twenty irreducible primitives that turn any agent-driven workspace into a self-operating system. Each primitive closes one failure mode that otherwise drifts into entropy in unsupervised agent sessions.

This file is the agent-readable primer, not the CLI. It teaches you the primitive contract so you can reason with it. The bstack CLI + governance substrate (the bstack binary, doctor, templates, hooks, schemas) is a separate product:

git clone https://github.com/broomva/bstack.git
cd bstack && ./bin/bstack bootstrap

Do not npx skills add broomva/bstack — bstack has a repo-root SKILL.md beside bin/, so skills.sh copies only that file and drops the CLI (vercel-labs/skills#1523). bstack bootstrap installs the companion-skill roster from this monorepo: npx skills add broomva/skills --skill <name> per entry.

Referencing primitives

Use the Name (Pn) form in prose — "applying Snapshot (P15)", "via Dep-Chain (P14)", "running Bookkeeping (P6)". The number is the canonical id; the name is the human handle.

Short-name index: Bridge (P1) · Gate (P2) · Tickets (P3) · Pipeline (P4) · Fanout (P5) · Bookkeeping (P6) · Freshness (P7) · Janitor (P8) · Wait (P9) · Hygiene (P10) · Empirical (P11) · Persist (P12) · Dream (P13) · Dep-Chain (P14) · Snapshot (P15) · Crystallize (P16) · Lens (P17) · Audience (P18) · Orchestrate (P19) · Cross-Review (P20).

The twenty primitives

#	Primitive	Closes / does
P1	Bridge — Conversation Bridge	Session amnesia. Stop hook → JSONL → docs → vault; capture is automatic.
P2	Gate — Control Gate	Destructive ops the model didn't authorize. PreToolUse hook → .control/policy.yaml; G1–G4 never bypassed.
P3	Tickets — Linear Tickets	Invisible work. Every unit tracked Backlog → Done; no significant work without a ticket.
P4	Pipeline — PR Pipeline	Merging unreviewed code. Branch → PR → CI → merge → deploy; never merge on red.
P5	Fanout — Parallel Agents	Serial bottlenecks. Concurrent isolated agents via worktrees; no shared mutable file writes.
P6	Bookkeeping — Knowledge Bookkeeping	Lost knowledge. Score → promote → entity pages → synthesize. Capture is a reflex, never a question — file it, report after.
P7	Freshness — Skill Freshness Check	Silent skill rot. SessionStart nudge when installed skills are ≥7d stale. Never blocks.
P8	Janitor — Branch + Worktree Janitor	Dead branches/worktrees. make janitor removes squash-merged + orphaned safely; default dry-run.
P9	Wait — Productive Wait	Sleeping on CI. gh pr checks --watch via background; drain a work-queue while blocked. Never sleep.
P10	Hygiene — Worktree Hygiene	Dirty trees. Decide worktree-or-not before the first file; a clean git status is the only reliable reset point.
P11	Empirical — Empirical Feedback	Reasoning mistaken for validation. Validate by interacting — log-tails, E2E, screenshots, deploy verification.
P12	Persist — Persistent Loop	In-context decay on long work (>1h). State lives in the filesystem; each iteration spawns a fresh context.
P13	Dream — Dream Cycle	Dense low-tier signal corrupting sparse high-tier rules. Cross-tier consolidation replays against a frozen substrate (stop-gradient).
P14	Dep-Chain — Dependency-Chain Reasoning	"Think deeply" as ritual. Enumerate upstream + downstream (concrete file paths, function names) in the response — not in your head.
P15	Snapshot — State-Snapshot Before Action	Plans built on stale state. Surface git status + branch + ahead/behind + open PRs + CI/deploy state before planning.
P16	Crystallize — Crystallization (the engine)	Patterns staying in the operator's head. Recurs ≥3× → promote to skill / rule / gate. The meta-primitive that produces the others.
P17	Lens — Lens-Routed Articulation	act as X persona theater. Route input through a lens registry that loads substantive context, not a persona rewrite.
P18	Audience — Format-Follows-Audience	Wrong format by habit. Agent-read → markdown; human-read (specs, reports) → rich HTML. Format follows audience.
P19	Orchestrate — Mechanism Selection	"Continue please" handoffs. Pick the autonomous-continuation mechanism by the 2×2×2 cube before substantive work.
P20	Cross-Review — Cross-Model Adversarial Gate	Single-model echo chambers. The writer cannot be the final judge; fire a cross-model gate (≥7/10) before merging substantive PRs.

When to use this primer

• You're operating in a bstack-governed workspace and need the primitive contract to reason with.
• Someone references Pn / a primitive short-name and you need its meaning + invariant.
• You're deciding how to install bstack (answer: clone + bstack bootstrap, not skills.sh).
• You want the discipline without the CLI (this primer is enough to apply the primitives by hand).

The full mechanism specs, the bstack doctor primitive-contract linter, the RCS control-loop math, and the governance templates all live in the CLI repo (github.com/broomva/bstack). This primer is the entry point; the substrate is the product.