Stop vibe coding. Start shipping quality code with contracts.
Analyze legacy Python code → Find gaps → Enforce contracts → Prevent regressions

SpecFact CLI analyzes your existing Python code to automatically extract specifications, find missing tests and contracts, and enforce them to prevent bugs during modernization.

Perfect for: Teams modernizing legacy Python systems who can't afford production bugs during migration.

• ❌ Legacy code with no documentation or outdated specs
• ❌ Missing tests and contracts that should exist
• ❌ Regressions introduced during refactoring/modernization
• ❌ No safety net to catch bugs before production

SpecFact CLI:

1. Analyzes your existing code → Extracts specs automatically
2. Finds gaps → Missing tests, contracts, documentation
3. Enforces contracts → Prevents regressions with runtime validation
4. Integrates → Works with VS Code, Cursor, GitHub Actions, pre-commit hooks

Works offline. No account required. Zero vendor lock-in.

graph TB
    subgraph "Your Legacy Code"
        LC[Legacy Python Code<br/>No docs, no tests]
    end
    
    subgraph "SpecFact Analysis"
        A1[import from-code<br/>Extract specs]
        A2[Find Gaps<br/>Missing tests & contracts]
        A3[Generate Plan Bundle<br/>Features & Stories]
    end
    
    subgraph "Contract Enforcement"
        E1[Add Contracts<br/>Runtime validation]
        E2[Enforce SDD<br/>Quality gates]
        E3[CI/CD Integration<br/>Block bad code]
    end
    
    subgraph "Team Collaboration"
        T1[Export by Role<br/>PO, Architect, Dev]
        T2[Markdown Workflows<br/>No YAML editing]
        T3[Sync to DevOps<br/>GitHub, Linear, Jira]
    end
    
    subgraph "Safety Net"
        S1[Prevent Regressions<br/>Catch bugs early]
        S2[Modernize Safely<br/>Refactor with confidence]
    end
    
    LC -->|Step 1| A1
    A1 --> A2
    A2 --> A3
    A3 -->|Step 2| E1
    E1 --> E2
    E2 --> E3
    E3 -->|Step 3| S1
    S1 --> S2
    
    A3 -->|Optional| T1
    T1 --> T2
    T2 --> T3
    
    style LC fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
    style A1 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff
    style A2 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff
    style A3 fill:#f97316,stroke:#c2410c,stroke-width:2px,color:#fff
    style E1 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff
    style E2 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff
    style E3 fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff
    style T1 fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff
    style T2 fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff
    style T3 fill:#10b981,stroke:#047857,stroke-width:2px,color:#fff
    style S1 fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff
    style S2 fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff

sequenceDiagram
    participant Dev as Developer
    participant SF as SpecFact CLI
    participant Code as Legacy Code
    participant CI as CI/CD
    
    Note over Dev,CI: Step 1: Analyze Legacy Code
    Dev->>SF: specfact import from-code my-project
    SF->>Code: Analyze Python files
    Code-->>SF: Extract features & stories
    SF-->>Dev: Plan bundle created
    
    Note over Dev,CI: Step 2: Find & Fix Gaps
    Dev->>SF: specfact analyze gaps my-project
    SF-->>Dev: Missing tests & contracts found
    Dev->>Dev: Add tests & contracts
    
    Note over Dev,CI: Step 3: Enforce Contracts
    Dev->>SF: specfact enforce sdd my-project
    SF->>SF: Validate contracts
    SF-->>Dev: Quality gates configured
    
    Note over Dev,CI: Step 4: Modernize Safely
    Dev->>Code: Refactor code
    Code->>CI: Push changes
    CI->>SF: Run contract validation
    SF-->>CI: ✅ Pass or ❌ Block
    
    alt Contracts Pass
        CI-->>Dev: ✅ Merge allowed
    else Contracts Fail
        CI-->>Dev: ❌ Merge blocked
        Dev->>Code: Fix violations
    end

# Zero-install (recommended - no setup needed)
uvx specfact-cli@latest

# Or install globally
pip install -U specfact-cli

Analyze your existing code:

# Analyze legacy codebase (most common use case)
specfact import from-code my-project --repo .

# Or start a new project
specfact plan init my-project --interactive

That's it! SpecFact will:

• Extract features and stories from your code
• Find missing tests and contracts
• Generate a plan bundle you can enforce

👉 Getting Started Guide - Complete walkthrough with examples

