| name | blackbox |
| description | Front door and opt-in for the Blackbox Protocol — industrial delivery assurance for agentic work. Enables ambient dispatch for this project so the protocol runs itself thereafter. Use when the user says "blackbox", asks to deliver something with real assurance, asks whether what an agent built actually works, or wants a certificate rather than a "done". |
/blackbox
Confidence is a separate product from the software, and it cannot be manufactured by the party that made the software.
This skill is the opt-in, not the interface. After it runs once in a project, the ambient hook dispatches every turn and the human never types a protocol command again.
Opting a project in
mkdir -p .blackbox && bb next --brief
Resolving bb
Every skill in this plugin writes bb .... Resolve it once at the start of a session, in this order, and use whatever you found for the rest of the turn:
bb on PATH (present if the user ran pip install -e .)${CLAUDE_PLUGIN_ROOT}/bin/bb — the usual case after a plugin install; needs no install step and no dependenciesPYTHONPATH=<repo> python3 -m blackbox.cli — a bare checkout
Do not assume option 1. A plugin install puts nothing on PATH, and a protocol that fails at its first command has verified nothing.
From then on, a UserPromptSubmit hook runs bb next before every turn and injects what must happen. Follow that injection. It is computed from disk by fixed rules, so it is the same answer in any session on any machine, and you do not need to reason about protocol mechanics.
Projects without a .blackbox/ directory get no injection at all. That silence is deliberate — do not create one speculatively.
Your one job the code cannot do
Classify what the human asked for. This is perception, and a regex cannot do it:
- new — nothing exists yet
- change — something exists and gains behaviour
- fix — something exists and is wrong
bb scenario --set fix --summary "the refund button 404s for settled orders" --target "refunds"
Infer it; do not interview the human about it. Say which you chose in one line and move on. Everything downstream — whether a witness is required, what gets verified, what must not break — follows from this.
The stages
| Stage | Skill | What happens |
|---|
| 1 | /freeze | Vision → disambiguated EARS criteria → human signature → hashed, immutable |
| 2 | /build | Any build process. production-grade by default; a plain session works |
| 3 | /verify | Access contract → harness → campaign → live use → red pass. Blind |
| 4 | /certify | Integrity checks → assurance case → verdict |
The commands still exist and still work. Use them when the human explicitly asks, or when bb next names one. Otherwise let the router drive.
Rules that hold in every stage
- The human signs the contract. Nothing else is theirs to do. Never sign on their behalf, never infer a signature from enthusiasm, never treat "sounds good" as approval of criteria they have not read.
- Never claim more than the certificate says. If a criterion is
UNVERIFIED, the correct sentence is "this was not checked" — not "this looks fine".
CANNOT DELIVER costs you nothing. It is a first-class outcome. A protocol that must produce success will manufacture it.- Set
BLACKBOX_ROLE before any stage: build or accept. The scope guard is inert without it, and an inert guard means the independence claim on the certificate is false.
Status vocabulary
Report runs in the protocol's own terms, never softened:
DELIVERED — every criterion met at its required evidence tier, coverage complete, integrity clean.PARTIALLY DELIVERED — something is unmet or unverified. Name which.CANNOT DELIVER — a critical criterion is not met.VOID — the instrument failed: a canary was reported satisfied, the evidence chain broke, or a tamper event is undisposed. A void run says nothing about the product.
Per criterion, and the distinction that matters most:
MET / NOT_MET — checked on this run.CARRIED — certified earlier, unchanged since, deliberately out of scope. Say "not re-checked", never "fine".UNVERIFIED — nobody has ever checked this. The only honest sentence is "no conclusion should be drawn."
