hatch3r 1.3.0 → 1.5.0

package/skills/hatch3r-context-health/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-context-health
 description: Monitor and maintain conversation context health during long sessions. Use when context may be degrading, after many turns, or when experiencing repeated errors.
 tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Context Health Monitoring
 
@@ -64,14 +65,34 @@ After corrective action:
 - Confirm health is at Green or Yellow
 - Resume work on the original task
 
+## Context Poisoning Detection
+
+During context health checks, also scan for signs of context poisoning -- stale or incorrect information that has accumulated in the conversation:
+
+| Signal | Detection | Action |
+|--------|-----------|--------|
+| Outdated file content | You reference a file's content but the file has been modified since you last read it | Re-read the file before continuing |
+| Stale assumptions | A decision was made based on information that has since changed (e.g., a function was refactored) | Re-verify assumptions against current state |
+| Contradictory context | Two pieces of context in the conversation disagree (e.g., "the API uses REST" vs. code showing GraphQL) | Resolve by reading the actual source of truth |
+| Accumulated errors | Multiple tool calls have failed, suggesting the mental model of the codebase is wrong | Reset context by re-reading key files from scratch |
+
+Context poisoning is more dangerous than missing context because it leads to confident-but-wrong decisions.
+
+## Error Handling
+
+- **Context degradation detected mid-task**: If health drops to Orange or Red during implementation, stop the current task, summarize progress so far, and recommend delegating the remainder to a fresh sub-agent with the summary as input.
+- **Health checks produce conflicting signals**: If some checks indicate Green while others indicate Red, trust the worst signal and investigate the specific check that failed before proceeding.
+- **Unable to estimate token usage**: If the platform does not expose token counts, use character-based estimation (1 token per 4 characters) and note the approximation in the report.
+
 ## Definition of Done
 
 - [ ] Context health assessed with all 5 checks
+- [ ] Context poisoning scan completed (no stale assumptions)
 - [ ] Degradation level determined (Green/Yellow/Orange/Red)
 - [ ] Appropriate corrective action taken
 - [ ] Health verified at Green or Yellow after correction
 
 ## Related Skills & Agents
 
-- **Command**: `hatch3r-context-health` — full monitoring protocol with integration points
-- **Command**: `hatch3r-board-pickup` — auto-advance mode uses context health for session management
+- **Command**: `hatch3r-context-health` -- full monitoring protocol with integration points
+- **Command**: `hatch3r-board-pickup` -- auto-advance mode uses context health for session management

package/skills/hatch3r-cost-tracking/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-cost-tracking
 description: Track token usage and estimate costs for agent sessions. Use when monitoring spend, approaching budget limits, or generating cost reports.
 tags: [maintenance]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Cost Tracking Workflow
 
@@ -26,12 +27,15 @@ Task Progress:
 
 Estimate tokens for the current session using these rules:
 
-| Content Type | Rule |
-|-------------|------|
-| Messages | ~4 characters per token |
-| Tool calls | JSON length / 4 (input), response length / 4 (output) |
-| File reads | Character count / 4 |
-| Web searches | ~500 tokens per search |
+| Content Type | Rule | Accuracy |
+|-------------|------|----------|
+| Messages | ~4 characters per token | High -- stable ratio for English text |
+| Tool calls | JSON length / 4 (input), response length / 4 (output) | Medium -- JSON has more overhead characters |
+| File reads | Character count / 4 | High -- but large files may be truncated by the tool |
+| Web searches | ~500 tokens per search | Low -- varies widely by result length |
+| Subagent spawns | Estimate full context re-sent per spawn (~2000-5000 tokens base) | Medium -- depends on included rules/context |
+
+**Subagent cost multiplier.** Each subagent spawn carries a base cost for the agent protocol, included rules, and context. A pipeline with 8 subagents (researcher + implementer + reviewer + fixer + 4 Phase 4 specialists) has significant overhead from context re-transmission. Factor this into budget estimates.
 
 Calculate estimated cost using the model tier rates from the `hatch3r-cost-tracking` command reference.
 
@@ -53,6 +57,12 @@ Produce a cost report using the output format from the `hatch3r-cost-tracking` c
 - Budget status (if configured)
 - Top optimization opportunities
 
