Meta Agent Tools
PT

Back to the catalog

brownfield-code-surgeon

AI coding assistants are more helpful in greenfield development than for modifying brownfield code — large, undertested, poorly-maintained s

Open source Repository Open in the app JSON README (API)

About

AI coding assistants are more helpful in greenfield development than for modifying brownfield code — large, undertested, poorly-maintained systems that make up the majority of professional programming. This workflow follows Michael Feathers' workflow from 2002, applied in the context of agentic coding. This is the Claude Code plugin that delivers the [seven-phase brownfield surgery](https://zenodo.org/records/19640171) workflow as slash commands, subagents, and phase-aware hooks. This workflow is already published as a paper Zenodo titled [Agentic Code Surgery for Brownfield Systems](https://zenodo.org/records/19640171) by the author of this plugin.

Details

Kind
Plugins
Topic
No topic detected
Publisher
vivganes
Origin
marketplace
Category
ferramentas
Forks
1
Last push
2026-04-27T00:04:20Z
Repository state
ativo
Language
TypeScript
License
MIT
Added
2026-08-30 01:48:58
Updated
2026-08-30 01:48:58
Origin id
vivganes/brownfield-code-surgeon/brownfield-code-surgeon

README

# Brownfield Code Surgeon

A package of tools that productionize the **seven-agent brownfield code-surgery workflow** — Plan, Map, Break, Cover, Implement, Refactor, Finish — from:

> Ganesan, Vivek, Kamal Raj Sekar, and Kiran Kashyap. '*Agentic Code Surgery for Brownfield Systems*'. Zenodo, 18 April 2026. https://doi.org/10.5281/zenodo.19640171 

Author of this package is the original author of the paper mentioned above.

## Screenshot

![Screenshot of the Operation theatre UI with animated cat as patient](./screenshot.png)

## Motivation

AI coding assistants are more helpful in greenfield development than for modifying brownfield code — large, undertested, poorly-maintained systems that make up the majority of professional programming.

This package aims to change that.  This package `brownfield-code-surgeon` will enable easily working with brownfield repositories using Claude code.

## One backbone, three user interface choices

All interfaces read and write the same artifacts and emit the same events.

| User Interface | Package | Purpose | Usage Guide |
|---|---|---|---|
| Claude Code plugin | `packages/plugin` | Native subagents + slash commands + forbidden-moves hooks.  | Refer the plugin's [README.md](packages/plugin/README.md) |
| CLI based SDK runner (with optional Claude managed runner for final phase) | `packages/sdk-runner` | Local Node CLI driving the pipeline via the Claude Agent SDK.  Optionally hands-off the final phase to Claude managed runners | Refer the runner's [README.md](packages/sdk-runner/README.md) |
| Operating-theater web UI | `packages/ui` | Vitals, seams graph, phase timeline, approval controls | Refer the UI's [README.md](packages/ui/README.md) |

Shared contracts live in `packages/shared`; the source-of-truth agent prompts live in `packages/core-prompts`.

## Setup

### Environment Variables (Needed only if you use Claude Managed Runners)

Copy `.env.example` to `.env.local` and configure your credentials:

```bash
cp .env.example .env.local
```

Then edit `.env.local` with your API keys:

```env
# Required: Anthropic API key
SURGERY_ANTHROPIC_API_KEY=sk-your-key-here

# Optional: GitHub token (can also be configured via UI)
SURGERY_GIT_TOKEN=ghp_...

# Optional: Managed-Agents environment ID (can also be configured via UI)
ANTHROPIC_AGENT_ENV_ID=env_...
```

The `.env.local` file is git-ignored and will not be committed.

## What if I want to experience the UI without actually running a code surgery?

There is a toy-test mode.  This sets up a toy repo for you and simulates running all the phases.  This could be the best way to experience the system in under 2-3 seconds.

Run the following commands:

```
npm install
cd packages/ui
npm install
npm run toy-test:auto-approve
```

## Evidence of Effectiveness of this Workflow

The evidence of effectiveness can be seen by comparing pull requests [#33 - Regular Plan + Implement Approach](https://github.com/vivganes/kanbanstr/pull/33) and [#34 - Brownfield Surgery Claude Code Plugin](https://github.com/vivganes/kanbanstr/pull/34) of the [Kanbanstr](https://github.com/vivganes/kanbanstr) repo.

Our workflow increased the coverage from 0.82% to 19.24% of lines, while implementing the same feature.

This would mean:
 - Less manual testing effort after the agent finishes
 - Provably correct implementation
 - Prevention of regression in the covered lines of code by anyone in the future
  
## Continuous Integration

CI using Github Actions is enabled in this repository so that we maintain the quality continuously.

## License

MIT. See [LICENSE](./LICENSE).

More