hatch3r 1.0.0

package/skills/hatch3r-feature/SKILL.md

@@ -0,0 +1,129 @@
+---
+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.
+---
+> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
+
+# Feature Implementation Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Read the issue and all relevant specs
+- [ ] Step 2: Produce an implementation plan
+- [ ] Step 2b: Test-first approach (TDD alternative — optional)
+- [ ] Step 3: Implement the vertical slice
+- [ ] Step 4: Write tests (unit, integration, security, E2E)
+- [ ] Step 5: Verify quality gates
+- [ ] Step 5b: Browser verification (if UI)
+- [ ] Step 6: Open PR
+```
+
+## Step 1: Read Inputs
+
+- Parse the issue body: problem/goal, proposed solution, acceptance criteria, scope (in/out), UX notes, edge cases, security considerations, rollout plan.
+- Read relevant project documentation (glossary, user flows, behavior, event model, data model, privacy, monetization, as applicable).
+- Review existing code patterns in the affected area.
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 2: Implementation Plan
+
+Before coding, output:
+
+- **Approach:** high-level strategy
+- **Files to create/modify:** list with what changes
+- **Data model changes:** new collections/fields, if any
+- **Event changes:** new event types, if any
+- **Entitlement changes:** new gates, if any
+- **Risks:** what could go wrong
+- **Phasing:** how to split into PRs if large
+
+## Step 2b: Test-First Approach (TDD Alternative)
+
+When acceptance criteria are specific and testable, write tests BEFORE implementing:
+
+1. **Write acceptance tests** from the issue's acceptance criteria. Each criterion becomes at least one test.
+2. **Write unit test shells** for planned functions/modules from the implementation plan.
+3. **Run all new tests** — confirm they fail (proves they're testing real behavior, not tautologies).
+4. **Implement the vertical slice** (Step 3) to make tests pass incrementally.
+5. **Add edge case tests** as you discover them during implementation.
+
+Prefer TDD when:
+- Acceptance criteria are specific and quantifiable
+- Building a well-defined API, service, or utility
+- Working in a domain with complex business logic
+
+Use standard flow (implement → test) when:
+- Acceptance criteria are exploratory ("improve UX of...")
+- Heavy UI work where visual verification is primary
+- Prototyping or spike work
+
+## Step 3: Implement
+
+- Deliver a complete vertical slice (data -> logic -> UI).
+- 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.
+
+## Step 4: Tests
+
+- **Unit tests:** All new business logic.
+- **Integration tests:** Cross-module interactions.
+- **Security rules tests:** If database collections/rules modified.
+- **Contract tests:** If new event types or API contracts.
+- **E2E tests:** If user-facing flow.
+
+## Step 5: Verify
+
+```bash
+npm run lint && npm run typecheck && npm run test
+```
+
+## Step 5b: Browser Verification (if UI)
+
+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.
+- Navigate to the page or surface affected by the new feature.
+- Walk through the acceptance criteria visually — confirm the feature renders and behaves correctly.
+- 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.
+- Capture screenshots showing the feature working as expected.
+
+## Step 6: Open PR
+
+Use the project's PR template. Include:
+
+- Feature summary and motivation
+- Implementation approach
+- Screenshots/recordings (if UI)
+- Test evidence
+- Rollout plan (feature flag if specified)
+
+## 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 `codebase-impact`, `feature-design`, `architecture`. Skip only for trivially simple features (`risk:low` AND `priority:p3`).
+- **`hatch3r-implementer`** — MUST spawn one per sub-issue when the feature is decomposed into multiple tasks. Each implementer receives its own sub-issue context.
+- **`hatch3r-reviewer`** — MUST spawn after implementation for code review before PR creation.
+
+## Related Skills
+
+- **Skill**: `hatch3r-qa-validation` — use this skill for end-to-end verification of the implemented feature
+
+## Definition of Done
+
+- [ ] All acceptance criteria met
+- [ ] Unit + integration tests cover new logic
+- [ ] Security rules tested (if data model changed)
+- [ ] Entitlement gates enforced server-side (if gated)
+- [ ] Accessibility requirements met (if UI)
+- [ ] Browser-verified against acceptance criteria (if UI)
+- [ ] Performance budgets maintained
+- [ ] Privacy invariants respected
+- [ ] Rollout plan documented
+- [ ] Relevant spec docs updated

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

@@ -0,0 +1,150 @@
+---
+id: hatch3r-gh-agentic-workflows
+description: Set up GitHub Agentic Workflows for continuous AI-powered repository automation
+---
+# GitHub Agentic Workflows Integration
+
+GitHub Agentic Workflows (technical preview, Feb 2026) bring AI agent orchestration into
+GitHub Actions. This skill guides setup for hatch3r-managed projects.
+
+## Overview
+
+Agentic Workflows are markdown files in `.github/workflows/` with YAML frontmatter that
+compile to GitHub Actions jobs. They support multiple AI engines (GitHub Copilot, Claude,
+OpenAI Codex) and use MCP for tool access.
+
+## Available Workflow Templates
+
+hatch3r recommends these agentic workflow patterns for projects:
+
+### 1. Continuous Test Improvement
+
+Automatically assess test coverage and add high-value tests.
+
+```yaml
+# .github/workflows/hatch3r-continuous-testing.md
+---
+name: Continuous Test Improvement
+on:
+  schedule:
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+engine: copilot
+permissions:
+  contents: read
+  pull-requests: write
+---
+```
+
+Analyze test coverage gaps and open PRs with new tests for uncovered critical paths.
+
+### 2. Continuous Triage
+
+Automatically summarize, label, and route new issues.
+
+```yaml
+# .github/workflows/hatch3r-continuous-triage.md
+---
+name: Continuous Triage
+on:
+  issues:
+    types: [opened]
+engine: copilot
+permissions:
+  issues: write
+---
+```
+
+When a new issue is opened, analyze it, apply labels from the hatch3r taxonomy
+(type:*, priority:*, area:*), and add a triage summary comment.
+
+### 3. Continuous Documentation
+
+Keep documentation aligned with code changes.
+
+```yaml
+# .github/workflows/hatch3r-continuous-docs.md
+---
+name: Continuous Documentation
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+engine: copilot
+permissions:
+  contents: write
+  pull-requests: write
+---
+```
+
+After a PR is merged, check if documentation needs updating and open a follow-up PR.
+
+## Security Considerations
+
+- Workflows run in sandboxed environments with minimal permissions
+- Use read-only defaults; only grant write permissions when needed
+- Review all AI-generated changes before merging
+- Network isolation and tool allowlisting are enforced by the runtime
+
+## Integration with hatch3r
+
+- hatch3r's label taxonomy (type:*, executor:*, priority:*) aligns with agentic triage
+- The hatch3r-test-writer agent's patterns can inform continuous testing workflows
+- The hatch3r-docs-writer agent's patterns can inform continuous documentation
+- Board management commands complement continuous triage
+
+## Setup
+
+1. Enable GitHub Agentic Workflows in your repository settings
+2. Create workflow files in `.github/workflows/` using the templates above
+3. Configure the AI engine (copilot is default, claude and codex are alternatives)
+4. Set appropriate permissions for each workflow
+5. Monitor workflow runs in the Actions tab
+
+## Verification Steps
+
+1. **Syntax check**: Validate the workflow file with `gh workflow view {name}` or the GitHub Actions web UI.
+2. **Dry run**: Trigger manually via `gh workflow run {name}` and monitor with `gh run watch`.
+3. **Output review**: Check the AI-generated output (PR, comment, label) for quality and correctness.
+4. **Permission audit**: Verify the workflow cannot access resources beyond its declared permissions.
+5. **Idempotency**: Run the workflow twice on the same input — it should not create duplicate artifacts.
+6. **Error handling**: Trigger with invalid/edge-case input — workflow should fail gracefully with clear error.
+
+## Monitoring
+
+- **Execution tracking**: Use `gh run list --workflow={name}` to monitor recent runs.
+- **Failure alerts**: Configure GitHub Actions notifications (Settings → Notifications → Actions).
+- **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 / total PRs), mean time per run.
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| Workflow doesn't trigger | Incorrect `on:` event or branch filter | Verify event type matches, check branch protection rules |
+| AI output is empty/poor | Insufficient context in workflow body | Add more context, reference specific files, include examples |
+| Permission denied | Missing or insufficient permissions | Add required permissions in frontmatter, check org policies |
+| MCP tool fails | Server not available or misconfigured | Verify MCP server is accessible, check auth tokens |
+| Rate limiting | Too many workflow runs | Add concurrency groups, reduce trigger frequency |
+| Workflow hangs | Large repo context or slow AI response | Set timeout-minutes, scope file references |
+
+## Rollback
+
+If a workflow produces undesirable results:
+
+1. **Disable immediately**: `gh workflow disable {name}` or toggle in repo Settings → Actions.
+2. **Revert outputs**: Close AI-generated PRs, remove applied labels, revert merged changes if needed.
+3. **Diagnose**: Review recent run logs with `gh run view {run-id} --log`.
+4. **Fix and re-enable**: Update the workflow file, test via manual dispatch, then re-enable.
+
+## Definition of Done
+
+- [ ] Workflow file created in `.github/workflows/` with correct YAML frontmatter
+- [ ] Engine configured (copilot/claude/codex) with appropriate model selection
+- [ ] Permissions scoped to minimum required (read-only defaults, write only where needed)
+- [ ] MCP tool access configured if needed (with allowlisting)
+- [ ] Trigger events appropriate for the workflow's purpose
+- [ ] Manual `workflow_dispatch` trigger included for testing
+- [ ] Workflow tested via manual dispatch with expected outcomes verified
+- [ ] Monitoring configured (GitHub Actions notifications or Slack integration)
+- [ ] Documentation updated (README or CONTRIBUTING) to describe the new workflow

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

@@ -0,0 +1,86 @@
+---
+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.
+---
+# Incident Response Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Classify severity (P0-P3) based on impact
+- [ ] Step 2: Triage — identify affected systems, user impact, blast radius
+- [ ] Step 3: Mitigate — apply hotfix or rollback, verify mitigation works
+- [ ] Step 4: Root cause analysis — trace the failure chain
+- [ ] Step 5: Write post-mortem with timeline, root cause, action items
+- [ ] Step 6: Create follow-up issues for permanent fixes and preventive measures
+```
+
+## Step 1: Classify Severity
+
+| Severity | Definition                                  | Examples                                     |
+| -------- | ------------------------------------------- | -------------------------------------------- |
+| P0       | Complete outage, data loss, security breach | App unusable, auth down, data exposed        |
+| P1       | Major degradation, significant user impact  | Sync failing, billing broken, >1% error rate |
+| P2       | Partial degradation, limited impact         | Single flow broken, slow performance       |
+| P3       | Minor issue, workaround available            | Cosmetic bug, edge case                     |
+
+- Use **GitHub MCP** (`issue_read`, `search_issues`) to check for related issues or prior incidents.
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 2: Triage
+
+- **Affected systems:** Frontend, backend, database, auth, payment, third-party services?
+- **User impact:** How many users? Which flows? Which plans (free/paid)?
+- **Blast radius:** Is the issue contained or spreading?
+- **Data:** Any data corruption, loss, or exposure? Check project privacy/security specs for implications.
+- **Timeline:** When did it start? Any recent deploys, config changes, or dependency updates?
+
+## Step 3: Mitigate
+
+- **Immediate actions:** Rollback last deploy, disable feature flag, revert config, scale up, or apply hotfix.
+- **Verification:** Confirm mitigation works — error rate drops, affected flow recovers.
+- **Communication:** Notify stakeholders if P0/P1. Document status in incident channel or issue.
+- Do not spend time on perfect fixes during active incident — stabilize first.
+
+## Step 4: Root Cause Analysis
+
+- Trace the failure chain: what changed, what failed, why.
+- Review logs (correlationId, userId), metrics, deploy history.
+- Check ADRs in project docs for architectural context.
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 5: Post-Mortem
+
+Write a structured post-mortem document:
+
+- **Summary:** One-paragraph description of the incident.
+- **Timeline:** Key events (detection, mitigation, resolution) with timestamps.
+- **Root cause:** What went wrong and why.
+- **Impact:** Users affected, duration, business impact.
+- **Action items:** Permanent fixes, preventive measures, process improvements.
+- **Lessons learned:** What we'll do differently.
+
+Store in project incident docs or as a GitHub issue/wiki page. Follow project conventions.
+
+## Step 6: Follow-Up Issues
+
+- Create GitHub issues for each action item from the post-mortem.
+- Label appropriately (e.g., `incident-follow-up`, `P0`, `P1`).
+- Link issues to the post-mortem and to each other.
+- Assign owners and due dates for critical fixes.
+- Use **GitHub MCP** (`issue_create` or equivalent) to create issues.
+
+## Definition of Done
+
+- [ ] Incident mitigated and verified
+- [ ] Post-mortem written with timeline, root cause, and action items
+- [ ] Follow-up issues created for permanent fixes and preventive measures
+- [ ] Stakeholders notified (if P0/P1)
+- [ ] No sensitive data (secrets, PII, code content) in post-mortem or logs
+
+## Additional Resources
+
+- Privacy/security specs: project documentation
+- Observability: project logging and correlation conventions
+- Error handling: project error handling patterns

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

