By vivganes
A safety-first, seven-phase brownfield workflow for Claude Code. Seven expert subagents (Plan, Map, Break, Cover, Implement, Refactor, Finish) with phase-aware forbidden-move enforcement via hooks.
Step 3 of 7 — Break: break dependencies to enable testing.
Step 4 of 7 — Cover: write characterization tests for existing behavior.
Step 7 of 7 — Finish: update docs, changelog, and produce a PR-ready summary.
Step 5 of 7 — Implement: add the new behavior with TDD.
Step 2 of 7 — Map: find seams, test points, and dependencies.
Plan phase of brownfield surgery: understand the requested change and write plan/plan.md. Does not modify source.
Map phase: identify seams, test points, and dependencies; write plan/seams-and-dependencies.md.
Break phase: break dependencies to enable testing. No new features, no new tests.
Cover phase: write characterization / pinning tests for existing behavior. Tests only, no source edits.
Implement phase: add the new behavior using TDD. Production code and tests both welcome.
Executes bash commands
Hook triggers when Bash tool is used
Modifies files
Hook triggers on file write and edit operations
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimBased on adoption, maintenance, documentation, and repository signals. Not a security audit or endorsement.
Uses power tools
Uses Bash, Write, or Edit tools
Uses power tools
Uses Bash, Write, or Edit tools
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.

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.
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 |
| 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 |
| Operating-theater web UI | packages/ui | Vitals, seams graph, phase timeline, approval controls | Refer the UI's README.md |
Shared contracts live in packages/shared; the source-of-truth agent prompts live in packages/core-prompts.
Copy .env.example to .env.local and configure your credentials:
cp .env.example .env.local
Then edit .env.local with your API keys:
# 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.
The evidence of effectiveness can be seen by comparing pull requests #33 - Regular Plan + Implement Approach and #34 - Brownfield Surgery Claude Code Plugin of the Kanbanstr repo.
Our workflow increased the coverage from 0.82% to 19.24% of lines, while implementing the same feature.
This would mean:
CI using Github Actions is enabled in this repository so that we maintain the quality continuously.
MIT. See LICENSE.
npx claudepluginhub vivganes/brownfield-code-surgeon --plugin brownfield-code-surgeonHarness-native ECC operator layer - 67 agents, 271 skills, 92 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses
Comprehensive feature development workflow with specialized agents for codebase exploration, architecture design, and quality review
Superpowers Plus core skills library for Claude Code: planning, execution routing, TDD, debugging, and collaboration workflows
Tools to maintain and improve CLAUDE.md files - audit quality, capture session learnings, and keep project memory current.
Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification
Comprehensive C4 architecture documentation workflow with bottom-up code analysis, component synthesis, container mapping, and context diagram generation