+## Error Handling
+
+- **Token usage data unavailable**: If the platform does not expose token metrics, use input/output character counts divided by 4 as an estimate. Note the approximation method in the report.
+- **Budget limit exceeded mid-session**: Stop non-critical operations, produce a partial cost report, and recommend which remaining tasks to defer or delegate to a lower-cost model.
+- **Cost configuration missing from hatch.json**: Operate in report-only mode and note that budget enforcement is inactive. Recommend adding cost configuration to enable guardrails.
+
 ## Definition of Done
 
 - [ ] Cost configuration reviewed (or report-only mode noted)

package/skills/hatch3r-customize/SKILL.md

@@ -0,0 +1,124 @@
+---
+id: hatch3r-customize
+description: Create and manage customization files for any hatch3r artifact type (agents, commands, rules, skills). Supports model overrides, description changes, scope overrides, enable/disable control, and project-specific markdown instructions.
+tags: [customize]
+quality_charter: agents/shared/quality-charter.md
+---
+# Artifact Customization Management
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Identify what to customize (and why)
+- [ ] Step 2: Determine customization needs
+- [ ] Step 3: Multi-stakeholder review
+- [ ] Step 4: Create the customization files
+- [ ] Step 5: Sync to propagate changes
+- [ ] Step 6: Verify the customized output
+```
+
+## Artifact Types
+
+This skill handles customization for all artifact types. The `type` parameter determines file locations, available YAML fields, and verification steps.
+
+| Type | Source Directory | Customization Directory | YAML Fields |
+|------|-----------------|------------------------|-------------|
+| `agent` | `.agents/agents/` | `.hatch3r/agents/` | `model`, `description`, `enabled` |
+| `command` | `.agents/commands/` | `.hatch3r/commands/` | `description`, `enabled` |
+| `rule` | `.agents/rules/` | `.hatch3r/rules/` | `scope`, `description`, `enabled` |
+| `skill` | `.agents/skills/` | `.hatch3r/skills/` | `description`, `enabled` |
+
+**Protected agents:** Some agents have `protected: true` in their canonical frontmatter. For these agents, `description` and `enabled` overrides are ignored — only `model` and markdown instructions can be customized.
+
+## Step 1: Identify and Root-Cause
+
+Determine which artifact needs customization and **why**:
+
+1. Review the artifacts in the appropriate source directory and their default behaviors.
+2. Identify gaps between default behavior and project needs.
+3. Check for existing customization files in the appropriate `.hatch3r/{type}s/` directory.
+4. **Root-cause analysis:** Before proceeding, consider:
+   - Is this a genuine project-specific need, or a workaround for a bug in the default content?
+   - Would this customization be better addressed upstream (by modifying the canonical artifact)?
+   - Could a rule or learning achieve the same effect with less coupling?
+
+   If the customization is working around a default content issue, note it as a candidate for upstream contribution before proceeding.
+
+## Step 2: Determine Customization Needs
+
+Decide which customization approach to use:
+
+**YAML (`.customize.yaml`)** — for structured overrides:
+
+| Field | Available For | Description |
+|-------|--------------|-------------|
+| `model` | agent only | Override the agent's preferred model |
+| `scope` | rule only | Override when the rule applies (`always` or glob patterns) |
+| `description` | all types | Change how the artifact is described in adapter outputs |
+| `enabled` | all types | Set to `false` to exclude from adapter output generation |
+
+**Markdown (`.customize.md`)** — for free-form instructions:
+- Domain-specific checklists, constraints, or workflow additions
+- Architecture context relevant to the artifact's function
+- Project-specific requirements (compliance, testing, deployment)
+
+Set only the fields/content you need — partial customization is valid.
+
+## Step 3: Multi-Stakeholder Review
+
+Before creating customization files, consider the impact from multiple perspectives:
+
+1. **Developer experience:** Does this customization make the developer's workflow better or worse? Will it cause confusion for new team members?
+2. **Quality impact:** Does disabling or weakening an artifact (especially agents or rules) reduce quality safeguards? What compensating controls exist?
+3. **Maintenance burden:** Will this customization need updating when the upstream canonical artifact changes? Is the coupling acceptable?
+4. **Consistency:** Does this customization create inconsistency with other artifacts or team conventions?
+
+**Confidence expression:** State your confidence in the customization decision:
+- **High confidence:** Clear project-specific need with no quality trade-offs.
+- **Medium confidence:** Reasonable need but with trade-offs worth noting.
+- **Low confidence:** Workaround or uncertain benefit — recommend revisiting after more experience.
+
+## Step 4: Create Customization Files
+
+Create files in `.hatch3r/{type}s/`:
+
+**For YAML overrides:** Create `.hatch3r/{type}s/{artifact-id}.customize.yaml` with the applicable fields from the Step 2 table.
+
+**For markdown instructions:** Create `.hatch3r/{type}s/{artifact-id}.customize.md` with project-specific content. This is injected into the managed block under `## Project Customizations`.
+
+## Step 5: Sync
+
+Run `npx hatch3r sync` to propagate customizations to all adapter outputs. The sync reads `.customize.yaml` for structured overrides, reads `.customize.md` and appends it inside the managed block, and generates updated output for every configured adapter.
+
+## Step 6: Verify
+
+Confirm customizations appear in adapter output files:
+- Check YAML fields are reflected in adapter-specific frontmatter
+- Check markdown instructions appear inside the managed block
+- Verify disabled artifacts are absent from adapter outputs
+- **For rules:** verify scope field in adapter-specific frontmatter matches the configured scope value
+
+### Quality Gate
+
+Verification is not just "sync completes." Confirm:
+- [ ] The adapter output for the customized artifact contains the expected changes
+- [ ] No unrelated artifacts were affected by the sync
+- [ ] If an artifact was disabled, verify no command or skill references it as a required dependency
+- [ ] If a rule scope was narrowed, verify the excluded file patterns do not lose important coverage
+
+## Error Handling
+
+- **`hatch3r sync` fails after customization**: Check the customization YAML for syntax errors (missing quotes, incorrect indentation). Validate the file against the schema documented in the corresponding customize command.
+- **Customization has no visible effect in adapter output**: Verify the customization file is in the correct directory (`.hatch3r/{type}s/`) and that the `id` field matches the target artifact's `id` exactly.
+- **Disabling an artifact breaks a command dependency**: Re-enable the artifact, then check which commands reference it. Either update the command to remove the dependency or keep the artifact enabled.
+
+## Definition of Done
+
+- [ ] Root-cause considered (Step 1) — not working around an upstream issue
+- [ ] Multi-stakeholder impact reviewed (Step 3)
+- [ ] Customization files created in `.hatch3r/{type}s/`
+- [ ] `npx hatch3r sync` completes without errors
+- [ ] Adapter output files reflect the customizations
+- [ ] Quality gate checks pass (Step 6)
+- [ ] Customization files committed to the repository

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

