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
• NBS Hub - Deterministic process enforcement for teams
• 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

Hub (Process Enforcement)

The hub is a deterministic C binary that enforces process discipline on AI supervisors. Mandatory for teams work.

• nbs-hub - Audit gates, phase gates, stall detection, document registry, session recovery

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 tests for C binaries.

• 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)

C binary tests: tests/automated/test_nbs_hub.sh, tests/automated/test_nbs_chat.sh, tests/automated/test_nbs_chat_remote.sh

See tests/README.md for running tests.

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

git clone https://github.com/SonicField/nbs-framework.git
cd nbs-framework

Building the C binaries

The framework includes C binaries for nbs-hub, nbs-chat, nbs-chat-terminal, and nbs-chat-remote. Build them before installing:

cd src/nbs-hub && make && cd ../..
cd src/nbs-chat && make && cd ../..

The compiled binaries are placed in bin/.

Installing

./bin/install.sh

This creates ~/.nbs/ with processed commands and symlinks in ~/.claude/commands/.

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

Author

Dr Alex Turner

Licence

MIT