hatch3r 1.5.1 → 1.6.2

package/rules/hatch3r-observability-tracing.mdc

@@ -21,7 +21,7 @@ Core distributed tracing and OpenTelemetry conventions. For structured logging s
 | Queue       | `{queue} {operation}`         | `tasks-queue publish`       |
 | Internal    | `{module}.{function}`         | `auth.verifyToken`          |
 
-- Required span attributes: `service.name`, `service.version`, `deployment.environment`. Add domain-specific attributes where relevant.
+- Required span attributes: `service.name`, `service.version`, `deployment.environment`. Add domain-specific attributes (e.g., `user.id`, `tenant.id`) where relevant.
 - Parent-child span relationships: every outbound call (HTTP, DB, queue) creates a child span of the current context. Never create orphan spans.
 - Sampling strategies: use `ParentBased(TraceIdRatioBased(0.1))` in production (10% sample rate). Always sample errors and slow requests (> p95 latency) at 100%.
 - Use the OpenTelemetry Collector as a gateway between applications and backends to enable batching, retrying, and vendor-neutral export.
@@ -29,48 +29,53 @@ Core distributed tracing and OpenTelemetry conventions. For structured logging s
 
 ## OpenTelemetry Semantic Conventions
 
-Follow the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) (v1.29+) for consistent attribute naming.
+Follow the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) (v1.29+) for consistent attribute naming across all telemetry signals.
 
 ### Standard Attribute Namespaces
 
 | Namespace | Scope | Key Attributes |
 |-----------|-------|----------------|
-| `http.*` | HTTP client and server spans | `http.request.method`, `http.response.status_code`, `http.route` |
-| `db.*` | Database client spans | `db.system`, `db.operation.name`, `db.collection.name` |
-| `rpc.*` | RPC client and server spans | `rpc.system`, `rpc.service`, `rpc.method` |
+| `http.*` | HTTP client and server spans | `http.request.method`, `http.response.status_code`, `http.route`, `url.full`, `url.scheme` |
+| `db.*` | Database client spans | `db.system`, `db.operation.name`, `db.collection.name`, `db.query.text` (sanitized) |
+| `rpc.*` | RPC client and server spans | `rpc.system`, `rpc.service`, `rpc.method`, `rpc.grpc.status_code` |
 | `messaging.*` | Message queue spans | `messaging.system`, `messaging.operation.type`, `messaging.destination.name` |
 | `faas.*` | Serverless/FaaS invocations | `faas.trigger`, `faas.invoked_name`, `faas.coldstart` |
 | `cloud.*` | Cloud provider context | `cloud.provider`, `cloud.region`, `cloud.availability_zone` |
 | `k8s.*` | Kubernetes context | `k8s.namespace.name`, `k8s.pod.name`, `k8s.deployment.name` |
 
-- Use semantic convention attribute names exactly as specified.
-- Prefer experimental conventions over project-specific names for future migration.
+- Use semantic convention attribute names exactly as specified. Do not invent custom alternatives for concepts already covered.
+- When semantic conventions are marked "Experimental," prefer them over project-specific names to ease future migration.
 
 ### Resource Semantic Conventions
 
+Every telemetry-producing service must declare resource attributes at startup:
+
 | Attribute | Requirement | Description |
 |-----------|-------------|-------------|
 | `service.name` | Required | Logical name of the service |
 | `service.version` | Recommended | Semantic version of the service |
-| `deployment.environment.name` | Recommended | Deployment environment |
-| `service.instance.id` | Recommended | Unique instance identifier |
+| `deployment.environment.name` | Recommended | Deployment environment (production, staging, development) |
+| `service.instance.id` | Recommended | Unique instance identifier (pod name, container ID) |
+
+- Configure via environment variables (`OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`) or programmatically at SDK initialization.
+- Do not use the default `unknown_service` value in any deployed environment.
 
 ### Span Status Codes
 
 | Code | When to Set |
 |------|-------------|
 | `UNSET` | Default. Span completed without error indication. |
-| `OK` | Explicitly override lower-level error signals. Use sparingly. |
-| `ERROR` | Exception caught, HTTP 5xx, or business-logic error. |
+| `OK` | Set only when the application explicitly considers the operation successful and wants to override lower-level error signals. Use sparingly. |
+| `ERROR` | Operation failed: exception caught, HTTP 5xx, or business-logic error visible in error rate metrics. |
 
