Inspiration
Most cloud migrations aren't slowed down by code. They stall on everything around the code: the approvals no one knew were needed, the security review that shows up in week six, the runbook in someone's head, the rollback plan that was never written. Existing tools like AWS Transform and Microsoft's modernization agents are good at analyzing and converting legacy code. Then they hand you a plan and stop.
We wanted to automate the part that actually drowns teams: coordination. What if a migration were a pull request, with the plan, the approvals, and the rollback all versioned together, and an agent team that could carry it all the way to production and fix it when it broke?
What it does
MaC-aroni (Migration as Code) takes a request like migrate <service> to AWS and handles the rest:
- Understands the system. An ingestion agent reads Confluence docs, existing repos, and past Jira approvals, and builds a knowledge graph of the legacy service, its dependencies, data classification, and owners, along with the target landing-zone standards.
- Plans the migration as code. A planner agent writes a
migration.yamlDAG and iterates on it in a ReAct loop against ourmac validatechecker until it passes. - Raises the approvals. A compliance agent maps company policy to the approvals this migration needs and files real Jira tickets, each with a written justification and the design doc attached.
- Opens a PR. The whole migration lands as a pull request in a migrations repo, with branch protection, CODEOWNERS, and CI.
- Executes deterministically. Once merged and approved, a plain Python state machine runs the steps in order, waits at approval gates, and rolls back in reverse if anything fails. The LLM never touches deploy.
- Fixes what breaks. When a step fails, a diagnostician agent reads the run logs, reasons through the root cause, and opens a fix PR.
The short version: other tools propose a plan and stop. MaC raises the approvals, commits the pipeline, runs it with rollback, and fixes it when it breaks.
How we built it
- Agents: LangGraph orchestrating NVIDIA Nemotron through NIM / build.nvidia.com. We routed by task: Nemotron Nano for high-volume ingestion, Nemotron Super with reasoning on for planning, compliance, and diagnosis. NVIDIA embedding and reranking models handle retrieval. No non-NVIDIA models anywhere in the loop.
- Tool calling: Agents act only through tools (knowledge-graph queries, Jira, GitHub, the validator). They never shell out to Terraform or AWS directly.
- Knowledge graph: Stored as a JSON graph in the repo, with every entity carrying a
doc_urlback to its source so each agent decision is traceable. - Runner: Python + FastAPI. It validates the spec, checks approval status, runs
terraform plan, executes steps as a saga in topological order, and runs compensating rollbacks on failure. - Infra: Terraform against a real AWS sandbox, GitHub Actions for CI, Jira and Confluence as the systems of record.
- Traceability: Every agent emits
observation → reasoning → action → outcomewith the model's reasoning attached, so you can see exactly why each decision was made.
Challenges we ran into
- Scope. Our first design touched six external systems and was roughly twice what a weekend allows. We cut Neo4j for a JSON graph behind the same tool interface, let the GitHub PR and Jira board serve as the UI, and shrank the deploy target to a single small AWS resource. [confirm which cuts you made]
- Keeping the LLM out of the blast radius. Our early instinct was to let agents run the deployment. We drew a hard line instead: agents are slow and smart and write the spec; the runner is fast and dumb and executes it. Getting that boundary clean took several rewrites.
- Making agents converge. The planner's first drafts often failed validation. Feeding validator errors back into a ReAct loop is what made the plans reliable. [confirm, add how many iterations it typically takes]
- Integration setup. Atlassian, GitHub branch protection, AWS credentials, and NIM all had to be configured before any agent could do anything. [confirm, add your worst one]
What we learned
- The hard part of enterprise migration is organizational, not technical. Approvals and ownership are the real dependency graph.
- LLMs are best at planning, reviewing, and diagnosing. Execution belongs to something deterministic and auditable.
- A validator in the loop beats a better prompt. Giving the agent precise feedback made more difference than any prompt tweak.
- Model routing matters: using a small model for ingestion and a reasoning model for decisions kept the system fast without losing quality.
What's next for MaC-aroni
- A live DAG console showing each step, gate, and agent trace in real time.
- A reviewer agent that comments on migration PRs against internal standards.
- Simulation and evaluation runs that score agent plans against golden migrations before anything deploys.
- Support for multi-service migrations and cost estimates on every plan.
- More targets beyond AWS, and import of existing approval workflows from ServiceNow and similar tools.
