@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/http-gateway-client-patterns.md

@@ -0,0 +1,76 @@
+# HTTP Gateway And Client Patterns
+
+Use this when implementing HTTP handlers, generated routes, middleware, API docs, or generated HTTP clients.
+
+## Generated Route Files
+
+- Keep generated route registration files marked as generated and do not hand-edit them.
+- Use generator-supported insertion points or separate custom registration functions for custom routes.
+- Regenerate routes after IDL path, method, handler path, or middleware annotations change.
+- If generator output contains placeholder handler bodies, replace behavior in preserved handler files or application services, not in overwritten files.
+- Route tests should assert method, path, middleware presence, and auth bypass behavior for changed endpoints.
+
+## Handler Implementation
+
+- Bind and validate request structs at the transport boundary.
+- Authenticate and resolve authorization context before domain-side effects.
+- Convert path/query/header/body fields into a command/query object instead of passing raw HTTP context into application logic.
+- Return responses through one response builder or canonical envelope.
+- Map validation failures, auth failures, dependency failures, and domain failures through the canonical error mapping.
+- Keep generated documentation comments synchronized with the source contract; do not maintain duplicate route tables by hand.
+
+## Middleware Hooks
+
+- Middleware factory functions should return stable ordered lists and be easy to test.
+- Keep no-op middleware hooks explicit when the generator requires them.
+- Do not capture per-request mutable state in package-level middleware variables.
+- Middleware should add typed context values for trace/log id, auth subject, authorization scope, lane/environment, and request deadline when needed.
+- Recovery middleware should convert panics into canonical errors and preserve trace/log id in logs.
+
+## Generated HTTP Client
+
+- Build requests through a typed builder that supports context, path params, query params, headers, body, form fields, files, and request options.
+- Escape path parameters and encode repeated query parameters predictably.
+- Detect or set content type before serializing body payloads.
+- Do not send body payloads for HTTP methods where the client or gateway does not support them.
+- Handle gzip or other negotiated compression before unmarshalling.
+- Decode successful response bodies into typed responses and error bodies into typed errors when the server provides them.
+- Let callers override the response-success policy when HTTP status alone is not enough.
+- Return raw response metadata where callers need status, headers, or request diagnostics.
+
+## IDL-First Hertz Layout
+
+When the HTTP gateway uses an IDL-driven generator (Hertz `hz`, gateway-style tools, etc.), the resulting layout has three intentional tiers:
+
+- `<hertz_gen>/router/<domain>/`: generator output binding IDL methods to URL paths and HTTP verbs. Treat as generated code; do not hand-edit. Regenerate when IDL changes.
+- `api_methods/`: thin handwritten stub per IDL method. Its job is exactly three things: declare the typed request struct, call `c.BindAndValidate(&req)`, then dispatch to the business handler. Stubs may be initially generated and then frozen with a "do not edit" header; subsequent edits go through the generator only when the IDL changes.
+- `handler/<domain>/`: the actual business logic — application service calls, cross-RPC calls, response mapping. Domain code never appears in `api_methods/` and validation logic never appears in `handler/`.
+
+This separation makes IDL evolution cheap (regenerate `router/`, untouched `api_methods/`, business handler unchanged) and keeps each tier reviewable in isolation.
+
+## Double-Layer Middleware Composition
+
+- Framework-default middleware (recovery, ctx injection, metrics, tenant info, tracing) is registered inside the server-construction wrapper. Business-level middleware (CORS, auth/login, logging, custom ctx) is appended in the service's `main()`.
+- Document both layers and the resulting order so reviewers can see which step happens before which. A typical merged order: `CtxInject → Recovery → Metrics → TenantInfo` (framework) then `CORS → UserAuth → Login → RequestLog → CustomCtx` (business).
+- Do not let two middleware do the same job in different layers (e.g., two recovery wrappers, two metrics counters) — duplicate metrics inflate counters and double-handling of panic obscures the stack trace.
+- Recovery middleware must sanitize the response: return a stable error code (`coderr.ServerPanic` or equivalent) and a generic message; never put the panic value, stack trace, or internal error chain in the response body. The stack trace belongs in the log and the trace, not in the JSON.
+- Route-level middleware stubs that exist but have empty bodies are dead code; either implement them or delete them. Empty stubs invite future engineers to assume coverage that does not exist.
+- The same risk applies to **scaffold-generated VALIDATION GATES that ship with placeholder content** — distinct from generator-required no-op middleware hooks and extension hooks, which are explicitly allowed empty per the rules above (`http-gateway-architecture.md` Route And Middleware Design "generated middleware hooks should default to no-op", and the "Keep no-op middleware hooks explicit when the generator requires them" rule in the Middleware Hooks section above). A validation gate is identified by **scaffold naming convention** (`check<HandlerName>`, `validate<X>`, `precondition<X>`) — i.e. functions whose name the scaffold uses to signal "this is a validation gate". Defining the gate by call-site position is not enforceable because the lint cannot reliably read intent; the naming convention is the contract between scaffold and reviewer. The scaffold template MUST use the conventional gate name when emitting a validation-gate function — emitting a gate under a non-conventional name (e.g. a generic `hook<X>` that downstream code treats as validation) is itself the bug; fix the scaffold template, not the lint. A gate function body of `// your codes...\nreturn nil` (or any equivalent placeholder comment + bare success return) is a "validation passed" claim that the validation in fact never ran. Required: the build/CI lint fails on a gate-named function whose body lacks an error-returning path. The AST check is "the function has at least one statement that can return a non-nil error (`return ...err...`, `return errdef.X`, `return fmt.Errorf(...)`)" — adding logging, metrics, or a dummy expression without an error path does NOT satisfy the lint. Detection by grep on the placeholder comment is a minimal floor; the AST/error-path check is the real defense.
+
+## API Documentation Generation
+
+- Use the framework's IDL-driven doc generator (Hertz `hz` doc, swag/swaggo, protoc-gen-doc) and expose the docs endpoint only in non-production environments or behind explicit auth.
+- Doc generation should run from the same Makefile target as code generation so docs and binding rules never drift.
+
+## Tests
+
+- Test binding for path, query, header, body, form, repeated fields, and enum values when used.
+- Test invalid input, missing auth context, canonical error mapping, empty responses, compressed responses, and non-JSON error bodies.
+- Test generated clients with a fake Doer/client instead of live network by default.
+- Keep generated-code snapshots or clean-generation checks only where generator churn is controlled.
+- For IDL-first layouts, include a smoke test that proves a fresh regeneration of `router/` plus untouched `api_methods/` and `handler/` still compiles and routes correctly. This catches the case where the generator changes its emitted shape.
+- For recovery middleware, assert that a panic produces a stable error code and a sanitized message, and that the stack trace appears only in the log capture, not in the response body.
+
+## stdlib net/http As Option
+
+- **Go 1.22+ `net/http.ServeMux` got enhanced routing** — pattern syntax now supports method matching (`"GET /users/{id}"`), path wildcards (`{id}`, `{path...}` trailing wildcard), and host matching. Per the net/http docs, route precedence is based on specificity (most-specific pattern wins), and `r.PathValue("id")` reads the matched wildcard. Use stdlib `http.ServeMux` when (a) the service is a small internal tool / admin endpoint / health-probe shim where pulling Hertz/Kitex is over-engineering, (b) the binary needs to be importable as a library and avoid the framework's transitive dependency, (c) the team is writing a sidecar / sidecar-helper / migration utility. For the team's main product services, Hertz remains the default (richer middleware, observability adapters, codegen integration); stdlib ServeMux is an intentional alternative for narrow scope, not a Hertz replacement. **Do NOT mix stdlib `ServeMux` mid-service inside a Hertz application for "just one admin endpoint"**: the stdlib handler runs outside Hertz's middleware chain, so observability (request log, metrics, tracing), auth, rate limiting, panic recovery, and ctx propagation that Hertz attaches to other routes will silently bypass the stdlib-handled endpoint. Either route the admin endpoint through Hertz with its own middleware subset, or use Hertz's v0.10+ `http.Handler` adapter to wrap the stdlib handler so Hertz middleware still applies — never let two HTTP routers serve the same binary's port without an explicit boundary review.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/mq-consumer-patterns.md

