From Vibe Coding to Verified Specs: How SpecFact Completes the SDD Workflow in DevSecOps

TL;DR: Spec-Driven Development tools (OpenSpec, Spec-Kit) create specs, but SpecFact enforces them. This article shows how SpecFact integrates into agile workflows (Scrum/Kanban), addresses common fears through analysis-only mode and gradual adoption, and provides executable contracts that bridge the gap between intent and implementation. Includes real-world scenarios for different team maturity levels and persona-specific workflows.

Introduction: The SDD Landscape

Spec-Driven Development (SDD) has emerged as a powerful methodology for building software with clear intent. Tools like OpenSpec and Spec-Kit help teams create comprehensive specifications through structured workflows.

However, there's a critical gap: What happens after implementation? How do you ensure specs stay aligned with code?

This is where SpecFact comes in. While SDD tools create specs, SpecFact enforces them through executable contracts, automated drift detection, and CI/CD integration.

Reference: This article is inspired by Hari Krishnan's excellent work on SDD tools and extends the conversation to include enforcement and agile workflow integration.

The Standard SDD Workflow (Without Enforcement)

Most SDD tools follow a four-phase workflow:

Specify → Plan → Tasks → Implement

But what happens after implementation?

The Problem: Specs are created, but there's no automated enforcement to prevent drift or catch regressions.

The Vibe Coding Anti-Pattern

Before diving into solutions, let's examine the anti-pattern that SpecFact helps prevent: vibe coding.

Reference: Hari Krishnan's analysis of vibe coding vs SDD

Problems with Vibe Coding:

• ❌ No executable specs to validate against
• ❌ No contract enforcement to catch regressions
• ❌ Relies on human review (error-prone)
• ❌ Spec drift goes undetected

SpecFact-Enhanced SDD Workflow

SpecFact adds the missing enforcement layer to the SDD workflow:

Key Additions:

• ✅ Contract decorators added to code (beartype, icontract) - Required in v0.22.1
• ✅ Pre-commit validation
• ✅ CI/CD enforcement gates
• ✅ Runtime monitoring

Analysis-Only Mode: Zero-Risk Exploration

Critical for Adoption: Many teams fear modifying production code. SpecFact supports analysis-only workflows that require zero code modification and provide immediate value without risk.

Analysis-Only Commands (Zero Code Modification)

# 1. Reverse engineer codebase (read-only analysis)
specfact import from-code legacy-api --repo .

# 2. Review extracted plan (no code changes)
specfact plan review legacy-api

# 3. Compare code vs. plan (drift detection)
specfact plan compare --code-vs-plan

# 4. Analyze contract coverage (read-only)
specfact analyze contracts --bundle legacy-api

# 5. Generate reports (documentation only)
# Reports saved to .specfact/projects/legacy-api/reports/

Value Without Risk:

• ✅ Zero code modification - All analysis is read-only
• ✅ Immediate insights - Discover undocumented features, gaps, drift
• ✅ Documentation generation - Auto-generate specs from code
• ✅ Risk assessment - Identify high-risk areas before changes
• ✅ Sprint planning - Use extracted features for backlog refinement

Real-World Example: Analysis-Only Success

Scenario: Mid-size fintech team, 5-year-old Django app, team fearful of breaking payment system

Week 1 (Analysis-Only):

# Zero code changes, just analysis
specfact import from-code payment-api --repo .
specfact plan review payment-api
# Discovered: 23 undocumented features, 8 critical gaps

Outcome:

• ✅ Generated comprehensive documentation
• ✅ Identified high-risk areas (payment processing, fraud detection)
• ✅ Created backlog items from discovered features
• ✅ Zero production risk - no code modified
• ✅ Team confidence increased (saw value without risk)

Agile Workflow Integration: Scrum & Kanban

Real-World Context: SpecFact integrates seamlessly with existing agile workflows without disrupting team processes.

Scrum Integration

Scrum Personas & SpecFact Usage

Kanban Integration

Kanban Benefits:

• WIP Limits: Contract validation prevents over-commitment
• Flow Metrics: Drift detection shows bottlenecks
• Continuous Delivery: Automated gates enable faster releases

Addressing Common Biases and Fears

Real-World Concerns: Teams often have legitimate concerns about introducing new tools. Here's how SpecFact addresses them:

Bias 1: "We Don't Have Time for This"

Concern: "Adding contracts will slow us down"

Reality Check:

