feat: add ArchiPy 5 observability and app rules

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "archipy",
       "source": ".",
       "description": "Cursor and Claude Code plugin: rules, skills, and commands for building apps with ArchiPy",
-      "version": "0.8.0"
+      "version": "0.9.0"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "archipy",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Cursor and Claude Code plugin: rules, skills, and commands for building apps with ArchiPy",
   "author": {
     "name": "SyntaxArc"

.cursor-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "archipy",
       "source": ".",
       "description": "Cursor and Claude Code plugin: rules, skills, and commands for building apps with ArchiPy",
-      "version": "0.8.0"
+      "version": "0.9.0"
     }
   ]
 }

.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "archipy",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Cursor and Claude Code plugin: rules, skills, and commands for building apps with ArchiPy",
   "author": {
     "name": "SyntaxArc"

AGENTS.md

@@ -22,10 +22,15 @@ Consumer plugin for **apps that depend on** PyPI [`archipy`](https://pypi.org/pr
 | Helpers                         | `/scaffold-utils`, `/scaffold-decorator`, `/scaffold-interceptor`                                                                                    |
 | Redis search                    | `/redis-search` (full-text, vector, caching)                                                                                                         |
 | Health checks                   | `/scaffold-health-checks`, `/docs-health-checks`                                                                                                     |
+| OpenTelemetry                   | `/scaffold-observability`, `/docs-observability`                                                                                                     |
 | Docs                            | `/docs-quickstart`, `/docs-adapters`, `/docs-helpers`, `/docs-config`, `/docs-errors`, `/docs-testing`, `/docs-observability`, `/docs-health-checks` |
 
 Bundled cheat sheet: `skills/archipy-docs/reference.md`.
 
+When a command names a skill, read that skill's `SKILL.md` in full before generating files. Resolve
+`skills/*/reference/` templates from the plugin installation (`$CURSOR_PLUGIN_ROOT` or `$CLAUDE_PLUGIN_ROOT`), copy
+them into the app, and never edit plugin templates in place.
+
 Live docs: https://syntaxarc.github.io/ArchiPy/
 
 ## Hard rules (apps)
@@ -34,3 +39,17 @@ Live docs: https://syntaxarc.github.io/ArchiPy/
 - Domain adapters under `repositories/{domain}/adapters/` — not a top-level app `adapters/` package.
 - FastAPI/uvicorn from `config.FASTAPI`; prefer `AppUtils.create_fastapi_app` / gRPC factories.
 - Specific exceptions; always `raise ... from e`.
+- Python 3.14 typing, double quotes, Google docstrings, complete public annotations; follow app tooling when stricter.
+- No hardcoded secrets or logged credentials/tokens; parameterize queries and justify narrow security suppressions.
+
+## Rule index
+
+- Ownership/precedence: `rules/rules-index-for-apps.mdc`
+- Always-on: `architecture-for-apps.mdc`, `python-code-style-for-apps.mdc`, `security-for-apps.mdc`,
+  `tooling-for-apps.mdc`, `contributing-for-apps.mdc`
+- Python typing: `typing-for-apps.mdc`
+- Layers: `using-archipy-models.mdc`, `using-archipy-adapters.mdc`, `using-archipy-repositories.mdc`,
+  `using-archipy-logics.mdc`, `using-archipy-services.mdc`
+- Support/config: `using-archipy-utils.mdc`, `using-archipy-decorators.mdc`, `using-archipy-interceptors.mdc`,
+  `config-and-di.mdc`
+- Tests: `testing-bdd-for-apps.mdc`

CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-09-07
+
+### Added
+
+- `/scaffold-observability` command and `scaffold-archipy-observability` skill for ArchiPy 5.x OpenTelemetry setup,
+  stack-specific extras, bootstrap ordering, decorators, and test guidance
+- Consumer app rules for Python style, strict typing, security, `uv` tooling, contribution workflow, and rule precedence
+- Catalog guards for skill quality, command/skill prompt parity, referenced templates, required rules, rule frontmatter,
+  and ArchiPy 5.x API drift
+
+### Changed
+
+- Scaffolding skills now inspect existing projects first, ask only unresolved choices, preserve files, and require
+  focused verification
+- Slash commands now read their complete skills and follow the same inspect-first workflow
+- Bundled reference and observability guidance now target ArchiPy 5.1 OpenTelemetry APIs and `otel*` extras
+- Layer rules now align DTOs, adapter/repository error boundaries, AppUtils error mapping, config sources, BDD workflow,
+  and Claude Code rule injection with current ArchiPy conventions
+- Plugin-template paths are resolved from Cursor/Claude plugin roots and copied into consumer apps
+
+### Fixed
+
+- Removed stale ArchiPy 4.x `TracingUtils`, Prometheus, Sentry, Elastic APM, and capture-decorator recommendations
+- Removed redundant direct `grpcio-health-checking` installation when `archipy[grpc]` already provides it
+- Corrected service helper documentation link and DTO examples to use ArchiPy `BaseDTO`
+
+### Tests
+
+- Added regression coverage for verification loops, inspect-first commands, template references, ArchiPy API drift,
+  and injection of all always-on consumer rules
+
 ## [0.8.0] - 2026-08-24
 
 ### Added

README.md

@@ -72,11 +72,17 @@ Then restart Claude Code or run `/reload-plugins`.
 
 ## What’s included
 
-### Rules (11)
+### Rules (17)
 
 | Rule file                        | Applies when                                     |
 |----------------------------------|--------------------------------------------------|
+| `rules-index-for-apps.mdc`       | Always                                           |
 | `architecture-for-apps.mdc`      | Always                                           |
+| `python-code-style-for-apps.mdc` | Always                                           |
+| `security-for-apps.mdc`          | Always                                           |
+| `tooling-for-apps.mdc`           | Always                                           |
+| `contributing-for-apps.mdc`      | Always                                           |
+| `typing-for-apps.mdc`            | `**/*.py`                                        |
 | `using-archipy-adapters.mdc`     | `**/repositories/**/adapters/**/*.py`            |
 | `using-archipy-utils.mdc`        | `**/helpers/utils/**/*.py`                       |
 | `using-archipy-decorators.mdc`   | `**/helpers/decorators/**/*.py`                  |
@@ -88,7 +94,7 @@ Then restart Claude Code or run `/reload-plugins`.
 | `using-archipy-services.mdc`     | `**/services/**/*.py`, `**/manage.py`            |
 | `testing-bdd-for-apps.mdc`       | `**/features/**/*`                               |
 
-### Skills (12)
+### Skills (13)
 
 | Skill                            | When to use                                                               |
 |----------------------------------|---------------------------------------------------------------------------|
@@ -102,10 +108,11 @@ Then restart Claude Code or run `/reload-plugins`.
 | `scaffold-archipy-decorator`     | Wire or create `helpers/decorators`                                       |
 | `scaffold-archipy-interceptor`   | Wire or create `helpers/interceptors`                                     |
 | `scaffold-archipy-health-checks` | Scaffold FastAPI/gRPC health checks and optional K8s probe YAML           |
+| `scaffold-archipy-observability` | Configure ArchiPy 5.x OpenTelemetry and stack instrumentation             |
 | `redis-search`                   | RediSearch full-text, vector search, and search-cache adapters            |
 | `archipy-docs`                   | Answer “how do I… with ArchiPy?” using bundled `reference.md` + live docs |
 
-### Commands (19)
+### Commands (20)
 
 | Command                   | Action                                               |
 |---------------------------|------------------------------------------------------|
@@ -119,6 +126,7 @@ Then restart Claude Code or run `/reload-plugins`.
 | `/scaffold-decorator`     | Run scaffold-archipy-decorator                       |
 | `/scaffold-interceptor`   | Run scaffold-archipy-interceptor                     |
 | `/scaffold-health-checks` | Scaffold FastAPI/gRPC health + K8s probe YAML        |
+| `/scaffold-observability` | Configure OpenTelemetry traces, metrics, and logs    |
 | `/redis-search`           | Scaffold Redis full-text / vector / search-cache     |
 | `/docs-quickstart`        | Quickstart + bundled reference                       |
 | `/docs-adapters`          | Adapter patterns + docs links                        |
@@ -189,7 +197,7 @@ There is **no** `/scaffold-helper` — use the three helper-specific commands.
 ### `/scaffold-decorator`
 
 - **Purpose:** Prefer ArchiPy decorators (`ttl_cache_decorator`, `postgres_sqlalchemy_atomic_decorator`,
-  `capture_span` / `capture_transaction`, …).
+  `trace_span` / `trace_root`, `measure_duration` / `count_calls`, …).
 - **Asks:** Purpose; sync/async; built-in vs custom.
 - **Outcome:** Usage snippet or `helpers/decorators/<name>.py` with example.
 
@@ -207,6 +215,13 @@ There is **no** `/scaffold-helper` — use the three helper-specific commands.
 - **Outcome:** Shared check helpers + `health_service.py` and/or `health_grpc_service.py` (`grpc.health.v1`) + optional
   `deploy/k8s-probes.yaml` (`httpGet` / `grpc`).
 
+### `/scaffold-observability`
+
+- **Purpose:** Configure ArchiPy 5.x OpenTelemetry traces, metrics, logs, and stack-specific instrumentation.
+- **Asks:** Only unresolved signals, OTLP endpoint/protocol, service name, sampling, and log-level choices.
+- **Outcome:** Matching `otel*` extras, `OTEL__*` config documentation, early `OtelUtils` bootstrap, and focused
+  verification.
+
 ### `/redis-search`
 
 - **Purpose:** Add Redis full-text (RediSearch), vector, or search-cache adapters under a domain repository.
@@ -217,8 +232,8 @@ There is **no** `/scaffold-helper` — use the three helper-specific commands.
 
 `/docs-observability` / `/docs-health-checks`
 
-- **Purpose:** Orient the agent on the matching topic using `skills/archipy-docs/reference.md` first, then live docs
-  URLs.
+- **Purpose:** Orient the agent using the bundled ArchiPy 5.x reference and live docs; version-sensitive topics use live
+  docs first.
 - **Outcome:** Short guidance + links; may suggest a `/scaffold-*` follow-up.
 
 ## Rules deep dive
@@ -230,6 +245,13 @@ Always-on layer map, call flow (`services → logics → repositories → adapte
 - **Do:** Keep models free of I/O; UoW on logics; cross-domain via logics only.
 - **Don’t:** Import repositories/adapters from `models/`; invent a top-level app `adapters/` package.
 
+### Cross-cutting app rules
+
+`python-code-style-for-apps`, `typing-for-apps`, `security-for-apps`, `tooling-for-apps`, and
+`contributing-for-apps` carry the consumer-safe parts of ArchiPy's core standards: Python 3.14 style, complete typing,
+runtime-evaluated type safety, secrets/logging controls, parameterized queries, `uv`, and focused PR workflow. App
+tooling wins when stricter; library-only Make targets and per-file exemptions are not copied.
+
 ### `using-archipy-adapters`
 
 Prefer ArchiPy extras and thin domain wrappers under `repositories/{domain}/adapters/`.
@@ -338,7 +360,7 @@ always-on rule text, and the post-tool hook injects glob-matched rules.
 | `/docs-config`                               | [Config](https://syntaxarc.github.io/ArchiPy/tutorials/config_management/), [DI](https://syntaxarc.github.io/ArchiPy/tutorials/dependency_injection/)                      |
 | `/docs-errors`                               | [Error handling](https://syntaxarc.github.io/ArchiPy/tutorials/error_handling/)                                                                                            |
 | `/docs-testing`, `scaffold-archipy-bdd`      | [Testing strategy](https://syntaxarc.github.io/ArchiPy/tutorials/testing_strategy/)                                                                                        |
-| `/docs-observability`                        | [Observability](https://syntaxarc.github.io/ArchiPy/tutorials/observability/)                                                                                              |
+| `/docs-observability`, OTel scaffold         | [Observability](https://syntaxarc.github.io/ArchiPy/tutorials/observability/) + `/scaffold-observability`                                                                  |
 | `/docs-health-checks`, health scaffold       | Bundled `reference.md` Health checks + `/scaffold-health-checks`                                                                                                           |
 | `archipy-docs` / `reference.md`              | [Docs home](https://syntaxarc.github.io/ArchiPy/), [API reference](https://syntaxarc.github.io/ArchiPy/api_reference/)                                                     |
 

commands/docs-observability.md

@@ -1,6 +1,6 @@
 ---
 name: docs-observability
-description: Open ArchiPy observability guidance (tracing, metrics, APM)
+description: Open ArchiPy OpenTelemetry guidance (traces, metrics, logs)
 ---
 
 # /docs-observability
@@ -9,9 +9,10 @@ Use the **archipy-docs** skill and the Observability section of `skills/archipy-
 
 Cover:
 
-- Tracing: `TracingUtils`, `capture_span` / `capture_transaction`
-- Metrics: `PrometheusUtils`, metric interceptors (`archipy[prometheus]` required to import)
-- APM / Sentry extras and AppUtils config flags
+- OpenTelemetry: `BaseConfig.OTEL` + `OtelUtils`
+- Tracing: `trace_root` / `trace_span` (+ async twins)
+- Metrics: `measure_duration` / `count_calls` (+ async twins)
+- AppUtils instrumentation through `archipy[otel-fastapi]` / `archipy[otel-grpc]`
 - Timing: `timing_decorator`
 
 Live docs:

commands/redis-search.md

@@ -5,10 +5,10 @@ description: Scaffold Redis search adapters (RediSearch full-text, vector, searc
 
 # /redis-search
 
-Follow the **redis-search** skill.
+Read and follow the **redis-search** skill in full. Inspect the workspace as directed there; ask only for unresolved
+choices.
 
-1. Ask for search type (full-text / vector / caching), domain name, data structure, sync/async, and patterns needed.
-2. Prefer `uv add "archipy[redis]"` and a thin domain wrapper under `repositories/<domain>/adapters/`.
-3. Generate the matching adapter stub (s) + repository orchestrator stub if missing; wire via DI.
+1. Prefer `uv add "archipy[redis]"` and a thin domain wrapper under `repositories/<domain>/adapters/`.
+2. Generate the matching adapter stub (s) + repository orchestrator stub if missing; wire via DI.
 
 Docs: https://syntaxarc.github.io/ArchiPy/tutorials/adapters/ · bundled `skills/archipy-docs/reference.md`

commands/scaffold-adapter.md

@@ -5,11 +5,11 @@ description: Scaffold a domain adapter under repositories/{domain}/adapters/
 
 # /scaffold-adapter
 
-Follow the **scaffold-archipy-adapter** skill.
+Read and follow the **scaffold-archipy-adapter** skill in full. Inspect the workspace as directed there; ask only for
+unresolved choices.
 
-1. Ask for domain name, adapter purpose, sync/async, and whether mocks are needed.
-2. Prefer wrapping an existing ArchiPy adapter via extras when possible.
-3. Generate a thin wrapper under `repositories/<domain>/adapters/` (e.g. `user_db_adapter.py`). Create
+1. Prefer wrapping an existing ArchiPy adapter via extras when possible.
+2. Generate a thin wrapper under `repositories/<domain>/adapters/` (e.g. `user_db_adapter.py`). Create
    `repositories/<domain>/<domain>_repository.py` stub if missing.
 
 Docs: https://syntaxarc.github.io/ArchiPy/getting-started/project_structure/

commands/scaffold-app.md

@@ -5,12 +5,12 @@ description: Scaffold a minimal ArchiPy application package layout
 
 # /scaffold-app
 
-Follow the **scaffold-archipy-app** skill.
+Read and follow the **scaffold-archipy-app** skill in full. Inspect the workspace as directed there; ask only for
+unresolved choices.
 
-1. Ask for package name, ArchiPy extras, and optional first domain.
-2. Generate config, models stub, `repositories/<domain>/` (adapters + repository stub), optional helpers tree, and
+1. Generate config, models stub, `repositories/<domain>/` (adapters + repository stub), optional helpers tree, and
    `.env.example`.
-3. Point the user to `/docs-quickstart` and `/scaffold-adapter` for domain wrappers under
+2. Point the user to `/docs-quickstart` and `/scaffold-adapter` for domain wrappers under
    `repositories/<domain>/adapters/`.
 
 Docs: https://syntaxarc.github.io/ArchiPy/getting-started/quickstart/

commands/scaffold-bdd.md

@@ -5,17 +5,17 @@ description: Scaffold Behave BDD layout with ScenarioContext, pool manager, envi
 
 # /scaffold-bdd
 
-Follow the **scaffold-archipy-bdd** skill.
+Read and follow the **scaffold-archipy-bdd** skill in full. Inspect the workspace as directed there; ask only for
+unresolved choices.
 
-1. Ask for feature name and **mocks** vs **infra** (`@needs-*` + testcontainers).
-2. Always generate (if missing), modeled on ArchiPy `features/`:
+1. Always generate (if missing), modeled on ArchiPy `features/`:
     - `features/scenario_context.py`
     - `features/scenario_context_pool_manager.py`
     - `features/test_helpers.py` (`get_current_scenario_context`)
     - `features/environment.py` (behave hooks + `TestConfig`)
     - `features/<name>.feature` + `features/steps/<name>_steps.py`
-3. Infra mode: also `features/test_containers.py` (`ContainerManager` + only needed containers), `.env.test` image vars,
+2. Infra mode: also `features/test_containers.py` (`ContainerManager` + only needed containers), `.env.test` image vars,
    `uv add "archipy[testcontainers]"`.
-4. Do **not** copy ArchiPy-core gRPC/Temporal server bootstrap unless the app tests those.
+3. Do **not** copy ArchiPy-core gRPC/Temporal server bootstrap unless the app tests those.
 
 Docs: https://syntaxarc.github.io/ArchiPy/tutorials/testing_strategy/

commands/scaffold-decorator.md

@@ -5,10 +5,11 @@ description: Scaffold or wire a helpers/decorators module (prefer ArchiPy decora
 
 # /scaffold-decorator
 
-Follow the **scaffold-archipy-decorator** skill.
+Read and follow the **scaffold-archipy-decorator** skill in full. Inspect the workspace as directed there; ask only for
+unresolved choices.
 
-1. Ask for purpose, sync/async, and ArchiPy vs custom.
-2. Prefer `ttl_cache_decorator`, `postgres_sqlalchemy_atomic_decorator`, `capture_span` / `capture_transaction`, etc.
-3. Custom decorators: no adapter imports at module level; include usage example.
+1. Prefer `ttl_cache_decorator`, `postgres_sqlalchemy_atomic_decorator`, `trace_span` / `trace_root`,
+   `measure_duration` / `count_calls`, etc.
+2. Custom decorators: no adapter imports at module level; include usage example.
 
 Reference: skills/archipy-docs/reference.md (Decorators). Docs: https://syntaxarc.github.io/ArchiPy/tutorials/helpers/

commands/scaffold-domain.md

@@ -5,10 +5,10 @@ description: Scaffold a full ArchiPy domain slice (models, repo, logic, service)
 
 # /scaffold-domain
 
-Follow the **scaffold-archipy-domain** skill.
+Read and follow the **scaffold-archipy-domain** skill in full. Inspect the workspace as directed there; ask only for
+unresolved choices.
 
-1. Ask for domain name, extras, and transport (FastAPI default).
-2. Compose adapter + models + logic + service skills for one domain.
-3. Note DI wiring: ports → adapters → repository → logic → service.
+1. Compose adapter + models + logic + service skills for one domain.
+2. Note DI wiring: ports → adapters → repository → logic → service.
 
 Docs: https://syntaxarc.github.io/ArchiPy/getting-started/project_structure/