hatch3r 1.3.0 → 1.5.0

package/rules/hatch3r-performance-budgets.mdc

@@ -1,5 +1,6 @@
 ---
 description: Performance budgets and targets for the project
+globs: ["**/*perf*", "**/*benchmark*", "**/*budget*", "**/lighthouse*", "**/*.perf.*"]
 alwaysApply: false
 ---
 # Performance Budgets

package/rules/hatch3r-secrets-management.md

@@ -2,8 +2,9 @@
 id: hatch3r-secrets-management
 type: rule
 description: Secret management, rotation, and secure handling patterns for the project
-scope: always
+scope: "**/.env*,**/*secret*,**/*credential*,**/*token*,**/config/**,**/.gitignore,**/vault/**,**/*auth*.config*"
 tags: [security]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Secrets Management
 

package/rules/hatch3r-secrets-management.mdc

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

package/rules/hatch3r-security-patterns.md

@@ -2,8 +2,9 @@
 id: hatch3r-security-patterns
 type: rule
 description: Security patterns including input validation, auth enforcement, and AI/agentic security for the project
-scope: always
+scope: "**/auth/**,**/security/**,**/middleware/**,**/*auth*,**/*guard*,**/*policy*,**/*permission*,**/*sanitiz*,**/*validat*"
 tags: [security]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Security Patterns
 
@@ -202,7 +203,7 @@ tags: [security]
 ### 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-security-patterns.mdc

@@ -1,6 +1,6 @@
 ---
 description: Security patterns including input validation, auth enforcement, and AI/agentic security for the project
-alwaysApply: true
+globs: ["**/auth/**", "**/security/**", "**/middleware/**", "**/*auth*", "**/*guard*", "**/*policy*", "**/*permission*", "**/*sanitiz*", "**/*validat*"]
 ---
 # Security Patterns
 
@@ -61,6 +61,11 @@ alwaysApply: true
 - Enforce parameter schemas on every tool call. Reject calls with unexpected, missing, or out-of-range arguments.
 - Rate-limit tool invocations per agent per time window. Alert on anomalous tool usage patterns.
 - Sandbox tool execution: restrict file system access, network egress, and subprocess spawning.
+- **MCP server filesystem scope:** MCP servers with filesystem access must be scoped to the minimum necessary directories:
+  - Restrict filesystem access to the project directory. MCP servers should never have access to the home directory, system directories, or unrelated project directories.
+  - Document which MCP servers have filesystem access and define their intended scope (read-only vs read-write, which directories).
+  - Configure `allowedDirectories` in MCP server configs where supported. If the server does not support directory restrictions, document this as a known risk and apply compensating controls (monitoring, read-only mode).
+  - Audit MCP server filesystem access on configuration changes. Verify that added servers do not expand the filesystem attack surface beyond the project boundary.
 
 ### ASI03 — Identity & Privilege Abuse
 
@@ -75,6 +80,12 @@ alwaysApply: true
 - Verify package integrity (checksums, signatures) before loading tools or plugins.
 - Audit third-party prompt templates for injected instructions before use.
 - Maintain an allowlist of approved MCP servers and tool sources.
+- **`npx -y` safety:** The `-y` flag auto-confirms installation of unknown packages without prompts, creating a supply chain attack vector:
+  - Never use `npx -y` with untrusted, unknown, or typo-squattable package names.
+  - Always pin explicit versions when using npx: `npx package@1.2.3` instead of `npx package`.
+  - Prefer `npm exec --package=package@version -- command` for critical tooling — it provides explicit version control and avoids silent auto-install.
+  - In CI pipelines, install tools as explicit `devDependencies` with pinned versions rather than relying on `npx` at runtime.
+  - Verify the package name and publisher on the npm registry before first use. Typosquatting attacks exploit `npx -y` by registering names similar to popular packages.
 
 ### ASI05 — Unexpected Code Execution
 

package/rules/hatch3r-testing.md

@@ -2,8 +2,9 @@
 id: hatch3r-testing
 type: rule
 description: Test standards and conventions for the project
