Brownfield Code Surgeon

# Brownfield Code Surgeon ## The Problem Statement AI coding assistants are great on greenfield projects but not-so-great on brownfield ones — the sprawling, undertested, half-documented codebases. Unfortunately, the brownfield code makes up most real software work. AI assistants tend to quietly break things nobody had tests for, in such old codebases. ## The Approach Brownfield Code Surgeon fixes that with a **seven-phase workflow** — Plan → Map → Break → Cover → Implement → Refactor → Finish. The roots go back to Michael Feathers' *[Working Effectively with Legacy Code](https://objectmentor.com/resources/articles/WorkingEffectivelyWithLegacyCode.pdf)* (2002) — seams, characterization tests, the whole vocabulary humans have used on legacy code for two decades. I, along with my colleagues, translated that workflow for agentic use in a [paper](https://doi.org/10.5281/zenodo.19640171) published April 2026. This repository submission is the paper's productionized form. Each phase has its own subagent, its own approval gate, and a set of forbidden moves the agent can't bypass. ## What's in the Submission? During the hackathon, I have created a Claude-code-focused package with one backbone, three ways to use it, all writing the same artifacts: - **Operating Theater UI** — Picture a live operating theater. A cute cat that represents your codebase is on the operating table, breathing, twitching, reacting in real time as Claude operates on your legacy codebase. Vitals tick across the monitor — coverage, seams, failing tests. Every incision the agent makes shows up on screen. That's the UI we have in our submission. - **Claude Code plugin** — slash command `/surgery`, one subagent per phase, hooks that block dangerous edits - **SDK runner** — a Node CLI that drives the same pipeline through the Claude Agent SDK - **Managed agents hand-off** — The Finish phase can hand off to **Claude Managed Agents** so long-running cleanup doesn't tie up your laptop. ## Why Opus 4.7? Opus 4.7's 1M context is doing real work here: a single subagent can hold an entire legacy module in view and find seams a human reviewer would skim past. The seven-phase split keeps every decision auditable. ## Proof It Works PR #33 vs PR #34 on `vivganes/kanbanstr` github repo — same brownfield task, with-surgeon vs without — tighter diffs, real coverage, no forbidden moves. Coverage improved from 0.82% to 19.24%. ## Licensing & CI Open source under MIT, 90% line coverage enforced in CI.