hatch3r 1.0.0

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

@@ -0,0 +1,114 @@
+---
+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.
+---
+> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
+
+# Performance Audit Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Read performance budgets from rules and specs
+- [ ] Step 2: Profile — bundle size, runtime, memory
+- [ ] Step 3: Identify violations — which budgets exceeded, which hot paths slow
+- [ ] Step 4: Plan optimizations — code splitting, lazy loading, memoization, etc.
+- [ ] Step 5: Implement optimizations with before/after measurements
+- [ ] Step 6: Verify all budgets met, no regressions
+```
+
+## Step 1: Read Performance Budgets
+
+Load the project's performance budgets from project rules and quality documentation:
+
+- Common metrics: render frame rate, cold start to interactive, idle CPU usage, memory footprint, event processing latency, bundle size (initial, gzipped), database reads per session, API warm execution.
+- Note which surface is in scope: frontend, backend, or both.
+- Read project architecture docs for constraints if auditing a specific module.
+
+## Step 2: Profile
+
+**Bundle size:**
+
+- Run `npm run build`. Inspect output for gzipped sizes.
+- Use `vite-bundle-visualizer`, `rollup-plugin-visualizer`, or `webpack-bundle-analyzer` (or build tool equivalent) to identify large chunks and dependencies.
+- Compare bundle sizes if multiple build targets exist.
+
+**Runtime (frontend):**
+
+- Use Chrome DevTools Performance tab: record startup, record key interactions.
+- Measure: Time to Interactive (TTI), First Contentful Paint (FCP), Largest Contentful Paint (LCP).
+- Use **cursor-ide-browser MCP** `browser_profile_start`/`browser_profile_stop` for CPU profiling with call stacks.
+- Check frame rate during animations (target: 60fps, 16ms/frame).
+
+**Memory:**
+
+- Heap snapshot before/after session. Target per project budget.
+- Look for leaks: detached DOM, growing arrays, uncleared timers.
+
+**Backend/API:**
+
+- Check monitoring for cold start and warm execution times.
+- Instrument key paths.
+
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 3: Identify Violations
+
+- List which budgets are exceeded and by how much.
+- Identify hot paths: which functions/components contribute most to latency or bundle size.
+- Prioritize: critical user flows first.
+- Document baseline measurements for comparison.
+
+## Step 4: Plan Optimizations
+
+Common strategies:
+
+- **Code splitting:** Route-based or component-based. Lazy-load panels, modals, non-critical features.
+- **Lazy loading:** `defineAsyncComponent`, dynamic `import()` for heavy components.
+- **Memoization:** `computed`, `memo` for expensive derivations. Avoid unnecessary re-renders.
+- **Reduce re-renders:** `v-show` over `v-if` for frequently toggled. `shallowRef` where appropriate.
+- **Bundle:** Remove unused deps, replace heavy libs with lighter alternatives, tree-shake.
+- **Images/assets:** Optimize, lazy-load, use appropriate formats.
+- **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.
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 5: Implement Optimizations
+
+- Apply changes incrementally. Measure before and after each change.
+- Document before/after for each metric in PR or audit report.
+- Respect `prefers-reduced-motion` — do not add animations that ignore it.
+- Run full test suite after each optimization to avoid functional regressions.
+
+## Step 6: Verify
+
+```bash
+npm run lint && npm run typecheck && npm run test
+npm run build
+```
+
+- All performance budgets met.
+- No functional regressions.
+- Before/after measurements documented.
+- CI performance check passes (if configured).
+
+## Required Agent Delegation
+
+You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:
+
+- **`hatch3r-perf-profiler`** — MUST spawn to perform autonomous performance profiling and optimization. Provide the target areas, budget thresholds, and baseline measurements.
+
+## Related Rules
+
+- **Rule**: `hatch3r-performance-budgets` — reference this rule for the project's defined performance budget thresholds
+
+## Definition of Done
+
+- [ ] All performance budgets met
+- [ ] Before/after measurements documented
+- [ ] No functional regressions
+- [ ] Bundle size within budget (if defined)
+- [ ] Key metrics within project targets

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

@@ -0,0 +1,85 @@
+---
+id: hatch3r-pr-creation
+description: Create a pull request following project conventions including branch naming, PR template, checklist, and rollout plan. Use when opening or preparing a pull request, or when the user asks to create a PR.
+---
+> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
+
+# PR Creation Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Verify branch naming
+- [ ] Step 2: Self-review against checklist
+- [ ] Step 3: Fill PR template
+- [ ] Step 4: Create the PR
+```
+
+## Step 1: Branch Naming
+
+Branches must follow `{type}/{short-description}`:
+
+| Type        | When to Use                        | Example                       |
+| ----------- | ---------------------------------- | ----------------------------- |
+| `feat/`     | New features                       | `feat/add-user-preferences`   |
+| `fix/`      | Bug fixes                          | `fix/login-validation-bug`    |
+| `refactor/` | Code, logical, or visual refactors  | `refactor/simplify-auth-flow`  |
+| `qa/`       | QA validation or test additions    | `qa/e2e-checkout-flow`        |
+| `docs/`     | Documentation changes              | `docs/update-readme`          |
+| `infra/`    | CI/CD, tooling, infrastructure     | `infra/add-lint-ci-step`      |
+
+Rules: lowercase, hyphens (no underscores), 3-5 words max.
+
+## Step 2: Self-Review Checklist
+
+Before creating the PR, verify:
+
+**Scope:** Changes limited to the stated issue. No unrelated changes. No TODOs without linked issues.
+
+**Quality:** Code compiles (`npm run typecheck`). Lint passes (`npm run lint`). All tests pass (`npm run test`). No `any` types. No `@ts-ignore` without linked issue.
+
+**Security & Privacy:** No secrets in code. Database rules updated and tested if data model changed. No sensitive content leaks to cloud. Event metadata uses allowlisted keys. Entitlement gates enforced server-side if gated.
+
+**Accessibility (if UI):** Animations respect `prefers-reduced-motion`. Color contrast meets WCAG AA. Interactive elements keyboard accessible.
+
+## Step 3: Fill PR Template
+
+Use the project's PR template. Fill every section:
+
+- **Summary:** 1-3 sentences on what and why
+- **Type:** Feature / Bug fix / Refactor / QA / Docs / Infra
+- **Related Issues:** `Closes #N` or `Relates to #N`
+- **Changes:** Bullet list of key changes
+- **Screenshots:** Required for UI changes (before/after)
+- **Testing:** Which tests added/updated, manual test steps
+- **Rollout Plan:** Feature flag / gradual / direct
+- **Rollback Plan:** How to revert
+
+## Step 4: Create the PR
+
+PR title format: `{type}: {short description} (#issue)`
+
+Examples:
+
+- `feat: add user preferences panel (#42)`
+- `fix: correct validation for email field (#87)`
+
+## Required Agent Delegation
+
+You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:
+
+- **`hatch3r-reviewer`** — MUST spawn before PR creation for code review. Include the full diff and acceptance criteria in the prompt. Apply reviewer feedback before creating the PR.
+
+## Related Skills
+
+- **Skill**: `hatch3r-issue-workflow` — use this skill for the parent issue-to-PR workflow that feeds into PR creation
+
+## Size Guidelines
+
+| Files Changed | Recommendation                       |
+| ------------- | ------------------------------------ |
+| 1-5           | Ideal. Review and merge quickly.     |
+| 6-15          | Acceptable. Thorough PR description. |
+| 16-30         | Split if possible.                   |
+| 30+           | Must be split.                       |

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

