Tasks — API Plugin Foundation (umbrella)

Umbrella change. Tasks here track stage acceptance — per-package work is checked off in each package's own change. Do not retroactively tick boxes for work done before this change opened.

0. Pre-flight (non-negotiable)

0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

0. Pre-work

0.1 Brainstorm + design doc at docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md
0.2 Design reviewed by spec-document-reviewer subagent (twice — once on initial draft, once on enterprise-scope rewrite)
0.3 User-approved scope: all 8 items previously deferred folded in as v1 design surface

1. Per-package OpenSpec proposals authored

Stage 1 — Contracts

1.1 api-types
1.2 api-manifest
1.3 api-router
1.4 api-graphql (abstract contract)
1.5 api-ws (abstract contract)
1.6 api-sse (abstract contract)
1.7 api-auth (abstract session-resolver)
1.8 api-auth-provider (abstract provider)
1.9 api-secrets (abstract contract)
1.10 api-tenant-provider (abstract contract)
1.11 api-loader
1.12 api-lifecycle

Stage 2 — Host orchestration

2.1 api-host

Stage 3 — Worker isolation

3.1 api-worker-rpc
3.2 api-worker-host
3.3 api-router-worker-bridge
3.4 api-db-worker-proxy
3.5 api-events-worker-proxy
3.6 api-secrets-worker-proxy
3.7 api-jobs-worker-proxy
3.8 api-logger-worker-proxy

Stage 4 — Base adapters

4.1 api-router-hono
4.2 api-auth-jwt
4.3 api-auth-anonymous
4.4 api-auth-bearer-static
4.5 api-tenant-resolver-jwt
4.6 api-secrets-env
4.7 api-db-adapter
4.8 api-tenant-provider-memory

Stage 5 — Testing kit + conformance suites

5.1 api-router-in-memory
5.2 api-auth-static-principal
5.3 api-db-sqlite-memory
5.4 api-events-in-memory
5.5 api-ws-broker-in-memory
5.6 api-host testing-kit subpath (./testing export populated)
5.7 Conformance suites authored on every abstract package (./testing subpaths) — runXxxConformance shipped from api-manifest, api-router (+ api-host's runPipelineRouterConformance), api-graphql, api-ws, api-sse, api-auth, api-auth-provider, api-secrets, api-tenant-provider, api-loader, api-lifecycle, api-worker-rpc. api-types is types-only, no runtime conformance.

Stage 6 — Distributed transactions + Better-Auth

6.1 api-saga
6.2 api-2pc
6.3 api-auth-better-auth

Stage 7 — GraphQL + WebSocket / SSE

7.1 api-graphql-yoga
7.2 api-graphql-apollo
7.3 api-graphql-ui-graphiql
7.4 api-graphql-ui-altair
7.5 api-ws-bun
7.6 api-ws-broker-redis
7.7 api-sse-bun

Stage 8 — Sandboxing + middleware + helpers

8.1 api-sandbox-permissions
8.2 api-sandbox-vm
8.3 api-sandbox-wasm
8.4 api-rbac
8.5 api-rate-limit
8.6 api-openapi
8.7 api-openapi-ui-scalar
8.8 api-openapi-ui-swagger
8.9 api-openapi-ui-redoc
8.10 api-audit-stdout
8.11 api-audit-file
8.12 api-auth-rolled (session-resolver half; provider half deferred to api-auth-rolled-provider)
8.13 api-secrets-bun
8.14 api-secrets-vault
8.15 api-tenant-resolver-header
8.16 api-tenant-resolver-subdomain
8.17 api-plugin-example
8.18 create-suaveplan-plugin

2. Stage acceptance gates

Per openspec/AGENTS.md §17, every stage closes ONLY when its integration smoke is green — a real-composition test booting every shipped package in the stage and exercising the cross-package seams. Per-package conformance passing is necessary but not sufficient.

2.1 Stage 1 ✓ — every Stage-1 child change archived; bun openspec validate passes for every spec delta
2.2 Stage 2 ✓ — api-host archived; bun examples/api-host-empty.ts returns 200 on /internal/livez
2.3 Stage 3 ✓ — api-worker-rpc conformance suite passes against trivial proxy under both direct and worker surfaces
2.4 Stage 4 ✓ — every Stage-4 adapter passes its conformance suite under both surfaces AND e2e/foundation-stack/ smoke (bunx playwright test) is green with NO hand-wired shims (router-pipeline, tenant-chain, secrets-injection, ledger-db). Coherence-fix changes foundation-fix-gap-{1,2,3,4,5} are the closure artifacts.
2.5 Stage 5 ✓ — createTestHost boots api-plugin-example skeleton with 100% conformance pass AND e2e/foundation-stack-test-host/ smoke proves createTestHost(config) returns a host that drives every Stage-1..4 conformance surface without external services. (8/8 smoke groups green; foundation packages all pass §15 + §16 lint.)
2.6 Stage 6 ✓ — multi-step saga runs end-to-end (incl. compensation); api-2pc commits + aborts against real Postgres AND e2e/foundation-stack-saga/ runs a 3-step compensable workflow end-to-end across two plugins. (7/7 specs green: 3 saga + 4 2PC against Postgres 16 testcontainer with max_prepared_transactions=8.)
2.7 Stage 7 ✓ — api-plugin-example federates GraphQL across two plugins; tenant-scoped WebSocket broadcast works AND e2e/foundation-stack-engines/ smoke proves Yoga/Apollo + Bun WS + SSE coexist on one host. (5/5 specs green: 2 GraphQL federation across plugin-a+plugin-b through both Yoga and Apollo engines; 1 tenant-scoped WS broadcast with cross-tenant isolation; 1 SSE stream + publish; 1 four-engines-on-one-host route-collision check.)
2.8 Stage 8 ✓ — api-plugin-example deploys under every isolation tier (incl. sandboxed WASM); create-suaveplan-plugin <name> scaffold tests pass first time AND e2e/foundation-stack-full/ smoke boots every Stage 1-8 package together and exercises the full §6 11-step pipeline end-to-end.

Smoke-fail = stage incomplete

If a smoke needs hand-wired shims to boot (today's E2E pre-Wave-1 caught 5 such gaps in Stage 4), the stage is NOT complete. Open coherence-fix changes against the gap-bearing packages — do NOT paper over with shims in the smoke. The smoke must consume canonical adapter surfaces a real downstream consumer would. See openspec/archive/2026-05-26-foundation-fix-gap-{1,2,3,4,5} for the precedent.

3. Foundation acceptance

3.1 Reference plugin's full integration test (design doc §13.5) green in CI
3.2 Better-Auth adapter passes end-to-end OAuth flow with at least one provider (GitHub)
3.3 Hot-reload cycle exercised: blue-green swap with in-flight completion + new-slot health probe + traffic flip
3.4 Bad-module path: failed start triggers auto-rollback; plugin enters rolled_back; prior version keeps serving
3.5 Admin API exercised end-to-end: install/uninstall/disable/enable/reload/rollback/force-uninstall with audit log entries
3.6 Conformance suites pass for every adapter under both direct and worker-proxy surfaces

4. Archive

4.1 Refresh MANIFEST.md to include every foundation package
4.2 Update CLAUDE.md packages/api/ section with the foundation listing
4.3 Move openspec/changes/api-plugin-foundation/ → openspec/archive/<yyyy-mm-dd>-api-plugin-foundation/ only after every child change is archived

7.9 KiB Raw Blame History