NBS Framework

A framework for honest collaboration between humans and AI systems.

Documentation

• Why NBS - The philosophy: falsifiability over bullshit
• Overview - Why this exists and how it works
• Getting Started - Installation and first use
• NBS Teams - Supervisor/worker patterns for multi-agent work
• NBS Chat - File-based AI-to-AI chat for worker coordination
• Testing Strategy - AI-evaluates-AI testing approach
• Interactive Testing - Multi-turn testing with pty-session
• pty-session Reference - Terminal session manager for automation
• Style Guide - Internal reference for AI writing these materials
• Document Tools - Analysis, planning, and description tools

Examples

• CLAUDE.md - Example project configuration for NBS programming

Foundation

• Goals - The why. Everything else exists in service of this.

Pillars

Built on the foundation:

• Falsifiability - Claims require potential falsifiers
• Rhetoric - Ethos, Pathos, Logos and knowing when to ask
• Verification Cycle - Design → Plan → Deconstruct → [Test → Code → Document]
• Zero-Code Contract - Engineer specifies, Machinist implements with evidence
• Bullshit Detection - Honest reporting, negative outcome analysis

Tools

Core Command

• /nbs - Review and dispatch

Run this after any session. It detects context and dispatches:

• In investigation/* branch → reviews investigation rigour
• After /nbs-discovery → verifies the discovery report is complete
• After /nbs-recovery → reviews the recovery work
• Otherwise → general NBS review

NBS Teams Tools

Supervisor/worker patterns for multi-agent AI work. See NBS Teams for the full overview.

Commands for setting up and using NBS teams:

• /nbs-teams-start - Bootstrap project with .nbs/ structure (one command setup)
• /nbs-teams-help - Interactive guidance for NBS teams usage
• /nbs-help - Interactive guidance for the NBS framework

For AI-as-supervisor or AI-as-worker roles:

• NBS Teams Supervisor - Role and responsibilities for supervisor
• NBS Teams Worker - Role and responsibilities for worker
• NBS Teams Chat - File-based AI-to-AI chat for worker coordination

Workflow Commands

• /nbs-discovery - Read-only archaeology for messy projects
• /nbs-recovery - Step-wise restructuring with confirmation

Document Tools

Tools for working with documents - analysing, planning, and describing:

• /nbs-doc-help - Interactive guidance for document tools
• /nbs-doc-analyse - Detect BS, find actual vs stated goals
• /nbs-doc-plan - Plan documents before writing
• /nbs-doc-describe - Help describe systems, code, concepts

See Document Tools for the full overview.

Side Quest Commands

• /nbs-investigation - Hypothesis testing through experiment (isolated side branch)

Run this when you want to test a hypothesis before committing to a direction. Creates an isolated investigation branch, designs falsifiable experiments, and produces a verdict (falsified / failed to falsify / inconclusive).

Verification Commands

• /nbs-discovery-verify - Verify discovery report completeness (auto-dispatched by /nbs)

Operational Tools

• /nbs-audit - Audit codebase against engineering standards with parallel sub-agents
• /nbs-poll - Periodic check of chats and workers (heartbeat)
• /nbs-chat-digest - Summarise chat channel history
• /nbs-pte - Precise Technical English mode for unambiguous specifications
• /nbs-natural - Exit Precise Technical English mode

Sub-Projects

Terminal Weathering

Progressive replacement of CPython call protocol paths with C type slot implementations, using NBS principles. Evidence from initial Rust/PyO3 work showed that function body replacement leaves CPython's dispatch overhead intact — the performance-critical layer is the call protocol, which requires direct C access to type slots. The methodology (evidence gates, falsifiability, progressive replacement) is unchanged; the unit of work shifted from function bodies to type slots, and the implementation language from Rust to C against CPython's type API, with ASan, leak analysis, and refcount verification as mandatory correctness gates.

• Terminal Weathering Documentation - Theory, getting started, methodology
• Concept - The philosophy and phases
• Evidence - Measured data supporting the Rust-to-C pivot
• /nbs-terminal-weathering - The tool command

Testing

The framework includes automated tests using a novel AI-evaluates-AI approach, plus unit and integration tests for all C binaries.

make test-unit     # 70+ unit tests across bus, chat, sidecar
make test          # Integration tests (lifecycle, interrupt, auto-archive, + component tests)
make test-all      # Everything

• Testing Strategy - Philosophy, adversarial testing, test isolation
• Interactive Testing - Using pty-session for multi-turn tests
• pty-session Reference - Interactive terminal session manager (REPLs, debuggers)
• nbs-worker Reference - Worker lifecycle management (spawn, monitor, search, dismiss)

See tests/README.md for details.

Planning

Project plans and progress logs live in planning/:

• <date>-<project>-plan.md - Terminal goal, completed/outstanding items, decisions
• <date>-<project>-progress.md - Session-by-session record of what was done

Installation

Prerequisites

• GCC (C11 support) or Clang
• GNU Make
• tmux (runtime dependency for session management)

Quick Start

git clone https://github.com/SonicField/nbs-framework.git
cd nbs-framework
make && make install
./bin/install.sh

That's it. Three commands: clone, build, install.

What Gets Built

make builds all five C components from src/:

Component	Binary	Purpose
nbs-bus	bin/nbs-bus	File-based event queue for agent coordination
nbs-chat	bin/nbs-chat, bin/nbs-chat-terminal, bin/nbs-chat-remote, bin/nbs-chat-web	Chat file protocol (create, send, read, poll, search)
nbs-sidecar	bin/nbs-sidecar	Background monitor for Claude Code sessions (20 behaviours)
nbs-pty-session	bin/pty-session	Terminal session manager (create, send, read, wait, kill)
nbs-worker	bin/nbs-worker	Worker lifecycle management (spawn, status, search, dismiss)

All binaries are compiled with -Wall -Wextra -Wshadow -Werror -std=c11. Assertions are always-on (not gated by NDEBUG).

make install copies binaries to bin/.

./bin/install.sh creates ~/.nbs/ with processed commands and symlinks in ~/.claude/commands/.

For custom install location: ./bin/install.sh --prefix=/path/to/location

Running Tests

make test          # Integration tests for all components
make test-unit     # Unit tests only (bus + chat + sidecar)
make test-all      # Unit tests + integration tests

Build Modes

make debug         # Debug build (-O0 -g, for gdb)
make               # Release build (-O2, assertions ON)

ASan builds are available per-component: make -C src/nbs-sidecar asan

Remaining Bash Scripts

The bin/ directory also contains bash scripts for user-facing tools that are not performance-critical:

• nbs-claude — Thin wrapper (~300 lines) that launches Claude Code + nbs-sidecar
• nbs-remote-* — SSH proxy tools for remote operations
• pty-session-lock — Advisory locking for pty sessions
• nbs-chat-init — Project initialisation

These are orchestration scripts, not hot-path code. The sidecar, chat, bus, pty-session, and worker — all called per-tick or per-agent-action — are C binaries.

Author

Dr Alex Turner

Licence

MIT