Version: 1.1.1 Status: Production Website: bspec.dev Documentation: bspec.dev/docs MCP Server: mcp.bspec.dev License: MIT

Business Specification Standard (BSpec) is the universal language for describing any business as a structured, machine-readable knowledge graph. Like how SAFE agreements standardized early-stage investing, BSpec standardizes business documentation to enable systematic analysis, automated generation, and intelligent decision-making.

Key Innovation: Treat every business as a system of atomic, interconnected documents that together form a complete picture of strategy, operations, and execution.

Today's business documentation is fragmented, inconsistent, and impossible to analyze systematically:

• Entrepreneurs reinvent business planning without structured guidance
• Investors compare deals using incompatible formats and incomplete information
• AI systems cannot understand business context to provide intelligent assistance
• Organizations lose knowledge when people leave or contexts change

BSpec provides a standardized vocabulary and relationship model for describing any business completely:

Business = Graph of Connected Documents
Each Document = One Business Concern + Rich Metadata
Relationships = How Documents Depend On, Enable, or Conflict With Each Other

This enables:

• Systematic thinking through templates and dependencies
• Automated analysis by AI systems that understand business structure
• Intelligent generation of business artifacts (pitch decks, code, marketing)
• Consistent evaluation across different businesses and industries

Every BSpec document follows this structure:

---
# Core Identity
id: STR-platform-strategy
title: "AI Platform Strategy"
type: STR
status: Draft|Review|Accepted|Deprecated
version: 1.0.0

# Relationships (creates business knowledge graph)
depends_on: [MSN-mission, MKT-ai-market]
enables: [PRD-inference-api, GTM-developer-first]
conflicts_with: [STR-consumer-focus]

# Business Context
domain: strategic
priority: critical
success_criteria:
  - "Platform adoption exceeds 1000 developers by Q4"
  - "API revenue reaches $100k MRR within 12 months"
---

# Platform Strategy Content
*Document content in structured Markdown...*

BSpec defines document types across comprehensive business domains:

MSN Mission • VSN Vision • VAL Values • STR Strategy • OBJ Objectives • MOT Moats • PUR Purpose • THY Theory of Change

MKT Market Definition • SEG Market Segments • CMP Competitive Analysis • POS Positioning • TRN Trends • ECO Ecosystem • OPP Opportunities • THR Threats • REG Regulatory Environment • MAC Macro Environment

PER Personas • JTB Jobs-to-be-Done • CJM Customer Journey • USE Use Cases • STO User Stories • PAI Pain Points • GAI Gains • EMP Empathy Maps • FEE Feedback • INT Interviews • SUR Surveys • BEH Behaviors

PRD Products • SVC Services • FEA Features • ROD Roadmap • REQ Requirements • QUA Quality Standards • UXD User Experience • PER Performance • INT Integrations • SUP Support

BMC Business Model Canvas • REV Revenue Streams • PRC Pricing • CST Cost Structure • CHN Channels • REL Customer Relationships • RES Key Resources • ACT Key Activities • PRT Key Partnerships • UNT Unit Economics • LTV Lifetime Value • CAC Customer Acquisition

PRC Processes • WFL Workflows • ORG Organization • ROL Roles • TEA Teams • SKI Skills • POL Policies • SLA Service Levels • VND Vendors • FAC Facilities • TOO Tools • CAP Capabilities

ARC Architecture • SYS Systems • DAT Data Models • API APIs • INF Infrastructure • SEC Security • DEV Development • ANA Analytics

FIN Financial Model • BUD Budget • FOR Forecasts • FND Funding • INV Investment • VAL Valuation • MET Metrics • REP Reporting • AUD Audit • TAX Tax Strategy

RSK Risks • MIT Mitigations • CMP Compliance • GVN Governance • CTL Controls • CRI Crisis Management • ETH Ethics • STA Stakeholders

GTM Go-to-Market • GRW Growth Model • SCL Scaling • EXP Experiments • INN Innovation • RND Research • ACQ Acquisitions • EXP Expansion

DEC Decisions • LRN Learnings • RET Retrospectives • HYP Hypotheses • KNO Knowledge • WIS Wisdom

🥉 Bronze: Minimum Viable Business Spec (12+ documents)

• Strategic core (MSN, VSN, VAL)
• Customer understanding (2+ PER with JTB)
• Solution definition (1+ PRD/SVC)
• Business model (REV, CST)
• Risk awareness (2+ RSK with MIT)

🥈 Silver: Investment Ready (25+ documents)

• Bronze foundation + strategic depth + market analysis
• Complete business model and financial foundation
• Growth strategy and key metrics

🥇 Gold: Operational Excellence (45+ documents)

• Silver foundation + operational processes
• Organization design and technology architecture
• Compliance framework and innovation pipeline

Specialized requirements for different business types:

• Software/SaaS: ARC, API, SEC, SUP + SaaS metrics (MRR, CAC, LTV, Churn, NRR)
• Physical Product: INF, QUA, VND, REG + supply chain and manufacturing
• Service Business: PRC, SLA, SKI, QUA + service delivery and capacity planning
• Nonprofit: PUR, STA, MET, GVN + impact measurement and accountability

BSpec follows Semantic Versioning 2.0.0 with component-specific versioning strategies:

• Core Specification: 1.1.1 (in spec/v1/version.txt)
• All SDKs: 1.1.1 (aligned with specification)
• CLI Tool: 1.1.1 (aligned with specification)
• Web App: 1.1.1 (aligned with specification)
• MCP Server: 1.1.0 (aligned with specification)

Use the automated version synchronization script:

# Display current versions across all components
python3 scripts/version-sync.py --report

# Validate version consistency
python3 scripts/version-sync.py --validate

