/using-lib-commons

name: ring:using-lib-commons
description: "Using lib-commons v5, Lerian's shared Go library (non-observability surface), in two modes. Sweep Mode detects DIY code replaceable by lib-commons at file:line. Reference Mode catalogs lifecycle (Launcher), outbox repo, circuit breakers, tenant management, idempotency, security/TLS, database, and HTTP toolkit. Observability moved to ring:using-lib-observability. Go-only. Skip for non-Go."

ring:using-lib-commons

> **Scope note (lib-observability v1.0.0):** The observability layer — `log`, `metrics`, `tracing`, `zap`, `assert`, `runtime` (panic recovery), `redaction`, and OTel attribute constants — **moved out of lib-commons into `github.com/LerianStudio/lib-observability`** as of v1.0.0. lib-commons v5 keeps deprecated shims for back-compat, but this skill is no longer the canonical reference for those packages. For observability work, dispatch [[using-lib-observability]] (top-level) or its dedicated sub-skills [[using-tracing]] / [[using-runtime]] / [[using-assert]]. This skill now focuses on lib-commons's non-observability surface: lifecycle (`commons.Launcher`), outbox repository (writer side lives in [[using-lib-streaming]]), circuit breakers, tenant management, idempotency, security/TLS, database connections, messaging (RabbitMQ command queues; events go through [[using-lib-streaming]]), HTTP toolkit.

When to use

Sweep mode:

• "Sweep the codebase for lib-commons opportunities"
• "Find where we could use lib-commons instead of DIY"
• "Audit this service for lib-commons compliance"
• "Identify lib-commons migration opportunities"

Reference mode:

• Need to understand what lib-commons provides
• Looking for the right package/API for a task
• Setting up a new service that uses lib-commons
• Need correct constructor/initialization patterns
• Working with multi-tenancy (tenant-manager subsystem)
• Working with event-driven tenant discovery

Skip when

• Working on non-Go services
• Working on frontend code
• Target codebase is Ring itself (no lib-commons dependency)

Related

**Similar:** ring:using-dev-team, ring:planning-backend-refactor **Observability layer (moved to lib-observability):** [[using-lib-observability]], [[using-tracing]], [[using-runtime]], [[using-assert]] **Adjacent libs:** [[using-outbox]], [[using-lib-streaming]], [[using-lib-systemplane]]

Mode Selection

| Request Shape | Mode | |---|---| | "Sweep / audit / find opportunities / migrate to lib-commons" | **Sweep** | | "What does lib-commons provide for X?" | **Reference** | | "How do I initialize Y from lib-commons?" | **Reference** | | "Replace our DIY webhook delivery with lib-commons" | **Sweep** |

---

SWEEP MODE

Orchestrate a 4-phase sweep. Each phase has a hard gate — do not proceed until the current phase produces its artifact.

Phase 1: Version Reconnaissance   → version-report.json
Phase 2: CHANGELOG Delta Analysis → delta-report.json
Phase 3: Multi-Angle DIY Sweep    → 22 × libcommons-sweep-{N}-{angle}.json
Phase 4: Consolidated Report      → libcommons-sweep-report.md + tasks.json

Phase 1: Version Reconnaissance

1. Read `go.mod` — extract pinned version of `github.com/LerianStudio/lib-commons/vN` 2. WebFetch `https://api.github.com/repos/LerianStudio/lib-commons/releases/latest` — extract `tag_name` 3. Classify drift: up-to-date / minor-drift / moderate-drift / major-upgrade / module-mismatch 4. If v4.x detected: add major upgrade advisory flag 5. Emit `version-report.json`: `{pinned_version, latest_version, drift_classification, major_upgrade_required, module_path}`

Phase 2: CHANGELOG Delta Analysis

1. WebFetch `https://raw.githubusercontent.com/LerianStudio/lib-commons/main/CHANGELOG.md` 2. Extract entries between pinned_version (exclusive) and latest_version (inclusive) 3. Classify each: `new-package` / `new-api` / `breaking-change` / `security-fix` / `performance` / `bugfix` 4. Emit `delta-report.json` with classified entries

Phase 3: Multi-Angle DIY Sweep

Dispatch all 22 explorer angles in **3 batches** (8+8+6). Wait for each batch before next.

| Batch | Angles | Focus | |---|---|---| | 1 | 1–8 | Infrastructure + HTTP | | 2 | 9–16 | Ergonomics + security + observability-shim detection | | 3 | 17–22 | Resilience + multi-tenant + utilities |

⛔ STOP-CHECK BEFORE DISPATCH (each batch)

Before emitting any Task call in a batch, count the explorers you intend to launch in this turn.

• Count MUST equal the batch size declared above (8, 8, or 6).
• If your dispatch count diverges from the batch size → STOP and reconcile against the batch row.
• No substitutions, no omissions within a batch.

⛔ MUST NOT trickle-dispatch within a batch

All explorers in a batch leave in the SAME TURN, before reading any explorer output.

Forbidden sequences:

• Dispatch explorer 1 → read result → dispatch explorer 2
• Dispatch a subset of the batch → wait → dispatch the rest
• Dispatch follow-up explorers conditioned on partial output
• Loop sequentially over the batch's angle list

If you find yourself about to dispatch an explorer in a turn AFTER any explorer in the SAME batch has already returned a result → STOP. You violated parallel dispatch. Report the violation and mark the batch INCOMPLETE rather than completing the trickle. (Sequential batch ordering is intentional; trickle within a batch is not.)

Self-verify after dispatch

After each batch's dispatch turn, verify all batched Task calls were emitted in that single turn. If fewer went out than the batch size, the batch did NOT execute correctly. Mark INCOMPLETE and surface the dispatch failure — do NOT silently continue with a partial batch.

Parallel dispatch — atomic batch (within this batch)

Emit all Task calls for THIS BATCH in a SINGLE TURN, as one atomic batch. (Batches themselves remain sequential — do not dispatch batch N+1 until batch N has fully returned.)

**If your runtime exposes a `multi_tool_use.parallel` wrapper**, use it to dispatch the comp