System Prompt Architecture for a Code Migration Agent

Background

A developer productivity company has built a code migration agent that helps engineering teams upgrade legacy codebases — converting deprecated APIs, updating dependency versions, and restructuring modules to match new conventions. The agent uses a frontier model and runs multi-step tasks that typically take 20-40 minutes.

The team's engineering lead has flagged two persistent problems. First, the agent behaves inconsistently: on some runs it asks users before touching certain file types, on others it just proceeds without permission. On some runs it produces clean, idiomatic code in the target style; on others it reverts to old patterns mid-session. Second, the current system prompt was written incrementally over several months — it's now a wall of prose with contradictions and redundant instructions that no one fully understands. The evaluator component's prompt is a two-sentence afterthought.

Before re-engineering the agent, the team wants to establish a clean, principled system prompt architecture. Your task is to design the complete prompt architecture for this agent — both the main agent prompt and the evaluator prompt — and provide the actual prompt text (not just a description of what it should contain).

Output Specification

Produce the following files:

1. system-prompt.md — The full system prompt for the code migration agent. This should be the actual prompt text, ready to be used, not a planning document.

2. evaluator-prompt.md — The full system prompt for the evaluator component that assesses the migration quality after the agent produces its output.

3. prompt-architecture.md — A concise explanation of the structural decisions made in the two prompts: how permissions are organized, how guidance is triggered, what is specified explicitly vs. left implicit, and how reasoning budget is handled.

The prompts should be detailed enough to serve as a real starting point for the engineering team.