-- Set `ERROR` for server-side errors (5xx) and unhandled exceptions. Do not set `ERROR` for client errors (4xx).
-- Attach exceptions as span events when setting `ERROR`.
+- Set `ERROR` for server-side errors (5xx) and unhandled exceptions. Do not set `ERROR` for client errors (4xx) on the server span.
+- Attach exceptions as span events (`exception.type`, `exception.message`, `exception.stacktrace`) when setting `ERROR`.
 
 ### Attribute Naming Guidelines
 
 - Use dot-separated namespaces: `http.request.method`, not `httpRequestMethod`.
-- Attribute values should be low-cardinality. Never use unbounded values as attribute values.
-- Prefix custom attributes with your project namespace.
+- Attribute values should be low-cardinality. Never use unbounded values (full URLs with query params, raw SQL) as attribute values.
+- Prefer semantic convention attributes over custom attributes. Prefix custom attributes with your project namespace (e.g., `myapp.feature.flag_key`).
 
 ### AI Agent Semantic Conventions (Summary)
 

package/rules/hatch3r-performance-budgets.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-performance-budgets
 type: rule
-description: Performance budgets and targets for the project
+description: Core Web Vitals targets, API response-time tables, database query caps, bundle-size limits, and Lighthouse CI enforcement gates
 scope: conditional
 globs: "**/*perf*,**/*benchmark*,**/*budget*,**/lighthouse*,**/*.perf.*"
 tags: [performance]

package/rules/hatch3r-performance-budgets.mdc

@@ -1,5 +1,5 @@
 ---
-description: Performance budgets and targets for the project
+description: Core Web Vitals targets, API response-time tables, database query caps, bundle-size limits, and Lighthouse CI enforcement gates
 globs: ["**/*perf*", "**/*benchmark*", "**/*budget*", "**/lighthouse*", "**/*.perf.*"]
 alwaysApply: false
 ---

package/rules/hatch3r-secrets-management.mdc

@@ -1,6 +1,7 @@
 ---
 description: Secret management, rotation, and secure handling patterns for the project
 globs: ["**/.env*", "**/*secret*", "**/*credential*", "**/*token*", "**/config/**", "**/.gitignore", "**/vault/**", "**/*auth*.config*"]
+alwaysApply: false
 ---
 # Secrets Management
 

package/rules/hatch3r-security-patterns.md

@@ -55,7 +55,7 @@ quality_charter: agents/shared/quality-charter.md
 ### ASI01 — Agent Goal Hijack
 
 - Separate system prompts from user input with clear delimiters. Never allow user content to override system instructions.
-- Implement input guardrails: scan user messages for injection patterns before LLM processing.
+- Implement input guardrails: scan user messages for injection patterns before LLM processing. Canonical pattern catalog: `agents/shared/injection-patterns.md` (Sections A, B, C enumerate pipeline, learnings-storage, and user-facing screening patterns respectively).
 - Enforce instruction hierarchy: system > developer > user. Reject attempts to redefine agent purpose.
 - Defend against indirect prompt injection: sanitize and tag content retrieved from external sources (RAG, web, files) before including in context.
 

package/rules/hatch3r-security-patterns.mdc

@@ -1,6 +1,7 @@
 ---
 description: Security patterns including input validation, auth enforcement, and AI/agentic security for the project
 globs: ["**/auth/**", "**/security/**", "**/middleware/**", "**/*auth*", "**/*guard*", "**/*policy*", "**/*permission*", "**/*sanitiz*", "**/*validat*"]
+alwaysApply: false
 ---
 # Security Patterns
 