@@ -0,0 +1,55 @@
+# MQ Consumer Patterns
+
+Use this when implementing MQ consumers, producers, event handlers, delayed tasks, or async side effects.
+
+## Constructor And Startup
+
+- Create one small consumer struct per topic/group responsibility; inject service logic, repositories, and dependency clients.
+- Load topic, consumer group, credentials, worker count, retry count, filters, and activation gates from typed config.
+- If the queue supports vendor-specific features, such as message tags, server-side selectors, table-change filters, ordered or broadcast delivery, delayed delivery, lane metadata, or log/trace properties, model them as typed config or producer/consumer wrapper behavior rather than inline literals.
+- Producers should inject trace/log and lane/environment metadata into outgoing messages when the platform supports it; consumers should restore that context before calling application logic.
+- Build all consumers through DI and expose an aggregate starter only at the application boundary.
+- Startup should return errors to the main runtime; fail fast for required consumers and skip cleanly for disabled optional consumers.
+- Do not create consumers with nil handlers or missing group config.
+- If a durable outbox relay is needed, implement it as an infrastructure/platform worker with typed config, lifecycle ownership, readiness/metrics, and a repository/publisher boundary. Do not duplicate outbox scan, retry, publish, and status-transition loops in each business feature.
+
+## Handler Flow
+
+- Handler shape should be: create/receive context, decode typed payload, validate, pre-handle/drop, call application logic, map result to ack/retry.
+- Do not let raw message bodies leak past the consumer boundary.
+- Treat malformed payloads as permanent failures: log safe context, alert if needed, and acknowledge or dead-letter according to policy.
+- Return retryable errors for transient dependency failures.
+- Return success for irrelevant or intentionally skipped events after logging the reason.
+- Add idempotency around every side effect that can be repeated by duplicate delivery.
+- If ordering is configured, keep worker count or partitioning consistent with the ordering key; if ordering is not configured, re-read current state before every side effect that depends on sequence.
+- Handler return values must intentionally map to queue ack/retry/drop behavior. Do not let an incidental error type decide whether the message is retried.
+
+## Durable Outbox Relay
+
+- Store the event before or in the same transaction as the state change that requires publication.
+- Relay workers should claim rows with a bounded batch size, lease timeout, retry threshold, next-attempt timestamp, poll interval, and optional jitter; all knobs belong in typed config.
+- Lock ownership must be unique across container replicas and process restarts. Prefer service plus pod or host identity plus process id or random instance id; service plus pid alone is not enough in containerized runtimes.
+- Do not assume a relay preserves emit order once retries, batching, or multiple replicas are involved. Consumers must tolerate reordering, or the relay must enforce ordering by an explicit partition or ordering key.
+- Publish success should transition the outbox row to a terminal published state. Publish failure should persist a safe truncated error, increment attempts, apply bounded backoff, and move to a terminal failed state after the threshold.
+- Expired processing leases should be repaired by a bounded release step before claiming new work.
+- Relay publish payloads should preserve the same envelope shape as synchronous publishers so consumers do not need separate handling paths.
+- Tests should cover claim ordering, duplicate or missing ownership, success transition, retry transition, terminal failure threshold, expired lease repair, and publisher payload shape.
+
+## Dynamic Activation
+
+- Check environment/lane or feature-gate activation before starting the consumer, not inside every message unless the policy must change live.
+- If live activation changes are required, keep the active snapshot atomic and define what happens to in-flight messages.
+- Log skipped startup with consumer group, topic, current environment/lane, and selected config version.
+
+## Latency And Alerting
+
+- Measure each message handler duration.
+- Emit metrics for received, decoded, dropped, succeeded, retried, failed, and slow messages.
+- Slow-message alerts should include event type, event id or safe resource id, consumer group, topic, and trace/log id.
+- Redact or truncate payloads in alerts; never send raw secret-bearing bodies.
+
+## Tests
+
+- Unit-test decode failure, validation failure, skip/drop, retryable dependency error, idempotent duplicate, slow handler alert, and disabled startup.
+- Use fake queue clients and fake service logic by default.
+- Integration tests with real queue infrastructure should be opt-in and isolated from the fast test target.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/notification-patterns.md

