@ccoalm/ccl-skills 0.1.0

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

@@ -0,0 +1,123 @@
+# Redis Cache Lock Patterns
+
+Use this when implementing Redis clients, key builders, local/distributed caches, locks, counters, rate limits, idempotency, or lightweight task queues.
+
+## Client Setup
+
+- Build Redis clients from typed config and a secret provider.
+- Resolve endpoints through service discovery or explicit environment config.
+- Configure dial timeout, read timeout, write timeout, and pool size.
+- Load Lua scripts at startup when using script-based atomic operations.
+- On `NOSCRIPT`, reload the script and fall back to direct eval once; emit a metric for script-cache misses.
+- Redis command errors should include operation name and key purpose, but not secret payloads.
+
+## Key Builders
+
+- Put all keys in one package or adapter per service domain.
+- Use functions such as `KeyForX(id)` rather than inline formatting. When two components share a key namespace, funnel key derivation through one canonicalization function used symmetrically on read and write; mismatched normalization on one side silently splits the namespace.
+- Include environment/lane/resource-scope dimensions only when they are necessary for isolation.
+- Validate non-empty keys before commands that mutate data.
+- Keep key names stable; changing a key format is a migration and invalidation event.
+- Keep pattern deletes or key scans behind explicit adapter methods with bounded scan/batch behavior and metrics. Do not scatter raw `KEYS` or broad pattern deletion through service logic.
+
+## Distributed Locks
+
+- Acquire with `SET NX EX/PX` or a proven library.
+- Lock value must be unique per attempt: instance id plus random id or operation id.
+- Unlock with compare-and-delete, usually via Lua.
+- Renew with compare-and-expire when the critical section can exceed one lease.
+- Renewal loops must stop on context cancellation and max lease.
+- Always `defer unlock` after successful acquire unless the lock is intentionally no-unlock throttling.
+- Return a typed lock-failed error when acquire fails; callers must decide skip, retry, or fail.
+
+## CAS And Atomic Scripts
+
+- Use Lua for compound atomic operations such as compare-and-set, compare-and-delete, compare-and-expire, positive-only decrement, increment-only-if-exists, hash get-and-set, and sorted-set pop.
+- Define return codes for success, compare failure, and missing key.
+- Convert Redis nil/missing-key into explicit domain behavior.
+- Keep scripts deterministic and small.
+- Test script fallback and invalid return type handling.
+
+## Cache Implementations
+
+- Local cache:
+  - protect map/LRU state with locks.
+  - enforce capacity and TTL.
+  - make cleanup goroutines stoppable or acceptable for process lifetime.
+  - deep-copy mutable data when callers might mutate it.
+- Distributed cache:
+  - serialize through a stable format.
+  - set TTL on every write.
+  - distinguish miss from Redis failure.
+  - handle malformed cache payload by treating it as miss and optionally deleting it.
+- Do not let cache failures hide source-of-truth failures unless fallback is explicitly designed.
+
+## Counters And Quotas
+
+- For counters that must not go below zero, use an atomic script rather than read-modify-write.
+- Decide whether missing key means zero, nil, or error.
+- On increment, decide whether to set, extend, or preserve TTL.
+- Batch get/set/delete should validate keys and use pipelines carefully; make sure commands are executed, not only created.
+- Return existence along with value when callers must distinguish zero from missing.
+
+## Rate Limiting
+
+- Use a stable scope such as subject, resource scope, IP, app id, operation, or domain object.
+- Sliding window implementation should:
+  - remove entries older than the window.
+  - count current entries.
+  - add the current hit atomically or inside a watched transaction.
+  - expire the key slightly after the window.
+  - retry boundedly on transaction conflict.
+- Return both allowed flag and current count when useful for logs or response headers.
+- Reset should be explicit and scoped.
+
+## Idempotency
+
+- Idempotency keys should include operation name and stable request/resource id.
+- Store status, result reference or summary, last error, created time, and expiry when the workflow is inspectable.
+- Separate pending claim, completed marker, duplicate completed event, and retryable failure. Pending claims need a short TTL or owner lease; completed markers need a dedupe window that matches the external retry horizon.
+- If Redis is unavailable on a high-risk idempotency path, fail safe according to the product contract rather than silently accepting duplicate side effects.
+- For MQ consumers, duplicate messages should normally return success after detecting already-processed state.
+- Include retry count in the key only when each retry is intentionally distinct; otherwise it can defeat deduplication.
+
+## Lightweight Task Queues
+
+- Sorted sets are useful for time-ordered pending work and priority.
+- Sets are useful for deduplicated pending ids.
+- Redis Streams can support replayable progress or event delivery only when the implementation defines starting id, resume behavior, heartbeat/no-message behavior, trimming or TTL cleanup, and malformed-message handling.
+- Pop operations should be atomic if losing the popped item is unacceptable.
+- For durable work, persist the task in DB or a real queue and use Redis only for scheduling or coordination.
+- Expose queue size, pop count, retry count, and stuck-item metrics.
+
+## Tests
+
+- Unit-test key builders and TTL selection.
+- Test lock acquire, acquire failure, compare-and-delete unlock, wrong-token unlock, renewal, context cancellation, and max lease.
+- Test rate limiter allow/deny at window boundaries and transaction conflicts.
+- Test counter missing-key and positive-only behavior.
+- Test cache malformed payload, miss, Redis failure, and source fallback.
+- Keep live Redis tests out of the default fast test target unless a local isolated Redis is guaranteed.
+
+## Cache Stampede Defense
+
+- Combine single-flight (one fetcher per key while others wait), negative caching for misses with shorter TTL, and randomized TTL jitter (±10-20%) for hot keys whose miss cost is high.
+- In-process single-flight uses a per-key mutex or `golang.org/x/sync/singleflight`; cross-process single-flight uses a short Redis lock with compare-and-delete release.
+- Apply jitter at write time, not at read time.
+- For very hot read-mostly data, layer a short-TTL in-process cache in front of Redis and invalidate through Pub/Sub or topology-change events.
+
+## Cluster Slot And Hash Tag Rules
+
+- Multi-key commands, `MULTI/EXEC`, Lua scripts, and pipelines that depend on key co-location must keep all keys in the same hash slot. Use the `{tag}` hash-tag syntax (`tenant:{tid}:resource`, `tenant:{tid}:counter`) to co-locate keys.
+- A Lua script with `KEYS[]` across slots fails with `CROSSSLOT`; review key schemas before writing scripts that take multiple keys.
+- `SCAN` walks one cluster node at a time; cluster-aware delete-by-pattern means iterating all primary nodes, not the cluster as one keyspace.
+- Pipelines across slots split into per-slot round-trips; do not assume a single network call.
+- Cluster clients refresh slot maps on `MOVED`/`ASK`; for latency-sensitive paths cache the slot map and refresh proactively on topology change.
+
+## Retry And Circuit Breaker Coordination
+
+- Retry only for transient errors: connection errors, read/write timeouts on idempotent reads, `LOADING`, `BUSY`. Do not retry write commands when retry could double-apply.
+- Bound retries: max attempts, exponential backoff with jitter, total deadline; enforce a per-request retry budget to prevent amplification.
+- Pair retry with a circuit breaker per upstream identity (cluster endpoint or sentinel set). Open after consecutive failures, half-open after cool-down, close on success. Do not retry inside an open circuit.
+- Coordinate with lock and idempotency: a retry against a lock you already hold uses compare-and-expire, not re-acquire; a retry against an idempotency store distinguishes `pending` (original attempt still in-flight; return in-progress/retry-later to the caller, do NOT execute again) from `completed` (return the recorded success/no-op). Treating duplicate `claimed`/`pending` as success acknowledges work that may still be running and risks double execution if the first attempt later fails or partially succeeds.
+- Surface retry count, breaker state, and budget exhaustion as metrics; sustained breaker-open is a paging condition.

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