@@ -51,7 +52,7 @@ globs: ["**/auth/**", "**/security/**", "**/middleware/**", "**/*auth*", "**/*gu
 ### ASI01 — Agent Goal Hijack
 
 - Separate system prompts from user input with clear delimiters. Never allow user content to override system instructions.
-- Implement input guardrails: scan user messages for injection patterns before LLM processing.
+- Implement input guardrails: scan user messages for injection patterns before LLM processing. Canonical pattern catalog: `agents/shared/injection-patterns.md` (Sections A, B, C enumerate pipeline, learnings-storage, and user-facing screening patterns respectively).
 - Enforce instruction hierarchy: system > developer > user. Reject attempts to redefine agent purpose.
 - Defend against indirect prompt injection: sanitize and tag content retrieved from external sources (RAG, web, files) before including in context.
 
@@ -199,7 +200,7 @@ globs: ["**/auth/**", "**/security/**", "**/middleware/**", "**/*auth*", "**/*gu
 ### A08 — Software and Data Integrity Failures
 
 - Verify integrity of all software updates, dependencies, and CI/CD pipeline artifacts using digital signatures or checksums.
-- Use lockfiles and verify their integrity. `npm ci` (not `npm install`) in CI to ensure deterministic builds.
+- Use lockfiles and verify their integrity. `npm ci` (not `npm install`) in CI for deterministic builds that fail on lockfile drift.
 - CI/CD pipelines: require code review for all changes, enforce branch protection, sign commits where feasible.
 - Never deserialize untrusted data without validation. Use schemas (zod, JSON Schema) to validate structure before processing.
 - Protect CI/CD secrets and permissions: restrict who can modify pipeline configuration, require approval for deployment steps.

package/rules/hatch3r-testing.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-testing
 type: rule
-description: Test standards and conventions for the project
+description: Coverage thresholds, mocking strategy, property-based testing, mutation-score targets, flaky test quarantine, and snapshot test discipline
 scope: "**/*.test.*,**/*.spec.*,**/__tests__/**,**/tests/**,**/test/**,**/*.cy.*,**/playwright/**,**/vitest.config.*,**/jest.config.*,**/cypress.config.*"
 tags: [core]
 quality_charter: agents/shared/quality-charter.md

package/rules/hatch3r-testing.mdc

@@ -1,6 +1,7 @@
 ---
-description: Test standards and conventions for the project
+description: Coverage thresholds, mocking strategy, property-based testing, mutation-score targets, flaky test quarantine, and snapshot test discipline
 globs: ["**/*.test.*", "**/*.spec.*", "**/__tests__/**", "**/tests/**", "**/test/**", "**/*.cy.*", "**/playwright/**", "**/vitest.config.*", "**/jest.config.*", "**/cypress.config.*"]
+alwaysApply: false
 ---
 # Testing Standards
 
@@ -90,7 +91,7 @@ Error handling code is often under-tested because developers focus on happy path
 
 - **Use sparingly.** Snapshots are appropriate for serialized output (JSON API responses, CLI output, rendered HTML structure) where the exact output matters and is stable.
 - **Not appropriate for:** UI component visual appearance (use visual regression tests), objects with timestamps or random IDs (unstable), large objects (unreadable diffs).
-- **Review discipline.** Snapshot updates (`--update-snapshots`) must be reviewed as carefully as code changes. Reviewers must verify the new snapshot is intentionally correct, not just "different."
+- **Review discipline.** Snapshot updates (`--update-snapshots`) must be reviewed with the same rigor as code changes. Reviewers must verify the new snapshot is intentionally correct, not just "different."
 - **Keep snapshots small.** Snapshot files > 100 lines suggest the test is asserting too broadly. Narrow the assertion to the relevant subset.
 - **Inline snapshots** (where supported) are preferred over external `.snap` files for short outputs (< 20 lines) because they keep the assertion co-located with the test.
 - **Name snapshot files** to match their test file: `auth.test.ts` → `auth.test.ts.snap`.

package/rules/hatch3r-theming.md

@@ -3,8 +3,8 @@ id: hatch3r-theming
 type: rule
 description: Theming, dark mode, and color system conventions for the project
 scope: conditional
-globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.css, src/**/*.scss
-tags: [implementation]
+globs: "src/**/*.vue,src/**/*.tsx,src/**/*.jsx,src/**/*.css,src/**/*.scss,**/*theme*,**/*color*"
+tags: [implementation, lang:typescript]
 quality_charter: agents/shared/quality-charter.md
 ---
 # Theming & Dark Mode

package/rules/hatch3r-theming.mdc

@@ -40,11 +40,11 @@ alwaysApply: false
 - Provide a `high-contrast` token set with ≥ 7:1 contrast ratios for all text and ≥ 3:1 for non-text UI.
 - Detect user preference with `@media (prefers-contrast: more)` and apply high-contrast tokens.
 - Support `forced-colors` mode: use system color keywords (`Canvas`, `CanvasText`, `LinkText`, `ButtonFace`, `ButtonText`) and test that information is not conveyed by color alone.
-- Ensure focus indicators and borders remain visible under forced-colors by using `Highlight` / `SelectedItem` keywords.
+- Verify focus indicators and borders remain visible under forced-colors by testing in Windows High Contrast Mode — use `Highlight` / `SelectedItem` keywords.
 
 ## Testing
 
-- Verify theme toggle switches all tokens correctly — no unstyled or hard-coded colors leak through.
+- Verify theme toggle switches all tokens — no unstyled or hard-coded colors leak through. Inspect computed styles to confirm all color values come from design tokens.
 - Validate contrast ratios per theme using automated tools (axe-core, Lighthouse) against WCAG AA (4.5:1 text, 3:1 non-text).
 - Capture screenshots across light, dark, and high-contrast themes at key viewport sizes for visual regression comparison.
 - Test `prefers-color-scheme` and `prefers-contrast` media query overrides using browser DevTools emulation or Playwright `emulateMedia`.

package/rules/hatch3r-tooling-hierarchy.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-tooling-hierarchy
 type: rule
-description: Priority order for tools and knowledge sources
+description: Platform MCP-first priority, documentation MCP for library APIs, web research for CVEs, and browser MCP for UI verification with fallback guidance
 scope: "**/.agents/**,**/mcp/**,**/mcp.json,**/.cursor/**,**/.github/copilot*,**/.windsurf/**,**/hatch.json,**/.claude/**"
 tags: [core]
 quality_charter: agents/shared/quality-charter.md

package/rules/hatch3r-tooling-hierarchy.mdc

@@ -1,6 +1,7 @@
 ---
-description: Priority order for tools and knowledge sources
+description: Platform MCP-first priority, documentation MCP for library APIs, web research for CVEs, and browser MCP for UI verification with fallback guidance
 globs: ["**/.agents/**", "**/mcp/**", "**/mcp.json", "**/.cursor/**", "**/.github/copilot*", "**/.windsurf/**", "**/hatch.json", "**/.claude/**"]
+alwaysApply: false
 ---
 # Tooling Hierarchy
 
@@ -88,7 +89,7 @@ If no web search MCP server is configured (e.g., `brave-search` is not in `mcp.s
 Use browser automation MCP tools to visually verify UI changes after automated tests pass.
 
 **When to use:**
-- Verifying UI component changes render correctly.
+- Verifying UI component changes render as specified in the design or acceptance criteria.
 - Reproducing and confirming fixes for visually observable bugs.
 - Accessibility auditing (keyboard nav, contrast, focus indicators).
 - Frontend performance profiling (CPU, frame rate, memory).

package/skills/hatch3r-a11y-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 id: hatch3r-a11y-audit
-description: Comprehensive WCAG AA accessibility audit with findings and fixes. Use when auditing accessibility, verifying WCAG compliance, or improving a11y across the application.
+description: Run a WCAG AA accessibility audit with findings and fixes across 7 scan categories (keyboard, contrast, ARIA, reduced motion, screen reader, high contrast, automated axe). Use when auditing accessibility or verifying WCAG compliance.
 tags: [review, a11y]
 quality_charter: agents/shared/quality-charter.md
 ---
@@ -12,33 +12,30 @@ quality_charter: agents/shared/quality-charter.md
 Task Progress:
 - [ ] Step 1: Read accessibility requirements from rules and specs
 - [ ] Step 2: Automated scan — run axe-core or similar on all pages/components
-- [ ] Step 3: Manual audit — keyboard, contrast, ARIA, reduced motion, screen reader
+- [ ] Step 3: Manual audit — load references/manual-audit-checklist.md
 - [ ] Step 4: Catalog findings by severity (critical/major/minor)
 - [ ] Step 5: Fix critical and major findings
 - [ ] Step 6: Verify fixes with re-scan and manual check
 ```
 
+## Progressive Disclosure
+
+- **Main skill file (this):** Workflow steps, automated scan, fix process, DoD.
+- **`references/manual-audit-checklist.md`:** Detailed WCAG requirements matrix, per-category manual criteria, severity cataloging rubric. Load during Step 3.
+
 ## Step 1: Read Accessibility Requirements
 
-**From project component rules (Accessibility section):**
+From project component rules (Accessibility section):
 
 - All animations: wrap in `prefers-reduced-motion` media query AND check user's reduced motion setting.
-- Color contrast: ≥ 4.5:1 for text (WCAG AA).
+- Color contrast: >= 4.5:1 for text (WCAG AA).
 - Interactive elements: keyboard focusable with visible focus indicator.
 - Dynamic content changes: use `aria-live` regions.
 - Support high contrast mode.
 
-**From project quality documentation:**
+For the full WCAG requirements matrix, load `references/manual-audit-checklist.md`.
 
-| Requirement         | Standard | Details                                                          |
-| ------------------- | -------- | ---------------------------------------------------------------- |
-| Reduced motion      | WCAG 2.1 | All animations respect `prefers-reduced-motion` and user setting |
-| Color contrast      | WCAG AA  | Text contrast ratio ≥ 4.5:1                                      |
-| Keyboard navigation | WCAG 2.1 | All interactive elements focusable and operable via keyboard     |
-| Screen reader       | WCAG 2.1 | Dynamic state and reactions announced via ARIA live regions      |
-| High contrast mode  | Custom   | User-configurable high contrast theme (if applicable)            |
-
-- For external library docs and current best practices, follow the project's tooling hierarchy.
+For external library docs and current best practices, follow the project's tooling hierarchy.
 
 ## Step 2: Automated Scan
 
@@ -49,51 +46,20 @@ Task Progress:
 
 ## Step 3: Manual Audit
 
-**Keyboard navigation:**
-
-- Tab through all interactive elements. Verify logical order and confirm no focus traps exist.
-- All buttons, links, inputs, custom controls focusable.
-- Visible focus indicator (outline or ring) — no `outline: none` without replacement.
-- Escape closes modals/dropdowns. Enter/Space activates buttons.
-
-**Color contrast:**
-
-- Check text vs background: ≥ 4.5:1 for normal text, ≥ 3:1 for large text.
-- Use DevTools or contrast checker. Test with design tokens — flag any ad-hoc colors that fall below the 4.5:1 ratio.
-
-**ARIA attributes:**
+Load `references/manual-audit-checklist.md` and work through each category:
 
-- `aria-label` or `aria-labelledby` for icon-only buttons, custom controls.
-- `aria-live="polite"` or `aria-live="assertive"` for dynamic state changes, notifications.
-- `role` correct for custom widgets (button, link, tab, etc.).
-- `aria-expanded`, `aria-selected`, `aria-hidden` where appropriate.
+1. Keyboard navigation
+2. Color contrast
+3. ARIA attributes
+4. Reduced motion
+5. Screen reader
+6. High contrast mode
 
-**Reduced motion:**
-
-- Test with `prefers-reduced-motion: reduce` (DevTools → Rendering → Emulate CSS media).
-- Verify animations are disabled or simplified. Check user's reduced motion setting.
-- No motion-dependent information (per WCAG 2.1).
-
-**Screen reader:**
-
-- Test with NVDA, VoiceOver, or similar. Verify announcements for dynamic content.
-- Dynamic state, errors, and success messages announced.
-- Form labels associated, error messages linked via `aria-describedby` or `aria-errormessage`.
-
-**High contrast mode:**
-
-- Verify user-configurable high contrast theme works (if applicable). No loss of information.
+The reference file provides the specific criteria, DevTools settings, and pass/fail conditions for each.
 
 ## Step 4: Catalog Findings
 
-| Severity | Definition                              | Examples                                                      |
-| -------- | --------------------------------------- | ------------------------------------------------------------- |
-| Critical | Blocks core functionality, fails WCAG A | Missing form labels, no keyboard access to primary actions    |
-| Major    | Significant barrier, fails WCAG AA      | Contrast < 4.5:1, missing focus indicators, no reduced motion |
-| Minor    | Improves experience, best practice       | Redundant labels, suboptimal heading order                    |
-
-- Produce a findings table: ID, severity, WCAG criterion, description, location, fix suggestion.
-- Prioritize: critical first, then major. Minor can be batched.
+Use the severity rubric in `references/manual-audit-checklist.md` to assign severity. Produce a findings table: ID, severity, WCAG criterion, description, location, fix suggestion. Prioritize critical first, then major. Minor can be batched.
 
 ## Step 5: Fix Critical and Major Findings
 
@@ -133,7 +99,7 @@ You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`
 - [ ] WCAG AA compliance on all audited surfaces
 - [ ] Reduced motion respected (`prefers-reduced-motion` + user setting)
 - [ ] Keyboard navigation complete with visible focus
-- [ ] Color contrast ≥ 4.5:1 for text
+- [ ] Color contrast >= 4.5:1 for text
 - [ ] ARIA live regions for dynamic content
 - [ ] Automated scan clean for critical/major
 - [ ] Manual verification completed

package/skills/hatch3r-a11y-audit/references/manual-audit-checklist.md

@@ -0,0 +1,58 @@
+# Manual A11y Audit Checklist — Detailed Criteria
+
+Loaded on demand during Step 3 of the accessibility audit workflow when a detailed manual checklist is needed beyond the automated scan.
+
+## WCAG Requirements Matrix
+
+| Requirement         | Standard | Details                                                          |
+| ------------------- | -------- | ---------------------------------------------------------------- |
+| Reduced motion      | WCAG 2.1 | All animations respect `prefers-reduced-motion` and user setting |
+| Color contrast      | WCAG AA  | Text contrast ratio >= 4.5:1                                     |
+| Keyboard navigation | WCAG 2.1 | All interactive elements focusable and operable via keyboard     |
+| Screen reader       | WCAG 2.1 | Dynamic state and reactions announced via ARIA live regions      |
+| High contrast mode  | Custom   | User-configurable high contrast theme (if applicable)            |
+
+## Keyboard Navigation
+
+- Tab through all interactive elements. Verify logical order and confirm no focus traps exist.
+- All buttons, links, inputs, custom controls focusable.
+- Visible focus indicator (outline or ring) — no `outline: none` without replacement.
+- Escape closes modals/dropdowns. Enter/Space activates buttons.
+
+## Color Contrast
+
+- Check text vs background: >= 4.5:1 for normal text, >= 3:1 for large text.
+- Use DevTools or contrast checker. Test with design tokens — flag any ad-hoc colors that fall below the 4.5:1 ratio.
+
+## ARIA Attributes
+
+- `aria-label` or `aria-labelledby` for icon-only buttons, custom controls.
+- `aria-live="polite"` or `aria-live="assertive"` for dynamic state changes, notifications.
+- `role` correct for custom widgets (button, link, tab, etc.).
+- `aria-expanded`, `aria-selected`, `aria-hidden` where appropriate.
+
+## Reduced Motion
+
+- Test with `prefers-reduced-motion: reduce` (DevTools → Rendering → Emulate CSS media).
+- Verify animations are disabled or simplified. Check user's reduced motion setting.
+- No motion-dependent information (per WCAG 2.1).
+
+## Screen Reader
+
+- Test with NVDA, VoiceOver, or similar. Verify announcements for dynamic content.
+- Dynamic state, errors, and success messages announced.
+- Form labels associated, error messages linked via `aria-describedby` or `aria-errormessage`.
+
+## High Contrast Mode
+
+- Verify user-configurable high contrast theme works (if applicable). No loss of information.
+
+## Severity Cataloging
+
+| Severity | Definition                              | Examples                                                      |
+| -------- | --------------------------------------- | ------------------------------------------------------------- |
+| Critical | Blocks core functionality, fails WCAG A | Missing form labels, no keyboard access to primary actions    |
+| Major    | Significant barrier, fails WCAG AA      | Contrast < 4.5:1, missing focus indicators, no reduced motion |
+| Minor    | Improves experience, best practice      | Redundant labels, suboptimal heading order                    |
+
+Produce a findings table: ID, severity, WCAG criterion, description, location, fix suggestion. Prioritize critical first, then major. Minor can be batched.

package/skills/hatch3r-agent-customize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 id: hatch3r-agent-customize
-description: Agent customization — redirects to the unified hatch3r-customize skill.
+description: Redirect to write agent persona, model, and apply-scope overrides under .hatch3r/agents/ -- use when tailoring a sub-agent for the current repository
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 ---

package/skills/hatch3r-command-customize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 id: hatch3r-command-customize
-description: Command customization — redirects to the unified hatch3r-customize skill.
+description: Redirect to edit orchestrator pipeline and prompt wording for slash commands under .hatch3r/commands/ -- use when changing how a command fans out to sub-agents
 tags: [customize]
 quality_charter: agents/shared/quality-charter.md
 ---