• ✅ Analysis-only mode: Immediate value, zero time cost (read-only)
• ✅ AI-assisted: /specfact.07-contracts automates contract addition
• ✅ Incremental: Start with new code only, legacy untouched
• ✅ Time saved: Prevents bugs that would take hours to debug

Real-World Example:

• Time invested: 30 minutes for analysis, 2 hours for contract addition (first module)
• Time saved: Prevented 4 production bugs (estimated 8 hours debugging each = 32 hours saved)
• ROI: 32 hours saved vs. 2.5 hours invested = 12.8x return

Bias 2: "It Will Break Our Existing Code"

Concern: "Adding decorators might break production"

Reality Check:

• ✅ Analysis-first: Understand codebase before changes
• ✅ Validation loop: 7-step validation before applying contracts
• ✅ Test-first: All tests must pass before commit
• ✅ Gradual adoption: Start with new code, then critical paths
• ✅ Rollback ready: Git commits allow easy rollback

Bias 3: "We Already Have Tests"

Concern: "Why do we need contracts if we have tests?"

Reality Check:

• ✅ Contracts complement tests: Tests verify behavior, contracts verify structure
• ✅ Faster feedback: Contracts catch issues before tests run
• ✅ Edge case discovery: CrossHair finds cases tests miss
• ✅ Documentation: Contracts document assumptions

Bias 4: "It's Too Complex for Our Team"

Concern: "Our junior developers won't understand contracts"

Reality Check:

• ✅ Analysis-only mode: No complexity, just run commands
• ✅ AI assistance: /specfact.07-contracts guides contract addition
• ✅ Gradual learning: Start simple, learn incrementally
• ✅ Documentation: Auto-generated from code

Bias 5: "We Can't Modify Legacy Code"

Concern: "Our legacy code is too risky to modify"

Reality Check:

• ✅ Analysis-only: Zero modification, immediate value
• ✅ New code first: Legacy untouched, new code protected
• ✅ Critical paths only: Modify only high-value modules
• ✅ Future: Sidecar container (zero modification) coming soon

Gradual Adoption Strategies: From Fear to Confidence

Real-World Scenario: Teams often fear modifying production code. SpecFact supports incremental adoption that builds confidence gradually.

Strategy 1: Analysis-Only Phase (Weeks 1-2)

Goal: Understand codebase without any changes

# Week 1: Discovery
specfact import from-code legacy-api --repo .
specfact plan review legacy-api

# Week 2: Gap Analysis
specfact plan compare --code-vs-plan
specfact analyze contracts --bundle legacy-api

Outcomes:

• ✅ Discovered 19 undocumented features
• ✅ Identified 24 drift issues
• ✅ Generated documentation automatically
• ✅ Zero code changes - No risk

Team Confidence: Low → Medium (seeing value without risk)

Strategy 2: New Code Only (Weeks 3-4)

Goal: Add contracts to new features only (no legacy modification)

# New feature development
specfact generate contracts-prompt src/new_feature.py --bundle legacy-api --apply all-contracts
# Add decorators to NEW code only

Outcomes:

• ✅ New features have contracts
• ✅ Legacy code unchanged
• ✅ Gradual improvement

Team Confidence: Medium → High (proven value, low risk)

Strategy 3: Critical Paths Only (Weeks 5-6)

Goal: Add contracts to high-risk legacy modules

# Identify critical modules
specfact analyze contracts --bundle legacy-api
# Add contracts to payment/auth modules only
specfact generate contracts-prompt src/payment.py --bundle legacy-api --apply all-contracts

Outcomes:

• ✅ Critical paths protected
• ✅ Incremental safety improvement
• ✅ Team comfortable with process

Team Confidence: High → Very High (proven safety)

Strategy 4: Full Enforcement (Week 7+)

Goal: Complete contract coverage

# Full enforcement
specfact enforce stage --preset balanced
specfact repro --verbose

Outcomes:

• ✅ Complete coverage
• ✅ Automated gates active
• ✅ Production-ready

Team Confidence: Very High (full adoption)

Real-World Scenarios: Different Maturity Levels

Scenario A: Startup Team (Low Maturity, High Fear)

Context: 3-person team, legacy Django app, no tests, fear of breaking production

Team Concerns:

• "We can't afford to break production"
• "We don't have time for extensive testing"
• "What if contracts break existing functionality?"

Approach: Analysis-only for 2 weeks, then new code only

Sprint 1 (Analysis-Only):

