Specfuse Spec-Authoring Kit

The upstream contract for Specfuse projects. Defines the conventions, vendor extensions, and authoring workflows that the Specfuse code generator consumes to produce backend, frontend, and worker artifacts from OpenAPI 3.0.3 + AsyncAPI 3.0.0 + Arazzo 1.0.1 specifications.

Quick start

Bootstrap a new Specfuse project with the kit's CLI:

pipx install specfuse-authoring     # CLI; recommended
#   (or, inside a venv you control: python3 -m pip install specfuse-authoring)
specfuse-authoring init ~/projects/my-new-project

Already have the specfuse umbrella? Install the kit through it — pipx install --force --include-deps 'specfuse[all]' — not standalone. Both paths expose a specfuse-authoring command, and pipx will not let the second one overwrite the first's shim in ~/.local/bin (File exists at … and points to … Not modifying.). Installing both leaves the command resolving to whichever won, so upgrading the other changes nothing. specfuse doctor (umbrella 0.9.4+) reports the conflict and the fix.

You'll be prompted for the project name, the project token (channel-address prefix), and the initial domain. The CLI substitutes placeholders, scaffolds the authoring contract (handbooks + samples + Spectral schemas) into .specfuse/authoring/, wires the specfuse-authoring Claude Code plugin into .claude/settings.json, and prints next steps. Pass --name/--token/--domain to run non-interactively.

The Claude Code authoring assets (skills + agents) ship as the specfuse-authoring plugin in the shared specfuse marketplace. init auto-wires the plugin, but you install it once in Claude Code with:

/plugin marketplace add specfuse/specfuse
/plugin install specfuse-authoring@specfuse

To pull a kit update into an existing project — handbooks, samples, schemas and the scripts/ tooling:

specfuse-authoring upgrade ~/projects/existing-project
specfuse-authoring upgrade ~/projects/existing-project --dry-run   # preview first

Your specs are never touched. upgrade tracks what it wrote (.specfuse/authoring/.scaffold-manifest), so it replaces kit files, warns before overwriting one you edited, and never deletes a file it did not create. (refresh is a deprecated alias.)

Pull newer skills with /plugin update specfuse-authoring@specfuse.

See examples/hello-orders/ for a complete worked example.

What's in the kit

Where to start

Relationship to other Specfuse repos

spec-authoring-kit  ◄── this repo (rules, samples, templates)
       ▲
       │ consumes
       │
   ┌───┴────────────────┐
   │                    │
generator           orchestrator
(Java/Kotlin —      (filesystem-based
 produces code      multi-agent workflow
 from specs)        coordination)

The kit is upstream of both: it defines what a Specfuse spec must look like. The generator consumes those specs to emit code. The orchestrator coordinates the multi-agent authoring workflow that produces those specs.

Status

Incubating (v0.5.7), Apache-2.0. Handbooks, samples, schemas, the project-init template, the bundled hello-orders example, the specfuse-authoring plugin (in the specfuse/specfuse marketplace), and the specfuse-authoring CLI are all in place. Generator-side alignment items are tracked in compatibility.md.

The kit is distributed on PyPI as specfuse-authoring and hosted under Specfuse/authoring. The code generator it drives is distributed separately as a pinned, checksum-verified release asset (see generator.lock); specfuse-authoring generate resolves, verifies, and runs it on demand.

Additional references

• compatibility.md — kit ↔ generator version matrix and outstanding generator-side follow-ups.
• provenance.md — bug-and-PR history that motivated each vendor extension. Kit-maintainer audit trail; external consumers do not need the referenced PRs to resolve.