Gathering Migration 🌲🐻🐕
The drum echoes through the valleys. The conductor stands at the pass, orchestrating two very different strengths. The Bloodhound arrives first with fresh eyes — no assumptions about what's connected, just a nose for dependencies. Then the Bear wakes, receiving a map it didn't draw — no shortcuts, no "I already know where things are." Together they move mountains safely, each with isolated context, each trusting only what it verified itself.
When to Summon
- Complex migrations requiring codebase exploration before execution
- Moving between systems, libraries, or architectural patterns
- Schema changes affecting multiple relationships
- Component or API migrations spanning many files
- Icon, asset, or content migrations with downstream dependencies
- Any migration where you need to understand the territory before moving
IMPORTANT: This gathering is a conductor. It never scouts or migrates directly. It dispatches subagents — one per animal — each with isolated context and an intentional model. The conductor only manages handoffs and gate checks.
The Gathering
SUMMON → DISPATCH → GATE → DISPATCH → GATE → VERIFY
↓ ↓ ↓ ↓ ↓ ↓
Spec Bloodhound Check Bear Check Final
(self) (haiku) ✓ (opus) ✓ Verify
Animals Dispatched
| Order | Animal | Model | Role | Fresh Eyes? | | ----- | ------------- | ----- | --------------------------------- | --------------------------------------------------- | | 1 | 🐕 Bloodhound | haiku | Scout dependencies, map territory | Yes — sees only the migration spec | | 2 | 🐻 Bear | opus | Execute migration safely | Yes — sees only territory map, not scouting process |
Reference: Load references/conductor-dispatch.md for exact subagent prompts and handoff formats
Phase 1: SUMMON
The drum sounds. The valley listens...
The conductor receives the migration request and prepares the dispatch plan:
Clarify the Migration:
- What needs to migrate? (data, components, icons, config, conventions...)
- From where to where? (old pattern → new pattern)
- What downstream dependencies exist?
- What does "undo" look like if something goes wrong?
Determine the Bear's domain guide:
| Migration Type | Domain Guide |
| -------------------------------------- | ---------------------- |
| Database schema, tables, D1/SQLite | domain-database.md |
| Component props, API upgrades, imports | domain-components.md |
| Icons, assets, documents, file formats | domain-content.md |
| Config, conventions, dependencies | domain-general.md |
Confirm with the human, then proceed.
Output: Migration specification, domain guide identified, dispatch plan confirmed.
Phase 2: SCOUT (Bloodhound)
The conductor signals. The Bloodhound puts its nose to the ground...
Agent(bloodhound, model: haiku)
Input: migration specification only
Reads: bloodhound-scout/SKILL.md (MANDATORY)
Output: territory map
Dispatch a haiku subagent to scout the codebase. The Bloodhound receives ONLY the migration specification — no pre-analysis, no assumptions. It reads its own skill file and executes its full SCENT → TRACK → HUNT → REPORT → RETURN workflow.
What the Bloodhound maps:
- Every reference to the items being migrated
- Dependency relationships (what depends on what)
- Downstream consumers
- Edge cases and unusual usage patterns
- Current state counts (how many items, how many references)
Handoff to conductor: Territory map (affected files, dependency graph, edge cases, current state counts, risk assessment).
Gate check: Territory map has: file lists, dependency relationships, item counts, edge cases identified. If incomplete, resume Bloodhound with specific questions.
Phase 3: MIGRATE (Bear)
The Bear wakes. It receives a map it didn't draw...
Agent(bear, model: opus)
Input: migration spec + territory map (from Bloodhound)
Reads: bear-migrate/SKILL.md + references/{domain-guide} (MANDATORY)
Output: migration results + file list
Dispatch an opus subagent to execute the migration. The Bear receives the spec and the Bloodhound's territory map — NOT the Bloodhound's scouting process, just its structured output.
What the Bear does:
- Preserve original state (branch, backup, or snapshot)
- Execute migration in manageable chunks
- Validate after each chunk
- Verify item counts match (source vs destination)
- Run integrity checks (references resolve, imports work, no orphans)
Handoff to conductor: Migration results (items migrated, items skipped, validation reports), file list.
Gate check:
pnpm install
gw dev ci --affected --fail-fast --diagnose
Must compile and pass. If it fails, resume Bear with the error.
Phase 4: VERIFY
The journey ends. The conductor confirms safe arrival...
Validation Checklist:
- [ ] Bloodhound: All dependencies mapped
- [ ] Bloodhound: All references found
- [ ] Bloodhound: Edge cases documented
- [ ] Bear: Original state preserved (branch, backup, or snapshot)
- [ ] Bear: Item counts match (source vs destination)
- [ ] Bear: Integrity checks pass (references resolve, imports work, no orphans)
- [ ] Bear: Tests pass (
gw dev ci --affected) - [ ] Bear: Rollback path documented
Completion Report:
🌲 GATHERING MIGRATION COMPLETE
Migration: [Description]
DISPATCH LOG
🐕 Bloodhound (haiku) — [territory mapped, X files identified, Y dependencies found]
🐻 Bear (opus) — [Z items migrated, domain guide: {guide}]
GATE LOG
After Bloodhound: ✅ territory map complete
After Bear: ✅ compiles clean, migration verified
Final CI: ✅ gw dev ci --affected passes
MIGRATION RESULTS
Items migrated: [count]
Items skipped: [count, reason]
Item count match: ✅ [source] = [dest]
Integrity checks: ✅
Rollback: [branch/backup location]
Everything found its new home.
Conductor Rules
Never Do Animal Work
The conductor dispatches. It does not scout dependencies or execute migrations.
Fresh Eyes Are a Feature
The Bear receives the territory map, not the Bloodhound's scouting process. It trusts the map but verifies what it finds during migration.
Gate Every Transition
Territory map must be complete before Bear starts. CI must pass after Bear finishes.
Resume, Don't Restart
If a gate check fails, resume the failing agent. The Bear especially benefits from resumption — it has the migration context and can fix issues faster than starting fresh.
Anti-Patterns
The conductor does NOT:
- Scout the codebase itself
- Execute migration steps directly
- Let Bear start without a complete territory map
- Skip count validation (source must equal destination)
- Skip rollback documentation
Quick Decision Guide
| Migration Scope | Strategy | | ------------------------------------ | ---------------------------------------- | | Simple rename (< 5 files) | Bear only (no Bloodhound needed) | | Cross-cutting migration (5-50 files) | Standard: Bloodhound → Bear | | Large migration (50+ files) | Bloodhound → Bear with chunked execution | | Unknown scope ("migrate X") | Always start with Bloodhound |
When no single animal suffices, the gathering answers. 🌲🐾