bstack

name	bstack
category	governance
latent_only	true
description	bstack primer — the Broomva Stack: twenty irreducible automation primitives (P1–P20) that turn an agent-driven workspace into a self-operating system. This is the AGENT-READABLE PRIMER (primitive contract + short-name index + when each fires), NOT the CLI. The bstack CLI + governance substrate (bin/, doctor, templates, hooks) is a separate product installed by clone + bootstrap (git clone https://github.com/broomva/bstack && ./bin/bstack bootstrap) — do NOT `npx skills add broomva/bstack` (it drops bin/scripts, the repo-root SKILL.md case of vercel-labs/skills#1523). Use this primer to reason with the primitives: 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). Triggers on 'bstack', 'Broomva Stack', 'the primitives', 'P1'..'P20', 'primitive contract', 'bstack bootstrap', 'governance metalayer', 'self-operating workspace', 'how do I install bstack', 'what does Pn mean'.

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.

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.