@ccoalm/ccl-skills 0.1.0

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

@@ -0,0 +1,143 @@
+---
+name: python-service-dev
+description: 用 Python 写接口 / FastAPI / Django model / Celery 任务 / pytest → implement, modify, scaffold, test, and wire Python backend services, workers, packages, standalone CLI/tooling, migrations, Redis, queues, config, observability, and clients. Triggers also include "用 Python 写个命令行工具", "重构 Python 服务里的某文件/某类(局部)", "refactor a file/class within a Python service". For reproduction, isolation, or root-cause debugging, use defect-diagnosis first; for architecture/layering decisions or a service-wide refactor, use python-service-architecture; for a multi-stage / cross-module refactor delivery, re-enter product-rd-workflow.
+---
+
+# Python Service Dev
+
+Use this for implementation of Python backend products, services, microservices, AI-service hosts, workers, packages, and batch tools. For new backend products, implement the smallest deployable or package shape justified by ownership, data boundary, runtime isolation, scaling, release cadence, and rollback needs. It should adapt to the repository in front of you, but the workflow is independent of any prior codebase.
+
+## Skill Routing
+
+- Use this skill for Python implementation, scaffolding, handlers/routes/views, schemas, services, microservices, repositories, migrations, Redis, queues, workers, external/inter-service clients, config, observability, packaging, and tests.
+- Use `product-rd-workflow` first when the request is an end-to-end product delivery workflow, product idea to implementation plan, release workflow, cross-skill coordination, bug postmortem, or durable process improvement.
+- 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 `python-service-architecture` when the user asks for system design, service boundaries, contract strategy, storage ownership, reliability design, or architecture review without code changes.
+- Use `testing-strategy` when the main question is which unit, integration, contract, or E2E layer should prove behavior; then return here for Python-specific implementation.
+- Use `test-artifact-management` when the ask is about generating structured test cases from a Feishu requirements doc or codebase and tracking them in Feishu Bitable before implementation begins.
+- Use `llm-inference-integration` for inference, RAG, prompt, model-routing, evaluation, replay, token-cost, and batch-inference design. Return here for Python API, worker, adapter, persistence, and observability implementation.
+- Use `go-microservice-dev` for Go services. Do not load Go implementation rules for Python work unless the task is explicitly cross-language contract or generated-client integration.
+- Use codebase-specific skills only when the task is explicitly about an existing repository.
+- For money, billing, quota, permission, tenant/user data isolation, high-impact AI, repeated writes, async finality, or incident-explanation risk, apply `product-rd-workflow` high-risk resilience gates and route test-layer design through `testing-strategy`.
+- When a change edits strings, templates, or config values that are returned to, persisted for, emitted to, served to, synchronized with, or configured for client consumption (error copy, labels, notification text, localization payloads, content/CMS/seed rows, message or notification templates, flag-delivered content), classify the consumers with a recorded bounded check (client repo / contract / locale search) before closing on API/log evidence; if any client surface renders the value user-facing, or consumers are unknown, load `product-ui-ux-design` and record its implementation-owner checkpoint — including the consuming client stack owner(s) and `testing-strategy` per that checkpoint's field list — with client-side rendered-evidence routing. Backend-only closure without that recorded consumer check is invalid.
+
+## Generalization Discipline
+
+- Implement the repo in front of you, but do not import product nouns, service names, package paths, provider names, IDs, dashboards, or organization-specific habits from prior codebases.
+- Convert domain-specific source patterns into reusable mechanics: route shape, schema validation, repository/unit-of-work boundary, transaction scope, cache key strategy, idempotency, job lease, config object, trace context, fake client, or test style.
+- If an observed pattern only works for one product domain, discard it instead of turning it into a rule.
+- Resolve conflicts by choosing the safer generic default: explicit schemas over dicts, typed settings over ad hoc environment reads, reviewed migrations over blind autogeneration, bounded async concurrency over unbounded gather, dependency injection over import-time clients, focused pytest tests over live-infra tests by default, and fail-closed for auth/permission/data-integrity paths.
+- When adding or revising durable Python implementation guidance, check whether the lesson is generic backend service practice that should also update `go-microservice-dev`, or belongs in a shared workflow skill instead. If the rule depends on Python tooling, FastAPI/Flask/Django, Pydantic, asyncio, pytest, or Python package layout, keep it here and do not force a Go mirror.
+
+## Development Workflow
+
+Before editing code, generated files, migrations, configs, or tests, complete enough analysis and planning for the change to be reviewable. Scale the plan to risk: a simple low-risk single-package change can use a short inline plan; multi-file, contract-visible, data/schema, async, release, bug-fix, branch/MR, unclear-risk, or high-risk work needs explicit task split, acceptance checks, verification commands, rollback or stop conditions, and named handoffs to architecture, testing, or diagnosis skills before edits.
+
+Repo-local agent contracts (`AGENTS.md` at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per `product-rd-workflow`'s spec / repo-contract sync gate.
+
+1. Establish the target Python project shape.
+   - Find the nearest `pyproject.toml`, lockfile, package root, app entrypoint, framework app, settings, migrations, tests, and documented commands.
+   - Identify whether this is an HTTP API microservice, internal microservice, worker service, scheduled job service, SDK/package, CLI, AI-service host, or batch tool.
+   - For internal service-to-service calls, use RPC/gRPC by default and HTTP when the service contract chooses it. Do not treat HTTP as a local shortcut: use the repository/platform HTTP client wrappers for discovery, auth, deadlines, retries, logging, metrics, tracing, and contract tests.
+   - For new backend products, implement a separate microservice slice only when ownership, scaling, data ownership, runtime isolation, deployment cadence, or rollback needs justify a separate deployable unit. Otherwise keep the slice inside the existing modular monolith, worker, package, or script shape and preserve clean contracts, config, observability, and tests.
+   - When mining a local/internal reference tree for Python implementation patterns, first detect nested git repositories, submodules, and implementation-bearing non-default branches or tags before judging the tree empty. Prefer read-only tree inspection over switching branches, and record the reusable mechanism rather than the source branch, module, or path.
+   - Check whether tests are split by unit, integration, contract, API, E2E, and live-infra markers.
+
+2. Start from contracts and data.
+   - Update Pydantic/OpenAPI, Django serializer/form, or protobuf/gRPC contracts before changing request/response behavior.
+   - When protobuf is in scope for gRPC or HTTP contracts, record the source/config/test location for the globally unique service name, IDL source, generation command, generated artifact version, framework binding, and JSON/binary wire-format policy before implementing handlers or service logic; any unconfirmed item is a blocker. Prefer consuming generated contract packages from the contract/generation boundary. When shared IDL and IDLGen repositories exist, Python implementation must use the generated Python artifacts from that shared boundary and keep compatibility with Go and client-side consumers; do not create service-local private IDL copies that drift from the shared contract.
+   - Implement JSON-wire business API responses through the contract-recorded envelope per `../platform-service-connectivity/references/http-response-envelope-contract.md`; when the canonical envelope applies, map domain errors to the canonical `code`/`message` model at the framework boundary and do not return ad hoc top-level business fields from routes/views.
+   - Select the transport contract first — the carrier is scenario-driven per the Carrier decision in `../platform-service-connectivity/references/rpc-framework-recipe.md`: on a platform that has standardized the in-message `base` carrier (or a contract that declares/publishes `base`), apply the recipe's ordered base-field gate as the single source of truth; on a metadata-carrier service (the default for ordinary gRPC), apply the R7 owner-recorded header-set gate (`../platform-service-connectivity/SKILL.md` R7) instead. Boundary-exposure classification (canonical trigger set, rerun conditions, dispositions) and the implementation population check are canonical in the same recipe; when any canonical boundary trigger fires, run boundary-exposure classification before release per that recipe — missing or contradictory classification evidence is an open release gap, and authz on unauthenticated caller-supplied identity is an immediate blocking implementation finding. Python service diffs cite the recipe evidence for the touched edit kind; service-authored proto snippets, service-local copied descriptors, uncited provenance claims, stale/wrong-version descriptors, or broad tag claims cannot self-certify the shared contract.
+   - Route/view/handler, adapter, or DTO diffs that manually construct generated request/response DTOs outside the middleware-filled path, or write/mutate/overwrite `base`, `LogId`, caller, `From`, `To`, `Tags`, or equivalent identity fields on generated DTOs, apply the implementation population check in `../platform-service-connectivity/references/rpc-framework-recipe.md` (carrier-neutral — it runs even when the base-field gate is not applicable); missing evidence is an open implementation gap.
+   - Convert generated protobuf types at the transport/application boundary unless a quotable architecture or repo-contract record deliberately treats generated DTOs as the public application contract. Without that record, domain code must not depend on generated transport types.
+   - Use generated or schema-owned request/response/common-field types where they exist. If domain or persistence models differ from transport DTOs, map them explicitly at the route/application boundary.
+   - Define ORM model and migration changes before repository code. New Python relational services use SQLAlchemy 2.x plus Alembic by default unless the service records a deliberate alternative data-access choice; use framework ORM and migrations when the chosen framework, such as Django, owns that boundary. For new MySQL async services, prefer `asyncmy`; `aiomysql` is allowed when deliberately chosen or already established. Do not replace an existing working `aiomysql` driver solely to comply with the default. Do not mix MySQL async drivers inside one service boundary.
+   - Define Redis keys, TTLs, and idempotency/lock semantics before cache code.
+   - Define queue payloads, retry behavior, and idempotency before consumers.
+   - Define runtime config, health/readiness, entrypoint, and rollback controls before release-facing code.
+
+3. Keep layers clean.
+   - Transport layer: framework mapping, validation, auth context, response mapping.
+   - Application/service layer: use-case orchestration and transactions.
+   - Domain layer: rules and invariants.
+   - Infrastructure layer: DB, Redis, MQ, HTTP clients, object storage, inference clients.
+   - Generated code: never hand-edit generated clients or protobuf output. Migration files are reviewable source.
+
+4. Wire dependencies explicitly.
+   - Constructors and dependency providers should declare what they need.
+   - Prefer small boundary interfaces or protocols where tests or adapters matter.
+   - Keep production and test dependency graphs separate when clients need fakes.
+   - Avoid import-time client creation and hidden global mutable state. When a library reads config only from process globals (env vars) and the mutation is unavoidable, confine it to a snapshot/restore context manager scoped to the minimal window — restoring by `pop` when the value was unset versus reassigning when it had a value — under any existing lock.
+   - If a mature internal reference has stronger wrappers than the target repo, reuse existing target-repo wrappers first. When no wrapper exists, add the smallest local adapter that the current task justifies, or route platform-wide wrapper extraction to architecture/platform skills before implementation. Do not paste reference business code or private package layout; preserve only the generic contract, such as unit-of-work transaction helper, typed config client, queue producer/consumer wrapper, context injector, error mapper, or query-safety hook. Safety-critical fragments — exception-firewall wrappers, timeout enforcement, untrusted-input parsing — must be a single shared implementation even at a dozen lines; a per-call-site copy that drifts fails as a dead worker or a silent no-op, not as slowness.
+   - If the implementation task directly mines an internal checkout, private repository, local path, or organization project, apply the same sanitization gate before landing any artifact: keep only mechanisms and generic contracts; remove source-identifying domains, paths, repository/module names, people, tickets, and business nouns.
+   - For service registration, model serving, or worker bootstraps, verify readiness before registration, publish environment/version/routing metadata, and make shutdown/polling loops bounded and testable.
+   - For Python-hosted inference or long-running service hosts, separate HTTP ingress, request routing, handler/model execution, SDK registration, and generated deployment config. Treat generated serving configs, model packages, debug downloads, and runtime outputs as artifacts, not source templates.
+
+5. Verify at the right scope.
+   - Run focused pytest tests for changed packages.
+   - Run async tests with the repo's configured `pytest-asyncio` mode.
+   - Run integration tests only when required services and credentials are available.
+   - **TC traceability**: link tests via `@pytest.mark.tc("TC-XX-NNN")` marker. Registers at collection time so `@skip` / `@skipif` / fixture failures still map to Bitable status. Needs the `tc` plugin from `test-artifact-management/references/tc_helpers/tc.py` loaded via `addopts = -p tc`. See `test-artifact-management/references/tc-marker-conventions.md`. Before adding tests, `grep -rn 'pytest\.mark\.tc' tests/` plus the sidecar `test/results/tc-map.jsonl` to check for existing coverage — extend rather than duplicate. When a TC is marked 废弃, grep both source and sidecar; follow deprecation cascade in `testing-strategy`. Tests without any TC link: prompt user only when the underlying code is also removed.
+   - **废弃级联：业务代码是否仍在用** — grep 只找出"测试函数引用了什么 import"是第一步；判断"该 import 是否还有其他 caller"才能定生死。Python 顺序：
+     1. 看测试体导入的模块：`grep -E "^(from |import )" tests/test_<x>.py`
+     2. 对每个产品模块（非 stdlib / 非测试 helper），找全仓库 caller：`grep -rEn "from <pkg>\.<mod>|import <pkg>\.<mod>" --include='*.py' --exclude-dir=tests`
+     3. 零产品 caller → 同 commit 删该模块 + 测试；有产品 caller → 测试目标仍在用，不删测试（若 TC 已废弃但代码活，先确认产品决策）
+     4. 边界：动态 import（`importlib.import_module("...")`）grep 抓不到；含 reflection 的代码人工确认；DI/插件注册（`@register` 装饰器）的产品代码需查注册表而非 import
+   - Run ruff, mypy/pyright, formatting, and codegen/migration checks when the repo uses them.
+   - Keep fast tests deterministic; isolate live infrastructure, long sleeps, generated files, and external credentials behind markers.
+
+## Implementation Rules
+
+- Validate inputs at framework boundaries.
+- When ingesting a dynamic set of headers by prefix, whitelist each derived key against a strict token/charset regex and reject empty or malformed keys; do not trust the shape of externally-supplied header names.
+- Use typed Pydantic or framework schemas for public APIs.
+- For finite domain values such as market, region, status, scene, source, provider, priority, permission, or channel, define a domain-owned `Enum`/`Literal` alias/constant set plus one parser or canonicalization helper before using the value across service, repository, schema, or tests. Transport enums, query/header strings, DB strings, and generated-client values convert at the boundary; business logic and tests reuse the domain symbols.
+- Pass request/trace context through external calls where the stack supports it. The carve-out is narrow and behavioral: only a genuinely side-effect-free function — no external calls, task spawning, filesystem/env, clock/random, or logging/trace/tenant/feature lookup across its body and callees — may omit it. A mapper or helper that does, or later gains, any such call takes it. The test is behavior, not the name.
+- Set timeouts for HTTP/DB/Redis/MQ/inference calls.
+- Honor cancellation and request deadlines in async code.
+- Do not block the event loop with sync clients, CPU-heavy processing, large file I/O, or GPU work.
+- Use SQLAlchemy/Django transactions for multi-step writes inside one database.
+- Keep SQLAlchemy, SQLModel, Django ORM, and raw SQL behind repository or data-access modules; routes/views and business services should not scatter SQL or ORM query construction.
+- When a reference stack exposes unit-of-work or session/transaction-bound repositories, reuse or add that shape instead of passing raw sessions through business code. Service logic should enter one transaction boundary, then call repositories bound to that session, transaction, or unit of work.
+- For DB-heavy services, prefer shared unit-of-work or transaction helpers that recover/rollback on exception, and add non-production query-safety checks where the repo has ORM hooks, query builders, migration metadata, or test infrastructure to support them. If the repo cannot mechanically check missing indexes or full scans yet, record the platform gap and cover changed high-risk queries with migration/repository review evidence, bounded pagination assertions, or focused tests. These checks should become framework or repository behavior, not reviewer folklore.
+- Keep migrations, model changes, repository changes, and rollback notes together.
+- For Python microservice work, keep API/OpenAPI or gRPC contract changes, generated clients, service-client adapters, auth headers/tokens, timeout/retry policy, and deployment config in the same implementation slice when they change together.
+- Treat queue delivery as at-least-once; consumers must be idempotent.
+- Queue producer/consumer wrappers should centralize metadata propagation, topic/routing-key/filter config, worker sizing, retry/drop behavior, exception recovery, close/drain lifecycle, latency/error metrics, and replay or DLQ visibility. Business handlers should implement domain work and idempotency, not recreate consumer scaffolding.
+- Treat write retries as unsafe by default. Add automatic retry only when the operation has a durable idempotency key, unique constraint, state machine, dedupe table, or equivalent proof, and test duplicate submit/callback/queue/job-restart behavior.
+- For money, quota, entitlement, permission, tenant/user isolation, privacy, and sensitive state changes, fail closed on uncertainty and return the canonical error before side effects.
+- Do not default missing tenant, actor, subject, or resource scope on high-risk paths. Reject before side effects unless the code is an explicit bootstrap, seed, or maintenance path with separate approval.
+- Do not rely on Redis-only, TTL-only, memory-only, or process-local dedupe for durable side effects. Use persistent idempotency or a state machine when the side effect is auditable, billable, externally acknowledged, or hard to reverse.
+- Commit primary mutations with audit/outbox/governance evidence in one transaction when possible. If not possible, create a replayable repair record, surface stale/pending counts, and test the reconciliation gap.
+- For high-risk user-visible operations, persist or return a stable request/task/order/support identifier and keep logs, audit records, or metrics sufficient for support explanation and compensation.
+- Use Redis locks with unique values and compare-and-delete unlock.
+- Centralize Redis keys, TTLs, lock leases, counters, and rate-limit scopes.
+- Keep config typed and environment-specific.
+- Do not hard-code registry endpoints, provider URLs, secrets, or production fallbacks. Missing production config for high-risk capabilities should keep the capability disabled or fail startup, not silently switch to a local/test default.
+- For high-risk config, add typed settings, production-safe defaults, tests for disabled/missing config, and explicit enablement checks before behavior can run.
+- Use pytest fakes/mocks for external clients by default; reserve live dependency tests for explicit integration gates.
+- High-risk external flows that depend on real credentials, callback delivery, MQ/DB semantics, private-network services, or external model/runtime behavior need an explicit release-blocking integration, sandbox, replay, or manual evidence gate outside the default fast target. If that gate is unavailable, record the blocker, residual risk, and next unblock action instead of claiming fake-only confidence is complete.
+- Python AI/service-host tests that require live model servers, real datasets, private-network endpoints, long sleeps, or manual scripts are integration/manual evidence. Keep the default fast gate on deterministic handler, router, config, readiness, metadata, parser, and error-mapping assertions, but do not use the fast gate alone to close high-risk runtime integration.
+- Comments state invariants and why, not status snapshots that rot ("X is the only implementation", line counts, "temporary tool"). A comment claiming a guarantee the code does not provide (e.g. a per-attempt timeout that is never actually set) is worse than no comment; in review, treat every guarantee a comment claims as an assertion to verify against the code.
+- Code that will live in production must not carry temporariness-implying names (spike/minimal/temp). Transitional scaffolding must state its retirement condition and expected retirement point explicitly, or it is not transitional.
+- When bumping a shared dependency's version, change it across **every** consuming package/module, not only the obviously-affected ones — including indirect consumers that reach the dependency through a local/editable path install or that independently pin the same transitive dependency. Keep the version consistent everywhere it is declared (e.g. `pyproject.toml`, lockfile, and package `__version__` when present), then run the **full** test suite (not just the directly-related extra/subset) and update any test that hard-asserts the dependency pin/version. A consumer left on the old pin fails only later, often masked as a CI dependency-resolution error.
+- For Python package releases, this skill owns package internals and tests; route registry upload, duplicate-publish recovery, simple-index metadata checks, and registry-only install verification through `platform-release-engineering/references/python-package-registry-release.md`.
+
+## 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 feature implementation steps, read `references/feature-playbook.md`.
+- For project layout, package roots, uv/poetry/pip, import mode, and tooling, read `references/project-structure-and-tooling.md`.
+- For FastAPI, Flask, Django, routes/views, dependencies, and app factories, read `references/web-framework-patterns.md`.
+- For Pydantic/OpenAPI/schema validation and generated clients, read `references/schema-and-validation-patterns.md`.
+- For public API implementation, partner app auth, signature verification, callback handling, authorization scope, and API security tests, read `references/public-api-security-patterns.md`.
+- For SQLAlchemy/Django ORM, Alembic, migrations, repositories, and transactions, read `references/sqlalchemy-and-migrations-patterns.md`.
+- For asyncio, blocking work isolation, concurrency limits, and cancellation, read `references/async-and-worker-patterns.md`.
+- For Redis, cache, locks, idempotency, counters, and rate limits, read `references/redis-cache-lock-patterns.md`.
+- For Celery/RQ/arq, queues, scheduled tasks, and job execution, read `references/background-job-patterns.md`.
+- For external HTTP clients, SDKs, generated clients, service discovery, and dependency adapters, read `references/dependency-client-patterns.md`.
+- For errors, exception mapping, response envelopes, and validation errors, read `references/error-handling-patterns.md`.
+- For logs, metrics, traces, health checks, and instrumentation, read `references/observability-implementation-patterns.md`.
+- For pytest, async tests, fakes, fixtures, markers, ruff, mypy/pyright, and CI gates, read `references/testing-and-quality-patterns.md`.
+- For Python API/worker wiring around LLM/RAG/inference systems, read `references/ai-service-wiring-patterns.md`.
+- For import/export, backfill, repair scripts, generated artifacts, and batch reports, read `references/batch-and-artifact-patterns.md`.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Python Service Dev"
+  short_description: "Build Python backend and service features"
+  default_prompt: "Use $python-service-dev to implement a product-agnostic Python backend feature in the smallest service, worker, package, or script shape justified by the repo and boundary evidence."

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/ai-service-wiring-patterns.md

@@ -0,0 +1,16 @@
+# AI Service Wiring Patterns
+
+Use this for Python implementation around LLM/RAG/inference calls after `llm-inference-integration` has defined the inference behavior.
+
+## Wiring
+
+- Keep provider adapters separate from route handlers and domain orchestration.
+- Add timeout, retry, rate limit, circuit-breaker/backpressure, and cost/usage logging where needed.
+- Handle streaming with cancellation, heartbeat, and terminal error events.
+- Persist request, response, citation/source, and audit metadata only according to product privacy rules.
+- For CPU/GPU-heavy local inference, isolate concurrency and memory limits.
+- Use fakes for provider tests and mark live provider tests explicitly.
+
+## Do Not
+
+- Encode prompt policy, retrieval strategy, evaluation rubric, or model routing here; route those decisions to `llm-inference-integration`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/async-and-worker-patterns.md

@@ -0,0 +1,24 @@
+# Async And Worker Patterns
+
+Use this for asyncio, async endpoints, workers, blocking work, and cancellation.
+
+## Async Rules
+
+- Bound `asyncio.gather` with semaphores, pools, or queue limits.
+- Use `asyncio.timeout`, client timeouts, or framework timeout controls where available.
+- Use `asyncio.to_thread` only for bounded blocking calls that are safe to run in a thread.
+- Do not run CPU-heavy work in the event loop.
+- Clean up async clients through lifespan, context managers, or explicit close hooks.
+- **`asyncio.TaskGroup` (Python 3.11+) is the default structured-concurrency primitive for fan-out work; prefer it over `asyncio.gather`** for any code where partial failure should cancel siblings. Per Python docs: when a child task raises, TaskGroup cancels remaining scheduled tasks; `gather(return_exceptions=False)` does not — sibling tasks keep running to completion, which is the wrong default for most fan-out (each leak burns a request budget or external rate-limit). Use `gather` only when partial success with independent siblings is the intended contract (and even then, pair with bounded concurrency + per-task timeout). Wrap TaskGroup with `async with asyncio.timeout(...):` for deadline enforcement, NOT per-task timeouts when the whole batch shares a deadline. **Exception-shape gotcha when outer timeout fires concurrently with a sibling failure**: the outer `asyncio.timeout()` cancels the TaskGroup scope; `TaskGroup.__aexit__` drains children and propagates failures as an `ExceptionGroup`. If a sibling raised an application error before the timeout cancellation completed, you do NOT receive a clean `TimeoutError` — you receive an `ExceptionGroup` containing both the application error AND a `CancelledError` (or `TimeoutError`) from the cancellation. Handle both shapes with `except* asyncio.TimeoutError` AND `except* DomainError` AND a fallback `except* BaseException`; do not assume `except TimeoutError` will catch the deadline case, because in this race it does not.
+- **Handle TaskGroup failures with `try / except*` (PEP 654 ExceptionGroup, Python 3.11+) rather than `except Exception`** — when multiple sibling tasks fail, TaskGroup raises an `ExceptionGroup` (or `BaseExceptionGroup` for cancellation cases) that bundles all errors; a bare `except` strips the multi-error structure and discards diagnostics. Pattern: `try: async with asyncio.TaskGroup() as tg: ... except* SomeTransientError as eg: ... except* SomeFatalError as eg: ...`. Each `except*` handler receives an ExceptionGroup containing only the matching subset, and unmatched exceptions re-raise as a residual group. Document in API contracts that operations using TaskGroup may raise ExceptionGroup so consumers wrap with `except*`, not `except`.
+- **Never swallow `asyncio.CancelledError` inside async code that runs under TaskGroup or `asyncio.timeout`** — Python docs warn that those structured-concurrency primitives are implemented via cancellation internally; a `try/except Exception` that catches CancelledError (because CancelledError is a `BaseException` in 3.8+ but some code still catches it as a transient) prevents the cancellation from completing and leaves the task group / timeout in an inconsistent state. Re-raise CancelledError explicitly after any cleanup, or use `except Exception:` (which excludes BaseException) so CancelledError propagates naturally.
+
+## Worker Rules
+
+- Use workers for long-running or retryable work.
+- Store progress and terminal status when user-visible work outlives a request.
+- Separate the setup lifetime from the spawned-worker lifetime: work that must outlive the request must not be a child of the request's structured-concurrency scope — do not put it in a request-owned `TaskGroup`, and do not `await` it under the request's `asyncio.timeout` — or it is cancelled when the request ends. But "outside the request scope" is not fire-and-forget: register it with an application-lifetime supervisor / durable queue / tracked task registry that keeps a strong reference (a bare `asyncio.create_task` can be garbage-collected and lose its exception), observes failures, and gives the worker its own bounded deadline. The request handler's own setup still honors request cancellation; cancelling the request after the task is registered must not cancel it, and cancelling setup must not orphan an already-registered task.
+- An exception inside a detached execution never reaches framework/request exception handlers: a bare `asyncio.create_task` failure surfaces only via the loop exception handler when the task is garbage-collected, a `threading.Thread` dies silently, an executor future swallows the exception until awaited, and a queue-job body gets only what the worker runner is configured to record. Route every production detached spawn (task, thread, executor submit, job body) through one shared firewall wrapper that catches, logs the traceback with the trace/correlation id, and increments a failure metric; enforce coverage with a checklist or lint, not memory. The only rigorous regression proof for "the process/worker survives this exception" is a subprocess exit code: a test runs a child process that triggers the exception inside the detached execution and asserts it exits cleanly — an in-process assertion cannot prove process survival. Scope that proof to per-item/per-request work where catch-and-continue is the policy; for a supervisor or global-invariant task (scheduler loop, registry owner), the test asserts the opposite — the worker goes non-serving/unready or exits nonzero on purpose rather than continuing on corrupted state.
+- For any async side-path that outlives the request (audit, ledger, usage reporting, notifications), the working posture is four pieces together: detach the lifecycle but keep only correlation — re-attach the correlation/trace fields of the contextvars snapshot per `redis-cache-lock-patterns.md` rather than dropping the correlation id, but never a wholesale snapshot replay that smuggles request auth/session/secrets into work outliving the request (whitelist correlation + durable work-item identity; the worker runs under service identity), detaching only at the accept boundary for an already-accepted work item with its own bounded deadline; for the service's own rollbackable mutations the accept boundary is durable commit success — or a same-transaction/outbox row that commits and rolls back atomically with the mutation: before that, caller cancellation suppresses side-path work and nothing detached may be enqueued against an in-flight commit (a commit that fails, rolls back, or returns unknown must never leave a fired detached record — and idempotent reconciliation of an unknown outcome requires a durable intent/reconciliation key written with or before the mutation, the outbox row being exactly that key; post-commit async capture without such a durable key is a blocked design for audit/billing-relevant records unless unknown outcomes are impossible or reconciliation is provable from durable authoritative state); after it, capture is mandatory and not gated on the caller still being connected; records of NON-rollbackable external side effects (a provider call that already consumed quota) invert the order — book a per-attempt reservation/outbox row independently of the local outcome, with idempotent reconciliation; a bounded queue or semaphore; shutdown ordering where accepting new submissions and draining are serialized so no submit can race the drain — mark closed, stop accepting, then drain with a deadline without holding the accept lock through the drain wait (drain/flush paths must not need it, or shutdown deadlocks); and a loss policy matched to the data class: explicitly accepted bounded loss + a reconciliation/repair job only when a tested idempotent reconstruction source exists — for billing/ledger/usage data with no such source, use a same-transaction outbox or backpressure instead of drop.
+- Make retries idempotent.
+- Include exception handling, logs, metrics, and retry-vs-drop behavior.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/background-job-patterns.md

@@ -0,0 +1,18 @@
+# Background Job Patterns
+
+Use this for Celery, RQ, arq, APScheduler, queue consumers, and scheduled tasks.
+
+## Job Implementation
+
+- Define typed payloads.
+- Add idempotency keys.
+- Bound retries and backoff.
+- Distinguish retryable, drop, quarantine, and terminal failures.
+- Store status for user-visible jobs.
+- Protect singleton jobs with locks or scheduler guarantees.
+
+## Request Boundary
+
+- Do not hide long work behind a synchronous request unless the timeout budget proves it is safe.
+- Return job IDs or status URLs for long-running work.
+- Make cancellation and duplicate submissions explicit.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/batch-and-artifact-patterns.md

@@ -0,0 +1,13 @@
+# Batch And Artifact Patterns
+
+Use this for import/export scripts, backfills, reports, generated files, CSV/XLSX/PDF artifacts, and repair tools.
+
+## Implementation
+
+- Add dry-run mode for destructive or broad updates.
+- Use chunking, checkpointing, and resume for large jobs.
+- Bound concurrency and external dependency rate.
+- Write error reports for partial failures.
+- For object or artifact migration, record success, error, skipped, and conflict rows in replayable output so reruns can resume or audit decisions without re-discovering every item.
+- Make output artifact paths, object storage keys, retention, and download permissions explicit.
+- Test parsing, validation, edge rows, and retry/resume behavior.

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

@@ -0,0 +1,39 @@
+# Dependency Client Patterns
+
+Use this for external HTTP clients, SDKs, object storage, service discovery, generated clients, and inference clients.
+
+## Rules
+
+- Create clients through explicit providers or app startup, not scattered constructors.
+- Import-time or module-level convenience clients must be replaceable through dependency overrides, app lifespan wiring, or provider injection. If initialization can perform network I/O or fail, keep it in startup/bootstrap and expose constructors that return ordinary errors for request-time dependencies.
+- A must-never-break-the-caller adapter over an OPTIONAL dependency catches `Exception` on import/init, not just `ImportError` — a third-party module's import-time side effects can raise anything — but does not swallow `BaseException` subclasses such as `KeyboardInterrupt`/`SystemExit`. Degrade to a safe default and test the raising-import path, not only the missing-module path.
+- Set timeout, retry, base URL, credentials, user agent, and observability labels.
+- **A middleware/client WRAPPER (interceptor, governance layer) owns deadline *propagation*, not a fixed timeout *policy* — but every production call still gets a bounded effective deadline.** Honor the caller's deadline (the `context` / `asyncio.timeout` the caller set); don't bake an arbitrary fixed default into a wrapper that overrides it. But "no wrapper default" ≠ "unbounded": a caller with no deadline plus a hung dependency pins tasks/connections forever, so apply an **env-configured max backstop** as the effective deadline when the caller supplies none, overridable at the call site, with an explicit opt-out only for long-lived watch/stream calls **that still bound their own liveness** (idle/read timeout, heartbeat, bounded reconnect, cancel cleanup) — opt-out is from the request deadline only, not from all bounds, or a half-open stream pins tasks/connections forever. Clamp **every untrusted/external inbound deadline** — an inbound gRPC `grpc-timeout` as much as an HTTP deadline header — to platform min/max **before** honoring or propagating it, or an external caller sets a huge deadline to hold resources (slow-DoS). Propagate with the transport's **native** deadline mechanism where it exists (gRPC `grpc-timeout`, propagated + decremented), not a reinvented header — but an HTTP client's own timeout bounds only the *local* call and is **not** sent downstream: HTTP has no native on-wire deadline, so cross-hop propagation needs an explicit deadline-header contract, and that header is untrusted (strip a caller-supplied one at ingress; generate the internal one from the server-side clamped context). Don't add an *independent competing* timer, but a **derived** per-attempt cap is correct — `per-attempt = min(caller-remaining, configured max)`; and before each retry recompute the remaining budget and **skip** the attempt when it can't cover attempt + backoff + cleanup (doomed retries amplify overload).
+- Validate status codes and response schemas.
+- Wrap provider-specific exceptions into canonical service errors.
+- Provide fakes for tests.
+- Close async clients and connection pools.
+- **Per-object state registries: release on lifecycle, and never key by `id()`.** When you keep state in a long-lived dict/registry tied to a per-object thing (a DB engine, connection, session, or client — e.g. per-engine listeners or per-connection counters), release the entry when that object is closed/disposed, or it leaks for the process lifetime. Do NOT key the registry by `id(obj)` — CPython **reuses** `id()` values after an object is garbage-collected, so a retained stale entry silently attributes one object's state to a *different, later* object. Prefer a `weakref.WeakKeyDictionary` (auto-releases when the object is collected) — but it needs **hashable, weak-referenceable** keys (a class with `__slots__` and no `__weakref__`, most C-extension/builtin types, or a type with `__eq__` but no `__hash__` raises `TypeError`); for those, use an owned stable token/wrapper plus a deterministic delete on close. It also keys by the object's `__eq__`/`__hash__`, **not identity** — a key type with value-based `__eq__`/`__hash__` aliases two distinct live objects into one entry (cross-attribution), so require identity equality/hash (default `object` identity) or key by an owned per-object identity token. And it only auto-releases when the stored **value does not strongly reference the key** — a listener/closure/back-pointer capturing the object keeps it alive, so the weak key never collects and you still leak; when values can reach the key, deterministic close-delete is mandatory, not weak auto-release. Make the registry own its lock: keep the `closed`/tombstone flag and the state under the **same** critical section, reject post-close get/create, and drain in-flight users before the final delete — otherwise a concurrent thread/task recreates stale state right after disposal. Keep the closed flag on the object itself (not only in the registry entry) so the delete doesn't erase the tombstone and let a later call on the still-referenced object recreate state.
+- **Adapter / fake / test-substitution boundaries are typed with `typing.Protocol` (PEP 544, structural typing), not abstract base classes**. The Protocol declares the surface the application code needs (`def get(url: str) -> Response: ...`); production client and test fake both satisfy it implicitly — no inheritance, no registration. Reserve `abc.ABC` / nominal base classes for cases where you genuinely need an authoritative runtime type gate, or a published-package public hierarchy that downstream code subclasses. If a Protocol must be used with `isinstance`, decorate it `@runtime_checkable` and treat the check as a shallow runtime guard (it checks attribute presence, not signature shape) — prefer ABC / nominal base classes when the runtime gate must be authoritative. Do not invent an `IUserRepository` per concrete class out of habit — that is Java-style nominal interface inflation; Python's structural typing makes it unnecessary.
+
+## HTTP Clients
+
+- Prefer `httpx` for modern sync/async clients when repo conventions allow it.
+- Use `aiohttp` only when the project standard or dependency requires it.
+- Avoid `requests` inside async endpoints unless isolated.
+
+## Dynamic Config And Discovery
+
+- Wrap service discovery, secret lookup, and dynamic config behind typed provider classes or functions; do not let raw backend keys, registry metadata, or secret-store payload shape leak into route or domain code.
+- Centralize namespace and backend key construction in the provider; list/watch APIs should return caller-facing keys or documented resume markers.
+- Cache hot config reads with a bounded TTL only when stale behavior is acceptable, and expose cache hit/miss/error metrics when the stack supports it.
+- Listener or watch callbacks should recover/log exceptions, update local cache atomically, and stop cleanly during application shutdown.
+- Tests should cover missing config, malformed payloads, dependency failure, cache behavior, and dependency override/fake behavior.
+
+## Object Storage
+
+- Add source service, environment/lane, request id, ownership, retention, and content metadata on writes when the provider supports it.
+- For copy or migration tools, define overwrite/conflict policy before transfer, tag migrated objects with source identity, emit replayable success/error/conflict records, bound concurrency, and close or flush report writers on shutdown.
+- Signed URLs must have explicit expiry and requester scope; do not log full signed URLs when they contain credentials.
+
+Evidence note: object-migration rules here are generalized backend mechanics from Go shared-package evidence, not Python-source confirmation. When a Python codebase has its own object-migration framework, confirm or narrow these rules against that framework before treating them as local convention.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/error-handling-patterns.md

@@ -0,0 +1,26 @@
+# Error Handling Patterns
+
+Use this for exceptions, HTTP errors, validation errors, and response envelopes.
+
+> Sibling sync: the Go counterpart `go-microservice-dev/references/error-contract-patterns.md` holds the **canonical** shared error-model invariant list (canonical typed error model; convert only at the transport boundary; no internal/secret leak; structured-details envelope, not a freeform status-message string; closed classification enums with fail-closed defaults, classification correct before retry/fallback policy). This file must stay consistent with that list rather than restating it. Advisory — there is no automated parity gate; keep in sync by hand.
+
+## Rules
+
+- Keep one canonical error mapping per service.
+- Convert internal exceptions at transport boundaries.
+- Preserve original exceptions in logs where safe, but do not expose stack traces or secrets in API responses.
+- Use typed domain exceptions for expected business failures.
+- Do not simulate errors at the API/transport boundary with return-value shapes — `(data, err)` tuples, `None` plus a message, or `{"success": false}` / ad-hoc `{code, message}` dicts smuggled into the data payload. Expected failures raise typed exceptions (EAFP). A pure/domain layer MAY use an explicit `Result`/`Either` value internally — but **"boundary" is defined by behavior, not file/module name**: any code whose return value is serialized to an HTTP/RPC/WebSocket/job-terminal response is boundary code and must raise a typed exception or emit the canonical envelope, never return a `Result`/dict as the wire payload. Relabeling a handler as "domain" does not exempt it.
+- Treat validation errors as client errors; treat dependency failures according to retry/fallback policy.
+- For shipped response envelopes and error payloads, keep client-readable fields, status/code meanings, and business-data locations stable by default. Removing legacy fields or changing where clients read success/error information is a breaking contract change and requires explicit human approval plus a compatibility, rollout, and rollback plan.
+- Test edge cases for error envelopes, status codes, and partial failures.
+
+## Cross-RPC Typed Error Envelope (Cross-Stack)
+
+When Python services participate in a portfolio that propagates typed errors across gRPC / Kitex / HTTP boundaries with a shared envelope:
+
+- Server side: convert internal exceptions — validation failures, RPC timeouts, dependency errors, panics — to the canonical typed error class and serialize it into the transport-level error slot per protocol. For gRPC, encode structured details via `google.rpc.Status` with `details` (carried in the `grpc-status-details-bin` trailer or via the framework's documented details mechanism); do NOT pack JSON into the freeform `status.message` string — that loses typed retry/security semantics and risks leaking server-rendered text. For HTTP, use the response body envelope `{code, message, data}`. Never let bare Python exceptions leak across the boundary.
+- Client side: extract the canonical structured shape from the protocol-specific channel (gRPC `details` / HTTP body envelope) and reconstruct the typed error so callers can branch on `code` and use `isinstance` / pattern matching on the recovered error class. Parsing the freeform gRPC status text as JSON is fallback-only; wrap unknown wire shapes as a transport/unknown error without dropping the original cause.
+- Numeric Code range allocation is portfolio-wide; Python services raising biz codes must use the same allocation table as Go services. Codes outside the allocated range fail at registration, not at runtime.
+- i18n boundary: error messages in the envelope are one language (typically English). User-facing translations live in the gateway or front-end keyed by the code; do not localize on the Python producer side.
+- Standard library wrap compatibility: prefer raising chained exceptions with `raise NewError(...) from cause` inside one process; when crossing a transport boundary forces JSON serdes, keep a reverse-path that reconstructs the chain on the client side rather than silently dropping it.

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

@@ -0,0 +1,43 @@
+# Feature Playbook
+
+Use this for concrete Python service implementation.
+
+## Steps
+
+1. Locate the project root and commands.
+   - Prefer `pyproject.toml` and lockfiles over guessing.
+   - Identify framework app, package root, tests, migrations, and scripts.
+2. Define the contract.
+   - Pydantic/OpenAPI, Django serializer/form, generated client, or protobuf.
+3. Define state changes.
+   - ORM model, migration, repository, transaction, cache, queue, or artifact.
+4. Implement the use case.
+   - Keep route/view thin and put decisions in service/domain code.
+5. Add focused tests.
+   - Unit for pure logic, API/contract for route behavior, integration only when real dependency behavior matters.
+6. Run the repo's quality commands.
+   - pytest target, ruff, mypy/pyright, formatting, migrations/codegen checks.
+
+## Common Implementation Slices
+
+- New HTTP endpoint: update schema/OpenAPI or serializer first, add route/view wiring, keep handler thin, pass resolved auth/context into service code, add API/contract tests for success and canonical failures.
+- New repository or DB mutation: design model and migration together, keep transaction scope explicit, add rollback/error-path tests, and verify pagination or uniqueness/idempotency behavior when relevant.
+- New Redis cache/lock/idempotency path: define key namespace, tenant/resource scope, TTL, miss/error behavior, compare-and-delete unlock, and tests for expiry or duplicate submit.
+- New queue or background worker: define payload schema, retry/drop/DLQ policy, idempotency key, concurrency bound, graceful shutdown, metrics, and duplicate-delivery tests before business handler logic.
+- New external or inter-service client: define typed request/response, auth/signature headers, timeout, retry policy, error mapping, trace propagation, fake client, and integration marker for live contract checks.
+- New generated artifact or report: render from typed inputs, write under a controlled output path, compare parsed structures or stable golden files, and verify generated-file drift in CI when deterministic.
+
+## Public API And Callback Security
+
+- Authenticate before trusting request body, query, path, or header identity fields unless signature verification requires canonical raw body bytes.
+- Resolve actor, tenant, resource scope, app/integration source, and permission from authenticated context; client-supplied owner/creator/scope fields are claims, not authority.
+- Validate signatures/tokens, timestamp windows, nonce or request id replay protection, payload schema, event type, and resource id before callback side effects. State-changing public APIs and callbacks require replay defense unless the exception is explicitly read-only or already idempotent.
+- Cache dynamic auth config briefly and fail closed for unknown app ids, disabled integrations, malformed config, expired timestamps, signature mismatch, or permission lookup errors.
+- Add tests for signature canonicalization, timestamp expiry, replay, spoofed owner/tenant/scope fields, duplicate callback delivery, malformed payloads, and unknown event types. Keep provider sandbox/live-callback tests outside the default fast target.
+
+## Do Not
+
+- Add untyped dictionaries at API boundaries when the repo uses schemas.
+- Introduce hidden global clients or import-time network I/O.
+- Mix live dependency tests into default fast test suites.
+- Copy local business terms from source examples into generic implementation rules.

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

@@ -0,0 +1,31 @@
+# Observability Implementation Patterns
+
+Use this for logging, tracing, metrics, health checks, and instrumentation.
+
+## Implementation
+
+- Add request IDs and trace IDs to logs.
+- Use structured JSON logs when the service runs in aggregated logging environments.
+- Instrument FastAPI/Flask/Django, HTTP clients, DB clients, Redis, queues, and inference calls when supported.
+- Add runtime base attributes such as service name, environment, region/lane, process or worker group, pod/host identity, and version once at the recorder/provider layer; feature code should add only operation-specific attributes.
+- Keep metric labels low-cardinality and bounded. Do not use raw path parameters, user IDs, request IDs, prompt text, provider payload values, or free-form error strings as labels.
+- For HTTP/RPC/worker metrics, combine stable runtime attributes with endpoint, operation, status, canonical error code, and duration; use logs or traces for high-cardinality details.
+- Add health and readiness endpoints according to deployment needs.
+- Do not log secrets, tokens, raw PII, or full provider payloads unless explicitly safe.
+- Add tests for logging, tracing, and metric-label helpers when they are shared packages.
+
+## Metric Naming And Standard Label Set (Cross-Stack)
+
+Match the portfolio's cross-stack metric naming so Python services compose with Go services on the same dashboards.
+
+- Metric name shape: `{category}_{operation}_{suffix}` snake_case. Categories name the surface (`http_server`, `grpc_server`, `grpc_client`, `worker`, `db`, `cache`); operation names what happens (`request`, `invoke`, `task`); suffix names what is measured (`qps`, `latency`, `err_qps`, `success_rate`).
+- Define metric names in one central module (e.g., `app/observability/metric_names.py`); inline string literals in handlers are a regression.
+- Use the portfolio's base label set for RPC/HTTP metrics so cross-service joins work without renaming: `caller`, `caller_cluster`, `caller_env`, `caller_method`, `callee`, `callee_cluster`, `callee_env`, `method`, `err_code`. New labels go through cardinality review.
+- Never use high-cardinality identifiers (user id, tenant id, request id, trace id, prompt text) as metric labels. They belong in traces and logs.
+
+## Ctx-Aware Logger Trace Linkage (Cross-Stack)
+
+- Wrap the chosen logger (structlog, stdlib logging with a formatter, or loguru) so it accepts the active context and automatically emits trace identity: `_trace_id`, `_span_id`, `_trace_flags`, and a request/log id field (`_logid`, `request_id`, etc.). Callers do not pass these manually.
+- Pair logs with the active OTel span: at warn/error level, add `span.add_event(message, attributes)` so the trace backend correlates logs without manual join. Flip span status to error only at logical error boundaries (handler entry/exit, dependency call failure), not on every warn.
+- For async/await, use `contextvars` to carry the logger context across `await` and `asyncio.create_task` boundaries. When spawning a task that should join the parent trace, capture the current OTel context at task-creation time via `opentelemetry.context.get_current()` (or `contextvars.copy_context()` for the broader ctx) and re-attach inside the spawned coroutine via `context.attach(captured) / context.detach(token)` so spans created in the child task become children of the originating span. Without this snapshot, `asyncio.create_task` inherits the contextvar snapshot at task-creation but subsequent OTel SDK calls in the child can still race with the parent's span lifecycle if the parent ends first.
+- Configure the OTel resource (`service.name`, `service.namespace`, `service.version`, `lane`, `pod.ip`, `pod.name`) once at startup; per-call attributes belong on individual spans.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/project-structure-and-tooling.md

@@ -0,0 +1,24 @@
+# Project Structure And Tooling
+
+Use this for Python package layout, dependency management, imports, linting, and type checking.
+
+## Discovery
+
+- Find `pyproject.toml`, `uv.lock`, `poetry.lock`, `requirements.txt`, `setup.py`, and workspace configuration.
+- Identify package mode: app package, `src/` layout, namespace package, Django project, generated client, or script-only project.
+- Use the repo's configured commands before inventing new ones.
+
+## Tooling Defaults
+
+- Prefer `pyproject.toml` for pytest, ruff, mypy/pyright, and package metadata.
+- Keep runtime and dev dependency groups separate.
+- Use lockfiles for deployable services.
+- Use `pytest --import-mode=importlib` when the repo standard sets it.
+- Do not rely on developer-local absolute paths or implicit `PYTHONPATH` in durable commands.
+- **`uv` (Astral, Rust-based) is the current default-recommendation single-tool stack for most pure-Python service workflows** — covers the pip + pip-tools + virtualenv + pipx + (most of) poetry + pyenv use cases with one static binary. Per Astral docs: ~10-100x faster than pip on resolve/install; built-in Python version management (`uv python install`), Cargo-style workspaces, cross-platform `uv.lock` reproducible builds. Drop-in pip-compatible interface via `uv pip` for migration. **Validate per-project edge cases before declaring full replacement**: editable installs in deeply nested monorepos (workspace path resolution rules differ from poetry / pip), private PyPI index auth (`.netrc` / keyring / index-url env precedence), post-install hooks (`pip install` script-execution semantics), conda-managed environments (uv does not replace conda's binary-package channel), vendored wheel directories used as offline indexes, Debian/RHEL system-Python policies (uv-installed Python lives parallel to system Python, which can confuse system service managers expecting `/usr/bin/python3`). When picking up an existing project: keep its established stack (poetry / pip-tools / pdm / rye / hatch) rather than forced-migrate during normal feature work; schedule the uv switch as its own slice with lockfile parity verified. The "single tool replaces N tools" framing means CI pipelines, Dockerfiles, dev-onboarding docs, and CI cache configs all need to flip together — not piecemeal.
+- **PEP 723 inline script metadata + `uv run script.py`** for one-off scripts, batch tools, ad-hoc data jobs, repair scripts, and report generators — replaces "create a venv just to run this" and `requirements.txt` siblings. Inline format: `# /// script` block at top of file declaring `requires-python` and `dependencies = [...]`, then `uv run script.py` auto-creates the ephemeral environment per PEP 723. **Reproducibility is NOT automatic**: `uv run` without an explicit lock will re-resolve dependencies each run against the latest matching versions — fine for ad-hoc local use, NOT for CI or production replay. Pin reproducibility by running `uv lock --script script.py` to produce `script.py.lock` adjacent to the script AND committing the sidecar lock to source control; CI should run `uv run --script script.py` against the committed lock. **Scope**: single-file scripts where the cost of a project skeleton (pyproject.toml + venv + install) outweighs the script's value. PEP 723 scripts CANNOT import internal first-party packages unless those packages are published to a private index (declared in `[tool.uv.sources]` inline) or referenced via `--with-editable` workspace paths — for scripts that need internal-package access, promote them to a proper project rather than fighting the inline format. Anything that grows past one file or gets imported by other code → promote to a proper project.
+
+## Generated And Vendored Code
+
+- Exclude generated clients, vendored libraries, migration output, and typings from strict lint/type rules when the repo already does so.
+- Do not edit vendored third-party code to satisfy project style checks.

package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/public-api-security-patterns.md

@@ -0,0 +1,52 @@
+# Public API Security Patterns
+
+Use this for implementing Python public APIs, partner integrations, signed callbacks, app credentials, authorization scope checks, and API security tests.
+
+## Auth Middleware
+
+- Keep bypass path lists explicit and small.
+- Preserve raw body bytes when signature verification requires them; otherwise authenticate before parsing domain payloads.
+- Extract only the untrusted selector needed to find verification material, such as app id or key id; load auth config; verify token/signature; then resolve app/user identity and authorization/resource scope.
+- Return canonical auth errors; log detailed causes with safe identifiers.
+- Do not mutate global auth settings per request.
+
+## App Credential Model
+
+- Store app id, secret/public-key reference, allowed source restrictions, allowed resource scopes, integration/source identity, status, and rotation metadata.
+- Generate secrets with cryptographic randomness and keep secret values out of logs, tests, docs, generated files, and fixtures.
+- Support disabled apps and rotated credentials.
+- If auth config is dynamic, cache briefly and fail closed for unknown app ids, disabled apps, expired credentials, or malformed config.
+
+## Safer Composition (Python 3.14+)
+
+- **Python 3.14 (released 7 October 2025) introduced t-strings via PEP 750** — template literals using `t"..."` syntax that evaluate to `string.templatelib.Template` objects rather than `str`, giving a consuming function access to interpolated values BEFORE they are combined into a string. The standard library exposes `string.templatelib.Template`. **t-strings are inert by themselves — they are NOT automatic injection protection by syntax**. A bare t-string only carries the raw values plus their surrounding template; safety arrives only when a trusted consumer library is t-string-aware and validates/escapes each interpolation according to its target language (SQL, shell, HTML). Writing `t"SELECT * FROM users WHERE id = {user_id}"` and passing it to an ORM/driver that has not added Template support gains nothing over an f-string — and passing it to a function expecting `str` triggers `Template.__str__()` which raises by default, surfacing the misuse rather than silently producing the wrong result. As of 2026-Q1: most popular template engines (Jinja2, Django templates) and most DB drivers do NOT yet consume `Template` directly — verify the specific library's Template support before relying on this rule. **PEP 787 (safer subprocess via t-strings) is currently Deferred to Python 3.15** per peps.python.org — PEP authors are pursuing experimental t-string subprocess work outside the stdlib through 3.14 beta before re-proposing for 3.15. Do NOT assume `subprocess.run(t"...")` works safely in 3.14; for shell/subprocess composition on 3.14, keep using `shlex.quote()` + argument-list form (`subprocess.run(["cmd", arg])`) until PEP 787 or its equivalent lands. For Python ≤3.13 targets, t-strings are unavailable — keep `shlex.quote()` / parameterized DB queries / framework-native HTML escaping; t-strings are a 3.14-and-later opt-in, not a backport.
+
+## Signature And Replay Verification
+
+- Canonicalize signed data before verification.
+- Include timestamp and nonce or request id in the signed payload.
+- Enforce timestamp windows and replay protection for state-changing APIs and callbacks. Allow an exception only for explicitly read-only or already-idempotent calls with documented rationale.
+- Use constant-time comparison for MAC/signature checks where applicable.
+- Prefer HMAC or asymmetric signatures for new integrations.
+
+## Authorization Scope
+
+- Treat client-supplied tenant, owner, actor, creator, account, permission, and resource fields as claims until resolved from authenticated context or an authoritative service.
+- For write paths, use the resolved authenticated identity as source of truth. Reject mismatches or overwrite client-supplied owner fields before domain logic.
+- Put resolved scope/source into typed request context and include it in cache keys, idempotency keys, rate limits, logs, and audit records.
+- Scope-check bypass must be explicit config with audit logging, not a hidden branch in handler code.
+
+## Callback Handler
+
+- Validate signature/token, timestamp, event type, resource id, and payload shape before side effects.
+- Convert provider event codes into internal enums at the boundary.
+- Persist a callback receipt or idempotency marker before expensive work when retries are expected.
+- Treat empty payloads, unknown event types, and malformed signatures as permanent failures unless provider contract says otherwise.
+
+## Tests
+
+- Unit-test signature canonicalization, timestamp expiry, replay handling, and authorization-scope checks.
+- Add spoofing tests for owner, actor, tenant, creator, account, permission, and resource fields in every accepted input surface.
+- Add fail-closed tests for auth, permission, profile-resolution, malformed config, and disabled integration errors before downstream side effects.
+- Add duplicate-delivery, malformed-payload, and unknown-event callback tests.
+- Use fake secrets in fixtures. Keep provider sandbox or live-callback tests behind explicit integration/live markers.

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

@@ -0,0 +1,78 @@
+# Redis Cache Lock Patterns
+
+Use this for Redis clients, keys, caches, locks, rate limits, and idempotency.
+
+## Implementation
+
+- Centralize key builders and TTL constants.
+- Include tenant/user/resource scope in keys when isolation matters.
+- Use unique values for locks and compare-and-delete unlock.
+- Renew locks with compare-and-expire when work can exceed one lease, and stop renewal on cancellation, timeout, or max lease.
+- Set timeouts on Redis clients.
+- Choose sync or async Redis clients to match the call path. Do not call sync Redis clients directly inside async request handlers or long-lived async loops unless the call is isolated through a thread/process boundary.
+- Build Redis clients through dependency assembly or app lifespan, and close clients/pools on shutdown. Per-request connect/read/close loops are acceptable only for narrow scripts or tools, not hot service paths.
+- Prefix keys through one adapter and keep pattern deletes bounded. If a method deletes by pattern, prefer `SCAN` with a limit/batch policy, observability, and tests for no-match and large-match behavior.
+- For JSON cache values, validate decode and schema. Treat malformed cached payloads as explicit cache corruption or miss according to product risk, and avoid letting decode errors bypass source-of-truth checks.
+- For compound atomic operations, use Lua scripts, Redis transactions, or a proven library rather than read-modify-write. Examples include compare-and-set, compare-and-delete, compare-and-expire, positive-only decrement, increment-if-exists, and atomic pop.
+- Define explicit return meanings for success, compare failure, and missing key; callers should not infer these from raw Redis values.
+- If using Lua scripts, load or register scripts during startup when possible; on missing script cache, reload and fall back once while emitting an observable metric or log.
+- Idempotency stores need separate pending, completed, duplicate, and retryable-failure meanings. A pending marker should have a short TTL or owner lease; a completed marker should live for the dedupe window; retry counters should fail safe when Redis is unavailable on high-risk paths.
+- Redis Streams need an explicit delivery contract: starting message id, heartbeat/no-message behavior, stream TTL/trim/delete policy, reconnect/resume behavior, and whether messages may be replayed or lost.
+- Do not let cache misses silently bypass authorization or data-integrity checks.
+- Keep cache invalidation close to writes or explicit events.
+
+## Tests
+
+- Use fake Redis for service-level tests when behavior is simple.
+- Use real Redis integration tests for locks, scripts, expiration, or cluster-specific behavior.
+- Test wrong-token unlock, renewal cancellation, missing-key semantics, malformed JSON payloads, pattern-delete boundaries, script reload/fallback, invalid return type handling, pending-vs-completed idempotency states, stream heartbeat/resume, and positive-only counters when those helpers exist.
+
+## Cache Stampede Defense
+
+Concurrent cache misses on a hot key turn into a thundering herd on the source of truth. Three defenses combine; pick all when miss cost is high.
+
+- Single-flight: when a miss is detected, only one coroutine/process performs the fetch while others wait or read a placeholder. Implement with a per-key `asyncio.Lock` in-process, plus a short-lived Redis lock (`SET NX PX`) for cross-process coordination; followers re-read the cache after the leader publishes the value.
+- Negative caching: cache the "not found" outcome with a shorter TTL (a few seconds to a minute) using a distinguishable sentinel value so distinct miss reasons (no row vs auth-denied) do not collapse into one cache entry.
+- TTL jitter: add randomized ±10-20% to every TTL so bulk-loaded keys do not expire in lockstep. Apply jitter at write time, not at read time.
+- For very hot read-mostly data, layer a short-TTL local cache in front of Redis so even Redis sees a flat load curve; coordinate invalidation through Pub/Sub or `CLIENT TRACKING` (RESP3) when staleness budget is tight.
+
+## Redis Cluster Slot And Hash Tag Rules
+
+When the deployment is Redis Cluster (or Cluster-compatible managed Redis), every multi-key operation must stay within a single hash slot.
+
+- Multi-key commands, `MULTI/EXEC`, Lua scripts, and pipelines that depend on key co-location must use hash tags: `user:{uid}:profile` and `user:{uid}:settings` share a slot because `{uid}` is the tagged section; `user:uid:profile` and `user:uid:settings` do not.
+- A Lua script that touches keys passed via `KEYS[]` will be rejected with `CROSSSLOT` if those keys hash to different slots; design key schemas with the smallest co-location set you need (per-user, per-tenant, per-aggregate) and document the hash-tag convention next to the key builder.
+- `SCAN` walks one cluster node at a time; cluster-aware delete-by-pattern means iterating all primary nodes, not the cluster as one space.
+- Pipelines across slots split into per-slot batches; do not assume a single round-trip.
+- Cluster clients refresh slot maps on `MOVED`/`ASK` responses; for very latency-sensitive paths cache the slot map in the client and refresh proactively on cluster topology change events.
+
+## TLS And IAM Authentication
+
+Production Redis traffic must be authenticated and encrypted; cloud-managed Redis adds IAM/AAD-based auth on top of (or instead of) static passwords.
+
+- Connect with TLS for any non-loopback Redis: pass `ssl=True` and a configured `ssl.SSLContext` to `redis.asyncio.Redis`. Share the `SSLContext` across clients to amortize handshake setup.
+- For managed Redis with IAM/AAD auth (AWS ElastiCache IAM, Azure Cache for Redis with AAD), credentials are short-lived tokens fetched per connection: configure the client with an auth callback that retrieves a fresh token (e.g., via boto3/azure-identity) and handle the token's TTL by rotating before expiry.
+- Use Redis ACL users for application accounts: grant the minimum command set required (no `FLUSHDB`, `CONFIG`, `DEBUG`, `KEYS`); store credentials through the platform secret provider, never inline in code or config files.
+- Do not log connection URLs that contain passwords or tokens; redact at the logger configuration layer.
+
+## Retry And Circuit Breaker Coordination
+
+Transient Redis errors (timeout, connection reset, `LOADING`, `BUSY`) sometimes warrant a retry; sustained failure warrants opening a circuit.
+
+- Retry only for transient errors: connection errors, read/write timeouts on idempotent reads, `LOADING`, and `BUSY` (script in progress). Do not retry application-level errors, wrong-type errors, or write commands when retry could double-apply.
+- Bound retries: max attempt count, exponential backoff with jitter, total deadline. A retry budget per request prevents amplification.
+- Pair retry with a circuit breaker per upstream identity (Redis cluster endpoint, sentinel set): open after consecutive failures, half-open after a cool-down probe, close on success. Do not retry inside an open circuit — return the fast-fail outcome the product has chosen for that path.
+- Coordinate with the lock and idempotency layer: a retry against a lock that you already hold should `COMPARE-AND-EXPIRE` not re-acquire; a retry against an idempotency store should treat duplicate `claimed` as success.
+- Surface retry count, breaker state transitions, and budget exhaustion as metrics; sustained breaker-open is a paging condition, not a normal mode.
+
+## OpenTelemetry Instrumentation Across Await
+
+Async Python loses span context easily when tasks are created outside the current `await` chain.
+
+- Use OTel auto-instrumentation for SQLAlchemy and Redis when the package is available (`opentelemetry-instrumentation-sqlalchemy`, `opentelemetry-instrumentation-redis`); enable it once at app startup.
+- For `asyncio.create_task`, `asyncio.gather`, and background workers, contextvars snapshot at task creation time — spans created in the parent after the child starts will not be visible to the child. Capture and re-attach context explicitly when launching a task that should join the parent trace (`context.attach(snapshot)` inside the task; `contextvars.copy_context().run(...)` for sync code launched from async).
+- Emit DB and Redis attributes per OTel semantic conventions: `db.system`, `db.name`, `db.statement` (sanitized), `db.operation`, `network.peer.address`; for Redis, also `db.redis.database_index` when applicable.
+- Do not emit raw SQL or raw key payloads as span attributes when they may contain secrets; use the framework's sanitization hook or a custom span processor.
+- Long-running coroutines and SSE/websocket handlers should periodically end the per-message span instead of one giant span per connection; otherwise traces become unusable.
+
+Evidence note: rules above derive from public specifications (SQLAlchemy 2.0 Async docs, Redis Cluster spec, Redis ACL/TLS docs, OpenTelemetry semantic conventions) and documented industry patterns (Cache-Aside variants, Circuit Breaker, Outbox via cross-stack reference). Lua/CAS/script-fallback rules earlier in this file were generalized from external Go evidence; under the portfolio-stability prefilter, the portfolio is not a confirmation baseline, so caveat wording elsewhere should be read as "generic best-practice baseline" rather than "pending verification".