-scope: always
+scope: "**/*.test.*,**/*.spec.*,**/__tests__/**,**/tests/**,**/test/**,**/*.cy.*,**/playwright/**,**/vitest.config.*,**/jest.config.*,**/cypress.config.*"
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Testing Standards
 
@@ -80,11 +81,20 @@ tags: [core]
 - **Fixture files** (JSON, YAML) are acceptable for large, complex, or externally-sourced test inputs (API response snapshots, configuration samples). Store in `tests/fixtures/`.
 - **Database state:** Integration tests that require database state must set up and tear down within the test using helpers. Never depend on database state from a previous test.
 
+## Error Path Coverage
+
+Error handling code is often under-tested because developers focus on happy paths. Enforce minimum error coverage:
+
+- **Every exported function that can fail** must have at least one test exercising the error path. "Can fail" includes: functions returning `Result<T, E>`, functions with `throw` statements, async functions calling external services, and functions with input validation.
+- **Error message assertions.** Test that error messages, codes, and structured fields contain the expected values. Do not assert only that "an error was thrown" -- verify the error content.
+- **Error propagation.** When a function wraps or transforms errors from a dependency, test that the original error context is preserved (cause chain, stack trace, original error code).
+- **Boundary error tests.** For each architectural boundary (API handler, event handler, background processor), test that errors are caught, logged, and returned as safe responses without leaking internal details.
+
 ## Snapshot Testing
 
 - **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-testing.mdc

@@ -1,6 +1,6 @@
 ---
 description: Test standards and conventions for the project
-alwaysApply: true
+globs: ["**/*.test.*", "**/*.spec.*", "**/__tests__/**", "**/tests/**", "**/test/**", "**/*.cy.*", "**/playwright/**", "**/vitest.config.*", "**/jest.config.*", "**/cypress.config.*"]
 ---
 # Testing Standards
 
@@ -13,7 +13,7 @@ alwaysApply: true
 - **Named clearly.** Describe behavior: `"should award 15 XP for 25-min focus block"`.
 - **Regression.** Every bug fix includes a test that fails before the fix and passes after.
 - **No network.** Unit tests must not make network calls. Use mocks.
-- No `any` types in tests. No `.skip` without a linked issue.
+- No type escape hatches in tests. No `.skip` without a linked issue.
 - Write tests to `tests/unit/`, `tests/integration/`, `tests/e2e/`, or equivalent.
 - Use test fixtures from `tests/fixtures/` or equivalent.
 - **Browser verification.** For UI changes, verify visually in the browser via browser automation MCP after automated tests pass. Capture screenshots as evidence.
@@ -77,6 +77,15 @@ alwaysApply: true
 - **Fixture files** (JSON, YAML) are acceptable for large, complex, or externally-sourced test inputs (API response snapshots, configuration samples). Store in `tests/fixtures/`.
 - **Database state:** Integration tests that require database state must set up and tear down within the test using helpers. Never depend on database state from a previous test.
 
+## Error Path Coverage
+
+Error handling code is often under-tested because developers focus on happy paths. Enforce minimum error coverage:
+
+- **Every exported function that can fail** must have at least one test exercising the error path. "Can fail" includes: functions returning `Result<T, E>`, functions with `throw` statements, async functions calling external services, and functions with input validation.
+- **Error message assertions.** Test that error messages, codes, and structured fields contain the expected values. Do not assert only that "an error was thrown" -- verify the error content.
+- **Error propagation.** When a function wraps or transforms errors from a dependency, test that the original error context is preserved (cause chain, stack trace, original error code).
+- **Boundary error tests.** For each architectural boundary (API handler, event handler, background processor), test that errors are caught, logged, and returned as safe responses without leaking internal details.
+
 ## Snapshot Testing
 
 - **Use sparingly.** Snapshots are appropriate for serialized output (JSON API responses, CLI output, rendered HTML structure) where the exact output matters and is stable.

package/rules/hatch3r-theming.md

@@ -5,6 +5,7 @@ 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]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Theming & Dark Mode
 
@@ -43,11 +44,11 @@ tags: [implementation]
 - 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-theming.mdc