• Reverse engineer legacy code into documented specs
• Find gaps in tests, contracts, and documentation
• Works with any Python project (no special setup required)

• Prevent regressions with runtime contract validation
• CI/CD integration - Block bad code from merging
• Works offline - No cloud required

• Role-based workflows - Product Owners, Architects, Developers work in parallel
• Markdown-based - No YAML editing required
• Agile/scrum ready - DoR checklists, story points, dependencies

• VS Code, Cursor - Catch bugs before you commit
• GitHub Actions - Automated quality gates
• AI IDEs - Generate prompts for fixing gaps
• DevOps tools - Sync with GitHub Issues, Linear, Jira

Problem: Existing codebase with no specs or outdated documentation

# Step 1: Analyze your code
specfact import from-code my-project --repo .

# Step 2: Review what was found
specfact plan review my-project

# Step 3: Enforce contracts to prevent regressions
specfact enforce sdd my-project

👉 Brownfield Modernization Guide - Complete walkthrough

Problem: Need team collaboration with role-based workflows

# Product Owner: Export backlog
specfact project export --bundle my-project --persona product-owner

# Architect: Export technical design
specfact project export --bundle my-project --persona architect

# Developer: Export implementation tasks
specfact project export --bundle my-project --persona developer

👉 Agile/Scrum Workflows Guide - Team collaboration guide

Problem: Want AI to fix gaps, but need validation

# Step 1: Find gaps
specfact analyze gaps --bundle my-project

# Step 2: Generate AI prompt
specfact generate fix-prompt GAP-001 --bundle my-project

# Step 3: Copy to AI IDE → AI fixes → Validate
specfact enforce sdd --bundle my-project

👉 AI IDE Integration - Setup guide

We ran SpecFact CLI on itself to prove it works:

• ⚡ Analyzed 32 legacy Python files → Found 32 features and 81 stories in 3 seconds
• 🚫 Set enforcement → Blocked 2 HIGH violations automatically
• 📊 Compared plans → Found 24 deviations in 5 seconds

Total time: < 10 seconds | Result: Found real bugs and inconsistencies

👉 Read the complete example - See actual commands and outputs

New to SpecFact?

1. Getting Started - Install and first commands
2. Modernizing Legacy Code? ⭐ - Complete guide
3. Use Cases - Common scenarios
4. Command Reference - All commands

Working with a Team?

• Agile/Scrum Workflows ⭐ - Persona-based collaboration
• Project Commands - Export/import workflows

Want Integrations?

• IDE Integration - VS Code, Cursor setup
• Integration Showcases - Real bugs fixed
• GitHub Actions - CI/CD setup

Advanced Topics

• Architecture - How it works
• Schema Versioning - Bundle schemas
• Testing Guide - Development setup

👉 Full Documentation Index - Browse all documentation

Latest release introduces change tracking data models (v1.1 schema) and code change tracking with progress comments.

What's New:

• ✅ Change tracking data models for delta spec tracking
• ✅ Code change tracking with GitHub issue progress comments
• ✅ DevOps backlog tracking integration (GitHub Issues, ADO, Linear, Jira)
• ✅ OpenSpec bridge adapter support

👉 Changelog - Complete release history

• ✅ No new platform - Pure CLI, works offline
• ✅ No account required - Fully local, zero vendor lock-in
• ✅ Integrates everywhere - VS Code, Cursor, GitHub Actions, pre-commit hooks

• ✅ Role-based workflows - Product Owners, Architects, Developers work in parallel
• ✅ Markdown-based - No YAML editing, human-readable conflicts
• ✅ Agile/scrum ready - DoR checklists, story points, sprint planning

• ✅ Catches real bugs - See Integration Showcases
• ✅ Prevents regressions - Runtime contract enforcement
• ✅ Works on legacy code - Analyzed itself successfully

We welcome contributions! See CONTRIBUTING.md for guidelines.

git clone https://github.com/nold-ai/specfact-cli.git
cd specfact-cli
pip install -e ".[dev]"
hatch run contract-test-full

Apache License 2.0 - Open source and enterprise-friendly

• ✅ Free to use for any purpose (commercial or non-commercial)
• ✅ Modify and distribute as needed
• ✅ Enterprise-friendly with explicit patent grant

Full license

• 💬 Questions? GitHub Discussions
• 🐛 Found a bug? GitHub Issues
• 📧 Need help? hello@noldai.com
• 🌐 Learn more: noldai.com