hatch3r 1.0.0 → 1.2.0

package/commands/hatch3r-hooks.md

@@ -2,7 +2,13 @@
 id: hatch3r-hooks
 type: command
 description: Define and manage event-driven hooks that activate agents on project events
+tags: [core, devops]
 ---
+
+## Agent Pipeline
+
+This command runs as a single orchestrator without sub-agent delegation. Hook definition and management are performed inline.
+
 # Hooks — Event-Driven Agent Activation
 
 Define, edit, and manage event-driven hooks that automatically activate hatch3r agents when specific project events occur. Hook definitions are tool-agnostic — the adapter pipeline translates them into tool-native configurations during `npx hatch3r sync`.
@@ -15,8 +21,8 @@ Execute these steps in order. **Do not skip any step.** Ask the user at every ch
 
 ### Step 1: Discover Current State
 
-1. Check `/.agents/hooks/` for existing hook definition files (`.md` files with frontmatter).
-2. Read `/.agents/hatch.json` for configured tools and features.
+1. Check `.agents/hooks/` for existing hook definition files (`.md` files with frontmatter).
+2. Read `.agents/hatch.json` for configured tools and features.
 3. List existing hooks with their event, agent, and conditions.
 
 Present the current state:
@@ -76,7 +82,7 @@ Present available hatch3r agents:
 - `dependency-auditor` — Dependency security and update checks
 - `docs-writer` — Documentation generation and updates
 
-If the user wants a custom agent name not in this list, accept it but warn that the agent must exist in `/.agents/agents/`.
+If the user wants a custom agent name not in this list, accept it but warn that the agent must exist in `.agents/agents/`.
 
 **ASK:** "Select an agent to activate when this event fires."
 
@@ -89,7 +95,7 @@ If the user wants a custom agent name not in this list, accept it but warn that
 
 #### 2d. Write Hook Definition File
 
-Generate the hook definition file at `/.agents/hooks/{event}-{agent-short-name}.md`:
+Generate the hook definition file at `.agents/hooks/{event}-{agent-short-name}.md`:
 
 ```markdown
 ---
@@ -131,7 +137,7 @@ For editing an existing hook:
 1. List all hooks and ask which to edit.
 2. Show current definition.
 3. Ask what to change (event, agent, conditions, description).
-4. Update the hook file in `/.agents/hooks/`.
+4. Update the hook file in `.agents/hooks/`.
 
 **ASK:** "Updated hook: {summary}. Save? (yes / revert / cancel)"
 
@@ -142,7 +148,7 @@ For editing an existing hook:
 1. List all hooks and ask which to remove.
 2. Show the hook definition.
 
-**ASK:** "Remove hook '{id}'? This will delete `/.agents/hooks/{filename}`. (yes / cancel)"
+**ASK:** "Remove hook '{id}'? This will delete `.agents/hooks/{filename}`. (yes / cancel)"
 
 3. Delete the file. Warn that tool-specific generated files (e.g., `.cursor/rules/hatch3r-hook-*.mdc`) will be cleaned up on the next `npx hatch3r sync`.
 
@@ -150,7 +156,7 @@ For editing an existing hook:
 
 ### Step 5: Sync Hooks to Tools
 
-1. Read all hook definitions from `/.agents/hooks/`.
+1. Read all hook definitions from `.agents/hooks/`.
 2. For each configured tool in `hatch.json`, describe what will be generated:
    - **Claude Code:** Hook documentation appended to managed section of `CLAUDE.md`
    - **Cursor:** Glob-based `.mdc` rule files in `.cursor/rules/hatch3r-hook-*.mdc`
@@ -190,7 +196,7 @@ In `hatch.json`:
 }
 ```
 
-Custom events follow the same hook definition format as built-in events — create a hook file in `/.agents/hooks/` with `event: custom:{domain}:{action}`.
+Custom events follow the same hook definition format as built-in events — create a hook file in `.agents/hooks/` with `event: custom:{domain}:{action}`.
 
 ---
 
@@ -265,9 +271,9 @@ For `pre-commit` with three hooks:
 
 ## Error Handling
 
