feat: add ui-watchtower-setup and ui-watchtower-integration skills

CONTRIBUTING.md

@@ -250,4 +250,4 @@ Before opening a pull request, verify:
 - [ ] New skill's description does not conflict with or shadow existing skills
 - [ ] Skill added to the catalog table in `README.md`
 - [ ] Evals exist (or a note explains why they are not applicable)
-- [ ] `skills-ref validate ./skills/my-skill` passes (install: `pip install skills-ref`)
+- [ ] `uvx --from skills-ref agentskills validate ./skills/my-skill` passes (the `skills-ref` package installs an `agentskills` command and needs Python 3.11+; with pip: `pip install skills-ref`, then `agentskills validate ./skills/my-skill`)

README.md

@@ -100,6 +100,8 @@ deprecated entities; audit unused steps and PageObject methods. |
 | **[test-unit-write](./skills/test-unit-write/)**     | Generate unit tests from scratch following language-specific standards. Analyzes source, selects mock strategies, and produces tests covering happy paths, failure conditions, and edge cases. |
 | **[test-unit-review](./skills/test-unit-review/)**   | Systematically audit unit test suites. Runs test runner, checks isolation/scope/naming/assertions/coverage standards, and reports findings by severity (Blocker / Important / Nit). |
 | **[token-saving](./skills/token-saving/)**           | Always-active response discipline — enforces brevity, no filler openers or closers, structured output, and a What/Why/How footer on code responses. Suspends on explicit "full detail" requests. |
+| **[ui-watchtower-integration](./skills/ui-watchtower-integration/)** | Measure what matters in an Angular app that already uses `@absaoss-cps/ngx-ui-watchtower` — asks what the team wants to learn, scans the code, proposes scenarios and BI events marked by source (you / suggested), implements after confirmation, and tests each outcome. |
+| **[ui-watchtower-setup](./skills/ui-watchtower-setup/)** | Install and wire `@absaoss-cps/ngx-ui-watchtower` in an Angular app — destination per app role (CloudWatch RUM, micro-frontend shell or fragment, no-op), credentials, typed vocabulary, migration of a hand-written RumService, and route-navigation tracking as a tested proof. |
 
 ## Agent Roster
 

docs/README.md

@@ -67,6 +67,8 @@ Task-specific guidance for using individual skills. Start by picking your use ca
 | [Token Saving](./guides/token-saving.md) | Keeping AI responses concise — how the token-saving skill works and when it applies |
 | [PR Review](./guides/pr-review.md) | How the PR review skill works, what sections it applies, and how to trigger it |
 | [Create Repository](./create-repository.md) | Creating a new AbsaOSS/absa-group repo from the template with standard guardrails |
+| [UI Watchtower Setup](./guides/ui-watchtower-setup.md) | Install and wire the ngx-ui-watchtower telemetry library in an Angular app — destination per app role, RUM credentials, typed vocabulary, route-navigation proof, tests |
+| [UI Watchtower Integration](./guides/ui-watchtower-integration.md) | Measure an app's own journeys and interactions with ngx-ui-watchtower — asks what you want to learn, proposes, implements after confirmation, tests |
 
 ### QA And Testing Skills
 

docs/guides/ui-watchtower-integration.md

