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

$3

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

``bash
npm install -g @ipation/specbridge
`

Or use directly with npx:

`bash
npx @ipation/specbridge init
`

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

`bash
specbridge init
`

Quick Start

$3

`bash
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

$3

`bash
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

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

$3

`bash
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

$3

`bash
specbridge report
specbridge report --format markdown --save
`

Track compliance trends over time:
`bash
specbridge report --trend --days 30
specbridge report --drift
`

$3

`bash
specbridge analytics
specbridge analytics --insights
specbridge analytics auth-001
`

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

$3

`bash
specbridge dashboard
`

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

$3

`bash


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.

$3

`bash
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/:

`yaml
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
`

$3

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

$3

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

`bash
specbridge hook install
`

For Husky users:
`bash
specbridge hook install --husky
`

For Lefthook, add to lefthook.yml:
`yaml
pre-commit:
commands:
specbridge:
glob: "*.{ts,tsx}"
run: npx specbridge hook run --level commit --files {staged_files}
`

Configuration

Edit .specbridge/config.yaml:

`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 | Show decision details |
| specbridge decision create | 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 | Analyze specific decision |
| specbridge dashboard | Launch interactive web dashboard |
| specbridge hook install | Install git hooks |
| specbridge hook run | Run verification (for hooks) |
| specbridge context | Generate agent context |

Use specbridge --help` for detailed options.

Philosophy

$3

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

$3

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