@@ -0,0 +1,42 @@
+# Notification Patterns
+
+Use this when implementing notification clients, webhooks, operator alerts, callbacks, or delivery jobs.
+
+For durable delivery state, retries, and terminal-state behavior, also apply `state-machine-task-patterns.md`.
+
+## Client
+
+- Wrap each delivery provider behind an interface with `Send(ctx, message) error`.
+- Build requests with context deadlines, content type, status-code validation, and response body size limits.
+- Treat empty message batches as no-op.
+- Do not use package-level mutable clients unless construction is deterministic and test substitution is available.
+- Parse provider responses into canonical success, retryable error, and permanent error.
+
+## Message Shape
+
+- Include notification type, recipient or endpoint reference, template id/version, actor or service identity, trace/log id, safe summary, and dedupe key.
+- Render templates through typed variables, not string concatenation of raw objects.
+- Redact secrets, credentials, tokens, signatures, and large payloads.
+- Add environment and service metadata from a safe allowlist.
+
+## Async Delivery
+
+- Critical delivery should use an outbox table or durable queue with retry count, next retry time, terminal status, and last error.
+- Best-effort alerts may run asynchronously, but must recover panic and emit logs or metrics on failure.
+- Use bounded concurrency and backoff.
+- Group or throttle repeated alerts by stable fingerprint.
+- Flush or drain delivery workers during graceful shutdown when messages are critical.
+
+## Realtime Client Channels
+
+- For WebSocket or similar realtime notification channels, authenticate and resolve app, tenant, and user context before upgrading the connection.
+- Keep connection identity in a concurrency-safe registry keyed by the smallest delivery scope, and remove the client in `defer` on disconnect.
+- Rebuild initial client state from the durable store when a user connects for the first time or when cache state is absent.
+- Maintain cached unread/count state with explicit TTL refresh and atomic increment semantics; do not let a missing realtime cache create a durable-count side effect.
+- Queue consumers should treat disconnected clients as a no-op delivery outcome after durable storage succeeds.
+- Send a snapshot after connect, then send deltas or latest-message payloads; both payload shapes should be versioned or typed enough for clients to distinguish.
+
+## Tests
+
+- Test empty batch, timeout, non-2xx response, malformed response, retryable vs permanent errors, redaction, template rendering, dedupe key, throttling, and shutdown drain.
+- Test realtime connect, duplicate connection, disconnect cleanup, cache-miss bootstrap, unread increment, disconnected delivery no-op, malformed payload, and websocket write failure.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/observability-implementation-patterns.md