@@ -2,8 +2,9 @@
 id: hatch3r-dep-audit
 description: Audit and update npm dependencies for security, freshness, and bundle impact. Use when auditing dependencies, responding to CVEs, or upgrading packages.
 tags: [maintenance, security]
+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.
 
 # Dependency Audit Workflow
 
@@ -64,7 +65,7 @@ npm run build
 
 - Confirm bundle size within budget (if defined).
 - Run `npm audit` — no critical or high vulnerabilities remaining.
-- Ensure `package-lock.json` is committed.
+- Verify `package-lock.json` is committed by checking `git status` for untracked or modified lockfile.
 
 ## Step 6: Open PR
 
@@ -76,6 +77,12 @@ Use the project's PR template. Include:
 - **Test evidence:** all tests pass, no regressions.
 - **Rollback plan:** if risky (e.g., major version bump).
 
+## Error Handling
+
+- **`npm audit` reports vulnerabilities with no fix available**: Document the vulnerability, assess exploitability in the project context, and create a tracking issue. If the risk is high, evaluate alternative packages.
+- **Major version upgrade breaks tests**: Roll back the upgrade, document the breaking changes encountered, and create a dedicated migration issue with the specific test failures and required code changes.
+- **Lockfile conflicts after upgrade**: Regenerate the lockfile from scratch (`rm package-lock.json && npm install`), verify all tests pass, and commit the clean lockfile.
+
 ## Definition of Done
 
 - [ ] No critical or high CVEs remaining

package/skills/hatch3r-feature/SKILL.md

