manifest.json
The entry point. Contains project metadata (name, framework, language, LOC, entity count) and a file inventory pointing to the other spec files. AI agents read this first.
File Convention
The file convention is Layer 1 of ModernizeSpec — zero friction, zero dependencies. Place JSON files in a directory. Any agent can read them today.
Directory Structure
Section titled “Directory Structure”Location Convention
Section titled “Location Convention”ModernizeSpec files live under .agents/modernization/ at the root of the project repository. This follows the .agents/ convention established by AGENTS.md for machine-readable agent context.
File Purposes
Section titled “File Purposes”domains.json
Bounded context map. Each context has a name, type (core/supporting/generic), entities, aggregate root, LOC, coupling scores, and dependencies. Includes the context map showing upstream/downstream relationships.
complexity.json
Extraction difficulty assessment. Modules are organized into tiers (Extract Now, Extract With Care, Defer). Hotspots list God-classes and high-complexity files with recommendations.
extraction-plan.json
Phased extraction sequence. Each phase has a name, duration estimate, contexts to extract, risk level, dependencies, and acceptance criteria. Sequencing constraints define what must be extracted before what.
parity-tests.json
Behavior preservation test inventory. Lists test suites per bounded context with test count, type, command to run, baseline location, and acceptance thresholds (parity percentage, regression tolerance).
migration-state.json
Current progress. Tracks overall progress percentage, per-context status (not started, in progress, complete), entities migrated, parity test results, blockers, and velocity metrics.
runtime-profile.json
Runtime evidence from the legacy system. Hot paths, database query patterns, N+1 detection, dead code discovery, and resource usage. Collected via APM, OpenTelemetry, or profiling scripts.
MODERNIZATION.md
Section titled “MODERNIZATION.md”The human-readable counterpart. While JSON files serve agents and tooling, MODERNIZATION.md provides a prose overview for human developers. It summarizes the modernization strategy, current status, and key decisions in a format that renders in GitHub and Obsidian.
Design Principles
Section titled “Design Principles”Zero Dependencies
Section titled “Zero Dependencies”The file convention requires no tooling to use. Create the JSON files manually, with a text editor, with the CLI, or with the SDK. Any tool that reads JSON can consume them.
Machine-Readable First
Section titled “Machine-Readable First”Every file is valid JSON with a defined schema. This enables:
- Automated validation against JSON Schema
- Programmatic access via the SDK
- Visualization by dashboard tools
- CI/CD integration for compliance checks
Progressive Adoption
Section titled “Progressive Adoption”Not every file is required. Start with manifest.json and domains.json. Add complexity, extraction plans, and parity tests as the modernization progresses.
| Adoption Level | Files | Use Case |
|---|---|---|
| Minimal | manifest.json | Tell agents this project is undergoing modernization |
| Standard | + domains.json, complexity.json | Agents understand boundaries and risk |
| Complete | All files including runtime-profile.json | Full modernization context with progress tracking and runtime evidence |
Naming Convention
Section titled “Naming Convention”All file names use lowercase kebab-case with .json extension. The directory name is modernization (not modernize, not migration).
Version Control
Section titled “Version Control”All ModernizeSpec files should be committed to version control. They are part of the project’s documentation and evolve alongside the codebase. migration-state.json changes frequently as progress is made — this is expected.