@@ -1,6 +1,6 @@
 ---
 description: Theming, dark mode, and color system conventions for the project
-globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.css, src/**/*.scss
+globs: ["src/**/*.vue", "src/**/*.tsx", "src/**/*.jsx", "src/**/*.css", "src/**/*.scss", "**/*theme*", "**/*color*"]
 alwaysApply: false
 ---
 # Theming & Dark Mode

package/rules/hatch3r-tooling-hierarchy.md

@@ -2,8 +2,9 @@
 id: hatch3r-tooling-hierarchy
 type: rule
 description: Priority order for tools and knowledge sources
-scope: always
+scope: "**/.agents/**,**/mcp/**,**/mcp.json,**/.cursor/**,**/.github/copilot*,**/.windsurf/**,**/hatch.json,**/.claude/**"
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Tooling Hierarchy
 
@@ -91,7 +92,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/rules/hatch3r-tooling-hierarchy.mdc

@@ -1,6 +1,6 @@
 ---
 description: Priority order for tools and knowledge sources
-alwaysApply: true
+globs: ["**/.agents/**", "**/mcp/**", "**/mcp.json", "**/.cursor/**", "**/.github/copilot*", "**/.windsurf/**", "**/hatch.json", "**/.claude/**"]
 ---
 # Tooling Hierarchy
 
@@ -10,25 +10,39 @@ alwaysApply: true
 
 Read `platform` from `.agents/hatch.json` to determine which platform tools to use.
 
+### Prerequisites
+
+| Platform | Auth Setup |
+|----------|-----------|
+| **GitHub** | `gh auth login` or `GITHUB_TOKEN` env var. For Projects v2: `gh auth refresh -s project` |
+| **Azure DevOps** | `az login` and `az devops configure --defaults organization=ORG project=PROJECT` |
+| **GitLab** | `glab auth login` or `GITLAB_TOKEN` env var |
+
+### Platform CLI Fallback Reference
+
 **Fallback to the platform CLI only when:**
 - The MCP tool catalog lacks the specific capability.
 - An MCP call fails repeatedly and the CLI provides a viable alternative.
 
 **Never** use the platform CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
 
-### Platform CLI Fallback Reference
-
 | Action | GitHub | Azure DevOps | GitLab |
 |--------|--------|--------------|--------|
 | Create issue | `gh issue create` | `az boards work-item create` | `glab issue create` |
+| Edit issue | `gh issue edit` | `az boards work-item update` | `glab issue update` |
 | View issue | `gh issue view` | `az boards work-item show --id N` | `glab issue view` |
 | List issues | `gh issue list` | `az boards work-item list` | `glab issue list` |
 | Create PR/MR | `gh pr create` | `az repos pr create` | `glab mr create` |
 | View PR/MR | `gh pr view` | `az repos pr show` | `glab mr view` |
 | List PRs/MRs | `gh pr list` | `az repos pr list` | `glab mr list` |
+| Merge PR/MR | `gh pr merge` | `az repos pr complete` | `glab mr merge` |
+| Search issues | `gh search issues` | `az boards query` | `glab issue list --search` |
+| Search PRs | `gh search prs` | `az repos pr list --status all` | `glab mr list --search` |
 | Search code | `gh search code` | `az repos show` | `glab search` |
-| CI runs | `gh run list/view` | `az pipelines run list/show` | `glab ci list/view` |
+| Labels | `gh label create/list` | `az boards work-item update --fields` | `glab label create/list` |
 | Releases | `gh release create` | `az repos release` | `glab release create` |
+| CI runs | `gh run list/view/watch` | `az pipelines run list/show` | `glab ci list/view` |
+| Projects | `gh project item-add/edit/list` | `az boards iteration/area` | GitLab Boards API |
 
 ## B. Documentation MCP for Library Documentation
 
@@ -94,7 +108,7 @@ Use browser automation MCP tools to visually verify UI changes after automated t
 When seeking information, follow this priority order:
 
 1. **Project specs and ADRs** — authoritative for project-specific behavior, constraints, and decisions.