@@ -2,8 +2,9 @@
 id: hatch3r-feature
 description: End-to-end feature implementation workflow. Covers data model, domain logic, API, and UI as a vertical slice. Use when implementing new features or working on feature request issues.
 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.
 
 # Feature Implementation Workflow
 
@@ -66,11 +67,12 @@ Use standard flow (implement → test) when:
 ## Step 3: Implement
 
 - Deliver a complete vertical slice (data -> logic -> UI).
-- Follow the convention lock from Step 1 / the implementer's Step 1b — match the reference implementation's patterns for file structure, state management, error handling, data fetching, and testing. Do not invent new patterns when established ones exist in the codebase.
+- Follow the convention lock from Step 1 / the implementer's Step 1b -- match the reference implementation's patterns for file structure, state management, error handling, data fetching, and testing. Do not invent new patterns when established ones exist in the codebase.
 - Use stable IDs from the project glossary.
 - If database/backend data is needed, include security rules updates.
 - If feature is gated, enforce entitlements client-side AND server-side.
 - If new events, follow the project's event schema.
+- **Error handling for new code paths.** Every new function that can fail must use the project's error handling patterns (Result types for expected failures, custom error classes for domain errors, error boundaries at architectural boundaries). Do not defer error handling to "a future PR" -- incomplete error handling is a Critical review finding.
 
 ## Step 4: Tests
 
@@ -90,9 +92,9 @@ npm run lint && npm run typecheck && npm run test
 
 Skip this step if the feature has no user-facing UI changes.
 
-- 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 or surface affected by the new feature.
-- Walk through the acceptance criteria visually — confirm the feature renders and behaves correctly.
+- Walk through the acceptance criteria visually — confirm the feature renders and behaves as specified in the issue.
 - Interact with new UI elements: click, type, trigger state transitions.
 - Check the browser console for errors or warnings.
 - If the feature is responsive, test at different viewport sizes.
@@ -122,6 +124,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 implemented feature
 
+## Error Handling
+
+- **Acceptance criteria are ambiguous or incomplete**: Stop implementation, document the specific ambiguities, and ask the user for clarification before proceeding. Do not guess at requirements.
+- **Feature touches a module with no existing tests**: Write foundational tests for the existing behavior first, then implement the feature. This prevents regressions in untested code.
+- **Database migration fails or is irreversible**: Test the migration against a local database or emulator before applying. If rollback is needed, verify the down-migration restores the original schema.
+
 ## Definition of Done
 
 - [ ] All acceptance criteria met

package/skills/hatch3r-gh-agentic-workflows/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-gh-agentic-workflows
 description: Set up CI/CD agentic workflows for continuous AI-powered repository automation (GitHub Actions, Azure Pipelines, GitLab CI)
 tags: [devops, team]
+quality_charter: agents/shared/quality-charter.md
 ---
 # CI/CD Agentic Workflows Integration
 
@@ -220,6 +221,12 @@ Trigger on merge to the default branch. Check if documentation needs updating an
 - **Cost awareness**: Monitor AI token usage per workflow run. Set spending limits in org settings.
 - **Quality metrics**: Track: success rate, output acceptance rate (merged PRs/MRs / total), mean time per run.
 
+## Error Handling
+
+- **Workflow file has YAML syntax errors**: Validate the workflow file locally before pushing (e.g., `actionlint` for GitHub Actions, Azure Pipelines schema validation, or `glab ci lint` for GitLab). Fix all reported errors before committing.
+- **AI engine produces low-quality or empty output**: Add explicit context to the workflow prompt (file references, examples, constraints). If the output is still poor after enrichment, switch to a more capable model.
+- **Workflow runs exceed cost or time limits**: Add `timeout-minutes` to the workflow, scope file references to reduce context size, and add concurrency groups to prevent parallel runs.
+
 ## Troubleshooting
 
 | Symptom | Likely Cause | Fix |

package/skills/hatch3r-incident-response/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-incident-response
 description: Handle production incidents with structured triage, mitigation, and post-mortem. Use when responding to production issues, outages, or security incidents.
 tags: [devops]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Incident Response Workflow
 
@@ -77,6 +78,12 @@ Store in project incident docs or as an issue/wiki page on the platform. Follow
 - Link issues/work items to the post-mortem and to each other.
 - Assign owners and due dates for critical fixes.
 
