Why
SpecFact CLI currently exposes 21 flat top-level commands, overwhelming new users with no clear entry point and no indication of which modules are relevant to their workflow. Every install loads every module, even when users need only backlog management or codebase quality tooling.
The marketplace infrastructure (marketplace-01 archived, marketplace-02 in progress) now provides the foundation to move forward with a UX reorganisation. This change introduces a categorisation layer that groups the 21 modules into 5 workflow-domain bundles under category group commands, adds the metadata fields to module-package.yaml that drive the grouping, and replaces the overwhelming flat help with a curated first-run selection experience.
This mirrors the VS Code model: present workflow-domain groups and let users install exactly the bundle that matches how they work.
What Changes
- Add
category, bundle, bundle_group_command, and bundle_sub_command fields to all 21 module-package.yaml files
- Create a
groups/ layer with 5 category umbrella commands:
specfact project — project lifecycle (project, plan, import, sync, migrate)specfact backlog — backlog management (backlog, policy)specfact code — codebase quality (analyze, drift, validate, repro)specfact spec — specification management (contract, spec, sdd, generate)specfact govern — governance & enforcement (enforce, patch)
- Update
specfact init with first-run interactive module selection, --profile and --install parameters
- Add 4 workflow profile presets: solo-developer, backlog-team, api-first-team, enterprise-full-stack
- All 21 existing top-level commands remain functional via deprecation shims (removed after one major version cycle)
Acceptance Criteria
specfact --help shows category group commands instead of 21 flat commands (when bundles are installed)specfact init --profile solo installs the specfact-codebase bundle interactively or non-interactively- All 21 existing commands continue to work via shims in CI/CD mode (no breaking changes)
- Category group umbrella commands correctly route to module sub-commands
OpenSpec Change Proposal: module-migration-01-categorize-and-group
Why
SpecFact CLI currently exposes 21 flat top-level commands, overwhelming new users with no clear entry point and no indication of which modules are relevant to their workflow. Every install loads every module, even when users need only backlog management or codebase quality tooling.
The marketplace infrastructure (marketplace-01 archived, marketplace-02 in progress) now provides the foundation to move forward with a UX reorganisation. This change introduces a categorisation layer that groups the 21 modules into 5 workflow-domain bundles under category group commands, adds the metadata fields to
module-package.yamlthat drive the grouping, and replaces the overwhelming flat help with a curated first-run selection experience.This mirrors the VS Code model: present workflow-domain groups and let users install exactly the bundle that matches how they work.
What Changes
category,bundle,bundle_group_command, andbundle_sub_commandfields to all 21module-package.yamlfilesgroups/layer with 5 category umbrella commands:specfact project— project lifecycle (project, plan, import, sync, migrate)specfact backlog— backlog management (backlog, policy)specfact code— codebase quality (analyze, drift, validate, repro)specfact spec— specification management (contract, spec, sdd, generate)specfact govern— governance & enforcement (enforce, patch)specfact initwith first-run interactive module selection,--profileand--installparametersAcceptance Criteria
specfact --helpshows category group commands instead of 21 flat commands (when bundles are installed)specfact init --profile soloinstalls thespecfact-codebasebundle interactively or non-interactivelyOpenSpec Change Proposal:
module-migration-01-categorize-and-group