# Brownfield Code Surgeon

- **Event:** [Built with Opus 4.7: a Claude Code hackathon](https://cerebralvalley.ai/e/built-with-4-7-hackathon)
- **When:** Apr 21 at 12:00 PM – Apr 27 at 2:00 AM (EDT)
- **Where:** Online
- **Team:** [Vivek Ganesan](https://cerebralvalley.ai/u/vivganes)
- **GitHub:** https://github.com/vivganes/brownfield-code-surgeon
- **Demo video:** https://www.youtube.com/watch?v=ypbRUI6m5jc
- **Gallery:** https://cerebralvalley.ai/e/built-with-4-7-hackathon/hackathon/gallery
- **Page:** https://cerebralvalley.ai/e/built-with-4-7-hackathon/hackathon/gallery/50

# 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.

---

Markdown version of https://cerebralvalley.ai/e/built-with-4-7-hackathon/hackathon/gallery/50. Site index for agents: https://cerebralvalley.ai/llms.txt · full text: https://cerebralvalley.ai/llms-full.txt