@eltonssouza/development-utility-kit 1.0.0

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

@@ -0,0 +1,201 @@
+---
+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'.
+---
+
+# 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)

package/.claude/skills/quick-feature/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: quick-feature
+description: Fast-lane for small/medium features that don't justify the full grill-me → to-prd → to-issues → analyst → run-sprint pipeline. Use when the requirement is concrete enough that a 5-question discovery interview would be friction, not value. Examples: "add a new field to the Product DTO", "fix the search to be case-insensitive", "create endpoint to export sales as CSV", "add pagination to the orders list", "add a confirm dialog before delete". Triggers on "quick feature", "atalho", "fast-lane", "feature pequena", "ajuste rápido", "small feature", "tarefa pequena". Generates a minimal PLAN_*.md (1 sprint, 1-3 tasks, goal-ready DoD) directly from the user's description — no discovery, no PRD, no issues — and hands off to run-sprint. Do NOT use for new bounded contexts, new domain concepts, cross-cutting refactors, or features requiring architectural decisions (those still need grill-me + analyst + ADR). Do NOT use to skip the senior+ gate — gate-keeper still runs at end-of-task. PT triggers: 'feature rápida', 'tarefa pequena', 'ajuste rápido', 'pula a entrevista', 'só vai e faz', 'quick feature', 'atalho'.
+---
+
+# Quick Feature — Fast-lane for small features
+
+> **Bypass authorized only for low-risk, well-scoped work.** The full pipeline (`grill-me → to-prd → to-issues → analyst → run-sprint`) exists to surface hidden requirements and force discovery. For small features where the requirement is already concrete, that pipeline is friction. This skill is the audited bypass: it generates a minimal PLAN, dispatches `run-sprint`, and lets `gate-keeper` do its job at the end.
+
+Always respond in American English.
+
+---
+
+## 1. When to trigger
+
+- "quick feature: <description>"
+- "atalho: <descrição>"
+- "feature pequena: <X>", "tarefa pequena: <X>", "ajuste rápido"
+- "pula a entrevista, é simples"
+- "só vai e faz: <X>"
+- "small feature", "fast-lane"
+- Examples that fit:
+  - "add a new field `description` to ProductRequest DTO with validation"
+  - "fix the product search to be case-insensitive"
+  - "add CSV export to the sales list page"
+  - "add a confirmation dialog before deleting an order"
+  - "expose a new GET endpoint that returns count by status"
+
+## 2. When NOT to trigger
+
+This skill is **NOT** for:
+
+- **New bounded context** or new domain concept → `grill-me` + `to-prd` + `analyst` (full pipeline).
+- **Cross-cutting refactor** (changing pattern, splitting monolith, redesigning API) → `tech-lead` + ADR.
+- **Architectural decision** (Kafka vs SQS, Hexagonal vs Clean, new lib choice) → `tech-lead` + ADR.
+- **Feature touching > 5 files or > 2 bounded contexts** → use full pipeline; it's not small.
+- **Ambiguous requirements** (you can phrase 3+ different things from the prompt) → `grill-me` instead.
+- **Bug in production** → `pair-debug` (hypothesis-driven), not this.
+- **Performance regression without clear cause** → `pair-debug` + `tech-lead`.
+
+When in doubt → full pipeline. Bypass exists for clear cases; ambiguity is the signal to NOT bypass.
+
+## 3. Flow
+
+### Step 1 — Confirm scope is "small"
+
+Apply the 4-question sanity check (silent, do not ask the user):
+
+1. Is the requirement concrete enough to phrase as a single user story?
+2. Does it touch ≤ 5 files in a single bounded context?
+3. Does it NOT require an ADR (no pattern change, no new dependency)?
+4. Are inputs/outputs/validation already implied by existing code patterns?
+
+If any answer is **no**, **stop and instruct** the user to use the full pipeline (`grill me sobre <X>`). Do not generate the PLAN.
+
+### Stage 0 — Stack pre-resolution (per ADR-026 Layer 1)
+
+> **MANDATORY after Step 1 sanity check passes and BEFORE Step 2 grounding.** Resolves the project's stack so every downstream dispatch (`sprint-runner` → developers, `qa-engineer`, `gate-keeper`) receives the correct knowledge pack inline in its prompt. Avoids re-resolution in `run-sprint` (optimization: resolve once, propagate).
+
+Steps:
+
+a) Invoke `stack-resolver` via Task tool:
+
+```
+Task(
+  subagent_type: "stack-resolver",
+  description: "Resolve stack for project at CWD",
+  prompt: "resolve stack for project at CWD"
+)
+```
+
+b) Parse the first line of `stack-resolver` output:
+
+- **`[STACK: <lang>/<framework>-<major> | PACK: loaded]`** — extract the full `STACK CONTEXT` block from the response. Store it in memory as `STACK_CONTEXT_BLOCK` for use in Step 4 dispatch.
+- **`[STACK: <lang>/<framework>-<major> | PACK: none]`** — pack missing. Dispatch the `create-stack-pack` skill conversationally:
+
+  ```
+  Stack pack ausente para `<lang>/<framework>-<major>`. Disparando `create-stack-pack` para gerar agora; depois repito Stage 0.
+  ```
+
+  Once the pack is created, repeat Stage 0a.
+
+c) `STACK_CONTEXT_BLOCK` is now ready to inject as a prompt prefix into Step 4 dispatch (and any in-flow Task call this skill makes).
+
+If `stack-resolver` cannot determine the stack (no `## Project Identity` in CLAUDE.md, unparseable `Primary stack`), abort with a clear message:
+
+```
+Não consegui resolver a stack do projeto. Preencha a seção `## Project Identity` da CLAUDE.md com `Primary stack: <lang> <version> + <framework> <version>` e tente de novo.
+```
+
+### Step 2 — Ground in the codebase
+
+Read existing similar code via `Read`, `Glob`, `Grep`:
+- For backend: find an analogous endpoint/use case/service.
+- For frontend: find an analogous component/feature folder.
+- For database: find existing migration patterns + naming.
+
+State to the user in 2-3 lines what you found (anchoring the work in concrete files).
+
+### Step 3 — Generate minimal PLAN
+
+Write `docs/plans/PLAN_<slug>.md` with this slim structure:
+
+```markdown
+# PLAN — <feature title>
+
+- **Type**: quick-feature (fast-lane, bypassed discovery)
+- **Date**: <ISO>
+- **Estimated effort**: S (small, 1-3 tasks, ≤ 1 sprint)
+- **Bounded context**: <module/feature>
+- **Anchored in**: <list of existing files used as reference>
+- **Stack**: <lang>/<framework>-<major> (from Stage 0)
+
+## 1. User story (single, prose)
+
+As a <persona>, I want <capability>, so that <value>.
+
+## 2. Acceptance criteria (Given/When/Then)
+
+- Given <state>, When <action>, Then <result>.
+- (1-3 criteria — happy path + main edge case)
+
+## 3. Sprint 1 — Tasks
+
+### Task 1.1 — <verb + noun>
+- **Layer**: backend|frontend|migration|test
+- **Files touched** (expected): <list>
+- **Definition of Done** (goal-ready):
+  - `<command>` returns exit 0
+  - file `<path>` contains `<assertion>`
+  - test `<TestClass#method>` passes
+
+### Task 1.2 — ...
+
+### Task 1.3 — ... (optional)
+
+## 4. Out of scope (explicit)
+
+- <thing user might expect but isn't included>
+- (1-3 items to prevent scope creep)
+
+## 5. /goal block
+
+```
+/goal "PLAN_<slug>.md Sprint 1 is done when:
+1. <DoD task 1.1 verbatim>
+2. <DoD task 1.2 verbatim>
+3. ./mvnw verify returns exit 0
+4. npm test -- --watchAll=false returns exit 0
+5. gate-keeper returns GREEN on the new code
+"
+```
+```
+
+### Step 4 — Hand off to run-sprint
+
+Dispatch via Task tool, prefixing the prompt with the `STACK_CONTEXT_BLOCK` captured in Stage 0:
+
+```
+Task(
+  subagent_type: "sprint-runner",
+  description: "Execute Sprint 1 of PLAN_<slug>.md (quick-feature fast-lane)",
+  prompt: """<STACK_CONTEXT_BLOCK from Stage 0>
+
+caller: quick-feature
+plan_path: docs/plans/PLAN_<slug>.md
+sprint: 1
+
+This PLAN was generated via the quick-feature fast-lane skill — bypassed grill-me/to-prd/to-issues. Treat it as a normal PLAN for execution purposes. TDD is still mandatory (qa-engineer before developer). gate-keeper still validates senior+ thresholds at end-of-task.
+
+Stack already resolved upstream; reuse the STACK CONTEXT above when dispatching to backend-developer / frontend-developer / qa-engineer / gate-keeper instead of re-running stack-resolver."""
+)
+```
+
+### Step 5 — Done
+
+After `run-sprint` returns GREEN, suggest `brain-keeper` to register the feature:
+
+```
+Próximo passo: `registra no cérebro` (brain-keeper salva docs/brain/features/<slug>.md + daily note).
+```
+
+## 4. Inviolable rules
+
+1. **Sanity check in Step 1 is non-negotiable.** Bypass exists for clear cases; ambiguity = full pipeline.
+2. **Stage 0 stack pre-resolution is non-negotiable.** No dispatch to `run-sprint` without `STACK_CONTEXT_BLOCK` from `stack-resolver` (per ADR-026 Layer 1).
+3. **No skip of senior+ gate.** `gate-keeper` runs at end of every task in `run-sprint`, even via fast-lane.
+4. **TDD remains mandatory.** `sprint-runner` still spawns `qa-engineer` to write failing tests before the developer.
+5. **No ADR-level decisions inside quick-feature.** If during execution an architectural question surfaces, `sprint-runner` escalates to `tech-lead`.
+6. **PLAN is goal-ready.** DoD must reference concrete commands/files/tests verifiable by Claude Code's `/goal` evaluator.
+7. **Persist always.** Even fast-lane writes `PLAN_<slug>.md` — auditability is non-negotiable.
+
+## 5. Interface with other skills/agents
+
+- `stack-resolver` — invoked in Stage 0 to resolve project stack and load knowledge pack (ADR-026 Layer 1).
+- `create-stack-pack` — invoked from Stage 0 when pack is missing for the declared stack.
+- `grill-me` — alternative entry for ambiguous features. Use it when sanity check fails.
+- `analyst` — accepts quick-feature PLAN as valid seed (via `caller: quick-feature` signal in Task prompt; same exemption as `caller: sprint-runner|autonomous`).
+- `sprint-runner` — executes the generated PLAN normally; receives `STACK_CONTEXT_BLOCK` inline in its prompt to skip its own re-resolution.
+- `gate-keeper` — runs senior+ gate end-of-task regardless of how PLAN was produced.
+- `brain-keeper` — registers history post-sprint.
+
+## 6. Examples
+
+### Example A — adding a field
+
+User: `quick-feature: adicionar campo description em ProductRequest com validação NotBlank Size max 500`
+
+Skill output (after Stage 0 + Step 2 grounding):
+- Stage 0: `stack-resolver` returned `[STACK: java/spring-boot-4 | PACK: loaded]`. Loaded `.claude/stacks/java/spring-boot-4.md` (record DTO + Bean Validation + jakarta.validation).
+- Identified existing: `application/dto/ProductRequest.java` (current fields: name, price)
+- Identified existing: `web/controller/ProductController.java` (uses @Valid)
+- PLAN with 2 tasks:
+  - Task 1.1: add `@NotBlank @Size(max=500) String description` field + update tests
+  - Task 1.2: update OpenAPI spec + regenerate frontend types via `openapi-typescript`
+
+Step 4 dispatch:
+
+```
+Task(
+  subagent_type: "sprint-runner",
+  description: "Execute Sprint 1 of PLAN_product-description-field.md (quick-feature fast-lane)",
+  prompt: """[STACK: java/spring-boot-4 | PACK: loaded]
+
+STACK CONTEXT
+- Language: Java 25
+- Framework: Spring Boot 4.0.x
+- DTO pattern: record (immutable)
+- Validation: jakarta.validation (@Valid, @NotBlank, @Size)
+- (...pack body inlined...)
+
+caller: quick-feature
+plan_path: docs/plans/PLAN_product-description-field.md
+sprint: 1
+(...)"""
+)
+```
+
+### Example B — UI ajuste
+
+User: `feature pequena: adicionar dialog de confirmação antes de deletar pedido`
+
+Skill output:
+- Stage 0: `stack-resolver` returned `[STACK: typescript/angular-21 | PACK: loaded]`.
+- Identified existing: `features/orders/order-list.component.ts` (uses NgbModal already)
+- PLAN with 2 tasks:
+  - Task 1.1: extrair ConfirmDialogComponent reutilizável em `shared/components/` (3 arquivos separados conforme pack Angular 21)
+  - Task 1.2: integrar em `OrderListComponent.delete()` + teste Jest + a11y
+
+### Example C — caso que NÃO encaixa
+
+User: `quick-feature: refatorar o módulo de pagamento pra usar Strategy Pattern`
+
+Skill output:
+> Sanity check falhou (Q3: requer ADR sobre pattern). Use o fluxo completo: `grill me sobre refatorar pagamento` → produz DISCOVERY → ADR de pattern → PLAN normal. Esta skill é só para features pequenas sem decisão arquitetural.
+
+### Example D — pack ausente
+
+User: `quick-feature: adicionar endpoint /health customizado`
+
+Skill output (Stage 0):
+- `stack-resolver` returned `[STACK: python/fastapi-0.115 | PACK: none]`.
+- Disparando `create-stack-pack` para gerar `.claude/stacks/python/fastapi-0.md` (conversa de 5-8 perguntas).
+- Após pack criado, repito Stage 0a → `PACK: loaded` → segue para Step 2.