@@ -0,0 +1,112 @@
+# Release Operations Patterns
+
+Use this when implementing release-facing code: deploy config, health endpoints, traffic config, canary checks, approval workflows, callbacks, or operations notifications.
+
+## Health And Runtime Introspection
+
+- Add a lightweight liveness endpoint that returns success when the process can serve basic traffic.
+- Add readiness when correctness depends on DB, Redis, MQ, service discovery, or a critical remote API.
+- Keep debug/profiling endpoints internal-only. Register them under a predictable path and guard by environment, network, or auth.
+- Add a ping/introspection endpoint for HTTP services when useful. Include service name, environment/lane, instance id, client address, and status; do not include secrets.
+- Middleware should normally bypass auth for liveness and readiness, but not for debug or administrative endpoints.
+
+## Runtime Config Access
+
+- Wrap dynamic config in typed accessors: `GetX(ctx)`, `SetX(ctx, value)`, `ListX(ctx, prefix)`, and listener registration when live reload is needed.
+- Return typed empty defaults only when empty config is valid. Otherwise fail fast with a clear startup or request error.
+- For list-style config, page through keys with a bounded limit. **Fail the whole snapshot** if any entry is invalid for security/routing/credentials lists — silently skipping one malformed routing rule or credential entry can flip traffic to the wrong upstream or disable a protection without alerting anyone. Partial-skip-with-warning is acceptable ONLY for non-critical inventory lists with an explicit degraded-mode contract.
+- Never log secret values. For app credentials, expose only key id, version, or masked identifier.
+- Cache mostly-static config with a short TTL and a mutex-protected refresh path; return copies so callers cannot mutate shared state.
+
+## Service Discovery Reconciliation
+
+- Load desired instance config through typed dynamic config or IaC output.
+- Resolve hostnames explicitly and fail the single instance, not the whole reconciliation batch, when one host is invalid.
+- Compare desired and actual instances by endpoint and metadata before writing to the registry.
+- Register missing or changed instances and deregister stale instances; make both operations idempotent.
+- Use `time.NewTicker` with `Stop` and context cancellation for periodic reconciliation.
+- Log and metric changed, unchanged, removed, skipped, and failed instances with service identifier and lane/environment tags.
+
+## Deployment Implementation
+
+- Build deployment manifests from a typed params struct.
+- Validate required inputs before rendering:
+  - service identifier and app name.
+  - environment/lane.
+  - image.
+  - CPU, memory, replica count.
+  - protocol and ports.
+  - optional storage or hardware flags.
+- If a redeploy allows empty image, resolve it from the current workload first and fail if no current image exists.
+- Apply multi-document manifests through a parser that handles each resource independently and reports the failing kind/name.
+- Ensure namespace and service-level resources before deploying lane workloads.
+- For deletion, make not-found idempotent and log resource kind/name.
+
+## Interactive Deploy Watch
+
+- For user-visible deploy flow, watch the workload after apply and stream normalized events.
+- Mark success only when desired replicas, updated replicas, ready replicas, and available replicas all meet target.
+- Include condition messages when the workload is not progressing.
+- Use a bounded watch timeout and stop the watcher on completion or context cancellation.
+- Keep event payloads stable so CLI, web UI, and automation can consume the same stream.
+
+## Traffic Config Updates
+
+- Model traffic config by caller, callee, method/path, lane, weight, timeout, and enable flag.
+- Protect updates with a write lock keyed by caller/callee or the smallest safe route scope.
+- Read existing config, apply the minimal patch, validate the full result, then write once.
+- Make route removal explicit. Do not silently drop unrelated routes while updating one route.
+- Emit audit logs for old value, new value summary, actor, reason, and request id.
+
+## Approval Tasks
+
+- Store approval task by service, lane, run id, status, expiry, required approval count, and pipeline metadata.
+- Store reviewer decisions separately from the task row.
+- Create or reset a task idempotently for the same run id.
+- When approving:
+  - acquire the task write lock.
+  - verify the reviewer is allowed.
+  - count current approved/rejected decisions.
+  - update reviewer result and task status in one transaction.
+  - reject wins immediately; approve finishes when the threshold is reached.
+- Expired tasks should fail closed for production-impacting releases.
+
+## Release CLI And Automation
+
+- Release CLIs should validate pipeline/run identifiers before remote calls and should fail closed when service or lane extraction is ambiguous.
+- If a CLI streams deploy progress, consume the same normalized event contract used by API/web clients and treat the final result event as authoritative.
+- Apply read deadlines or heartbeat expectations while waiting on WebSocket, SSE, or long polling progress streams.
+- Waiting for approval or deploy completion needs a bounded timeout, a bounded consecutive-error budget, and a clear nonzero failure when the result is rejected, expired, or never observed.
+- Print stable machine-readable identifiers, such as task id or run id, in addition to human progress text so CI can chain commands.
+
+## Canary Checks
+
+- Persist canary check window by service and run id. Repeated checks should use the same start and expiry timestamps.
+- Resolve canary instances and baseline instances from the runtime platform.
+- Query logs/metrics within the window using service, lane, instance, and severity dimensions.
+- Group errors by stable location such as caller, stack frame, error code, or normalized message.
+- Flag:
+  - errors present only in canary.
+  - canary error count materially higher than baseline.
+  - restart/readiness changes.
+  - latency or domain metric regression when available.
+- Return a structured report with `is_success`, reason, canary count, baseline count, and representative samples.
+
+## Notifications And Callbacks
+
+- Treat CI/CD and alert callbacks as external inputs: validate signature/token, timestamp, event type, and idempotency key before side effects.
+- Parse service and lane from explicit fields whenever possible; regex extraction from names is a fallback and must fail closed.
+- Send notifications asynchronously only when waiting for upstream state would block a callback. Use bounded retries or timeout.
+- Rate-limit notification fanout to avoid alert floods.
+- Route messages by environment/lane and severity.
+- Include owners/reviewers when available, but do not block the core workflow if owner lookup fails.
+- Keep provider-specific SDK and notification rendering behind an interface so release workflow logic is testable.
+
+## Tests
+
+- Unit-test manifest rendering with golden outputs or structured object assertions.
+- Test config parsing for missing, empty, malformed, and multi-page list cases.
+- Test traffic patch behavior preserves unrelated routes.
+- Test approval concurrency with duplicate approve/reject attempts.
+- Test canary report classification with baseline-only, canary-only, and count-growth cases.
+- Test callback validation and idempotency before any side effect is executed.

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

