Brownfield-first legacy code modernization with runtime contract enforcement.
Analyze existing Python code → Extract specs → Find gaps → Enforce contracts → Prevent regressions
No API keys required. Works offline. Zero vendor lock-in.
- specfact.com - Commercial landing page (marketing, pricing, enterprise)
- specfact.io - Product ecosystem hub (CLI reference, integrations, changelog, product docs)
- specfact.dev - Developer community (tutorials, guides, blog, community content) ⭐ For developers
- docs.specfact.io - Complete online documentation
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.
AI coding assistants are powerful but unpredictable when requirements live in chat history. SpecFact adds a brownfield-first analysis workflow that understands existing code, extracts specs automatically, and enforces them as runtime contracts, giving you deterministic, reviewable outputs.
Key outcomes:
- Understand legacy code in minutes, not weeks (automatic spec extraction)
- Find gaps in tests, contracts, and documentation automatically
- Prevent regressions with runtime contract enforcement during modernization
- Works with the tools you already use: VS Code, Cursor, GitHub Actions, pre-commit hooks
- No API keys required - Works completely offline
# Zero-install (recommended - no setup needed)
uvx specfact-cli@latest
# Or install globally
pip install -U specfact-cliSet up slash commands in your IDE (Cursor, VS Code, Copilot, etc.):
# Auto-detect IDE and initialize
specfact init
# Or specify IDE explicitly
specfact init --ide cursor
specfact init --ide vscode
# Install required packages for contract enhancement
specfact init --ide cursor --install-depsWhat this does:
- Copies prompt templates to your IDE
- Makes slash commands available in your IDE's AI chat
- Optionally installs required packages (
beartype,icontract,crosshair-tool,pytest)
In your IDE's AI chat, use the slash command:
# In IDE chat (Cursor, VS Code, Copilot, etc.)
/specfact.01-import my-project --repo .Or use the CLI directly:
# Analyze legacy codebase (most common use case)
specfact import from-code my-project --repo .⏱️ Timing: Analysis typically takes 10-15 minutes for typical repositories (e.g., specfact-cli itself with several hundred features & contracts). Smaller codebases may complete in 2-5 minutes. The analysis performs AST parsing, Semgrep pattern detection, and Specmatic integration.
That's it! SpecFact will extract features and stories from your code, find missing tests and contracts, and generate a plan bundle you can enforce.
👉 Getting Started Guide - Complete walkthrough with examples
👉 AI IDE Workflow Guide ⭐ - Complete AI-assisted development workflow
Primary Goal: Analyze legacy Python → find gaps → enforce contracts
- Getting Started - Install and run your first command
- Command Chains Reference ⭐ NEW - Complete workflows from start to finish
- Common Tasks Quick Reference ⭐ NEW - Quick answers to "How do I X?"
- Modernizing Legacy Code? ⭐ - Brownfield-first guide
- The Brownfield Journey ⭐ - Complete modernization workflow
Time: < 10 minutes | Result: Running your first brownfield analysis
Primary Goal: Let SpecFact find gaps, use your AI IDE to fix them
👉 AI IDE Workflow Guide ⭐ NEW - Complete AI-assisted development workflow
Primary Goal: Enable team collaboration with role-based workflows
👉 Agile/Scrum Workflows ⭐ - Persona-based team collaboration
Primary Goal: Integrate with Spec-Kit, OpenSpec, Specmatic, or DevOps tools
👉 Integrations Overview ⭐ NEW - Complete guide to all integrations
- Reverse engineer legacy code into documented specs
- Find gaps in tests, contracts, and documentation
- Works with any Python project (no special setup required)
👉 Command Chains - See complete workflows
- Prevent regressions with runtime contract validation
- CI/CD integration - Block bad code from merging
- Works offline - No cloud required
👉 Command Reference - All enforcement commands
- Role-based workflows - Product Owners, Architects, Developers work in parallel
- Markdown-based - No YAML editing required
- Agile/scrum ready - DoR checklists, story points, dependencies
👉 Agile/Scrum Workflows - Team collaboration guide
- 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
- Spec-Kit, OpenSpec, Specmatic - Works with your existing tools
👉 Integrations Overview - All integration options
Problem: Existing codebase with no specs or outdated documentation
👉 Brownfield Modernization Guide - Complete walkthrough
Problem: Need team collaboration with role-based workflows
👉 Agile/Scrum Workflows Guide - Team collaboration guide
Problem: Want AI to fix gaps, but need validation
👉 AI IDE Workflow Guide - Complete AI-assisted workflow
Problem: Want to use SpecFact with Spec-Kit, OpenSpec, or Specmatic
👉 Integrations Overview - Choose the right integration
- Command Chains ⭐ NEW - Complete workflows from start to finish
- Common Tasks ⭐ NEW - Quick answers to "How do I X?"
- Command Reference - All commands documented
- Getting Started Guide - Install and first commands
- Modernizing Legacy Code? ⭐ - Brownfield-first guide
- The Brownfield Journey ⭐ - Complete modernization workflow
- AI IDE Workflow ⭐ NEW - AI-assisted development
- Agile/Scrum Workflows ⭐ - Team collaboration
- Integrations Overview ⭐ NEW - All integrations
- Use Cases - Common scenarios
- Spec-Kit Journey - From Spec-Kit to SpecFact
- OpenSpec Journey - OpenSpec integration
- Specmatic Integration - API contract testing
- DevOps Adapter Integration - GitHub Issues, Linear, Jira
👉 Full Documentation Index - Browse all documentation
👉 Online Documentation - Complete documentation site
New to spec-driven development? Here's how SpecFact compares to other tools:
| Tool | Best For | SpecFact's Focus |
|---|---|---|
| GitHub Spec-Kit | Greenfield specs, multi-language, interactive authoring | Brownfield analysis, runtime enforcement, formal verification |
| OpenSpec | Specification anchoring, change tracking, cross-repo workflows | Code analysis, contract enforcement, DevOps integration |
| Traditional Testing | Manual test writing, code review | Automated gap detection, contract-first validation, CI/CD gates |
Key Differentiators:
- ✅ Brownfield-first - Reverse engineers existing code (primary use case)
- ✅ Runtime enforcement - Contracts prevent regressions automatically
- ✅ Formal verification - CrossHair symbolic execution (not just LLM suggestions)
- ✅ Team collaboration - Role-based workflows for agile/scrum teams
- ✅ Works offline - No API keys, no cloud, zero vendor lock-in
👉 See detailed comparison guide - Understand when to use SpecFact, Spec-Kit, OpenSpec, or all together
- ✅ 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-fullApache 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
- 💬 Questions? GitHub Discussions
- 🐛 Found a bug? GitHub Issues
- 📧 Need help? [email protected]
- 🌐 Learn more: specfact.com • specfact.io • specfact.dev
Built with ❤️ by NOLD AI
Copyright © 2025-2026 Nold AI (Owner: Dominikus Nold)
Trademarks: NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). All other trademarks mentioned in this project are the property of their respective owners. See TRADEMARKS.md for more information.