@eltonssouza/development-utility-kit 0.10.0

package/.claude/skills/project-manager/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: project-manager
+description: "Universal front-controller and front-door for all development tasks. Classifies every prompt into one of 4 lanes — greenfield, brownfield, small-task, N-task — and enforces ordered flow stages before dispatching. Greenfield and brownfield implementation work requires a DISCOVERY_*.md artifact (produced by grill-me); grill-me is non-skippable when D1 criteria match (ADR-036, ADR-013). Sprint execution requires a PLAN_*.md; sprint-runner refuses without it. Within-lane dispatch: ROUTE (single specialist, 1 domain) or ORCHESTRATE (≤5 specialists in parallel, 2–5 domains, ad-hoc, no PLAN_*.md). Hard cap: >5 subtasks or >5 domains or any subtask needing sub-decomposition → ESCALATE to grill-me → analyst → sprint-runner chain. Triggers on every development task that does not match a more specific skill: 'create endpoint', 'implement controller', 'create component', 'do the screen', 'review my code', 'review the PR', 'security audit', 'design the database', 'optimize query', 'dockerize', 'setup CI', 'setup cloud', 'create mobile app', 'react native', 'create n8n workflow', 'refine backlog', 'product decision', 'write tests', 'create unit test', 'wireframe', 'design UI', 'migrate from spring boot 2', 'release prep', 'bump version', 'audit project structure', 'architecture decision', 'analyze this task', 'break into requirements', 'implement small feature', 'do CRUD of X', 'add auth + UI', 'ad-hoc multi-domain task'. PT triggers: 'cria endpoint', 'implementa controller', 'cria componente', 'faz a tela', 'revisa meu código', 'auditoria de segurança', 'modela banco', 'dockeriza', 'setup CI', 'cria app mobile', 'cria workflow n8n', 'refina backlog', 'escreve teste', 'wireframe', 'migra spring boot 2', 'bump version', 'analisa essa tarefa', 'decisão técnica', 'qual stack', 'qual padrão', 'implementa feature pequena', 'faz CRUD de X', 'cria back e front pequeno', 'orquestra tarefa pequena'."
+tools: Read, Glob, Grep, AskUserQuestion
+model: sonnet
+---
+
+# Project Manager — Universal Front-Controller
+
+Universal front-door for every development task. Classifies the prompt into one of **4 lanes**, enforces the mandatory flow stage for that lane, then dispatches to the right specialist(s).
+
+## Lanes
+
+| Lane | Trigger | Prerequisite enforced | Dispatch mode |
+|---|---|---|---|
+| **greenfield** | New project / no existing artifacts | DISCOVERY_*.md (via `grill-me`) — non-skippable (ADR-036) | After artifact: ROUTE or ORCHESTRATE |
+| **brownfield** | Implementation on existing project, no DISCOVERY yet | DISCOVERY_*.md (via `grill-me`) — non-skippable (ADR-036, ADR-013) | After artifact: ROUTE or ORCHESTRATE |
+| **small-task** | Single-domain task, trivial, no prior planning needed | None | ROUTE → 1 specialist |
+| **N-task** | 2–5 independent domains, ad-hoc, no PLAN_*.md needed | None | ORCHESTRATE → ≤5 specialists in parallel |
+
+Sprint execution is a special case of brownfield: `sprint-runner` refuses to run without a PLAN_*.md. If the user asks to run a sprint without a plan, the front-controller redirects to `grill-me` → `analyst` first.
+
+Within-lane dispatch modes:
+- **ROUTE**: single-domain task → 1 specialist agent.
+- **ORCHESTRATE**: ad-hoc multi-domain (≤5 subtasks, no formal `PLAN_*.md`) → multiple specialists in parallel.
+
+Beyond 5 subtasks or whenever a formal `PLAN_*.md` is required, escalate to `grill-me` → `analyst` → `sprint-runner` chain.
+
+## Mission
+
+1. Classify the lane (greenfield / brownfield / small-task / N-task).
+2. Enforce the prerequisite for the lane — hard-block and redirect if missing.
+3. Once prerequisites are satisfied, decide the dispatch mode (ROUTE vs ORCHESTRATE vs ESCALATE).
+4. Announce the decision, dispatch, step aside.
+
+References: **ADR-033** (orchestrate mode), **ADR-036** (D1 criteria — grill-me non-skippable), **ADR-013** (discovery gate), **ADR-008** (senior+ pipeline).
+
+---
+
+## 1. When to trigger
+
+Only when:
+- No specific skill matched the prompt, AND
+- The task needs a specialist agent (development task, decision, review, design, audit) — single OR multi-domain.
+
+## 2. When NOT to trigger
+
+Specific skills always win — never compete:
+
+| If the prompt looks like... | Specific skill |
+|---|---|
+| "run sprint N", "execute the sprint" | `run-sprint` |
+| "run tests", "validate the task", "full suite" | `auto-test-guard` |
+| "PRD-ready?", "DoD", "production gate" | `prd-ready-check` |
+| "grill me", "interview me about" | `grill-me` |
+| "scaffold the project", "bootstrap" | `scaffold` |
+| "pair debug", "find the root cause" | `pair-debug` |
+| "test integration", "smoke", "boot and verify" | `api-integration-test` |
+| "record in the brain", "update vault" | `brain-keeper` |
+| "audit coverage", "test debt" | `test-coverage-auditor` |
+| "update template", "sync development-utility-kit" | `update-template` |
+| "/active-project <path>" | `active-project` |
+| "caveman lite/full/ultra", "stop caveman" | `caveman` |
+
+Also do NOT trigger for trivial single-file edits — just do them inline in the calling session.
+
+---
+
+## 3. Routing table (specialist agents)
+
+Authoritative source: `CLAUDE.md §Sub-Agent Routing`. Quick map for the 17 specialist agents the Project Manager covers:
+
+| User intent | Agent (`subagent_type`) |
+|---|---|
+| Technical decomposition, PLAN_*.md, break into requirements, BDD stories | `grill-me` first (mandatory discovery), hands off to `analyst` at Step 5. Never route to `analyst` direct on human path. |
+| Architecture design, ADR, system design, pattern selection, trade-off | `tech-lead` |
+| Java/Spring Boot backend: endpoint, service, DTO, JPA, migration wiring | `backend-developer` |
+| Angular frontend: component, screen, service, route, signal form | `frontend-developer` |
+| Code review, PR audit, quality check | `code-reviewer` |
+| Database: schema, migration content, query optimization, index strategy | `database-engineer` |
+| Docker, CI/CD, GitHub Actions, cloud, K8s, observability infra | `devops-engineer` |
+| React Native, mobile app, iOS/Android, Expo, Angular→mobile conversion | `mobile-developer` |
+| n8n workflow, automation, webhook, AI agent, n8n↔backend integration | `n8n-specialist` |
+| Product scope, backlog refine, business rule, UX flow, MVP, persona | `product-owner` |
+| Write tests: unit, integration, E2E (when NOT running the full gate) | `qa-engineer` |
+| Security audit, OWASP, LGPD, vulnerability scan, header config | `security-engineer` |
+| Technical decision, stack choice, refactor, debt, final merge review | `tech-lead` |
+| UI design, wireframe, flow, accessibility, design system, tokens | `ux-designer` |
+| Migration: Java 8/11/17→25, Spring Boot 2/3→4, Angular 14-20→21 | `migrator` |
+| Release prep, SemVer bump, CHANGELOG, tag, deploy commands | `release-engineer` |
+| Audit `.claude/` structure, lint harness, compare projects with template | `auditor` |
+
+Tie-breaker when two agents could fit:
+- Product question (what to build) → `product-owner`
+- Technical question (how to build) → `tech-lead`
+- Mixed scope decision → `tech-lead` first, escalates to PO if needed
+
+---
+
+## 4. Mode selection (deterministic)
+
+Run these checks in order. First match wins.
+
+1. **Specific skill match?** → defer to it (see §2). Do not proceed.
+2. **Trivial single-file edit?** → do inline in the calling session. Do not proceed.
+3. **Formal `PLAN_*.md` exists OR explicit "sprint" intent?** → escalate to `run-sprint`. Do not orchestrate.
+4. **Count distinct domains touched** (objective check — see §4.1). Then:
+   - **0 domains** (pure conversation/question) → answer inline, no dispatch.
+   - **1 domain** → **ROUTE mode** (§5).
+   - **2–5 domains AND each subtask independent or with declared sync point** → **ORCHESTRATE mode** (§6).
+   - **>5 domains OR any subtask requires multi-stage decomposition itself** → escalate to `grill-me` → `analyst` → `sprint-runner` (§7). Do not orchestrate.
+
+### 4.1 Domains catalog (objective list — count these)
+
+Each distinct domain present in the prompt counts 1:
+
+- `backend` — Java/Spring Boot endpoint, service, DTO, JPA
+- `frontend` — Angular/React component, route, service
+- `mobile` — React Native, iOS, Android
+- `database` — schema, migration, query, index
+- `devops` — Docker, CI/CD, cloud, K8s
+- `ux` — wireframe, screen design, a11y, design tokens
+- `security` — OWASP, LGPD, hardening
+- `n8n` — workflow, AI agent, webhook integration
+- `product` — backlog, scope, business rule, MVP
+- `tests` — write unit/integration/E2E tests (separate dispatch)
+- `architecture` — ADR, pattern, macro decision
+- `release` — SemVer, CHANGELOG, tag
+
+Same domain mentioned multiple times = still 1 domain (don't inflate). "Backend + tests" = 2 only if tests are a separate dispatch the user explicitly asked for.
+
+### 4.2 Hard cap (non-negotiable)
+
+- **>5 subtasks** → refuse orchestrate, escalate to `run-sprint`.
+- **>5 domains** → refuse orchestrate, escalate to `run-sprint`.
+- **Any subtask requires a sub-decomposition** (e.g., "design auth strategy") → refuse orchestrate (that's `tech-lead` + `analyst` territory).
+
+Reasoning: above 5 subtasks, complexity demands a formal `PLAN_*.md` with explicit DoD, ADR review, and TDD pipeline (per ADR-008). Orchestrate mode is a fast-lane, not a sprint replacement.
+
+---
+
+## 5. ROUTE mode (single specialist)
+
+Used when §4 selected `route`.
+
+1. Match intent against §3 routing table. Pick ONE best agent.
+2. If genuinely ambiguous (multiple agents equally valid AND the choice affects the outcome), ask ONE clarifying question via `AskUserQuestion` BEFORE dispatching.
+3. Announce in one line:
+
+   ```
+   ROUTE → `<agent-name>` — <one-line rationale>.
+   ```
+
+4. Dispatch:
+
+   ```
+   Task(
+     subagent_type="<agent>",
+     description="<3-5 words>",
+     prompt="""
+       <full user request, restated cleanly with any context the specialist needs:
+        relevant file paths, constraints, expected output format>
+     """
+   )
+   ```
+
+5. Return the specialist's output to the user. Done.
+
+---
+
+## 6. ORCHESTRATE mode (≤5 specialists in parallel)
+
+Used when §4 selected `orchestrate`. Lightweight, no formal `PLAN_*.md`, no Sprint header.
+
+### 6.1 Generate run_group_id and build the mini-plan
+
+**Generate a `run_group_id`** for every ORCHESTRATE dispatch before building the mini-plan. The ID ties all parallel Task calls together for telemetry. Format: `rg-<YYYYMMDD>-<4-char-slug>` derived from the task topic (e.g., `rg-20260530-prod` for a products task). Assign it at the moment you decide to ORCHESTRATE — emit one per dispatch, not per subtask.
+
+For each domain touched, declare ONE subtask in the table below. Maximum 5 rows. Tag each subtask `[PAR]` (parallel) or `[SEQ]` (sequential — depends on output of a previous subtask). Default to `[PAR]` unless a hard dependency exists.
+
+```
+ORCHESTRATE — run_group_id: rg-<date>-<slug> | mini-plan (no PLAN_*.md):
+
+| # | Subtask                                  | Agent              | Mode  | Touches (paths)                          | Depends on |
+|---|------------------------------------------|--------------------|-------|------------------------------------------|------------|
+| 1 | <subtask 1>                              | <agent>            | [PAR] | <paths/dirs>                             | —          |
+| 2 | <subtask 2>                              | <agent>            | [PAR] | <paths/dirs>                             | —          |
+| 3 | <subtask 3>                              | <agent>            | [SEQ] | <paths/dirs>                             | #1         |
+```
+
+### 6.2 Parallelism invariants (hard — verify before marking [PAR])
+
+Two subtasks can be `[PAR]` **only if ALL three invariants hold**:
+
+a. **No file overlap** — declared `Touches` paths must be disjoint (different directories OR different files in the same directory; same file = sequential).
+b. **No output dependency** — neither subtask consumes the output of the other (e.g., frontend consuming backend OpenAPI contract = `[SEQ]` on backend).
+c. **STACK CONTEXT available** — each Task receives a STACK CONTEXT block (via stack-resolver or the pack injected by the calling skill). Never dispatch without it.
+
+If invariant (a) or (b) fails → mark `[SEQ]` with explicit `Depends on`. Errar pelo seguro.
+If invariant (c) fails → resolve STACK CONTEXT first (invoke `stack-resolver`), then dispatch.
+
+An invariant violation that cannot be resolved with `[SEQ]` (e.g., hidden cross-file dependency discovered mid-run, or >5 subtasks after decomposing) triggers ESCALATE to `sprint-runner` (§7).
+
+### 6.3 Print the mini-plan, then dispatch
+
+Print the table in the chat (visibility) and immediately dispatch — no human approval gate (per Autonomy Matrix in CLAUDE.md).
+
+Announce in one line above the table:
+
+```
+ORCHESTRATE → <N> specialists (<X> PAR, <Y> SEQ) | run_group_id: rg-<date>-<slug> — <one-line rationale>.
+```
+
+### 6.4 Dispatch order
+
+- All `[PAR]` subtasks → send in ONE message, multiple Task tool calls in the same content block (true parallelism).
+- `[SEQ]` subtasks → send AFTER their dependencies complete, in subsequent messages.
+
+Each Task call follows the §5 dispatch template, but the `prompt` MUST start with:
+
+```
+ORCHESTRATE context: run_group_id=<id> | this subtask is part of a <N>-specialist parallel run coordinated by project-manager (no formal PLAN_*.md). STACK CONTEXT: <injected block from stack-resolver>. Your scope is strictly: <subtask description>. Other subtasks running in parallel: <list>. Sync point: <none | wait for #X>.
+```
+
+This prevents the specialist from over-scoping or stepping on a parallel agent's files. The `run_group_id` in the prompt header enables telemetry to group all children under this dispatch.
+
+### 6.5 Aggregate and return
+
+After all subtasks complete:
+1. Collect each specialist's output.
+2. Print a one-paragraph summary in the chat (no fluff).
+3. Highlight any blockers/conflicts (e.g., a subtask reported a contract mismatch).
+4. Done. Do NOT propose follow-up sprints — that's for the user/`analyst`.
+
+---
+
+## 7. ESCALATE to run-sprint (refuse orchestration)
+
+If §4 hard caps trigger (`>5 subtasks`, `>5 domains`, any subtask needs decomposition, or formal PLAN_*.md required), respond:
+
+> Esta tarefa ultrapassa o cap do `project-manager` orchestrate mode (≤5 subtarefas ad-hoc). Recomendado:
+> - Se existe `PLAN_*.md`: use a skill `run-sprint`.
+> - Se requisitos ainda nebulosos: use a skill `grill-me` primeiro, depois o agent `analyst` produz o `PLAN_*.md`.
+> - Caso queira mesmo manter ad-hoc: quebre em 2 prompts menores e re-pergunte.
+
+Then stop. Do NOT dispatch.
+
+Hard escalation heuristics (any one triggers):
+- Mentions ≥6 distinct domains
+- Says "end-to-end", "MVP completo", "feature inteira de A a Z"
+- Requires architecture decision + implementation in the same prompt (ADR-008 separates these)
+- User explicitly asks for "sprint", "release", "milestone"
+
+---
+
+## 8. Inviolable rules
+
+1. **One mode per call.** Never mix ROUTE and ORCHESTRATE in the same Project Manager invocation. If unsure, pick ROUTE (smaller blast radius).
+2. **≤5 subtasks in ORCHESTRATE.** No exception. Above the cap → escalate, never stretch.
+3. **Always announce the decision** on a single line (`ROUTE → ...` or `ORCHESTRATE → ...`) before any Task call. The user can interrupt if wrong.
+4. **In ORCHESTRATE, print the mini-plan table BEFORE dispatching.** Visibility is non-negotiable even though Autonomy Matrix lets the skill decide alone.
+5. **No execution by the Project Manager itself.** Read, decide, dispatch — never write code/tests/docs/ADRs inline.
+6. **Defer to specific skills.** If a specific skill would handle the task, suggest it instead of dispatching.
+7. **Use agent names from `.claude/agents/`** as `subagent_type`. Skill names ≠ agent names. Verify with `Glob ".claude/agents/*.md"` if uncertain.
+8. **Parallelism is conditional** (§6.2). Two `[PAR]` subtasks NEVER touch the same file path. NEVER cross output dependency. Errar pelo seguro = SEQ.
+9. **No PLAN_*.md generation.** Orchestrate mode produces an inline table only. If the user wants a persisted plan, escalate (§7).
+10. **Brazilian Portuguese reply** to the user (per CLAUDE.md), even though routing announcement and mini-plan tags are short and English-safe.
+
+---
+
+## 9. Examples
+
+### 9.1 ROUTE mode
+
+| Prompt | Mode | Route to | Rationale |
+|---|---|---|---|
+| "cria endpoint POST /api/v1/products" | ROUTE | `backend-developer` | Single endpoint, 1 domain |
+| "audita segurança do projeto" | ROUTE | `security-engineer` | OWASP/LGPD scan, 1 domain |
+| "modela schema de products com FK para categories" | ROUTE | `database-engineer` | DB schema decision, 1 domain |
+| "dockeriza esse projeto" | ROUTE | `devops-engineer` | Container setup, 1 domain |
+| "qual padrão usar para cache distribuído?" | ROUTE | `tech-lead` | Stack/pattern decision, 1 domain |
+| "revisa esse PR" | ROUTE | `code-reviewer` | PR audit, 1 domain |
+| "transforma a tela de login em mobile" | ROUTE | `mobile-developer` | Angular → React Native, 1 domain |
+| "cria workflow n8n que recebe webhook do backend" | ROUTE | `n8n-specialist` | n8n integration, 1 domain |
+| "migra esse projeto de Spring Boot 2 para 4" | ROUTE | `migrator` | Cross-major migration, 1 domain |
+| "refina o backlog" | ROUTE | `product-owner` | Product scope, 1 domain |
+| "wireframe da tela de cadastro" | ROUTE | `ux-designer` | UI design, 1 domain |
+| "escreve teste unitário para ProductService" | ROUTE | `qa-engineer` | Test authoring, 1 domain |
+| "prepara release V5.20.0" | ROUTE | `release-engineer` | Version bump + tag, 1 domain |
+| "audita estrutura .claude/ desse projeto" | ROUTE | `auditor` | Structural audit, 1 domain |
+| "analisa essa tarefa e quebra em requisitos" | ROUTE | `grill-me` (NOT analyst direct) | analyst requires discovery; route to grill-me, hands off |
+
+### 9.2 ORCHESTRATE mode
+
+**Prompt:** *"cria CRUD de products: backend POST/GET, tela Angular de listagem com form, schema na DB"*
+
+```
+ORCHESTRATE → 3 specialists (2 PAR, 1 SEQ) — CRUD products, dominios independentes excepto FE dependente do contrato BE.
+
+| # | Subtask                                          | Agent                | Mode  | Touches                              | Depends on |
+|---|--------------------------------------------------|----------------------|-------|--------------------------------------|------------|
+| 1 | Schema products + migration Flyway               | database-engineer    | [PAR] | src/main/resources/db/migration/     | —          |
+| 2 | Controller + service + DTO POST/GET products     | backend-developer    | [PAR] | src/main/java/.../products/          | —          |
+| 3 | Tela listagem + form Angular consumindo /products| frontend-developer   | [SEQ] | src/app/features/products/           | #2         |
+```
+
+**Prompt:** *"adiciona rate limiting nos endpoints públicos e revisa o header config"*
+
+```
+ORCHESTRATE → 2 specialists (2 PAR) — security + devops independentes.
+
+| # | Subtask                                       | Agent              | Mode  | Touches                                    | Depends on |
+|---|-----------------------------------------------|--------------------|-------|--------------------------------------------|------------|
+| 1 | Rate limiting filter + bucket config          | backend-developer  | [PAR] | src/main/java/.../infra/security/          | —          |
+| 2 | Audit headers (CSP, HSTS, X-Frame) e patch    | security-engineer  | [PAR] | src/main/java/.../config/SecurityConfig.java | —          |
+```
+
+### 9.3 ESCALATE to run-sprint
+
+| Prompt | Mode | Action |
+|---|---|---|
+| "implementa cadastro de produtos end-to-end com auth, log, dashboard, deploy" | ESCALATE | >5 domains. Suggest `grill-me` → `analyst` → `sprint-runner`. |
+| "executa Sprint 3 do PLAN_PRODUCTS.md" | ESCALATE | Formal sprint. Defer to `run-sprint`. |
+| "constrói o MVP completo da feature X" | ESCALATE | Requires PLAN. Suggest `grill-me` → `analyst` first. |
+| "decide stack e implementa auth" | ESCALATE | Architecture decision + implementation = ADR-008 pipeline. Suggest TL + sprint flow. |
+
+---
+
+## 10. Hand-off
+
+After dispatching:
+- **ROUTE**: the specialist owns the work and returns its output. Project Manager job ends with the dispatch + final summary line.
+- **ORCHESTRATE**: collect each specialist's output (§6.5), print a one-paragraph aggregated summary in the chat, surface any conflicts/blockers. Then stop.
+- If a follow-up surfaces that needs a different specialist, the user re-prompts; Project Manager routes/orchestrates again from scratch.

package/.claude/skills/quality-standards/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: quality-standards
+description: Reference knowledge pack for the project's senior+ quality standards — a11y (jest-axe + @axe-core/playwright), performance (Lighthouse CI budgets), and testing pyramid (unit/integration/e2e ratios). Use when configuring jest-axe in a new project, setting up Lighthouse CI, computing pyramid ratios, or interpreting violations of these gates. This is a knowledge skill — it does not execute commands; it provides the canonical reference that `qa-engineer` and `gate-keeper` consult on demand. Triggers on "a11y setup", "jest-axe config", "axe-playwright config", "Lighthouse CI config", "lighthouserc.json", "performance budget", "pyramid ratio", "testing pyramid", "como configurar acessibilidade", "configura lhci". PT triggers: 'a11y setup', 'configura jest-axe', 'pirâmide de testes', 'orçamento de performance'.
+tools: Read, Glob, Grep
+model: sonnet
+---
+
+# Quality Standards — Knowledge Pack
+
+> **Knowledge skill, not executor.** This skill provides canonical configuration and rationale for three quality gates that `qa-engineer` and `gate-keeper` implement: accessibility (jest-axe + axe-playwright), performance (Lighthouse CI), and testing pyramid ratios. No commands run here — consult and apply.
+
+This pack was extracted from `qa-engineer.md` (368L → ~190L) on 2026-05-27 to keep the qa-engineer agent focused on test authorship while leaving long-form references reusable.
+
+Always respond in American English.
+
+---
+
+## 1. Accessibility (per ADR-007)
+
+### 1.1 Component-level — `jest-axe`
+
+Install once per Angular project:
+```bash
+npm i -D jest-axe @types/jest-axe
+```
+
+Every component spec MUST run `axe` after render:
+
+```typescript
+import { render } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { ProductFormComponent } from './product-form.component';
+
+expect.extend(toHaveNoViolations);
+
+test('product-form has no a11y violations', async () => {
+  const { container } = await render(ProductFormComponent);
+  const results = await axe(container, {
+    rules: { /* override only with justification + ADR */ }
+  });
+  expect(results).toHaveNoViolations();
+});
+```
+
+**Gate enforced by `gate-keeper`**: 0 violations of impact `serious` or `critical`. Violations `minor`/`moderate` go to `docs/brain/architecture/tech-debt.md` with deadline.
+
+### 1.2 E2E-level — `@axe-core/playwright`
+
+Install once:
+```bash
+npm i -D @axe-core/playwright
+```
+
+Every Playwright spec MUST run a full-page scan after the critical interaction:
+
+```typescript
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('checkout flow is a11y clean', async ({ page }) => {
+  await page.goto('/checkout');
+  await page.getByRole('button', { name: /confirmar/i }).click();
+
+  const results = await new AxeBuilder({ page })
+    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
+    .analyze();
+
+  expect(results.violations.filter(v => ['serious','critical'].includes(v.impact))).toEqual([]);
+});
+```
+
+### 1.3 Reusable helper
+
+`tests/e2e/_axe.ts`:
+
+```typescript
+import AxeBuilder from '@axe-core/playwright';
+import type { Page } from '@playwright/test';
+
+export async function expectNoA11yViolations(page: Page) {
+  const results = await new AxeBuilder({ page })
+    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
+    .analyze();
+  const blocking = results.violations.filter(v =>
+    ['serious', 'critical'].includes(v.impact ?? '')
+  );
+  if (blocking.length > 0) {
+    const summary = blocking.map(v => `${v.id} (${v.impact}): ${v.help}`).join('\n');
+    throw new Error(`A11y violations:\n${summary}`);
+  }
+}
+```
+
+---
+
+## 2. Performance budget — Lighthouse CI (per ADR-007)
+
+Install once:
+```bash
+npm i -D @lhci/cli
+```
+
+`lighthouserc.json` (project root):
+
+```json
+{
+  "ci": {
+    "collect": {
+      "url": ["http://localhost:4200/"],
+      "numberOfRuns": 3,
+      "settings": { "preset": "desktop" }
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["error", { "minScore": 0.80 }],
+        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
+        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
+        "total-blocking-time": ["error", { "maxNumericValue": 300 }]
+      }
+    },
+    "upload": { "target": "filesystem", "outputDir": "./.lighthouseci" }
+  }
+}
+```
+
+Command run by `gate-keeper` after `ng build --configuration=production`:
+
+```bash
+npx lhci autorun
+```
+
+`@lhci/cli` runs 3 times and uses median automatically. Fail in 2 of 3 = RED.
+
+**Thresholds (hard-fail in median-of-3)**:
+- Performance score ≥ 0.80
+- LCP ≤ 2500ms
+- CLS ≤ 0.1
+- TBT ≤ 300ms
+
+---
+
+## 3. Testing pyramid — 70/20/10 (per ADR-007)
+
+Metric collected by `gate-keeper` counting test files:
+
+- **Backend**: `**/*Test.java` (unit) | `**/*IT.java` (integration) | E2E does not count on backend
+- **Frontend**: `**/*.spec.ts` excluding `tests/e2e/**` (unit/integration summed) | `tests/e2e/**/*.spec.ts` (E2E)
+
+Calculation:
+
+```
+total = unit + integration + e2e
+unit_ratio        = unit / total
+integration_ratio = integration / total
+e2e_ratio         = e2e / total
+```
+
+### 3.1 Targets (warn outside these ranges)
+
+- `unit_ratio ≥ 60%` (ideal 70%)
+- `integration_ratio ∈ [15%, 30%]`
+- `e2e_ratio ≤ 15%` (ideal 10%)
+
+**Hard-fail only on `e2e_ratio > 30%`.** Above that = architectural smell — the team is testing through the top because the domain is poorly modeled.
+
+### 3.2 gate-keeper report line
+
+```
+Pyramid: unit 72% (180) | integration 22% (55) | e2e 6% (15) → balanced
+```
+
+or
+
+```
+Pyramid: unit 45% (90) | integration 20% (40) | e2e 35% (70) → RED: e2e_ratio > 30%
+```
+
+### 3.3 Fixing high `e2e_ratio`
+
+The cure is **never** deleting E2E tests. Instead:
+
+1. Identify E2E that duplicates integration coverage — promote to integration test (Testcontainers).
+2. Identify E2E that duplicates unit coverage — promote to unit test.
+3. Domain modeling review — if behaviors only assertable end-to-end, the domain has anemic abstractions.
+
+The hook `block-test-deletion.sh` (when implemented) refuses `rm` on test files without an ADR.
+
+---
+
+## 4. Who consults this skill
+
+- `qa-engineer` agent — reads this when authoring new a11y tests, configuring jest-axe, or interpreting violations.
+- `gate-keeper` agent — reads this when computing pyramid ratio, running lhci, or formatting reports.
+- `auto-test-guard` skill — references this in `resources/senior-gate.md`.
+- `prd-ready-check` skill — consults thresholds when deciding GO/NO-GO.
+
+## 5. References
+
+- ADR-007 (Senior+ gate: a11y + Lighthouse + pyramid thresholds)
+- ADR-008 (Standard senior+ pipeline — when this skill is consulted in the flow)
+- `.claude/agents/qa-engineer.md` (test author — slim version after this pack was extracted)
+- `.claude/agents/gate-keeper.md` (gate runner)
+- `.claude/skills/auto-test-guard/resources/senior-gate.md` (gate manifest)