@@ -0,0 +1,83 @@
+# Reliability Patterns
+
+## Context And Log Id
+
+- Start every inbound request with a trace/log id. If the caller provides one, validate and reuse it; otherwise generate one.
+- Put trace/log id, lane/environment, authorization/resource scope, and auth subject into context once at the edge.
+- Return trace/log id in HTTP headers or response metadata when supported.
+- Do not create `context.Background()` inside request handling unless starting a deliberately detached task; pass the parent context down.
+- At the outermost boundary the framework invokes on your behalf — a documented entrypoint with no parent-context source, where a nil `ctx` means no caller context could exist (e.g. a direct or background caller), not a dropped one — normalize it (`if ctx == nil { ctx = context.Background() }`) with a diagnostic rather than relying on the framework's always-non-nil guarantee; anywhere a caller context was expected, treat nil as a bug and fail/log explicitly instead of masking a lost cancellation/deadline. Test the nil path.
+- For detached async work, create a new context with inherited metadata and a fresh bounded deadline — but separate the two lifetimes: the setup/registration call itself still honors the caller's cancellation (do not strip it with `context.WithoutCancel`; cancelling setup must still abort setup), and only the spawned worker runs on the detached context, so cancelling the caller after setup succeeds does not kill the worker and cancelling setup does not orphan a worker already spawned. Test cancellation with an explicit `cancel()`, not a race-prone tiny timeout+sleep.
+
+## Detached Goroutines And Panic Firewall
+
+- A panic inside a detached goroutine is unreachable by any framework or RPC middleware recover — it crashes the whole process. Route every production goroutine spawn through one shared safe-spawn wrapper that recovers, logs the stack with trace/log id, and increments a panic metric; no bare `go func()` on production paths. Recovery policy follows isolation level: recover-and-continue is for per-request/per-item work whose state dies with it (plus its cleanup); a supervisor or global-invariant goroutine (scheduler, registry owner, singleton reader) that panics mid-mutation must not silently keep serving on recovered-but-corrupted state — recover to log/metric, then actually stop serving: flipping readiness alone leaves existing connections and un-propagated routing serving corrupt state, so also stop accepting, cancel/drain the serving loops, and exit nonzero (or hard-drain with serving disabled).
+- Enforce firewall coverage with a checklist or lint, not memory. Failure shape: the sites most often missed are exactly the largest-blast-radius ones — top-level server goroutines and stream readers decoding untrusted bytes. Verify the panic metric is actually wired per spawn site instead of assuming the wrapper implies it.
+- The only rigorous regression proof for "process survives this panic" is a subprocess exit code: the test runs a child process that triggers the panic inside the detached goroutine and asserts the fixed binary exits 0. An in-process recover assertion cannot prove process survival. Scope this proof to per-request/per-item work where recover-and-continue is the policy; for a supervisor/global-invariant goroutine the assertion is the opposite — the child process must go unready/non-serving or exit nonzero on purpose, and an exit-0-and-still-serving result is the failure being prevented, not the pass.
+
+## Timeout And Deadline
+
+- Pick local defaults per dependency type: connection timeout, RPC/HTTP request timeout, DB query timeout, Redis timeout, MQ publish timeout.
+- If `ctx.Deadline()` exists and is shorter than the configured timeout, use the remaining deadline.
+- Always call `cancel()` for contexts created with timeout.
+- Avoid unbounded retries inside a context that is already near its deadline.
+
+## External RPC/HTTP Clients
+
+- Build clients around a single method that accepts context, request, and operation name.
+- Validate transport errors, HTTP status, and domain status code separately.
+- Wrap errors with operation name and endpoint/service identity, but keep secrets and payloads out of error text.
+- Use retry only for idempotent operations or operations with an idempotency key.
+- Define fallback explicitly: alternate endpoint, cached response, degraded result, or hard failure.
+- For outbound URL or file fetches, validate scheme and host before request, set redirect policy, cap response size, verify content type, and always close the response body.
+
+## Admission Control And Circuit Breakers
+
+- Add inbound rate limit, concurrency limit, or cost-based guard middleware before expensive handlers.
+- Return a canonical overload error and optional retry-after hint when rejecting work; do not let overload surface as panic or random timeout.
+- Use bounded queues only when callers have a defined wait deadline and cancellation path.
+- Circuit breakers should wrap dependency calls or expensive workflows with explicit open, half-open, and close conditions.
+- Emit metrics for admitted, rejected, queued, shed, circuit-open, and circuit-half-open outcomes.
+- Tests should cover limit reached, context canceled while queued, breaker open, half-open success, and half-open failure.
+
+## Streams, Uploads, And Downloads
+
+- Streaming handlers should check context cancellation or send errors on every loop iteration and close upstream streams in `defer`.
+- For long-lived stream state machines, prefer a single owner goroutine keeping state in closure-local variables: "local variables have no data race" is an argument a reviewer can verify at a glance, while shared mutable state behind locks needs a proof per field.
+- Set max request body size, max file count, max object size, and allowed content types before parsing uploads.
+- For compressed uploads or archives, enforce compressed size, expanded size, file count, path traversal checks, and expansion-ratio limits.
+- Download handlers should support bounded range reads only when object metadata confirms size and range validity.
+- Temporary files and directories should be created under a controlled base path and removed on both success and failure.
+- For generated or transformed files, write to a temp path first, then atomically publish or upload when complete.
+- Tests should cover client disconnect, oversized body, invalid content type, partial stream error, and cleanup after failure.
+
+## Async Consumers
+
+- Decode payload into a typed struct and validate required fields before side effects.
+- Treat duplicate delivery as normal. Use idempotency keys or persisted processing state for non-repeatable writes.
+- Decide return behavior intentionally:
+  - return error for retryable infrastructure failure.
+  - return nil after logging for permanent bad payload or already-processed work.
+  - dead-letter when the queue supports it and the payload needs later inspection.
+- Attach trace/log metadata to logs and downstream calls.
+- Recover panic at the consumer boundary and convert it into retry/dead-letter behavior according to queue policy.
+
+## Scheduled Jobs
+
+- Define job name, schedule, lock key, lock lease, max execution time, retry count, and backoff.
+- Acquire a distributed lock before work starts; failure to acquire should normally skip, not fail the process.
+- For jobs whose max execution time can exceed one lease window (GC pause, slow dependency, large backfill), require **renewable leases with fencing tokens**: the job renews the lease via heartbeat at < ½ the lease TTL, and every write/external-call carries the current fencing token so a second pod that acquires the lock after the first's lease expires cannot overwrite work from the original holder. Stop work immediately on a failed renewal. Fixed-lease + max-execution alone is not enough — if execution exceeds lease, two pods run simultaneously and can both write non-idempotent backfill/repair side effects.
+- Use a job-scoped context with timeout and pass it to all downstream operations.
+- Recover panic and release locks in `defer`.
+- Emit metrics for start, success, failure, timeout, retry, skipped-lock, and duration.
+- Support both fixed interval and cron-style schedules only through validated config; reject empty or malformed schedules at startup.
+- Job managers should be closable: stop tickers, prevent new executions, and let in-flight jobs finish or cancel by policy.
+- Immediate-run behavior should be explicit and normally disabled for jobs with external side effects.
+- Retry sleep must be bounded by the job context deadline.
+
+## Redis Locks And Idempotency
+
+- Lock values must be unique per attempt and unlock must compare value before delete.
+- Lock lease must exceed expected critical section time but remain bounded.
+- Idempotency records should include operation key, status, result pointer or summary, expiry, and last error if useful.
+- Choose TTL based on domain retry window, not arbitrary cache duration.

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