@@ -0,0 +1,86 @@
+---
+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.
+---
+# QA E2E Validation Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Read the issue and relevant specs
+- [ ] Step 2: Produce a validation plan
+- [ ] Step 3: Execute all test cases
+- [ ] Step 4: Produce the validation report
+- [ ] Step 5: File follow-up issues
+```
+
+## Step 1: Read Inputs
+
+- Parse the issue body: validation scope, test matrix, environments, preconditions, pass/fail criteria, evidence requirements.
+- Read project user flows documentation for expected behavior.
+- Read project quality documentation for DoD, testing pyramid, performance budgets.
+- Read project permissions/privacy and security threat model for security test cases.
+- Confirm the correct version is deployed to the test environment.
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 2: Validation Plan
+
+Before executing, output:
+
+- **Scope:** feature/release being validated
+- **Environment:** where tests will run
+- **Version:** build/commit being tested
+- **Preconditions verified:** checklist
+- **Test execution order:** sequence with dependencies
+- **Estimated duration:** time estimate
+
+## Step 3: Execute Tests
+
+### 3a. Automated Test Execution
+
+Run the project's automated test suites (unit, integration, E2E) and record results.
+
+### 3b. Browser-Based Validation
+
+For each user-facing test case in the matrix:
+
+1. Ensure the dev server is running. If not, 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.
+5. Capture a screenshot as evidence for each test case result.
+6. Check the browser console for errors or warnings after each test case.
+7. Mark as **PASS**, **FAIL**, or **BLOCKED** (with reason and screenshot).
+
+For non-UI test cases (API, data integrity, background jobs), use appropriate non-browser verification methods.
+
+Do NOT fix bugs during validation. Document and file issues.
+
+## Step 4: Validation Report
+
+Produce a structured report with:
+
+- **Summary:** total/passed/failed/blocked counts, overall result
+- **Results table:** test case, priority, result, evidence, notes
+- **Regression results:** checks for unaffected flows
+- **Security validation:** invariant checks
+- **Performance validation:** metric vs budget vs actual
+- **Issues found:** severity, description, issue link
+- **Recommendation:** SHIP or HOLD with reasons
+
+## Step 5: Follow-Up
+
+- File new issues for bugs discovered during validation.
+- If validation fails, state what must be fixed before re-validation.
+- Post report as comment on the issue or linked PR.
+
+## Definition of Done
+
+- [ ] All test cases in the matrix executed
+- [ ] Evidence collected for every result
+- [ ] Regression checks completed
+- [ ] Security and performance validation completed
+- [ ] Validation report produced
+- [ ] Issues filed for all failures
+- [ ] Ship/hold recommendation provided

package/skills/hatch3r-recipe/SKILL.md

@@ -0,0 +1,67 @@
+---
+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.
+---
+# Recipe Management
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Identify the workflow to capture as a recipe
+- [ ] Step 2: Design the step sequence and dependency graph
+- [ ] Step 3: Write the recipe YAML
+- [ ] Step 4: Test with dry-run mode
+- [ ] Step 5: Validate with a real execution
+```
+
+## Step 1: Identify Workflow
+
+Determine the repeatable workflow pattern:
+- What commands/skills/agents are involved?
+- What order do they execute in?
+- Which steps can run in parallel?
+- Where should the user be asked to confirm (checkpoints)?
+
+## Step 2: Design Step Sequence
+
+Map out the dependency graph:
+- List all steps with their hatch3r command or skill reference
+- Identify dependencies between steps
+- Identify steps that can run in parallel
+- Mark checkpoint steps where user confirmation adds value
+
+## Step 3: Write Recipe YAML
+
+Create the recipe file in `.hatch3r/recipes/` following the schema defined in the `hatch3r-recipe` command. Include:
+- Clear name and description
+- Required variables with descriptions
+- Steps with proper `depends_on` and `parallel_with` relationships
+- Checkpoint markers at decision points
+- Completion message with next steps
+
+## Step 4: Test with Dry-Run
+
+Execute `--dry-run` to validate:
+- YAML schema is valid
+- All referenced commands/skills exist
+- Dependency graph has no cycles
+- Variables are properly referenced
+- Prerequisites are checkable
+
+## Step 5: Validate with Real Execution
+
+Run the recipe on a test project to verify:
+- Steps execute in correct order
+- Parallel steps don't conflict
+- Checkpoints pause appropriately
+- Error handling works (intentionally fail a step)
+- Completion message is accurate
+
+## Definition of Done
+
+- [ ] Recipe YAML validates against schema
+- [ ] Dry-run completes without errors
+- [ ] Real execution produces expected results
+- [ ] Error handling tested
+- [ ] Recipe committed to project or shared globally

