@ccoalm/ccl-skills 0.1.0

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

@@ -0,0 +1,130 @@
+# Dependency Client Patterns
+
+Use this when implementing reusable clients or adapters for dependencies.
+
+## Secret Client
+
+- Hide secret reads behind typed methods such as `GetDatabaseCredential`, `GetQueueCredential`, `GetObjectStorageCredential`, or `GetAppCredential`.
+- Apply a request timeout to secret reads and wrap errors with the secret class, not the secret value.
+- Decode JSON secret payloads into typed structs and validate required fields.
+- Cache temporary credentials under a mutex or singleflight and refresh before expiry.
+- For write/admin secret APIs, require explicit call sites and audit logging.
+- Redact secrets from logs, test output, panic messages, and generated docs.
+- Convenience package-level clients must be replaceable by constructors or DI for tests. If a client can panic during initialization, keep that path in bootstrap code and expose a constructor that returns errors for request-time dependencies.
+
+## Service Discovery Client
+
+- Create discovery clients once in DI and pass them to RPC/HTTP client builders.
+- Use healthy-only lookup by default.
+- Support metadata filters such as lane/environment through typed tags.
+- If lane lookup misses, fall back only to an explicit baseline lane.
+- Return a clear dependency error when no instance is available; do not fabricate endpoints.
+
+## Internal RPC Proxy Adapter
+
+- Require an explicit target-service field in trusted metadata or a typed proxy request; reject empty or malformed destinations before opening downstream connections.
+- Resolve targets through the runtime discovery policy: in-cluster service DNS when appropriate, otherwise same-lane lookup with explicit baseline fallback.
+- Preserve trace/log id, lane/environment, and caller service identity in outgoing metadata; do not forward unreviewed headers or credentials blindly.
+- Bound connection pools, return or close connections deterministically, and propagate context cancellation to both upstream and downstream streams.
+- Isolate transport-specific reflection or frame-copying code behind a narrow adapter with tests for metadata propagation, connection cleanup, EOF handling, and downstream selection failure. When codegen output shape varies, prefer a documented interface method with a direct-then-unwrap fallback over reflecting into generated structs; reflection here is a smell, and the reflective fallback must emit an observability signal when it fails to find the field, or propagation breaks silently.
+
+## Dynamic Config Client
+
+- When etcd backs dynamic config, prefer a small store adapter or typed client boundary; do not let etcd imports or raw keys leak into domain, application, or transport code.
+- For local-first KMS over dynamic config, provide an in-memory store for fast tests and verify encrypted envelopes, missing master key failure, missing secret failure, and readiness behavior.
+- Wrap dynamic config keys behind typed methods instead of exposing raw string keys throughout application code.
+- Centralize namespace and backend key construction in the client; list/watch APIs should return caller-facing keys or documented resume markers, not raw backend prefixes by accident.
+- Use bounded timeouts for get, set, delete, and watch operations.
+- Decode JSON config into typed structs and validate required fields before use.
+- Cache read-heavy keys with TTL; distinguish not found, decode error, and remote dependency error.
+- Listener callbacks should recover panics, update local cache, and stop cleanly when the parent context is canceled.
+- Tests should cover default behavior when config is missing or malformed.
+
+## HTTP Client Wrapper
+
+- Provide helpers for constructing requests, attaching discovery options, setting headers, and executing with timeout.
+- Use `DoTimeout` or a context deadline for every outbound call.
+- **A middleware / client WRAPPER (interceptor, governance layer) owns deadline *propagation*, not a fixed timeout *policy* — but every production call still gets a bounded effective deadline.** Honor the caller's `context` deadline; don't bake an arbitrary fixed default (a hardcoded `30s`) into the wrapper that overrides it. But "no wrapper default" ≠ "unbounded": a `context.Background()` caller plus a hung dependency pins goroutines/connections forever, so the wrapper applies an **env-configured max backstop** as the effective deadline when the caller supplies none, overridable at the call site, with an explicit documented opt-out only for long-lived watch/stream calls **that still bound their own liveness** (idle/read timeout, heartbeat, bounded reconnect, cancel cleanup) — the opt-out is from the single request deadline, not from all bounds, or a half-open stream pins resources forever. Clamp **every untrusted/external inbound deadline** — an inbound gRPC `grpc-timeout` as much as an HTTP deadline header — to platform min/max **before** honoring or propagating it, or an external caller sets a huge deadline to hold resources (slow-DoS). Propagate with the transport's **native** decrementing mechanism where it exists (gRPC `grpc-timeout`, not a reinvented `x-rpc-timeout-ms`); HTTP has **no** native on-wire deadline, so cross-hop propagation over HTTP needs an explicit deadline-header contract — strip any caller-supplied one at ingress and generate the internal header from the server-side (clamped) effective context. Don't add an *independent competing* timer, but a **derived** per-attempt cap is correct — `per-attempt = min(caller-remaining, configured max)`; and before each retry/hedge recompute the remaining budget and **skip** the attempt when it can't cover attempt + backoff + cleanup (doomed retries amplify overload).
+- Always close response bodies when using standard HTTP APIs.
+- Parse response status and body separately; do not treat a 200 transport status as domain success automatically.
+- Keep redirect behavior explicit.
+- Include operation name, callee service, status code, duration, and canonical error code in logs/metrics.
+
+## Object Storage Adapter
+
+- Build object storage clients from config plus secret provider credentials.
+- Default endpoint selection can depend on runtime environment, but the choice must be explicit and testable.
+- Add source service, lane/environment, and trace/log id metadata or tags on writes when supported.
+- Wrap provider errors into typed categories: not found, forbidden, retryable server error, client/config error.
+- For uploads, validate content size, content type, key namespace, and idempotency before writing.
+- For downloads, support `Head` before `Get` when size, range, or existence matters.
+- For multipart upload, define part iterator, part numbering, completion, and cleanup-on-error behavior.
+- For object copy or migration tools, define overwrite/conflict policy before transfer, tag migrated objects with source identity, emit replayable success/error/conflict records, bound concurrency, and flush/close log writers on shutdown.
+- For signed URLs, require explicit expiry and never log the full URL if it contains credentials.
+
+## Search Or Document Store Adapter
+
+- Wrap index or collection access behind repository interfaces; do not let handlers build raw provider queries.
+- Build clients with timeout, pool bounds, tracing, health policy, and credentials from the secret provider.
+- Keep index names, collection names, mappings, and versioning policy near the adapter or migration package.
+- Validate filters through an allowlist and enforce max limit plus stable sorting before executing queries.
+- Treat bulk writes as partially successful until per-item results are inspected.
+- Tests should cover query construction, pagination, empty result behavior, and retryable write failures.
+
+## ID Generator Client
+
+- Wrap ID allocation behind a small interface such as `Next(ctx)` and `Batch(ctx, n)`.
+- Validate namespace and requested count at the boundary.
+- Batch prefetch may improve latency, but cache size must be bounded and refill errors must not spin hot.
+- `Next` should time out quickly and return an ordinary error.
+- If using local fallback, log it as degraded behavior and keep the fallback generator's node/namespace uniqueness explicit.
+- Propagate caller identity and trace/log id to central ID services.
+
+### In-process ID generator (snowflake-style)
+
+Applies when the architecture chose a local-only generator OR when the central client falls back to a local one. The architecture-level "in-process vs central vs DB-issued" decision lives in `go-microservice-architecture/references/dependency-platform.md` (ID Generation section); the rules here govern how the local generator must behave once that choice is made.
+
+- **Bit layout is a frozen contract**: document the layout once (e.g., `41-bit timestamp + 8-bit namespace + 4-bit node + 10-bit counter`) and the epoch (`baseTs`) alongside it. Changing widths or order invalidates every previously-issued ID that any consumer parses by position; treat layout changes as a versioned migration with an epoch bump, not an in-place edit.
+- **Counter width sizes the per-generator per-millisecond peak**: 10 bits is 1024 IDs/ms per generator, 12 bits is 4096/ms. When the millisecond's counter exhausts, the generator yields (short `Sleep` or runtime yield, not a raw spin) until the next millisecond — never overflow into adjacent bit fields (namespace or node), which silently collides IDs with another logical generator. The wait is bounded by both the caller's context deadline AND a documented per-generator cap (typical: low milliseconds for counter rollover, longer for clock-backward stall); whichever fires first returns an ordinary timeout error rather than block past it. A `context.Background()` caller still hits the per-generator cap — never block indefinitely on a stalled wall clock. The same discipline applies to the clock-backward stall below.
+- **Clock-backward protection is mandatory, not advisory**: persist `last_issued_ts` in-memory across a process lifetime. On every issue, refuse or stall when `now < last_issued_ts`. Logging a warning while issuing the ID is not protection — NTP slew, VM pause-replay, container start before time sync, and operator clock reset all produce backward clocks; without refusal, duplicates are issued for the entire backward window. Stalls are bounded by caller deadline AND a per-generator cap as above; on exceed, return an error rather than block.
+- **Restart safety when `(namespace, node)` is reused**: persisting in-memory state only is insufficient — a crash-restart cycle inside the same millisecond resets the in-memory counter to zero and re-issues the IDs already emitted that millisecond, without any clock rewind. When `(namespace, node)` is reusable across restarts (the common case for stable-identity replicas), the generator MUST do one of:
+  - **(a) Skip-the-partial-millisecond**: persist `last_issued_ts` durably and, on startup, refuse to issue until wall time strictly exceeds the persisted value. Durable write of `last_issued_ts` must occur BEFORE the ID with that timestamp is observable to the caller (write-ahead, not async flush, not shutdown-only flush) — otherwise a crash between "ID returned" and "state persisted" leaves the persisted high-water mark below the issued ts and the next startup re-issues into that millisecond. Per-call durable writes are expensive; the common implementation amortizes by reserving the next millisecond durably (write `last_issued_ts = now_ms + 1` before issuing any ID in `now_ms`).
+  - **(b) Resume-the-counter**: persist `(last_issued_ts, last_counter)` durably and resume from `last_counter + 1` within the same millisecond on startup. The same write-ahead durability rule applies as in (a). Option (b) does NOT replace the clock-backward refusal above: when the host clock restarts below the persisted `last_issued_ts` (container before NTP sync, operator reset), the generator MUST still refuse-or-stall until wall time catches up, otherwise it re-issues timestamps from the rewound window.
+  - **(c) Incarnation / fencing epoch**: include an incarnation epoch in the bit layout (sub-allocated from the node-id bits) that increments monotonically per process restart and is allocated by an external registry. The epoch field MUST fail closed on exhaustion: when the encoded width has wrapped or the registry refuses, the generator refuses to start and the operator either rotates to a fresh node-id namespace or widens the epoch field with an epoch-bump migration. A rapid crash loop within one millisecond can exhaust a small epoch field; the registry's allocation contract guarantees no epoch reuse within the timestamp collision window (typical: epoch is never reused, period).
+
+  Persisting only across "host clock can rewind across restart" cases is too narrow; same-ms restart re-issuance does not require a clock rewind to occur.
+- **Field-width masking uses `(1<<bits)-1`, not `1<<bits`**: masking a configured `node_id` or `namespace_id` with `value & (1<<bits)` keeps only the high bit and zeroes the rest, which collapses many distinct IDs into one. The correct mask is `(1<<bits) - 1`. Validate inputs at boundary; clamp documented.
+- **Node id and namespace id come from a uniqueness-enforced source**: k8s StatefulSet ordinal, a centralized allocator that registers and revokes on shutdown, or a pinned per-host config with a registry of assignments. "Random in range" is a finding; the bit budget is small (typically 4-10 bits combined) and birthday collisions are easy. Two replicas with the same `(namespace, node)` re-issue duplicates within the same millisecond.
+- **Singleton per process AND per (namespace, node)**: multiple generator instances in the same process sharing the same `(namespace, node)` re-issue duplicates because each holds its own counter / `last_issued_ts` state. If sharded generators are needed (per-CPU, per-shard), partition the node-id bits across them; do not partition the counter bits.
+- **Concurrent callers serialize through a mutex on (counter, last_issued_ts)**: lock-free atomics are valid only when bit-pack, clock-backward check, and counter-rollover-to-next-millisecond wait fit into a single CAS loop. Default to mutex; only optimize when contention is measured.
+- **Wall clock, not monotonic**: IDs encode wall time for cross-process orderability, so `time.Now().UnixMilli()` (or equivalent) is the time source. The clock-backward check on `last_issued_ts` catches wall-time non-monotonicity — that is what protects correctness, not the choice of clock source.
+- **Local-fallback discipline**: when the in-process generator is a fallback for a central ID service, the fallback's node-id MUST come from a different pool than the central generators (a reserved high-bit prefix, or a fallback-only namespace) so post-incident reconciliation can distinguish central IDs from fallback IDs. Fallback issuance is a degraded-mode metric; never silent.
+
+## Queue And Task Clients
+
+For full consumer implementation, activation, retry/drop, and observability rules, also apply `mq-consumer-patterns.md`.
+
+- Producers should attach trace/log id and lane/environment metadata to every message when the queue supports properties.
+- Consumer constructors should read topic, group, worker count, retry count, filter tags, and mode from typed config.
+- Ordered consumers must reduce concurrency to one or otherwise prove ordering is preserved.
+- Consumer handlers should decode into typed payloads, validate, then call application logic.
+- Return retry for transient dependency errors; return success after logging for permanent malformed payloads.
+- For delayed tasks, put delay, queue name, timeout, and max retry in config rather than literals.
+- For Redis-backed task queues, create producer, server, and inspector as separate DI dependencies.
+
+## Bounded Fan-Out
+
+- Use a shared helper or local pattern for bounded concurrency instead of open-ended goroutines.
+- Configurable knobs should include limit, timeout, retry count, retry interval, and ignore-error behavior.
+- Preserve task index or key with each result so callers can reconstruct slices or maps.
+- Cancel remaining work on first error only when partial results are not useful.
+- Keep retry sleeps bounded by context deadline.
+
+## Dynamic Config Key Convention (Etcd / Config Center)
+
+When the dynamic config backend is etcd or an etcd-style key-value store, the key scheme is part of the cross-service contract.
+
+- Use a structured key pattern such as `/{service}/{namespace}/{key}` where `service` identifies the owning platform service identifier, `namespace` separates logical config domains (e.g. `db_shard`, `rate_limit`, `feature_flag`), and `key` is the leaf. Never let raw etcd keys leak into application code — wrap with typed accessors.
+- Periodic endpoint discovery: when the etcd endpoint list itself comes from service discovery (Nacos / Consul / k8s services), refresh the endpoint list on a bounded cadence (10–30 s is typical) in a background goroutine — NOT on the hot request path. Lazy refresh on next operation makes the refresh + reconnect cost (DNS lookup, TLS handshake) land on a user request during endpoint churn, and lets concurrent requests stampede the reconnect. Use singleflight to deduplicate concurrent reconnects and serve last-known-good endpoints with a bounded staleness window while the background refresh runs.
+- For dynamic config that backs production-critical data (DB sharding map, rate-limit budget, feature flag), distinguish three failure modes: key not found, decode error, and remote/transient error. The product contract decides which falls back to the cached value, which fails closed, and which fails open.
+- Watch callbacks (`AddListener`) must recover from panics, update the local cache atomically, and stop cleanly on parent-ctx cancellation. A watch goroutine that crashes silently is harder to detect than a missing watcher.

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