@@ -0,0 +1,32 @@
+# Replay Comparison Patterns
+
+Use this when implementing replay jobs, shadow execution, response comparison, migration verification, or diff reports.
+
+## Replay Jobs
+
+- Persist replay jobs with status, target, config version, total count, processed count, success count, failed count, diff count, timeout, concurrency, rate limit, and retention.
+- Reuse `state-machine-task-patterns.md` for task transitions and terminal-state behavior.
+- Use bounded workers and context deadlines for replay execution.
+- Preserve only allowlisted headers and metadata.
+- Redact captured requests and responses before storage.
+- Ensure replay targets cannot commit side effects unless isolated by environment, lane, transaction rollback, or explicit dry-run mode.
+
+## Comparator Design
+
+- Define a comparator interface such as `Compare(ctx, original, replay) Result`.
+- Select comparators by method, route, content type, or schema version.
+- Generic JSON comparators should normalize strings containing JSON, structs, maps, arrays, and scalar values.
+- Support ignored fields by exact path and field name only when documented.
+- Support custom field comparators for tolerances, unordered collections, timestamps, generated IDs, and approximate numeric values.
+- Avoid hard-coded ignored paths in generic comparators; load them from config or comparator registration.
+
+## Diff Result Shape
+
+- Include field name, field path, original value summary, replay value summary, diff type, diff score, ignored flag, and metadata.
+- Use bounded value summaries so diff records do not store huge payloads.
+- Record total compared fields, diff count, similarity, threshold, comparator name, and comparator version.
+- Distinguish missing value, added value, type mismatch, length mismatch, value mismatch, and custom comparison.
+
+## Tests
+
+- Test nil/nil, nil/value, value/nil, JSON string normalization, struct-to-map conversion, array length mismatch, missing keys, numeric tolerance, ignored fields, custom comparator, threshold behavior, redaction, storage pagination, and replay cancellation.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/scaffold-and-codegen.md

