From Swiss Knife to Ecosystem: How SpecFact CLI's Module Marketplace Unlocks Open-World Contribution

TL;DR: SpecFact CLI's marketplace architecture (Waves 0–2 now complete) lays the foundation for a VS Code-style extension ecosystem: a lean 4-command core, five workflow category bundles, cryptographically signed module packages, and a fully open registry that any trusted publisher — NOLD AI, enterprise teams, or the community — can contribute to. The "swiss knife" approach scales because the knife is no longer a fixed shape.

The Problem with One-Size-Fits-All CLIs

SpecFact CLI has always positioned itself as a swiss knife: one tool that keeps backlog, specs, contracts, tests, and code in sync across your entire agile DevOps workflow. That promise delivered — but it also created a quiet UX problem.

Today, running specfact --help exposes 21 top-level commands simultaneously. A solo developer who just needs contract enforcement sees the same wall of options as an enterprise scrum team who needs backlog ceremonies, PI planning, and governance gates. The tool answers every question but asks you to filter the relevant ones yourself.

More importantly, a monolithic package creates a ceiling. Every new integration — a new backlog tool, a new spec format, a new AI IDE bridge — has to land in the core repository and ship with the next release. Community contributors can file issues but can't ship capabilities independently. Enterprise teams with custom field mappings or internal workflow modules have nowhere to put them except forks.

The marketplace architecture solves both problems at once: show users only the capabilities they need, and let anyone with a good module idea ship it without waiting for a core release.

What's Already Built: Waves 0–2

The journey from monolith to marketplace has been deliberate and sequential. Each wave built on the last without breaking existing workflows.

Wave 0 — Modular foundation (arch-01 through arch-05)

The CLI was refactored from a flat command list into a proper module registry with lazy loading. Each capability became a self-contained module package, discovered at startup but only imported when actually invoked. The module-package.yaml manifest format established the contract between core and modules:

• Command registration and help text
• Core compatibility version constraints (PEP 440 semver)
• Module dependency declarations
• Enable/disable lifecycle via specfact init --enable-module / --disable-module

The bridge registry (arch-05) added a second dimension: modules can register schema converters for external services (ADO, Jira, Linear, GitHub), so other modules can perform cross-tool sync without importing each other directly. Interoperability without coupling.

Wave 1 — Trust and extensibility infrastructure (arch-06, arch-07)

Two foundational capabilities shipped in parallel with the cross-cutting quality foundations:

• Enhanced manifest security (arch-06) — ModulePackageMetadata extended with publisher identity, SHA-256 checksums, and Ed25519 cryptographic signatures. All official modules are auto-signed in CI. Unsigned modules require explicit --allow-unsigned consent.
• Schema extension system (arch-07) — Modules can now declare typed extension fields on core models (Feature, ProjectBundle) via their manifest. Extensions are namespaced to the declaring module (backlog.ado_work_item_id), preventing collisions. Core models stay stable; modules add richness.

Wave 2 — Central registry and marketplace MVP (marketplace-01)

The specfact-cli-modules repository was created as the canonical marketplace store. It implements a versioned index.json registry schema:

{
  "schema_version": "1.0",
  "modules": [
    {
      "id": "specfact/backlog",
      "namespace": "specfact",
      "tier": "official",
      "latest_version": "0.38.0",
      "core_compatibility": ">=0.27.0,<1.0.0",
      "checksum_sha256": "...",
      "signature_url": "https://registry.nold.ai/keys/nold-ai.asc",
      "tags": ["backlog", "agile", "sync"]
    }
  ]
}

Module management commands landed in the same wave:

# Search for available modules
specfact module search backlog

# Install a module from the registry
specfact module install specfact/backlog

# List installed modules (builtin / marketplace / custom)
specfact module list --source all

# Upgrade a module
specfact module install specfact/backlog --upgrade

Multi-location discovery means the CLI finds modules across three locations transparently: built-in (shipped with core), marketplace-installed (~/.specfact/marketplace-modules/), and custom (~/.specfact/custom-modules/).

What's Actively Being Built: Wave 3

marketplace-02 — Advanced marketplace features

