Spec-Kit Journey: Interactive Specs With Deterministic Enforcement

TL;DR: Spec-Kit is great for fast, interactive specs. SpecFact is built for brownfield analysis and deterministic enforcement. This guide shows two verified paths: Spec-Kit-first (import and enforce) and code-first (import legacy code, then export back to Spec-Kit).

Why Spec-Kit plus SpecFact

Spec-Kit makes it easy to specify new features with slash commands. SpecFact makes it safe to modernize legacy code with contracts, plan review, and enforcement gates. Together, you keep the speed of Spec-Kit while eliminating drift, regressions, and guesswork.

---

Flow A: Spec-Kit-first (interactive specs to enforcement)

Start with Spec-Kit artifacts, then let SpecFact import and enforce them.

Step 1: Set up Spec-Kit and SpecFact

Before starting, ensure you have both tools installed:

• Spec-Kit: Follow the Spec-Kit installation guide to initialize your project with slash commands
• SpecFact: Install via pip install -U specfact-cli or uvx specfact-cli@latest

For detailed installation instructions, see the respective GitHub repositories: Spec-Kit and SpecFact.

Step 2: Author specs in Spec-Kit

What this achieves: Spec-Kit helps you quickly create specifications, plans, and tasks using interactive slash commands in your AI IDE.

# In GitHub Copilot chat (or other supported AI IDE)
/speckit.specify --feature "User Authentication"
/speckit.plan --feature "User Authentication"
/speckit.tasks --feature "User Authentication"

Step 3: Import the Spec-Kit project into SpecFact

What this achieves: SpecFact imports your Spec-Kit artifacts and converts them into a plan bundle with contracts, relationships, and enforcement capabilities. This bridges interactive spec creation with deterministic validation.

Use the sync slash prompt (recommended for bidirectional sync):

# In your AI IDE
/specfact.06-sync --adapter speckit --repo /path/to/speckit-repo --bidirectional

Or use the CLI directly:

# Import Spec-Kit project
specfact sync bridge --adapter speckit --repo /path/to/speckit-repo

Step 4: Review the generated plan bundle

What this achieves: SpecFact analyzes your imported plan to identify gaps, missing acceptance criteria, and quality issues. This helps you refine your specs before implementation.

specfact plan review main

Step 5: Keep Spec-Kit and SpecFact in sync

What this achieves: Bidirectional sync ensures changes in Spec-Kit are reflected in SpecFact, and vice versa. Watch mode keeps them synchronized automatically.

specfact sync bridge --adapter speckit --bundle main --repo . --bidirectional --watch --interval 5

Step 6: Enforce contracts in CI

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

specfact enforce stage --preset balanced

Step 7: Detect code vs plan drift

What this achieves: SpecFact compares your actual code against the plan bundle to detect deviations. This helps you catch when implementation drifts from the spec.

specfact plan compare --code-vs-plan

Note: Drift detection requires a code-derived bundle (created via specfact import from-code). In Spec-Kit-first workflows, this is most useful after you've implemented code and want to verify it matches the spec. For code-first workflows, drift detection works immediately after importing code.

SpecFact value-add: Spec-Kit excels at fast, interactive spec creation. SpecFact adds enforcement and validation—ensuring your specs are not just documented, but actually enforced in your codebase.

---

Flow B: Code-first (legacy repo to Spec-Kit)

Start with legacy code, use SpecFact to extract and enrich plans, then export to Spec-Kit for ongoing collaboration.

Step 1: Import legacy code with AI enrichment

What this achieves: SpecFact analyzes your existing codebase to extract structure, relationships, and contracts. AI enrichment adds missing context and features that weren't obvious from code alone.

First, initialize SpecFact slash commands:

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

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

# In the AI IDE chat:
/specfact.01-import --bundle legacy-portal --repo .

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

CLI-only fallback: If you prefer no AI enrichment:

specfact import from-code legacy-portal --repo .

Step 2: Export to Spec-Kit format

What this achieves: SpecFact converts your code-derived plan bundle into Spec-Kit format, making it available for interactive collaboration. Bidirectional sync keeps both systems in sync.

Use the sync slash prompt (recommended):

# In your AI IDE
/specfact.06-sync --adapter speckit --bundle legacy-portal --repo . --bidirectional

Or use the CLI directly:

specfact sync bridge --adapter speckit --bundle legacy-portal --repo . --bidirectional

Step 3: Continue working in Spec-Kit

What this achieves: Once exported, you can use Spec-Kit's interactive slash commands to refine and extend the plan. Changes sync back to SpecFact automatically.

/speckit.specify --feature "Audit Trails"
/speckit.plan --feature "Audit Trails"
/speckit.tasks --feature "Audit Trails"

SpecFact value-add: Spec-Kit is great for collaborative spec refinement, but SpecFact provides the grounding—your specs start from actual code analysis, not assumptions. This ensures your interactive specs reflect reality.

---

Persona-driven value

Persona	Without SpecFact	With SpecFact plus Spec-Kit
Product Owner	Stories are optimistic and unverified	Plans are derived from actual code, then refined with Spec-Kit
Agility Master	Team velocity is based on subjective status	SpecFact plan review and compare expose real progress and drift
DevOps Engineer	Spec artifacts do not gate releases	Quality gates enforce contracts before merge or deploy
QA Engineer	Edge cases rely on manual test design	Contracts and symbolic checks reveal missing scenarios early

---

Proof-of-work checklist

Use these commands as a local validation sequence:

# Spec-Kit-first workflow
/specfact.06-sync --adapter speckit --repo /path/to/speckit-repo --bidirectional
specfact plan review main
specfact sync bridge --adapter speckit --bundle main --repo . --bidirectional --watch --interval 5
specfact enforce stage --preset balanced
specfact plan compare --code-vs-plan

# Code-first workflow
specfact init --ide cursor
/specfact.01-import --bundle legacy-portal --repo .
/specfact.06-sync --adapter speckit --bundle legacy-portal --repo . --bidirectional

---

Conclusion

Spec-Kit gives you speed. SpecFact gives you safety. The combined flow keeps your specs collaborative and your codebase verified, which is exactly what modern modernization programs need.

Stop relying on spec-driven vibe coding. Start shipping with contracts, evidence, and shared plans.