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 Specfuse CLI:

pipx install specfuse                # the whole suite; no extras, no flags
#   (or: uv tool install specfuse)
specfuse authoring init ~/projects/my-new-project

The kit is one component of the Specfuse suite, and the suite is driven through the single specfuse command — specfuse authoring … is this kit. Installing specfuse brings the kit with it, and pipx upgrade specfuse (or uv tool upgrade specfuse) pulls every component's new release.

Standalone use. pip install specfuse-authoring still works if you want the kit alone or as a library, and its flat specfuse-authoring command is kept as a deprecated alias until 1.0.0 — drop the specfuse prefix from every command below. Do not install both ways: the two installs provide the same flat command name, so whichever claimed ~/.local/bin first is what runs, and upgrading the other changes nothing. specfuse doctor reports which install owns each command.

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/specfuse/ 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.30.0), 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.
• docs/generator-releases.md — release notes for each generator pin bump: what breaks before you regenerate, what is new, which tracked issues it fixes. Ships into every project at .specfuse/authoring/docs/generator-releases.md, so upgrade brings the notes with the pin.
• 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.