Getting Started with SpecFact Modules

Welcome to the modules getting-started guide. This section covers installing and using official bundles. For core CLI platform setup, see docs.specfact.io.

Installation

Choose your preferred installation method:

  • Installation Guide - All installation options (uvx, pip, Docker, GitHub Actions)
  • Installation Guide - Optional dependencies for graph-based analysis (pyan3, syft, bearer, graphviz)

Quick Start

Module System Note

SpecFact runs on a lifecycle-managed module system.

  • Core runtime manages lifecycle, registry, contracts, and orchestration.
  • Feature behavior is implemented in module-local command implementations.
  • This allows feature modules to evolve independently without repeatedly rewiring CLI core logic.

Your First Command

For Legacy Code Modernization (Recommended):

# CLI-only mode (works with uvx, no installation needed)
uvx specfact-cli@latest code import --repo . my-project

# Interactive AI Assistant mode (requires pip install + specfact init)
# See First Steps guide for IDE integration setup

For New Projects:

# Install a project-oriented bundle first, then inspect the mounted workflow surface
specfact module install nold-ai/specfact-project
specfact project --help

Note: Interactive AI Assistant mode provides better feature detection and semantic understanding, but requires pip install specfact-cli and IDE setup. CLI-only mode works immediately with uvx but may show 0 features for simple test cases.

Migration Note (0.40.0)

Flat root commands were removed. Use the mounted grouped command forms:

  • root-level validate moved under specfact code validate ...
  • root-level sync moved under specfact project sync ...
  • root-level policy actions moved under specfact backlog policy ...
  • grouped command surfaces such as specfact code repro ... and specfact govern enforce ... remain current

First-run bundle selection examples:

specfact init --profile solo-developer
specfact init --install backlog,codebase
specfact init --install all

Marketplace bundle install examples:

specfact module install nold-ai/specfact-codebase
specfact module install nold-ai/specfact-backlog

Official bundles are published in the nold-ai/specfact-cli-modules registry and verified as official tier during install. Some bundles install dependencies automatically:

  • nold-ai/specfact-spec -> pulls nold-ai/specfact-project
  • nold-ai/specfact-govern -> pulls nold-ai/specfact-project

Modernizing Legacy Code?

New to brownfield modernization? See our Brownfield Engineer Guide for a complete walkthrough of modernizing legacy Python code with SpecFact CLI.

Next Steps

Need Help?