@@ -0,0 +1,86 @@
+# Scaffold And Codegen
+
+## New Service Checklist
+
+- Create or locate the service module and entrypoint.
+- Add `proto/` or `idl/` source contracts before generated stubs.
+- Add typed config structs and sample environment config.
+- Add production DI providers for config, DB, Redis, MQ, RPC/HTTP clients, service logic, handlers, and workers.
+- Add a test DI graph or lightweight constructors for tests.
+- Add Makefile or script targets for:
+  - protobuf/IDL generation.
+  - HTTP route/docs generation when used.
+  - DB model/DAL generation when used.
+  - DI generation.
+  - fast tests.
+  - integration tests.
+
+## Entrypoint And Runtime Setup
+
+- Build servers from explicit options plus middleware lists; let caller-provided options override defaults intentionally.
+- A common middleware order is context injection, recovery/error mapping, tracing, authentication/authorization, metrics/logging, then domain routes. Recovery MUST wrap auth and validation: a panic in session/token parsing without recovery wrapped around it either drops the connection or crashes the process depending on framework. Adapt only when the framework's wrapper semantics enforce a different order — and verify the panic-catch coverage explicitly.
+- Register health/readiness, debug, profiling, and docs routes in one place so exposure rules are reviewable.
+- Keep debug/profiling and generated docs behind environment, network, or auth gates when deployed outside local development.
+- Return a cleanup function or closer list from server construction and call it from signal/shutdown handling.
+- Close resources in shutdown order: stop traffic, wait for in-flight requests up to a deadline, stop consumers/workers/schedulers, close dependency clients, then flush logs/metrics/traces.
+- Prefer `time.NewTicker` with `Stop` over `time.Tick` in long-lived runtime code. Stop every timer/ticker you own; when `time.Timer.Stop` returns false and the channel may already hold a tick, drain it with a non-blocking `select`+`default` before reuse so a stale fire cannot trigger later logic — never a bare blocking `<-timer.C` (another goroutine may already have consumed the tick, and a blocking drain then hangs shutdown). This drain applies only to channel timers whose channel this goroutine owns; `time.AfterFunc` has no channel to drain — and a bare atomic flag is not enough (the callback can read the flag before the terminal path sets it and still fire late): the callback must re-check the terminal/generation state under the same lock or CAS that guards its side effect (or use a generation token / done-channel the terminal path waits on) before acting.
+- Tests for server setup should assert middleware presence, route exposure rules, and cleanup invocation where practical.
+
+## Portable Commands
+
+- Prefer repo-relative paths.
+- If a generator needs a root path, derive it from the current repo or an environment variable.
+- Do not commit commands containing a developer's local home directory.
+- Do not bake one organization's import root into a reusable generator; pass module path, IDL path, output path, and package mapping as parameters.
+- Keep generated inputs and outputs in the same change.
+- If a generated file changes unexpectedly, inspect the generator version and input diff before accepting churn.
+
+## Protobuf Contract Rules
+
+- For detailed protobuf definition, generation, and compatibility rules, apply `protobuf-contract-patterns.md`.
+- Keep source `.proto`, generated output, handler updates, and contract tests in the same change when the contract changes.
+- Keep HTTP mapping annotations and field binding annotations close to the IDL method or field they describe.
+
+## DI Provider Pattern
+
+- Group providers by concern: base, DAL, cache, RPC/HTTP clients, services, tasks, handlers, and test graph.
+- Aggregate related dependencies into explicit structs only at module boundaries.
+- Avoid global initialization in application code; initialize clients in providers.
+- Regenerate DI output after provider-set changes.
+- Compile the service after DI generation before moving to behavior tests.
+- For non-trivial services, prefer layered DI sets (e.g., `inject/infra` → `inject/service` → `inject/logic` → top-level `inject/`) where each set depends only on lower layers; the aggregate at each layer (`AllInfra`, `AllService`, `AllLogic`) is an embed-friendly struct that the next layer can compose without re-declaring providers.
+
+## Kitex / RPC Client Wrapper
+
+- Wrap framework-native client constructors behind a generic helper such as `NewClient[T](psm, ctor, opts...)` so callers cannot accidentally instantiate per-request or with inconsistent option sets. The helper composes a shared default option set (resolver, meta handler, tracing suite, middleware chain) with caller-supplied overrides.
+- Caller-supplied options must override the helper's defaults, not the other way around — append them after the defaults in the option slice. Document this precedence so reviewers can verify which side wins.
+- Construct each RPC client exactly once per process and inject via DI. `sync.Once` plus a package-level container or a Wire-generated provider both work; avoid plain package-level vars initialized from `init()` because they hide error handling.
+- The wrapper assembles the client middleware chain in a fixed order so observability and error handling cannot be silently reordered. A common order: error handler → metrics → caller-identity injection → context/log-id injection → request/response logging.
+- For Kitex specifically, pick the meta handler by transport protocol exclusively: HTTP/2 meta handler for gRPC, TTHeader meta handler for Thrift. Do not register both; do not switch at request time.
+- **Kitex v0.13 (released 2025-04-07) baseline shifts to track**: (a) `StreamX` now supports gRPC alongside the existing TTHeader Streaming, so a server can be compatible with both streaming protocols simultaneously — pick StreamX for new streaming code and let the server keep multi-protocol compatibility during migration; (b) **default Thrift transport protocol changed from `Buffered` to `Framed` to leverage FastCodec — this is a wire-format change, NOT a negotiation**: a v0.13 client built with default options sending Framed frames to an older Kitex server still on Buffered (PurePayload) will fail before useful RPC traffic, not gracefully downgrade. Upgrade discipline: either upgrade ALL participating services in one rollout window, OR explicitly pin the new client back to `PurePayload` (transport.PurePayload) via client option during the rolling-upgrade interval until every callee is on v0.13. Verify the same on `Framed` server returning to a `Buffered` client. Treat the transport-default flip as a wire-compat break that needs a versioned-upgrade plan, not a default-flag bump; (c) Kitex Tool by default stopped generating repeated `Set` validation code and `DeepEqual` functions (smaller generated output) and disabled Apache Codec generation by default — if any business code depended on those generator outputs, the upgrade will fail to compile until those usages are removed or the generator flags are re-enabled; (d) Go version support is 1.19–1.24, so Kitex services on Go 1.25 should validate framework compatibility before upgrading toolchain. Treat any Kitex minor-version bump as an architecture change: read CloudWeGo release notes, run the protocol-default check + the wire-compat fan-in/fan-out matrix, and rerun integration tests against any sibling service still on the prior version.
+
+## Server Wrapper And Option Precedence
+
+- Server constructors should expose a default-options helper and accept caller-supplied options that override defaults. Common defaults: server basic info, service address, meta handler, registry, tracing suite, error handler, the standard middleware chain.
+- Registry registration is environment-conditional, not unconditional. Register only when running in an environment that the platform layer expects to discover this instance (typically online / canary / lane environments), not in local-dev or short-lived test environments.
+- Return both the cleanup function (`func()`) and the closer list (`[]io.Closer`) from server construction so signal handlers can drive deterministic shutdown.
+
+## Generated DB Model Pattern
+
+- Generate table constants, struct fields, `TableName`, updatable column lists, query helpers, and update helpers from DDL when available.
+- Keep unique/primary/index constraints represented in query helpers where the generator supports it.
+- Exclude immutable columns such as create-time, creator, primary key, and unique key columns from generic update helpers.
+- Do not hide unsafe raw SQL behind generated helpers; add explicit DAL methods for complex queries.
+- Parse DDL with a real SQL parser instead of regular expressions.
+- Refuse to overwrite hand-maintained DAL files unless the caller explicitly asks for regeneration.
+- Format generated Go files and fail the command if formatting or import resolution fails.
+- Keep sharding keys and read/write routing explicit in generated query helpers when the stack supports them.
+
+## HTTP Docs And Route Generation
+
+- For detailed HTTP gateway, generated route, handler, middleware, and generated client rules, apply `http-gateway-client-patterns.md`.
+- Route generation and API docs should derive from source contracts or handler annotations, not duplicated hand-written tables.
+- Remove stale generated comments before writing new generated comments.
+- Keep route method/path annotations close to the handler or IDL method they describe.
+- Run formatter and docs generator after patching annotations.
+- If a handler signature does not match the generator pattern, fail visibly rather than generating partial docs.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/source-evidence-map.md

