Anthropic recently published a Code Modernization Plugin for Claude Code: a structured workflow and set of specialist agents for modernizing legacy codebases. It targets COBOL, legacy Java/C++, and monolith web apps, and enforces a specific sequence: assess → map → extract-rules → reimagine → transform → harden.
The plugin's opening line could have been pulled straight from a SpecOps talk: "Legacy modernization fails most often not because the target technology is wrong, but because teams skip steps: they transform code before understanding it, reimagine architecture before extracting business rules, or ship without a harness that would catch behavior drift."
I couldn't agree more. And it turns out the two approaches complement each other remarkably well. The plugin provides the tactical execution toolkit, and SpecOps provides the governance framework that makes the output durable.
What the Plugin Does
The Code Modernization Plugin ships seven slash commands and five specialist agents:
/modernize-brief: Capture the modernization scope, constraints, and success criteria/modernize-assess: Inventory the legacy codebase with quantitative metrics and effort estimation/modernize-map: Map legacy structure onto a target architecture/modernize-extract-rules: Extract business rules into structured, testable rule cards/modernize-reimagine: Propose the target design/modernize-transform: Execute the code transformation module by module/modernize-harden: Post-transform security audit and test coverage review
The five agents (legacy-analyst, business-rules-extractor, architecture-critic, security-auditor, and test-engineer) are invoked from within those commands or directly. Each has a defined personality and adversarial stance. The architecture-critic's default question is "do we actually need this?" The test-engineer's core principle is "the legacy code is the oracle."
Highly Aligned with the SpecOps Method
Several design decisions in the plugin mirror SpecOps principles almost exactly:
| Principle | Code Modernization Plugin | SpecOps Method |
|---|---|---|
| Understand before transforming | Enforced sequence: assess and extract before transform | "Read specifications before code" |
| Business rules as discrete artifacts | Dedicated extraction command and agent | Specifications capture what the system should do |
| Given/When/Then format | Rule Cards use Given/When/Then with concrete values | Acceptance criteria in GIVEN/WHEN/THEN |
| Confidence and ambiguity | High/Medium/Low confidence with SME questions | "Flag ambiguity for human review" |
| Tests pin legacy behavior | "We're proving equivalence first; fixing bugs is a separate decision" | "Capture what the code does, not what you think it should do" |
Where SpecOps Adds To What the Plugin Does
The plugin is excellent at the extraction and transformation work. SpecOps covers some other critical steps that happen before and after that work. Three things stand out:
1. Specification as the enduring source of truth
The plugin produces analysis artifacts like analysis/rules.md and analysis/assessment.md that are valuable during modernization but aren't positioned as the ongoing governance layer. SpecOps treats the specification as permanent institutional knowledge: it outlives both the legacy and modern systems, governs future changes, and flows through a version-controlled change management process.
2. Human verification as a hard gate
The plugin flags low-confidence rules for SME review, but the workflow is fluid: you can proceed from /modernize-extract-rules to /modernize-transform without an enforced stop. SpecOps inserts an explicit Phase 3 where domain experts (not engineers) verify specifications before any implementation begins. The rule is: "Domain experts verify specifications, not code."
3. Post-modernization governance
Once the plugin's /modernize-harden pass is complete, the workflow is done. SpecOps continues: the SpecOps GitHub Action creates trackable issues when specifications change, enforcing "propose spec changes before code changes" for the life of the new system.
Two Great Tastes That Taste Great Together 🥜 + 🍫
The natural integration of the plugin and SpecOps would use the plugin's commands for execution and the SpecOps Method for governance:
| Phase | Plugin Role | SpecOps Role |
|---|---|---|
| 1. Discovery | /modernize-brief, /modernize-assess |
Stakeholder engagement, scope confirmation |
| 2. Extraction | /modernize-extract-rules |
Convert Rule Cards to governed specifications |
| 3. Verification | — | Human gate: domain experts verify specs |
| 4. Architecture | /modernize-map, /modernize-reimagine |
Traceability check against specs |
| 5. Transformation | /modernize-transform |
Implement to spec, not to legacy behavior |
| 6. Hardening | /modernize-harden |
Remediate per spec-change workflow |
| 7. Governance | — | Specs govern all future changes |
The critical handoff is between Phase 2 and Phase 3. The plugin's business-rules-extractor produces Rule Cards with confidence ratings and Given/When/Then specifications. Those cards get converted into SpecOps specification format (plain-language requirements with acceptance criteria, edge cases, and references to governing authority) and placed in the specifications/ directory for domain expert review. Only after verification do they become the source of truth that drives implementation.
The AGENTS.md File as the Bridge
The mechanism that would tie the two systems together is the AGENTS.md file placed at the project root.2 This file provides standing instructions to any AI agent working in the repository, including the plugin's specialist agents. It encodes the SpecOps governance rules so that when the legacy-analyst or business-rules-extractor operates in the workspace, their output is shaped by specification-driven principles:
- Read specifications before code
- Never implement undocumented behavior
- Preserve institutional knowledge by extracting implicit rules into specification language
- Flag ambiguity for human resolution rather than interpreting
This means the plugin's agents don't just produce standalone analysis artifacts. They feed into the specification governance pipeline automatically.
Skills: The Domain Knowledge Layer
The plugin's agents are generalists. They know how to structure an assessment or extract rules, but they may lack deep fluency in your specific legacy stack or business domain. This is where SpecOps skills come in: human-authored Markdown instruction sets that teach agents how to read specific technologies, apply domain patterns, and produce structured output.
A COBOL comprehension skill teaches paragraph-level control flow and copybook resolution. A tax-logic skill maps IRC section references to calculation implementations. A contract-test skill is tuned to your project's test framework conventions. These fill the gap between a general-purpose plugin agent and the specialized expertise your modernization requires.1
This composability is the key architectural insight. Tools like Claude Code are explicitly built to leverage plugins, skills, and agent instruction sets as a composable ecosystem. The Code Modernization Plugin is one purpose-built capability. SpecOps' AGENTS.md provides governance. Community skills provide domain-specific knowledge. They assemble into a pipeline matched to the problem at hand, rather than forcing every modernization through a single monolithic tool.
The SpecOps Skills Directory catalogs community-contributed skills spanning the full modernization pipeline, from initial planning and analysis through specification generation, verification, testing, and drift detection. The directory is growing, and the Code Modernization Plugin is now listed as a complementary resource.
Key Principles for the Combined Approach
- The plugin does the work; SpecOps governs the outcome. Use the plugin's agents and commands for extraction and transformation. Use SpecOps for verification, traceability, and ongoing change management.
- Specifications outlive both systems. The
analysis/directory is a modernization artifact. Thespecifications/directory is permanent institutional knowledge. - Never skip verification. The plugin can extract rules at High confidence. Domain experts still confirm them. "The code is correct" is an assumption until a human says so.
- Bugs are decisions, not accidents. When legacy behavior differs from policy, the specification captures the correct behavior (per domain expert), and the implementation follows the specification, not the bug.
- Incremental, not big-bang. Both the plugin (module-by-module transform) and SpecOps (iterative specification development) support incremental modernization. Use the Strangler Fig pattern to replace components progressively.
This is Big
The fact that Anthropic built a legacy modernization plugin that independently arrived at many of the same principles (understand before transforming, extract rules as discrete artifacts, use Given/When/Then, flag ambiguity, pin legacy behavior with tests) is validating. It suggests these aren't just SpecOps opinions; they're emerging consensus about how to do this work responsibly.
The difference is scope and durability. The plugin is excellent at the tactical execution. SpecOps provides the governance that makes the output last: verified specifications that outlive both systems, domain expert sign-off, tracked changes, and institutional knowledge preserved for the next team that inherits this code twenty years from now.
Together, they form a complete answer: discover, extract, verify, implement, validate, govern. Like peanut butter and chocolate, baby.
The book, The SpecOps Method: A New Approach to Modernizing Legacy Technology Systems, is now available on Amazon.
1 As models continue to mature, their training data will increasingly include legacy languages and conventions, and agents will become more fluent in these stacks out of the box. This makes it important to be strategic about what skills to introduce into the agent's context during modernization. Skills can augment what agents do during the process, but more information is not always better. Research suggests that excessive skills content can actually hurt performance by creating cognitive overhead. Be selective, and prioritize focused, actionable guidance over exhaustive documentation. See the SkillsBench study for empirical findings on this effect. ↩
2 This file could also be named CLAUDE.md to match Claude Code conventions. Claude Code recognizes both AGENTS.md and CLAUDE.md as agent instruction files at the project root. ↩