@@ -0,0 +1,70 @@
+# Developer Tooling Patterns
+
+Use this when implementing developer CLIs, code generators, scaffolding commands, or generated-file workflows.
+
+## CLI Shape
+
+- Provide non-interactive flags for every input needed by CI or agents.
+- Interactive prompts may wrap the same execution path, but should not be the only supported mode.
+- Validate required flags before doing file or remote work.
+- Print planned inputs and output paths before generation when the command changes files.
+- Return errors instead of only logging so callers can fail CI.
+
+## Project Dev Command Surface
+
+- Prefer a small documented project command surface for common agent/developer actions: status, setup, start, stop, restart, format, lint, check, test, focused test, codegen, and review.
+- A wrapper script or Make target should call the same underlying commands used by CI; do not create a second untested path.
+- Commands should print the working directory, selected config, important environment source, and the exact subcommands they run when useful for debugging.
+- Long-running service commands should expose readiness checks and logs instead of requiring manual observation.
+- Test commands should distinguish fast deterministic tests from integration, live dependency, browser, replay, or long-running suites.
+- Wrappers may load local env files for development, but CI and agents need non-interactive flags or documented environment variables.
+- Repo-local agent contracts (`AGENTS.md`): when the repo adopts root + per-source-directory contracts, wire the coverage gate into the normal lint/check path so contracts do not drift from the code. `check-agent-contract-coverage.sh` (from `product-rd-workflow/scripts/`) provides it — `--check` (guidance, non-blocking), `--fix` (scaffold missing, additive), `--enforce` (CI block once adopted). Contracts are nearest-file-wins (no root index); scope is every source-code directory, detected by source file rather than manifest — Go packages such as `dal`/`service`/`handler`/`logic` carry no manifest yet each owns distinct layering rules. Policy/ownership lives in `product-rd-workflow`'s spec / repo-contract sync gate; do not rely on review memory or a generic passing build to prove the contract is current.
+
+## Generator Shape
+
+- Parse structured inputs with real parsers, not ad hoc string splitting.
+- Keep templates in files or embedded assets with tests for rendered output.
+- Build a typed intermediate model before rendering generated files.
+- Use deterministic ordering for columns, fields, imports, indexes, routes, and generated methods.
+- Run formatting tools on generated Go files.
+- Mark generated files and document whether they are safe to edit.
+
+## File Safety
+
+- Refuse to overwrite hand-written files by default.
+- Overwrite only generated files or when an explicit force flag is provided.
+- Write to a temporary file and rename when partial writes would leave broken output.
+- Use repo-relative paths in docs and generated references.
+- Clean up temporary layout/config files.
+- When regenerating directories, move old generated output to a guarded backup path and delete that backup only after the full generation succeeds.
+- Guard any cleanup command with repo-root/path validation so a bad environment variable cannot remove an arbitrary directory.
+
+## DDL And Data Model Generation
+
+- Parse DDL with a SQL parser and preserve table name, column names, comments, indexes, unique constraints, nullable fields, and soft-delete fields.
+- Map database types to Go types through one tested table.
+- Generate model constants, query helpers, update helpers, and optional repository wrappers from the same intermediate model.
+- Sharded table suffix handling must be explicit and tested; do not infer it silently unless the convention is documented.
+
+## Tests
+
+- Test missing input, bad input parse, existing output file, force overwrite, deterministic output, formatting failure, template failure, type mapping, index generation, module path detection, and command exit status.
+
+## Build Script And Makefile Convention
+
+- Keep a per-service `build.sh` whose only job is reproducibly produce a deployable artifact: create the output directory, copy the conf files needed at runtime, mark scripts executable, and run `go build` with explicit output path. Avoid embedding codegen inside `build.sh` — codegen runs separately and its output is committed.
+- For cross-platform builds, detect OS/ARCH from `uname` and select the matching binary suffix; do not embed personal absolute paths or developer-specific Go toolchain pinning in the script.
+- Centralize all codegen and DI entrypoints in the Makefile so callers do not need to remember tool names: `make wire` (DI), `make gen_db` (DAL from DDL), `make idl` or `make_service` (IDL → server/client stubs), `make doc` (API docs). Each target is the canonical command — CI and developers use the same path.
+- Provide a top-level one-command codegen target (e.g., `make codegen` that fans out to `make wire`, `make gen_db`, `make idl`) for new-service onboarding and post-IDL-bump refreshes. Leaving each business repo with its own ad-hoc targets and no portfolio-level entrypoint is a recurring onboarding pain.
+- The Makefile should expose `make test` (fast tests) and `make test-integration` (live-dep tests). Builds that skip tests are intentional, not an oversight.
+
+## Breaking-Change Gate
+
+- For any IDL surface consumed by another team, another binary, or external clients, add a breaking-change check to CI: `buf breaking` for proto, `kitex check` for Kitex, or a custom script that compares the generated descriptor against the previous merged revision.
+- Pre-commit syntax/format checks (protoc compile + clang-format) are not breaking-change checks. They catch typos, not contract regressions.
+- When a breaking change is intentional, route it through an explicit approval path: a marker file, a PR label, or a separate "breaking" branch the gate recognizes. Do not let "the gate is annoying" be a reason to disable the check.
+
+## Static Analysis And Vulnerability Scan
+
+- **`golangci-lint` is the current default-recommendation meta-linter** for Go services — wraps `staticcheck`, `govet`, `errcheck`, `ineffassign`, `gosec`, and 100+ other linters behind one config + one binary, with parallel execution and caching. v2 reorganized the config format and made the enabled-linter list explicit rather than implicit; verify the exact stability tiering against `golangci-lint.run/usage/linters` for the version you pin. Pin a specific version in CI so the rule set doesn't drift under a contributor's local `golangci-lint` upgrade. Service-specific tuning lives in `.golangci.yml` at the repo root — do NOT enable every available linter (the noise drowns real findings); start from a curated set (`govet, errcheck, ineffassign, staticcheck, gosec, gocritic` plus team-specific picks) and add linters individually as the team agrees on them. Reserve `staticcheck` standalone only when a sibling Go service hasn't yet adopted golangci-lint and migration would block the current change.
+- **`govulncheck` (`golang.org/x/vuln/cmd/govulncheck`) is the Go team's official vulnerability scanner** — symbol/call-graph aware (significantly reduces false positives versus naive go.sum CVE scanners by skipping CVEs whose vulnerable symbols the binary's call graph does not reach; reflection / `init` side effects / build-tag-conditional code can still expose CVEs that static call-graph analysis misses, so govulncheck is a strong baseline, not absolute proof of safety). Run as a CI gate: `govulncheck ./...`. Integrate into the same Make target as other quality gates (`make vuln` or fold into `make lint`); fail the build on findings unless the project explicitly waives a CVE via an issue-tracker reference and a justification comment in the waive-list. Re-run on schedule (weekly cron) in addition to per-PR — new CVEs land continuously and a passing PR last month may be vulnerable today.

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