@@ -0,0 +1,54 @@
+# Go Dev Source Evidence Map (Methodology Template)
+
+This file describes the **shape** of source-evidence tracking for Go implementation extraction. Project-specific provenance (real repo names, branch state, dates, file counts, extraction logs) lives in the maintainer's private alias file at `~/.<host>/.private-aliases/<project>.yaml`, never in this shared skill tree — see `skill-extraction-workflow` Core Rule "Extraction lifecycle handoff".
+
+## Scope boundary
+
+This shared template contains reusable methodology only. Do not add concrete repository names, branch state, module counts, feature findings, or extraction logs.
+
+## Source coverage dimensions to track
+
+When extracting Go implementation guidance from a new source set, organize evidence by these dimensions in the private alias map:
+
+| Dimension | What to collect | What to extract |
+| --- | --- | --- |
+| Broad Go inventory | Module count by shape (service vs library vs tool vs generated), without exposing real module names | Implementation guidance must classify shape before recommending patterns |
+| New-product Go service | Build files, IDL tree, dependency container, observability wiring, generated code, unit/integration tests | Contract-first implementation, documented generators, explicit dependency lifecycle, generated-file discipline |
+| Legacy Go services | Representative generated surfaces, config files, handlers, logic, DAL tests | Handler/logic split, env config, generated transport files, test utilities |
+| Search / AI-adjacent service | HTTP/RPC clients, store clients (Redis, search index, queue), probe/debug/load assets | Dependency adapters, probe/debug tests, performance/replay as opt-in evidence |
+| Mature multi-service workspace | Handler/logic/service/infra modules, DI wiring, codegen Makefile, shared runtime wrappers, DB/MQ adapters, config, live-dependency tests | Thin handlers, generated code through reproducible commands, ctx/log/trace through clients, visible DB/MQ retries + transaction boundaries, live-dependency tests outside fast gate |
+| High-risk service samples | Targeted context / idempotency / audit / repair samples | Missing-context rejection, durable idempotency, mutation-plus-audit atomicity or repair, visible admin repair states |
+| Shared platform packages | Discovery-backed HTTP clients, secret accessors, dynamic config, ID allocation, DB proxy/DAL generation, object storage, migration tooling | Constructor/DI paths beside convenience globals; dynamic-config backend abstraction; generated DAL builder mutability; object migration conflict policy + replay logs |
+| Shared cache/lock packages | Cache client with Lua/CAS helpers, lock/renew/unlock, missing-script fallback, result codes | Atomic script + fallback, compare-and-delete unlock, compare-and-expire renewal, positive-only counter, pending/completed idempotency |
+| Infra control-plane services | Release-facing CLI, internal RPC proxy, generator image, dynamic service registration, KMS, ID service, tracker, RPC proxy | Executable rules for CLI progress/wait, approval/deploy/canary boundaries, generator cleanup guards, RPC proxy metadata/connection handling |
+| Database / DAL layer | DB wrapper, sharding plugin, DDL/index samples, repository query/update methods, DAL tests | Batch-upsert generated-field repair, explicit updatable-column lists, schema/query conflict-key alignment, DB/sharding assertions |
+| Official docs | Language test/subtest guidance, code-review comments | Focused tests, context/error hygiene, useful failure messages |
+
+## Sibling-generalization mini-map (template)
+
+For each Go extraction, record decisions across sibling skills:
+
+- `python-service-dev` — does the same pattern apply to Python? mirror with evidence caveat.
+- `go-microservice-architecture` — does the rule belong at architecture level instead?
+- `python-service-architecture` — cross-language architecture consequence?
+- `testing-strategy` — does this affect test-layer policy?
+- `defect-diagnosis` — does this prevent a class of defect?
+
+Decisions go in the private alias map alongside the per-batch extraction log.
+
+## Coverage discipline rules
+
+- Mark each dimension `pending` / `read` / `deep-read` / `excluded` / `unavailable` / `routed` with the actual artifacts inspected.
+- Distinguish targeted mechanism extraction from full coverage; never claim "complete" for representative-sample work.
+- Re-read source artifacts when changing rules; use `wording cleanup` / `no new source read` labels honestly.
+
+## Where the live provenance lives
+
+For the maintainer's current Go extraction project, see:
+- Private alias map: `~/.<host>/.private-aliases/<project>.yaml`
+- Per-batch extraction logs: `~/.<host>/skills/.extraction-work/<batch>-completion.md`
+- These files are never pushed to the shared skill tree.
+
+## Audit gate
+
+Before committing a change to this skill, run the private alias map's `audit_cmd` against the changed shared-skill files. Any hit on real repo names, branch states, dates, file counts, or business-domain nouns is either fixed or recorded as `known_debt` in the alias map. Pre-existing leakage may be grandfathered; new or modified content must remain zero-hit.

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

