@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: go-microservice-architecture
+description: Use when designing, reviewing, or explaining a new product's Go backend or microservice architecture using Kitex or similar RPC, Hertz or similar HTTP gateway, protobuf IDL, MySQL/GORM-style relational storage, Redis cache/locks/rate limiting, service discovery, dynamic config, message queues, observability, DI, and code generation. Product-agnostic; do not depend on existing codebase paths, service names, or legacy repositories. Prefer this for architecture, service boundaries, contracts, data ownership, reliability, security, and platform decisions when no code changes are requested; use go-microservice-dev for implementation work. Triggers also include "Go 后端架构怎么设计", "Go 微服务怎么拆", "RPC 接口怎么定义", "Go 服务边界", "Go 服务重构 / 架构分层重构", "拆分 Go 服务的上帝类/模块边界", "decompose a god class in a Go service".
+---
+
+# Go Microservice Architecture
+
+Use this for new product/server architecture work. It distills proven backend patterns but must not assume any existing repository, service identifier, package path, database, or legacy service layout.
+
+## Skill Routing
+
+- Use this skill for architecture decisions, service decomposition, API/RPC contract shape, storage ownership, async workflow design, observability, reliability, and launch readiness.
+- Use `product-rd-workflow` first when the request spans product shaping, architecture, implementation, review, release, and learning loops rather than architecture alone.
+- Use `go-microservice-dev` when the user asks to implement, modify, debug, test, scaffold, or generate code. A localized refactor (某文件/某类) also belongs to `go-microservice-dev`; only service-wide layering/boundary redesign stays here, and a multi-stage / cross-module refactor delivery must re-enter `product-rd-workflow`. An unqualified whole-service "Go 服务重构" enters here by default, mirroring the Python pair — do not let the unqualified form fall to the implementation skill.
+- Use `python-service-architecture` for Python services. Do not load Python rules for Go work unless the task is explicitly cross-language contract design.
+- Use `platform-observability` for logs/metrics/traces/log-id propagation/dashboards/alerts/SLI-SLO design. This skill owns only the service-side observability surface (Kitex/Hertz middleware that emits structured logs, OTel SDK use, baseline labels attached by metrics client, health endpoints); the cross-cutting evidence stack belongs there.
+- Use `platform-service-connectivity` for service mesh, service discovery (Nacos/Consul/equivalent), mTLS, multi-environment lane routing, retry/timeout/circuit-breaker policy, and the canonical RPC base struct shape. This skill defines what the service exposes (framework default options usage, request-metadata propagation conformance via the platform's chosen carrier — in-message `base` or transport metadata, scenario-driven per the connectivity Carrier decision — graceful shutdown); mesh policy and routing rules live there.
+- Use `platform-release-engineering` for environment/lane matrix, canary/blue-green, promotion gates, rollback playbook, secret distribution, dynamic-config (config-center) vs static-config split, image build pipeline. This skill owns the service-side contracts (config schema, secret consumption interface, registration metadata); release flow lives there.
+- Use codebase-specific skills only when the task is explicitly about an existing legacy/workspace repository.
+- Architecture references should define decision criteria, invariants, ownership boundaries, and acceptance checks. Put concrete code patterns, helper APIs, and test mechanics in `go-microservice-dev`.
+- When changing an architecture rule that implementation must obey, name the downstream execution owner before landing: `go-microservice-dev` for code mechanics, `testing-strategy` for proof layer, platform skills for runtime contracts, and `product-rd-workflow` for cross-stage gates. If the rule also applies outside Go, route through `skill-extraction-workflow` and mirror or explicitly skip sibling architecture/dev skills.
+- For money, billing, quota, permission, tenant/user data isolation, privacy, high-impact AI, repeated writes, async finality, or incident-explanation risk, start from `product-rd-workflow` and its high-risk resilience gate before choosing service boundaries or fallback behavior.
+
+## Platform Boundary
+
+This skill owns the **service-internal** view: layer separation (transport/application/domain/infra), protobuf IDL design, DAL boundaries, MQ consumer shape, error-code contract, DI/Wire generation. It exposes a fixed contract to the platform layer:
+
+| Service exposes (this skill owns) | Platform owns (route to platform-* skill) |
+|---|---|
+| `/healthz`, `/readyz`, `/ping` endpoints (via framework default) | Orchestrator probes; registry healthcheck contract |
+| Use of framework default server suite + client suite (e.g. Kitex/Hertz `Default*Options`, or equivalent) | What that middleware chain must include — see `platform-observability` and `platform-service-connectivity` |
+| Conformance to the platform's request-metadata envelope (request id / correlation id / lane / caller identity), populated by client middleware | Cross-language contract on the envelope shape |
+| `context.Context` carrying correlation id, trace context, lane/env, deadline through every hop; helper to clone-without-cancel for spawned goroutines | How those fields propagate across mesh / queue / async boundaries |
+| Structured logger interface that emits JSON with the platform field schema (trace context extracted from ctx automatically) | Log shipping pipeline, search index |
+| Stable error-code enum + framework error mapping (timeouts, panics, permission errors → typed codes) | Cross-service error contract evolution |
+| Graceful shutdown: deregister from SD → drain → close clients → exit | Orchestrator pre-stop hook and termination grace |
+| Secret consumption via platform secret-store SDK; never read from committed files | Secret rotation pipeline, secret-store deployment |
+| Static config in per-environment files bundled in the image; dynamic config via config-center SDK | Config-center deployment, audit, rollout |
+| Service registration metadata: platform service identifier, lane tag, region/cluster tags, version, weight | Registry deployment, federation, healthcheck propagation |
+| Metric emission via framework metrics client with baseline labels auto-attached | Metric storage, cardinality budget, SLI definition |
+
+A Go service author works against this contract. Platform-level questions ("which mesh policy?", "which collector?", "which canary weight?") route to the platform skills. Cross-language uniformity is what makes the platform layer reusable.
+
+## Generalization Discipline
+
+- Keep only reusable server-side mechanics: contracts, layers, storage ownership, config, reliability, observability, security boundaries, code generation, and delivery workflow.
+- Do not copy product nouns, service names, package paths, provider names, environment names, IDs, dashboards, callback types, or organization-specific operating habits into the architecture.
+- When source code shows a domain-specific concept, generalize it to `domain object`, `resource`, `authorization scope`, `integration scope`, or `workflow` only if the mechanic is reusable; otherwise discard it.
+- When patterns conflict, choose deliberately:
+  - Prefer current contracts and requirements over historical code habits.
+  - Prefer relational durable truth over Redis-only truth for auditable state.
+  - Prefer explicit protobuf/config/schema contracts over reflection, hidden globals, or stringly conventions.
+  - Prefer idempotency and durable acceptance over retry-only designs.
+  - Prefer fail-closed for auth, permission, critical state transitions, and data-integrity paths; fail-open only for non-critical cache/telemetry paths when availability requires it.
+  - Fuse patterns only when both are generic and complementary; otherwise keep the simpler product-agnostic rule.
+- Example: if one codebase stores workflow state only in Redis and another persists it in a relational table, keep the relational source-of-truth rule and optionally use Redis as cache, lock, rate limit, or scheduling aid.
+
+## Core Workflow
+
+Before changing architecture guidance, contracts, service boundaries, diagrams, plans, or implementation-driving recommendations, complete enough analysis and planning for the decision to be reviewable. Scale the plan to risk: a simple low-risk explanation can use a short inline plan; multi-service, contract-visible, data-ownership, release, high-risk, branch/MR, or unclear-risk architecture work needs explicit assumptions, alternatives, tradeoffs, acceptance checks, verification evidence, rollback or migration path, and named handoffs to implementation, testing, platform, or product workflow skills before edits or approval.
+
+1. Define the product boundary.
+   - Identify user workflows, domain objects, external integrations, and lifecycle events.
+   - Decide which capabilities must be synchronous APIs, internal RPCs, async jobs, or scheduled tasks.
+   - Internal microservice calls use RPC/gRPC by default and may use HTTP when the service contract chooses it. Internal HTTP must meet the same service discovery, auth, timeout, retry, observability, and contract-test standards as RPC.
+   - Avoid splitting into microservices until ownership, scaling, data boundary, or deployment cadence justifies it.
+
+2. Define service contracts before implementation.
+   - Use protobuf IDL as the default contract format.
+   - Service identity is decided before IDL and implementation. For new services, define the globally unique service name first, then IDL, then generated contract artifacts, then business implementation.
+   - Treat IDL and idlgen outputs as a stable boundary between service contracts and business repositories. Prefer centralized IDL ownership plus versioned generated artifacts that business services import. When the platform uses shared IDL and IDLGen repositories, Go, Python, web, mobile, and mini-program consumers must derive from the same contract source; do not fork IDL or generated artifacts per service repository or per language unless it is a deliberate compatibility branch with owner, version, and deprecation plan. Service repository layout (single service, multi-service, API/RPC split) does not change contract ownership.
+   - Protobuf may be the contract source for HTTP as well as RPC. For protobuf-backed or cross-language HTTP gateways, decide separately: contract source (protobuf/OpenAPI), generated route/client artifacts, and wire format (JSON vs binary protobuf). Classify protobuf-backed HTTP using the canonical wire-format gate in `../platform-service-connectivity/references/protobuf-http-contract-signals.md`; do not restate or widen that predicate locally.
+   - API contracts must define request messages, the response envelope, and shared public fields in the shared contract source before implementation, per the canonical `code`/`message`/`data` envelope contract in `../platform-service-connectivity/references/http-response-envelope-contract.md` (adoption, migration, non-JSON surfaces, and anti-patterns live there — do not restate them here).
+   - Internal RPC contracts carry the platform's shared request/response metadata field when the platform defines one; `platform-service-connectivity` owns the canonical base-struct shape and named-framework examples. Do not inherit a framework's reserved envelope/base field number as a cross-product convention (per `references/protobuf-contract-architecture.md`); if a shared metadata field must be part of the protobuf contract (rather than carried via middleware metadata), a new product picks an explicit field and documents it. Within a platform that has already standardized such a field, its field number, name, and message type are compatibility surfaces — do not renumber, rename, or replace them locally.
+   - Internal service data models need the same contract discipline: shared cross-service DTOs, enums, status values, metadata fields, and request/response models live in the contract or generated artifact boundary; service-private domain and persistence models stay inside the owning service and convert at transport/application boundaries.
+   - Separate public HTTP API models from internal RPC models when external clients have different stability needs.
+   - Prefer additive contract evolution: new fields, new methods, new enum values; avoid breaking field numbers or response semantics.
+   - **Inventory the service's exposed surfaces and review new ones at the boundary.** Keep a machine-checkable inventory of every externally reachable surface appropriate to the stack — HTTP routes, RPC services and methods, and async subscriptions (MQ / event / webhook consumers); a surface absent from it should not reach production unreviewed. Drive it from a deterministic discovery profile (routes/subscriptions-as-code, or a generated manifest plus a checked-in snapshot, are two common patterns) with explicit allowlisted carve-outs for framework / health / debug, generated, plugin, and env-conditional surfaces, so the gate flags genuinely new exposure instead of churning on false positives; also flag inventory entries no longer present in code so the snapshot stays trustworthy. Scale enforcement to risk: hard-fail CI for production, externally reachable services; a lighter manifest + review checklist suffices for prototypes, internal scripts, or repos without CI. The inventory proves *every surface was seen and reviewed*, **not** that it is authorized — it is not an authn/authz gate; auth, tenant isolation, and safe exposure remain separate evidence the boundary review must still demand. An unregistered new route or consumer is a *shadow surface* (unreviewed; async consumers are a commonly missed class). Distinct from breaking-change detection (`buf breaking` / `kitex check`, which guards *changes to existing* surfaces) and from agent-contract directory coverage (whether a directory carries an `AGENTS.md`); it guards *new runtime exposure*. `product-rd-workflow`'s spec/repo-contract sync gate owns the human discipline; this is its mechanical enforcement. Mirror any change to this rule in `../python-service-architecture/SKILL.md`.
+   - For finite values that cross service, storage, client, analytics, or generated-code boundaries, architecture must name the canonical owner, shared package or contract location, conversion boundaries, unknown/default behavior, and migration/debt exit path before implementation. If no shared location exists, approve the local-slice fallback and require every `finite-value-debt` marker to carry task reference, owner, deadline, and reason.
+
+3. Design data ownership.
+   - Each service owns its write model and schema.
+   - Cross-service reads should go through RPC/API or explicit read models, not shared table writes.
+   - Use relational DB as source of truth for transactional domain state.
+   - Use GORM as the default MySQL DAL choice for new Go services unless the repo already standardizes or conventionally uses another query layer, or the architecture records a deliberate alternative.
+   - Decide schema, indexes, unique constraints, migration path, and sharding keys before writing DAL code.
+   - Keep GORM, sqlx, and raw SQL behind DAL or repository boundaries; transport and application layers must not build database queries directly.
+   - Use Redis for cache, locks, counters, idempotency windows, rate limits, and ephemeral coordination, not durable truth.
+   - Define Redis key scope, TTL policy, lock lease, rate-limit window, and idempotency lifetime as part of the architecture.
+
+4. Design runtime platform contracts.
+   - Config: local file + dynamic config, with environment/lane separation.
+   - High-risk feature flags and runtime config default fail-closed in production. Local stubs, test defaults, and developer-safe switches must be visibly scoped and cannot become implicit production enablement.
+   - Secrets: never stored in code or config files; resolve through a secret provider.
+   - Service discovery: all internal RPC clients use discovery/resolver abstraction.
+   - Service identity: internal RPC/HTTP trust should be based on workload identity, mTLS, signed service tokens, or an equivalent zero-trust control, not only network location.
+   - Runtime wrappers should provide service identity, registration/discovery, context propagation, trace/log id, metrics, timeout/circuit behavior, and safe debug exposure consistently across HTTP, RPC, and workers.
+   - A capability requirement is not a framework-adoption decision. When a requirement names a capability (service discovery, mTLS, graceful drain), first define its minimal closure — the smallest layer that satisfies it — before adopting a platform framework or runtime component for it, AND name which layer actually closes it: service discovery and mTLS can close at the deployment layer (orchestrator DNS, mesh sidecar), but graceful drain inherently needs runtime behavior (stop accepting, SIGTERM/readiness handling, in-flight completion) — manifests alone leave it explicitly `not closed`, never silently satisfied. Framework adoption is not all-or-nothing: when a framework default conflicts with a service characteristic (e.g. a fixed 30s drain window versus minute-scale streaming requests), split at the boundary — land the part that delivers value on its own (deployment manifests), decide or defer the conflicting part (runtime lifecycle adoption) separately with each deferred capability's closure status recorded, and keep a quotable record of why it was not adopted. Mirror any change to this rule in `../python-service-architecture/SKILL.md`.
+   - Dependency clients: DB, Redis, MQ, object storage, service discovery, secret provider, and external HTTP clients must have explicit timeout, credential, observability, and test-substitution contracts.
+   - Dependency platform layers own SDK lifecycle, credential resolution, readiness, shared timeout policy, close hooks, and test substitution. Feature infrastructure adapters own feature-specific schemas, indexes, query/ranking contracts, object names, event payload meaning, and repair semantics. Do not place feature contracts in the platform layer just because they use a platform client.
+   - Admission control: inbound rate limits, concurrency limits, load shedding, backpressure, and circuit-breaker behavior are part of reliability design.
+   - Release runtime: service metadata, deployment resources, mesh/gateway routing, canary traffic, approval, and rollback are first-class architecture surfaces.
+   - Error contract: define canonical code/message semantics once, then map HTTP, RPC, worker, and dependency errors into it.
+   - Context contract: trace/log id, lane/environment, authorization/resource scope, request deadline, and auth subject must propagate through all sync and async paths.
+   - Observability: logs, metrics, traces, health checks, pprof/debug where safe, and structured request context.
+   - When comparing a new product backend against a mature internal reference, convert the comparison into a platform-capability gap list, not a source-code shopping list.
+     - The recurring maturity checks are: identity/RBAC subject model, external API signature/replay/allowlist boundary, dynamic config with version/cache/watch/rollback, MQ producer/consumer lifecycle with retry/drop/replay visibility, DB transaction and query-safety guardrails, context/error propagation across HTTP/RPC/MQ, and resource/search visibility scope.
+     - A placeholder or README-only package family is not implementation evidence.
+   - Before marking an internal reference package family as placeholder-only, inspect nested git repositories or submodules, non-default local/remote branches, tags, and tree contents with read-only commands. Default-branch scaffolds do not prove the architecture capability is absent.
+   - If the comparison uses internal checkouts, private repositories, local paths, or organization projects, route preservation through `skill-extraction-workflow` or apply the same sanitization gate before landing any artifact: keep only mechanisms, boundaries, and acceptance gates; remove source-identifying domains, paths, repository/module names, people, tickets, and business nouns.
+
+5. Define code generation and ownership boundaries.
+   - Generated code is an output surface, not hand-maintained source.
+   - Keep IDL, generated contracts, HTTP route generation, DB model generation, and Wire/DI generation explicit.
+   - Introducing or migrating any HTTP gateway/framework requires a quotable record in the architecture doc, repo contract, or MR description, with a separately locatable entry for gateway-capability justification, contract source, middleware order, generated artifacts, observability, and tests. Protobuf motivation alone is insufficient evidence unless the same record states a concrete missing capability in the existing framework, why the current extension points cannot satisfy it, and which requirement the new framework satisfies. Adding protobuf-backed HTTP on an unchanged gateway/framework requires the contract-source and wire-format records; expand to generated-artifact, observability, and test records when those surfaces change.
+   - Health checks should be able to prove the boundary: IDL source location, generation command, generated package version, service implementation importing generated contracts, and CI/breaking-change checks. Agent review then judges whether the service layer bypasses the contract or hides domain semantics in transport code.
+   - Document the generation commands in the repo.
+   - Generation commands must be portable and must not contain developer-local absolute paths.
+
+## Architecture Defaults
+
+- One product can start as a modular monolith if service boundaries are unclear; split by data ownership and team/runtime needs, not by noun count.
+- Public API layer should be thin: auth, validation, request/response mapping, orchestration handoff.
+- RPC services should own domain operations and internal contracts.
+- Background workers should own event processing, retries, idempotency, and backfill/repair workflows.
+- A mature Go service usually separates transport/handler, application logic, domain/service orchestration, and infrastructure adapters; dependency injection or provider sets should make those seams visible instead of letting handlers construct DB/MQ/RPC clients directly.
+- Shared libraries are allowed for infrastructure concerns; do not put domain rules in shared packages.
+- Cross-boundary semantic values are an architecture responsibility even when their local representation is small. Architecture decides where finite values such as status, market, region, channel, source, provider, or permission are canonical, who may expose generated transport enums to domain code, and how duplicate constants are retired.
+- Mature reference code is useful only when it exposes a reusable boundary. Prefer extracting framework wrappers, typed clients, context/error contracts, config schemas, transaction helpers, MQ lifecycle helpers, and query-safety checks; discard business nouns, private module layout, and one-off legacy habits.
+- A service should have clear layers: transport, application/service logic, domain logic, infrastructure adapters, generated contracts.
+- Long-running jobs require a first-class runtime model: distributed lock scope, lease time, max execution time, retry policy, idempotency key, and failure visibility.
+- External dependencies require explicit timeout budgets, status-code validation, retry/fallback rules, and clear ownership of degraded behavior.
+- High-risk operations require a resilience contract: fail-closed policy, idempotency strategy, durable status, reconciliation or repair path, trace/request id propagation, user/support explanation surface, and proof that fallback/degradation cannot bypass authorization, tenant/user isolation, quota, audit, or data-retention controls.
+- High-risk context resolution must reject missing tenant, actor, subject, or resource scope instead of falling back to default identities. Durable side effects need atomic audit/outbox evidence or an explicit reconciliation/repair workflow.
+- External dependency bootstrap requires a first-class operability contract: which resources may be created automatically, which existing resources must be validated, which partial failures can be repaired, which operations fail startup, and which timeouts apply to administrative work versus serving requests.
+
+## Reference Loading
+
+- For source provenance, current extraction boundary, and keep/merge/discard decisions, read `references/source-evidence-map.md` when auditing or re-extracting this skill.
+- For architecture decisions and boundaries, read `references/architecture-playbook.md`.
+- For reliability and operability requirements, read `references/ops-checklist.md`.
+- For cross-cutting server contracts, read `references/cross-cutting-concerns.md`.
+- For service scaffolding, generation, DI, config, and test architecture, read `references/service-scaffold.md`.
+- For protobuf/IDL contract design, package boundaries, message/enum/service evolution, and HTTP/RPC mapping, read `references/protobuf-contract-architecture.md`.
+- For secret providers, service discovery, dependency clients, object storage, and controlled concurrency, read `references/dependency-platform.md`.
+- For public API, third-party callbacks, authorization scope isolation, and external integration boundaries, read `references/api-security-boundaries.md`.
+- For HTTP gateway boundaries, generated routes, handler responsibilities, middleware order, and generated HTTP clients, read `references/http-gateway-architecture.md`.
+- For deployment, environment/lane runtime, mesh/gateway traffic, canary, approval, rollback, and launch operations, read `references/release-runtime-readiness.md`.
+- For runtime identity, environment/lane metadata, service discovery, logs, metrics, tracing, and debug exposure, read `references/runtime-observability.md`.
+- For relational data modeling, schema ownership, indexes, sharding, migrations, and generated DAL boundaries, read `references/data-modeling-and-migrations.md`.
+- For Redis cache, locks, counters, rate limiting, task coordination, local cache, and idempotency architecture, read `references/redis-cache-coordination.md`.
+- For import/export, backfill, migration, partitioning, artifact policy, and batch limits, read `references/bulk-workflow-architecture.md`.
+- For durable workflow state, allowed transitions, retry, cancellation, idempotency, and terminal-state policy, read `references/workflow-state-architecture.md`.
+- For MQ topics, consumer groups, event contracts, activation gates, retry/drop policy, and async consumer operations, read `references/mq-consumer-architecture.md`.
+- For event-driven architecture concerns — delivery semantics taxonomy, producer-side patterns, transactional outbox/inbox, idempotency design, partition-key ordering, schema evolution, retry/DLQ/replay strategy, fanout patterns, saga vs choreography, end-to-end "exactly-once" illusion, and Go-specific implementation glue (consumer goroutine + worker pool, outbox poller with `SKIP LOCKED`, error classification, graceful-shutdown order) — read `references/event-driven-architecture.md`. Stack-agnostic core sections mirror the sibling `python-service-architecture/references/event-driven-architecture.md`; maintainers updating those sections must update both files in the same change.
+- For multi-tenant SaaS isolation concerns — isolation-tier decision tree (RLS / schema-per-tenant / DB-per-tenant / region-per-tenant), tenant context as a first-class value, tenant-aware data access with DB-engine enforcement, per-tenant quota and rate limit at every layer, tenant-aware observability with cardinality management, per-tenant lifecycle (provision / suspend / export / delete / retention / archive), per-tenant rollout and feature flags, cross-tenant capability gating, compliance / residency / sovereignty, migration between tiers, and Go-specific implementation glue (tenant on `context.Context`, GORM RLS session variables, connection pool reset, cache key construction, HTTP middleware, message consumer pattern, outbox tenant propagation) — read `references/multi-tenant-isolation.md`. Stack-agnostic core sections mirror the sibling `python-service-architecture/references/multi-tenant-isolation.md`; maintainers updating those sections must update both files in the same change.
+- For data-platform architecture concerns — DB engine choice axis (single-instance OLTP / sharding middleware like Vitess / distributed SQL like TiDB / managed cloud DB), HA topology and failover model, read scaling and replica routing with staleness budget, sharding and resharding strategy, cross-region replication and data residency, backup with tested recovery (RPO/RTO + restore drill), cluster lifecycle (provision / scale / decommission), capacity planning (storage / IOPS / connections / latency / replica lag), fleet-wide schema-migration coordination, connection-pool and proxy topology (PgBouncer / ProxySQL / Vitess gateway), cost and efficiency, and Go-specific implementation glue (`database/sql` driver+pool, replica routing via DSN, migration tooling choice, PgBouncer mode decision, health-check shape) — read `references/data-platform-architecture.md`. Stack-agnostic core sections mirror the sibling `python-service-architecture/references/data-platform-architecture.md`; maintainers updating those sections must update both files in the same change.
+- For audit logs, history records, retention, redaction, and query authorization, read `references/audit-history-architecture.md`.
+- For dynamic config, rules, filters, routing, rollout ratios, and validation policy, read `references/config-rule-routing-architecture.md`.
+- For replay, shadow execution, response comparison, diff retention, and rollout confidence checks, read `references/replay-comparison-architecture.md`.
+- For performance budgets, capacity controls, DB query safety, batch limits, replay load, and launch readiness, read `references/performance-capacity-architecture.md`.
+- For notifications, webhooks, alert delivery, retries, and recipient policy, read `references/notification-architecture.md`.
+- For generated files, reports, PDFs, spreadsheets, object storage, and download artifacts, read `references/artifact-generation-architecture.md`.
+- For error codes, response envelopes, transport mapping, and cross-service error propagation, read `references/error-contract-architecture.md`.
+- For developer CLIs, code generation, generated-file ownership, and reproducible tooling workflows, read `references/developer-tooling-architecture.md`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Go Microservice Architecture"
+  short_description: "Design Go microservice backend systems"
+  default_prompt: "Use $go-microservice-architecture to design a product-agnostic Go backend architecture."

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/api-security-boundaries.md

@@ -0,0 +1,47 @@
+# API Security Boundaries
+
+## Public API Boundary
+
+- Treat public APIs as a separate trust boundary from internal RPC.
+- Authenticate the calling application or user before resolving authorization scope.
+- Keep authentication, authorization, scope resolution, and domain validation as separate steps.
+- Define which paths bypass auth, and keep bypass lists explicit, reviewed, and minimal.
+- Public error responses should be stable; logs should keep the detailed auth failure reason.
+
+## Partner Application Auth
+
+- A partner application model should include:
+  - application id.
+  - secret or public key reference.
+  - allowed source IPs or network policy when applicable.
+  - allowed authorization/resource scope.
+  - integration/source identity.
+  - enable/disable status and rotation metadata.
+- Store secrets in a secret provider or encrypted config, not in code.
+- Support secret rotation with overlapping validity windows when external partners need rollout time.
+- Signatures should include timestamp, nonce or request id, app id, and canonical request data.
+- Choose HMAC or asymmetric signatures for new integrations; avoid weak hash-only signing unless compatibility requires it and compensating controls exist.
+- Reject expired signatures and replayed nonces/request ids.
+
+## Authorization Scope Isolation
+
+- Scope id from the request is an input, not proof of permission.
+- Resolve allowed resource scope from the authenticated app/user.
+- Enforce scope permission before domain logic and again at repository boundaries for sensitive writes when feasible.
+- Include resolved scope id in idempotency keys, cache keys, rate limits, and audit records.
+- Never allow a scope-check bypass flag without a narrow integration reason, explicit config, and audit trail.
+
+## Third-Party Callback Boundary
+
+- Callback endpoints must validate signature/token, timestamp window, event type, payload shape, and required resource identifiers.
+- Callback processing should assume duplicate, delayed, and out-of-order delivery.
+- Use provider event id or a derived idempotency key to deduplicate.
+- Return success only after durable acceptance, or document why the provider should not retry.
+- Put provider verification keys in secret/config providers; do not hardcode callback verification keys in source.
+
+## Audit And Operations
+
+- Log app id, resolved scope id, provider, event id, endpoint, auth result, and canonical error code.
+- Do not log secrets, raw signatures, full tokens, or sensitive payloads.
+- Metrics should separate auth failure, permission failure, validation failure, callback duplicate, callback processing failure, and dependency failure.
+- Admin changes to integration auth data should be auditable and optionally notify an operations sink.

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

@@ -0,0 +1,160 @@
+# Architecture Playbook
+
+## Service Boundary Rules
+
+Create a separate service when at least one is true:
+
+- It owns a distinct transactional data model.
+- It has independent scaling or latency requirements.
+- It needs independent deployment or failure isolation.
+- It is consumed by multiple products or integration surfaces.
+- It has a different compliance, security, or operational boundary.
+
+Do not create a service only because:
+
+- A domain noun exists.
+- A table exists.
+- A team wants a cleaner folder.
+- A future scale concern is speculative.
+
+## Recommended Service Types
+
+### API Gateway / HTTP Service
+
+Responsibilities:
+
+- External HTTP contract.
+- Authentication, authorization, subject/resource context, request validation.
+- DTO mapping between external model and internal commands/queries.
+- Swagger/OpenAPI docs if the API is consumed outside the service team.
+
+Avoid:
+
+- Direct complex SQL.
+- Long-running jobs.
+- Hidden cross-service transactions.
+
+### Internal RPC Service
+
+Responsibilities:
+
+- Core domain operations.
+- Internal protobuf contract.
+- Data ownership and transaction boundary.
+- Calls to other internal services through typed clients.
+
+Avoid:
+
+- Returning raw DB models when the contract should be stable.
+- Sharing write access to owned tables.
+
+### Worker / Consumer Service
+
+Responsibilities:
+
+- Async events, scheduled jobs, retryable side effects.
+- Idempotency and deduplication.
+- Backfill, compensation, repair workflows.
+- Outbox/inbox handling when domain consistency matters.
+
+Avoid:
+
+- Assuming exactly-once delivery from MQ.
+- Treating retries as safe without idempotency keys.
+
+### Shared Package
+
+Appropriate for:
+
+- Logging, tracing, metrics.
+- Config and secret clients.
+- DB/Redis/MQ wrappers.
+- Codegen helpers.
+- Generic data structures and concurrency utilities.
+
+Not appropriate for:
+
+- Product-specific domain rules.
+- Cross-service data model coupling.
+- Hidden network calls behind generic helpers.
+
+## Contract Design
+
+- Use protobuf for current API/RPC contracts.
+- For detailed protobuf package, service, message, enum, annotation, and evolution rules, apply `protobuf-contract-architecture.md`.
+- Design pagination, filtering, sorting, and idempotency from v1 for list and write APIs.
+- Include request context fields only when they are part of the domain contract; transport context should travel via middleware/metadata.
+- Keep transport DTOs, application parameters/results, domain objects, and storage models as separate boundaries when behavior or compatibility is non-trivial.
+- Patch/update contracts need presence semantics, not only zero values.
+- For finite values used across contracts, domain logic, persistence, clients, analytics, or events, architecture owns the semantic source of truth. Decide the canonical owner, shared contract/package location, allowed representations per boundary, parser/canonicalization owner, unknown/default behavior, and rollout order. If a shared location does not yet exist, the architecture decision must approve a local fallback and a consolidation task with owner and deadline; unowned `finite-value-debt` markers are architecture findings.
+- **RPC framework choice: Kitex remains the default; ConnectRPC is the credible 2025-2026 alternative for specific contexts**. Per `connectrpc.com` docs, Connect ships as a single small Go package (single-digit-thousand LOC), built on `net/http` with handlers implementing `http.Handler` and clients wrapping `http.Client` — works with any third-party router, middleware, or server. Supports three protocols (gRPC, gRPC-Web, Connect's own protocol) over both HTTP/1.1 and HTTP/2; any gRPC client in any language can call a Connect server, and Connect clients can call any gRPC server (validated by Google's interop tests). CNCF-incubated as of 2025; production-adopted at CrowdStrike, PlanetScale, Bluesky, Dropbox per `buf.build/blog`. Architecture choice: **choose Connect** when (a) the service hosts a browser-facing API and gRPC-Web is the main use case (Connect collapses gRPC + gRPC-Web + Connect into one server), (b) the service is small and Kitex's framework surface is over-spec'd, (c) the service must interop bidirectionally with multi-language gRPC clients but the team wants to avoid grpc-go's 130k-LOC dependency footprint. **Stay on Kitex** when (a) the team already operates Kitex across many services and the platform observability/middleware/registry contracts are Kitex-native, (b) Thrift IDL (TTHeader / TTHeader Streaming) is in active use alongside protobuf — Connect is protobuf-only, (c) Kitex-specific features (StreamX, FastCodec, generic call) are load-bearing. The two are NOT mutually exclusive: a Connect-based public-edge gateway can fan out to internal Kitex services, but **wire compatibility alone is not interop** — Connect speaks gRPC on the wire when configured for gRPC, and Kitex servers configured with the gRPC meta handler can accept those calls; however, Kitex services in production typically depend on Kitex-specific framework metadata (lane / tenant / caller-identity ctx values propagated via TTHeader or Kitex middleware), and Connect clients do not emit those by default. The fan-out works ONLY when (a) the target Kitex services are configured for the gRPC meta handler (not TTHeader), (b) the Connect-side Go client explicitly attaches the gRPC metadata (`metadata.MD`) that the Kitex service's middleware reads as caller-identity / lane / tenant — typically through a small adapter layer at the Connect-side that pulls fields from the Connect call context and writes them as gRPC headers, (c) any Kitex-specific TTHeader Streaming / generic call / Thrift-only paths stay routed through a Kitex-native edge instead. Plan the adapter layer as a first-class architecture component, not a one-line bridge; otherwise tenant / lane context drops silently at the protocol boundary and downstream services run without isolation.
+
+## Data Design
+
+- MySQL or compatible relational DB is the default domain truth store.
+- Redis is for ephemeral state: cache, lock, counter, limiter, idempotency, job state.
+- MQ is for eventual consistency and async workflows; model delivery as at-least-once.
+- Dynamic config controls rollout, feature gates, thresholds, and routing, not core domain truth.
+- Search stores, document stores, and analytics stores are projections unless explicitly designed as source of truth.
+
+## Dependency Direction
+
+Recommended:
+
+```text
+transport -> application/service -> domain -> infrastructure adapters
+                         |
+                         -> generated clients/contracts
+```
+
+Rules:
+
+- Domain logic should not import HTTP or RPC framework packages.
+- Infrastructure adapters should be behind interfaces when they are complex or externally visible.
+- Generated code may be imported by transport and adapter layers; avoid letting generated DTOs dominate core domain modeling when behavior is complex.
+- How a layer boundary is enforced is itself an architecture decision, with a strength ladder: physical module/package boundary (a violation is a compile or import error), import-architecture lint (the tiering CI gate below), then review convention — in decreasing strength; prefer mechanisms where a violation is a CI error, not a review comment. For a core where a frozen contract must coexist with continuous evolution (a gateway data plane, a billing domain), prefer the physical boundary, and add a deterministic digest/conformance anchor as machine proof that evolution has not touched the frozen surface. Record why the chosen strength is enough (cost versus strength); a weaker tier is a documented tradeoff, not a default. Sibling: `python-service-architecture/references/architecture-playbook.md` ("Layering Depth") carries the same rule for Python; keep the two in sync.
+
+### Functional Core, Imperative Shell (Recommended, Not Mandatory)
+
+- Keep calculation, rule, and state-transition logic in pure functions with no I/O or hidden state; let handlers, repositories, clients, and workers be the thin imperative shell that calls them. The payoff is testability — the pure core unit-tests without mocks, and the shell stays small enough for focused integration tests. Conflating them (domain rules inside a repository method or a worker callback) is the recurring cause of "we cannot test this without a real DB / queue / network."
+- This pure-core *style* is a recommended outcome for I/O-heavy services, **not a mandatory gate**, and not a license to cargo-cult functional-programming idioms into Go — plain functions and structs, not an abstraction tower. Distinct and **not** optional, though: domain invariants must not be hidden inside handlers, repository methods, IO adapters, framework hooks/middleware, or worker/task callbacks — anywhere outside the domain/service layer. That is the dependency-direction rule above, independent of whether you adopt the pure-core style.
+- Sibling: `python-service-architecture/references/architecture-playbook.md` ("Layering Depth — Apply In Moderation") carries the same principle for Python; keep the two in sync.
+
+### Shared Foundation Module Package Tiering
+
+A shared cross-service module (a `common` / foundation / utility library imported by many services) needs stricter internal discipline than a single service: one import cycle or one heavyweight coupling inside it is inherited by every consumer, and a leaf utility cannot be reused once it transitively drags in unrelated packages. Scale the strictness to blast radius — a widely-imported foundation module earns this; a tiny single-consumer helper does not.
+
+- Define and **document** an explicit linear package-tier order in the module's own README/doc. The order `generated value-types -> constants/globals -> generic pure utils -> logging/metrics -> framework/business adapters` is illustrative — each team picks its own — but the written order is the artifact reviewers enforce, and an unwritten "everyone knows the order" rots into cycles. Keep pure helpers in a tier below logging/config so they do not drag observability or runtime config into every consumer.
+- **Earlier tiers must never import later tiers** — the tier list is one-directional and acyclic.
+- **Default to sibling independence within a tier** so each leaf stays independently importable. When one same-tier package genuinely needs another (a real case: a `retry` helper used by an http client, `backoff` used by a queue), that is the signal to extract the shared piece **down into an earlier tier** so it is no longer a sibling — not to copy-paste it and not to add an artificial micro-tier. Reserve strict "no sibling import" for declared leaf packages.
+- **Split generated packages by what they pull in.** Generated pure contract/value types may be imported by any tier; generated clients/server bindings carry transport and runtime deps (gRPC, HTTP) and belong in the adapter tier only — importing them broadly pressures domain code to model around transport shapes, which the Dependency Direction rule above warns against. All generated code is regenerate-only (rebuild via the codegen target, never hand-edit).
+- Gate the invariant in CI rather than relying on review memory. Outright cycles already fail `go build` / `go list ./...` (the compiler forbids import cycles), but that does not catch a legal-but-wrong cross-tier or sibling import — for those use a dedicated import-architecture linter: `depguard` (via golangci-lint) to allow/deny imports per package, or a layer/component checker such as `go-arch-lint` or k8s-style `import-boss`. (`internal/` only blocks imports from outside a parent tree; it does not enforce tier order or sibling independence inside the module.) Treat a new cross-tier or sibling import as an architecture-review item, not a silent merge.
+
+### Adapter / Plugin Family — Shared Core + Thin Bridges Across Repos
+
+When one cross-cutting platform concern (observability, auth/governance, a client-SDK wrapper) must bridge into *many* frameworks or drivers — one governance layer wired into gin / hertz / gRPC / Kitex plus a set of DB, cache, and MQ drivers — design **one shared core that owns the invariants + a thin per-framework bridge adapter each**, not a full re-implementation per adapter. Each adapter owns only framework-specific wiring (how *this* framework exposes middleware/hooks/interceptors); the invariants (a **risk-appropriate failure policy** — fail-open for genuinely optional telemetry, fail-closed for auth / governance / data-integrity / audit-and-compliance; classify each concern explicitly, an audit / compliance / security signal is a control, not "observability"; but "fail-closed" for audit/compliance means **durable local capture (outbox) + bounded degraded mode**, hard-blocking only the specific regulated operation (a mutation, sensitive read, export, or privileged access — whatever the compliance scope covers) — not turning the audit exporter into a synchronous production kill switch for unrelated traffic — context binding, lifecycle/cleanup, propagation, canonical schema and error model) live once in the core and are delegated to. This is Ports-and-Adapters applied to a *fleet of transports*, distinct from the intra-module tiering above — here the adapters are typically separate repos.
+
+- **The core exposes only the seam + invariants; concrete adapters live outside it — dependency-neutral, but NOT semantics-neutral.** The shared core defines the extension interface/seam and owns the invariants — a *concrete* framework/driver adapter (a specific ORM, HTTP framework, or MQ-client binding) must NOT live inside the core package: co-locating it pulls that framework's heavyweight deps into every core consumer and inverts the dependency direction (adapters import the core, never the reverse; the core stays adapter-agnostic). Keep the seam neutral to the concrete *dependency* but **explicit about semantics** — it names the required transaction / commit / ack / retry / cancel / failure guarantees the invariants rely on (an outbox/audit control needs real commit-and-ack semantics, not a seam that hides them) plus an adapter conformance suite; a driver that cannot implement a required guarantee is rejected, not silently flattened to a lowest common denominator. A library swap is a **thin shim only if the replacement preserves that declared capability matrix** (session scoping, driver connection reset, broker nack/backpressure, official middleware ordering); dropping a real semantic is an architecture change, not a shim. And "outside the core" ≠ "ship nothing" — provide at least one official/reference adapter + bootstrap for **every mandatory fail-closed control** (auth / governance / data-integrity / audit / compliance) and for baseline instrumentation, so services don't each hand-roll and diverge from — or bypass — the invariants. Catching a concrete adapter that slipped into the core late means ripping it back out — a costly reversal, not a tidy refactor.
+- **Repeated-fix-across-siblings is the extract-the-abstraction trigger — but fix the live bug first.** The same bug fixed in a third sibling adapter, or sustained "harden X" churn across the family, is a missing seam, not N unlucky bugs. Backport/mitigate the incident across the existing adapters **first**; the core extraction is the durable follow-up, not a reason to leave the Nth adapter broken. (An adapter that duplicated the concern and later delegates to a shared helper typically collapses to a fraction of its size — that deleted duplication was the tax on the missing abstraction.)
+- **Design a seam early, but keep it minimal — and split the stable API from the core impl.** "Extract down a tier" cannot reach across import-pinned repos, so a *minimal, explicitly-versioned* SPI/compat seam (provider/runtime injection, no core internals or process-global set-once state) should exist before out-of-repo adapters ship — but do NOT freeze a broad abstraction from one adapter; stabilize the wider shared-core shape only after real sibling evidence (rule of three), or you build a version-lock chokepoint. Ship the stable **API/contract as a tiny package separate from the core implementation**, so a core-impl or canonical-schema change does not force-lock every independently-pinned adapter; govern it with semver compatibility windows, an adapter↔core version matrix, and cross-adapter contract tests. Minimal-early, not big-early — a *wrong* shared abstraction couples the whole family to a bad decision and is harder to undo than duplication.
+- **Reuse the framework's official instrumentation for wire/transport mechanics — through explicit injection, not its globals.** Official instrumentation often uses process-global providers / auto-registration; wrap it behind an explicitly injected provider/runtime and contract-test that no global set-once state leaks, or you get cross-service exporter/context leakage and double instrumentation. If a framework's official instrumentation *only* exposes a global / set-once API, a documented global-only exception is fine — confined to a single-owner idempotent bootstrap with teardown/test isolation and no custom wire semantics; don't fork or hand-roll transport instrumentation just to avoid the global. Keep platform governance semantics in the shared core so they do not fork per framework.
+
+Sibling: `python-service-architecture/references/architecture-playbook.md` carries the same adapter-family principle; keep the two in sync.
+
+## Cross-Layer Contract Integrity
+
+- For any value that must travel across transport, application, domain, infrastructure, async event, or generated-code boundaries, name its source, destination, allowed transformations, and validation owner.
+- Required parameters should be validated at the boundary and re-checked before irreversible side effects when they cross async, retry, or persistence boundaries.
+- Do not rely on hidden globals, mutable maps, or stringly payloads for critical parameters; use typed request/result structs or generated contracts.
+- Branches behind one public endpoint or command should return the same envelope shape and preserve required workflow steps unless a documented product decision says otherwise.
+- Special-case branches need the same acceptance checks as the main path: auth, validation, idempotency, persistence, observability, error mapping, and regression coverage.
+- When modifying a cross-layer parameter, update contract docs, generated code, adapters, tests, and observability together.
+- When modifying a cross-boundary finite value, update enum/string conversion, storage compatibility, client mappings, analytics dimensions, event payloads, boundary conversion tests, and every tracked `finite-value-debt` marker together or record the remaining owner/deadline explicitly.
+
+## Architecture Change Checklist
+
+- Identify affected contracts, data shapes, state transitions, dependency calls, and generated artifacts before implementation.
+- Check backward compatibility for existing clients, stored data, queued messages, cached values, and replay/backfill inputs.
+- Define rollout and rollback behavior before migrating data or changing public behavior.
+- Add verification for both the new path and historical/compatibility path when old data or old messages may still exist.
+- Confirm no branch skips a required step such as validation, authorization, idempotency, persistence, event publication, or audit logging.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/artifact-generation-architecture.md

@@ -0,0 +1,37 @@
+# Artifact Generation Architecture
+
+Use this when designing generated spreadsheets, PDFs, CSVs, reports, exports, or downloadable files.
+
+## Contract
+
+- Treat generated files as artifacts with owner, type, source query, version, generation time, retention, access control, and size limit.
+- Large or slow artifacts should be generated by jobs rather than request handlers.
+- Define output formats, templates, fonts/assets, localization, and schema/version compatibility before implementation.
+- Generated artifacts must apply the same authorization and resource-scope filters as the underlying read path.
+- Decide whether artifacts are regenerated, cached, or immutable after creation.
+
+## Storage
+
+- Prefer object storage for generated files and store only object keys or short-lived signed references in relational records.
+- Artifact keys should be deterministic enough for traceability but should not expose private data.
+- Define cleanup policy for source files, temporary files, and generated outputs.
+- Local filesystem output is acceptable for tests and CLI tools, not server runtime durability.
+
+## Quality Checks
+
+- Validate that generated files open in common clients and preserve expected rows/pages.
+- Define behavior for empty datasets, partial data, oversized output, unsupported characters, missing fonts/assets, and upload failure.
+
+## Server-Side Document Rendering
+
+When the artifact is a print-quality document (PDF, image batches, report packets, certificates, structured forms) rendered server-side from rich content (HTML + math + embedded media):
+
+- **Print-vs-design DPI separation is explicit constants AND coordinate-domain-named**: declare `CSS_LAYOUT_PX_PER_INCH` (typical 96, the browser CSS px coordinate space the renderer lays out in), `PDF_POINTS_PER_INCH` (constant 72, the PDF coordinate space points map into), `OUTPUT_RASTER_DPI` (typical 300, the target raster density on final output), and the page dimension constants in mm. Name the coordinate domain on each constant explicitly — `LAYOUT_DPI` vs `PRINT_DPI` alone is the classic footgun: a renderer that computes browser-layout pixels with 72 thinking it's "print dpi" produces a half-size layout before rasterizing at 300 DPI, and the bug only appears on paper. Compute pixel dimensions from these named constants, not hand-tuned literals; document one conversion table for the three coordinate spaces in the renderer.
+- **Font embedding is part of the deployment artifact, not "system font"**: for non-ASCII typesetting (CJK, Cyrillic, Devanagari, IPA) the renderer ships the chosen font files (typically variable fonts to avoid weight/width explosion) alongside the binary. Relying on the host OS's font set means tests pass on dev-machines that happen to have the font installed and renders fall back to a glyph-substitution box in production. Architecture names the font set, the license, and the cache-busting strategy for font upgrades.
+- **Math / formula typesetting is configured once at the service**, not per-request: server-side MathJax / KaTeX is loaded once at module init with the explicit package set (mhchem, extpfeil, siunitx, unicode, boldsymbol — list only those needed), the explicit macro set (degree, parallel, unit aliases, project-specific shorthand), and inline-vs-display delimiter pairs. Per-request math config is a P1 latency surface: the engine warmup is slow and serializing it across requests serializes the renderer.
+- **Batch rendering chunks with per-chunk concurrency**: when the request asks for N items rendered (e.g. 200 question images, a paper sheet with M questions), the handler splits into chunks (typical: low double-digits) and `Promise.all` within the chunk; chunks run sequentially. Naive `Promise.all(allItems.map(render))` peaks heap to N parallel rendering contexts and OOMs the renderer. Naive sequential single-item loops waste cores. The chunk size is a function of the per-render memory cost, not a guessed magic number.
+- **Output goes direct to object storage from the renderer**, not via local FS: write the rendered buffer to the configured bucket key in the same handler; emit `{key, format, dimensions, density, quality}` as the response. Local FS as a staging layer fails on container restart and complicates horizontal scale-out. Local FS is acceptable only for unit tests and CLI tools.
+- **Credentials for the upload come from the platform credential surface, scoped to the upload operation**: object-storage access uses the platform's STS / role-broker per the full contract in `platform-release-engineering/references/secret-and-config-management.md` Pattern C-adjacent — Cloud Session Token Brokering (caller authn/authz before mint, full credential-scope cache key, refresh-ahead-of-expiry, single-flight refresh, fail-closed on STS failure, per-issuance audit). The renderer's credential is scoped narrowly: `(tenant, bucket, key-prefix, put-only)` — not a broad "renderer can write any bucket" role; a renderer role with broad write surface is a privilege-escalation pivot through any RCE in the renderer. A raw `accessKeyId / accessKeySecret` pair in config is the anti-pattern this replaces. Single static bucket name passed via env is acceptable when the bucket is the same for the whole tenancy; multi-tenant artifacts need a per-tenant bucket / prefix scheme.
+- **Missing-config fails closed, not config-or-empty**: `bucket = config.get('TOS_BUCKET') ?? ''` silently uploads to bucket "" (which most SDKs accept as "default" or "first bucket the credential can see") instead of failing fast. Required config is asserted at startup; the renderer refuses to serve traffic when any required value is missing.
+- **Snake-case vs camel-case at the consumer boundary** applies ONLY to non-IDL JSON endpoints: when the renderer is exposed via a hand-written controller that returns plain JSON to a FE caller and the contract is snake_case while the service uses camelCase internally, the conversion lives at the controller response. For endpoints that ARE defined by an authoritative IDL (proto / OpenAPI) and consumed via generated clients, the casing comes from the IDL — applying a blanket `snakeDumpResultCase` at the controller desyncs server output from the generated client and is a contract violation (see `http-gateway-architecture.md` Generated HTTP Client Policy and `protobuf-contract-architecture.md` Front-End Consumer Contract). The rule: one casing convention per endpoint surface, decided by whichever side owns the authoritative contract; never apply blanket case-conversion to a generated-client endpoint.
+- **Anti-pattern observed**: a hardcoded vendor / bucket URL in the renderer's source (for example, `<project-dev-vendor-bucket-url>/...`) bakes the project's identity into the deployable artifact, leaks the bucket address into anyone who decompiles the binary or reads the source, and breaks every cross-region / cross-tenant deployment. Asset URLs are config inputs, never literals.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/audit-history-architecture.md

@@ -0,0 +1,29 @@
+# Audit And History Architecture
+
+Use this when designing audit logs, resource history, activity records, or change tracking.
+
+## Audit Boundary
+
+- Decide which operations require durable audit and which can use best-effort activity logs.
+- Define actor identity, service identity, resource scope, resource id, operation name, result, timestamp, trace id, and canonical error fields.
+- Keep end user, client application, service caller, and operator identity separate.
+- Use stable operation names rather than function names that change during refactors.
+- Define retention, privacy, redaction, query authorization, export, and deletion policy.
+
+## Data Shape
+
+- Store selective before/after summaries or field-level diffs when needed; do not store raw secrets, tokens, passwords, signatures, or unrelated payloads.
+- Serialize request parameters and result data through redaction helpers.
+- Prefer append-only audit records. Corrections should be new records unless a legal deletion policy requires removal.
+- For event-derived history, define lag, rebuild, reconciliation, and source event retention.
+
+## Write Path
+
+- Critical audit should be in the same transaction or outbox as the state change when correctness depends on it.
+- Best-effort audit is acceptable only when explicitly non-critical and observable through logs or metrics on write failure.
+- Async audit pipelines need bounded queues, retry policy, backpressure or drop policy, and shutdown flush.
+
+## Query Path
+
+- Query APIs need resource-scope authorization, pagination, time range filters, and redaction on read.
+- High-volume audit stores need partitioning or retention windows before launch.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/bulk-workflow-architecture.md

@@ -0,0 +1,33 @@
+# Bulk Workflow Architecture
+
+Use this when designing import, export, backfill, migration, reconciliation, or other large batch workflows.
+
+For durable status, allowed transitions, retry, cancellation, and idempotency rules, use `workflow-state-architecture.md` as the canonical contract. This file covers only the bulk-workflow concerns layered on top of that contract.
+
+## Workflow Model
+
+- Model long-running work as a durable job with actor, resource scope, source artifact, status, progress, total count, success count, failed count, error artifact, idempotency key, and timestamps.
+- Separate validation, enrichment, commit, report generation, cleanup, and notification phases.
+- Decide whether row-level errors produce partial success or fail the whole job before implementation starts.
+- Use async processing when work can exceed request deadlines; synchronous APIs should create, inspect, cancel, or download jobs.
+- Define maximum file size, row count, slice count, worker concurrency, and artifact retention before implementation.
+
+## Partitioning And Coordination
+
+- Large jobs should be partitioned by stable slice index, id window, cursor, or object part.
+- Each slice needs a stable identity, ownership scope, retry limit, and per-slice progress.
+- Finalization should run once after all slices reach terminal state.
+- Cross-slice aggregation should use durable counters or transactional finalization, not in-memory state.
+
+## Artifact Policy
+
+- Source files, generated exports, and error reports need ownership, retention, size limit, access control, and cleanup policy.
+- Error artifacts should preserve enough context for repair without exposing secrets or unrelated records.
+- Store object keys or short-lived signed references; avoid storing large binary artifacts in relational rows.
+- Exports must apply the same authorization and resource-scope filters as read APIs.
+
+## Acceptance Checks
+
+- The design states maximum file size, maximum row count, concurrency limit, timeout budget, retry limit, and retention.
+- Error report generation failure has a defined terminal outcome.
+- Job status is inspectable without reading object storage or worker logs.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/config-rule-routing-architecture.md

@@ -0,0 +1,34 @@
+# Config Rule Routing Architecture
+
+Use this when designing dynamic config, rule evaluation, request routing, rollout ratios, filters, or controlled execution.
+
+## Contract
+
+- Define a typed config schema with version, enabled flag, include/exclude scopes, rules, priority, ratio, target, and metadata.
+- Validate config before activation: required fields, enum values, regex syntax, ratio bounds, total ratio limits, timeout limits, and unknown target behavior.
+- Keep rule input fields explicit. Avoid reading arbitrary context keys without a documented field registry.
+- Support nested condition groups only when the product needs them; otherwise prefer a flat rule list.
+- Define operator semantics once: equality, inequality, numeric comparison, containment, regex, set membership, and missing-field behavior.
+
+## Activation
+
+- Config refresh should be atomic: load, parse, validate, then swap the active snapshot.
+- On config load or parse failure, use the last valid snapshot or a documented safe default.
+- Version changes should be observable through logs and metrics.
+- Concurrency must be safe for high-read, low-write access patterns.
+
+## Routing Policy
+
+- Priority ordering must be deterministic, including tie-break behavior.
+- Ratio rollout should be stable when users or resources need sticky assignment; random sampling is acceptable only for stateless sampling.
+- Disabled rules should be skipped without side effects.
+- Unknown targets should fail closed or route to an explicitly approved default.
+- Every route decision should expose rule id, config version, selected target, and skip reason where useful.
+
+## Dynamic Config Key Namespace
+
+- For etcd-backed or config-center dynamic config, architecture declares the key namespace shape: `/{service}/{namespace}/{key}` is the common pattern, with `service` identifying the owning platform service identifier, `namespace` separating logical config domains (e.g. `db_shard`, `rate_limit`, `feature_flag`), and the leaf naming the entity. Raw etcd keys never leak into application code.
+- Endpoint discovery for the config backend itself: when etcd endpoints come from another service-discovery system, architecture sets the refresh cadence (10-30 s is typical) so endpoint churn does not amplify into config hot-path latency. Refresh happens lazily on the next operation, not on a tight loop.
+- Failure-mode allocation per responsibility: key-not-found, decode error, and remote/transient error each route to a different product behavior. Architecture documents which keys fall back to last-known-good cache (feature flags, rate budget), which fail closed (auth policy, billing rules), and which fail open (telemetry knobs).
+- Watch callbacks run in their own goroutines and must recover from panic, update local cache atomically, and shut down cleanly on parent-ctx cancellation. A silently-dead watcher is harder to detect than a missing one; surface watcher health as a metric.
+- Watch reconnect must preserve monotonicity: persist the last-observed revision/version, resume from `last_revision + 1` after disconnect, and trigger a full resync (re-read all subscribed keys) on `ErrCompacted` or other history-loss errors. Use jittered exponential backoff on reconnect to avoid stampede. Track watcher staleness as a metric and fail readiness probes when a critical-config watcher has been stale beyond a documented threshold.