Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
"How do I construct the client for Postgres / MongoDB?"
"Show me Register vs RegisterTenantScoped"
"Which read accessor should I use for a duration / int / bool?"
"How do OnChange and OnTenantChange differ?"
"How do I mount the admin HTTP surface safely?"
"What does the test harness look like?"
Skip when
Working on non-Go services
Working on frontend code
Target codebase has zero hot-reloadable runtime knobs (everything is static env-var-at-startup config — DSNs, TLS material, listen addresses, secrets stay outside the plane)
Task is documentation-only or non-code
Related
Migration partner:ring:migrating-to-lib-systemplane — end-to-end 11-gate migration cycle. This skill is the adoption/reference counterpart; the migration skill is the transformation pipeline.
[[ring:using-lib-commons]], [[ring:using-lib-observability]], [[ring:using-runtime]], [[ring:using-assert]]
Dual backend: Postgres 13+ (LISTEN/NOTIFY) or MongoDB 4.4+ (change streams; polling fallback for standalone deployments)
Provisioning: migration-only via systemplane.SchemaSQL() + systemplane.DefaultSeedSQL() public artifacts. Runtime DDL hook (runSchema) was removed in v1.6.0. Consumers vendor the artifacts into their own SQL migration pipeline via the make systemplane-ddl generator pattern — see ring:migrating-to-lib-systemplane Gate 3.5 and multi-tenant.md §27 "Cold-tenant resolution"
License: Elastic 2.0
Scope: runtime-mutable knobs only — never bootstrap-only material (DSNs, TLS, listen addresses, secrets)
SWEEP MODE
Orchestrate a 4-phase sweep. Each phase has a hard gate — do not proceed until the current phase produces its artifact.
Cross-reference MIGRATION_TENANT_SCOPED.md for two-phase rolling-deploy implications when adopting tenant overrides
Emit /tmp/systemplane-delta-report.json with classified entries
Phase 3: Multi-Angle DIY Sweep
⛔ STOP-CHECK BEFORE DISPATCH
Before emitting any Task call, count the explorers you intend to launch in this turn.
Count MUST equal 7.
If count < 7 → STOP. Do not partial-dispatch. Reconcile against the 7 angles below and try again.
The 7 angles are the canonical sweep. No substitutions, no omissions.
⛔ MUST NOT trickle-dispatch
All 7 explorers leave in the SAME TURN, before reading any explorer output.
Forbidden sequences:
Dispatch explorer 1 → read result → dispatch explorer 2
Dispatch a subset → wait → dispatch the rest
Dispatch follow-up explorers conditioned on partial output
Loop sequentially over the angle list
If you find yourself about to dispatch an explorer in a turn AFTER any explorer has already returned a result → STOP. You violated parallel dispatch. Report the violation and mark the phase INCOMPLETE rather than completing the trickle.
Self-verify after dispatch
After the dispatch turn, verify all 7 Task calls were emitted in that single turn. If fewer than 7 went out, the phase did NOT execute correctly. Mark INCOMPLETE and surface the dispatch failure — do NOT silently continue with a partial pool.
Parallel dispatch — atomic batch
Emit all 7 Task calls in a SINGLE TURN, as one atomic batch.
If your runtime exposes a multi_tool_use.parallel wrapper, use it to dispatch the complete pool in one wrapped invocation. This is the canonical fan-out mechanism on OpenAI-style tool envelopes and on certain Anthropic SDK consumers — naming it explicitly activates parallel emission on runtimes where trickle-dispatch is the default behavior.
If your runtime emits parallel tool_use blocks natively (Claude Code with Claude models), multi_tool_use.parallel may not be needed — but naming it is harmless and serves as an enforcement anchor.
The STOP-CHECK, anti-trickle, and self-verify guards above remain binding regardless of which mechanism your runtime uses.
Dispatch all 7 explorer angles in a single parallel batch. Wait for all before Phase 4.
signal.Notify(.*syscall.SIGHUP paired with re-reading .env, YAML, or os.Getenv post-startup
fsnotify.NewWatcher() watching config files
Goroutines that os.Open a config file on a time.Ticker
Any code path that re-loads env vars after main() has started
Replacement:systemplane.NewPostgres / NewMongoDB + Register + Start + OnChange. Per-key subscriptions replace the global reload pulse.
Severity rationale: SIGHUP/fsnotify reloads are racy by definition (no per-key fan-out, no validator, no audit trail). Hot-reload runtime config without observability is a class of silent misbehavior.
Replacement: Same as Angle 1. Viper's file-watching does not bind keys to validators or redaction policies; lib-systemplane does both at Register.
Angle 3 — Raw pgx LISTEN for config tables (CRITICAL)
DIY patterns to grep:
LISTEN SQL statements in code targeting a config / settings / feature-flag table
conn.WaitForNotification( consumers on settings channels
pgx.Connect long-lived connections used solely for config notifications
Custom NOTIFY triggers on a runtime-config table without debounce or write-through cache
Replacement:systemplane.NewPostgres(db, listenDSN, opts...). The library owns the LISTEN connection lifecycle, debounces per (namespace, key, tenantID) via WithDebounce (default 100ms), and provides a write-through cache so the in-process Get is consistent with the changefeed echo.
Severity rationale: Hand-rolled LISTEN paths typically miss the panic-recovery and reconnect-with-backoff machinery internal/postgres provides — silent goroutine death under load.
mongo.ChangeStream consumers without panic recovery
Polling loops (time.Ticker + Find) over a settings collection
Manual resumeAfter token persistence for config streams
Replacement:systemplane.NewMongoDB(client, "db", opts...). Pass WithPollInterval(...) for standalone Mongo (no replica set); otherwise change-streams are used automatically. The library wraps the subscribe goroutine with runtime.RecoverAndLog.
Angle 5 — Manual tenant-scoping in config reads (HIGH)
DIY patterns to grep:
Custom (tenantID, key) → value map indexed off a global config struct
Calls to core.GetTenantIDContext(ctx) followed by manual cascade to a global value or default
Tenant-specific config columns / Mongo fields read directly without validator or redaction
Missing tenant-ID validation when reading config (no core.IsValidTenantID check)
Replacement:RegisterTenantScoped(...) + GetForTenant(ctx, ns, key) (or the typed GetStringForTenant / GetIntForTenant / GetBoolForTenant / GetFloat64ForTenant / GetDurationForTenant). The library's extractTenantID is fail-closed — ErrMissingTenantContext / ErrInvalidTenantID is returned rather than silently falling back to a shared global.
Severity rationale: Silent fallback from a missing tenant to a shared global is the cross-tenant-leak vector. The library's fail-closed contract makes the bug a loud error instead of a quiet data leak.
Replacement:admin.Mount(router, client, admin.WithPathPrefix(...), admin.WithAuthorizer(...), admin.WithTenantAuthorizer(...), admin.WithActorExtractor(...)). The library serves the full six-route surface (list namespace, get/put one, list tenants for key, put/delete tenant override) with default-deny authorization and per-key redaction.
Severity rationale: Default-deny is the safe-by-default property. Hand-built admin routes routinely ship with weaker authorization than the lib-commons-backed reference implementation.
Supervisor, BundleFactory, ApplyBehavior types or methods
SYSTEMPLANE_* environment variables (the v4-era runtime knobs)
Sub-packages from the v4 layout: domain/, ports/, registry/, service/, bootstrap/ under any systemplane/ tree
lib-commons/v5/commons/systemplane imports (the v5 package was extracted to the standalone lib-systemplane module; lib-commons/v5/commons/systemplane is the pre-extraction location and signals an out-of-date pin)
Runtime DDL provisioning: systemplane.SchemaSQL() called at boot, runSchema-style hooks, CREATE TABLE systemplane_entries executed outside migrations/, missing cmd/generate-systemplane-ddl/ + migrations/systemplane_ddl_manifest.json, missing make systemplane-ddl / check-systemplane-ddl-drift Make targets
Replacement:
v4/v5-extracted paths → switch to the standalone module github.com/LerianStudio/lib-systemplane; delete the v4 sub-packages outright (v5 has no equivalent layers — the API surface is flat).
Runtime DDL → migration-only provisioning via the make systemplane-ddl generator (canonical scaffold: go-boilerplate-ddd once its systemplane-ddl PR lands; reference implementation in plugin-br-bank-transfer at cmd/generate-systemplane-ddl/, migrations/000011_systemplane_schema.{up,down}.sql → 000013_systemplane_project_seed.{up,down}.sql, migrations/systemplane_ddl_manifest.json, and the bootstrap seam SystemplaneSeedEntries() ([]SystemplaneSeedEntry, error) at internal/bootstrap/systemplane_ddl_gen.go).
Severity rationale: v4 packages and the runtime DDL hook are deleted from current lib-systemplane; any surviving call site will fail the build (v4) or fail at boot (runtime DDL under a least-privilege tenant-manager role). Surfacing both in the sweep prevents a CI/runtime surprise.
Read /tmp/systemplane-version-report.json, /tmp/systemplane-delta-report.json,
and /tmp/systemplane-sweep-*.json (7 files).
Emit:
1. /tmp/systemplane-sweep-report.md — aggregate findings by severity
2. /tmp/systemplane-sweep-tasks.json — one task per DIY-pattern cluster
(same file/package = one task). Each task references the matching
replacement API surface from Reference Mode.
MUST NOT invent findings.
MUST NOT omit explorer findings.
MUST NOT reclassify severity without justification.
Surface report path + task count to user; offer handoff to ring:migrating-to-lib-systemplane for the gated implementation cycle, or to ring:running-dev-cycle for ad-hoc remediation.
REFERENCE MODE
The API is small enough to inline. Sections follow the lifecycle order the client enforces at runtime: construct → register → start → read/write/subscribe → close.
db is the read/write handle (returned by sql.Open("pgx", dsn)).
listenDSN is a separate DSN passed to pgx.Connect for the long-lived LISTEN connection. database/sql does not expose its underlying DSN, so the caller supplies it explicitly. Typically equal to the DSN used to open db.
Structured logger (lib-observability). Nil is ignored.
WithTelemetry(*tracing.Telemetry)
nil
OpenTelemetry provider for spans/metrics. Nil is ignored.
WithListenChannel(string)
"systemplane_changes"
Postgres LISTEN channel name. Ignored by MongoDB.
WithPollInterval(time.Duration)
0 (change-streams)
Enables MongoDB polling mode. Ignored by Postgres.
WithDebounce(time.Duration)
100ms
Trailing-edge debounce per (ns, key, tenantID) tuple. Zero/negative disables debouncing.
WithCollection(string)
"systemplane_entries"
MongoDB collection. Ignored by Postgres.
WithTable(string)
"systemplane_entries"
Postgres table. Ignored by MongoDB.
WithLazyTenantLoad(maxEntries int)
eager mode
Switches tenant cache from eager hydration to a bounded LRU (hashicorp/golang-lru/v2). Non-positive max falls back to eager.
WithTenantSchemaEnabled()
false (phase-1 compat)
Drops the legacy (namespace, key) unique constraint and creates the composite (namespace, key, tenant_id) unique. Required before tenant writes succeed. See MIGRATION_TENANT_SCOPED.md §4 for rolling-deploy ordering.
Declares a tenant-scoped key. Same global semantics as Register (Get / Set / List / OnChange still operate on the legacy global row), plus the key becomes eligible for per-tenant overrides via SetForTenant / GetForTenant / DeleteForTenant / OnTenantChange.
Mutable-default caveat (locked in code comments): the registered default is held by reference. A subscriber mutating a slice/map default mutates it for every tenant falling through to the default. Prefer value types or wrap in a defensive copy.
KeyOption setters
Option
Effect
WithDescription(string)
Human-readable description surfaced via KeyDescription and admin GET responses
WithValidator(func(any) error)
Runs against the default at registration AND against every Set / SetForTenant value
WithRedaction(RedactPolicy)
Renders value as raw / "****" / "[REDACTED]" in admin output and logs
Redaction policies
const (
RedactNone RedactPolicy = iota// raw value
RedactMask // "****"
RedactFull // "[REDACTED]"
)
funcApplyRedaction(value any, policy RedactPolicy) any
Any key holding credentials / tokens / secrets MUST use RedactFull. The admin handlers call ApplyRedaction per key on every GET, with the policy looked up via client.KeyRedaction(ns, key).
4. Lifecycle: Start and Close
Start(ctx context.Context) error
Seeds the cache with registered defaults under cacheMu.
Hydrates from the backing store via store.List; unregistered rows are logged and skipped.
Eagerly hydrates the tenant cache (skipped in lazy mode — first-touch populates the LRU).
Launches the subscribe goroutine wrapped in runtime.RecoverAndLog.
Idempotent: a second Start returns nil. Returns ErrClosed on a closed receiver.
Close() error
Idempotent (via sync.Once), safe on a nil receiver.
Cancels the subscribe goroutine and waits up to closeWaitTimeout (10s) for it to exit.
Calls store.Close on the backend adapter. Does not close the externally-owned *sql.DB / *mongo.Client.
5. Reads (nil-receiver safe)
All read accessors return zero values when the receiver is nil, the client is closed, or the key is unregistered.
Untyped
Get(ns, key string) (any, bool) — (value, true) on hit; falls through cache → default.
KeyStatus(ns, key) (registered, tenantScoped bool) — used by admin to distinguish 404 vs 400.
KeyDescription(ns, key) string
KeyRedaction(ns, key) RedactPolicy
Logger() log.Logger — never nil; subpackages (notably admin) reuse the client's logger.
Typed (legacy / globals)
GetString(ns, key) string — "" on miss.
GetInt(ns, key) int — accepts both int and float64 (JSON numbers decode as float64).
Returns all currently-cached entries in the namespace, sorted by key. ListEntry{Key, Value, Description}. Empty namespace → empty slice (never nil).
Typed tenant reads
These mirror the legacy typed accessors but surface errors instead of silently returning zeros. Type mismatches return ErrValidation (configuration bug, not a runtime miss).
GetStringForTenant(ctx, ns, key) (string, error)
GetIntForTenant(ctx, ns, key) (int, error) — rejects non-integral float64 with ErrValidation (silent truncation would convert one bad config into another valid-looking config).
GetForTenant(ctx, ns, key) (value any, found bool, err error)
Resolution order: tenantCache[tenantID][nk] → legacy cache[nk] → registered default. found is true whenever a value is returned (including the default fallthrough — the "no tenant override yet" case is not an error).
6. Writes
Set(ctx, namespace, key string, value any, actor string) error
Globals-only write. Runs the registered validator (if any), json.Marshals the value, persists via store.Set, then write-through-caches the JSON-canonicalized value (so a subsequent GetInt returns a float64 consistently with the changefeed echo).
Errors: ErrClosed, ErrNotStarted, ErrUnknownKey, ErrValidation (validator or non-serializable value), or any wrapped store error.
Subscribers are NOT fired from Set. The changefeed echo drives OnChange. This invariant prevents double-firing and keeps the semantic that OnChange observes backend state changes.
SetForTenant(ctx, namespace, key string, value any, actor string) error
Tenant write. Validates tenant ID via extractTenantID (fail-closed: ErrMissingTenantContext, ErrInvalidTenantID), checks requireTenantScoped (ErrUnknownKey, ErrTenantScopeNotRegistered), runs validator, marshals, persists via store.SetTenantValue, write-through-caches.
DeleteForTenant(ctx, namespace, key, actor string) error
Removes a tenant override. Idempotent at the backend (delete-missing returns nil). On a no-op delete the backend emits no event, so OnTenantChange does not fire — tests relying on the callback must SetForTenant first.
ListTenantsForKey(namespace, key string) []string
Returns the sorted, deduplicated set of tenant IDs with an override for (ns, key). Never returns nil — every error path returns the shared emptyTenantList sentinel. Excludes the _global sentinel. Bounded by an internal 5s timeout.
Per-key callback fired by the changefeed echo for global-row writes (i.e. tenant_id = _global). Callbacks are invoked sequentially, each wrapped in runtime.RecoverAndLog. The returned unsubscribe is sync.Once-guarded; safe to call multiple times.
Nil receiver, nil fn, or unregistered key → no-op unsubscribe.
Tenant-aware callback fired by the changefeed echo for tenant-row writes. The ctx argument is pre-scoped to tenantID via core.ContextWithTenantID, so subscribers can pass it straight into tenant-aware lib-commons facilities (DLQ, idempotency, webhook delivery) without re-propagating the tenant ID.
A single subscription observes every tenant — the tenantID argument distinguishes which override changed.
Invariant (AC8 in the source): OnChange fires exclusively for store.SentinelGlobal events, OnTenantChange fires exclusively for tenant events. The split is on the row's tenant_id, not on whether the key was registered as tenant-scoped.
admin.Mount(router fiber.Router, c *systemplane.Client, opts ...MountOption)
Routes registered (default prefix /system):
GET /<prefix>/:namespace - list entries
GET /<prefix>/:namespace/:key - get one entry
PUT /<prefix>/:namespace/:key - write a global value
GET /<prefix>/:namespace/:key/tenants - list tenants with overrides
PUT /<prefix>/:namespace/:key/tenants/:tenantID - write a tenant override
DELETE /<prefix>/:namespace/:key/tenants/:tenantID - remove a tenant override
Path-segment caps enforced at the edge: namespace ≤ 256 bytes, key ≤ 512 bytes (BadRequest on overflow). Nil router or nil client makes Mount a no-op.
Mount options
Option
Effect
WithPathPrefix(string)
Override the URL prefix (default /system). Empty value ignored.
Authorizes tenant routes. Default: deny-all. For the tenant-list route, tenantID is empty.
WithActorExtractor(func(*fiber.Ctx) string)
Extracts the actor string passed into client.Set / SetForTenant. Default returns "".
Critical contract — default-deny escalation: the two authorizers are independent. Configuring only WithAuthorizer does NOT implicitly grant access to tenant routes (and vice-versa). This prevents a silent privilege escalation: a service that pre-dates tenant support and configures only WithAuthorizer cannot accept tenant writes it was never authorized to handle.
Wire-redaction contract: authorizer error strings are NOT echoed on the wire (the body is the fixed string "forbidden"). The original error is logged at Debug level.
9. Errors (sentinel set)
All exported as package-level vars; check via errors.Is.
Sentinel
When
ErrClosed
Receiver is nil or Close has run
ErrNotStarted
Read/write before Start
ErrRegisterAfterStart
Register / RegisterTenantScoped after Start
ErrUnknownKey
Unregistered (namespace, key)
ErrValidation
Validator rejected the value, non-JSON-serializable value, or typed accessor mismatch
ErrDuplicateKey
Re-registration of the same (namespace, key)
ErrMissingTenantContext
Tenant-scoped op called without a tenant ID in ctx
ErrInvalidTenantID
Tenant ID fails core.IsValidTenantID or equals _global sentinel
ErrTenantScopeNotRegistered
Tenant-scoped op against a key registered via Register
ErrTenantSchemaNotEnabled
Tenant write against a phase-1 backend (re-exported from internal/store)
10. Test Harness (NewForTesting)
Build-tag gated: compiled only under -tags=unit or -tags=integration. Excluded from production binaries.
//go:build unit || integration
client, err := systemplane.NewForTesting(myTestStore,
systemplane.WithDebounce(0), // already the default for testing
)
TestStore mirrors the internal store.Store interface with public TestEntry / TestEvent types.
Debouncing is disabled by default for deterministic tests (override via WithDebounce).
API stability is not promised — the harness is intentionally undocumented in README/API docs.
For contract testing against a real backend, see systemplanetest in the library repo (separate package, mirrors lib-commons conventions).
11. Composition With Adjacent Libraries
Library
Touchpoint
lib-commons/v5/commons/tenant-manager/core
ContextWithTenantID, GetTenantIDContext, IsValidTenantID — the only allowed tenant-ID extraction path. OnTenantChange pre-scopes ctx via ContextWithTenantID.
lib-observability/log
WithLogger accepts a log.Logger. Logger is reused by admin via client.Logger() — no parallel admin logger option exists.
lib-observability/tracing
WithTelemetry(*tracing.Telemetry) enables spans on Start / Set / GetForTenant / SetForTenant / DeleteForTenant / ListTenantsForKey.
lib-observability/runtime
runtime.RecoverAndLog wraps the subscribe goroutine and every OnChange / OnTenantChange callback dispatch.
lib-commons/v5/commons/net/http
The admin package uses commonshttp.RespondError for uniform error responses.
lib-systemplane v1.6.0+ publishes the DDL it needs as two public functions and removes the runtime runSchema hook. Consumers MUST fold the artifacts into their own SQL migration pipeline; provisioning at boot is FORBIDDEN.
Artifact
Returns
Folds into
systemplane.SchemaSQL() string
Byte-faithful DDL for systemplane_entries table + systemplane_notify_v3 function + 2 triggers (fully idempotent: CREATE TABLE IF NOT EXISTS / CREATE OR REPLACE / DROP TRIGGER IF EXISTS). Channel systemplane_changes, table systemplane_entries are fixed (no placeholders).
migrations/NNN_systemplane_schema.up.sql (down = drop triggers + function, never the table)
systemplane.DefaultSeedSQL() string
INSERT ... ON CONFLICT (namespace, key) DO NOTHING over the universal default keys (the lib's own runtime knobs).
migrations/NNN+1_systemplane_default_seed.up.sql (down = value-guarded DELETE of the universal keys)
Canonical scaffold:make systemplane-ddl (generator under cmd/generate-systemplane-ddl/) vendors both artifacts into append-only migrations + a migrations/systemplane_ddl_manifest.json, then emits a third project-seed migration derived from the service's own registrations via a bootstrap seam returning []SystemplaneSeedEntry. The full pattern (seam contract, manifest, drift guard, MT/ST symmetry) is normative in multi-tenant.md §27 "Cold-tenant resolution" and operational in ring:migrating-to-lib-systemplane Gate 3.5. Reference implementation: plugin-br-bank-transfer (cmd/generate-systemplane-ddl/, internal/bootstrap/systemplane_ddl_gen.go, migrations/000011..000013_systemplane_*).
Invariants (locked):
NEVER call SchemaSQL() or DefaultSeedSQL() at boot. Runtime DDL is a CRITICAL deviation — least-privilege tenant-manager roles cannot execute it.
NEVER hand-edit a generated migrations/NNN_systemplane_*.sql. The generator is the only writer; check-systemplane-ddl-drift enforces this.
ALWAYS expose the seam — same signature (SystemplaneSeedEntries() ([]SystemplaneSeedEntry, error) or equivalent) across services. The generator depends on it; ad-hoc per-project shapes break the scaffold contract.
ST and MT use the SAME migration pipeline (single-tenant migrate-up or multi-tenant tenant-manager provisioning — same .sql files).
13. Scope Reminder (locked)
Systemplane is for runtime-mutable knobs only. Bootstrap-only configuration (DB DSNs, secrets, TLS material, telemetry endpoints, server identity, listen addresses) belongs in environment variables or a secret manager — never in the systemplane plane. Anything requiring resource teardown to apply (reopening a DB pool, rotating a TLS cert) violates the hot-reload contract by definition.
14. Cross-references
ring:migrating-to-lib-systemplane — gated end-to-end migration cycle (stack detection → v5 upgrade → register → subscribe → admin mount → tests → review). Use after this skill identifies adoption opportunities.
[[ring:using-lib-commons]] — tenant-manager/core, idempotency, DLQ, webhook delivery, and the broader v5 surface that composes with systemplane.
[[ring:using-lib-observability]] — log.Logger, tracing.Telemetry, runtime.RecoverAndLog — the three injected by WithLogger / WithTelemetry.
[[ring:using-runtime]] — panic-observability trident used internally for the subscribe goroutine and callback shields. Match the same policy elsewhere in your service.
