Architecture Decision Runtime - Transform architectural decisions into executable, verifiable constraints
npm install @ipation/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.
- 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.)
- 🔌 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
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
`bash`
cd your-project
specbridge init
This creates a .specbridge/ directory with:config.yaml
- - Project configurationdecisions/
- - Architectural decision filesverifiers/
- - Custom verification logicinferred/
- - Auto-detected patternsreports/
- - Compliance reports
`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
`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/.
`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
`bash`
specbridge report
specbridge report --format markdown --save
Track compliance trends over time:
`bash`
specbridge report --trend --days 30
specbridge report --drift
`bash`
specbridge analytics
specbridge analytics --insights
specbridge analytics auth-001
Get AI-generated insights about compliance trends, violations, and decision impact.
`bash`
specbridge dashboard
Visit http://localhost:3000 to see real-time compliance metrics, trend charts, and decision details.
`bashCopy plugin template
cp templates/verifiers/example-custom.ts .specbridge/verifiers/my-verifier.ts
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 - 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)
- 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)
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
MIT
See CONTRIBUTING.md for guidelines.