SpecBridge

Architecture Decision Runtime - Transform architectural decisions into executable, verifiable constraints.

SpecBridge creates a living integration layer between design intent and implementation, bridging the gap between specifications and code.

Features

• Inference Engine - Analyzes existing codebases to extract implicit patterns
• Decision Registry - Stores validated architectural decisions as versioned YAML files
• Verification Engine - Continuously verifies code compliance at multiple levels
• Propagation Engine - Analyzes impact when architectural decisions change
• Compliance Reporting - Provides dashboards and tracks conformity over time
• Analytics & Insights - AI-generated insights, drift detection, and trend analysis
• Interactive Dashboard - Real-time compliance monitoring with visual charts
• Agent Interface - Exposes decisions to code generation agents (Copilot, Claude, etc.)

New in v2.0 ✨

• 🔌 Plugin System - Create custom verifiers without modifying core code (Guide)
• ⚖️ Severity-Weighted Compliance - Scores that properly reflect violation criticality
• ⚡ Performance Boost - 30% faster verification with instance pooling and caching
• 📊 Sub-1s Dashboard - In-memory caching for instant report loading
• 🔄 Migration Tool - Automated v1 → v2 migration with comparison reports

📖 See full changelog | 🔧 Migration Guide

Project vision: French | English summary

Installation

Requires Node.js 20.19.0 or later.

npm install -g @ipation/specbridge

Or use directly with npx:

npx @ipation/specbridge init

Once installed globally, you can use the specbridge command directly:

specbridge init

Quick Start

1. Initialize SpecBridge in your project

cd your-project
specbridge init

This creates a .specbridge/ directory with:

• config.yaml - Project configuration
• decisions/ - Architectural decision files
• verifiers/ - Custom verification logic
• inferred/ - Auto-detected patterns
• reports/ - Compliance reports

2. Detect patterns in your codebase

specbridge infer

SpecBridge analyzes your code and suggests patterns it has detected, such as:

• Naming conventions (PascalCase classes, camelCase functions)
• Import patterns (barrel imports, path aliases)
• Code structure (directory conventions, file naming)
• Error handling patterns

3. Create architectural decisions

specbridge decision create auth-001 \
  --title "Authentication Token Handling" \
  --summary "All authentication tokens must be validated server-side"

Or edit the YAML files directly in .specbridge/decisions/.

4. Verify compliance

specbridge verify

Run verification at different levels:

• --level commit - Fast checks for pre-commit hooks (< 5s)
• --level pr - Full checks for pull requests
• --level full - Comprehensive verification

5. Generate compliance reports

specbridge report
specbridge report --format markdown --save

Track compliance trends over time:

specbridge report --trend --days 30
specbridge report --drift

6. Analyze compliance with AI insights

specbridge analytics
specbridge analytics --insights
specbridge analytics auth-001

Get AI-generated insights about compliance trends, violations, and decision impact.

7. Launch interactive dashboard

specbridge dashboard

Visit http://localhost:3000 to see real-time compliance metrics, trend charts, and decision details.

8. Create custom verifiers (v2.0+)

# Copy plugin template
cp templates/verifiers/example-custom.ts .specbridge/verifiers/my-verifier.ts

# Edit and customize
# Then use in decisions:
# check:
#   verifier: my-verifier

# Verify
specbridge verify

See the Plugin Development Guide for detailed instructions.

Open your browser to view real-time compliance metrics, trend charts, and insights.

8. Integrate with AI agents

specbridge context src/api/auth.ts

Generates architectural context in Markdown format for AI code assistants.

Dogfooding

SpecBridge uses itself to enforce its own architectural decisions! We verify:

• ✅ Error handling patterns (all errors extend SpecBridgeError)
• ✅ ESM import conventions (.js extensions required)
• ✅ Naming conventions (PascalCase/camelCase)
• ✅ TypeScript strict mode settings
• ✅ Domain-driven module structure

See our Dogfooding Guide to learn how we use SpecBridge on itself, or explore our decision files in .specbridge/decisions/ as real-world examples.

Decision File Format

Decisions are stored as YAML files in .specbridge/decisions/:

kind: Decision
metadata:
  id: auth-001
  title: Authentication Token Handling
  status: active
  owners: [security-team]

decision:
  summary: All authentication tokens must be validated server-side
  rationale: Client-side validation can be bypassed...

constraints:
  - id: server-validation
    type: invariant
    rule: Token validation must occur in server-side code
    severity: critical
    scope: src/api/**/*.ts

  - id: token-expiry
    type: convention
    rule: Tokens should include expiry timestamps
    severity: high
    scope: src/auth/**/*.ts

Constraint Types

| Type | Description | Enforcement | |------|-------------|-------------| | invariant | Never to be violated | Blocks merges | | convention | Must be respected unless justified | Requires explanation | | guideline | Recommended practice | Informational only |

Severity Levels

| Level | Description | |-------|-------------| | critical | Blocks deployment immediately | | high | Must be resolved within deadline | | medium | Should be addressed | | low | Added to backlog |

Git Hook Integration

Install pre-commit hooks:

specbridge hook install

For Husky users:

specbridge hook install --husky

For Lefthook, add to lefthook.yml:

pre-commit:
  commands:
    specbridge:
      glob: "*.{ts,tsx}"
      run: npx specbridge hook run --level commit --files {staged_files}

Configuration

Edit .specbridge/config.yaml:

version: "1.0"
project:
  name: my-project
  sourceRoots:
    - src/**/*.ts
    - src/**/*.tsx
  exclude:
    - "**/*.test.ts"
    - "**/node_modules/**"

inference:
  minConfidence: 70
  analyzers: [naming, structure, imports, errors]

verification:
  levels:
    commit:
      timeout: 5000
      severity: [critical]
    pr:
      timeout: 60000
      severity: [critical, high]

CLI Reference

| Command | Description | |---------|-------------| | specbridge init | Initialize SpecBridge in project | | specbridge infer | Detect patterns in codebase | | specbridge verify | Verify code compliance | | specbridge decision list | List all decisions | | specbridge decision show <id> | Show decision details | | specbridge decision create <id> | Create new decision | | specbridge decision validate | Validate decision files | | specbridge report | Generate compliance report | | specbridge report --trend | Show compliance trends over time | | specbridge report --drift | Analyze drift since last report | | specbridge analytics | Analyze compliance with AI insights | | specbridge analytics <id> | Analyze specific decision | | specbridge dashboard | Launch interactive web dashboard | | specbridge hook install | Install git hooks | | specbridge hook run | Run verification (for hooks) | | specbridge context <file> | Generate agent context |

Use specbridge <command> --help for detailed options.

Philosophy

What SpecBridge Is

• A runtime constraint system for architectural decisions
• A bridge between human decisions and automated enforcement
• An inference system that learns before enforcing
• A graduated constraint framework (guideline → convention → invariant)

What SpecBridge Is Not

• Not an architectural framework (it's architecture-agnostic)
• Not a code generator (it guides/constrains generators)
• Not a documentation tool (decisions are executable)
• Not a test replacement (verifies structure, not behavior)

Maturity Levels

SpecBridge supports progressive adoption:

1. Observation - Infer patterns from existing code
2. Documentation - Document and version decisions
3. Detection - CI detects violations
4. Constrained Generation - Agents receive context
5. Automatic Correction - Auto-fix minor violations

License

MIT

Contributing

See CONTRIBUTING.md for guidelines.