How Building Blocks Connect
Every building block works alone. When peers are present, they discover each other and compose — no tight coupling required.
Integration in Practice
These integrations follow the same pattern: check if a peer is present, read its state, act accordingly. If the peer is absent, the tool works fine without it. Solid lines are shipped; dashed cards show planned integrations that follow the same pattern.
Biff → Vox
Biff speaks /wall broadcasts and incoming messages aloud when Vox is installed.
A shell hook checks if Vox's state directory exists, reads whether speaking is enabled,
and calls vox directly. No model round-trip — ~110ms end to end.
PR/FAQ → Quarry
The researcher agent searches your knowledge base for evidence to support claims.
The agent checks whether Quarry's MCP tools are available at runtime. If Quarry isn't installed, the researcher proceeds with web research alone.
Domain tools → Persona coming soon
Z Spec auto-selects a formal methods mentor. PR/FAQ selects a product strategist.
When entering tutor mode, the tool checks for Persona's state directory. If present, it writes a character. If the user has manually set a persona, the override is respected. The pattern already works in LangLearn, where each language level has a named instructor (Profesor Garcia, Madame Moreau) with a distinct teaching philosophy and voice.
Persona → Vox coming soon
A persona suggests a voice that matches the character.
Persona writes a voice_hint field to its state file. Vox reads the hint
and switches voices. If no hint is set, Vox uses its session default.
How It Works
Every integration above follows the same four-step check. This pattern is the same whether the caller is a Python library, a shell hook, or an MCP tool — the checks are filesystem operations that any language can perform.
[[ -d ".punt-labs/vox/" ]] command -v vox grep '^speak:' .punt-labs/vox/config.local.md If any step fails, the tool proceeds without the peer. No error, no warning — just the tool working as if the peer doesn't exist. This is the degradation rule: every integration must be an enrichment, never a dependency.
Composable Axes
Building blocks compose along four independent axes. Any subset works. Full composition is the richest experience, but each axis degrades independently.
Six Integration Layers
The four-step discovery pattern maps onto a layered model. The first four layers use only filesystem conventions and shell commands — any tool can participate, not just ours. The last two layers add tighter coupling for Punt Labs tools only.
Universal tier — open to any tool
These layers use filesystem checks, CLI availability, hook events, and shared config files.
A bash script can integrate at all four layers with test -d,
command -v, grep, and sed.
No imports, no libraries, no shared code.
[[ -d ".punt-labs/vox/" ]] command -v vox Enhanced tier — Punt Labs tools
Tighter integration for our own tools. Every feature at these layers must fall back to universal-tier behavior when the shared library or peer is absent.
Shell Hooks as Integration
Shell hooks are first-class participants in this model. A PostToolUse hook is a bash script triggered when a tool call completes. That script uses the same four-step discovery pattern: check the sentinel directory (L0), verify the CLI (L1), read state (L3), and act. The Biff → Vox integration above is entirely a shell hook.
This is by design. The integration standard uses YAML frontmatter (parseable with
grep), sentinel directories (checkable with test -d), and CLIs
(discoverable with command -v) specifically so that shell scripts can
participate at the same level as Python code. The universal tier is universal because
it requires no runtime beyond a POSIX shell.