Module Bootstrap Checklist
Use this checklist right after installing or upgrading SpecFact CLI to ensure official workflow bundles 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.
Core ships the bootstrap/runtime needed to install bundles. The official bundle source of truth is
the marketplace registry in nold-ai/specfact-cli-modules, even when specfact module init
seeds bundled copies for the current CLI release line.
1. Initialize Bundled Bundle Copies
User scope (default)
specfact module init
This seeds bundled copies of the official bundles into ~/.specfact/modules.
Project scope (optional)
specfact module init --scope project --repo .
This seeds bundled copies of the official bundles 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 bundle copies 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 --source bundled
Install from marketplace only:
specfact module install nold-ai/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 --scope user
# or
specfact module uninstall backlog --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.