-- `/.agents/hooks/` doesn't exist: create it automatically.
+- `.agents/hooks/` doesn't exist: create it automatically.
 - Invalid event type: warn and show the valid events table.
-- Agent not found in `/.agents/agents/`: warn but allow (agent may be added later).
+- Agent not found in `.agents/agents/`: warn but allow (agent may be added later).
 - Adapter doesn't support hooks: generate hook definition file anyway, warn that sync for that tool is a no-op.
 - Duplicate hook ID: warn and ask the user to choose a different name or overwrite.
 

package/commands/hatch3r-learn.md

@@ -2,7 +2,13 @@
 id: hatch3r-learn
 type: command
 description: Capture learnings from development sessions into reusable knowledge files for future consultation.
+tags: [core, maintenance]
 ---
+
+## Agent Pipeline
+
+This command runs as a single orchestrator without sub-agent delegation. Learning extraction and file management are performed inline.
+
 # Learning Capture -- Extract and Store Development Insights
 
 Capture learnings from completed development sessions. Can be invoked manually after finishing work, automatically by board-pickup after PR merge, or with a specific issue number for targeted reflection.
@@ -41,9 +47,9 @@ Execute these steps in order. **Do not skip any step.** Ask the user at every ch
 
 ### Step 3: Write Learning Files
 
-For each confirmed learning, create a file in `/.agents/learnings/`.
+For each confirmed learning, create a file in `.agents/learnings/`.
 
-If `/.agents/learnings/` does not exist, create it.
+If `.agents/learnings/` does not exist, create it.
 
 **Filename:** `{YYYY-MM-DD}_{short-slug}.md`
 
@@ -89,8 +95,8 @@ Present all saved learnings with file paths.
 
 ```
 Learnings Captured:
-  /.agents/learnings/{filename1}.md -- {category}: {one-line summary}
-  /.agents/learnings/{filename2}.md -- {category}: {one-line summary}
+  .agents/learnings/{filename1}.md -- {category}: {one-line summary}
+  .agents/learnings/{filename2}.md -- {category}: {one-line summary}
 ```
 
 Remind user that these will be auto-consulted during future board-pickup and board-fill runs.
@@ -129,7 +135,7 @@ superseded_by: {learning-id}    # reference when deprecated
 
 ### Archival
 
-Archived learnings are moved to `/.agents/learnings/archived/` with their original filename. An archival notice is prepended:
+Archived learnings are moved to `.agents/learnings/archived/` with their original filename. An archival notice is prepended:
 
 ```markdown
 > **Archived on {date}**: {reason — expired | deprecated | superseded by {id}}
@@ -155,7 +161,7 @@ Archived learnings are moved to `/.agents/learnings/archived/` with their origin
 ```
 Learnings matching "{query}":
   [{confidence}] {title} ({date}, tags: {tags})
