{
  "markdown": "# Brownfield Code Surgeon\n\nA package of tools that productionize the **seven-agent brownfield code-surgery workflow** — Plan, Map, Break, Cover, Implement, Refactor, Finish — from:\n\n> 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 \n\nAuthor of this package is the original author of the paper mentioned above.\n\n## Screenshot\n\n![Screenshot of the Operation theatre UI with animated cat as patient](./screenshot.png)\n\n## Motivation\n\nAI 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.\n\nThis package aims to change that.  This package `brownfield-code-surgeon` will enable easily working with brownfield repositories using Claude code.\n\n## One backbone, three user interface choices\n\nAll interfaces read and write the same artifacts and emit the same events.\n\n| User Interface | Package | Purpose | Usage Guide |\n|---|---|---|---|\n| Claude Code plugin | `packages/plugin` | Native subagents + slash commands + forbidden-moves hooks.  | Refer the plugin's [README.md](packages/plugin/README.md) |\n| 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) |\n| Operating-theater web UI | `packages/ui` | Vitals, seams graph, phase timeline, approval controls | Refer the UI's [README.md](packages/ui/README.md) |\n\nShared contracts live in `packages/shared`; the source-of-truth agent prompts live in `packages/core-prompts`.\n\n## Setup\n\n### Environment Variables (Needed only if you use Claude Managed Runners)\n\nCopy `.env.example` to `.env.local` and configure your credentials:\n\n```bash\ncp .env.example .env.local\n```\n\nThen edit `.env.local` with your API keys:\n\n```env\n# Required: Anthropic API key\nSURGERY_ANTHROPIC_API_KEY=sk-your-key-here\n\n# Optional: GitHub token (can also be configured via UI)\nSURGERY_GIT_TOKEN=ghp_...\n\n# Optional: Managed-Agents environment ID (can also be configured via UI)\nANTHROPIC_AGENT_ENV_ID=env_...\n```\n\nThe `.env.local` file is git-ignored and will not be committed.\n\n## What if I want to experience the UI without actually running a code surgery?\n\nThere 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.\n\nRun the following commands:\n\n```\nnpm install\ncd packages/ui\nnpm install\nnpm run toy-test:auto-approve\n```\n\n## Evidence of Effectiveness of this Workflow\n\nThe 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.\n\nOur workflow increased the coverage from 0.82% to 19.24% of lines, while implementing the same feature.\n\nThis would mean:\n - Less manual testing effort after the agent finishes\n - Provably correct implementation\n - Prevention of regression in the covered lines of code by anyone in the future\n  \n## Continuous Integration\n\nCI using Github Actions is enabled in this repository so that we maintain the quality continuously.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n",
  "bytes": 3594,
  "sha": "c8365891da4bc05a4c75ca67f8610f91ecc11fd78dacf65f33c1528d7190f167",
  "repo_slug": "vivganes/brownfield-code-surgeon",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_vivganes_brownfield_code_surgeon_brownfi_3484e2f9/readme"
}