-2. **Codebase exploration** (Grep, SemanticSearch) — ground truth for current implementation.
+2. **Codebase exploration** (code search tools, semantic code search) — ground truth for current implementation.
 3. **Documentation MCP** — authoritative for external library/framework APIs and patterns.
 4. **Web research** — current events, best practices, security advisories, novel problems.
 5. **Browser verification** — visual confirmation of UI changes after automated tests pass.

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

@@ -2,6 +2,7 @@
 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.
 tags: [review, a11y]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Accessibility Audit Workflow
 
@@ -50,7 +51,7 @@ Task Progress:
 
 **Keyboard navigation:**
 
-- Tab through all interactive elements. Ensure logical order, no focus traps.
+- 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.
@@ -58,7 +59,7 @@ Task Progress:
 **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 — ensure no ad-hoc colors fail.
+- Use DevTools or contrast checker. Test with design tokens — flag any ad-hoc colors that fall below the 4.5:1 ratio.
 
 **ARIA attributes:**
 
@@ -99,7 +100,7 @@ Task Progress:
 - Implement fixes following project component and quality requirements.
 - Use semantic HTML where possible (`<button>`, `<a>`, `<nav>`, `<main>`).
 - Add `aria-*` attributes for custom components.
-- Ensure `prefers-reduced-motion` respected in CSS and JS.
+- Verify `prefers-reduced-motion` is respected by enabling the media query in DevTools and confirming animations are disabled or simplified.
 - Add or fix focus styles. Use design tokens for focus ring.
 - Verify reduced-motion behavior in tests.
 
@@ -107,7 +108,7 @@ Task Progress:
 
 - Re-run automated scan. No critical or major violations.
 - Manual keyboard and screen reader check on fixed areas.
-- Run full test suite to ensure no regressions.
+- Run full test suite and confirm 0 failures to verify no regressions.
 - Document remaining minor findings for future backlog.
 
 ## Required Agent Delegation
@@ -120,6 +121,12 @@ You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`
 
 - **Rule**: `hatch3r-browser-verification` — follow this rule for live browser-based accessibility testing
 
+## Error Handling
+
+- **No automated scanner available**: If axe-core, Lighthouse, or equivalent is not installed, report the gap and proceed with manual checklist-only audit. Do not skip the audit.
+- **Scanner produces false positives**: Cross-reference automated findings against manual inspection. Mark confirmed false positives with justification and exclude from the violation count.
+- **Component renders differently across browsers**: Test in at least two browser engines (Chromium + Firefox or Safari). Document browser-specific a11y gaps with reproduction steps.
+
 ## Definition of Done
 
 - [ ] No critical a11y violations

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

@@ -1,78 +1,11 @@
 ---
 id: hatch3r-agent-customize
-description: Create and manage per-agent customization files for model overrides, description changes, and project-specific markdown instructions. Use when tailoring agent behavior to project-specific needs.
+description: Agent customization — redirects to the unified hatch3r-customize skill.
 tags: [customize]
+quality_charter: agents/shared/quality-charter.md
 ---
-# Agent Customization Management
+# Agent Customization
 
-## Quick Start
+> **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: agent`.
 
