suaveplan/openspec/archive/2026-05-26-create-suaveplan-plugin/proposal.md

create-suaveplan-plugin — interactive scaffold for new plugins

Package: create-suaveplan-plugin Status: PROPOSED Type: new-package Stage: 8 — see umbrella openspec/changes/api-plugin-foundation/

Why

Per design doc §13.7, plugin authors should never start from an empty directory. create-suaveplan-plugin <name> generates a complete, immediately-testable plugin skeleton with plugin.json, definePlugin body, host-test, integration test (with real Postgres when DB is selected), both vitest configs, migrations, and a README. The author runs bun test, sees green, then replaces the skeleton.

The scaffold ships AS a plugin loaded by @suaveplan/installer — consistent with how install-agent-skills works. The binary entrypoint is bunx create-suaveplan-plugin <name> (or bun create suaveplan-plugin <name>).

What changes

• ADDED: Bin create-suaveplan-plugin mounted under @suaveplan/installer plugin host.
• ADDED: Interactive prompt asking about: plugin name, isolation tier, capabilities selected (multi-select), DB engine (postgres / sqlite / surrealdb / none), whether to scaffold GraphQL / WS / SSE / sagas / 2PC / per-tenant jobs.
• ADDED: Template output, generated atomically into a fresh directory:
  • plugin.json — every section commented with explanatory text AND populated with minimal viable values for selected capabilities.
  • src/index.ts — definePlugin({ ... }) skeleton hitting every selected capability with TODO-marked handler bodies that compile + pass type-check on day one.
  • src/index.test.ts — createTestHost against the skeleton; one it(...) per capability declaring "host wires the capability + calls a no-op handler".
  • tests/integration/example.integration.test.ts — uses testing-integration-postgres (or sqlite / surrealdb per prompt). Runs only when INTEGRATION=1.
  • vitest.config.ts and vitest.integration.config.ts — pre-wired with createTestConfig from @suaveplan/testing.
  • migrations/<engine>/0001-init.sql — empty boilerplate matching the DB engine.
  • README.md — manifest + lifecycle + capability docs filled in for the selected surface.
  • package.json — version 0.0.0, deps for selected capabilities, scripts (test, test:integration, test:coverage, lint, typecheck, build).
  • tsconfig.json — extends @suaveplan/typescript-config/library-node.
  • .gitignore, biome config inheritance.
• ADDED: Snapshot test of the generated tree — tests/scaffold-output/scaffold-output.test.ts runs the generator against a fixture prompt set and asserts the produced files match a committed snapshot byte-for-byte.
• ADDED: Error codes (SCAFFOLD_*): INVALID_NAME, DIRECTORY_EXISTS, WRITE_FAILED, UNKNOWN_ENGINE.

Out of scope

• Publishing the scaffolded plugin to a registry — author's job.
• Continuous-update flow (re-running scaffold to add a capability later) — separate change.
• Web UI for the scaffold — CLI only in v1.

Source mapping

Genesis-original. Source of design intent: docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md.

Requirement	Design doc section
create-suaveplan-plugin <name> scaffold	§13.7
Generated files compile + bun test green immediately	§13.7
Integration test wired with testing-integration-postgres when DB selected	§13.7

Verification approach

• src/prompt/prompt.test.ts — every prompt branch produces the right capability set; invalid names raise SCAFFOLD_INVALID_NAME.
• src/generator/generator.test.ts — each template file renders with the right substitutions for a given prompt set.
• tests/scaffold-output/scaffold-output.test.ts — snapshot test: run the generator against three fixture prompt sets (trusted+postgres+full, isolated+sqlite+REST-only, sandboxed+none+REST-only) and assert the produced tree matches tests/scaffold-output/snapshots/<fixture>/** byte-for-byte.
• tests/scaffold-output/runs-bun-test.test.ts — for each fixture, run bun test against the generated tree AND assert exit code 0 (proves the scaffold is immediately green).
• tests/dep-graph.test.ts — runtime deps.

Migration impact

None — additive only. The scaffold is published as a separate npm package consumable via bunx create-suaveplan-plugin <name>.