# Week 1-2: Analysis only (zero risk)
specfact import from-code legacy-api --repo .
specfact plan review legacy-api
specfact plan compare --code-vs-plan
# Share findings in standup, no code changes

Sprint 1 Outcomes:

• ✅ Discovered 19 undocumented features
• ✅ Generated documentation automatically
• ✅ Identified 3 high-risk areas
• ✅ Zero production risk (no legacy code changes)
• ✅ Team confidence increased (saw value without risk)

Team Feedback: "We started with zero risk analysis, saw immediate value, then gradually added contracts. No production incidents."

Scenario B: Mid-Size Team (Medium Maturity, Moderate Fear)

Context: 10-person team, some tests, CI/CD exists, cautious about changes

Approach: Gradual adoption with validation gates

Phase 1: Analysis + CI/CD Warnings (Sprint 1-2)

# Analysis-only first
specfact import from-code legacy-api --repo .
specfact plan review legacy-api

# Add to CI/CD: warnings only (no blocks)
specfact enforce stage --preset minimal
# GitHub Actions: warnings logged, PRs still merge

Phase 1 Outcomes:

• ✅ Discovered gaps in existing tests
• ✅ CI/CD warnings highlighted issues (no blocks)
• ✅ Team saw value without disruption
• ✅ No workflow changes required

Team Feedback: "Gradual adoption worked perfectly. We started with warnings, saw value, then increased enforcement. Zero disruption."

Scenario C: Enterprise Team (High Maturity, Low Fear)

Context: 50-person team, comprehensive tests, mature CI/CD, architecture focus

Approach: Full adoption with architecture contracts

Sprint 1: Analysis & Architecture Definition

# Complete analysis
specfact import from-code legacy-api --repo .
specfact plan review legacy-api
specfact analyze contracts --bundle legacy-api

# Define architecture contracts
# Create SDD manifest with architecture patterns

Sprint 1 Outcomes:

• ✅ Complete codebase analysis
• ✅ Architecture patterns identified
• ✅ Compliance requirements documented
• ✅ Audit trail established

Team Feedback: "SpecFact provides the architectural compliance layer we needed. Automated enforcement ensures all teams follow patterns."

Validation-First Approach: Building Trust

Critical Principle: Never modify code without validation. SpecFact enforces this through a validation-first workflow.

Validation Steps:

1. Analysis Validation (No Code Changes): Review extracted plan before proceeding
2. Contract Prompt Validation (No Code Changes): Review prompt file before applying
3. Contract Application Validation (Code Changes): Use AI IDE with 7-step validation loop
4. Pre-Commit Validation (Before Commit): Pre-commit hook validates
5. CI/CD Validation (Before Merge): GitHub Actions validates

Trust Building:

• ✅ Every step is validated before proceeding
• ✅ No code changes without review
• ✅ Tests must pass before commit
• ✅ CI/CD blocks invalid code

Working with Existing Code: Two Approaches

Critical Understanding: SpecFact works with existing (brownfield) code, but runtime contract enforcement requires one of two approaches.

Approach A: Contract Decorators (Current - v0.22.1)

Flow: Code → Analysis → Contract Prompts → Add Decorators → Enforcement

# Before: Legacy code (no contracts)
def process_payment(request):
    user = get_user(request.user_id)
    payment = create_payment(user.id, request.amount)
    return JsonResponse(["'status': 'success'"])

# After: With SpecFact contracts
@icontract.require(lambda request: request.user_id is not None)
@icontract.require(lambda request: request.amount > 0)
@icontract.ensure(lambda result: result['status'] == 'success')
@beartype
def process_payment(request: HttpRequest) -> JsonResponse:
    user = get_user(request.user_id)
    payment = create_payment(user.id, request.amount)
    return JsonResponse(["'status': 'success'"])

Workflow:

1. specfact import from-code - Analyzes code (no modification)
2. specfact generate contracts-prompt - Creates AI IDE prompt (no modification)
3. AI IDE adds decorators using /specfact.07-contracts (code modification required)
4. Contracts enforced at runtime

Pros:

• ✅ Available now (v0.22.1)
• ✅ Full contract enforcement
• ✅ Works with any Python codebase
• ✅ Integrated with CI/CD

Cons:

• ⚠️ Requires code modification (adding decorators)
• ⚠️ May need to update existing code incrementally

Approach B: Sidecar Container (Future - Early Research)

Flow: Code → Sidecar Container → Runtime Enforcement (No Code Changes)

