Migration Guild

Inspiration

Legacy modernization projects fail when teams jump directly from intent to rewrite. They skip the mapping phase, miss hidden dependencies, and ship broken migrations. I wanted to build a system that makes the safer path the default — where agents can't proceed without evidence, and every decision is auditable.

What it does

Migration Guild is a multi-agent system that collaborates through a shared registry to safely modernize legacy code. Eight specialized agents (inventory, planner, analyzer, test-writer, codegen, reviewer, remediation, orchestrator) coordinate atomically — claiming tasks, recording evidence, and gating progress through explicit state transitions.

The system enforces an evidence-gated workflow:

1. Map evidence first — scan dependencies, entry points, routes, persistence
2. Block planning until evidence is reviewed and approved
3. Migrate bounded slices with parallel workers that don't step on each other
4. Review with full audit trails — every run records prompts, inputs, outputs, and status

How I built it

• Registry-backed coordination: SQLite registry tracks all artifact state with atomic claims, wave planning, and parallel execution
• Provider-neutral runtime: OpenAI-compatible API contract — works with Qwen, local models, LiteLLM, OpenRouter, or hosted providers through named profiles
• Evidence-gated runtime: Blocks planning and execution until required evidence is collected and reviewed
• Prompt packs: Version-controlled migration instructions per phase, portable across Java, Python, and other legacy stacks
• Run ledgers: Every material run is recorded with config snapshots, prompts, evidence, and outputs for reproducibility

The architecture separates the kit repository from migration workspaces. Each workspace has its own .guild/config.yaml, evidence directory, and run ledgers. The guildctl CLI orchestrates the workflow with commands like inventory, plan, bootstrap, migrate --parallel 3, and review.

Challenges I faced

• Parallel coordination without conflicts: Multiple agents claiming the same artifact was a race condition. Solved with atomic registry claims and explicit status transitions (pending → planned → in-progress → migrated → reviewed).
• Provider neutrality vs. vendor lock-in: Wanted to support any OpenAI-compatible endpoint without coupling to a specific CLI. Built harness adapters (opencode, codex) behind a stable contract: <harness> --agent <persona> --model <model> --yolo -p <prompt>.
• Evidence gating without blocking progress: How do you require evidence before planning without making the workflow tedious? Made evidence collection a first-class phase with its own prompts and outputs, then enforced gates at the registry level.
• Auditability without overhead: Every run needed to be reproducible and reviewable. Built run ledgers that capture config snapshots, prompts, evidence, and outputs — so you can answer "what did the runtime see?" and "what is safe to do next?"

What I learned

Legacy modernization isn't a code translation problem — it's an evidence-collection problem. Agents are only as good as the context they're given. By forcing explicit mapping before intent, Migration Guild makes migrations safer, reviewable, and recoverable. The multi-agent society pattern (orchestrator + specialized workers + shared registry) scales better than monolithic agent loops for complex, multi-phase workflows.

Vision

The north star for Migration Guild is turning legacy applications into agent-compatible applications.

Today's legacy systems weren't built for AI agents. They have hidden state, implicit workflows, tangled dependencies, and interfaces designed for humans — not tools. You can't drop an autonomous agent into a 15-year-old Java monolith and expect it to operate safely.

Migration Guild's evidence-first approach solves the first half of that problem: it maps what exists before anything changes. But the migration target isn't just "modern framework" — it's agent-ready architecture. That means:

• Explicit state surfaces — agents can query what's happening without guessing
• Structured interfaces — tool-friendly contracts instead of screen-scraping or brittle integrations
• Bounded, auditable operations — every action has evidence, every decision is reviewable
• Provider-neutral runtimes — agents aren't locked to one model or vendor

The end state: a legacy app goes in, and what comes out isn't just "rewritten in Spring Boot" — it's an application that agents can autonomously operate, extend, and maintain. The migration itself becomes the onboarding process for AI agents into enterprise systems.

This is why the evidence-gated workflow matters. You can't make an app agent-compatible if you don't first understand what it does. Map evidence → plan from evidence → migrate to agent-ready targets. That's the pipeline.

Built With

• codex
• node.js
• openai-compatible-api
• opencode
• react
• sqlite
• typescript