OpenSpec Journey: Change Proposals Meet Runtime Enforcement

TL;DR: OpenSpec manages change proposals and anchored specs. SpecFact adds code analysis, contract enforcement, and DevOps sync. This article shows two working flows: OpenSpec-first and code-first. Every command below is copy/paste ready.

Why OpenSpec plus SpecFact

OpenSpec gives you durable change proposals and source-of-truth specs. SpecFact gives you brownfield analysis and runtime enforcement. Together, you stop spec-driven vibe coding and get deterministic proofs of what changed, why it changed, and whether it is safe to ship.

OpenSpec owns the intent. SpecFact owns the evidence. That separation is the difference between a document and a verified system.

---

Flow A: OpenSpec-first (specs to enforcement)

Start with OpenSpec change proposals, then let SpecFact analyze the code and enforce contracts in CI.

Step 1: Set up OpenSpec and SpecFact

Before starting, ensure you have both tools installed:

• OpenSpec: Follow the OpenSpec installation guide to install the CLI and initialize your project
• SpecFact: Install via pip install -U specfact-cli or uvx specfact-cli@latest

For detailed installation instructions, see the respective GitHub repositories: OpenSpec and SpecFact.

Step 2: Create an OpenSpec change proposal

mkdir -p openspec/changes/modernize-billing

cat > openspec/changes/modernize-billing/proposal.md << 'EOF'
# Change: Modernize Billing Service

## Why
Reduce billing regressions and unlock contract-first validation.

## What Changes
- Add contract validation to billing endpoints
- Refactor invoice reconciliation
- Add audit trail for adjustments

## Impact
- Affected specs: billing, payments
- Affected code: src/billing/, src/payments/
EOF

cat > openspec/changes/modernize-billing/tasks.md << 'EOF'
## Implementation Tasks

- [ ] Add contract validation to billing endpoints
- [ ] Refactor invoice reconciliation
- [ ] Add audit trail for adjustments
- [ ] Add tests
EOF

Step 3: Import the legacy code into SpecFact

What this achieves: SpecFact analyzes your existing codebase to extract routes, schemas, relationships, and contracts. This creates a plan bundle that represents the current state of your code.

Use the SpecFact import slash prompt in your AI IDE (recommended for AI-assisted enrichment):

# In your AI IDE (Cursor, VS Code with Copilot, etc.)
/specfact.01-import --bundle billing-api --repo /path/to/source-code-repo

Or use the CLI directly:

specfact import from-code billing-api --repo /path/to/source-code-repo

Step 4: Sync OpenSpec proposals into the SpecFact bundle

What this achieves: SpecFact reads OpenSpec change proposals and links them to your code-derived plan bundle. This creates a bridge between your change intent (OpenSpec) and your code reality (SpecFact).

specfact sync bridge --adapter openspec --mode read-only \
  --bundle billing-api \
  --repo /path/to/openspec-repo

Step 5: Export OpenSpec proposals to GitHub Issues

What this achieves: SpecFact exports your OpenSpec change proposals as GitHub Issues, making them visible to your DevOps workflow. Optionally tracks code changes to show progress.

Use the sync-backlog slash prompt (recommended for interactive selection and sanitization):

# In your AI IDE
/specfact.sync-backlog --adapter github --target-repo your-org/your-repo \
  --repo /path/to/openspec-repo \
  --code-repo /path/to/source-code-repo \
  --track-code-changes

Or use the CLI directly:

# Basic export
specfact sync bridge --adapter github --mode export-only \
  --repo-owner your-org \
  --repo-name your-repo \
  --repo /path/to/openspec-repo

# With code change tracking (adds progress comments to issues)
specfact sync bridge --adapter github --mode export-only \
  --repo-owner your-org \
  --repo-name your-repo \
  --track-code-changes \
  --repo /path/to/openspec-repo \
  --code-repo /path/to/source-code-repo

Step 6: Enforce runtime quality gates

