Specfuse

Two things live here: the specfuse pip package — one install that owns the whole script suite — and the Claude Code plugin marketplace for the Specfuse gate-cycle methodology.

The split is deliberate. The scripts are one install because choosing between them is not a decision anyone wants to make; the plugins stay separate because which Claude assets a repository enables is exactly the decision it should make.

Install

uv tool install specfuse      # or: pipx install specfuse
cd <your repo> && specfuse init

That's the whole suite — driver, spec-authoring kit, orchestrator — behind one command. No extras, no --include-deps, no bracket quoting. Upgrade with:

specfuse upgrade              # runs your installer for you

Then, in Claude Code, install the plugins the repo needs:

/plugin marketplace add specfuse/specfuse
/plugin install specfuse@specfuse

specfuse init already wires the marketplace and the specfuse plugin into the repo's .claude/settings.json, so that second command is usually all that's left. Add --plugins authoring,orchestrator to enable those too.

Hitting a platform bug, or migrating off the retired specfuse[all] extras? See docs/troubleshooting.md, and run specfuse doctor.

The specfuse command

One command, one name on PATH.

specfuse init [DIR]           # scaffold .specfuse/ + wire .claude/ — or upgrade what's there
specfuse upgrade [DIR]        # the same thing, named for the other direction
specfuse doctor [--fix]       # check every suite command resolves here; --fix clears dead shims
specfuse --version            # the umbrella version + every component's resolved version

init and upgrade are one idempotent operation under two names — neither is ever the wrong one to run — and DIR defaults to the current directory. Both take --dry-run (writes nothing), --plugins, and --no-self-upgrade.

The component tools are subcommands:

The old flat commands still work. specfuse-loop, specfuse-lint, specfuse-authoring and the rest are deprecated aliases, removed in 1.0.0. specfuse doctor lists the ones still on PATH. One name on PATH is the point: the flat names are also the standalone packages' console scripts, so two installs could fight over them and the loser's upgrades silently changed nothing about what ran. See docs/plan-bundle-suite-distribution.md.

specfuse init lays down .specfuse/ (templates, rules, docs, verification.yml) and merge-safely wires .claude/ (including this plugin's config) — pip-native scaffolding via specfuse.loop.scaffold, no init.sh checkout required. Every specfuse run also self-provisions (version-syncs .specfuse/ from the installed package), so an upgrade reaches existing projects on their next run.

The suite is one distribution with three components as hard dependencies (specfuse-loop, specfuse-authoring, specfuse-orchestrator) — that is what makes one install and one upgrade cover everything. They contribute to the shared specfuse.* import namespace, so specfuse.loop, specfuse.authoring and specfuse.orchestrator coexist in one environment.

See specfuse/loop for the methodology, the driver, and getting-started docs.

Plugins

Installed per repo, via the marketplace — pick the toolset that repo needs.

Update with /plugin update specfuse@specfuse; reload after changes with /reload-plugins. The skills drive the pip-installed commands above.

Layout

.claude-plugin/marketplace.json   # catalog: per plugin { name, source, source_repo, managed }
plugins/<name>/                    # GENERATED copies — do not hand-edit (see below)
  .claude-plugin/plugin.json
  skills/<skill>/SKILL.md
  agents/<agent>.md

How the plugins are sourced (contributors)

Edit a plugin in its origin repo, never here. Each plugin's canonical source lives in its own repo at plugins/<name>/ (for the loop, .specfuse/skills/ is vendored from plugins/specfuse/skills/ for its dogfood — the plugin dir is still the source). The copies under plugins/ in this repo are generated output, produced by specfuse/publish.py.

• Publish on release. When a source repo publishes its package to PyPI, its release workflow dispatches to this repo; the publish step regenerates that plugin from the source at tag v<version>, stamps plugin.json.version to the released version (plugin@X == package@X == tag vX), and opens a PR only if the plugin changed.
• Drift-guard. The plugin-drift-guard CI (required check) re-derives every managed plugin from its source at the pinned tag and fails on any diff — so a hand-edit, a bad merge, or an agent's "quick fix" cannot land in plugins/. The only way in is a faithful publish.
• Manual publish (testing / backfill): the plugin-publish workflow's workflow_dispatch (plugin, version) runs the same path by hand.

See docs/plan-unify-plugin-sourcing.md for the full design. Skills reach a target repo through the installed plugin (under the /specfuse: etc. namespaces), not by copying files into the repo.

License

Apache License 2.0. See LICENSE.