Module Bootstrap Checklist

Use this checklist right after installing or upgrading SpecFact CLI to ensure bundled modules are installed and discoverable. Use plain specfact ... commands below (not hatch run specfact ...) so the steps work for pipx, pip, uv tool installs, and packaged environments.

1. Initialize Bundled Modules

User scope (default)

specfact module init

This seeds bundled modules into ~/.specfact/modules.

Project scope (optional)

specfact module init --scope project --repo .

This seeds bundled modules into <repo>/.specfact/modules.

Use project scope when modules should apply only to a specific codebase/customer repository.

2. Verify Installed Modules

specfact module list

If bundled modules are still available but not installed, you’ll see a hint to run:

specfact module list --show-bundled-available

3. Inspect Bundled But Not Installed Modules

specfact module list --show-bundled-available

This prints a separate bundled table plus install guidance.

4. Install Specific Modules Only (Optional)

Install from bundled sources only:

specfact module install backlog-core --source bundled

Install from marketplace only:

specfact module install specfact/backlog --source marketplace

Install with automatic source resolution (bundled first, then marketplace):

specfact module install backlog

5. Scope-Safe Uninstall

specfact module uninstall backlog-core --scope user
# or
specfact module uninstall backlog-core --scope project --repo .

If the same module exists in both user and project scope, SpecFact requires explicit --scope to prevent accidental removal.

6. Startup Freshness Guidance

SpecFact performs bundled module freshness checks:

• on first run after a CLI version change
• otherwise at most once per 24 hours

When modules are missing/outdated, startup output suggests exact refresh commands for project and/or user scope.