@@ -0,0 +1,45 @@
+# State Machine And Task Patterns
+
+Use this when implementing durable tasks, async workflows, scheduled jobs, imports, exports, and retryable processors.
+
+For generic async, consumer, scheduled-job, panic recovery, context timeout, and external-call mechanics, also apply `reliability-patterns.md`. This file is the canonical guide for durable state transitions and terminal-state behavior.
+
+## State Model
+
+- Define states as enums or constants with documented terminal states.
+- Define allowed transitions in one table or function; do not scatter status checks.
+- Terminal states should reject ordinary processing and failure transitions.
+- Include retry count, last error, start time, finish time, progress, result pointer, and idempotency key when tasks are inspectable.
+- Store progress separately from state; progress is best-effort while state transitions are durable.
+- Create the durable task row before launching background work, queueing expensive processing, or generating external artifacts.
+
+## Transition Implementation
+
+- Use compare-and-update, row lock, or distributed lock before processing a task.
+- Lease or lock owners must be unique at the runtime-instance level, not only at the service name level. In Kubernetes or similar container platforms, include pod or host identity and process id or a random instance id so replicas cannot claim or complete each other's work.
+- Re-read task state under the lock before side effects.
+- Make duplicate delivery normal: already successful is success or no-op; already terminal is no-op or typed conflict depending on caller.
+- Start transitions should move pending work to processing before expensive work.
+- Failure transitions should capture canonical error code, safe message, retryable flag, retry count, and last trace or log id.
+- Success transitions should persist result pointer or summary before publishing completion events.
+
+## Async Processing
+
+- Prefer queue or task execution for work that must survive process restart.
+- Delayed events should re-check task state when consumed.
+- Retry thresholds and backoff belong in config or state policy, not inline literals.
+- Panic recovery should convert the task to failed or retryable failed state after applying the retry policy.
+- Background work that produces a file, report, media object, or other artifact should persist the object key or result pointer before the success transition and expose a retryable failure state when upload/finalization fails.
+
+## Scheduled Repair Jobs
+
+- Scheduled checkers that repair stuck tasks need a job name, interval, distributed lock key, lock lease, per-run max batch size, and max execution time.
+- A job-level lock prevents duplicate scans; a task-level lock or compare-and-update prevents duplicate repair of the same record.
+- Time-window selection should be explicit, bounded, and based on durable timestamps such as `updated_at`, not process memory.
+- Repair actions must re-read current task state before changing status or emitting side effects.
+- Emit metrics for scan count, claimed count, repaired count, skipped count, lock conflict, failure, and duration.
+
+## Tests
+
+- Test illegal transition, duplicate event, concurrent processing, already terminal, retry threshold, cancellation, panic-to-failure, and completion event idempotency.
+- Test scheduled repair lock conflict, stale-window selection, per-task duplicate prevention, panic recovery, and repeated-run idempotency.