-```
-Task Progress:
-- [ ] Step 1: Identify which agent to customize
-- [ ] Step 2: Determine customization needs
-- [ ] Step 3: Create the customization files
-- [ ] Step 4: Sync to propagate changes
-- [ ] Step 5: Verify the customized output
-```
-
-## Step 1: Identify Agent
-
-Determine which hatch3r agent needs customization:
-- Review the agents in `.agents/agents/` and their default behaviors
-- Identify gaps between default behavior and project needs
-- Check for existing customization files in `.hatch3r/agents/`
-
-## Step 2: Determine Customization Needs
-
-Decide which customization approach to use:
-
-**YAML (`.customize.yaml`)** — for structured overrides:
-- **Model**: Override the agent's preferred model (e.g., `model: opus`)
-- **Description**: Change how the agent is described in adapter frontmatter
-- **Enabled**: Set to `false` to disable the agent entirely
-
-**Protected agents:** Some agents have `protected: true` in their canonical frontmatter. For these security-critical agents (e.g., reviewer, security-auditor, test-writer), customization cannot override `scope`, `description`, or `enabled` — only `model` and markdown instructions can be customized. See the `hatch3r-agent-customize` command for full details.
-
-**Markdown (`.customize.md`)** — for free-form instructions:
-- Domain-specific review checklists
-- Architecture context and constraints
-- Project-specific workflow steps
-- Compliance and security requirements
-
-## Step 3: Create Customization Files
-
-Create files in `.hatch3r/agents/`:
-
-**For YAML overrides:**
-```yaml
-# .hatch3r/agents/{agent-id}.customize.yaml
-model: opus
-description: "Security-focused reviewer for healthcare platform"
-```
-
-**For markdown instructions:**
-Create `.hatch3r/agents/{agent-id}.customize.md` with project-specific instructions. This content is injected into the managed block under `## Project Customizations`.
-
-Set only the fields/content you need — partial customization is valid.
-
-## Step 4: Sync
-
-Run `npx hatch3r sync` to propagate customizations to all adapter outputs. The sync:
-- Reads `.customize.yaml` for structured overrides (model, description, enabled)
-- Reads `.customize.md` and appends it inside the managed block
-- Generates updated output for every configured adapter (Cursor, Claude, etc.)
-
-## Step 5: Verify
-
-Confirm customizations appear in adapter output files:
-- Check model appears in frontmatter (e.g., `.cursor/agents/hatch3r-reviewer.md`)
-- Check markdown instructions appear inside the managed block
-- Verify disabled agents are absent from adapter outputs
-
-## Definition of Done
-
-- [ ] Customization files created in `.hatch3r/agents/`
-- [ ] `npx hatch3r sync` completes without errors
-- [ ] Adapter output files reflect the customizations
-- [ ] Customization files committed to the repository
+For agent-specific reference (model resolution, protected agents, YAML schema), see the `hatch3r-agent-customize` command.

package/skills/hatch3r-api-spec/SKILL.md

@@ -3,6 +3,7 @@ id: hatch3r-api-spec
 type: skill
 description: Generate and validate OpenAPI specifications from codebase. Covers endpoint design, schema validation, and documentation generation.
 tags: [planning]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 # API Specification Workflow
@@ -37,7 +38,7 @@ Task Progress:
 
 ## Step 3: Validate Schemas
 
-- Ensure all request bodies have JSON Schema validation constraints (`required`, `minLength`, `maxLength`, `pattern`, `enum`).
+- Verify all request bodies have JSON Schema validation constraints (`required`, `minLength`, `maxLength`, `pattern`, `enum`).
 - Verify response schemas match actual serialized output (check serializers, DTOs, or response builders).
 - Validate enum values match database constraints or application constants.
 - Check for nullable fields — mark explicitly with `nullable: true` or type union.
@@ -55,9 +56,15 @@ Task Progress:
 
 - Cross-reference the generated spec against integration tests to confirm endpoint behavior.
 - Verify content types (`application/json`, `multipart/form-data`, etc.) match actual handlers.
-- Check that path parameters, query parameters, and headers are correctly documented.
+- Check that path parameters, query parameters, and headers are documented with accurate types, required flags, and example values.
 - Validate against any existing API consumers (SDKs, frontend clients) for breaking changes.
 
+## Error Handling
+
+- **Route definitions use dynamic or meta-programmed patterns**: If endpoints are generated at runtime or via decorators that resist static analysis, document the gap and manually enumerate the missing endpoints.
+- **OpenAPI linter fails on generated output**: Fix the specific schema violations reported by the linter. Do not suppress linter rules without documenting the reason.
+- **Breaking changes detected against existing consumers**: Flag each breaking change with the affected consumer, the migration path, and whether a versioned endpoint is needed.
+
 ## Definition of Done
 
 - [ ] OpenAPI spec covers all endpoints in the codebase

package/skills/hatch3r-architecture-review/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-architecture-review
 description: Evaluate architectural decisions and produce ADRs following the project template. Use when making architectural decisions, evaluating trade-offs, or creating ADRs.
 tags: [review]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Architecture Review Workflow
 
