5-Minute Quickstart

Get from zero to a scored code review in a few commands. This path is aimed at developers who want one command and one clear result 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.

Step 3: 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 4: Set Up IDE (Optional)

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

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

Step 5: Analyze Your Codebase and Check Health

specfact code import my-project --repo .
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 6: Validate

specfact code repro --verbose

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

What’s Next