{"id":42500815,"url":"https://github.com/nouatzi/specbridge","last_synced_at":"2026-02-06T20:04:53.504Z","repository":{"id":334733147,"uuid":"1142482978","full_name":"nouatzi/specbridge","owner":"nouatzi","description":"Architecture Decision Runtime - Transform architectural decisions into executable, verifiable constraints","archived":false,"fork":false,"pushed_at":"2026-01-30T21:47:58.000Z","size":399,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-31T13:33:41.702Z","etag":null,"topics":["adr","architectural-decisions","architecture","cli","code-quality","constraints","pattern-detection","typescript","verification"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nouatzi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-26T13:25:19.000Z","updated_at":"2026-01-30T21:47:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nouatzi/specbridge","commit_stats":null,"previous_names":["nouatzi/specbridge"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/nouatzi/specbridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nouatzi%2Fspecbridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nouatzi%2Fspecbridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nouatzi%2Fspecbridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nouatzi%2Fspecbridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nouatzi","download_url":"https://codeload.github.com/nouatzi/specbridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nouatzi%2Fspecbridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29174381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T19:56:27.068Z","status":"ssl_error","status_checked_at":"2026-02-06T19:56:18.934Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr","architectural-decisions","architecture","cli","code-quality","constraints","pattern-detection","typescript","verification"],"created_at":"2026-01-28T13:06:04.701Z","updated_at":"2026-02-06T20:04:53.492Z","avatar_url":"https://github.com/nouatzi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SpecBridge\n\n[![CI](https://github.com/nouatzi/specbridge/workflows/CI/badge.svg)](https://github.com/nouatzi/specbridge/actions)\n[![npm version](https://img.shields.io/npm/v/@ipation/specbridge)](https://www.npmjs.com/package/@ipation/specbridge)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/node/v/%40ipation%2Fspecbridge)](https://nodejs.org)\n\n**Architecture Decision Runtime** - Transform architectural decisions into executable, verifiable constraints.\n\nSpecBridge creates a living integration layer between design intent and implementation, bridging the gap between specifications and code.\n\n## Features\n\n- **Inference Engine** - Analyzes existing codebases to extract implicit patterns\n- **Decision Registry** - Stores validated architectural decisions as versioned YAML files\n- **Verification Engine** - Continuously verifies code compliance at multiple levels\n- **Propagation Engine** - Analyzes impact when architectural decisions change\n- **Compliance Reporting** - Provides dashboards and tracks conformity over time\n- **Analytics \u0026 Insights** - AI-generated insights, drift detection, and trend analysis\n- **Interactive Dashboard** - Real-time compliance monitoring with visual charts\n- **Agent Interface** - Exposes decisions to code generation agents (Copilot, Claude, etc.)\n\n### New in v2.0 ✨\n\n- 🔌 **Plugin System** - Create custom verifiers without modifying core code ([Guide](./docs/PLUGIN-DEVELOPMENT.md))\n- ⚖️ **Severity-Weighted Compliance** - Scores that properly reflect violation criticality\n- ⚡ **Performance Boost** - 30% faster verification with instance pooling and caching\n- 📊 **Sub-1s Dashboard** - In-memory caching for instant report loading\n- 🔄 **Migration Tool** - Automated v1 → v2 migration with comparison reports\n\n[📖 See full changelog](./CHANGELOG-v2.0.md) | [🔧 Migration Guide](./docs/MIGRATION-V2.md)\n\n## Installation\n\n```bash\nnpm install -g @ipation/specbridge\n```\n\nOr use directly with npx:\n\n```bash\nnpx @ipation/specbridge init\n```\n\nOnce installed globally, you can use the `specbridge` command directly:\n\n```bash\nspecbridge init\n```\n\n## Quick Start\n\n### 1. Initialize SpecBridge in your project\n\n```bash\ncd your-project\nspecbridge init\n```\n\nThis creates a `.specbridge/` directory with:\n- `config.yaml` - Project configuration\n- `decisions/` - Architectural decision files\n- `verifiers/` - Custom verification logic\n- `inferred/` - Auto-detected patterns\n- `reports/` - Compliance reports\n\n### 2. Detect patterns in your codebase\n\n```bash\nspecbridge infer\n```\n\nSpecBridge analyzes your code and suggests patterns it has detected, such as:\n- Naming conventions (PascalCase classes, camelCase functions)\n- Import patterns (barrel imports, path aliases)\n- Code structure (directory conventions, file naming)\n- Error handling patterns\n\n### 3. Create architectural decisions\n\n```bash\nspecbridge decision create auth-001 \\\n  --title \"Authentication Token Handling\" \\\n  --summary \"All authentication tokens must be validated server-side\"\n```\n\nOr edit the YAML files directly in `.specbridge/decisions/`.\n\n### 4. Verify compliance\n\n```bash\nspecbridge verify\n```\n\nRun verification at different levels:\n- `--level commit` - Fast checks for pre-commit hooks (\u003c 5s)\n- `--level pr` - Full checks for pull requests\n- `--level full` - Comprehensive verification\n\n### 5. Generate compliance reports\n\n```bash\nspecbridge report\nspecbridge report --format markdown --save\n```\n\nTrack compliance trends over time:\n```bash\nspecbridge report --trend --days 30\nspecbridge report --drift\n```\n\n### 6. Analyze compliance with AI insights\n\n```bash\nspecbridge analytics\nspecbridge analytics --insights\nspecbridge analytics auth-001\n```\n\nGet AI-generated insights about compliance trends, violations, and decision impact.\n\n### 7. Launch interactive dashboard\n\n```bash\nspecbridge dashboard\n```\n\nVisit `http://localhost:3000` to see real-time compliance metrics, trend charts, and decision details.\n\n### 8. Create custom verifiers (v2.0+)\n\n```bash\n# Copy plugin template\ncp templates/verifiers/example-custom.ts .specbridge/verifiers/my-verifier.ts\n\n# Edit and customize\n# Then use in decisions:\n# check:\n#   verifier: my-verifier\n\n# Verify\nspecbridge verify\n```\n\nSee the [Plugin Development Guide](./docs/PLUGIN-DEVELOPMENT.md) for detailed instructions.\n\nOpen your browser to view real-time compliance metrics, trend charts, and insights.\n\n### 8. Integrate with AI agents\n\n```bash\nspecbridge context src/api/auth.ts\n```\n\nGenerates architectural context in Markdown format for AI code assistants.\n\n## Dogfooding\n\nSpecBridge uses itself to enforce its own architectural decisions! We verify:\n\n- ✅ Error handling patterns (all errors extend SpecBridgeError)\n- ✅ ESM import conventions (.js extensions required)\n- ✅ Naming conventions (PascalCase/camelCase)\n- ✅ TypeScript strict mode settings\n- ✅ Domain-driven module structure\n\nSee our [Dogfooding Guide](docs/dogfooding-guide.md) to learn how we use SpecBridge on itself, or explore our decision files in `.specbridge/decisions/` as real-world examples.\n\n## Decision File Format\n\nDecisions are stored as YAML files in `.specbridge/decisions/`:\n\n```yaml\nkind: Decision\nmetadata:\n  id: auth-001\n  title: Authentication Token Handling\n  status: active\n  owners: [security-team]\n\ndecision:\n  summary: All authentication tokens must be validated server-side\n  rationale: Client-side validation can be bypassed...\n\nconstraints:\n  - id: server-validation\n    type: invariant\n    rule: Token validation must occur in server-side code\n    severity: critical\n    scope: src/api/**/*.ts\n\n  - id: token-expiry\n    type: convention\n    rule: Tokens should include expiry timestamps\n    severity: high\n    scope: src/auth/**/*.ts\n```\n\n### Constraint Types\n\n| Type | Description | Enforcement |\n|------|-------------|-------------|\n| `invariant` | Never to be violated | Blocks merges |\n| `convention` | Must be respected unless justified | Requires explanation |\n| `guideline` | Recommended practice | Informational only |\n\n### Severity Levels\n\n| Level | Description |\n|-------|-------------|\n| `critical` | Blocks deployment immediately |\n| `high` | Must be resolved within deadline |\n| `medium` | Should be addressed |\n| `low` | Added to backlog |\n\n## Git Hook Integration\n\nInstall pre-commit hooks:\n\n```bash\nspecbridge hook install\n```\n\nFor Husky users:\n```bash\nspecbridge hook install --husky\n```\n\nFor Lefthook, add to `lefthook.yml`:\n```yaml\npre-commit:\n  commands:\n    specbridge:\n      glob: \"*.{ts,tsx}\"\n      run: npx specbridge hook run --level commit --files {staged_files}\n```\n\n## Configuration\n\nEdit `.specbridge/config.yaml`:\n\n```yaml\nversion: \"1.0\"\nproject:\n  name: my-project\n  sourceRoots:\n    - src/**/*.ts\n    - src/**/*.tsx\n  exclude:\n    - \"**/*.test.ts\"\n    - \"**/node_modules/**\"\n\ninference:\n  minConfidence: 70\n  analyzers: [naming, structure, imports, errors]\n\nverification:\n  levels:\n    commit:\n      timeout: 5000\n      severity: [critical]\n    pr:\n      timeout: 60000\n      severity: [critical, high]\n```\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `specbridge init` | Initialize SpecBridge in project |\n| `specbridge infer` | Detect patterns in codebase |\n| `specbridge verify` | Verify code compliance |\n| `specbridge decision list` | List all decisions |\n| `specbridge decision show \u003cid\u003e` | Show decision details |\n| `specbridge decision create \u003cid\u003e` | Create new decision |\n| `specbridge decision validate` | Validate decision files |\n| `specbridge report` | Generate compliance report |\n| `specbridge report --trend` | Show compliance trends over time |\n| `specbridge report --drift` | Analyze drift since last report |\n| `specbridge analytics` | Analyze compliance with AI insights |\n| `specbridge analytics \u003cid\u003e` | Analyze specific decision |\n| `specbridge dashboard` | Launch interactive web dashboard |\n| `specbridge hook install` | Install git hooks |\n| `specbridge hook run` | Run verification (for hooks) |\n| `specbridge context \u003cfile\u003e` | Generate agent context |\n\nUse `specbridge \u003ccommand\u003e --help` for detailed options.\n\n## Philosophy\n\n### What SpecBridge Is\n\n- A runtime constraint system for architectural decisions\n- A bridge between human decisions and automated enforcement\n- An inference system that learns before enforcing\n- A graduated constraint framework (guideline → convention → invariant)\n\n### What SpecBridge Is Not\n\n- Not an architectural framework (it's architecture-agnostic)\n- Not a code generator (it guides/constrains generators)\n- Not a documentation tool (decisions are executable)\n- Not a test replacement (verifies structure, not behavior)\n\n## Maturity Levels\n\nSpecBridge supports progressive adoption:\n\n1. **Observation** - Infer patterns from existing code\n2. **Documentation** - Document and version decisions\n3. **Detection** - CI detects violations\n4. **Constrained Generation** - Agents receive context\n5. **Automatic Correction** - Auto-fix minor violations\n\n## License\n\nMIT\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnouatzi%2Fspecbridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnouatzi%2Fspecbridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnouatzi%2Fspecbridge/lists"}