Skip to content
ModernizeSpec

Specification Overview

ModernizeSpec is an open specification that tells AI agents how to understand, decompose, and modernize legacy systems. It extends AGENTS.md for the modernization use case.

The Problem

Section titled “The Problem”

Every legacy modernization project starts from zero. AI agents encounter codebases with no structured understanding of bounded contexts, complexity hotspots, extraction sequences, or parity requirements. The result: agents guess, humans correct, weeks are wasted.

The Three-Part Architecture

Section titled “The Three-Part Architecture”

ModernizeSpec follows the same structural pattern as MCP (Model Context Protocol) — a specification alone is not enough. MCP ships a protocol specification, an SDK, and host integration. ModernizeSpec adapts this for a static file specification (files on disk) rather than a runtime protocol (processes communicating via JSON-RPC).

Part 1: Specification

JSON files on disk in .agents/modernization/. Zero dependencies. Any tool can read them. Defines bounded contexts, complexity scores, extraction plans, parity tests, and migration state.

Part 2: SDK + CLI

@modernizespec/sdk reads, writes, validates, and generates spec files. The CLI wraps the SDK for terminal use. Third parties import the SDK instead of parsing JSON themselves.

Part 3: Agent Bridge

Three integration mechanisms: AGENTS.md section (universal, zero setup), Agent Skill (progressive disclosure), and MCP Server (deterministic tool access with read/write).

Architecture Diagram

Section titled “Architecture Diagram”

Relationship to AGENTS.md

Section titled “Relationship to AGENTS.md”

ModernizeSpec extends AGENTS.md — it does not replace it. AGENTS.md provides general AI agent context (build steps, test commands, conventions). ModernizeSpec adds a domain-specific extension for modernization: bounded contexts, complexity tiers, extraction plans, and parity verification.

This follows established precedent: Schema.org extends HTML. OpenAPI extends HTTP. Conventional Commits extends Git.

How It Maps to MCP

Section titled “How It Maps to MCP”
MCPModernizeSpecDifference
Protocol Spec (JSON-RPC format)File Spec (JSON file formats)MCP defines wire messages; ModernizeSpec defines files on disk
TypeScript SDK (@modelcontextprotocol/sdk)TypeScript SDK (@modernizespec/sdk)MCP SDK handles transport/serialization; ModernizeSpec SDK handles file I/O/validation
MCP Server (exposes tools to agents)MCP Server + Agent Skill + AGENTS.md sectionModernizeSpec has three integration paths, not just one
MCP Client (lives inside host)Host’s native context injectionAgents already read AGENTS.md/Skills — no new client needed
Host (Claude Code, VS Code)Same hostsModernizeSpec runs inside the same agent ecosystem

The key architectural difference: MCP is a runtime protocol (live communication between processes), while ModernizeSpec is primarily a static specification (files on disk describing a project). The MCP server bridge is optional — the spec works without it.

Who Benefits

Section titled “Who Benefits”

Run npx modernizespec init or create files manually. Any AI agent reading the project immediately understands the modernization context. Zero dependencies, zero build step, zero lock-in.

Next Steps

Section titled “Next Steps”