+## Error Handling
+
+- **Cannot reproduce the incident locally**: Use production logs and traces to build the timeline. If local reproduction is blocked by environment differences, document the gap and recommend a staging environment test.
+- **Mitigation introduces new issues**: Roll back the mitigation immediately, reassess the approach, and apply a more targeted fix. Document both the original incident and the mitigation regression in the post-mortem.
+- **Root cause spans multiple services or teams**: Document the cross-service dependency chain, assign follow-up items to the responsible teams, and coordinate a joint post-mortem.
+
 ## Definition of Done
 
 - [ ] Incident mitigated and verified

package/skills/hatch3r-issue-workflow/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-issue-workflow
 description: Guides the 8-step agentic development workflow for issues/work items. Covers parsing issues, loading skills, reading specs, planning, implementing, testing, opening PRs/MRs, and addressing review. Use when working on any issue/work item or when the user mentions an issue number.
 tags: [core, implementation]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Issue Workflow
 
@@ -108,7 +109,7 @@ The implementer sub-agent protocol is defined in the hatch3r-implementer agent.
 
 Skip this step if the issue has no user-facing UI changes.
 
-- 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 or surface affected by the change.
 - Visually confirm the implementation matches acceptance criteria from the issue.
 - Interact with changed elements to verify functional correctness.
