Metadata-Version: 2.4
Name: specfuse
Version: 0.10.0
Summary: Specfuse — the whole script suite (driver, authoring kit, orchestrator) in one install, plus the init/upgrade bridge to the Claude Code plugin.
Author: Specfuse contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/specfuse/specfuse
Project-URL: Source, https://github.com/specfuse/specfuse
Project-URL: Driver, https://github.com/specfuse/loop
Keywords: specfuse,gate-cycle,cli,bridge
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: specfuse-loop>=0.9.3
Requires-Dist: specfuse-orchestrator>=0.4.1
Requires-Dist: specfuse-authoring>=0.5.6
Provides-Extra: dev
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# Specfuse

Two things live here: the **`specfuse` pip package** — one install that owns the
whole script suite — and the [Claude Code plugin
marketplace](https://code.claude.com/docs/en/plugin-marketplaces) 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`](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:

| Subcommand | What it does | Component |
|---|---|---|
| `specfuse run` | run the gate-cycle driver | `specfuse-loop` |
| `specfuse lint` | lint a feature plan | `specfuse-loop` |
| `specfuse monitor`, `monitor-lint` | the monitoring CLI and its linter | `specfuse-loop` |
| `specfuse stats` | event statistics for a repo's loop | `specfuse-loop` |
| `specfuse authoring` | design / validate / bundle specs | `specfuse-authoring` |
| `specfuse pm` | multi-repo initiative coordination | `specfuse-orchestrator` |
| `specfuse poller`, `runner` | the orchestrator's poller and agent runner | `specfuse-orchestrator` |
| `specfuse validate-event`, `validate-frontmatter` | orchestrator validators | `specfuse-orchestrator` |

> **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`](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](https://github.com/specfuse/loop) for the methodology, the
driver, and getting-started docs.

## Plugins

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

| Plugin | What it ships | Source repo |
|--------|----------------|-------------|
| `specfuse` | Gate-cycle skills (pick / draft / arm / diagnose / wrap, authoring, verification) | [`specfuse/loop`](https://github.com/specfuse/loop) `plugins/specfuse/` |
| `specfuse-authoring` | Spec-craft: design OpenAPI/AsyncAPI/Arazzo, validate, bundle + the `specs` agent (idea → validated initiative) | [`specfuse/authoring`](https://github.com/specfuse/authoring) `plugins/specfuse-authoring/` |
| `specfuse-orchestrator` | Multi-repo initiative coordination (onboard, pm) | [`specfuse/orchestrator`](https://github.com/specfuse/orchestrator) `plugins/specfuse-orchestrator/` |

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`](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`](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`](LICENSE).
