hatch3r 1.4.0 → 1.5.0

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

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

@@ -2,6 +2,7 @@
 id: hatch3r-rule-customize
 description: Rule customization — redirects to the unified hatch3r-customize skill.
 tags: [customize]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Rule Customization
 

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

@@ -2,6 +2,7 @@
 id: hatch3r-skill-customize
 description: Skill customization — redirects to the unified hatch3r-customize skill.
 tags: [customize]
+quality_charter: agents/shared/quality-charter.md
 ---
 # Skill Customization
 

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

@@ -2,8 +2,9 @@
 id: hatch3r-visual-refactor
 description: UI/UX change workflow matching design, accessibility, and responsiveness requirements. Use when making visual changes, updating components, working on UI issues, or implementing design mockups.
 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.
 
 # Visual Refactor Workflow
 
@@ -40,9 +41,9 @@ Before modifying code, output:
 
 - Match the mockup/screenshot exactly. Do not improvise design.
 - Use existing design system tokens and components.
-- Ensure animations respect `prefers-reduced-motion`.
-- Ensure color contrast meets WCAG AA (4.5:1 for text).
-- Ensure interactive elements are keyboard accessible with focus indicators.
+- Verify animations respect `prefers-reduced-motion` by enabling the media query in DevTools and confirming animations are disabled or simplified.
+- Verify color contrast meets WCAG AA (4.5:1 for text) using a contrast checker tool.
+- Verify interactive elements are keyboard accessible by tabbing through them and confirming visible focus indicators.
 - Add ARIA attributes for screen reader support.
 
 ## Step 4: Verify
@@ -58,7 +59,7 @@ npm run lint && npm run typecheck && npm run test
 
 ### 4b. Browser Verification
 
-- 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 every surface affected by the visual change.
 - Compare the rendered result against the mockup or design from the issue.
 - Test at multiple viewport sizes if the change affects responsive behavior.
@@ -77,6 +78,12 @@ Use the project's PR template. Include:
 - Accessibility verification evidence
 - Responsive behavior across sizes
 
+## Error Handling
+
+- **No design mockup or reference provided**: Ask the user for a design reference before implementing. If none is available, propose the design based on existing design system tokens and get approval before proceeding.
+- **Snapshot tests fail after visual changes**: Update the snapshots only after visually verifying the new rendering is correct. Do not blindly update snapshots without visual confirmation.
+- **Component renders differently across browsers**: Test in at least two browser engines. Document browser-specific rendering differences and fix those that affect usability or accessibility.
+
 ## Definition of Done
 
 - [ ] UI matches mockup/design in the issue