@@ -132,6 +133,12 @@ Skip this step if the issue has no user-facing UI changes.
 - Push fixes as new commits (don't force-push during review).
 - Re-request review after addressing all comments.
 
+## Error Handling
+
+- **Issue description is too vague to implement**: Do not guess. Ask the user for clarification on acceptance criteria, scope boundaries, and expected behavior before starting Step 3 (planning).
+- **Tests fail after implementation and the cause is unclear**: Run tests in isolation to identify whether the failure is in new code or existing code. If existing tests broke, check whether they relied on behavior that was intentionally changed.
+- **PR/MR creation fails due to branch conflicts**: Rebase onto the target branch, resolve conflicts, re-run all tests, and verify the merge result before re-creating the PR/MR.
+
 ## Escalation
 
 Stop and ask when:

package/skills/hatch3r-logical-refactor/SKILL.md

@@ -2,8 +2,9 @@
 id: hatch3r-logical-refactor
 description: Workflow for changing behavior or logic flow without adding new features or overhauling UI. Use when modifying business logic, data flows, behavioral rules, or working on logical refactor issues.
 tags: [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.
 
 # Logical Refactor Workflow
 
@@ -63,6 +64,12 @@ Use the project's PR template. Include:
 - Test evidence for both new behavior and preserved behavior
 - Spec docs updated (if any)
 
+## Error Handling
+
+- **Behavioral invariant violated during refactor**: If a test that should pass now fails, check whether the invariant was incorrectly preserved or whether the refactor inadvertently changed behavior. Fix the refactor, not the test, unless the test was wrong.
+- **Refactor scope grows beyond the original task**: If additional modules need changes to complete the refactor, stop, document the expanded scope, and get confirmation before continuing.
+- **Cannot verify behavioral equivalence due to missing tests**: Write characterization tests for the current behavior before applying the refactor. This provides a safety net for the transformation.
+
 ## Definition of Done
 
 - [ ] New behavior matches the "after" description

package/skills/hatch3r-migration/SKILL.md

@@ -3,6 +3,7 @@ id: hatch3r-migration
 type: skill
 description: Plan and execute migrations for databases, frameworks, and dependencies. Covers breaking change analysis, phased rollout, and rollback procedures.
 tags: [implementation, brownfield]
+quality_charter: agents/shared/quality-charter.md
 ---
 
 # Migration Workflow
@@ -67,6 +68,12 @@ Task Progress:
 - Delete unused migration scripts after they've been applied to all environments.
 - Write a migration retrospective noting what went well and any issues encountered.
 
+## Error Handling
+
+- **Migration phase fails partway through**: Roll back to the last successful phase checkpoint. Diagnose the failure before retrying. Each phase must leave the codebase in a working state.
+- **Rollback procedure does not restore original behavior**: Treat this as a critical gap. Fix the rollback procedure before proceeding with the migration, since an untested rollback path is a deployment risk.
+- **Dependency version conflict during migration**: Pin the conflicting dependency to the version compatible with the migration target. Document the pin and plan its removal after all consumers are updated.
+
 ## Definition of Done
 
 - [ ] All phases completed and verified

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

@@ -2,8 +2,9 @@
 id: hatch3r-perf-audit
 description: Profile and optimize application performance against defined budgets. Use when investigating performance issues, auditing performance budgets, or optimizing hot paths.
 tags: [review, performance]
+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.
 
 # Performance Audit Workflow
 
@@ -74,7 +75,7 @@ Common strategies:
 - **Database:** Reduce reads (batch, cache, denormalize).
 - **Cloud/API:** Warm-up strategies, reduce cold starts.
 
-- Check project ADRs for constraints. Ensure optimizations don't violate privacy/security invariants.
+- Check project ADRs for constraints. Verify optimizations do not violate privacy/security invariants documented in the ADRs.
 - For external library docs and current best practices, follow the project's tooling hierarchy.
 
 ## Step 5: Implement Optimizations
@@ -106,6 +107,12 @@ You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`
 
 - **Rule**: `hatch3r-performance-budgets` — reference this rule for the project's defined performance budget thresholds
 
+## Error Handling
+
+- **No performance budgets defined for the project**: Use the defaults from `hatch3r-performance-budgets` rule as a baseline. Note in the report that custom budgets should be defined.
+- **Profiling tool unavailable or incompatible**: Fall back to manual timing measurements (e.g., `performance.now()` or `console.time`) for critical paths. Document the measurement method used.
+- **Optimization introduces functional regressions**: Revert the optimization, add a regression test for the broken behavior, then re-attempt with a different approach.
+
 ## Definition of Done
 
 - [ ] All performance budgets met

package/skills/hatch3r-pr-creation/SKILL.md

@@ -2,8 +2,9 @@
 id: hatch3r-pr-creation
 description: Create a pull request or merge request following project conventions including branch naming, PR/MR template, checklist, and rollout plan. Use when opening or preparing a PR/MR, or when the user asks to create a PR or MR.
 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.
 
 # PR / MR Creation Workflow
 
@@ -85,6 +86,12 @@ You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`
 
 - **Skill**: `hatch3r-issue-workflow` — use this skill for the parent issue-to-PR workflow that feeds into PR creation
 
+## Error Handling
+
+- **PR/MR creation fails due to missing remote branch**: Push the local branch to the remote first (`git push -u origin {branch}`), then retry the PR/MR creation.
+- **CI checks fail on the PR/MR**: Diagnose the failure locally, push fixes as new commits (do not force-push during review), and verify CI passes before requesting review.
+- **Merge conflicts with the target branch**: Rebase onto the target branch, resolve conflicts, re-run all tests, and force-push the rebased branch only if no reviews have been submitted yet.
+
 ## Size Guidelines
 
 | Files Changed | Recommendation                       |

package/skills/hatch3r-qa-validation/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-qa-validation
 description: E2E validation workflow producing a structured pass/fail report with evidence. Use when running QA validation, acceptance testing, verifying releases, or working on QA E2E validation issues.
 tags: [core, review]
+quality_charter: agents/shared/quality-charter.md
 ---
 # QA E2E Validation Workflow
 
@@ -46,7 +47,7 @@ Run the project's automated test suites (unit, integration, E2E) and record resu
 
 For each user-facing test case in the matrix:
 
-1. Ensure the dev server is running. If not, start it in the background.
+1. Confirm the dev server is running by checking the expected port. If not running, start it in the background.
 2. Navigate to the page or surface under test using browser automation MCP.
 3. Execute the test steps exactly as described — click, type, navigate, trigger state changes.
 4. Observe the actual result and compare to the expected result.
@@ -76,6 +77,12 @@ Produce a structured report with:
 - If validation fails, state what must be fixed before re-validation.
 - Post report as comment on the issue/work item or linked PR/MR (check `platform` in `.agents/hatch.json`).
 
+## Error Handling
+
+- **Test environment unavailable or misconfigured**: Document which tests could not be executed, note the environment gap, and recommend a fix. Do not mark untested scenarios as passing.
+- **Validation discovers a blocking defect**: File an issue immediately, mark the validation as HOLD, and include the defect details in the validation report with reproduction steps.
+- **Flaky test results (pass on retry)**: Run the test 3 times. If it passes inconsistently, mark it as flaky in the report, file a tracking issue, and exclude it from the pass/fail determination.
+
 ## Definition of Done
 
 - [ ] All test cases in the matrix executed

package/skills/hatch3r-recipe/SKILL.md

@@ -2,6 +2,7 @@
 id: hatch3r-recipe
 description: Create, test, and manage workflow recipes that compose hatch3r capabilities into guided sequences. Use when creating new recipes, customizing existing ones, or troubleshooting recipe execution.
 tags: [core]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Recipe Management
 
@@ -47,7 +48,7 @@ Execute `--dry-run` to validate:
 - YAML schema is valid
 - All referenced commands/skills exist
 - Dependency graph has no cycles
-- Variables are properly referenced
+- Variables are referenced with valid names that resolve to defined values
 - Prerequisites are checkable
 
 ## Step 5: Validate with Real Execution
@@ -59,6 +60,12 @@ Run the recipe on a test project to verify:
 - Error handling works (intentionally fail a step)
 - Completion message is accurate
 
+## Error Handling
+
+- **Recipe step fails during execution**: The recipe runner should report which step failed, its inputs, and the error message. Provide a `resume-from` option to restart from the failed step after fixing the issue.
+- **Recipe YAML has schema validation errors**: Report the specific field and line that violates the schema. Do not attempt to execute a recipe that fails validation.
+- **Circular dependency between recipe steps**: Detect cycles during the dry-run phase and report the dependency chain that creates the loop.
+
 ## Definition of Done
 
 - [ ] Recipe YAML validates against schema

package/skills/hatch3r-refactor/SKILL.md

@@ -2,8 +2,9 @@
 id: hatch3r-refactor
 description: Internal code quality improvement workflow without changing external behavior. Use when refactoring code structure, simplifying modules, or improving maintainability.
 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.
 
 # Code Refactor Workflow
 
@@ -46,7 +47,8 @@ Before changing code, output:
 - Preserve all public interfaces and external behavior.
 - Remove dead code created by the refactor.
 - Do not introduce new dependencies.
-- If a bug is found, document it — fix in a separate PR.
+- If a bug is found, document it -- fix in a separate PR.
+- **Error handling preservation.** When moving or restructuring error handling code, verify that the error behavior is preserved. A common refactoring mistake is accidentally changing error types, removing error context, or altering error propagation paths. Run error-path tests after each structural change.
 
 ## Step 4: Verify
 
@@ -81,6 +83,12 @@ You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`
 - **Skill**: `hatch3r-logical-refactor` — use when the refactor changes internal logic flow while preserving external behavior
 - **Skill**: `hatch3r-visual-refactor` — use when the refactor targets UI/styling changes without altering functionality
 
+## Error Handling
+
+- **Existing tests fail after refactor**: Do not modify tests to make them pass unless the test was verifying an implementation detail (not behavior). If a behavioral test fails, the refactor changed external behavior and must be revised.
+- **Refactor scope expands beyond the original module**: If additional modules need changes due to coupling, stop and assess whether the refactor should be split into phases. Get confirmation before expanding scope.
+- **Type errors after restructuring**: Resolve all type errors before running tests. If the type system reveals unexpected dependencies, document them as findings for the codebase health record.
+
 ## Definition of Done
 
 - [ ] All existing tests pass without modification

package/skills/hatch3r-release/SKILL.md

@@ -2,8 +2,9 @@
 id: hatch3r-release
 description: Cut a release with version bump, changelog, tagging, and deploy verification. Use when preparing a release, cutting a version, or deploying to production.
 tags: [devops]
+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.
 
 # Release Workflow
 
@@ -86,6 +87,12 @@ npm run build
 - Watch user-reported issues for first 24h.
 - If errors spike: rollback and investigate.
 
+## Error Handling
+
+- **Quality gates fail during release preparation**: Do not proceed with the release. Fix the failing gate (test failures, lint errors, type errors), re-run all gates, and restart the release process.
+- **Git tag already exists for the target version**: Check whether the existing tag points to the correct commit. If it was created in error, delete and recreate it. If it was a previous release attempt, bump the version and start over.
+- **Post-deploy monitoring detects regressions**: Execute the rollback plan immediately. Document the regression in a post-mortem issue and block the next release until the regression is fixed.
+
 ## Definition of Done
 
 - [ ] Version bumped in package.json