What this achieves: SpecFact validates that your code meets the contracts and quality gates defined in your plan bundle. This prevents regressions and ensures code matches the spec.

specfact enforce stage --preset balanced

SpecFact value-add: While OpenSpec tracks what should change, SpecFact enforces how the code actually behaves. Runtime contracts catch deviations before they reach production.

---

Flow B: Code-first (legacy repo to OpenSpec)

Start with the legacy code, let SpecFact import and enrich it, then seed OpenSpec proposals for governance and cross-team context.

Step 1: Import legacy code with AI enrichment

What this achieves: SpecFact extracts your code structure (routes, schemas, relationships) and uses AI to enrich it with business context, missing features, and acceptance criteria.

First, initialize SpecFact slash commands in your AI IDE:

specfact init --ide cursor  # or --ide vscode

Then use the import slash prompt (recommended for AI enrichment):

# In your AI IDE chat:
/specfact.01-import --bundle billing-api --repo .

The slash prompt combines CLI code extraction with AI enrichment to add missing context and features.

CLI-only fallback: If you prefer no AI enrichment, use the CLI directly:

specfact import from-code billing-api --repo .

Step 2: Review the plan bundle for gaps

What this achieves: SpecFact analyzes your plan bundle to identify missing acceptance criteria, incomplete features, and quality gaps. This helps you understand what needs attention before implementation.

specfact plan review billing-api --list-findings --findings-format table

Step 3: Export a Product Owner view and seed OpenSpec

What this achieves: SpecFact generates a human-readable proposal document from your code-derived plan. This bridges the gap between technical analysis and product planning.

specfact project export --bundle billing-api --persona product-owner --stdout \
  > /tmp/billing-api-proposal.md

mkdir -p openspec/changes/billing-modernization
cp /tmp/billing-api-proposal.md openspec/changes/billing-modernization/proposal.md

cat > openspec/changes/billing-modernization/tasks.md << 'EOF'
## Implementation Tasks

- [ ] Confirm contract coverage for billing endpoints
- [ ] Add regression tests for invoice reconciliation
- [ ] Validate audit trail and data retention rules
EOF

SpecFact value-add: OpenSpec provides the structure for change proposals, but SpecFact provides the evidence from your actual codebase. The exported proposal reflects real code analysis, not assumptions.

Step 4: Archive the change when done

Once the change is complete, archive it in OpenSpec:

openspec archive billing-modernization --yes

---

Persona-driven value

Persona	Without SpecFact	With SpecFact plus OpenSpec
Product Owner	Backlog stories drift from the real codebase	Exports a verified backlog from the actual code and anchors it in OpenSpec proposals
Agility Master	Progress is manual and subjective	GitHub issue export plus code change tracking ties commits to OpenSpec change IDs
DevOps Engineer	Specs do not block regressions	Runtime enforcement gates failures in CI with deterministic exit codes
QA Engineer	Test coverage is guesswork	Contracts and plan review expose missing acceptance criteria early

---

Proof-of-work checklist

Use these commands as a local validation sequence:

# OpenSpec-first workflow
/specfact.01-import --bundle billing-api --repo /path/to/source-code-repo
specfact sync bridge --adapter openspec --mode read-only --bundle billing-api --repo /path/to/openspec-repo
/specfact.sync-backlog --adapter github --target-repo your-org/your-repo --repo /path/to/openspec-repo --code-repo /path/to/source-code-repo
specfact enforce stage --preset balanced

# Code-first workflow
specfact init --ide cursor
/specfact.01-import --bundle billing-api --repo .
specfact plan review billing-api --list-findings --findings-format table
specfact project export --bundle billing-api --persona product-owner --stdout > /tmp/billing-api-proposal.md

---

Conclusion

OpenSpec brings clarity to intent. SpecFact brings proof to behavior. When you connect them, you get a workflow that survives real-world change: proposals are traceable, code is analyzable, and enforcement is automatic.

If your team needs accuracy, reliability, and validation beyond spec-driven vibe coding, this is the path.