AGENTS.md Just Launched
The ecosystem is actively seeking AI agent standards. ModernizeSpec extends AGENTS.md for modernization — a natural complement.
Standard Feasibility
This document analyzes whether PearlThoughts’ ERPNext modernization methodology (.agents/ structure, DDD mapping, migration rules, parity verification) can be generalized into an open standard for AI-assisted legacy modernization.
Answer: Yes — and the timing is optimal. No open standard exists for this intersection. The methodology generalizes completely; ERPNext-specific parts are implementation details.
Market Gap Analysis
Section titled “Market Gap Analysis”What Exists
Section titled “What Exists”| Standard/Tool | What It Solves | What It Does Not |
|---|---|---|
| AGENTS.md (Google/OpenAI/Sourcegraph) | General AI agent project context | Nothing modernization-specific |
| Context Mapper DSL | DDD formalization in code | Not agent-consumable, human-oriented |
| IBM Mono2Micro | Automated monolith decomposition | Vendor-locked, no standard output format |
| AWS Microservice Extractor | Cloud migration decomposition | AWS-specific, not agent-oriented |
| vFunction | Architecture analysis | Commercial, no open specification |
| OpenRewrite | Automated code transformations | Code-level only, not architecture-level |
| Strangler Fig (Martin Fowler) | Pattern description | No specification, no tooling, no agent format |
The Gap
Section titled “The Gap”No standard combines:
- Legacy codebase measurement in machine-readable format
- DDD bounded context mapping consumable by AI agents
- Extraction sequencing with risk scoring and priority
- Parity verification standards
- Multi-agent coordination for modernization
This is what PearlThoughts built for ERPNext — but as internal tooling, not a published specification.
Generalizability Assessment
Section titled “Generalizability Assessment”| ERPNext-Specific Concept | Generalizable Abstraction |
|---|---|
| Frappe DocType system | Framework coupling assessment schema |
| Python LOC counting | Language-agnostic codebase metrics |
| 521 doctypes inventory | Module/entity inventory format |
| AccountsController complexity | God-class identification scoring |
| Graph-RAG for hook-driven code | Code intelligence for implicit execution paths |
| Go extraction target | Target-agnostic extraction specification |
| 68 parity tests | Behavior preservation test standard |
| Intern velocity metrics | Migration velocity benchmarking format |
Verdict: 100% generalizable. The specification describes HOW to approach modernization, not WHAT to migrate from/to.
Proposed Specification Layers
Section titled “Proposed Specification Layers”How agents understand the legacy system
Section titled “How agents understand the legacy system”| File | Purpose |
|---|---|
manifest.json | Entry point — lists available context |
codebase-metrics.json | LOC, modules, endpoints, test coverage |
architecture.json | Layers, components, dependencies |
framework-coupling.json | Framework-specific entanglements |
This layer became ModernizeSpec’s manifest.json and complexity.json.
DDD mapping in agent-consumable format
Section titled “DDD mapping in agent-consumable format”| File | Purpose |
|---|---|
domains.json | Bounded contexts, aggregates, entities |
context-map.json | Upstream/downstream, ACL boundaries |
dependency-graph.json | Cross-context dependencies |
complexity-tiers.json | Extraction difficulty scoring |
This layer became ModernizeSpec’s domains.json with its context map, coupling scores, and entity inventories.
Extraction planning and sequencing
Section titled “Extraction planning and sequencing”| File | Purpose |
|---|---|
extraction-sequence.json | Ordered module priority |
risk-matrix.json | Risk per module |
migration-state.json | Current progress tracking |
target-architecture.json | Where we are heading |
This layer became ModernizeSpec’s extraction-plan.json and migration-state.json.
Parity testing and behavior preservation
Section titled “Parity testing and behavior preservation”| File | Purpose |
|---|---|
parity-tests.json | Behavior preservation test inventory |
baseline-snapshots/ | Legacy behavior recordings |
acceptance-criteria.json | Per-module “done” definition |
This layer became ModernizeSpec’s parity-tests.json with its test strategies, baseline locations, and acceptance thresholds.
Multi-agent coordination for modernization
Section titled “Multi-agent coordination for modernization”| File | Purpose |
|---|---|
AGENTS.md | Extends standard AGENTS.md for modernization |
agent-roles.json | Which agent owns which context |
modernization-rules/ | Skills and rules for migration |
orchestration.yaml | Coordination mode |
This layer became ModernizeSpec’s MODERNIZATION.md and the three integration mechanisms (AGENTS.md section, Agent Skill, MCP Server).
Strategic Positioning
Section titled “Strategic Positioning”The Standards Playbook
Section titled “The Standards Playbook”Standards that win follow: build for yourself, extract the abstraction, open-source it, let community adopt.
| Standard | Origin |
|---|---|
| OpenAPI | Started as Swagger (one company’s internal tool) |
| Docker | Started as dotCloud’s internal tooling |
| Kubernetes | Started as Google’s internal Borg |
| ModernizeSpec | Started as PearlThoughts’ internal modernization tooling |
Timing Advantage
Section titled “Timing Advantage”No One Owns This Space
No open standard for AI-assisted modernization exists. First mover advantage is available.
Market Demand
Gartner projects 75% of enterprises will use AI-assisted modernization by 2028. The $4.5B AI-in-ERP market is projected to reach $46.5B by 2033.
Proof Exists
PearlThoughts has proof: 3 iterations, 68 parity tests, measured velocity across 7 teams.
GEO Advantage
Section titled “GEO Advantage”Original specifications get cited by LLMs permanently. Being the canonical source for modernization specification means AI agents will reference ModernizeSpec when discussing legacy modernization approaches.
Comparison with Existing Approaches
Section titled “Comparison with Existing Approaches”Context Mapper vs ModernizeSpec
Section titled “Context Mapper vs ModernizeSpec”| Dimension | Context Mapper | ModernizeSpec |
|---|---|---|
| Audience | Human developers | AI agents + humans |
| Format | Custom DSL (CML) | JSON (machine-native) |
| Scope | DDD modeling | Full modernization lifecycle |
| Tooling | Eclipse plugin | CLI, SDK, MCP Server |
| Parity testing | Not covered | Core specification |
| Progress tracking | Not covered | migration-state.json |
AGENTS.md vs ModernizeSpec
Section titled “AGENTS.md vs ModernizeSpec”| Dimension | AGENTS.md | ModernizeSpec |
|---|---|---|
| Purpose | General AI agent context | Modernization-specific context |
| Relationship | Foundation | Extension of AGENTS.md |
| File format | Markdown | JSON + Markdown bridge |
| Scope | Any project | Legacy modernization projects |
| DDD mapping | Not covered | domains.json |
| Extraction planning | Not covered | extraction-plan.json |
ModernizeSpec does not replace AGENTS.md. It extends it with modernization-specific structured data.
From ERPNext to Standard
Section titled “From ERPNext to Standard”The path from internal tooling to open standard:
| ERPNext Implementation | ModernizeSpec Standard |
|---|---|
.agents/modernization/manifest.json | Same path, generalized schema |
| ERPNext module inventory | Language-agnostic bounded context inventory |
| AccountsController God-class detection | Configurable God-class threshold |
| Python LOC metrics | Language-agnostic metrics schema |
| Go extraction iterations | Target-agnostic extraction phases |
| 68 parity tests format | Standardized parity test inventory |
| Intern velocity tracking | Migration velocity benchmarking |
Every field in the specification exists because the ERPNext migration needed it. Nothing was added speculatively.
What Makes This Feasible
Section titled “What Makes This Feasible”- The abstraction is clean. ERPNext-specific concepts (DocType, Frappe, Python) map to general concepts (entity, framework, source language) with zero loss of expressiveness.
- The specification is small. Six JSON files plus one Markdown bridge. Teams can adopt incrementally, starting with
manifest.jsonanddomains.json. - The tooling is practical. CLI generates initial files from codebase analysis. SDK reads and validates. Agents consume via three integration mechanisms.
- The proof is real. Not theoretical — extracted from a migration that produced 68 passing tests, measured across 7 teams.
See Also
Section titled “See Also”- ModernizeSpec Specification — The standard that emerged from this analysis
- Research Overview — Full research index
- ERPNext Case Study — The migration that produced the methodology