5-Minute Quickstart

Get from zero to AI-bloat defense and a scored code review in a few commands. This path is aimed at developers who want one command, one clear result, and a JSON handoff for AI IDE cleanup before reading about modules, profiles, or architecture.

Prerequisites

  • Python 3.11+ (python3 --version)
  • A Git repository to analyze (or create a test project)

Step 1: Bootstrap with uvx (no pip install)

From your repo root:

uvx specfact-cli init --profile solo-developer

This installs the workflow bundles for the solo-developer profile (including the code-review module). See specfact init for other profiles.

Step 2: Run a scored code review

uvx specfact-cli code review run --path . --scope full

You should see a Verdict, Score, and findings. That is the fastest “aha” path on a real codebase.

If the Code Review bundle reports category=ai_bloat, treat those entries as cleanup candidates, not proof of AI authorship. They are severity=info, advisory-only, and score-neutral.

Step 3: Run the JSON-first cleanup loop

Run simplify-focused review with JSON output:

uvx specfact-cli code review run --scope changed --enforcement shadow --focus simplify --preview-fixes --json --out .specfact/code-review.json

Then work the report in this order:

  1. Inspect cleanup_forecast and the AI-bloat index.
  2. Hand remediation packets to your AI IDE.
  3. Accept only safe or approved changes.
  4. Re-run review for proof.

This is AI-bloat defense, not AI-authorship detection. For exact simplify flags, invalid combinations, and report fields, see the AI bloat quickstart and Code Review run guide on the modules docs site.

Step 4: Install SpecFact locally (optional)

When you want a stable specfact command and IDE integration, install with pip:

pip install specfact-cli
cd /path/to/your/project
specfact init --profile solo-developer

Step 5: Set Up IDE (Optional)

specfact init ide --ide cursor --install-deps

This creates .specfact/ directory structure and IDE-specific prompt templates.

Step 6: Analyze Your Codebase and Check Health

specfact code import --repo . my-project
specfact project health-check

code import analyzes your code and extracts features, user stories, and dependency graphs into a project bundle at .specfact/projects/my-project/. project health-check summarizes what SpecFact discovered.

Step 7: Validate

specfact code repro --verbose

Runs the full validation suite: linting, type checking, contracts, and tests.

What’s Next