@@ -0,0 +1,78 @@
+# Domain Feature Patterns
+
+## Handler Pattern
+
+- Keep handlers thin: bind request, validate shape and limits, resolve auth/resource scope context, call application logic, and map response/error.
+- Put reusable validation in small check functions instead of burying it in domain orchestration.
+- Validate batch size, required IDs, enum values, pagination, and mutually exclusive fields before side effects.
+- Use canonical error codes for validation failures; do not leak raw dependency errors in public responses.
+- Always return a response envelope even when downstream logic returns an error.
+- Avoid mutating inbound generated request objects except for narrowly documented compatibility normalization; prefer converting into application parameters.
+
+## Parameter And Result Mapping
+
+- Convert transport requests into application parameter structs before domain logic.
+- Parameter constructors should tolerate nil input only when nil is a valid no-op; otherwise validate at the handler boundary.
+- Use pointer fields or explicit presence flags for patch/update semantics where zero and absent differ.
+- Keep helper getters such as `GetX()` value-or-zero only after validation has decided whether absence is allowed.
+- Result structs should own conversion back to transport response objects when response assembly is non-trivial.
+- Add a safe `Meta` or summary method for audit/logging when complex params need observability; include identifiers and option flags, not raw sensitive payloads.
+
+## Domain Model Mapping
+
+- Keep domain objects separate from DB models when they carry behavior, derived flags, runtime-only fields, or compatibility transforms.
+- For finite domain values such as market, region, status, scene, source, provider, priority, permission, or channel, define one domain-owned constant/type set and one canonicalization/parse function before using the value across application, persistence, or tests. Transport enums, DB strings, headers, and query params should convert at the boundary; business logic and tests should reuse the domain symbols instead of scattering raw literals such as `"US"`, `"CN"`, `"active"`, or `"default"`.
+- When the same finite value crosses service or package boundaries, put the canonical type/constants and parser in the smallest shared domain or platform package already allowed by the repo. Do not let two services invent parallel canonical sets for the same concept. A shared package exempts local debt markers only after it actually contains the canonical type/constants and parser, not merely because the package exists; a CI check, grep panel, or required review checklist MUST verify the package contents before accepting the exemption. If no eligible shared package exists, the shared package lacks the canonical type/parser, or creating one needs architecture approval, keep the local constants for this slice, add a same-line `finite-value-debt: <task-ref> <owner> <deadline> <reason>` comment at every temporary duplicate/raw use outside boundary conversion, and record a consolidation task. A debt marker without task reference, owner, and deadline is non-compliant.
+- When a finite value already has a protobuf enum or external enum, do not treat the generated enum as the only domain model unless every non-transport layer can safely depend on it. If storage, headers, or existing domain models remain string-based, add domain constants plus explicit enum/string conversion helpers first, mark direct generated-enum or raw-string use outside transport/storage conversion with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`, and migrate call sites incrementally.
+- Architecture owns cross-boundary semantic consistency for finite values: approve the shared package or contract location, approve any transport-coupled exception through a traceable architecture decision, and make sure every `finite-value-debt` marker has an exit owner, deadline, and consolidation task.
+- Use explicit `FromModel`, `Model`, or `Populate` methods for conversion; do not rely on reflection-based copying for behavior-rich objects.
+- For patch/updater structs, use pointer fields to mean "set this field" and nil to mean "leave unchanged".
+- Generate or centralize repetitive getters/mappers when many services need stable map/group/sort keys.
+- Do not let storage-only columns leak into public response objects unless the API contract intentionally exposes them.
+
+## Application Logic Pattern
+
+- Application logic orchestrates domain rules and infrastructure calls; it should not parse transport-specific headers, cookies, or query strings directly.
+- Convert transport DTOs into domain/application parameters before deep domain logic.
+- Group related side effects into phases:
+  - validation and read preconditions.
+  - durable writes inside a transaction. **Required async side effects (MQ publish, projection update, downstream notify that the workflow depends on) MUST be written to an outbox row in the SAME transaction**, then dispatched by a separate poller/relayer — see `db-schema-and-dal-patterns.md` outbox pattern. Publishing MQ "after the transaction commits" loses messages whenever the process dies between commit and publish.
+  - only explicitly **best-effort** side effects (cache warm-up, low-priority counter, optional notification) may happen post-commit; document each one as opt-in best-effort, not the default.
+- Mark best-effort side effects explicitly in logs and metrics; failures should not silently disappear. If a side effect's failure would leave the system in an inconsistent state, it is NOT best-effort — promote it to the outbox.
+- For external file or HTTP fetches, use bounded clients with context, validate content type/size/status, and close response bodies with `defer`.
+- Do not accept caller-provided URLs, file paths, or object keys directly into fetch/read/delete operations without validation and namespace checks.
+
+## Transaction Pattern
+
+- Use a DB transaction only for writes that must commit atomically in the same database.
+- Pass transaction-bound repositories into inner calls rather than letting inner code reopen the default write connection.
+- Keep network calls, MQ sends, object storage writes, and long CPU work outside the transaction where possible.
+- Re-read mutable quantities or counters inside the transaction when correctness depends on latest state.
+- Use row locks or compare-and-update when concurrent writers can affect the same record.
+- Do not hide post-commit side effects inside transaction callbacks.
+- Transaction helpers should rollback on returned error and recovered panic, then return a typed error instead of swallowing the failure.
+- Always check begin and commit errors; if rollback fails, log it with safe context without replacing the original operation error unless the rollback failure changes correctness.
+
+## Batch Write Pattern
+
+- Enforce a maximum batch size at the handler or application boundary.
+- Split huge imports into chunks and make each chunk idempotent.
+- Use upsert with explicit update columns; avoid update-all unless the whole row is intentionally replaceable.
+- For per-row status updates, prefer generated update helpers or parameterized expressions. If raw SQL is unavoidable, never construct it from untrusted strings.
+- Treat empty input as a no-op only when that is semantically valid; otherwise return a validation error.
+
+## Pagination And Listing
+
+- Normalize page/limit or offset/limit at the boundary.
+- Set a maximum limit for public APIs and high-cost internal queries.
+- For ordinary UI lists, count plus ordered page is acceptable.
+- For backfills, exports, and large reads, prefer cursor/id-window iteration over offset pagination.
+- Always specify a deterministic order when paginating.
+
+## Concurrency In Domain Logic
+
+- Use bounded concurrency for fan-out RPC/HTTP calls.
+- Combine timeout, retry, and concurrency limit; do not retry unboundedly.
+- Preserve result mapping by stable key when concurrent calls return out of order.
+- Decide fast-fail versus collect-partial-results deliberately.
+- Tests that stress concurrency should be separate from default fast tests when they need real services.

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

@@ -0,0 +1,119 @@
+# Engineering Patterns
+
+## Repo Layout
+
+Recommended layout for a new service:
+
+```text
+cmd/ or main.go
+conf/
+idl/ or proto/
+handler/
+service/ or logic/
+domain/
+infra/
+  dal/
+  cache/
+  rpc/
+  mq/
+model/
+inject/ or internal/di/
+tests/
+```
+
+Use the existing repo's layout when one already exists.
+
+When a layering boundary must actually hold — e.g. the core domain must never import infra or heavy SDK dependencies — consider giving that layer its own Go module: a module whose `go.mod` physically lacks the dependency turns a violation into a compile error, which is strictly harder to bypass than import-lint or review convention. Reserve this for boundaries worth the extra module/versioning overhead.
+
+## Code Generation
+
+- IDL/protobuf generates RPC/HTTP contracts and stubs.
+- DB DDL can generate model/query/updater/DAL helpers if the project has a generator.
+- DI code can be generated from provider declarations.
+- Swagger/OpenAPI annotations can be generated from handlers or contracts.
+
+Rules:
+
+- Keep source inputs and generated outputs in the same change.
+- Document commands in Makefile, README, or scripts.
+- Use repo-relative paths; do not commit generator commands with personal absolute paths.
+- Do not patch generated files manually unless the generator is unavailable and the risk is accepted.
+- When a repo uses multiple generators, identify the source of truth for IDL/routes, DB models/query helpers, and DI output before editing; update source inputs first, then regenerate outputs.
+
+## DB Pattern
+
+- DAL exposes intent-focused methods, not raw query fragments everywhere.
+- Query builder/updater helpers are useful when they prevent unsafe ad hoc SQL.
+- Use `R(ctx)` for reads and `W(ctx)` for writes when supported.
+- Configure connection pool, read/write resolver, tracing, and query logger at DB proxy initialization.
+- Treat sharding as a first-class DB concern: define shard key, shard count, DDL behavior, and bypass rules explicitly.
+- Use transactions for multi-step writes and recover/rollback on panic.
+- Apply the detailed DAL guardrails in `data-access-patterns.md` for list bounds, update/delete conditions, explicit update columns, and upsert column selection.
+
+## Redis Pattern
+
+- Key format should be deterministic and centralized.
+- TTL must be explicit for every cache key.
+- Cache miss should be distinguishable from infrastructure failure.
+- Locks must use unique values and safe unlock.
+- Lua/CAS scripts are appropriate for compound atomic operations.
+- Script-backed helpers should handle script-cache misses by reloading or falling back according to the client contract, and tests should cover missing-key, compare-failed, and invalid-return paths.
+
+## MQ Pattern
+
+- Event names should describe domain facts, not implementation steps.
+- Producers attach trace/log metadata where the stack supports it.
+- Producers should use bounded send context and document sync, async, or one-way semantics.
+- Consumers must tolerate duplicate, delayed, and out-of-order messages unless ordering is guaranteed and configured.
+- Handler return value should intentionally control retry vs skip.
+- Consumer config should make worker count, broadcast vs cluster mode, retry count, ordering, topic, and tag/filter expression explicit.
+
+## Tests
+
+- Table-driven unit tests for domain logic, pure helpers, validation, and DAL query options.
+- Component tests for DB/Redis/MQ wrappers when the local environment is available.
+- Fake clients for RPC/HTTP integrations, including timeout, dependency error, and non-OK domain status.
+- Contract tests for protobuf default values, enum handling, and response error mapping.
+- Handler/service scenario tests for request mapping, auth context, resource-scope context, and response codes.
+- Consumer tests for duplicate message and retry/skip decisions.
+- Scheduled job tests for lock acquisition failure, timeout, retry exhaustion, and panic recovery.
+- Build/codegen verification when IDL, generated code, or DI changes.
+- Keep infrastructure-dependent tests out of the default fast test path unless the local environment is guaranteed.
+
+## Middleware Pattern
+
+- Inbound middleware should create or accept a trace/log id, attach it to context, and return it to the caller when the protocol supports it.
+- Request and response body logging should be gated by config and environment.
+- Recovery middleware should log panic stack, return canonical internal/panic error, and increment panic metrics.
+- Metrics middleware should record QPS, latency, success, error, and canonical error code for both server and client sides.
+- Auth middleware should populate typed context values; application code should not parse tokens or cookies directly.
+
+## Error Handling Pattern
+
+- Domain/application code returns typed or wrapped errors with stable canonical codes.
+- Transport code converts canonical errors into HTTP/RPC responses.
+- Client middleware converts remote canonical errors back into local errors so callers can branch on code.
+- When a dependency or helper returns an explicit status/envelope, callers must branch on success or error before reading optional result fields; never assume success from a nil error alone when the contract carries domain status separately.
+- Unknown errors default to internal/dependency failure and must be logged with context.
+- Validation errors should be permanent; dependency timeouts and unavailable errors may be retryable depending on operation idempotency.
+
+## Context Key Convention And Metainfo Propagation
+
+The set of ctx keys a service relies on is part of the service's public surface; treat it as deliberately designed, not ad hoc.
+
+- Organize ctx keys in tiers by trust and lifetime: global keys that travel with every request (trace/log id, PSM, lane, IDC, cluster, stress tag); API-context keys derived from the gateway after auth (user id, tenant id, organization id, role); raw header keys mapping inbound `X-*` HTTP headers to their canonical ctx name. Document the tier in code (separate const blocks or files) so reviewers can see which keys are platform-level vs business-level.
+- Define a typed accessor per ctx key: a function `LogIDFromCtx(ctx) string` that performs the type assertion is safer than asking callers to remember `ctx.Value("logId").(string)`. Bare string-key access returning `any` is acceptable only for short-lived experiments; production code should hide the assertion behind typed helpers.
+- For Kitex-style frameworks that must propagate ctx values both inside the binary and across the wire, dual-inject: write the value to `metainfo.WithPersistentValue(ctx, key)` for cross-hop persistence and to the framework-specific outgoing metadata (HTTP/2 metadata for gRPC, TTHeader for Thrift). The framework's `MetaHandler` chosen at server-build time determines which transport carries it; the application code remains transport-agnostic.
+- Distinguish "persistent" metainfo (forwarded on every downstream hop) from "transient" metainfo (one hop only). Lane, stress tag, and trace identity are persistent; one-off control flags should be transient or moved to typed request fields.
+- For HTTP gateways, define the mapping between inbound `X-*` headers and ctx keys once, in a binding step at the edge; do not re-read raw headers in domain code.
+
+## Go Language Baseline 2025-2026
+
+Adopt newer Go stdlib idioms when the project targets Go 1.21+ — the older patterns (hand-rolled `sync.Once` value-cache, `for { ... <- ch }` iterators, manual JSON omit-zero handling, ad-hoc context propagation in tests) are now non-idiomatic and produce reviewer questions.
+
+- **`sync.OnceFunc` / `sync.OnceValue` / `sync.OnceValues` (Go 1.21+) replace the `sync.Once` + closure + cached-result pattern** for lazy singletons. Per Go stdlib docs: `sync.OnceValue(func() *Client { ... }) func() *Client` returns a function that initializes once and returns the cached value on every subsequent call. Use `OnceValues` for `(value, error)` pair. Old pattern (`var once sync.Once; var client *Client; func get() *Client { once.Do(...); return client }`) is verbose and easy to get wrong; `sync.OnceValue` is one-liner. **Panic semantics to know**: if the init function panics, every subsequent call re-panics with the same panic value (literally — same value, not a wrapped error); concurrent callers waiting during init unblock after `Do` completes and also re-panic. This is fail-fast-by-design (the cached value is never partial), but it means a transient init failure that you might want to retry across calls needs explicit retry-or-reset logic outside the OnceValue closure — OnceValue gives no second chance on its own.
+- **Range-over-function iterators (`iter.Seq[T]` / `iter.Seq2[K,V]`, Go 1.23+)** are the new idiom for user-defined iteration over arbitrary in-process sequences — paginated API pages held in memory, lazy filter/map/take/zip chains, tree/graph traversal, slice/map iteration via `slices.Values`/`maps.All`. Producers expose `func(yield func(T) bool) {...}`; consumers use `for v := range producer { ... }`. The new `iter` package shipped in 1.23; `slices` and `maps` packages already existed and gained iterator-oriented helpers in 1.23 (`slices.All`, `slices.Values`, `maps.All`, etc). **NOT the right tool for cancellable streaming over a network or long-lived async source** — yield is synchronous and the iterator does not compose with `select { case <-ctx.Done(): ... case v := <-ch: ... }` the way a channel does. Channels + cancellation context remain the right shape for: streaming RPC responses, MQ consumers, long-poll, websocket message loops, anywhere the consumer needs to interleave the data source with deadline / shutdown / multiple sources. The producer-side rule: if the source can block on I/O for an arbitrary duration AND the consumer needs to cancel it, prefer a channel + context; if the source is synchronous (computation, in-memory traversal) or blocks only on cooperative read calls the producer controls, prefer an iterator.
+- **`omitzero` struct tag (Go 1.24+)** replaces the `omitempty` foot-gun for non-pointer numeric / time / struct fields. `omitempty` drops `0`, `""`, `false` (often incorrect for fields where zero IS meaningful); `omitzero` drops only the actual Go zero value of the field type, and if the type has `IsZero() bool` (e.g. `time.Time`) it uses that. Migrate `time.Time omitempty` to `omitzero` first — it's the most common bug source. **`omitzero` is recognized only by Go's stdlib `encoding/json` (1.24+). Third-party JSON encoders (`json-iterator/go`, `goccy/go-json`, `easyjson`, `sonic`, etc) ignore unknown tags silently and behave as if no `omitempty` is set — verify the project's actual JSON serializer accepts `omitzero` before migration, or the marshaled output reverts to "always emit" semantics**. Same caveat for any non-stdlib codegen serializer.
+- **Per-object / per-request state maps: `delete` on lifecycle; a strong-pointer key leaks, a numeric/id key cross-attributes.** A long-lived map holding per-connection / per-request / per-object state must delete its entry on the object's close / lifecycle end. Two distinct failure modes: a `map[*T]` with a **strong pointer key keeps the object alive**, so a missed delete is a memory leak (the object is never freed); a `map[id]` / `map[uintptr]` keyed by a **numeric id or address does NOT keep the object alive**, so once the original is gone that id/address can be **reused** and silently cross-attributes one object's state to a different, later one. Either way, `delete` deterministically on the close/lifecycle you control — Go does not prune a strong-keyed map for you. Guard the map (a mutex or `sync.Map`) — but a map mutex alone is not enough: on `Close`, under the registry lock mark the object closed (tombstone) and block future lookups; then **release the lock to cancel/drain/wait** for in-flight goroutines (holding the lock through the drain deadlocks if those goroutines need it to finish); then re-acquire and `delete` — otherwise a concurrent goroutine reads or lazily recreates state for a closing object (use-after-delete / resurrected state). Keep the `closed` marker on the **object itself** (an object-owned flag / generation token), not only in the registry entry, or the `delete` erases the tombstone and a later call on the still-referenced object recreates state. (Go 1.24+ `weak` pointers + `runtime.AddCleanup` help for objects with **no** explicit close, but only as a backstop: they fire after the object is unreachable, may be delayed, and are not guaranteed before process exit. Route `Close` and the cleanup through **one idempotent release** (`sync.Once`/atomic) and call the cleanup's `Stop()` on a successful `Close` to avoid a double-free; and the cleanup func must NOT capture the object itself — that keeps it reachable so cleanup never runs — pass only the underlying handle and `runtime.KeepAlive` the object after its last real use.)
+- **`testing.TB.Context()` (Go 1.24+) and `t.Chdir(dir)` (Go 1.24+)** clean up two common test patterns. `tb.Context()` is a context auto-cancelled on test cleanup — replace `ctx, cancel := context.WithCancel(...); t.Cleanup(cancel)` with `ctx := t.Context()`. **Scope is the current test/subtest, not the parent**: a goroutine spawned inside `t.Run("sub", func(t *testing.T) { go work(t.Context()) })` sees the context cancel when the subtest ends, NOT when the parent ends — leaking that goroutine past the subtest is the responsibility of the test (use a wait + verify or use the parent's context if cross-subtest scope is intended). `t.Chdir()` changes directory for the test and restores on cleanup — replace manual `os.Chdir + t.Cleanup(os.Chdir(orig))`.
+- **`encoding/json/v2` (Go 1.25, experimental behind `GOEXPERIMENT=jsonv2`)** is the upcoming replacement for `encoding/json` — faster, stricter, better error messages, fixes long-standing decoder quirks. NOT production-default yet (experimental flag required). Track for Go 1.26+ stabilization; do not migrate hot paths to it before stable, but new greenfield services may pilot it on opt-in subpackages with the experiment flag set in build config + tests verifying behavior parity with stable v1.

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

@@ -0,0 +1,55 @@
+# Error Contract Patterns
+
+Use this when implementing canonical errors, response builders, validation errors, dependency error mapping, or transport error conversion.
+
+> Sibling sync (this file holds the canonical list): `python-service-dev/references/error-handling-patterns.md` mirrors these for Python and points back here rather than restating them, so the list lives in one place. Shared error-model invariants both stacks must hold — edit them HERE: canonical typed error model; convert only at the transport boundary; no internal/secret leak in API responses; cross-RPC envelope via structured details, not a freeform status-message string; closed classification enums with fail-closed defaults, and classification correct before retry/fallback policy is built on it. Stack glue (Kitex/gRPC vs FastAPI/gRPC) may differ; the invariants may not. Advisory — there is no automated parity gate; keep the two in sync by hand.
+
+## Error Type
+
+- Implement a typed error with code and safe message, and make it compatible with `errors.As`.
+- Keep the internal error chain when adding context; do not replace the cause with a formatted string unless intentionally crossing a trust boundary.
+- Do not encode typed errors only as JSON strings; provide methods or fields for code/message access.
+- Common constructors should cover known codes and default messages.
+- Avoid embedding raw request bodies, secrets, credentials, tokens, or personal data in error messages.
+
+## Definitions
+
+- Group local errors by layer: validation, domain rules, data access, dependency, and system failures.
+- Use common codes for common classes and local definitions for local meanings.
+- Validation errors should use stable field names and client-safe messages.
+- Dependency adapters should translate upstream status/code/message into canonical local errors.
+- Timeout, cancellation, and rate-limit errors should remain distinguishable.
+- When policy code (retry, fallback, cooldown, alerting) branches on error class, define the classification as a closed enum and make every `switch` over it fail closed in `default` — where "safe direction" is decided per policy domain, not one global answer: for side-effect-bearing actions (retry that can double-execute, billing, writes) unclassified means do-not-act; for availability paths, an unclassified dependency-origin error may still enter bounded, semantics-preserving degradation (count toward circuit-open, take an already-safe fallback) — a provider changing its error wire shape must not turn every response into a hard refusal. The invariant is that a missed mapping never *amplifies* (no blind retry storms) and never silently acts on unknown semantics; pick each default deliberately and record it.
+- Get the classification layer right before building retry/fallback/cooldown on top of it — the order cannot be reversed; policy stacked on a wrong or leaky classification hard-codes the wrong failure behavior and is expensive to unwind.
+
+## Response Mapping
+
+- Response builders should map typed errors to code/message and unknown errors to internal failure.
+- Success responses should set the canonical success code and include data only when available.
+- For shipped response envelopes or error payloads, preserve existing accepted fields and client-readable semantics by default while adding the new canonical shape. Removing legacy fields, changing success/error code meaning, or changing where business data lives is a breaking change and requires explicit human approval with a compatibility and rollback plan.
+- When a breaking response-contract change is approved, update server tests, generated or typed clients, web/app parsing tests, smoke/E2E checks, documentation, and residual compatibility scans in the same delivery slice.
+- HTTP and RPC handlers should convert errors once at the boundary.
+- Worker and async job handlers should persist canonical error code/message on terminal failure.
+- Logs should include trace/log id and the wrapped internal error where safe.
+
+## Cross-RPC Envelope Serdes
+
+When typed errors must traverse Kitex/gRPC/HTTP boundaries, both sides participate:
+
+- Server-side ErrorHandler converts internal causes — framework biz error, RPC timeout, ACL denial, panic, validation — into the canonical typed error and serializes it into the transport-level error slot per protocol: for gRPC, use `google.rpc.Status` details (carried via `grpc-status-details-bin` trailer or framework-native details mechanism), not the freeform status message string; for header-based RPC protocols, use protocol-native metadata frames; for HTTP, use a response body envelope. Do not let raw internal errors leak across the boundary.
+- Client-side ErrorHandler runs the reverse: extract the canonical structured shape from the protocol-specific channel — for gRPC, parse `google.rpc.Status` details from `grpc-status-details-bin` trailer or framework details mechanism, NOT freeform `rpcErr.Error()` text; for header-based RPC, read protocol-native metadata frames; for HTTP, parse the response body envelope. Reconstruct the typed error and surface it to the caller as a real Go error implementing the project's typed-error interface. If the wire payload is not the canonical shape, wrap it as a transport / unknown error and never drop the original cause silently. Parsing `rpcErr.Error()` as a JSON envelope loses typed-retry / security decisions and risks leaking server-rendered messages that were meant for logs.
+- Reserve a numeric code range for the shared envelope (e.g., `[0, 11999]`) inside the shared IDL (`base.proto` or equivalent). Within that range, sub-range allocation per tier (platform / api / domain) prevents collisions when services define their own codes.
+- Distinguish "system errors with a structured code" from "biz errors with a structured code" in the envelope so middleware decisions (alert vs ignore, retry-safe vs not) are deterministic.
+- Document the i18n boundary: error messages in the envelope are typically a single language (often English). User-facing translations belong to the gateway / front-end based on the code, not the message text.
+
+## Standard Library Wrap Compatibility
+
+- Prefer `fmt.Errorf("...: %w", err)` for non-boundary wrapping inside one process. When crossing a transport boundary forces JSON / string serialization of the typed error, keep the `errors.As`-compatible reconstruction on the client side so consumers can still type-assert. Document any place where `%w` chain is intentionally severed (boundary serdes) and provide a reverse path.
+- `%w` makes the wrapped error part of the package's public API — callers can `errors.Is`/`As` it. Inside the process keep `%w`. At an exported / public-contract or transport boundary, **return the typed safe error (or canonical envelope) itself** — do not `%v`-wrap the typed error, or the boundary mapper's `errors.As` stops matching and you emit unknown/500. Use `%v` only to embed a raw internal/driver cause as *text* inside a safe message or log line, never to wrap the canonical typed error. And do not blanket-`%v` errors callers legitimately match on: `context.Canceled` / `context.DeadlineExceeded`, not-found, and documented domain sentinels stay `%w` (test-asserted via `errors.Is`/`As`) — switching them to `%v` breaks cancellation/timeout/not-found mapping and loses the observability chain.
+
+## Tests
+
+- Test typed error matching with `errors.As`, wrapping preservation, unknown error fallback, validation field output, dependency mapping, panic mapping, timeout mapping, and response envelope output.
+- For cross-RPC envelope serdes, test a roundtrip: server raises typed error → wire format captured → client reconstruction yields a typed error with the same code/message and matches `errors.As` on the original type. Include the unknown-shape path: a wire-format that does not match the canonical envelope returns a transport/unknown error without silent data loss.
+- Test code-range allocation: a service trying to register a code outside its allocated range fails at build/test time, not at runtime.
+- For closed error-classification enums, add an exhaustive positive-assertion test: every enum member is explicitly asserted to map to its intended policy outcome, plus at least one unknown/unclassified value asserted to take the fail-closed branch.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/references/feature-playbook.md

@@ -0,0 +1,61 @@
+# Feature Playbook
+
+## Before Business Feature Work
+
+1. Inspect the existing platform layer before adding business code.
+2. Reuse existing cross-cutting primitives for runtime wiring, config, secrets, dependency clients, lifecycle, readiness, observability, request metadata, response envelopes, and canonical errors.
+3. Do not promote by category name alone. Promote a capability to platform only when it has at least two real reuse points, stable behavior across those features, and can remain domain-agnostic without importing domain/application/interfaces types.
+4. Keep concrete external adapters in infra unless the repository already defines a platform-level dependency lifecycle primitive for them.
+5. Keep product-specific workflow, policy, schema, query, feature-specific readiness, business error classification, and side-effect orchestration outside platform.
+
+## New HTTP Endpoint
+
+1. Add or update protobuf/API contract.
+2. Regenerate HTTP router/handler stubs if the stack uses codegen.
+3. Implement handler validation and auth/context extraction.
+4. Call application/service layer; do not put domain workflow directly in handler.
+5. Map domain errors to stable API errors.
+6. Add handler/service tests and update Swagger/OpenAPI if used.
+
+## New RPC Method
+
+1. Add protobuf request/response and service method.
+2. Regenerate RPC code.
+3. Implement generated interface in handler/server package.
+4. Put domain workflow in service/logic layer.
+5. Add client wrapper if other services will call it.
+6. Add compatibility tests for default/empty fields and error cases.
+
+## New DB Table Or Column
+
+1. Write migration/DDL first.
+2. Generate or update model/query/update helpers if codegen exists.
+3. Add DAL methods using context and read/write connection conventions.
+4. Keep batch sizes bounded.
+5. Use transactions for multi-table writes.
+6. Add tests for query conditions, empty inputs, duplicate/upsert behavior, and transaction rollback.
+
+## New Redis Cache / Lock / Limiter
+
+1. Define key format and scope.
+2. Define TTL and stale-data behavior.
+3. For caches, decide cache-aside read-through behavior and invalidation path.
+4. For locks, use unique values and compare-and-delete unlock.
+5. For rate limiters, define scope, window, limit, and transaction/retry behavior.
+6. Add tests around key generation and miss/error behavior.
+
+## New MQ Consumer
+
+1. Define event schema and producer ownership.
+2. Define topic, group, tag/filter, ordering, retry count, and worker count.
+3. Implement handler idempotency before side effects.
+4. Distinguish invalid messages that should be skipped from transient failures that should retry.
+5. Add metrics for consumed, skipped, retried, failed, and lag if available.
+6. Start consumer through service lifecycle, not package init.
+
+## New External Client
+
+1. Wrap generated or third-party client behind a small adapter.
+2. Centralize timeout, retry, discovery, auth, tracing, and logging.
+3. Convert external errors into service/domain errors.
+4. Add tests with fake adapter or mock client.