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

• /start-nbs-teams - 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

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)

Testing

The framework includes automated tests using a novel AI-evaluates-AI approach.

• Testing Strategy - Philosophy, adversarial testing, test isolation
• Interactive Testing - Using pty-session for multi-turn tests
• pty-session Reference - Interactive terminal session manager

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
./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