@@ -0,0 +1,73 @@
+# UI Watchtower Integration Skill
+
+The `ui-watchtower-integration` skill measures what matters in a specific Angular app with
+[`@absaoss-cps/ngx-ui-watchtower`](https://www.npmjs.com/package/@absaoss-cps/ngx-ui-watchtower):
+**scenarios** (did a user journey succeed, and how long did it take) and **BI events** (did a
+meaningful thing happen).
+
+It starts from what you want to learn, not only from what it finds in the code: it asks first,
+proposes a plan that marks which items you asked for and which it suggests, and implements only what
+you confirm. Run it again whenever the app grows — each pass adds to what is already instrumented.
+
+The library must already be installed and wired — use [UI Watchtower Setup](./ui-watchtower-setup.md)
+first.
+
+---
+
+## What it does
+
+| Step | Action |
+|---|---|
+| Check | Confirms the library is installed with a destination, otherwise stops and points to the setup skill; reads what is already instrumented so a re-run only adds |
+| Ask | One short set of questions: what the telemetry should answer, which journeys matter and what success means, which interactions to count, known pain points, what must not be tracked, scope of this pass |
+| Scan | Finds candidate journeys, clicks and journey-ending errors in the code, within that scope |
+| Propose | A merged plan with a **Source** column (`you` / `suggested`) and a section for requests it had to change (e.g. no raw search text, no ids in names) with the alternative |
+| Implement | Only what you confirmed — names in the schema, the right settle status for each outcome, cleanup on destroy; the scenario and BI services used directly where needed, never merged behind a facade |
+| Test & validate | A test per outcome through a recording sink; build, unit tests, a real type-check, a live check with the debug flags |
+
+---
+
+## How to trigger it
+
+```
+instrument the checkout flow as a scenario
+we want to know if customer search is slow — add telemetry
+which journeys should we measure in this app?
+track how often people use the export
+add BI events for the main buttons
+```
+
+---
+
+## What you'll be asked
+
+1. Which questions should this telemetry answer?
+2. Which user journeys matter most, and what counts as success?
+3. Which interactions or features do you want usage numbers for?
+4. Known pain points, incidents or support tickets to watch?
+5. Anything that must not be tracked?
+6. Scope of this pass — the whole app or one area?
+
+Questions your request already answers are skipped. "Just suggest something" works too: the proposal
+then says it is based on the code only.
+
+---
+
+## Out of scope
+
+- Installing or wiring the library → [UI Watchtower Setup](./ui-watchtower-setup.md)
+- CloudWatch dashboards, RUM extended metrics and alarms
+- A backend correlation-header interceptor (offered as a follow-up)
+- Non-Angular applications
+
+---
+
+## Installation
+
+```bash
+npx skills add https://github.com/AbsaOSS/agentic-toolkit -g --skill ui-watchtower-integration
+# Companion: holds the ngx-ui-watchtower API reference both watchtower skills load
+npx skills add https://github.com/AbsaOSS/agentic-toolkit -g --skill shared
+```
+
+See [Getting Started](../getting-started.md) for the full install guide.

docs/guides/ui-watchtower-setup.md

@@ -0,0 +1,78 @@
+# UI Watchtower Setup Skill
+
+The `ui-watchtower-setup` skill installs and wires
+[`@absaoss-cps/ngx-ui-watchtower`](https://www.npmjs.com/package/@absaoss-cps/ngx-ui-watchtower) — a
+telemetry library for Angular apps — in an existing application, and proves the pipeline works with
+one real scenario: route-navigation tracking.
+
+It is the first of two skills. Once the app is wired, use
+[UI Watchtower Integration](./ui-watchtower-integration.md) to measure the app's own journeys and
+interactions.
+
+---
+
+## What it does
+
+| Step | Action |
+|---|---|
+| Detect | Reads Angular version, bootstrap style, SSR, package manager, test runner, existing RUM code, and the app's role (standalone, micro-frontend shell, or fragment) |
+| Install | Adds the package (and `aws-rum-web` only where this app sends to RUM) |
+| Wire | Registers exactly one destination for the app's role; a credentials provider for RUM; a log provider only if the app has a log backend; an opaque user id on sign-in and sign-out |
+| Vocabulary | Creates `telemetry.schema.ts` so names are compile-checked metric dimensions |
+| Migrate | If the app already sends RUM events itself: inventory, keep wire parity, retire the old service only after comparing what reaches CloudWatch |
+| Prove | Adds route-navigation tracking with a test, and RUM page views — both under the route template (`/customers/:id`), never the resolved URL |
+| Test & validate | Fixes specs that now need telemetry providers; build, unit tests, a real type-check, and a live check with the debug flags |
+| Hand over | Points to the integration skill; for a shell, hands over the fragment contract |
+
+---
+
+## How to trigger it
+
+```
+add ngx-ui-watchtower to this Angular app
+set up CloudWatch RUM with the watchtower library
+replace our RumService with ngx-ui-watchtower
+wire telemetry into our micro-frontend shell
+our fragment should forward telemetry to the shell
+```
+
+---
+
+## What you'll be asked
+
+Only what the code can't answer: the `application` name to report, whether there is a log backend,
+the endpoint that returns RUM settings and short-lived AWS credentials — or that RUM isn't ready
+yet, in which case the app is wired with an explicit "ship nowhere" destination to swap later — and,
+if the app has sign-in but no obvious opaque user id, which one to use.
+
+If the library is already partly wired, only the missing pieces are added.
+
+---
+
+## Requirements
+
+- An Angular version the library supports (the skill checks its `peerDependencies` on npm and stops
+  rather than forcing an install)
+- A Node.js version your Angular version supports
+- Access to the npm registry
+
+---
+
+## Out of scope
+
+- Measuring the app's own journeys and interactions → [UI Watchtower Integration](./ui-watchtower-integration.md)
+- CloudWatch dashboards, RUM extended metrics and alarms
+- Fragment teams' own setup when your app is a shell — the skill hands you their contract
+- Non-Angular applications
+
+---
+
+## Installation
+
+```bash
+npx skills add https://github.com/AbsaOSS/agentic-toolkit -g --skill ui-watchtower-setup
+# Companion: holds the ngx-ui-watchtower API reference both watchtower skills load
+npx skills add https://github.com/AbsaOSS/agentic-toolkit -g --skill shared
+```
+
+See [Getting Started](../getting-started.md) for the full install guide.

skills/shared/SKILL.md

@@ -2,8 +2,8 @@
 name: shared
 description: >
   Internal library — not a task skill. Holds shared Python modules (skills/shared/lib/)
-  and shared reference docs (skills/shared/references/) that other living-doc and BDD
-  skills import or load, e.g. the canonical AC-ID grammar and entity-ID assignment logic.
+  and shared reference docs (skills/shared/references/) that other skills import or load,
+  e.g. the canonical AC-ID grammar, entity-ID assignment logic and the ngx-ui-watchtower API.
   Do not activate this for a user request; it has no standalone behavior of its own.
   Install it alongside any skill whose own SKILL.md names it as a required companion —
   the consuming skill's install instructions list the exact command.