@@ -0,0 +1,101 @@
+# Observability Implementation Patterns
+
+Use this when implementing middleware, context propagation, service discovery clients, logs, metrics, tracing, or runtime introspection in a Go microservice.
+
+## Context Injection
+
+- At the inbound edge, create or accept a trace/log id and put it into context once.
+- Put environment/lane, service name, caller identity, auth subject, and authorization/resource scope into typed context helpers instead of passing ad hoc maps.
+- Keep workload/service identity separate from end-user subject and client application identity.
+- Return trace/log id in HTTP headers or response metadata when the protocol supports it.
+- For RPC clients, write trace/log id and lane into outgoing metadata.
+- For RPC servers, read trace/log id and lane from metadata, then normalize into context for application code.
+- For async producers, copy trace/log id and lane into message headers or payload metadata.
+- For async consumers, restore metadata into context and create a new log id only when none exists.
+
+## Request Logging Middleware
+
+- Log request start and finish in one middleware.
+- Include method, route or method name, caller, service, lane, app/client id when safe, trace/log id, status, canonical error code, and latency.
+- Request and response bodies must be opt-in by config/environment and size-limited.
+- Redact tokens, cookies, signatures, passwords, secrets, and raw authorization headers.
+- Do not log request bodies for upload, streaming, large batch, or sensitive callback endpoints by default.
+- Recovery middleware should log panic stack with trace/log id and return a canonical internal/panic error.
+
+## Metrics Middleware
+
+- Record request count at entry and latency at exit.
+- Record success and error counts after response/error mapping.
+- Add canonical error code as a label for failures.
+- Use histograms for latency and gauges for current queue lag, active workers, and in-flight requests.
+- Heartbeat/progress metrics are useful for long-running requests and jobs, but should have a configurable interval to avoid excessive metric volume.
+- Build metrics clients with bounded async buffers. Dropped metrics should not block request handling.
+
+## Tracing Implementation
+
+- Initialize the tracer provider once during server startup and close it during graceful shutdown.
+- Add resource attributes for service name, environment/lane, pod/host id, and process metadata.
+- Use server-side tracing middleware for inbound HTTP/RPC and client-side tracing middleware for outbound calls.
+- Record dependency operation names as spans: DB query, Redis command, RPC method, HTTP endpoint, MQ publish/consume, and scheduled job.
+- Add span events for important state transitions, not every log line.
+- Set span status and record errors at the boundary where errors are classified.
+
+## Service Discovery Clients
+
+- Construct internal clients with a resolver/discovery abstraction.
+- Register server instances with service name, address, weight, and low-cardinality tags.
+- Attach workload identity, mTLS config, or signed service-token credentials according to the chosen internal trust model.
+- For local development, support an explicit proxy or local resolver path rather than changing production resolution behavior.
+- Implement same-lane lookup before baseline fallback when the product uses lane-based routing.
+- Fail fast when no healthy instance remains; do not silently call a random host.
+- Client timeout, retry, circuit breaker, and error handling should be set alongside the resolver.
+
+## Runtime Endpoints
+
+- Add `/_health` or equivalent for liveness.
+- Add readiness if serving correctly depends on external dependencies.
+- Add a ping/introspection endpoint only when useful; include service, lane/environment, instance, caller address, and status.
+- Register debug/profiling endpoints only on internal listeners or behind environment/auth gates.
+- Generated docs endpoints should be disabled or protected in production unless intentionally public.
+
+## Sidecar Health And Registration
+
+- If a sidecar owns service registration, validate service name, port, pod or host IP, and lane/environment before registering; fail fast when identity is missing.
+- Register only after the main workload is expected to serve traffic, and deregister during graceful shutdown.
+- Bound registration retries and log every failed attempt with service identity, endpoint, and retry count.
+- Local health probes should use short timeouts, a failure threshold, and a fixed interval; after threshold failure, emit metrics and capture safe recent logs when available.
+- Sidecar stop paths need a bounded timeout, idempotent start/stop state, and tests for duplicate start, stop-before-start, registration failure, health failure, and deregistration failure.
+
+## Shutdown And Closers
+
+- Server constructors should return both the server and a cleanup function or closer list.
+- Graceful shutdown should close tracing/metrics providers, log writers, MQ consumers/producers, DB pools, Redis clients, and background workers.
+- Cleanup should flush logs and metrics after stopping traffic.
+- Use panic-safe cleanup around server exit paths.
+
+## Verification
+
+- Test middleware with fake requests and assert context values, response headers, logging controls, and error mapping.
+- Test RPC metadata propagation on client and server sides when the transport supports it.
+- Test metrics label sets for cardinality regressions.
+- Test discovery fallback behavior: same lane, baseline fallback, no healthy instance, and local development mode.
+- Test debug endpoint exposure rules by environment/auth state.
+
+## Metric Naming And Standard Label Set
+
+Metric naming is a service-wide contract — once a name pattern is wrong it is expensive to migrate downstream dashboards and alerts.
+
+- Use snake_case with a `{category}_{operation}_{suffix}` shape: category names the surface (`kitex_server`, `kitex_client`, `hertz_server`, `mq_consumer`, `db_dal`), operation names what is happening (`method`, `invoke`, `request`), suffix names what the metric measures (`qps`, `latency`, `err_qps`, `success_rate`).
+- Define metric names in a single central file (e.g., `metrics_name.go`) per service or platform package; do not let metric names appear as inline string literals throughout the code.
+- Standardize a base label set for every RPC metric so dashboards can join across services without renaming: `caller`, `caller_cluster`, `caller_env`, `caller_method`, `callee`, `callee_cluster`, `callee_env`, `method`, `err_code`. Add domain-specific labels sparingly — every new label multiplies cardinality.
+- Refuse to attach user-id, tenant-id, request-id, or any high-cardinality identifier as a metric label. These belong in traces and logs.
+- For latency, decide histogram boundaries (or summary quantiles) at the platform layer and reuse across services; ad-hoc per-service buckets defeat cross-service comparison.
+
+## Logger Adapter Surface And Trace Linkage
+
+- Pick one structured logger and wrap it with per-framework adapters: Kitex `klog.FullLogger`, Hertz logger, GORM logger, MQ/RocketMQ logger. The adapter is responsible for matching the framework's interface while emitting the same JSON shape and the same field names.
+- **`log/slog` (Go stdlib, stable since Go 1.21) is the current default-recommendation for a new service's primary structured logger** — same `Logger` / `Handler` shape as zap/zerolog, JSON or text handlers built-in, attribute groups, context-aware logging via `slog.Logger.With(...)`, replaceable via `slog.SetDefault()`. Zap remains a valid choice when (a) the team already has zap-based adapters across Kitex/Hertz/GORM and the migration cost is not justified, (b) zap's lower-allocation hot-path matters on a profiled workload (slog has slightly higher allocation in its general case). Zerolog stays the niche choice for "minimal-allocation at all costs" production logging. For new greenfield services on Go 1.21+, prefer slog and wrap it for the framework adapters; for existing zap-based services, schedule the migration only when adapter rewrites are justified — do not mix slog and zap in the same service (two structured-log JSON shapes will fork log parsers and break correlation). **Framework-adapter migration is the load-bearing risk, not the application call sites**: Kitex `klog.FullLogger`, Hertz logger, GORM logger, MQ adapters historically wrap zap and emit zap's JSON field shape (e.g. zap uses `ts`/`level`/`msg`/`caller`; slog defaults differ). If the application code switches to slog while framework adapters still write zap-shape JSON, the service emits two structured-log schemas and downstream log parsers, alerts, SLO queries, and correlation joins fork silently. **Treat the schema-drift risk as P1 when logs feed alerts or SLOs**; the migration plan must include rewriting each framework adapter to a slog-backed implementation in the same slice as the application switch (or using `slog.NewLogLogger` shim + a custom Handler that normalizes field names), with a post-migration log-parser validation step that confirms every framework's output still matches the platform's expected schema.
+- The application-facing logger must accept `ctx` and read trace identity from it. Emit `_trace_id`, `_span_id`, `_trace_flags`, and `_logid` (or the project's equivalent four fields) automatically; do not require callers to pass them as args.
+- When the OTel SDK is present, the logger should also call `span.AddEvent(message, attributes)` on the active span so logs and traces correlate in the backend without manual join. Set the span status from the log level only at logical error boundaries — do not let every warn-log flip the span to error.
+- Use the framework's built-in OTel instrumentation where available: Kitex server suite, Hertz tracing middleware, GORM tracing plugin. Configure the OTel provider with stable resource attributes (`service.name`, `service.namespace`, `service.version`, `lane`, `pod.ip`, `pod.name`) once at process start.
+- For long-running coroutines, SSE/websocket handlers, and consumer loops, end the per-message span instead of letting one giant span span the whole connection.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/performance-capacity-patterns.md

@@ -0,0 +1,44 @@
+# Performance And Capacity Patterns
+
+Use this when implementing Go backend capacity controls, batch jobs, replay/shadow workers, or DB performance guards.
+
+## Bounded Concurrency
+
+- Use semaphores, worker pools, or queue consumers to cap concurrent external calls and heavy CPU work.
+- Derive default concurrency from config, not only CPU count; CPU-based defaults are a fallback.
+- Always release semaphore slots with `defer` or structured scope; structure each successful acquire to have exactly one release, and guard the release (e.g. `sync.Once`) only where it can genuinely race or double-fire — test the double-release path rather than letting a wrapper silently absorb the bug. For a request-admission limiter without a designed bounded queue, prefer a non-blocking acquire that rejects fast under overload and pre-checks `ctx.Done()` before admitting; where a bounded queue is intended, use `Acquire(ctx)` with a defined max wait and cancellation instead.
+- Pass `context.Context` through every bounded task and stop dispatching when the context is canceled.
+
+## Batch Jobs
+
+Implement batch jobs with:
+
+- CLI/config options for `batch_size`, `concurrency`, `limit`, `dry_run`, timeout, and report output;
+- cursor or checkpoint rather than unbounded scans;
+- per-row outcome with success/failure/skipped status;
+- bounded error samples;
+- final report containing processed count, success count, failure count, duration, and next resume point.
+
+Do not let batch jobs rely on invisible process logs only.
+
+## Replay And Shadow Workers
+
+- Persist replay task status: pending, running, completed, failed, canceled.
+- Store total, processed, success, failed, start/end timestamps, and metadata.
+- Use a task registry or lock to prevent duplicate in-process execution.
+- Scheduled replay needs a distributed lock and explicit timeout.
+- Compare candidate and baseline responses with predeclared thresholds and retain diffs for review.
+
+## Database Guards
+
+- Configure DB max open/idle connections and connection lifetime according to service concurrency.
+- Add focused tests or non-production hooks that catch missing indexes for known large queries.
+- Prefer generated or typed DAL methods with explicit filters, pagination, and ordering.
+- Avoid production-only query surprises by checking explain plans during development and staging.
+
+## Timeout And Repair
+
+- Every async task should have a timeout threshold per state.
+- Stuck tasks should transition to retryable state until retry budget is exhausted, then terminal failure.
+- Repair jobs should log both the stuck duration and retry count.
+- Retried jobs must be idempotent or guarded by a domain idempotency key.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/protobuf-contract-patterns.md

@@ -0,0 +1,72 @@
+# Protobuf Contract Patterns
+
+Use this when editing `.proto`, generated stubs, Kitex/Hertz/gRPC generation, or handlers bound to generated contracts.
+
+## Edit Workflow
+
+- Edit source `.proto` first, then regenerate outputs.
+- Locate include root, target IDL file, generated output root, package mapping, and generator command before changing code.
+- Commit source proto and generated output together.
+- Do not hand-edit generated `.pb.go`, gateway, or service stub files.
+- Prefer `new` only for initial scaffolding and `update` for existing services.
+- Keep generator commands repo-relative or configurable through environment variables and Makefile variables.
+- Avoid post-generation `mv` or `sed` import rewriting; prefer generator options for package and output mapping. If rewriting is unavoidable, isolate it in a documented script and verify imports.
+
+## Field Rules
+
+- Choose field numbers deliberately; leave gaps for future groups.
+- Never reuse field numbers; add `reserved` for removed numbers and names.
+- Adding an optional field is compatible only when "field absent" remains an accepted state forever; the moment a service starts to reject requests with the field absent, it is a breaking change for older clients regardless of what the IDL says. New required semantics need a versioned method/message OR a staged compatibility gate (server accepts both for a deprecation window, clients upgrade, then server enforces).
+- Use explicit units in field names or comments for timestamps, durations, and sizes.
+- Use `int64` for IDs and timestamps when range matters; document JSON/string behavior for HTTP clients if needed.
+- Use `optional` only when presence matters; otherwise rely on proto3 defaults and validation.
+- Add comments for non-obvious validation: max size, required-by-application, ordering, uniqueness, units, and lifecycle.
+
+## Request/Response Patterns
+
+- Use `MethodRequest` and `MethodResponse` names or one consistent local convention.
+- Response should include canonical error/envelope fields or embed a shared response once; do not mix multiple envelope styles in one service.
+- Follow the repo's current envelope convention; for new services, define the envelope field name and number intentionally instead of copying a legacy framework convention.
+- Data payload should be in typed fields, not JSON strings, unless the API intentionally carries opaque data.
+- Batch requests need max item count, idempotency behavior, partial-failure semantics, and per-item result shape.
+- List responses need items, pagination cursor/total policy, and stable sort definition.
+
+## Enum Patterns
+
+- First value is unknown/unspecified zero.
+- Prefix enum values with enum name or stable short prefix.
+- Do not rename generated enum values after clients import them.
+- Treat unknown enum values as validation errors at write boundaries and as safe fallback at read boundaries.
+- Avoid generic values like `Pending` or `Finished` in shared packages because generated Go names can collide.
+
+## Service And HTTP Mapping
+
+- Keep service methods cohesive; split large services by capability or stability boundary.
+- Put HTTP annotations near methods and field binding annotations near fields.
+- Path/query/body/header bindings should be explicit and tested.
+- Empty request/response messages are acceptable when the method truly has no payload, but keep them named for future evolution.
+- Streaming methods require explicit message size, cancellation, backpressure, and retry semantics.
+
+## Generation And Tests
+
+- Keep Kitex, Hertz, gRPC, protoc, and DI generation commands in Makefile targets or scripts.
+- Use `protoc --go_opt=paths=source_relative` or an equivalent explicit mapping when generated file layout should mirror source layout.
+- Run formatting and compile checks after generation.
+- Add contract tests for default values, optional presence, unknown enum handling, field binding, error envelope, pagination, and backward compatibility.
+- Add generated-code clean checks in CI when proto inputs change.
+- If generator version changes, review generated diff separately from contract changes.
+
+## IDL Repo Organization
+
+- For multi-service portfolios, prefer one or more dedicated IDL repos (proto, thrift, http-thrift each may be its own repo) over inlining IDL into business repos. Each IDL repo carries its own CI to run codegen, format, and pre-commit checks; business repos consume the published generated artifacts.
+- When the IDL repo is independent, the standard CI shape is a single docker image (e.g., `idlgen:v1.0.0`) plus a branch-aware `docker run` that rebuilds generated outputs and either commits them back or publishes a module. Tag the image; do not float `:latest` for production codegen.
+- Inside one IDL repo, organize sources by three intentional tiers: `base` for shared structs and the canonical error/code enum, `api` for gateway-facing contracts that cross the trust boundary, and `<domain>` (one bounded context per directory, e.g. `<product-line>`, `<platform-layer>`) for internal RPC by business domain. Use the same tiering in the generated output tree.
+- Reserve an explicit numeric range for the shared `Code` enum (for example `[0, 11999]`) and document per-tier sub-ranges so downstream services can allocate biz codes without colliding with platform codes.
+- Pre-commit hooks in IDL repos at minimum: protoc / thrift compile, formatter (clang-format for proto, thriftfmt for thrift). Add a breaking-change check (`buf breaking`, `kitex check`, or equivalent) when the IDL is consumed by more than one team or has external clients.
+- Generated output directories must be excluded from any reformatter the business repo runs; if `reformat.sh` exists, it should carry an explicit skip list (`! -path "./kitex_gen/*" ! -path "./hertz_gen/*"`).
+
+## Multi-Language Codegen
+
+- When the same IDL produces clients for multiple language families (Go, Python, Java, TypeScript), drive each language's codegen from its own dedicated script (one shell script per target language) rather than a single mega-script. Each script lives next to the IDL and is the canonical command — Makefile targets and CI jobs both delegate to it.
+- Cross-language codegen scripts that auto-commit and push generated artifacts should: pin tool versions (grpcio-tools, protoc-gen-go-grpc, etc.); use a known build-and-publish flow (poetry / npm publish / go module tag); skip on no-op diffs; emit a clear final status.
+- Document which language is the canonical source of behavior expectations when only one language has integration tests against the IDL. Other-language clients inherit the contract but may not catch protocol-level regressions.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/public-api-integration-patterns.md

@@ -0,0 +1,56 @@
+# Public API Integration Patterns
+
+## Auth Middleware
+
+- Keep the bypass path list explicit and small.
+- Extract application/user identity first, then load auth configuration, then validate signature/token, then resolve authorization/resource scope.
+- Do not parse domain request bodies before authentication unless signature verification requires canonical body bytes.
+- Return stable canonical auth errors; log detailed causes with safe identifiers.
+- Never mutate global auth settings per request.
+
+## App Credential Model
+
+- Store app id, secret/key reference, allowed source restrictions, allowed authorization/resource scopes, integration/source identity, status, and rotation metadata.
+- Generate secrets with cryptographic randomness.
+- Keep secret values out of logs, code, test fixtures, and generated docs.
+- Support disabled apps and rotated credentials.
+- If auth config is dynamic, cache briefly and fail closed for unknown app ids or malformed config.
+
+## Signature Verification
+
+- Canonicalize the signed data before verification.
+- Include timestamp and nonce/request id.
+- Enforce a short timestamp window appropriate to the integration.
+- Store nonce/request id for replay protection when the provider can retry.
+- Use constant-time comparison for MAC/signature checks where applicable.
+- Avoid weak hash-only signing for new integrations; prefer HMAC or asymmetric signatures.
+
+## Authorization And Integration Scope
+
+- Treat request scope id as a claimed scope.
+- Confirm the authenticated app/user is allowed to operate on that resource scope.
+- Treat identity, ownership, actor, tenant, creator, account, and permission fields in headers, query parameters, request bodies, and downstream RPC requests as claims until resolved from authenticated context or an authoritative service.
+- For write paths, use the resolved authenticated identity as the source of truth. Either overwrite client-supplied owner/creator fields or reject mismatches; never use authenticated identity only as a fallback after trusting a client field.
+- When fixing an auth or permission bug, search every ingress and propagation point for the same trust class: headers, body fields, query params, path params, generated RPC requests, service defaults, and downstream repository inputs.
+- Put resolved authorization scope and integration source into typed request context for downstream logic.
+- Include resolved scope/source in cache keys, idempotency keys, rate limits, logs, and audit records.
+- Only allow scope-check bypass for specific integrations with explicit config and audit logging.
+
+## Callback Handler
+
+- Validate signature/token, timestamp, event type, resource id, and payload shape before side effects.
+- Convert provider event codes into internal event enums at the boundary.
+- Deduplicate by provider event id, request id, or stable resource-event-time key.
+- Persist a callback receipt before expensive work when retries are expected.
+- Treat empty payloads, unknown event types, and malformed signatures as permanent failures.
+- Make retry behavior explicit in the response contract expected by the provider.
+
+## Integration Tests
+
+- Unit-test signature canonicalization, timestamp expiry, replay handling, and authorization-scope checks.
+- Add spoofing tests for identity/owner/creator fields in every accepted client input surface, and assert the downstream service receives the resolved identity or the request is rejected.
+- Add fail-closed tests for auth, permission, capability, and profile-resolution errors before downstream side effects.
+- Use fixtures with fake secrets, never production-like secrets.
+- Add callback duplicate-delivery tests.
+- Add malformed payload and unknown event tests.
+- Keep provider sandbox or live-callback tests out of the default fast test target.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/quality-and-testing-patterns.md

@@ -0,0 +1,91 @@
+# Quality And Testing Patterns
+
+Use this when adding tests, fixing brittle tests, setting CI targets, validating codegen, or building traffic replay/regression checks.
+
+## Test Target Split
+
+- Keep the default test target fast, deterministic, and runnable without live DB, Redis, MQ, service discovery, cloud credentials, or network-only dependencies.
+- Put infrastructure-dependent tests behind an explicit target, tag, environment variable, or separate package path.
+- Mark long-running tests clearly. Do not leave unbounded sleeps, watch loops, or manual inspection tests in the default path.
+- Generated output tests should compare structured objects or golden files, not rely on developers manually opening emitted files.
+- If a test writes files, write under a temp directory and clean up through `t.Cleanup`.
+
+## Unit Tests
+
+- Prefer table-driven tests for validation, domain rules, key builders, config parsing, route matching, retry decisions, and error mapping.
+- Unit tests should assert behavior, not log output. Use `t.Fatalf` or assertions for required outcomes.
+- For finite domain values, tests should use the domain constant/type names or boundary conversion helpers instead of repeating raw literals. Raw literals are acceptable only inside boundary conversion tests that prove specific external wire/storage values map to domain symbols. Those tests must be machine-findable by BOTH a file/test name containing `boundary`, `conversion`, `wire`, or `storage` AND a sentinel comment `finite-value boundary conversion tests only`; there is no unmarked "dedicated converter file" exception. The sentinel comment is invalid unless the project's lint, grep panel, or required review checklist for import isolation is active and passing for that file; for a repo without that enforcement yet, the same PR must add the checklist/check or link a tracked enforcement task before claiming the sentinel exception. Boundary conversion test files must contain no assertions on business-rule inputs or application state; shared setup/helpers are allowed only when they do not assert application state. Any mixed assertion file is non-compliant regardless of sentinel presence. A project lint, grep panel, or required review checklist MUST fail/block when sentinel boundary files import or call application service, repository, or workflow layers. Cover every known wire/storage value plus at least one unknown or invalid value and the converter-level default/empty output, such as returning the domain unknown/default symbol; do not assert downstream application state in these tests. When adding a finite-value boundary module, migrate existing test raw literals for that value in the same pull request or mark each remaining use with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`. Pre-existing scattered raw literals in non-boundary tests are in scope only for the same touched file/module and finite value; flag them with the same debt marker even when the current slice does not introduce a new mapper. A PR containing an in-scope non-compliant `finite-value-debt` marker, or an in-scope unmarked raw literal in a non-boundary test, must not be approved; treat it as a blocking finding equivalent to a missing test. For out-of-scope occurrences found by grep, record the tracking issue instead of expanding the current PR indefinitely.
+- Exercise negative paths: missing required fields, malformed config, forbidden auth subject, resource-scope mismatch, duplicate idempotency key, and dependency timeout.
+- For context-sensitive code, test shorter parent deadlines and canceled contexts.
+- For concurrency code, test cancellation, duplicate starts, bounded worker count, panic recovery, and final state.
+
+## Fakes And Mocks
+
+- Put external RPC/HTTP, object storage, notification, and repository boundaries behind interfaces when behavior needs testing without infrastructure.
+- Prefer small handwritten fakes for domain tests. Use monkey patching only for hard legacy boundaries or when refactoring the boundary is out of scope.
+- Fake clients should support:
+  - success.
+  - transport error.
+  - timeout.
+  - non-OK domain status.
+  - malformed response.
+  - slow response with context cancellation.
+- Keep fake data minimal and named by domain scenario, not by copied production identifiers.
+
+## Component And Integration Tests
+
+- DB wrapper tests should cover read/write routing, transactions, rollback on error, panic recovery, upsert columns, pagination, and sharding/table routing if used.
+- Redis tests should cover TTL, cache miss vs infrastructure error, lock acquire failure, compare-and-delete unlock, lease expiry, and idempotency states.
+- MQ tests should cover selector/filter expression, duplicate delivery, retry/skip/dead-letter behavior, ordering assumptions, and worker concurrency.
+- Dynamic config tests should cover get/set/delete, cache TTL, list pagination, malformed JSON, listener callback, and listener close.
+- Release-platform tests should cover manifest rendering, route patch preservation, canary report classification, approval task idempotency, and callback validation.
+
+## End-To-End And Real-Flow Evidence
+
+- End-to-end tests should assert the critical user or caller outcome, not only that a button was clicked or a handler returned 200.
+- Prefer structured snapshots or stable selectors for UI automation, then re-read state after every action that should change the page or workflow.
+- Use isolated browser/session contexts for different users or roles; save/load authenticated state only when the test is not about login itself.
+- Wait for explicit conditions such as visible text, URL transition, network idle, emitted event, or persisted state instead of fixed sleeps.
+- For UI-backed workflows, collect browser-visible state plus console errors, failed network requests, and backend logs for each critical step.
+- For API/backend workflows, collect response envelope, canonical error code, trace/log id, dependency call result, and persisted state or emitted event when relevant.
+- Real dependency tests should be explicit and isolated from the default fast target; use them for critical paths where mocks hide contract, credential, data-shape, or runtime integration failures.
+- For scenario tests, use `testing-strategy` to build the scenario matrix first; in Go services, map scenarios to table-driven unit tests, handler/service tests, protobuf/HTTP contract tests, DB/Redis/MQ integration tests, replay checks, or opt-in real-flow tests based on the risk.
+- If a real-flow test fails, route through `defect-diagnosis`; do not replace it with a thinner mock-only assertion unless the original scenario is invalid.
+- Keep screenshots, payload samples, log snippets, or trace ids only as evidence pointers; tests should still assert deterministic conditions.
+
+## Traffic Replay And Regression Checks
+
+- Treat traffic replay as a regression tool, not a substitute for unit tests.
+- A replay task should record batch id, config, status, start/end time, total count, processed count, success/failure count, and result summary.
+- Bound replay concurrency with a semaphore or worker pool.
+- Replay must support filters, mock rules, timeout, rate limit, environment tags, and variable mapping.
+- Diff results should include original response, replay response, field path, diff type, similarity, ignored fields, and representative samples.
+- Reports should include success rate, diff rate, average latency, original latency, performance change, sample diffs, and error summary.
+- Cancellation and cleanup must be explicit and should not delete results for a running task.
+
+## Codegen And Template Tests
+
+- Test manifest/template generation from typed inputs.
+- Validate required deployment/config inputs before rendering.
+- Compare generated YAML/JSON through parsers when possible; avoid brittle raw string snapshots for unordered fields.
+- For protobuf or API generation, add compile checks and contract tests for default values, enum unknowns, error envelope, and HTTP path mapping.
+- For DI generation, compile the service and run a smoke constructor test after provider changes.
+- Generated-file churn should trigger inspection of generator version, input files, and command arguments.
+
+## CI Quality Gates
+
+- Minimum useful gates for backend changes:
+  - formatting.
+  - static checks or lint if available.
+  - compile for changed modules.
+  - focused fast tests.
+  - `go test -race` on the fast target for any goroutine-spawning service (goleak on key packages optional) — baseline hygiene, not an advanced gate.
+  - codegen clean check when IDL, DDL, routes, or DI providers changed.
+- Add integration gates only where the environment is reliable; otherwise keep them opt-in and document how to run them.
+- CI should fail on generated output drift when generation is deterministic.
+- Do not require external secrets for ordinary pull-request tests.
+- Audit precision gates and baseline hygiene together. Failure shape: a repo builds elaborate custom gates (attestation, drift checks) while its CI never runs `-race` — the missing piece is usually the boring baseline, not another bespoke gate.
+
+## Testing Time And Concurrency
+
+- **`testing/synctest` (Go stdlib, stable since Go 1.25) is the default-recommendation for testing time-sensitive or concurrent code** — replaces hand-rolled fake clocks (`github.com/benbjohnson/clock` and similar) and the "sprinkle `time.Sleep(50*time.Millisecond)` and hope" pattern. Per Go blog, `synctest.Test(t, func(t *testing.T) { ... })` runs the test in an isolated "bubble" where time is virtualized: `time.Sleep`, `time.NewTimer`, `time.AfterFunc`, `context.WithTimeout` advance instantaneously when all goroutines in the bubble are blocked. Use for: retry-backoff verification, timeout handling, periodic loop pacing, expiry / lease / TTL behavior, multi-goroutine choreography. Do NOT use for tests that genuinely need wall-clock interaction (real DB query latency, real network call cancellation timing — those stay in integration tests). For services on Go 1.24 or older, `synctest` is available behind `GOEXPERIMENT=synctest` in Go 1.24 only; do not depend on it cross-version without a build tag.