package/dist/assets/marketplace/plugins/ccl-skills/skills/grill-me/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: grill-me
+description: grill-me / 访谈 / 拷问 / 压力测试方案 / stress-test a plan — lightweight one-question-at-a-time interview to challenge a plan, design, API shape, data model, or feature direction before implementation. Skip code-level YAGNI/delete/adversarial review of written code → `product-rd-workflow`'s independent-review gate; full delivery/spec/plan authoring → product-rd-workflow; tests → testing-strategy; implementation → stack/dev skill; process lesson extraction → skill-extraction-workflow.
+---
+
+# grill-me — 轻量方案拷问
+
+Use this when the user explicitly asks to grill, interview, challenge, or stress-test a plan before implementation.
+
+This is a narrow pre-implementation interview. It clarifies the next blocking decision; it does not write the plan, own delivery gates, or replace the relevant owner workflow.
+
+## When to use
+
+Use for explicit requests such as:
+
+- `grill-me` / `grill me`;
+- 访谈、拷问、追问一个方案；
+- 压力测试方案、设计、API shape、数据模型、权限模型、工作流；
+- before implementation, when several product or technical decisions depend on each other.
+
+Do not auto-trigger this from generic “帮我规划 / scope 一下 / 写个方案”. Those route to the owning workflow first, usually `product-rd-workflow`.
+
+## Owner boundaries
+
+- Full requirement shaping, spec, plan, lifecycle gates, or multi-step delivery → `product-rd-workflow`.
+- Risk tags, gate selection, rollout or review requirements → `feature-risk-router`.
+- Code-level YAGNI, delete-code, overengineering, or adversarial review of already-written code → `product-rd-workflow`'s independent-review gate (no dedicated CCL delete-code/YAGNI skill; the review gate owns it).
+- Test layers, fixtures, coverage, regression, CI gate design → `testing-strategy`.
+- Bug/root-cause diagnosis → `defect-diagnosis`.
+- Implementation → the relevant stack/dev skill or bounded executor.
+- Reusable process/skill lesson extraction → `skill-extraction-workflow`.
+
+`grill-me` may feed those owners by resolving one unclear decision first. It must hand back once the user asks for a deliverable artifact, implementation, formal review, or test plan.
+
+## Core contract
+
+Ask one blocking question at a time.
+
+Each turn must include:
+
+1. `Target`: the plan/design being challenged.
+2. `Current assumption`: the most important assumption currently visible.
+3. `Question N`: exactly one unresolved decision.
+4. `Recommended answer`: a concrete default.
+5. `Why`: short rationale and the risk if the answer is wrong.
+
+Then wait for the user's answer before asking the next dependent question.
+
+If the answer depends on existing repo facts, inspect the relevant files first. Do not ask the user to restate facts that are available in code, specs, runbooks, or local docs.
+
+## Workflow
+
+1. Frame the target. If the target is ambiguous, ask one clarifying question only.
+2. Identify the next decision that blocks meaningful progress.
+3. Ask exactly one question with the recommended answer and why.
+4. After the answer, update the assumption and choose the next dependent question.
+5. Stop when the direction is clear enough to route to the next owner or when the user rejects the premise.
+
+Avoid bundled questions. Avoid long lectures. Do not produce a full PRD, architecture doc, implementation plan, or code unless the user explicitly switches workflows.
+
+## Closeout
+
+When the interview reaches a stable stop, return:
+
+```text
+Resolved direction
+- <decision>: <answer>
+
+Remaining risks
+- <risk or unknown>
+
+Recommended next step
+- <owner workflow / implementation / no-op>
+```
+
+## Tone
+
+- Direct, skeptical, and practical.
+- Push back on weak assumptions with evidence.
+- No flattery.