-    /.agents/learnings/{filename}.md
+    .agents/learnings/{filename}.md
     Applies when: {trigger summary}
 ```
 
@@ -197,8 +203,8 @@ When writing learning files, validate:
 
 ## Error Handling
 
-- `/.agents/learnings/` directory doesn't exist: create it silently.
-- `/.agents/learnings/archived/` directory doesn't exist: create it when first archival occurs.
+- `.agents/learnings/` directory doesn't exist: create it silently.
+- `.agents/learnings/archived/` directory doesn't exist: create it when first archival occurs.
 - Duplicate learning detected: warn and **ASK** whether to merge or create separate.
 - No learnings identified: **ASK** user directly what they learned. If still nothing, skip silently.
 - Learning exceeds quality thresholds: warn user with specific violations and suggest fixes.
@@ -211,7 +217,7 @@ When writing learning files, validate:
 - **Never delete learnings.** Use archival (move to `archived/`) instead of deletion.
 - **Learnings must be specific and actionable.** Reject generic advice like "write better tests."
 - **Always include trigger conditions** in the "Applies When" section.
-- **Tags must match project vocabulary** -- use area labels from `/.agents/hatch.json`.
+- **Tags must match project vocabulary** -- use area labels from `.agents/hatch.json`.
 - **Max ~20 lines per learning** file body (excluding frontmatter).
 - **Learnings without evidence must be `hypothesis`.** Do not allow `proven` or `experimental` without evidence.
 - **Expired learnings are archived, not deleted.** Preserve institutional knowledge.

package/commands/hatch3r-migration-plan.md

@@ -2,50 +2,350 @@
 id: hatch3r-migration-plan
 type: command
 description: Create a phased migration plan for a major dependency or framework upgrade. Analyzes breaking changes and produces an actionable plan with rollback procedures.
+tags: [planning, brownfield]
 ---
-# Migration Plan Generator
 
-## Inputs
+## Agent Pipeline
 
-- **Migration target:** dependency name and target version, or framework/platform change description
-- **Current version:** auto-detected from lockfile or specified manually
-- **Scope:** `full` (default) or `assessment-only` (just the analysis, no plan)
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Research | `hatch3r-researcher` (2 parallel: dependency-analysis, breaking-changes) | Yes | Yes |
+| 2. Impact Analysis | `hatch3r-architect` | No | Yes |
+| 3. Plan Generation | `hatch3r-docs-writer` | No | Yes |
 
-## Procedure
+# Migration Plan — Dependency or Framework Upgrade from Assessment to Phased Execution
 
-1. **Detect current state:**
-   - Read `package.json`, lockfile, or equivalent for current version
-   - Identify all direct and transitive dependents of the migration target
-   - Count usage sites in the codebase (imports, API calls)
+Take a dependency or framework upgrade target and produce a complete migration plan (`docs/migrations/`), rollback procedures for each phase, and structured `todo.md` entries ready for `hatch3r-board-fill`. Spawns parallel researcher sub-agents (dependency changelog analysis, breaking change inventory) followed by an architect for codebase impact mapping, then a docs-writer for plan generation. AI proposes all outputs; user confirms before any files are written. Optionally chains into `hatch3r-board-fill` to create GitHub issues immediately.
 
-2. **Research breaking changes:**
-   - Read the changelog/release notes between current and target versions
-   - Use web research for migration guides, known issues, and community solutions
-   - Identify deprecated APIs, removed features, and behavioral changes
+---
+
+## Shared Context
+
+**Read the `hatch3r-board-shared` command at the start of the run** if it exists. While this command does not perform board operations directly, it establishes patterns and context (GitHub owner/repo, tooling directives) that downstream commands like `hatch3r-board-fill` rely on. Cache any values found.
+
+## Token-Saving Directives
+
+1. **Do not re-read files already cached.** Once researcher outputs are collected, reference them in memory — do not re-invoke sub-agents.
+2. **Limit changelog reads.** When reading changelogs spanning many versions, extract only breaking changes and deprecations — skip patch-level entries unless security-relevant.
+3. **Structured output only.** All sub-agent prompts require structured markdown output — no prose dumps.
+4. **Batch file scanning.** When mapping breaking changes to codebase files, use targeted grep/glob patterns rather than reading entire file trees.
+
+---
+
+## Workflow
+
+Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
+
+### Step 1: Gather Migration Target
+
+1. **ASK:** "Tell me about the migration you're planning. I need:
+   - **Dependency / framework name** (e.g., `react`, `prisma`, `next`, `typescript`)
+   - **Target version** (e.g., `v19`, `^6.0.0`, `latest`)
+   - **Motivation** (why now? — end-of-life, security, new feature needed, performance, ecosystem pressure)
+   - **Known constraints** (timeline, downstream consumers, deployment windows, feature freezes)
+
+   I'll auto-detect the current version from your lockfile. If this is a framework migration (e.g., CRA → Vite, Express → Fastify), describe the source and target instead of versions."
+
+2. Auto-detect the current version from `package.json`, lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`), `Cargo.toml`, `go.mod`, `pyproject.toml`, or equivalent. Identify the package manager and count direct/transitive dependents.
+
+3. Present a structured summary:
+
+```
+Migration Brief:
+  Target:          {dependency}  {current} → {target}
+  Package Manager: {npm/yarn/pnpm/cargo/go/pip}
+  Motivation:      {user-provided reason}
+  Constraints:     {list}
+  Direct Dependents: {N} packages depend on this
+  Usage Sites:       {N} imports / API call sites in codebase
+  Version Gap:       {N} major versions / {M} minor versions
+```
+
+**ASK:** "Does this capture the migration correctly? Adjust anything before I proceed to analysis."
+
+#### Step 1b: Dimension Probing
+
+After the migration brief is confirmed, probe for missing context. Analyze the brief for unstated assumptions and generate 4–8 targeted questions from the most relevant dimensions:
+   - **Data migrations**: Does the upgrade require database schema changes, data transformations, or format conversions?
+   - **Feature flags**: Should the migration be gated behind feature flags for gradual rollout?
+   - **Backward compatibility**: Must the old and new versions coexist during transition (e.g., dual-write, adapter pattern)?
+   - **Downstream consumers**: Are there other services, packages, or teams consuming APIs that will change?
+   - **CI/CD impact**: Will build tooling, test runners, or deployment pipelines need updates?
+   - **Runtime environment**: Does the target version require a newer Node.js, Python, Go, or OS version?
+   - **Bundle/binary size**: Are there known size regressions in the target version?
+   - **Type system**: Does the upgrade introduce stricter types or remove type exports?
+
+Skip dimensions that the migration brief already addresses clearly.
+
+**ASK:** "Before research begins, I have {N} questions to ensure we don't miss anything:
+{numbered question list — each with the dimension label and why the answer matters}
+
+Answer these now, or say 'use defaults' for any where you're comfortable with a reasonable default."
+
+Record the user's answers as **Resolved Requirements** (passed to researchers and architect). For defaults, note the assumed value explicitly.
+
+---
+
+### Step 2: Research Phase — Spawn Parallel Researcher Sub-Agents
+
+Spawn two sub-agents concurrently, each following the **hatch3r-researcher agent protocol**. Each receives the confirmed migration brief, the Resolved Requirements from Step 1b, and uses depth level `deep`.
+
+| Sub-Agent | Focus | Output |
+|-----------|-------|--------|
+| 1. Dependency Analysis | Changelog between current → target, deprecated APIs, removed exports, new required config, peer dependency changes, transitive dependency conflicts | Structured breaking change inventory with severity tags |
+| 2. Breaking Changes & Community | Community migration guides, known issues, common pitfalls, workarounds, codemods available, official migration tools | Curated list of migration resources with applicability assessment |
+
+**Each sub-agent uses the project's tooling hierarchy:** project docs first, then codebase exploration, then Context7 MCP for library documentation, then web research for community guides.
+
+If the version gap spans multiple major versions (e.g., v2 → v5), instruct the dependency-analysis researcher to produce a per-major-version breakdown, noting which changes compound or are superseded.
+
+Wait for both sub-agents to complete before proceeding.
+
+---
+
+### Step 3: Impact Analysis — Spawn Architect
+
+Spawn the **hatch3r-architect** agent with the combined researcher outputs. The architect maps each breaking change to the actual codebase.
+
+**Architect receives:** the breaking change inventory, community migration resources, Resolved Requirements from Step 1b, and full codebase context (file tree, import graph for the target dependency).
+
+**Architect produces:**
+
+| Output | Description |
+|--------|-------------|
+| **Breaking Change Map** | Each breaking change → list of affected files, line ranges, and code patterns that must change |
+| **Severity Classification** | Each change classified: `trivial` (find-replace / codemod), `moderate` (logic rewrite), `significant` (architectural rework) |
+| **Effort Estimates** | Hours per change, with confidence level (high/medium/low based on how well the change is understood) |
+| **Risk Register** | Data-loss risks, security implications, performance regressions, behavioral changes that tests may not catch |
+| **Codemod Candidates** | Changes amenable to automated codemods — AST transforms, regex replacements, or official migration tools |
+
+Wait for the architect to complete before proceeding.
+
+---
+
+### Step 4: Synthesize & Review Analysis
+
+1. Present a **merged summary** combining findings from all agents:
+
+```
+Migration Analysis:
+
+  Target:              {dependency}  {current} → {target}
+  Breaking Changes:    {N} total ({X} trivial, {Y} moderate, {Z} significant)
+  Affected Files:      {N} files across {M} modules
+  Codemod Candidates:  {N} changes automatable
+  Estimated Effort:    {total hours} ({confidence})
+  Risks:               {N} risks ({X} high, {Y} medium, {Z} low)
+  Data-Loss Risk:      {yes/no — details if yes}
+  Coexistence Required:{yes/no — dual-version period needed}
+  Peer Dep Conflicts:  {N} ({list if any})
+```
+
+2. **Highlight high-severity items** — any `significant` breaking change, data-loss risk, or change without a clear migration path.
+
+3. If the version gap spans multiple major versions, recommend incremental vs. direct migration with trade-offs for each.
+
+**ASK:** "Here is the migration analysis. High-severity items are highlighted above. Options:
+- **Confirm** to proceed with phased plan generation
+- **Adjust** specific findings (tell me what to change)
+- **Re-run** a specific researcher or the architect with updated parameters
+- **Descope** to target an intermediate version instead"
+
+---
+
+### Step 5: Generate Phased Migration Plan
+
+From the merged analysis, generate a phased migration plan. Present all content for review before writing any files.
+
+#### Migration Plan — `docs/migrations/{dependency}_{current}_to_{target}.md`
+
+```markdown
+# Migration Plan: {Dependency} {current} → {target}
+
+## Overview
+
+{2-3 sentence summary of the migration scope, motivation, and approach}
 
-3. **Impact analysis:**
-   - Map each breaking change to affected files in the codebase
-   - Classify impact: `trivial` (find-replace), `moderate` (logic change), `significant` (architectural change)
-   - Estimate effort per change (hours)
-   - Identify risk areas (data loss potential, security implications, performance impact)
+## Migration Summary
+
+| Metric | Value |
+|--------|-------|
+| Breaking changes | {N} |
+| Affected files | {N} |
+| Estimated effort | {hours} |
+| Recommended approach | {incremental / direct} |
+| Coexistence period | {yes/no — duration if yes} |
+| Rollback complexity | {low/medium/high} |
+
+## Phase 0: Preparation
+
+**Goal:** Create safety nets before any migration work begins.
+
+| # | Task | Files | Effort | Validation |
+|---|------|-------|--------|------------|
+| 0.1 | Add test coverage for migration-affected code paths | {files} | {hours} | All new tests pass |
+| 0.2 | Pin transitive dependencies to prevent drift | {files} | {hours} | Lockfile updated |
+| 0.3 | Create compatibility shims / adapter layer (if coexistence needed) | {files} | {hours} | Shims compile, existing tests pass |
+| 0.4 | Document current behavior for regression comparison | — | {hours} | Snapshot saved |
+
+**Rollback:** No codebase changes to roll back. Remove new tests only if abandoning migration entirely.
+
+## Phase 1: Non-Breaking Updates
+
+**Goal:** Apply changes that are backward-compatible with the current version.
+
+| # | Task | Files | Effort | Validation |
+|---|------|-------|--------|------------|
+| 1.1 | Update configuration to support both versions | {files} | {hours} | Config valid for both versions |
+| 1.2 | Add new imports alongside deprecated ones | {files} | {hours} | No runtime changes |
+| 1.3 | Run available codemods for trivial changes | {files} | {hours} | Codemod output reviewed, tests pass |
+
+**Rollback:** `git revert` the Phase 1 commits. No data or state changes to undo.
+
+## Phase 2: Migrate Consumers
+
+**Goal:** Update application code to use new APIs, patterns, and behaviors.
+
+| # | Task | Breaking Change | Severity | Files | Effort | Validation |
+|---|------|----------------|----------|-------|--------|------------|
+| 2.1 | {task description} | {breaking change ref} | {trivial/moderate/significant} | {files} | {hours} | {how to verify} |
+
+**Rollback:** Revert Phase 2 commits. If data migrations occurred, run reverse migration script `{script}`.
+
+## Phase 3: Cleanup
+
+**Goal:** Remove backward-compatibility code, old imports, shims, and dead dependencies.
+
+| # | Task | Files | Effort | Validation |
+|---|------|-------|--------|------------|
+| 3.1 | Remove compatibility shims | {files} | {hours} | No references to shim modules |
+| 3.2 | Remove old dependency version from lockfile | {files} | {hours} | Only target version remains |
+| 3.3 | Remove deprecated API usage suppressions | {files} | {hours} | No suppression comments remain |
+| 3.4 | Update documentation and READMEs | {files} | {hours} | Docs reflect new version |
+
+**Rollback:** Re-add shims from Phase 0 if a late regression surfaces.
+
+## Risk Register
+
+| Risk | Severity | Phase | Mitigation | Detection |
+|------|----------|-------|------------|-----------|
+| {risk} | High/Med/Low | {phase} | {strategy} | {how to detect early} |
+
+## Validation Checklist
+
+- [ ] All existing tests pass after each phase
+- [ ] No new lint warnings or type errors
+- [ ] Performance benchmarks within {X}% of baseline
+- [ ] No runtime deprecation warnings or console errors
+- [ ] CI pipeline passes on migration branch
+- [ ] Manual smoke test of critical user flows
+
+---
+
+**Owner / Reviewers / Last updated**
+Owner: {tbd}
+Reviewers: {tbd}
+Last updated: {today's date}
+```
+
+**ASK:** "Here is the phased migration plan. Review the content before I write the file:
+- `{dependency}_{current}_to_{target}.md` — {phase count} phases, {task count} tasks, {risk count} risks
+
+Confirm, or tell me what to adjust."
+
+---
+
+### Step 6: Generate todo.md Entries
+
+From the phased migration plan, generate structured `todo.md` entries in the format that `hatch3r-board-fill` expects. One **epic-level entry** referencing the migration plan, followed by **one entry per phase**:
+
+```markdown
+- [ ] **Migrate {dependency} {current} → {target}**: {Migration overview with scope and effort summary}. Ref: docs/migrations/{dependency}_{current}_to_{target}.md.
+- [ ] **{dependency} migration Phase 0 — Preparation**: {Phase 0 task summary}. Ref: docs/migrations/{dependency}_{current}_to_{target}.md.
+- [ ] **{dependency} migration Phase 1 — Non-breaking updates**: {Phase 1 task summary}. Ref: docs/migrations/{dependency}_{current}_to_{target}.md.
+- [ ] **{dependency} migration Phase 2 — Migrate consumers**: {Phase 2 task summary with breaking change count}. Ref: docs/migrations/{dependency}_{current}_to_{target}.md.
+- [ ] **{dependency} migration Phase 3 — Cleanup**: {Phase 3 task summary}. Ref: docs/migrations/{dependency}_{current}_to_{target}.md.
+```
+
+#### Placement
+
+Determine the appropriate priority header based on the migration motivation. Security and EOL migrations default to P0; feature-driven migrations default to P1; ecosystem-pressure migrations default to P2.
+
+#### If `todo.md` Already Exists
+
+**ASK:** "todo.md already exists with {N} items. How should I add the migration entries?
+- **(a) Append** under the appropriate priority header
+- **(b) Merge** — deduplicate against existing items and reorganize
+- **(c) Show me the entries** and I'll place them manually"
+
+#### If `todo.md` Does Not Exist
+
+Create a new `todo.md` with the appropriate priority header and the new entries.
+
+Present the drafted entries for review.
+
+**ASK:** "Here are the todo.md entries for this migration ({N} items — 1 epic + {M} phase items). Review before I write:
+
+{entries}
+
+Confirm, or tell me what to adjust."
+
+---
+
+### Step 7: Write All Files
+
+After all content is confirmed:
+
+1. Write the migration plan to `docs/migrations/{dependency}_{current}_to_{target}.md`. Create the directory if needed.
+2. Write or update `todo.md` at the project root.
+3. Present a summary:
+
+```
+Files Created/Updated:
+  docs/migrations/
+    {dependency}_{current}_to_{target}.md  — {phase count} phases, {task count} tasks
+  todo.md                                   — {N} entries added (1 epic + {M} phases)
+```
+
+---
+
+### Step 8 (Optional): Chain into Board-Fill
+
+**ASK:** "All files written. Run `hatch3r-board-fill` to create GitHub issues from the new todo.md entries? (yes / not now)"
+
+If yes, instruct the user to invoke the `hatch3r-board-fill` command. Board-fill will perform its own deduplication, grouping, and readiness assessment.
+
+---
 