# Update specification and sync all SDKs
python3 scripts/version-sync.py --update-spec 1.1.0

# Synchronize SDK versions to current spec
python3 scripts/version-sync.py --sync-all

# Update individual components
python3 scripts/version-sync.py --update-component typescript-sdk 1.0.1

See docs/VERSIONING.md for complete versioning policies and docs/CHANGELOG.md for release history.

BSpec-Foundations/
├── spec/v1/                     # BSpec 1.0 Specification (COMPLETE)
│   ├── spec.md                  # Complete specification document
│   ├── strategic-foundation/    # Strategic document types (MSN, VSN, VAL, etc.)
│   ├── market-environment/      # Market analysis document types
│   ├── customer-value/          # Customer-focused document types
│   ├── product-service/         # Product and service document types
│   ├── business-model/          # Business model document types
│   ├── operations-execution/    # Operations document types
│   ├── technology-data/         # Technology document types
│   ├── financial-investment/    # Financial document types
│   ├── risk-governance/         # Risk and governance document types
│   ├── growth-innovation/       # Growth document types
│   ├── learning-decisions/      # Learning document types
│   └── brand-marketing/         # Brand and marketing document types
├── apps/                        # BSpec Ecosystem Applications
│   ├── web/                     # bspec.dev website (SvelteKit, Apple/Liquid Glass design)
│   └── mcp/                     # Model Context Provider server (Cloudflare Workers)
├── sdk/                         # Software Development Kits
│   ├── v1/
│   │   ├── typescript/          # TypeScript SDK with complete type definitions
│   │   ├── python/              # Python SDK with Pydantic models
│   │   ├── go/                  # Go SDK with struct definitions
│   │   ├── rust/                # Rust SDK with type definitions
│   │   ├── json/                # JSON schemas for all document types
│   │   └── format/              # Format specifications and validation
│   └── cli/                     # Command-line interface (Go binary)
├── scripts/                     # Code generation and utilities
│   ├── generators/              # SDK generators for all languages
│   ├── parsers/                 # Specification parsers
│   └── templates/               # Code generation templates
├── examples/                    # Reference implementations
└── README.md                    # This file

Modern documentation site with comprehensive guides:

• Getting started guides and tutorials
• Interactive document type explorer
• Complete specification reference
• Download links for tools and SDKs

Comprehensive technical documentation:

• Complete BSpec 1.1 specification
• SDK documentation and API references
• Implementation guides and best practices
• Industry-specific profiles and examples

Hosted MCP (Model Context Protocol) server for AI agents:

• Parse and validate BSpec documents
• Query document types and domains
• Retrieve specification information
• Generate artifacts from specifications

Packaging format for complete business specifications:

business-spec.bspec  (like .tgz archive)
├── documents/       # All BSpec documents
├── assets/          # Images, diagrams, attachments
├── manifest.json    # Metadata and validation
└── relationships/   # Computed relationship graph

BSpec is designed for intelligent consumption:

Every document type has a corresponding JSON schema for validation and AI consumption.

Standard prompts for document generation, business analysis, and artifact creation.

interface BSpecAPI {
  // Document management
  getDocument(id: string): BSpecDocument
  createDocument(doc: BSpecDocument): void
  updateDocument(id: string, updates: Partial<BSpecDocument>): void

  // Relationship queries
  getDependencies(id: string, depth?: number): BSpecDocument[]
  getImpacts(id: string, depth?: number): BSpecDocument[]
  findConflicts(id: string): BSpecDocument[]

  // Analysis
  validateConformance(profile?: IndustryProfile): ConformanceReport
  findGaps(targetLevel: ConformanceLevel): DocumentGap[]
  analyzeReadiness(milestone: string): ReadinessReport

  // Generation
  generateDocument(type: DocumentType, context: BusinessContext): BSpecDocument
  generateArtifact(type: ArtifactType, documents: BSpecDocument[]): Artifact
}

1. Install the CLI:

   # Quick install (macOS/Linux)
   curl -sSL https://github.com/a3tai/bspec/releases/latest/download/bspec-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/') -o bspec
   chmod +x bspec
   sudo mv bspec /usr/local/bin/
   
   # Or build from source
   cd sdk/cli && make install
   
   # Verify installation
   bspec --help

2. Initialize a new BSpec project:

   bspec init my-business-spec
   cd my-business-spec

3. Start with strategic documents:

   # Interactive AI-assisted document creation
   bspec chat

TypeScript/JavaScript:

import { BSpecDocument, validateDocument } from '@bspec/typescript-sdk';

// Load and validate a BSpec document
const doc: BSpecDocument = loadFromMarkdown(content);
const validation = validateDocument(doc);

Python:

from bspec_sdk import BSpecDocument, DocumentValidator

# Create and validate documents
doc = BSpecDocument.from_markdown(content)
validator = DocumentValidator()
result = validator.validate(doc)

Go:

import "github.com/a3tai/bspec/sdk/v1/go"

// Parse and validate BSpec documents
doc, err := bspec.ParseDocument(content)
validation := bspec.ValidateDocument(doc)

1. Read the Specification: Start with spec/v1/spec.md for the complete framework
2. Choose Your Conformance Target: Bronze (12 docs), Silver (25 docs), or Gold (45 docs)
3. Pick Your Industry Profile: Software/SaaS, Physical Product, Service Business, or Nonprofit
4. Start with Strategic Foundation: Create MSN, VSN, and VAL documents first

This project is released under the MIT License. See the LICENSE file for details.

See CONTRIBUTING.md for guidelines on how to contribute to BSpec.

BSpec 1.0 is the beginning, not the end. It's the foundation for a future where every business decision is informed by complete context, where AI can truly understand and assist with business challenges, and where the complexity of modern business becomes manageable through systematic thinking and intelligent automation.