@@ -0,0 +1,139 @@
+---
+id: hatch3r-issue-workflow
+description: Guides the 8-step agentic development workflow for GitHub issues. Covers parsing issues, loading skills, reading specs, planning, implementing, testing, opening PRs, and addressing review. Use when working on any GitHub issue or when the user mentions an issue number.
+---
+# Issue Workflow
+
+## Quick Start
+
+When assigned a GitHub issue, follow these 8 steps in order:
+
+```
+Task Progress:
+- [ ] Step 1: Parse the issue
+- [ ] Step 2: Load the issue-type skill
+- [ ] Step 3: Read relevant specs
+- [ ] Step 4: Produce a plan
+- [ ] Step 5: Implement
+- [ ] Step 6: Test
+- [ ] Step 6b: Browser verification (if UI)
+- [ ] Step 7: Open PR
+- [ ] Step 8: Address review
+```
+
+## Step 1: Parse the Issue
+
+- Read all fields from the issue template.
+- Identify: type (bug/feature/refactor/qa), affected area, priority, acceptance criteria.
+- Note linked issues and spec references.
+
+## Step 2: Load the Issue-Type Skill
+
+Navigate to the matching skill based on issue type:
+
+| Issue Type        | Skill                    |
+| ----------------- | ------------------------ |
+| Bug report        | hatch3r-bug-fix          |
+| Feature request   | hatch3r-feature          |
+| Code refactor     | hatch3r-refactor         |
+| Logical refactor  | hatch3r-logical-refactor |
+| Visual refactor   | hatch3r-visual-refactor  |
+| QA E2E validation | hatch3r-qa-validation    |
+
+## Step 3: Read Relevant Specs
+
+Load only the specs relevant to the issue area. See the spec mapping table in the project context rule.
+
+Also check project ADRs for architectural constraints.
+
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 4: Produce a Plan
+
+Output a structured plan before writing code:
+
+- **Approach:** strategy
+- **Files to touch:** list with brief description per file
+- **Tests to write:** list
+- **Risks:** what could go wrong
+- **Open questions:** if any, propose answers
+
+## Step 4b: Sub-Agent Delegation
+
+Every issue MUST be delegated to a dedicated `hatch3r-implementer` sub-agent — never implement inline. The board-pickup command orchestrates this automatically, but if running issue-workflow standalone, follow the pattern below.
+
+### Single Issue
+
+Spawn one `hatch3r-implementer` sub-agent via the Task tool. Include: issue number, body, acceptance criteria, issue type, researcher output, and spec references. Await the result.
+
+### Epic with Sub-Issues
+
+1. **Group sub-issues by dependency level** from the epic's Implementation Order.
+2. **Spawn one implementer sub-agent per sub-issue** using the Task tool. Include: issue number, body, acceptance criteria, issue type, parent epic context, and spec references.
+3. **Launch sub-issues at the same dependency level in parallel** — as many concurrently as the platform supports.
+4. **Await all sub-agents at a level** before starting the next level.
+5. **Review results** from each sub-agent. Resolve any file conflicts between parallel outputs.
+
+### Multiple Standalone Issues (Batch)
+
+When working on multiple standalone issues (not part of an epic), apply the same parallel pattern:
+
+1. **Group issues by dependency level.** Independent issues (no mutual dependencies) share the same level and run in parallel.
+2. **Spawn one researcher sub-agent per issue** in parallel — as many concurrently as the platform supports. Each issue gets individual context gathering since standalone issues are unrelated.
+3. **Spawn one implementer sub-agent per issue per level** in parallel — as many concurrently as the platform supports. Each receives its own researcher output.
+4. **Await all sub-agents at a level** before starting the next level.
+5. **Review results** from each sub-agent. Resolve any cross-issue file conflicts.
+
+### Plain Chat with Multiple Tasks
+
+When working from plain chat instructions with multiple tasks (numbered lists, multiple issue references, or distinct requests), parse into discrete tasks and apply the batch delegation pattern above. For GitHub issue references, fetch issue details. For natural language tasks, derive title, acceptance criteria, and type from the instruction.
+
+The implementer sub-agent protocol is defined in the hatch3r-implementer agent. Each sub-agent handles its own implementation and testing but does NOT create branches, commits, or PRs.
+
+## Step 5: Implement
+
+- Follow the plan. Use stable IDs from the project glossary.
+- Do not expand scope beyond acceptance criteria.
+- Remove dead code. Keep changes minimal and focused.
+
+## Step 6: Test
+
+- Unit tests for new logic. Integration tests for cross-module interactions.
+- Database/security rules tests if rules changed.
+- Regression tests for preserved behavior.
+- All tests must be deterministic, isolated, and fast.
+
+## Step 6b: Browser Verification (if UI)
+
+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.
+- 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.
+- Check the browser console for errors or warnings.
+- Capture screenshots as evidence for the PR.
+
+## Step 7: Open PR
+
+- Use the project's PR template. Fill every section.
+- Link to the issue. Include plan, implementation summary, test evidence.
+- **Base branch:** Use `board.defaultBranch` from `/.agents/hatch.json` when creating PRs (fallback: `"main"`). Use `gh pr create --base {defaultBranch}` or equivalent.
+- Self-review against the Definition of Done from the loaded skill.
+
+## Step 8: Address Review
+
+- Respond to every review comment.
+- Push fixes as new commits (don't force-push during review).
+- Re-request review after addressing all comments.
+
+## Escalation
+
+Stop and ask when:
+
+1. Acceptance criteria are contradictory.
+2. Security concern discovered.
+3. Architectural decision needed (new ADR required).
+4. Spec conflict found.
+5. Scope creep detected.
+6. Test infrastructure missing.

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

@@ -0,0 +1,73 @@
+---
+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.
+---
+> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool as appropriate.
+
+# Logical Refactor Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Read the issue, specs, and existing tests
+- [ ] Step 2: Produce a change plan
+- [ ] Step 3: Implement the behavior change
+- [ ] Step 4: Update tests and verify invariants
+- [ ] Step 5: Open PR
+```
+
+## Step 1: Read Inputs
+
+- Parse the issue body: motivation, before/after behavior, invariants preserved, invariants changed, acceptance criteria, affected files, risk analysis, testing plan.
+- Read relevant project documentation: behavior engine, event model, data model, privacy, quality.
+- Review existing tests to understand what behavior is currently asserted.
+- For external library docs and current best practices, follow the project's tooling hierarchy.
+
+## Step 2: Change Plan
+
+Before modifying code, output:
+
+- **Current behavior:** how it works now
+- **New behavior:** how it will work after
+- **Invariants preserved:** list from issue + specs
+- **Invariants changed:** list, with justification
+- **Cascading effects:** which other flows/components are affected
+- **Files to modify:** list with what changes
+- **Risks:** what could go wrong
+
+## Step 3: Implement
+
+- Implement behavior change as described in the before/after section.
+- Verify every listed invariant is maintained (or explicitly updated with justification).
+- Update any spec docs affected by the behavior change.
+
+## Step 4: Test
+
+- **Update existing tests** that assert old behavior to assert new behavior.
+- **Add new tests** for the new behavior, especially edge cases.
+- **Regression tests** for preserved invariants.
+- **Integration tests** if change affects cross-module interactions.
+
+```bash
+npm run lint && npm run typecheck && npm run test
+```
+
+## Step 5: Open PR
+
+Use the project's PR template. Include:
+
+- Before/after behavior with concrete examples
+- Invariants preserved and changed
+- Test evidence for both new behavior and preserved behavior
+- Spec docs updated (if any)
+
+## Definition of Done
+
+- [ ] New behavior matches the "after" description
+- [ ] All preserved invariants verified with tests
+- [ ] Changed invariants documented and justified
+- [ ] Existing tests updated, new tests added
+- [ ] Performance budgets maintained
+- [ ] Privacy/security invariants respected
+- [ ] Spec docs updated if behavior diverges from spec

package/skills/hatch3r-migration/SKILL.md

@@ -0,0 +1,76 @@
+---
+id: hatch3r-migration
+type: skill
+description: Plan and execute migrations for databases, frameworks, and dependencies. Covers breaking change analysis, phased rollout, and rollback procedures.
+---
+
+# Migration Workflow
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 1: Assess migration scope
+- [ ] Step 2: Analyze breaking changes
+- [ ] Step 3: Create migration plan
+- [ ] Step 4: Execute migration phases
+- [ ] Step 5: Validate and verify
+- [ ] Step 6: Document and clean up
+```
+
+## Step 1: Assess Migration Scope
+
+- Identify the migration type: database schema, framework version, dependency upgrade, language version, or infrastructure change.
+- Inventory all affected files, modules, and services.
+- Check for transitive dependency impacts — upgrading one package may force others.
+- Review the target version's changelog, migration guide, and known issues.
+- Estimate effort and risk level (low/medium/high) based on scope.
+
+## Step 2: Analyze Breaking Changes
+
+- Compare current vs target API surfaces for changed/removed features.
+- Search the codebase for usage of deprecated or removed APIs.
+- For database migrations: identify schema changes, data transformations, and index impacts.
+- For framework upgrades: check configuration format changes, plugin compatibility, and behavioral differences.
+- Document each breaking change with affected file locations and required code modifications.
+
+## Step 3: Create Migration Plan
+
+- Define phases with clear boundaries — each phase should be independently deployable and rollback-safe.
+- Phase ordering: compatibility layer first, then consumer migration, then removal of old code.
+- For database migrations: write both `up` and `down` migration scripts. Test both directions.
+- Include a rollback plan for each phase with specific steps and time estimates.
+- Set validation criteria for each phase before proceeding to the next.
+
+## Step 4: Execute Migration Phases
+
+- Implement one phase at a time. Verify before proceeding.
+- For dependency upgrades: update lockfile, fix type errors, update API calls, run tests.
+- For database migrations: run against a staging copy first, verify data integrity, measure execution time.
+- For framework migrations: use codemods where available, manual fixes where not.
+- Keep backward compatibility during transition — both old and new code paths should work.
+
+## Step 5: Validate and Verify
+
+- Run the full test suite after each phase.
+- For database migrations: verify row counts, check constraint integrity, test queries against migrated data.
+- For dependency upgrades: verify bundle size impact, check for runtime behavior changes.
+- Performance benchmark critical paths before and after.
+- Test rollback procedure on a staging environment.
+
+## Step 6: Document and Clean Up
+
+- Remove compatibility shims and old code paths after the migration is complete.
+- Update project documentation (README, setup guides, deployment docs).
+- Update CI configuration if build steps changed.
+- Delete unused migration scripts after they've been applied to all environments.
+- Write a migration retrospective noting what went well and any issues encountered.
+
+## Definition of Done
+
+- [ ] All phases completed and verified
+- [ ] Full test suite passes
+- [ ] Rollback procedure tested
+- [ ] No backward-compatibility shims remain
+- [ ] Documentation updated
+- [ ] Performance verified against baseline