@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: python-service-architecture
+description: Python 后端架构 / FastAPI 项目结构 / Celery worker 拆分 / Python 微服务边界 / 服务分层重构 / Python 服务重构 → design or review Python backend, service, worker, package, API contract, data ownership, reliability, async/job, and runtime boundaries. Prefer this for architecture/boundary decisions; use python-service-dev for implementation work and localized refactor (某文件/某类); multi-stage / cross-module refactor delivery re-enters product-rd-workflow.
+---
+
+# Python Service Architecture
+
+Use this for new product/server architecture work in Python. For new backend products, decide the service boundary from ownership, data source of truth, runtime isolation, scaling, release cadence, and rollback needs before choosing microservice, modular monolith, worker, script, or package shape. This skill distills proven Python backend, AI-service hosting, worker, package, and data-access patterns, but must not assume any existing repository, product domain, package path, service identifier, database, or legacy service layout.
+
+## Skill Routing
+
+- Use this skill for Python architecture decisions, microservice decomposition, service decomposition, API contract shape, storage ownership, async execution, worker/job design, observability, reliability, release readiness, and platform boundaries.
+- Use `python-service-dev` when the user asks to implement, modify, scaffold, generate Python code, or apply a diagnosis/test strategy in Python code. A localized refactor (某文件/某类) also belongs to `python-service-dev`; only service-wide layering/boundary redesign stays here, and a multi-stage refactor delivery must re-enter `product-rd-workflow`. For root-cause debugging use `defect-diagnosis` first; for test-layer choice use `testing-strategy` first.
+- Use `product-rd-workflow` first when the request spans product shaping, architecture, implementation, review, release, and learning loops.
+- Use `defect-diagnosis` first when the task is to reproduce, isolate, instrument, fix, verify, or root-cause a backend defect, regression, repeated failure, review finding, or failing test.
+- Use `testing-strategy` when the main question is which unit, integration, contract, or E2E layer should prove behavior; then return here for Python architecture impact.
+- Use `llm-inference-integration` for inference, RAG, prompt, model-routing, evaluation, replay, token-cost, and batch-inference design. This skill only owns the Python service boundary that hosts or calls those capabilities.
+- Use `go-microservice-architecture` for Go services. Do not load Go skill rules for Python 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 (what fields the handler emits, what middleware the framework attaches, what health endpoints exist); the cross-cutting evidence stack belongs there.
+- Use `platform-service-connectivity` for service mesh, service discovery, mTLS, multi-environment lane routing, retry/timeout/circuit-breaker policy, and framework client/server middleware for cross-service hops. This skill defines what the service exposes (health endpoints, ctx propagation, error-code conformance); routing/policy lives 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 (what the service consumes from the secret store and config center); release flow lives there.
+- Use codebase-specific skills only when the task is explicitly about an existing repository.
+- When changing an architecture rule that implementation must obey, name the downstream execution owner before landing: `python-service-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 Python, 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 Python service boundaries or fallback behavior.
+
+## Platform Boundary
+
+This skill owns the **service-internal** view: handler shape, contracts, data ownership, async model, error map, worker design, package layout. It exposes a fixed contract to the platform layer:
+
+| Service exposes (this skill owns) | Platform owns (route to platform-* skill) |
+|---|---|
+| `/healthz`, `/readyz`, `/ping` endpoints with correct semantics | How orchestrator probes them; registry healthcheck contract |
+| Python equivalent of correlation propagation (`contextvars`, FastAPI `Request.state`, Starlette state, framework request scope) carrying request id / correlation id / trace context / lane / deadline | How those fields propagate across mesh / queue boundaries |
+| Logger interface that takes ctx and emits structured JSON matching the platform field schema | Log shipping pipeline, search index |
+| Use of the framework default app factory with the mandatory middleware chain attached | What that middleware chain must include — see `platform-observability` and `platform-service-connectivity` |
+| Stable error-code enum + mapping table (framework error → code → HTTP/RPC status) | Cross-service error contract evolution |
+| Graceful shutdown: deregister from SD → drain in-flight → close clients → exit | Orchestrator pre-stop hook and termination grace period |
+| Secret consumption via the platform secret-store SDK or injected env at boot | Secret rotation pipeline, distribution mechanism |
+| Static config in per-environment files bundled in the image; dynamic config via config-center SDK | Config-center deployment, audit, rollout |
+| Trace span creation around handler + outbound calls (auto via OTel instrumentation) | Trace backend, sampling policy, retention |
+| Metric emission via framework metrics client (baseline labels attached automatically) | Metric storage, cardinality budget, SLI definition |
+
+A Python service author works against this contract. Platform-level questions ("which collector?", "which mesh weight?", "which canary check?") route to the platform skills. Cross-language uniformity of this contract is what makes the platform layer reusable.
+
+## Generalization Discipline
+
+- Keep only reusable Python-side mechanics: framework boundaries, typed contracts, dependency assembly, storage ownership, migrations, async/concurrency model, workers, config, reliability, observability, security boundaries, packaging, and delivery workflow.
+- Do not copy product nouns, service names, package paths, provider names, environment names, IDs, dashboards, callbacks, or organization-specific operating habits into the architecture.
+- Convert domain-specific source patterns into reusable mechanics: router shape, schema evolution, repository/unit-of-work boundary, transaction ownership, cache key strategy, idempotency, job lease, config validation, trace context, or test contract.
+- When patterns conflict, choose deliberately:
+  - Prefer explicit Pydantic/OpenAPI schemas over untyped dictionaries for public API contracts.
+  - Prefer SQLAlchemy 2.x plus Alembic for new Python relational services unless the service records a deliberate alternative data-access choice; use framework ORM ownership when the chosen framework owns that boundary.
+  - Prefer relational durable truth over Redis-only truth for auditable state.
+  - Prefer explicit dependency assembly over import-time singletons and hidden global clients.
+  - Prefer async only when the call chain and libraries are truly non-blocking; isolate blocking CPU/GPU or sync I/O through workers, process pools, or `asyncio.to_thread`.
+  - 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.
+
+## 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 Python service boundary.
+   - Identify whether the product needs an HTTP API, internal API, microservice, worker, scheduled job, batch pipeline, SDK/package, or AI-service host.
+   - Classify Python code before reusing a pattern: deployable service, SDK/shared package, application service, experiment/benchmark, generated artifact, model/runtime artifact, or third-party/vendor code. Only deployable/current service code should define service defaults.
+   - 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.
+   - Use a microservice boundary only when ownership, scaling, data ownership, runtime isolation, deployment cadence, or rollback needs justify a separate deployable unit; then identify each service's owner, data source of truth, API/OpenAPI or gRPC contract, runtime dependencies, deployment unit, and rollback boundary.
+   - Use a modular monolith, script, worker-only service, or package when service boundaries are unclear, the product is too small to justify separate deployable services, the active repository is already that shape and the task is local to it, or the user explicitly requests that shape.
+   - Choose FastAPI, Flask, Django, or another framework by request model, admin needs, async needs, ecosystem constraints, and team familiarity.
+
+2. Define contracts before implementation.
+   - Use Pydantic/OpenAPI as the default HTTP contract surface.
+   - Use Django forms/serializers or framework-native schemas when the repository standard already exists.
+   - Use protobuf/gRPC for RPC only when the integration explicitly requires it; protobuf as an HTTP contract source is governed separately by this ordered decision:
+     1. Default to Pydantic/OpenAPI as the Python HTTP contract source.
+     2. Use protobuf as the HTTP contract source only when that default is not sufficient for a documented cross-language consumer set.
+     3. Before approving protobuf HTTP, record owner, consumers, generated artifacts, compatibility policy, and migration or deprecation path.
+     4. Record framework binding (FastAPI/Flask/Django) and wire format (JSON vs binary protobuf).
+     5. Define the globally unique service name before IDL and implementation, keep IDL ownership separate from business implementation, and consume versioned generated artifacts.
+     6. When the platform uses shared IDL and IDLGen repositories, consume the generated Python artifacts from the same contract source as Go and client-side consumers; do not copy IDL into a service repo, handwrite protobuf types, or treat generated clients as service-local source.
+     7. Satisfying a protobuf/cross-language trigger does not substitute for the owner, consumer, artifact, compatibility, migration, framework-binding, and wire-format records above; all are required before approval.
+   - Classify protobuf-backed HTTP using `../platform-service-connectivity/references/protobuf-http-contract-signals.md`; that reference owns the in-scope gate and the routine JSON/OpenAPI carve-out. In Python architecture, once the gate is in scope, record contract source, framework binding, owner, consumers, generated artifact package/version, compatibility policy, migration/deprecation path, and JSON vs binary protobuf wire format. Missing in-scope records block approval; out-of-scope routine Pydantic/OpenAPI changes use the normal contract-definition record.
+   - API contracts must define request schemas, 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 `../go-microservice-architecture/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 route/application boundaries.
+   - Prefer additive contract evolution: new fields, new endpoints, new enum values, and stable 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 (FastAPI / Flask / Django), any RPC services and methods, and async subscriptions (Celery / queue / 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 OpenAPI/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 (schema / contract diff on *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 `../go-microservice-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.
+   - A service owns its write model and migration path.
+   - Use SQLAlchemy 2.x plus Alembic by default for new relational services unless the service records a deliberate alternative data-access choice.
+   - For new MySQL async services, prefer `asyncmy`; `aiomysql` is allowed when the service deliberately chooses it or already uses it. Do not replace an existing working `aiomysql` driver solely to comply with the default. Do not mix MySQL async drivers inside one service boundary.
+   - For MySQL sync services, prefer `mysqlclient`; `PyMySQL` is allowed when portability or existing service convention requires it.
+   - Use Django ORM and Django migrations when the service is a Django service. Use SQLModel when the architecture deliberately chooses the Pydantic plus SQLAlchemy model shape or the service already uses SQLModel; do not replace existing SQLModel solely to comply with the default.
+   - Another deliberately chosen or existing ORM/query layer is allowed when kept consistent inside the service boundary and recorded as the service data-access choice.
+   - Treat Alembic or framework migrations as reviewable source artifacts; autogeneration is a draft, not a substitute for migration design.
+   - Use Redis for cache, locks, counters, idempotency windows, rate limits, and ephemeral coordination, not durable truth.
+
+4. Design runtime and dependency contracts.
+   - Config should be typed and environment-specific, preferably through Pydantic Settings or framework-equivalent config schemas.
+   - 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 must not live in code, config examples, tests, or generated clients.
+   - Dependency clients for DB, Redis, MQ, object storage, service discovery, external HTTP, and inference calls must have explicit timeout, credential, observability, and test-substitution contracts.
+   - Separate serving-path timeout budgets from admin, migration, bootstrap, repair, and batch-operation timeouts.
+   - Service registration or model-serving registration should happen only after readiness checks pass; registered metadata should identify environment, version, routing/lane, and capability. Shutdown, polling, and background registration loops need bounded timeout and explicit exit semantics.
+   - Readiness must be externally observable for operations. Internal SDK or serving-framework status is useful, but production services still need a clear health/readiness surface, startup failure behavior, and unregister/shutdown semantics.
+   - 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 `../go-microservice-architecture/SKILL.md`.
+   - Define error mapping once, then map framework, validation, ORM, worker, HTTP client, and dependency errors into it.
+   - 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, queue producer/consumer lifecycle with retry/drop/replay visibility, DB transaction and query-safety guardrails, context/error propagation across HTTP/RPC/queue, 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 observability, quality, and release readiness.
+   - Logs, metrics, traces, health/readiness endpoints, request IDs, and safe debug exposure are architecture surfaces.
+   - Package and runtime choices must be reproducible: lockfile, dependency groups, import mode, lint/type/test commands, and container entrypoint.
+   - Define deployment resources, process model, worker concurrency, canary/smoke checks, rollback, and migration order before launch.
+
+## Architecture Defaults
+
+- Do not split Python backends into microservices until ownership, scaling, data ownership, runtime isolation, deployment cadence, or rollback needs justify separate deployable units. When microservices are justified, each service has an owner, API/OpenAPI or gRPC contract, data ownership, inter-service auth, timeout/retry policy, service discovery or routing, observability, deployment unit, and rollback boundary.
+- A modular monolith, script, worker-only service, or package is valid when boundaries are unclear, the product is small, the existing repository shape fits, or the user requests simplification. Record the reason when choosing it.
+- Keep FastAPI/Flask route handlers thin: auth, validation, request/response mapping, and orchestration handoff.
+- In Django, keep framework conventions where they improve clarity, but do not hide domain rules in views, serializers, or settings side effects.
+- Use explicit app factories or startup assembly for clients and middleware; avoid doing network I/O at import time.
+- Avoid hard-coded registry endpoints, provider URLs, secrets, and fallback domains in code. Route them through typed config and fail closed when required production config is missing.
+- Use SQLAlchemy 2.x-style sessions, unit-of-work boundaries, or framework transactions as the data consistency boundary.
+- Long-running jobs require idempotency, checkpoint/restart behavior, failure visibility, and a max execution/concurrency model.
+- Mature reference code is useful only when it exposes a reusable boundary. Prefer extracting framework wrappers, typed clients, context/error contracts, config schemas, unit-of-work or transaction helpers, queue lifecycle helpers, and query-safety checks; discard business nouns, private module layout, and one-off legacy habits.
+- 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.
+- 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.
+- Python AI/RAG service hosts must separate service wiring from inference design. Model routing, prompt policy, retrieval design, evaluation, and replay belong to `llm-inference-integration`.
+- Generated API clients and generated protobuf code are output surfaces; do not hand-edit them. Generated migrations are drafts that require human review before landing.
+
+## 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 framework choice, app boundaries, ASGI/WSGI, and route ownership, read `references/web-framework-boundaries.md`.
+- For Pydantic, OpenAPI, schema evolution, and protobuf/gRPC exceptions, read `references/api-contract-and-schema.md`.
+- For public API, partner app auth, signature verification, callback trust boundaries, authorization scope, and audit/operations security, read `references/api-security-boundaries.md`.
+- For SQLAlchemy/Django ORM, migrations, transactions, and data ownership, read `references/data-modeling-and-migrations.md`.
+- For asyncio, blocking work, GIL, and concurrency design, read `references/async-execution-model.md`.
+- For Celery/RQ/arq, scheduled jobs, worker leases, and batch/restart policy, read `references/background-jobs-and-scheduling.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 Python-specific implementation glue (asyncio consumer + bounded queue, SQLAlchemy outbox poller with `SKIP LOCKED`, exception hierarchy, sync-vs-async consumer choice, graceful-shutdown order) — read `references/event-driven-architecture.md`. Stack-agnostic core sections mirror the sibling `go-microservice-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 Python-specific implementation glue (tenant on `contextvars.ContextVar`, FastAPI dependency + Starlette middleware, SQLAlchemy RLS session variables, connection pool reset via pool reset event, cache key helper, async task spawning with `copy_context`, async message consumer pattern, outbox tenant propagation) — read `references/multi-tenant-isolation.md`. Stack-agnostic core sections mirror the sibling `go-microservice-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 Python-specific implementation glue (sync-vs-async driver choice, SQLAlchemy 2.x async with asyncpg/asyncmy, Alembic migrations, PgBouncer prepared-statement caveat, health-check FastAPI dependency, connection-storm mitigation) — read `references/data-platform-architecture.md`. Stack-agnostic core sections mirror the sibling `go-microservice-architecture/references/data-platform-architecture.md`; maintainers updating those sections must update both files in the same change.
+- For Redis cache, locks, counters, rate limiting, and idempotency architecture, read `references/redis-cache-coordination.md`.
+- For typed settings, secrets, dependency clients, and runtime config, read `references/config-secrets-runtime.md`.
+- For logs, metrics, traces, health checks, and debug exposure, read `references/observability-and-ops.md`.
+- For timeouts, retries, canonical errors, validation, and failure policy, read `references/reliability-and-error-contract.md`.
+- For Python service boundaries around LLM/RAG/inference systems, read `references/ai-service-integration-boundaries.md`.
+- For uv/poetry/pip, lockfiles, dependency groups, containers, process model, and launch checks, read `references/packaging-runtime-readiness.md`.
+- For import/export, backfill, data repair, batch jobs, and pipeline boundaries, read `references/batch-and-pipeline-architecture.md`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Python Service Architecture"
+  short_description: "Design Python backend and service architectures"
+  default_prompt: "Use $python-service-architecture to design a product-agnostic Python backend architecture and choose service boundaries from ownership, data, runtime, scale, release, and rollback evidence."

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/ai-service-integration-boundaries.md

@@ -0,0 +1,57 @@
+# AI Service Integration Boundaries
+
+Use this for Python service architecture around LLM, RAG, model inference, embedding, OCR, vision, or ML calls.
+
+## Scope Boundary
+
+- This skill owns Python service hosting, API boundaries, worker execution, dependency clients, timeouts, streaming endpoints, and persistence around inference.
+- `llm-inference-integration` owns prompt design, model routing, retrieval design, evaluation, replay, token/cost policy, batch inference strategy, and agent behavior.
+
+## Service Rules
+
+- Separate request validation, inference orchestration, provider/client adapter, and result persistence.
+- Treat model calls as external dependencies with timeout, retry, rate limit, cost, observability, and partial-failure handling.
+- Long-running inference belongs in workers or async job APIs when request latency is not bounded.
+- Streaming endpoints need cancellation, heartbeat, error event, and cleanup policy.
+- Vector stores and embedding tables are data adapters; define ownership, refresh, versioning, and deletion policy.
+- GPU/CPU-bound inference must have concurrency controls and memory pressure safeguards.
+
+## Inference Service Runtime Topology
+
+For Python services that host models or wrap model-serving runtimes (Triton, TorchServe, Ray Serve, llama.cpp llama-server):
+
+- **Deployment shape choice** is an architecture decision: FastAPI + Ray Serve for multi-model orchestration with per-model autoscaling and traffic ratio; FastAPI + uvicorn lifespan for single-model CPU services with eager singleton load; llama-server / vLLM / similar for self-contained GGUF / safetensors with OpenAI-compatible HTTP surface. Mixing shapes within one service is a finding.
+- **Model load is part of readiness**, not startup side-effect. The readiness probe reflects "model loaded and warm", not "process up". Health stays public early so the orchestrator can place pods; readiness flips only after the model is callable. **FastAPI lifespan loading interaction**: putting a multi-minute model load inside the lifespan startup blocks the whole app from serving any endpoint (including `/health`) until startup completes; Kubernetes can restart the pod before readiness ever flips. Use one of: (1) Kubernetes startup probe with a generous failure budget (cluster waits the model-load time before liveness/readiness fire); (2) a separate lightweight health-only HTTP server on a different port that runs immediately while the main app loads; (3) an async load state machine where the main app starts immediately and `/ready` reads a "loaded" flag the background loader flips. Document which pattern the service uses.
+- **GPU memory budget is declared per replica**, not inferred. Document the model's resident memory, KV-cache budget (for LLMs), and headroom required for the largest expected batch; pick `instance count` / `Ray Serve replicas` so the product fits.
+- **Three-stage instance lifecycle**: register only after readiness; heartbeat with bounded cadence and explicit failure path; on SIGTERM deregister first, drain in-flight requests with a deadline, then close model handles and exit. Unbounded loops, process-kill exits, and registration-before-load are anti-patterns.
+- **Service metadata exposed to discovery** carries lane, environment, partition, active model version, startup timestamp, and commit hash. Discovery can route by lane and surface "which model version is serving this lane" without polling each instance.
+- **Per-request log_id and request_id propagation**: middleware reads W3C `traceparent` + `tracestate` (and `baggage` when needed) via OpenTelemetry propagator `extract` so spans continue the parent trace, alongside the platform's `X-Log-Id` / `X-Request-ID` for log correlation. At public trust boundaries, regenerate or validate inbound request ids so callers cannot spoof log correlation; on internal hops, preserve. For `asyncio.create_task` / Ray actors / thread-pool workers, capture the OTel context at task creation via `opentelemetry.context.get_current()` and reattach inside the worker; without this, child-task spans become orphans of the parent trace.
+
+## Internal Inference RPC Authentication And Authorization
+
+"Internal infrastructure" is not a security boundary on its own. Inference endpoints reachable from the service mesh need explicit auth at the architecture layer:
+
+- **Service identity**: every caller has a verified workload identity — mTLS service certificate, SPIFFE / SPIRE ID, signed JWT issued by the platform identity provider, or k8s service account token. The inference service refuses unauthenticated callers; "from inside the cluster" is not authentication.
+- **Caller allowlist per model**: each inference endpoint declares which callers (service identities, teams, environments) are allowed to invoke it. The allowlist is enforced by middleware before the model is loaded, not by trust in network reachability.
+- **Tenant / resource authorization**: when the call carries a tenant id or resource id, the inference service verifies the caller is permitted to use that tenant's / resource's data. A tenant-id passed in the request body and trusted as truth is a finding.
+- **Quota / rate limiting per caller × model × tenant**: a shared GPU model is a shared resource; per-caller quotas prevent one consumer from exhausting capacity for the rest.
+- **Signed object-storage URL trust**: a signed URL is a bearer credential plus a server-side fetch target. The inference server enforces (1) allowed bucket/host allowlist (SSRF defense), (2) allowed object namespace / prefix per caller, (3) maximum expiry window (minutes, not hours), (4) HTTP method scope, (5) content-length and content-type caps, (6) checksum / digest validation when the registry supports it, (7) redaction of signed query parameters from logs and trace attributes.
+
+## Discovery Cache Miss Policy
+
+The fallback policy on discovery cache miss is **per-route**, not a portfolio default. The SDK's cache fall-back-to-baseline-lane behavior must be overridable per call:
+
+- Read-only idempotent calls on data that is already public-to-the-tenant (classification, OCR on already-uploaded content) MAY fall back to a documented baseline lane.
+- Canary, stress, shadow, tenant-sensitive, or write-with-side-effects routes MUST fail closed when the requested lane has no healthy instance. Silent fallback can leak canary traffic, stress traffic, or one tenant's processing into the wrong lane.
+- The default for unmarked routes is fail-closed. Per-route opt-in to baseline fallback is explicit and reviewed.
+
+## Internal Inference SDK Boundary
+
+Portfolios with multiple Python inference services converge on an internal SDK that owns the integration concerns:
+
+- **SDK scope**: service discovery (registry-based or k8s-native, with environment/lane filtering), transport (sync and async paths against the same wire), retry with bounded budget, tracing header injection, contract (de)serialization (protobuf / Pydantic / equivalent), and registry-side lifecycle helpers (`register / heartbeat / shutdown`).
+- **Distribution**: package the SDK as a wheel published to a private package index. Pin the version per consumer; SDK upgrades are managed changes with a release note, not ambient editable installs.
+- **Service identity format**: SDK validates the platform's chosen identity format (e.g. three-segment `<owner>.<class>.<env>` or equivalent) at client construction; mistyped identities fail at startup, not at first request.
+- **Lane derivation**: SDK reads the lane environment variable at startup and tags every outbound discovery query and trace span; in-cluster discovery filters by lane metadata so a canary cannot fall back to production by accident.
+- **Discovery cache + failover**: SDK caches the resolved instance list with a short refresh interval (5-15 s), filters to healthy + matching lane, and load-balances over the survivors (round-robin or random). On cache miss, baseline-lane fallback is **per-route, not default-on**: it applies only to routes explicitly opted in per the Discovery Cache Miss Policy above; canary / stress / shadow / tenant-sensitive / write-with-side-effects and all unmarked routes fail closed (never silently fall back) — wiring baseline fallback globally leaks canary/tenant traffic into the wrong lane.
+- **Typed exceptions**: SDK raises typed errors (`InferenceTimeout`, `InferenceModelUnavailable`, `InferenceTransport`) rather than `RuntimeError("...")` with a string. Business code catches by class.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/api-contract-and-schema.md

@@ -0,0 +1,62 @@
+# API Contract And Schema
+
+Use this for HTTP API, internal API, generated client, Pydantic, OpenAPI, and protobuf/gRPC architecture.
+
+## Defaults
+
+- Use Pydantic models and OpenAPI as the default contract surface for Python HTTP APIs.
+- Keep request, response, persistence, and internal domain models separate when they evolve at different speeds.
+- Use protobuf/gRPC only when the integration or platform contract requires it.
+- Generated clients are build artifacts; generated migrations are not contract truth.
+
+## Evolution Rules
+
+- Prefer additive evolution: optional fields, new response fields, new endpoints, new enum values, and versioned behavior flags.
+- Treat shipped or externally consumed Pydantic/OpenAPI/protobuf/API contracts as compatible-by-default regardless of implementation language. Do not remove, rename, repurpose, make required, or stop accepting existing fields, codes, endpoints, or semantics unless a human explicitly approves a breaking change after reviewing a risk assessment.
+- A breaking-change risk assessment must name consumers and generated clients, rollout order, compatibility window, migration or dual-read/dual-write plan, monitoring, rollback path, user/customer impact, and contract/integration/replay evidence for the cutover.
+- If launch or consumer status is unknown, assume the contract may be live and design a compatible path first.
+- Do not reuse field meanings or silently change validation semantics.
+- Make deprecation explicit in schema, docs, and compatibility tests.
+- Use typed SDKs or generated clients for cross-service calls when contracts need stability.
+
+## Validation
+
+- Validate at the boundary, then convert to domain objects or use-case inputs.
+- Keep public error shape stable even when framework, validation, or dependency exceptions change.
+- If schema validation depends on external data, split syntactic validation from business validation.
+- Treat schema enums and generated enum clients as boundary representations unless architecture explicitly approves transport-coupled domain code through an ADR or an inline usage-site comment formatted `architecture-approval: transport-coupled finite value <scope> <decision-ref> <reason>` where `<decision-ref>` is a full URL or numeric record id such as `ADR-123`; reviewers must confirm the referenced record exists and approves the specific value/scope before approval. A CI check, grep panel, or required review checklist item MUST exist and pass before any PR introducing `architecture-approval:` comments is merged; absence of that check is itself a blocking finding. The first PR that introduces `architecture-approval:` comments must include the enforcement check in the same PR or reference a prior merged check; "will add later" is not approval.
+- For finite values shared by services or clients, define the canonical owner, shared schema/package location, conversion helper owner, unknown/default behavior, and rollout/debt retirement path. If no shared location exists, approve a local fallback and track every temporary duplicate/raw use with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`.
+
+## IDL And Schema Governance (Cross-Stack)
+
+When Python services share IDL surfaces (protobuf for gRPC, OpenAPI/JSON Schema for HTTP, Pydantic models for internal contracts) with Go services or other clients, governance applies symmetrically.
+
+- For multi-service portfolios, prefer dedicated IDL repos (proto, http-thrift, OpenAPI) over inlining schemas in business repos; each IDL repo runs codegen, formatter, and breaking-change checks in CI.
+- Inside one IDL set, use a tiered structure — `base` for shared structs and the canonical error/code enum, `api` for gateway-facing contracts, `<domain>` (one bounded context per directory) for per-domain RPC — matching the cross-stack convention. The shared `base` is defined once and imported by every service within that set, never redeclared per service (a deliberate compatibility fork with owner/version/deprecation plan is the documented exception); a service that diverged unintentionally is a recorded known divergence with a migration target, not a silent parallel convention.
+- Numeric Code range is reserved at the platform layer (e.g., the platform-specific reserved range) and sub-allocated per tier. Python services raising biz codes must register in the same allocation table as Go services; collisions are caught at allocation, not at runtime.
+- Multi-language codegen: each language has its own codegen script (e.g. one shell script per target language), driven from the IDL repo's CI. The language with integration tests is canonical; others inherit the contract and may need their own coverage.
+- Breaking-change governance is platform-level: `buf breaking` or equivalent runs in IDL-repo CI; intentional breaks route through an explicit approval path regardless of which language consumes the IDL.
+
+## Response Envelope Strategy (Cross-Stack)
+
+- Architecture decides once whether the portfolio uses HTTP-status-as-semantic or HTTP-200-always-with-JSON-code, and applies the choice consistently across Go and Python services. Mixing the two on the same portfolio breaks gateway error classification and SDK error parsing.
+- For HTTP-200-always portfolios, the envelope `{code, message, data}` shape and the code-allocation table are platform contracts. Python services use the same envelope as Go services; SDK generators on either side parse the same shape.
+
+## Contract Tiers, Streaming, And Shape Validation (Cross-Stack)
+
+Mirrors `go-microservice-architecture/references/protobuf-contract-architecture.md` (Streaming And Surface-Shape Validation); keep these cross-stack rules in sync across both files.
+
+- **Distinct contract tiers are distinct shapes — do not force one envelope across all.** Internal RPC (shared base + typed data), the public HTTP JSON envelope (`{code, message, data}`), streaming, and **externally-dictated standard protocols** (a provider-compatible API, a webhook spec, an industry wire format) each carry their own shape. An externally-dictated protocol follows that protocol's wire, mapped from the contract source — not the internal RPC/HTTP envelope. A compatible wire is **not an exemption from internal controls**: authz, tenant isolation, quota, audit, and error-code governance still apply behind it; "just being standard-compatible" must not become a bypass. For a surface with no consumer yet, don't default it to another tier's envelope; define its own contract when a consumer or stability requirement appears.
+- **A streamed message (`grpc.aio` streaming, FastAPI `StreamingResponse` / SSE / NDJSON) is a separate shape decision — not automatically the unary envelope.** Define completion and error semantics explicitly: for a fatal terminal error on a transport that can still signal it (gRPC trailers) surface a non-success status, but where the HTTP status is already committed (SSE / NDJSON after a 200) carry the error in-band and ensure observability classifies it as a failure rather than trusting the 200. A stream that already emitted client-visible data or dispatched side effects is not freely retryable; per-domain event payloads are that service's contract, not a universal field set.
+- **Make the conventions machine-checkable and multi-service, scaled to repo maturity** — an agent-readable convention spec plus a contract health check that iterates every service (not one hardcoded), validates each unary tier's envelope, and exempts streaming and shared-base definitions. A service it cannot yet validate is a recorded gap with owner and severity, not silently skipped.
+
+## Front-End Consumer Contract
+
+The HTTP / gRPC contract that Python services publish is consumed by front-end clients (React Web, mobile web, mobile-native). The same envelope, header, and timeout decisions appear on the consumer side; architecture documents both sides so they cannot drift independently.
+
+- **Envelope direction**: the server emits the same envelope shape every front-end client parses. Mixing HTTP-200-always with HTTP-status-as-semantic across services forces every front-end caller to special-case per endpoint; the choice is portfolio-level. See the web client skill's cross-stack contract guidance for the consumer-side rules.
+- **Trace propagation**: framework middleware reads inbound request-id header when present and otherwise generates one; both the request id and the OTel trace id are surfaced on the response (header or envelope field) so the front end can show them in error UI. Middleware that drops the inbound header silently breaks end-to-end correlation.
+- **Auth header contract**: the agreed auth header (e.g. `Authorization` or a platform-specific token header), app-identity header, and any tenant / lane / shadow-traffic headers are validated through one middleware and exposed on the request context using a tiered context-keys convention. Per-route ad hoc header reads are findings.
+- **Timeout layering**: outer caller budget is always longer than inner callee budget. For the path `front-end client → Python gateway → downstream RPC/HTTP`, the relationship is `client timeout > gateway timeout (uvicorn / gunicorn worker + framework-level) > downstream RPC/HTTP timeout`. A gateway longer than the client lets the client time out before the gateway can return a structured error; a gateway shorter than the downstream call the gateway itself initiates leaves the inner call running with no caller. Per-endpoint risk tunes the specific values; the ordering is invariant. For long-running work, the gateway holds the request only as far as the streaming/polling contract requires; otherwise the server hands the work to a background worker and returns a task id the front end can poll.
+- **Client-signed object-storage upload**: expose a narrow signed-credential endpoint (returns short-lived STS or signed URL + upload target) so front ends write directly to object storage. The main API channel never carries the file body. Token issuance is logged for audit.
+- **SDK/codegen for the front end**: when the contract is exposed via OpenAPI / Pydantic schemas, the front-end TS client is generated from the same source the server compiles. Architecture owns the generator command and the publishing cadence so the front-end client never lags the server contract by more than one release.

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

@@ -0,0 +1,39 @@
+# API Security Boundaries
+
+Use this when a Python service exposes public APIs, partner integrations, callbacks, signed requests, app credentials, or externally reachable admin surfaces.
+
+## Public API Boundary
+
+- Treat public APIs as a separate trust boundary from internal framework routes, workers, and RPC clients.
+- Authenticate the calling app or user before resolving authorization scope or running domain validation.
+- Keep authentication, authorization, scope resolution, schema validation, and domain validation as separate architecture steps.
+- Define auth bypass paths explicitly. Keep them small, reviewed, and limited to health/readiness or documented public metadata.
+- Public errors should be stable and non-sensitive; logs should keep the detailed auth failure reason with safe identifiers.
+
+## Partner Application Auth
+
+- A partner app model should include app id, secret/public-key reference, allowed source restrictions when applicable, allowed authorization/resource scope, integration/source identity, status, and rotation metadata.
+- Store secrets in a secret provider or encrypted config, not in code, config examples, tests, generated docs, or logs.
+- Support disabled apps and rotated credentials. Unknown, disabled, expired, or malformed auth config fails closed.
+- Signed requests should include timestamp, nonce or request id, app id, and canonical request data.
+- Prefer HMAC or asymmetric signatures for new integrations. Enforce timestamp windows and replay protection for state-changing APIs and callbacks; document explicit read-only or already-idempotent exceptions.
+
+## Authorization Scope Isolation
+
+- Treat tenant, account, owner, actor, resource, and permission fields from request body, query, path, headers, or downstream payloads as claims until resolved from authenticated context.
+- Resolve allowed resource scope from the authenticated app/user before domain logic.
+- Include resolved scope/source in idempotency keys, cache keys, rate limits, audit records, and downstream context.
+- Scope-check bypasses require explicit integration config, narrow reason, and audit trail.
+
+## Callback Boundary
+
+- Callback endpoints must validate signature/token, timestamp window, event type, payload shape, and required resource identifiers before side effects.
+- Callback processing should assume duplicate, delayed, and out-of-order delivery.
+- Deduplicate by provider event id, request id, or a stable resource-event-time key.
+- Return provider success only after durable acceptance, or document why the provider should not retry.
+
+## Audit And Operations
+
+- Log app id, resolved scope id, integration source, event id, endpoint, auth result, canonical error code, and trace/request id.
+- Do not log secrets, raw signatures, full tokens, or sensitive payloads.
+- Metrics should separate auth failure, permission failure, validation failure, duplicate callback, callback processing failure, and dependency failure.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/architecture-playbook.md

@@ -0,0 +1,46 @@
+# Architecture Playbook
+
+Use this as the first reference for Python backend, Python microservice, AI-service host, worker, batch, or package architecture. For new backend products, choose microservice, modular monolith, worker, script, or package shape from ownership, data boundary, runtime isolation, scaling, release cadence, and rollback evidence.
+
+## Source Lessons
+
+- Official framework docs support clear router/app separation, dependency injection, settings, test clients, and deployment checks.
+- Local production-service code shows strong Python service hygiene: `uv` workspace, dependency groups, FastAPI app factory, SQLAlchemy/Alembic, pytest markers, ruff, mypy/pyright, OpenTelemetry packages, generated clients, and release scripts.
+- Local inference-service code shows high-value async and model-hosting patterns, but also a risk: business-specific handlers, ad hoc scripts, and domain terms must be filtered out. Extract async boundaries and service wiring, not product vocabulary.
+
+## Architecture Decisions
+
+- Decide the backend shape first: API service, internal service, worker service, scheduled job service, SDK/package support library, CLI, AI-service host, or modular monolith.
+- Use separate deployable service boundaries only when ownership, scaling, data ownership, runtime isolation, deployment cadence, or rollback needs justify them. Keep one modular service/package/script shape when boundaries are unclear or the scope is too small for separate services.
+- For each Python microservice that is justified, define the owner, contract, data source of truth, inter-service auth, timeout/retry/fallback policy, deployment unit, canary/rollback, and observability.
+- Separate layers:
+  - transport/framework: routing, auth, validation, response mapping
+  - application/service: use-case orchestration and transactions
+  - domain: invariants and decisions
+  - infrastructure: DB, Redis, MQ, object storage, external HTTP, inference clients
+  - tooling: migrations, scripts, generated clients, test helpers
+- Avoid import-time network I/O, implicit global clients, and hidden environment reads outside settings/bootstrap.
+- Put cross-service contracts in schemas, OpenAPI, protobuf, SDKs, or typed clients, not in string conventions.
+- 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.
+
+## Layering Depth (Apply In Moderation)
+
+- The transport / application / domain / infrastructure split above is the **Ports-and-Adapters / Hexagonal** idea in moderation — `infrastructure` modules are the adapters, the application-service layer hides them behind plain function / class boundaries. Useful when: an external dependency has multiple real implementations (S3 + GCS, OpenAI + local-inference + vendor-N), a domain rule is stable enough that the test fake is reusable across years, or a regulated boundary requires a single audit point. Counter-indicated when: there is one real implementation that will not change, the "adapter" is a thin pass-through with no behavior, or the layering would force every DTO through 3 mappings. Do not introduce an interface per class out of habit — the Java-style "every service has an interface, DTO mirrors entity, entity mirrors row" pattern is over-engineering in Python and produces churn without testability or substitution gains.
+- **Functional core, imperative shell**: prefer pure functions for calculation / rule / state-transition logic; let FastAPI handlers, SQLAlchemy sessions, Celery tasks, and external clients be the I/O shell that calls them. The pure core is easy to unit-test without fixtures; the shell is small enough to integration-test directly. Conflating them — domain rules sprinkled inside ORM event listeners, or business calculation inside a Celery task — is the recurring source of "we cannot test this without a real database / queue / network." Distinct and **not** optional: domain invariants must not be hidden inside route/FastAPI handlers, repositories, external-client wrappers, SQLAlchemy/ORM event listeners or hooks, or Celery task/worker callbacks — anywhere outside the domain/service layer. That is the layering rule, independent of whether you adopt the pure-core style. Sibling: `go-microservice-architecture/references/architecture-playbook.md` ("Functional Core, Imperative Shell") carries the same principle for Go; keep the two in sync.
+- **Shared foundation/utility packages need stricter tiering than a single service**, scaled to blast radius — a widely-imported cross-service `common` library earns it; a tiny single-consumer helper does not. Such a module inherits one import cycle or one heavyweight coupling into every consumer, and a leaf utility cannot be reused once it transitively drags in unrelated packages. Document an explicit linear package-tier order in the module itself (illustrative: `generated value-types -> constants -> generic pure utils -> logging/metrics -> framework/business adapters`); forbid earlier tiers importing later tiers (one-directional, acyclic). Default to sibling independence so each leaf stays independently importable; when one same-tier package genuinely needs another, extract the shared piece down a tier rather than copy-pasting or adding a micro-tier. Generated pure contracts may be imported anywhere; generated clients carry transport deps and belong in the adapter tier only; all generated code is regenerate-only. Enforce with `import-linter` `layers` + `independence` contracts (a `src/` layout aids packaging isolation but does not enforce tiering) rather than review memory; a new cross-tier or sibling import is an architecture-review item.
+- **How a layer boundary is enforced is itself an architecture decision**, with a strength ladder: physical package boundary (a separate distribution package whose violation is an import or packaging error), `import-linter` contracts in CI (above), 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: `go-microservice-architecture/references/architecture-playbook.md` ("Dependency Direction") carries the same rule for Go; keep the two in sync.
+- **Adapter / plugin family = shared core + thin bridges (especially across repos).** When one cross-cutting concern (observability, auth/governance, a client-SDK wrapper) bridges into many frameworks/drivers (FastAPI / aiohttp / a set of DB, cache, MQ clients), put the invariants in one shared core and make each adapter a thin framework-specific bridge — not a per-adapter re-implementation. The core exposes only the seam + invariants; a *concrete* framework/driver adapter (a specific ORM, HTTP framework, or MQ-client binding) must NOT live inside the core package — that pulls its heavyweight deps into every core consumer and inverts the dependency direction (adapters import the core, never the reverse; keep the core adapter-agnostic). Keep the seam **dependency-neutral but semantics-explicit**: it names the required transaction/commit/ack/retry/cancel/failure guarantees the invariants rely on (an outbox/audit control needs real commit-and-ack, not a seam that hides it) plus an adapter conformance suite, and rejects a driver that can't meet them rather than flattening to a lowest common denominator. A library swap is a thin shim *only if* it preserves that declared capability matrix (session scoping, connection reset, broker nack/backpressure, middleware ordering); dropping a real semantic is an architecture change, not a shim. "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) + baseline instrumentation, so services don't each hand-roll and diverge from — or bypass — the invariants. Failure policy is risk-specific: fail-open only for genuinely optional telemetry, fail-closed for auth/governance/data-integrity/audit (audit & compliance signals are controls, not "observability") — but "fail-closed" for audit means durable local capture (outbox) + bounded degraded mode, hard-blocking only the specific regulated operation (mutation, sensitive read, export, or privileged access), not making the audit exporter a synchronous kill switch for unrelated traffic; context binding, lifecycle, propagation, canonical schema/error model are the other invariants. The same fix landing in a third sibling adapter is the signal to extract the invariant into the core — but backport/mitigate the live bug across existing adapters **first**; extraction is the durable follow-up. For independently-pinned adapters, ship a *minimal, explicitly-versioned* extension API plus a **tiny stable contract package separate from the core impl** (so a core change doesn't version-lock every adapter — govern with semver windows + cross-adapter contract tests); stabilize the broader abstraction only on rule-of-three evidence, not speculatively (a wrong shared abstraction is harder to undo than duplication). Reuse official framework instrumentation only through explicit injected provider/runtime (not its process-globals; contract-test no global set-once) — or, if the official lib is global-only, a documented single-owner idempotent bootstrap exception (test-isolated, no custom wire semantics) rather than forking it — keeping governance in the core. Sibling: `go-microservice-architecture/references/architecture-playbook.md` ("Adapter / Plugin Family") carries the same principle; keep the two in sync.
+- **Composition over inheritance** is the Python default. Reach for a base class only when the subclass relationship is genuinely "is-a" and the parent class is stable; a `BaseService` / `AbstractHandler` / `BaseRepository` that exists to share two helper methods is a refactor target — extract the helpers, drop the hierarchy. Deep business-service inheritance trees (3+ project-owned levels, excluding framework base classes like SQLAlchemy `DeclarativeBase` / Pydantic `BaseModel` / Django `Model`) are a code-review finding.
+
+## Architecture Output Checklist
+
+- Chosen framework and why.
+- Service shape: microservice set, modular service, package, CLI, worker, script, or AI-service host, with the boundary rationale.
+- API/schema contract and evolution policy.
+- Finite-value semantic owner, shared location or approved local fallback, conversion boundaries, unknown/default behavior, and debt retirement owner/deadline when relevant.
+- Data owner, migration owner, transaction boundary, and rollback strategy.
+- Async/concurrency model and blocking-work isolation.
+- Worker/job model, retries, idempotency, and failure visibility.
+- Config/secrets model and dependency client lifecycle.
+- Observability and launch checks.
+- Tests and quality gates at the architecture level, with detailed test mechanics routed to `testing-strategy` and `python-service-dev`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/async-execution-model.md

@@ -0,0 +1,24 @@
+# Async Execution Model
+
+Use this when deciding sync vs async, concurrency, event loops, CPU/GPU work, and blocking dependency boundaries.
+
+## Decisions
+
+- Use async when the dominant work is non-blocking I/O and the dependency libraries are async-native.
+- Keep synchronous stacks synchronous when async would only wrap blocking SDKs.
+- Do not call blocking DB, HTTP, file, CPU, or GPU work directly inside async endpoints.
+- Isolate blocking work with workers, process pools, thread pools, or `asyncio.to_thread` where appropriate.
+- Bound concurrency with semaphores, queue limits, worker pool settings, and dependency-specific connection limits.
+
+## Python-Specific Risks
+
+- The GIL makes CPU-heavy concurrency different from lightweight I/O concurrency. Use process or native-extension strategies for CPU-bound work.
+- `asyncio.gather` without limits can overload downstream systems.
+- Cancellation and timeouts must be designed; a cancelled request should not leave orphaned jobs, leaked clients, or half-written state.
+- Event-loop lifecycle and client cleanup belong to app lifespan/bootstrap, not module import.
+
+## Structured Concurrency Principle
+
+- **`asyncio.TaskGroup` (Python 3.11+) is the architecture default for fan-out concurrency** — supersedes `asyncio.gather` as the recommended primitive for any concurrent work where partial failure should cancel siblings. The architectural shift from `gather` to `TaskGroup` is the same shift Trio popularized as "structured concurrency": every concurrent task has a lexically-scoped lifetime, failures propagate as a unit (via `ExceptionGroup` + `except*` per PEP 654), and cancellation flows in a deterministic order. Reserve `gather(return_exceptions=True)` for the narrow case where partial success with independent siblings is the intended contract — every other use is technical debt waiting to leak.
+- **Free-threading (PEP 703) changes the GIL assumption for new architecture decisions starting at Python 3.14**, where free-threading reached officially-supported Phase II status (per PEP 779) with the single-threaded penalty narrowed to ~5-10%. For services where parallel CPU work matters (in-process inference fan-out, parallel parsing, image/document processing) this is the first version where the "use a process pool to escape the GIL" decision becomes "use threads in a free-threaded build" — a meaningfully different architecture. The catch: C extensions must opt in (PEP 803 `abi3t`), and ecosystem maturity at 2025-2026 is uneven. Treat free-threading as an architecture option to consider deliberately, not the default; for pure I/O-bound services, the stock-GIL build remains correct.
+- **`anyio` is the architecture choice for async code that should support both asyncio and Trio backends** — relevant when the service ships as a library consumed by both ecosystems or when the team values Trio's stronger structured-concurrency semantics. Pure-application services usually stay on asyncio directly (TaskGroup + timeout + ExceptionGroup); reach for anyio when the dual-backend requirement is real, not as a hedge.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/background-jobs-and-scheduling.md

@@ -0,0 +1,18 @@
+# Background Jobs And Scheduling
+
+Use this for Celery, RQ, arq, APScheduler, cron-like jobs, queue workers, and long-running tasks.
+
+## Job Model
+
+- Define job identity, payload schema, idempotency key, retry policy, timeout, max concurrency, and terminal states.
+- Decide whether the job is durable queue work, scheduled work, one-off repair, or batch pipeline before choosing a tool.
+- Use Celery/RQ/arq when work must survive process restarts or run outside the request path.
+- Use in-process background tasks only for short, non-critical work that can be lost safely.
+
+## Reliability
+
+- Treat queue delivery as at-least-once unless the platform proves otherwise.
+- Make consumers idempotent.
+- Use leases or locks for singleton jobs.
+- Store progress/checkpoints for long jobs.
+- Expose failure visibility through logs, metrics, status records, or administrative reports.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/batch-and-pipeline-architecture.md

@@ -0,0 +1,11 @@
+# Batch And Pipeline Architecture
+
+Use this for imports, exports, backfills, repair scripts, data processing, and pipeline-like Python work.
+
+## Boundaries
+
+- Keep one-off scripts from becoming hidden production systems. If a script is repeated, add config, logs, dry run, resume, and tests.
+- For large jobs, define chunk size, checkpoint, restart behavior, max concurrency, rate limits, and output artifacts.
+- Use durable task state for multi-step jobs that affect product data.
+- Separate extraction, transformation, validation, persistence, and reporting.
+- For Airflow, Dagster, Spark, dbt, or true data-engineering orchestration, consider a future dedicated `python-data-pipeline` skill instead of overloading this skill.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/config-secrets-runtime.md

@@ -0,0 +1,22 @@
+# Config Secrets Runtime
+
+Use this for settings, secrets, dependency clients, and runtime configuration.
+
+## Settings
+
+- Prefer typed settings through Pydantic Settings, Django settings modules with typed accessors, or equivalent schema-backed config.
+- Separate local, test, staging, and production configuration without hard-coding environment names into business logic.
+- Validate required config at startup before serving traffic. More generally, never let a critical invariant rest on a dependency's incidental or undocumented behavior — assert and own it locally, preferring construction-time fail-fast over request-time fail-open.
+- Keep defaults safe for local development, not silently production-like.
+- The Settings / Secrets / Dependency Clients rules in this file plus the stateless-process and structured-logs rules in `observability-and-ops.md` and `packaging-runtime-readiness.md` cover the Twelve-Factor App principles MOST relevant to a Python service skill (config in env, backing services as attached resources, build/release/run separation, processes, logs). Do not treat this as a full Twelve-Factor checklist — factors like codebase, port binding, and admin processes are owned elsewhere. Follow the typed-config + env/secret-injection + startup-validation rules here and route deployment / release / port-binding / admin-process factors to `platform-release-engineering` and `packaging-runtime-readiness.md`.
+
+## Secrets
+
+- Secrets must come from environment, secret manager, workload identity, or deployment platform.
+- Do not place real secrets in examples, tests, generated clients, notebooks, logs, or pyproject files.
+- Redact secrets from error messages and structured logs.
+
+## Dependency Clients
+
+- Define lifecycle: construction, readiness validation, timeout, retry, credentials, close hook, and fake/test substitution.
+- Separate startup/admin timeouts from request-path timeouts.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/data-modeling-and-migrations.md

@@ -0,0 +1,64 @@
+# Data Modeling And Migrations
+
+Use this for SQLAlchemy, SQLModel, Django ORM, Alembic, transactions, and storage ownership.
+
+## Ownership
+
+- A Python service owns its write schema and migration history.
+- Shared databases require explicit ownership rules. Do not let two services write the same tables without a designed contract.
+- Keep ORM models, repository interfaces, transactions, and migration scripts aligned.
+
+## Migration Policy
+
+- Treat Alembic autogenerate output as a draft. Review table names, indexes, constraints, data migrations, downgrade/rollback expectations, and lock impact.
+- Keep generated migrations in source control, with human-edited intent where needed.
+- For Django, treat migrations as source artifacts too; review data migrations and irreversible operations.
+- Define deploy order for schema changes that require application compatibility.
+
+## Index And Query Model
+
+Evidence boundary: these rules are cross-stack backend guidance expressed for Python ORM and migration tooling. Confirm the active repository's migrations, ORM conventions, database dialect, and observed repository methods before claiming local completeness.
+
+- Define expected query filters, joins, sort order, and pagination strategy before finalizing ORM models or migrations.
+- Composite indexes should match actual access paths: leading equality or `IN` predicates first, then range/order fields. Single-column `index=True` fields do not replace a reviewed composite index when the repository method filters by multiple columns.
+- Unique constraints should represent product/data invariants, not only performance. Upsert or de-duplication paths that re-query rows to recover generated fields need a stable unique/conflict key that matches the re-query shape.
+- Treat leading-wildcard search, broad `OR`, tuple or large `IN`, `DISTINCT` over joins, and offset pagination as warnings for hot user paths. Either prove bounded cardinality and a query-plan budget, or move the use case to exact-match filters, keyset pagination, or a search/read-model projection.
+- Query-plan tooling such as SQLAlchemy compiled SQL plus database `EXPLAIN`, or Django `QuerySet.explain()`, is a safety net. It does not replace reviewing migrations, access paths, and production cardinality assumptions.
+
+## Transactions
+
+- Use explicit unit-of-work/session boundaries for multi-step writes.
+- Avoid opening sessions deep inside domain functions when the caller owns the transaction.
+- Keep DB read/write routing and transaction ownership in a shared infrastructure layer when one exists.
+- Redis, queues, and external calls inside DB transactions require careful outbox, idempotency, or compensation design.
+
+## Postgres Driver Choice (Architecture Axis)
+
+- **Driver choice is an architecture decision, not a developer preference** — it constrains sync/async coexistence, ecosystem maturity, and operational tooling (psql tools, observability libraries, ORM dialect availability). Decide at service-shape time, not when the first repository method is written.
+- **`psycopg` v3 is the default for new services that need both sync and async** — per psycopg docs, one library, one DBAPI, both `create_engine()` and `create_async_engine()` consume the same URL with SQLAlchemy auto-selecting sync vs asyncio dialect. Supports modern Postgres features (composite types, JSONB, pipeline mode, server-side parameter binding). Migration target for psycopg2 (maintenance mode, no new features). Architecture impact: one driver across web handlers, Alembic migration runner, batch scripts, CLI tools, admin paths — no driver-boundary cognitive overhead.
+- **`asyncpg` is the alternative for pure-async high-throughput services** — independent driver, optimized for the async path; SQLAlchemy supports it as an async dialect. Architecture cost: any sync code path (Alembic, batch scripts, sync admin) will pull in psycopg2/psycopg anyway, producing a two-driver service. Choose asyncpg only when (a) the service is genuinely 100% async, (b) profiled benchmarks show measurable improvement over psycopg async on the actual workload (the gap has narrowed in psycopg v3), (c) the team accepts the cost of two-driver maintenance. The "asyncpg is faster" claim is generic; verify against the workload before letting it drive a driver split.
+- **For non-Postgres dialects, the same architectural question applies but with different defaults**: MySQL async → prefer `asyncmy` for new services; `aiomysql` is allowed when deliberately chosen or already established in the service, and should not be replaced solely to comply with the default. MySQL sync → prefer `mysqlclient`; `PyMySQL` is allowed for portability or existing convention. SQLite → built-in `sqlite3` (sync) + `aiosqlite` for async. Document the chosen driver per dialect at architecture level and do not mix two MySQL async drivers inside one service boundary.
+
+## Connection Pool And Proxy Topology
+
+- Pool sizing is a contract between the service, the connection proxy (PgBouncer, RDS Proxy), and the database server. Architecture must name the binding constraint and document how worker count, async concurrency, and replica count combine into the global connection budget.
+- Decide proxy mode (session vs transaction pooling) at the architecture level; transaction pooling forces the service to give up session-level state (server-side cursors, `LISTEN/NOTIFY`, prepared-statement caches, advisory locks held across statements). Code patterns that depend on session continuity must be redesigned or routed to a session-pooling pool.
+- Recycle intervals (`pool_recycle`, proxy idle timeout, load balancer idle timeout) must satisfy `recycle < idle_timeout` at every hop; architecture documents the tightest hop and the resulting client setting.
+
+## Read Replica And Routing Boundary
+
+- If the deployment includes read replicas, architecture declares which read paths can tolerate replica lag and which must read through the primary. Replica reads are a feature with a consistency contract, not a transparent optimization.
+- Read-after-write within a request window routes to primary until the consistency window closes; the window length and the carrier (request scope, causality token, session flag) are architecture decisions.
+- Replica engines should use read-only DB credentials so write attempts fail loudly at the database, not silently against the wrong endpoint.
+
+## Outbox And Dual-Write Consistency
+
+- DB-plus-Redis or DB-plus-MQ writes must use an outbox table when both must reflect the same business fact. Architecture declares which write paths cross a durability boundary and need outbox; ad hoc dual writes are review findings.
+- Outbox publishing is at-least-once; downstream consumers carry the idempotency burden. Architecture names the consumer-side idempotency mechanism (unique key, idempotency store, state machine) per outbox topic.
+- High-throughput outbox paths may use CDC (logical replication, binlog tail) instead of polling; architecture names the chosen strategy and the durability contract it provides.
+
+## Long-Running Transaction Budget
+
+- Architecture sets per-role transaction time budgets and chooses the enforcement layer: database `statement_timeout` / `idle_in_transaction_session_timeout`, framework-level transaction wrapper with timeout, or both.
+- External calls (HTTP, inference, object storage) inside DB transactions are an architectural error unless explicitly documented with a compensation plan. Streaming responses and websocket handlers must commit before entering the long phase.
+- Transaction-duration histograms and idle-in-transaction counts are first-class SLI/SLO signals owned at the platform observability layer; this skill names the emission contract.