The "swiss knife" CLI that turns any codebase into a clear, safe, and shippable workflow. Keep backlog, specs, tests, and code in sync so AI-assisted changes do not break production. Works for brand-new projects and long-lived codebases - even if you are new to coding.
No API keys required. Works offline. Zero vendor lock-in.
# Zero-install (recommended)
uvx specfact-cli@latest
# Or install globally
pip install -U specfact-cli# Bootstrap module registry and local config (~/.specfact)
specfact init
# Configure IDE prompts/templates (interactive selector by default)
specfact init ide
specfact init ide --ide cursor
specfact init ide --ide vscode# Analyze an existing codebase
specfact import from-code my-project --repo .
# Validate external code without modifying source
specfact validate sidecar init my-project /path/to/repo
specfact validate sidecar run my-project /path/to/repoAI IDE quick start
# In your IDE chat (Cursor, VS Code, Copilot, etc.)
/specfact.01-import my-project --repo .Next steps
- Typical runtime: 2-15 minutes depending on repo size and complexity.
- Checkpointing: Progress is saved during analysis so you can resume safely.
- Performance: Optimized for large codebases with cached parsing and file hashes.
- Clarity: Turn messy code into clear specs your team can trust.
- Safety: Catch risky changes early with validation and contract checks.
- Sync: Keep backlog items, specs, tests, and code aligned end to end.
- Adoption: Simple CLI, no platform lock-in, works offline.
- Vibe coders and new builders who want to ship fast with guardrails and confidence.
- Legacy professionals who want AI speed without lowering standards.
- DevOps and engineering leaders who need evidence and repeatable workflows.
- Analyze: Read code and extract specs, gaps, and risks.
- Sync: Connect specs, backlog items, and plans in one workflow.
- Validate: Enforce contracts and block regressions before production.
Most tools help either coders or agile teams. SpecFact does both:
- Backlog sync that is actually strong: round-trip sync + refinement with GitHub, Azure DevOps, Jira, Linear.
- Ceremony support teams can run: standup, refinement, sprint planning, flow metrics (Scrum/Kanban/SAFe).
- Policy + validation: DoR/DoD/flow checks plus contract enforcement for production-grade stability.
Try it now
- Coders: AI IDE Workflow
- Agile teams: Agile/Scrum Workflows
Core modules
- Analyze: Extract specs and plans from existing code.
- Validate: Enforce contracts, run reproducible checks, and block regressions.
- Report: CI/CD summaries and evidence outputs.
Agile DevOps modules
- Backlog: Refinement, dependency analysis, sprint summaries, risk rollups.
- Ceremony: Standup, refinement, and planning entry points.
- Policy: DoR, DoD, flow, PI readiness checks.
- Patch: Preview, apply, and write changes safely.
Adapters and bridges
- Specs: Spec-Kit and OpenSpec
- Backlogs: GitHub Issues, Azure DevOps, Jira, Linear
- Contracts: Specmatic, OpenAPI
SpecFact now has a lifecycle-managed module system:
specfact initis bootstrap-first: initializes local CLI state, discovers installed modules, and reports prompt status.specfact init idehandles IDE prompt/template sync and IDE settings updates.specfact init --list-modulesshows effective enabled/disabled state.specfact init --enable-module/--disable-modulesupport:- interactive selection in interactive terminals when no module id is provided
- explicit ids in non-interactive mode (for automation)
- dependency-aware safety checks with
--forcecascading enable/disable behavior
- Module manifests support dependency and core-version compatibility enforcement at registration time.
This lifecycle model is the baseline for future granular module updates and enhancements. Module installation from third-party or open-source community providers is planned, but not implemented yet.
- Primary command implementations live in
src/specfact_cli/modules/<module>/src/commands.py. - Legacy imports from
src/specfact_cli/commands/*.pyare compatibility shims and only guaranteeappre-exports. - Preferred imports for module code:
from specfact_cli.modules.<module>.src.commands import appfrom specfact_cli.modules.<module>.src.commands import <symbol>
- Shim deprecation timeline:
- Legacy shim usage is deprecated for non-
appsymbols now. - Shim removal is planned no earlier than
v0.30(or the next major migration window).
- Legacy shim usage is deprecated for non-
- Primary command implementations live in
src/specfact_cli/modules/<module>/src/commands.py. - Legacy imports from
src/specfact_cli/commands/*.pyare compatibility shims and only guaranteeappre-exports. - Preferred imports for module code:
from specfact_cli.modules.<module>.src.commands import appfrom specfact_cli.modules.<module>.src.commands import <symbol>
- Shim deprecation timeline:
- Legacy shim usage is deprecated for non-
appsymbols now. - Shim removal is planned no earlier than
v0.30(or the next major migration window).
- Legacy shim usage is deprecated for non-
SpecFact complements your stack rather than replacing it.
- Spec-Kit/OpenSpec for authoring and change tracking
- Backlog tools for planning and delivery
- CI/CD for enforcement and regression prevention
SpecFact connects them with adapters, policy checks, and deterministic validation.
Integrations snapshot: GitHub, Azure DevOps, Jira, Linear, Spec-Kit, OpenSpec, Specmatic.
- I want a quick win: Getting Started
- I use an AI IDE: AI IDE Workflow
- We have a team backlog: Agile/Scrum Workflows
- We have a long-lived codebase: Working With Existing Code
We welcome contributions. See CONTRIBUTING.md.
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.
- GitHub Discussions: https://github.com/nold-ai/specfact-cli/discussions
- GitHub Issues: https://github.com/nold-ai/specfact-cli/issues
- Email: hello@noldai.com
- Debug logs: Run with
--debugand check~/.specfact/logs/specfact-debug.log.
Built 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.