-4. **Generate phased plan:**
-   - Phase 0: Preparation (add compatibility shims, increase test coverage on affected areas)
-   - Phase 1: Non-breaking updates (update config, add new imports alongside old)
-   - Phase 2: Migrate consumers (update code to use new APIs)
-   - Phase 3: Remove old code (delete shims, deprecated usage, old dependencies)
-   - Each phase includes: files to change, validation criteria, rollback steps
+## Error Handling
 
-5. **Output the plan** as a markdown document or GitHub issue(s).
+- **No changelog available:** Fall back to git diff of the source repository between version tags. If unavailable, rely on community migration guide researcher output only and warn the user that the breaking change inventory may be incomplete.
+- **Breaking changes unmappable to codebase:** Flag as a **runtime risk** in the risk register with detection strategy (test, monitoring, canary) when a breaking change has no API signature difference to grep for.
+- **Version gap too large:** If the migration spans 3+ major versions, recommend incremental migration (one major at a time) and generate a plan for the first hop only. ASK whether to plan just the first hop or attempt the full jump.
+- **Sub-agent failure:** Retry once. If it fails again, present partial results and ask the user how to proceed (continue with partial analysis / provide missing information manually / abort).
+- **Conflicting researcher outputs:** Present both sides with trade-offs. Ask the user to decide. Do not silently pick one.
+- **File write failure:** Report the error and provide full file content so the user can create the file manually.
+- **Missing project context:** Proceed without board context — this command does not require board configuration.
+- **Peer dependency conflicts:** Enumerate conflicts in the analysis and include resolution tasks in Phase 0.
+- **No codebase usage found:** Warn that the dependency may be transitive-only and adjust the plan scope accordingly.
 