package/skills/hatch3r-refactor/SKILL.md

@@ -0,0 +1,86 @@
+---
+id: hatch3r-refactor
+description: Internal code quality improvement workflow without changing external behavior. Use when refactoring code structure, simplifying modules, or improving maintainability.
+---
+> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
+
+# Code Refactor Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Read the issue, specs, and existing tests
+- [ ] Step 2: Produce a refactor plan
+- [ ] Step 3: Implement with behavioral preservation
+- [ ] Step 4: Verify all tests pass, add regression tests
+- [ ] Step 5: Open PR
+```
+
+## Step 1: Read Inputs
+
+- Parse the issue body: motivation, proposed change, affected files, safety plan, risk analysis, acceptance criteria.
+- Read project quality standards documentation.
+- Read specs for the area being refactored.
+- Review all existing tests — every one must still pass after refactoring.
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 2: Refactor Plan
+
+Before changing code, output:
+
+- **Goal:** what improves (readability, performance, maintainability)
+- **Strategy:** how the refactor works
+- **Files to modify:** list with what changes
+- **Behavioral invariant:** what must NOT change
+- **Risk assessment:** what could go wrong, how to detect
+- **Rollback:** how to revert if needed
+
+## Step 3: Implement
+
+- Refactor with minimum changes needed.
+- 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.
+
+## Step 4: Verify
+
+- All existing tests must pass without modification.
+- Add regression tests for previously untested at-risk behavior.
+- Performance verification if refactored code is on a hot path.
+
+```bash
+npm run lint && npm run typecheck && npm run test
+```
+
+## Step 5: Open PR
+
+Use the project's PR template. Include:
+
+- Motivation (why this refactor now)
+- Before/after structure (high-level description)
+- Proof of behavioral preservation (test results)
+- Performance impact (if applicable)
+
+## Required Agent Delegation
+
+You MUST spawn these agents via the Task tool (`subagent_type: "generalPurpose"`) at the appropriate points:
+
+- **`hatch3r-researcher`** — MUST spawn before implementation with modes `current-state`, `refactoring-strategy`, `migration-path`. Skip only for trivially simple refactors (`risk:low` AND `priority:p3`).
+- **`hatch3r-reviewer`** — MUST spawn after implementation for code review, verifying behavioral preservation.
+
+## Related Skills
+
+- **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
+
+## Definition of Done
+
+- [ ] All existing tests pass without modification
+- [ ] Regression tests added for at-risk behavior
+- [ ] No new linter warnings
+- [ ] Performance budgets maintained
+- [ ] Dead code removed
+- [ ] No external behavior changed
+- [ ] No new dependencies introduced

package/skills/hatch3r-release/SKILL.md

@@ -0,0 +1,93 @@
+---
+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.
+---
+> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
+
+# Release Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Determine version bump (major/minor/patch) based on changes
+- [ ] Step 2: Generate changelog from merged PRs and commit history
+- [ ] Step 3: Update version in package.json and any other version references
+- [ ] Step 4: Verify quality gates (lint, typecheck, all tests)
+- [ ] Step 5: Create git tag and GitHub release with changelog
+- [ ] Step 6: Deploy and verify (staging first if applicable, then production)
+- [ ] Step 7: Monitor post-deploy for errors/regressions
+```
+
+## Step 1: Determine Version Bump
+
+- Review changes since last release: merged PRs, commit history.
+- Use **GitHub MCP** (`search_issues`, PR search) to list merged PRs since last tag.
+- Apply [Semantic Versioning](https://semver.org/):
+  - **Major:** Breaking changes (API, data model, config)
+  - **Minor:** New features, backward-compatible
+  - **Patch:** Bug fixes, security patches, non-breaking improvements
+- Check project release gates: no P0/P1 bugs open, E2E pass, performance budgets met.
+
+## Step 2: Generate Changelog
+
+- List merged PRs since last release (e.g., `git log v1.2.0..HEAD --oneline` or GitHub Releases API).
+- Group by category: Features, Bug Fixes, Security, Dependencies, Chore.
+- Format each entry: `- description (#PR-number)` or `- description (commit hash)`.
+- Include breaking changes section if major bump.
+- Follow project changelog format (e.g., `CHANGELOG.md` or GitHub Release notes).
+
+## Step 3: Update Version
+
+- Update `version` in `package.json`.
+- Update any other version references: `package-lock.json` (via `npm version`), docs, config files.
+- Run `npm install` to refresh lockfile if needed.
+- Commit with message: `chore(release): vX.Y.Z` or similar.
+
+## Step 4: Verify Quality Gates
+
+```bash
+npm run lint && npm run typecheck && npm run test
+npm run build
+```
+
+- All tests pass (unit, integration, E2E).
+- Bundle size within budget (if defined).
+- Security rules tests pass if rules changed.
+- No TODO without linked issue.
+- See project quality documentation for full pre-release gates.
+
+## Step 5: Create Tag and GitHub Release
+
+- Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`.
+- Push tag: `git push origin vX.Y.Z`.
+- Create GitHub Release with:
+  - Title: `vX.Y.Z`
+  - Changelog as release notes
+  - Attach build artifacts if applicable
+- Use **GitHub MCP** if available for release creation; otherwise use `gh release create` or GitHub UI.
+
+## Step 6: Deploy and Verify
+
+- Deploy to staging first (if applicable). Run smoke tests.
+- Deploy to production (project-specific pipeline).
+- Verify: health check, key flows.
+- Document deploy method and environment in project docs if not already.
+
+## Step 7: Monitor Post-Deploy
+
+- Monitor error rate (target per project SLO).
+- Monitor function/API error rate.
+- Check for startup time regression.
+- Watch user-reported issues for first 24h.
+- If errors spike: rollback and investigate.
+
+## Definition of Done
+
+- [ ] Version bumped in package.json
+- [ ] Changelog generated and included in release
+- [ ] Git tag created and pushed
+- [ ] GitHub release published with changelog
+- [ ] Deployed to production and verified
+- [ ] Post-deploy monitoring completed (no critical regressions)
+- [ ] All release gates satisfied

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

@@ -0,0 +1,70 @@
+---
+id: hatch3r-rule-customize
+description: Create and manage per-rule customization files for scope overrides, description changes, enable/disable control, and project-specific markdown instructions. Use when tailoring rules to project-specific needs.
+---
+# Rule Customization Management
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Identify which rule 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 Rule
+
+Determine which hatch3r rule needs customization:
+- Review the rules in `.agents/rules/` and their default scope/content
+- Identify gaps between default rules and project needs
+- Check for existing customization files in `.hatch3r/rules/`
+
+## Step 2: Determine Customization Needs
+
+Decide which customization approach to use:
+
+**YAML (`.customize.yaml`)** — for structured overrides:
+- **Scope**: Override when the rule applies (`always`, glob patterns like `src/**/*.ts`)
+- **Description**: Change how the rule is described in adapter outputs
+- **Enabled**: Set to `false` to disable the rule entirely
+
+**Markdown (`.customize.md`)** — for free-form instructions:
+- Project-specific rule additions or constraints
+- Domain-specific standards and requirements
+- Framework-specific conventions
+
+## Step 3: Create Customization Files
+
+Create files in `.hatch3r/rules/`:
+
+**For YAML overrides:**
+```yaml
+# .hatch3r/rules/{rule-id}.customize.yaml
+scope: "src/**/*.ts,src/**/*.tsx"
+description: "Testing rules with healthcare compliance requirements"
+```
+
+**For markdown instructions:**
+Create `.hatch3r/rules/{rule-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 scope is applied correctly in adapter-specific frontmatter (globs, alwaysApply, etc.)
+- Check description in adapter outputs
+- Check markdown instructions appear inside the managed block
+- Verify disabled rules are absent from adapter outputs
+
+## Definition of Done
+
+- [ ] Customization files created in `.hatch3r/rules/`
+- [ ] `npx hatch3r sync` completes without errors
+- [ ] Adapter output files reflect the customizations (scope, description, content)
+- [ ] Customization files committed to the repository

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

@@ -0,0 +1,67 @@
+---
+id: hatch3r-skill-customize
+description: Create and manage per-skill customization files for description overrides, enable/disable control, and project-specific markdown instructions. Use when tailoring skill workflows to project-specific needs.
+---
+# Skill Customization Management
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Identify which skill 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 Skill
+
+Determine which hatch3r skill needs customization:
+- Review the skills in `.agents/skills/` and their default workflows
+- Identify gaps between default workflows and project needs
+- Check for existing customization files in `.hatch3r/skills/`
+
+## Step 2: Determine Customization Needs
+
+Decide which customization approach to use:
+
+**YAML (`.customize.yaml`)** — for structured overrides:
+- **Description**: Change how the skill is described in adapter frontmatter
+- **Enabled**: Set to `false` to disable the skill entirely
+
+**Markdown (`.customize.md`)** — for free-form instructions:
+- Project-specific workflow additions
+- Additional prerequisites or validation steps
+- Custom tooling or process requirements
+
+## Step 3: Create Customization Files
+
+Create files in `.hatch3r/skills/`:
+
+**For YAML overrides:**
+```yaml
+# .hatch3r/skills/{skill-id}.customize.yaml
+description: "Issue workflow with mandatory security review"
+```
+
+**For markdown instructions:**
+Create `.hatch3r/skills/{skill-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 frontmatter (where applicable)
+- Check markdown instructions appear inside the managed block
+- Verify disabled skills are absent from adapter outputs
+
+## Definition of Done
+
+- [ ] Customization files created in `.hatch3r/skills/`
+- [ ] `npx hatch3r sync` completes without errors
+- [ ] Adapter output files reflect the customizations
+- [ ] Customization files committed to the repository