SpecFact CLI Documentation

Defend AI-assisted Python code from bloat before it reaches PR. Run deterministic review, cleanup forecasts, and spec/contract evidence locally.

Point SpecFact at your repo, get a scored review with file-level findings, then use the JSON report as the cleanup contract for your AI IDE. Go deeper into backlog, specs, and CI when you need more control.

uvx specfact-cli init --profile solo-developer
uvx specfact-cli code review run --path . --scope full

You should see a Verdict, a Score, and a list of findings on a real repo. That is the fastest way to see SpecFact on existing code. Read the full quickstart →

SpecFact does not include built-in AI. It pairs deterministic CLI commands with your chosen IDE and copilot so fast-moving work has a stronger validation and alignment layer around it.

AI-bloat defense: ai_bloat advisories flag bloated shapes commonly produced during AI-assisted coding. Simplify-focused reviews add a cleanup forecast, AI-bloat index, preserve reasons, and remediation packets that Claude, Codex, Cursor, Copilot, or another assistant can consume. They are cleanup signals, not AI-authorship detection. Try the AI bloat quickstart on modules.specfact.io.

SpecFact is the AI-bloat defense and validation CLI for AI-assisted and brownfield delivery.

What is SpecFact?

SpecFact helps you keep upstream intent, specifications, implementation, and validation from drifting apart. It consumes OpenSpec, Spec Kit-style workflows, backlog items, contracts, tests, and code as upstream inputs so brownfield and AI-assisted teams can validate what actually landed.

It is especially useful when:

  • AI-assisted or “vibe-coded” work needs bloat cleanup and stronger validation
  • brownfield and legacy code need trustworthy reverse-engineered understanding of existing systems
  • teams want to avoid the “I wanted X but got Y” delivery failure
  • organizations need a path toward stronger shared policy enforcement

Why does it exist?

SpecFact exists because backlog/spec/code drift is expensive: teams ship the wrong thing, AI-assisted changes accumulate bloat before validation catches up, and policy enforcement breaks down across IDEs and CI. SpecFact gives you a default starting point before you jump into module-deep workflows on the modules site.

Why should I use it?

Use SpecFact when you want faster delivery without losing validation, stronger brownfield understanding before making changes, and less drift between backlog intent, specifications, and the code that actually lands.

What do I get?

With SpecFact, you get:

  • deterministic local tooling instead of opaque cloud dependence
  • AI-bloat defense with cleanup forecasts and remediation packet handoff
  • a validation layer around AI-assisted delivery
  • codebase analysis and sidecar validation for brownfield work
  • stronger upstream-input/spec/code alignment without replacing your planning stack
  • a clean handoff from this site into module-deep workflows on modules.specfact.io

How to get started

  1. Installation — uvx (no install) or pip (persistent CLI)
  2. 5-Minute Quickstart — First commands on a repo
  3. specfact init — Profiles, bundles, and IDE setup
  4. Bootstrap Checklist — Verify bundle readiness

Choose your path

See what's wrong with your code right now

Run a scored code review, inspect AI-bloat cleanup candidates, then iterate.

Set up IDE slash-command workflows

Install the CLI, bootstrap bundles, then export prompts for Cursor, VS Code, and other IDEs.

Add a pre-commit or CI gate

Wire SpecFact into local hooks or GitHub Actions for repeatable checks.

Core Platform

The specfact-cli package provides the stable platform surface:

Installed modules add command groups such as project, backlog, code, spec, and govern. Deeper bundle docs live on modules.specfact.io.

Modules Documentation

docs.specfact.io is the default starting point and the canonical starting point for the core CLI story for first-time readers on this site. Move to the modules site when you need module-deep workflows, bundle-specific adapters, and authoring guidance.

Module System

Architecture

Workflows

Reference

Migration