@@ -89,6 +90,12 @@ Save as `docs/adr/XXXX_short-title.md` (or project convention). Use next availab
 - Link from related issues/work items or PRs/MRs on the platform.
 - If superseding an ADR, update the old ADR's Status to `SUPERSEDED by ADR-XXXX`.
 
+## Error Handling
+
+- **Conflicting ADRs discovered**: If an existing ADR contradicts the proposed decision, reference both ADRs and recommend superseding the older one with explicit justification.
+- **Insufficient context for trade-off evaluation**: If the codebase lacks enough information to evaluate an option, state the knowledge gap and recommend a time-boxed spike before finalizing the decision.
+- **Stakeholder disagreement on recommended option**: Document all positions with their rationale and escalate to the project lead with a clear recommendation and dissent summary.
+
 ## Definition of Done
 
 - [ ] ADR written following project template

package/skills/hatch3r-bug-fix/SKILL.md

@@ -2,8 +2,9 @@
 id: hatch3r-bug-fix
 description: Step-by-step bug fix workflow. Diagnose root cause, implement minimal fix, write regression test. Use when fixing bugs, working on bug report issues, or when the user mentions a bug.
 tags: [core, implementation]
+quality_charter: agents/shared/quality-charter.md
 ---
-> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
+> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool when your project uses a different package manager.
 
 # Bug Fix Workflow
 
@@ -33,16 +34,18 @@ Task Progress:
 
 Before fixing, output:
 
-- **Root cause hypothesis:** what is wrong and why
-- **Files to investigate:** list of files
-- **Reproduction strategy:** how to confirm the bug via tests
-- **Risks:** what could go wrong with the fix
+- **Root cause hypothesis:** what is wrong and why (distinguish between the symptom the user reported and the underlying cause)
+- **Files to investigate:** list of files with reason each file is relevant
+- **Reproduction strategy:** how to confirm the bug via tests (specific test scenario, expected vs. actual result)
+- **Error handling check:** does the affected code have proper error handling? If the bug is caused by a missing or incorrect error path, note this explicitly
+- **Risks:** what could go wrong with the fix (regression risk, related code paths that could be affected)
+- **Confidence:** high/medium/low for the hypothesis. If low, describe what additional investigation is needed before proceeding
 
 ## Step 2b: Browser Reproduction (if UI Bug)
 
 Skip this step if the bug has no visual or interactive symptoms.
 
-- Ensure the dev server is running. If not, start it in the background.
+- Confirm the dev server is running by checking the expected port. If not running, start it in the background.
 - Navigate to the page where the bug manifests.
 - Follow the reproduction steps from the issue to confirm the bug is observable.
 - Take a screenshot of the broken state as baseline evidence.
@@ -78,7 +81,7 @@ Skip TDD and use the standard flow (Steps 3→4) when:
 
 - Write a test that **fails before** the fix and **passes after**.
 - Add edge case tests if the bug reveals coverage gaps.
-- Ensure all existing tests still pass.
+- Run the full test suite and confirm 0 failures — all existing tests still pass.
 
 ## Step 5: Verify
 
