Init Walkthrough

The modernizespec init wizard generates your .agents/modernization/ directory through an interactive series of prompts. This guide explains each step.

Running Init

npx modernizespec init

Or if installed globally:

modernizespec init

Wizard Steps

1. Project name

   ? Project name: ERPNext

   The display name of your project. Used in manifest.json and MODERNIZATION.md.

2. Legacy framework

   ? Legacy framework:
     ❯ django
       rails
       spring
       dotnet
       frappe
       laravel
       custom

   Select the framework your legacy system is built on. If your framework is not listed, choose custom and specify it.

3. Legacy language

   ? Primary language:
     ❯ python
       java
       ruby
       csharp
       php
       cobol
       javascript

   The primary server-side language of the legacy codebase.

4. Codebase metrics

   ? Lines of code (approximate): 316000
   ? Number of entities/models: 521
   ? Number of API endpoints: 768
   ? Codebase age in years (optional): 20

   These populate the legacy section of manifest.json. Approximate values are fine — they help agents understand the scale.

5. Target language

   ? Target language:
     ❯ go
       kotlin
       typescript
       java
       rust

   The language you plan to migrate to.

6. Target architecture

   ? Target architecture:
     ❯ hexagonal
       clean
       modular-monolith
       microservices

   The architectural style for the modernized system.

7. Migration pattern

   ? Migration pattern:
     ❯ strangler-fig
       big-bang
       parallel-run

   • Strangler Fig — Incrementally replace modules while the legacy system continues to run
   • Big Bang — Complete rewrite before switching over
   • Parallel Run — Both systems run simultaneously, with traffic gradually shifted

8. Generate domain stubs

   ? Generate domain stubs from codebase analysis? (y/N): y

   If yes, the wizard scans your project directory for module boundaries and suggests initial bounded contexts for domains.json. You can edit these after generation.

9. Generate complexity analysis

   ? Run complexity hotspot analysis? (y/N): y

   If yes, the wizard analyzes file sizes, function counts, and import patterns to identify God-classes and populate complexity.json.

Generated Output

After completing the wizard, you will have:

.agents/modernization/
├── manifest.json           # Populated with your answers
├── domains.json            # Bounded contexts (stubs or analyzed)
├── complexity.json         # Hotspots (if analysis was run)
├── extraction-plan.json    # Empty template
├── parity-tests.json       # Empty template
├── migration-state.json    # Initialized with "not-started" for each context
└── MODERNIZATION.md        # Human-readable overview

Post-Init Steps

Review Domains

The generated domains.json is a starting point. Review the suggested bounded contexts:

• Are the boundaries correct? Modules that share extensive data may belong in one context.
• Is the context type accurate? Core vs supporting vs generic affects extraction priority.
• Are dependencies complete? Check for implicit dependencies through shared controllers or hook systems.

Review Complexity

If complexity analysis was run, check the hotspot list:

• Do the God-class identifications match your experience?
• Are the tier assignments reasonable?
• Add any known complexity that the static analysis missed (e.g., hook-driven implicit paths).

Add Extraction Plan

The extraction plan template is empty after init. Fill it in based on your domain knowledge:

• Which contexts should be extracted first?
• What are the dependencies between contexts?
• What acceptance criteria should each phase meet?

Commit

git add .agents/modernization/
git commit -m "feat: add ModernizeSpec modernization context"

Flags

Flag	Description
--dir <path>	Target directory (default: current directory)
--no-analyze	Skip codebase analysis, generate only from prompts
--json <path>	Non-interactive mode: read answers from a JSON file
--force	Overwrite existing .agents/modernization/ directory

Non-Interactive Mode

For CI or scripting, provide answers via JSON:

modernizespec init --json init-config.json

Where init-config.json:

{
  "project": "ERPNext",
  "legacy": {
    "framework": "frappe",
    "language": "python",
    "loc": 316000,
    "entities": 521,
    "endpoints": 768,
    "age_years": 20
  },
  "target": {
    "language": "go",
    "architecture": "hexagonal",
    "pattern": "strangler-fig"
  },
  "analyze": true,
  "complexityAnalysis": true
}

Next Steps

• Specification Overview — Understand each file in depth
• Integration Overview — Connect your agent