The in-progress change (#215) adds the three capabilities that take the marketplace from MVP to production-ready:

1. Dependency resolution

When installing a module with pip dependencies, the resolver aggregates constraints across all installed modules and resolves them together — detecting conflicts before installation rather than breaking an existing environment. Inspired by pip-compile: no surprise breakage when Module A and Module B have different version requirements for the same library.

2. Alias system

Namespaced module IDs (specfact/backlog, acme-corp/backlog-pro) are unambiguous but verbose. Aliases let users map short command names to whichever module they prefer:

# Prefer a community backlog module over the official one
specfact module alias backlog acme-corp/backlog-pro

# Back to the official module
specfact module alias remove backlog

Default resolution falls back to the specfact/ namespace, so existing commands work unchanged for users who haven't set aliases.

3. Custom registries

Enterprise teams can host private module registries and add them alongside the official one:

# Add a private enterprise registry
specfact module add-registry \
  https://modules.internal.acme.com/index.json \
  --trust prompt

# Install from the private registry
specfact module install acme-corp/custom-workflow

The trust model is explicit: the official NOLD AI registry is trusted by default; custom registries prompt for consent on first install. Each registry entry in ~/.specfact/config/registries.yaml carries a trust level (always, prompt, never) so enterprise security teams can lock down which sources are allowed.

What Follows: Module Migration (Waves 3–4)

Once marketplace-02 ships, the module migration changes extract the 21 currently bundled modules out of the core package and into independently versioned marketplace bundles. This is the step that makes the ecosystem real: official NOLD AI modules go through the same signed, versioned, registry-published path as any community module.

Five workflow category bundles

The 21 modules consolidate into five domain-scoped bundles — one per workflow role:

The four permanent core commands (init, auth, module, upgrade) stay in the core package and are always present.

Before and after: the help screen

VS Code-style first-run experience

On first run, specfact init walks through an interactive bundle selector — the same pattern VS Code uses for extension recommendations on first workspace open:

$ specfact init

  Welcome to SpecFact CLI!

  Let's install the modules for your workflow.
  Use arrow keys + space to select, Enter to confirm.

  ✅ Core (always installed)
     init · auth · module · upgrade

  Select your workflow bundles:

  ❯ [ ] Project lifecycle   (project, plan, import, sync, migrate)
    [ ] Backlog management  (backlog, policy)
    [x] Codebase quality    (analyze, drift, validate, repro)
    [ ] Spec & API          (contract, spec, sdd, generate)
    [ ] Governance          (enforce, patch)

  Or choose a profile:
    > Solo developer
    > Backlog team (scrum)
    > API-first team
    > Enterprise full-stack

Profile presets handle CI/CD pipelines and automated environments without interactive prompts:

# Non-interactive: install a preset
specfact init --profile enterprise

# Non-interactive: explicit bundle list
specfact init --install backlog,codebase

# Legacy: install everything (existing behaviour preserved)
specfact init --install all

The Open-World Contribution Model

This is where the swiss knife metaphor earns its name back — but at ecosystem scale rather than single-package scale.

What anyone can build and publish

A module is any self-contained Python package that implements the ModuleIOContract protocol and ships a module-package.yaml manifest. The contract is minimal:

• Declare your commands, their help text, and their core_compatibility version range.
• Declare pip dependencies so the resolver can prevent conflicts.
• Use ProjectBundle as your data exchange format — the shared language all modules speak.
• Namespace any schema extensions you add (yourmodule.field_name).

With those four rules in place, a module can do anything: wrap a new backlog tool, add AI-powered test generation, expose a custom reporting format, integrate a new spec language, or add domain-specific validation rules for regulated industries.

Publisher tiers and trust

Every module in the marketplace carries a publisher identity and a tier that signals its trust provenance:

A community module follows the same publishing pipeline as an official module — module-package.yaml, a signed tarball, a checksum, and a pull request to the registry index. NOLD AI reviews community submissions before they appear in search results. Enterprise modules skip the central registry entirely and go through a private registry URL that the org controls.

What the ecosystem unlocks

The category of modules the community can build is genuinely wide once the plumbing is in place:

• New backlog adapters — Asana, Monday.com, Notion, Shortcut, Height, or any custom internal tracker with an API.
• New spec languages — AsyncAPI, GraphQL SDL, gRPC Protobuf, or domain-specific schema formats.
• Domain-specific governance packs — HIPAA compliance templates, SOC 2 evidence generation, DORA metrics, ISO 27001 control mappings.
• AI integration modules — MCP server bridges, agent skill exporters, structured prompt generators for specific LLMs or IDEs.
• Reporting and doc generation — Architecture Decision Record (ADR) generators, confluence page exporters, SBOM generators, changelog formatters.
• Team-specific workflow modules — Custom standup formats, bespoke sprint metrics, internal Definition of Done profiles.

None of these require changes to SpecFact CLI core. They install via specfact module install, appear in specfact --help under their category group, and participate in the same bundle protocol as official modules.

Why This Is the Right Architecture for AI-first Teams

AI-first development teams are not a monolith. A solo developer using Claude Code and a regulated financial enterprise using SpecFact for contract compliance have almost nothing in common — except that both benefit from the same core guarantees: a trustworthy spec bundle, an honest diff between what specs say and what code does, and a CI gate that catches drift before it ships.

A monolithic CLI forces both teams to carry all the weight for the use cases of the other. A marketplace architecture lets each team install exactly the capabilities their workflow needs, trust the modules they install at the same cryptographic level as the core CLI, and extend the tool for their domain without forking anything.

The swiss knife metaphor holds because the blade set is customizable, not because every blade ships pre-installed.

Roadmap at a Glance

The critical path is linear by design: security before marketplace, marketplace before migration, migration before slimming. Each wave is independently shippable and leaves the CLI in a fully functional state.

The community contribution window opens fully at Wave 3 completion: once marketplace-02 ships the custom registry and dependency resolver, any org can host a private module registry and any developer can submit a signed community module to the central index.

Getting Started as a Module Author

If you want to build a module before the full publishing pipeline is complete, the foundation is already usable. The module package format is stable, the ModuleIOContract protocol is implemented, and the local custom module path (~/.specfact/custom-modules/) is supported today.

# Scaffold a new module (coming with module-migration-01)
specfact module new my-module

# Install a local module for development
specfact module install ./my-module --local

# Verify the module registers correctly
specfact module list --source custom

# Run with your module active
specfact my-module --help

Conclusion

SpecFact CLI was always a swiss knife. The module marketplace makes it a swiss knife factory — one where NOLD AI ships the standard blade set, enterprises grind custom blades for their specific materials, and the community contributes specialized tools that no single vendor would think to build.

The architecture is the point. Cryptographic trust, dependency resolution, namespacing, and category grouping are not engineering niceties — they are the conditions under which open-world contribution becomes safe at scale. Without them, any "marketplace" is just a curated list of forks. With them, it's a genuine ecosystem.

Watch the marketplace-02 issue (#215) for the community registry contribution process, and follow specfact-cli-modules for the growing module catalog.

Further Reading

• VR-SDD: The Agile Developer Level-Up Beyond Vibe Coding
• AI-Assisted Backlog Refinement for DevOps Teams
• DevOps Backlog Sync Capabilities
• SpecFact CLI on GitHub
• specfact-cli-modules (marketplace registry)
• SpecFact Docs