-## Output
+## Guardrails
 
-- Migration assessment with breaking change inventory
-- Phased migration plan with effort estimates
-- Rollback procedure for each phase
-- Checklist of validation steps
+- **Never auto-execute migration steps.** This command produces a plan — it never runs install, upgrade, or codemod commands.
+- **Never skip ASK checkpoints.** Every step with an ASK must pause for user confirmation.
+- **Never write files without user review and confirmation.** All generated content is presented first.
+- **Preserve rollback ability at each phase.** Every phase must include a rollback procedure. If a phase cannot be rolled back (e.g., irreversible data migration), flag it with **⚠ IRREVERSIBLE** and require explicit user acknowledgment.
+- **Flag data-loss risks prominently.** Any data-loss risk must appear in the risk register with `High` severity and a dedicated mitigation strategy.
+- **Always delegate research to the hatch3r-researcher agent protocol.** Researcher sub-agents handle Context7 MCP, web research, and the tooling hierarchy internally.
+- **Respect the project's tooling hierarchy:** project docs → codebase exploration → Context7 MCP → web research.
+- **todo.md must be compatible with board-fill format** — markdown checklist with bold titles, grouped by priority, referencing source specs.
+- **Preserve existing todo.md content.** Never overwrite or reorganize existing items without explicit user approval.
+- **Scope to the declared target.** Do not opportunistically upgrade other dependencies. Flag sibling upgrades as follow-up recommendations.
 
 ## Related
 
-- **Skill:** `hatch3r-migration` — execution workflow for the plan
-- **Skill:** `hatch3r-dep-audit` — dependency health check
+- **Command:** `hatch3r-dep-audit` — dependency health check; run before migration planning
+- **Command:** `hatch3r-refactor-plan` — structural refactoring that accompanies a migration
+- **Command:** `hatch3r-board-fill` — create GitHub issues from generated todo.md entries
+- **Command:** `hatch3r-feature-plan` — plan features that depend on the migration target's new capabilities
+- **Skill:** `hatch3r-refactor` — execution workflow for migration phases involving code restructuring