AI can do the heavy lifting here, but a senior engineer needs to own the design decisions.

This is a one-off architectural refactor of a specific codebase with its own history, conventions, and user expectations. The judgment calls — which flags to unify, how to structure middleware, what error messages to write — are unique to this project every time.

Success criteria are vague: 'consistent middleware pattern,' 'clear error text,' and '10 key workflows' are all undefined. An agent cannot reliably know when it's done without human sign-off on each design decision.

If the agent has full read/write access to the codebase and can run tests, the mechanical parts are executable. However, it lacks access to user feedback, issue trackers, or v1 usage telemetry that would inform which workflows matter most.

A botched refactor can introduce subtle regressions across 25 subcommands, break existing user scripts, or produce a misleading migration guide that causes real upgrade failures. Reversibility depends on version control discipline, but the cost of a bad output is high.

Choosing a middleware pattern, deciding what constitutes a 'breaking change' for v2, and writing error messages that feel right to real users all require taste and domain knowledge. The migration guide especially needs someone who understands what v1 users actually depended on.