@@ -119,6 +122,12 @@ You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`
 
 - **Skill**: `hatch3r-qa-validation` — use this skill for end-to-end verification of the bug fix
 
+## Error Handling
+
+- **Root cause cannot be identified**: If tracing reaches a dead end, document the investigation path taken, the hypotheses eliminated, and recommend additional instrumentation (debug logging, reproduction steps) to narrow down the cause.
+- **Fix introduces test failures elsewhere**: Analyze whether the failing tests relied on the buggy behavior. Update those tests if they were testing incorrect expectations; otherwise, rethink the fix approach.
+- **Bug is in a third-party dependency**: If the root cause is in external code, implement a workaround with a code comment linking to the upstream issue, and file or reference the upstream bug report.
+
 ## Definition of Done
 
 - [ ] Root cause identified and documented in PR

package/skills/hatch3r-ci-pipeline/SKILL.md

@@ -3,6 +3,7 @@ id: hatch3r-ci-pipeline
 type: skill
 description: Design and optimize CI/CD pipelines. Covers stage design, test parallelization, artifact management, and pipeline performance.
 tags: [devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 # CI Pipeline Workflow
@@ -53,7 +54,7 @@ Task Progress:
 ## Step 5: Implement and Validate
 
 - Implement pipeline changes incrementally — test each stage change in a feature branch.
-- Verify caching works correctly: first run populates cache, second run uses it.
+- Verify caching works: first run populates cache, second run uses it (confirmed by cache hit log output).
 - Confirm parallel stages don't have hidden dependencies causing race conditions.
 - Measure pipeline duration improvement against the baseline from Step 1.
 - Document the pipeline architecture for the team.
@@ -68,6 +69,12 @@ Task Progress:
 | Full pipeline (push to artifact) | < 15 minutes |
 | Cache hit ratio | > 80% |
 
+## Error Handling
+
+- **Pipeline config syntax errors**: Validate workflow YAML locally (e.g., `actionlint` for GitHub Actions) before pushing. Report the exact line and field causing the parse failure.
+- **Flaky tests block pipeline**: Identify the flaky test(s) by re-running the failing job. If confirmed flaky, quarantine the test with a tracking issue reference and unblock the pipeline.
+- **Cache invalidation causes slow builds**: Verify cache key patterns match the lockfile hash. If caches are stale, clear them and document the corrected key strategy.
+
 ## Definition of Done
 
 - [ ] Pipeline stages optimized with maximum parallelism

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

@@ -1,68 +1,11 @@
 ---
 id: hatch3r-command-customize
-description: Create and manage per-command customization files for description overrides, enable/disable control, and project-specific markdown instructions. Use when tailoring command behavior to project-specific needs.
+description: Command customization — redirects to the unified hatch3r-customize skill.
 tags: [customize]
+quality_charter: agents/shared/quality-charter.md
 ---
-# Command Customization Management
+# Command Customization
 
-## Quick Start
+> **This skill has been consolidated.** Use the `hatch3r-customize` skill with `type: command`.
 
-```
-Task Progress:
-- [ ] Step 1: Identify which command to customize
-- [ ] Step 2: Determine customization needs
-- [ ] Step 3: Create the customization files
-- [ ] Step 4: Sync to propagate changes
-- [ ] Step 5: Verify the customized output
-```
-
-## Step 1: Identify Command
-
-Determine which hatch3r command needs customization:
-- Review the commands in `.agents/commands/` and their default behavior
-- Identify gaps between default behavior and project needs
-- Check for existing customization files in `.hatch3r/commands/`
-
-## Step 2: Determine Customization Needs
-
-Decide which customization approach to use:
-
-**YAML (`.customize.yaml`)** — for structured overrides:
-- **Description**: Change how the command is described in adapter outputs
-- **Enabled**: Set to `false` to disable the command entirely
-
-**Markdown (`.customize.md`)** — for free-form instructions:
-- Project-specific workflow steps
-- Additional prerequisites or constraints
-- Custom deployment or release procedures
-
-## Step 3: Create Customization Files
-
-Create files in `.hatch3r/commands/`:
-
-**For YAML overrides:**
-```yaml
-# .hatch3r/commands/{command-id}.customize.yaml
-description: "Release workflow with staging validation"
-```
-
-**For markdown instructions:**
-Create `.hatch3r/commands/{command-id}.customize.md` with project-specific additions. This content is injected into the managed block under `## Project Customizations`.
-
-## Step 4: Sync
-
-Run `npx hatch3r sync` to propagate customizations to all adapter outputs.
-
-## Step 5: Verify
-
-Confirm customizations appear in adapter output files:
-- Check description in adapter outputs (where applicable)
-- Check markdown instructions appear inside the managed block
-- Verify disabled commands are absent from adapter outputs
-
-## Definition of Done
-
-- [ ] Customization files created in `.hatch3r/commands/`
-- [ ] `npx hatch3r sync` completes without errors
-- [ ] Adapter output files reflect the customizations
-- [ ] Customization files committed to the repository
+For command-specific reference (YAML schema, examples), see the `hatch3r-command-customize` command.