Status:

• 🔬 Early research phase - Not officially built-in to v0.22.1
• 📋 See SpecFact CLI GitHub Issues for progress
• 🚀 Will enable contract enforcement without modifying source code
• ⏳ Integration timeline: TBD (check GitHub issues for updates)

Use Case: When code modification is not possible (vendor code, read-only systems, third-party libraries, etc.)

Key Takeaways

1. SDD Tools Create Specs, SpecFact Enforces Them
   • OpenSpec/Spec-Kit: Intent and documentation
   • SpecFact: Evidence and enforcement
2. Executable Contracts Bridge the Gap
   • From markdown specs to runtime validation
   • From human review to automated gates
3. CI/CD Integration is Critical
   • Pre-commit hooks catch issues early
   • GitHub Actions block bad PRs automatically
   • Runtime monitoring prevents production issues
4. Brownfield-First Approach with Gradual Adoption
   • Works with existing codebases
   • Analysis-only mode: Zero code modification, immediate value
   • Gradual adoption: Start with analysis → new code → critical paths → full enforcement
   • Current (v0.22.1): Contract enforcement requires adding decorators, but analysis requires none
   • Future: Sidecar container approach (zero code modification) in early research phase
   • Validation-first: Every step validated before proceeding
   • No greenfield requirement - can start with legacy code safely
5. Agile Workflow Integration
   • Scrum: Fits into sprint planning, daily standups, sprint reviews
   • Kanban: Supports WIP limits, flow metrics, continuous delivery
   • Persona-specific: Different approaches for junior/mid/senior engineers
   • Fear mitigation: Analysis-only mode builds confidence before code changes
6. Validation-First Principle
   • Every step validated before proceeding
   • No code changes without review
   • Tests must pass before commit
   • CI/CD blocks invalid code automatically

Getting Started: Choose Your Path

Path Selection Guide:

Path 1: Analysis-Only (Zero Risk, Immediate Value)

# 1. Install SpecFact (v0.22.1)
pip install specfact-cli

# 2. Analyze codebase (read-only, no changes)
specfact import from-code legacy-api --repo .

# 3. Review extracted plan
specfact plan review legacy-api

# 4. Detect drift (analysis only)
specfact plan compare --code-vs-plan

# 5. Analyze contract coverage (read-only)
specfact analyze contracts --bundle legacy-api

# Result: Documentation, insights, zero code changes

Path 2: Gradual Adoption (Low Risk, Incremental Value)

# Week 1: Analysis only (see Path 1)

# Week 2: New code only
specfact generate contracts-prompt src/new_feature.py --bundle legacy-api --apply all-contracts
# Add decorators to NEW code only

# Week 3: Critical paths
specfact generate contracts-prompt src/payment.py --bundle legacy-api --apply all-contracts
# Add decorators to critical modules

# Week 4+: Full enforcement
specfact enforce stage --preset balanced

Path 3: Full Integration (Medium Risk, Complete Value)

# 1. Install SpecFact (v0.22.1)
pip install specfact-cli

# 2. Import from OpenSpec or Spec-Kit
specfact import from-bridge --adapter openspec --repo .
# OR
specfact import from-bridge --adapter speckit --repo .

# 3. Generate contract prompts
specfact generate contracts-prompt src/your_module.py --bundle your-bundle --apply all-contracts

# 4. Use AI IDE to add contract decorators
# Use /specfact.07-contracts slash command for automated contract addition

# 5. Set up pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
specfact --no-banner enforce stage --preset balanced
specfact --no-banner repro --fail-fast
EOF
chmod +x .git/hooks/pre-commit

# 6. Add to GitHub Actions
# .github/workflows/specfact-enforce.yml

Conclusion

SpecFact completes the SDD workflow by adding the missing enforcement layer. Through analysis-only mode, gradual adoption strategies, and validation-first approaches, teams can safely integrate contract enforcement into their agile workflows without fear or disruption.

Whether you're a startup team fearful of breaking production, a mid-size team looking to improve quality, or an enterprise team needing architectural compliance, SpecFact provides a path that matches your maturity level and risk tolerance.

Start with analysis-only mode to see immediate value without any code changes. Then, when you're ready, gradually adopt contract enforcement following the strategies outlined in this article.

For more information, visit:

• SpecFact CLI GitHub Repository
• OpenSpec GitHub Repository
• Spec-Kit GitHub Repository
• Hari Krishnan's SDD Tools Blog