DROW — Agentic Modernization Framework for Legacy Codebases

Your brownfield's best bro.

DROW scaffolds a structured, AI-powered workflow directly inside your legacy project — guiding specialized agents through discovery, planning, and translation with clear approval gates and shared context between sessions.

It works with any AI coding tool you already use: Claude Code, Cursor, Windsurf, Zed, Neovim, or VS Code with Copilot.

Why DROW?

Legacy modernization fails for predictable reasons: teams start translating before they understand what they have, lose business rules in the chaos, and run out of steam halfway through. DROW addresses this by enforcing a disciplined three-phase workflow before a single line of production code changes.

• 100% free and open source — no paywalls, no gated features, no SaaS
• Works with your existing AI tool — not another editor to learn
• Read-only discovery phases — agents cannot modify your source files during analysis
• Human approval gates — you review and approve the plan before any translation begins
• Shared context across sessions — agents pick up where the last one left off
• Language-agnostic — 13+ legacy source stacks, 19+ modern target stacks

Getting Started

Prerequisites

• Node.js >= 18.0.0
• An AI coding environment (Claude Code, Cursor, Windsurf, Zed, Neovim, or VS Code)

Installation

Run the interactive scaffolder at the root of your legacy project:

npx create-drow

The CLI will ask you:

1. Project name — defaults to the current directory name
2. Environments — which AI tools to configure (multi-select)
3. Agents — install all 9 agents or pick only what you need
4. Confirm — review before any files are written

That's it. DROW writes its configuration into a .drow/ directory and sets up environment-native command hooks for your selected tools.

How It Works

DROW organizes the modernization effort into three phases, each handled by specialized agents. Agents share state through a .drow/drow-context.md file that persists across sessions.

Phase 1 — Discovery (Read-Only)

No source files are modified during this phase.

| Agent | Command | Purpose | |---|---|---| | Archaeologist | /project:drow-discover | Scans codebase, maps modules, identifies risks | | Analyst | /project:drow-analyze | Extracts business rules, surfaces staleness signals | | Boundary Mapper | /project:drow-map-boundaries | Maps module interfaces and inter-system dependencies | | Cartographer | /project:drow-map-infra | Charts cloud infrastructure, CI/CD, IaC, observability | | Oraculus | /project:drow-assess-sre | Assesses SRE readiness, SLO gaps, reliability posture |

Phase 2 — Consultation & Planning

| Agent | Command | Purpose | |---|---|---| | Consul | /project:drow-consult | Synthesizes discovery, produces cross-cutting recommendations, awaits your approval | | Strategist | /project:drow-plan | Builds a phased migration roadmap with effort scores and go/no-go gates |

You review and approve the plan before Phase 3 begins. This is the most important gate in the workflow.

Phase 3 — Translation & Execution

| Agent | Command | Purpose | |---|---|---| | Transformer | /project:drow-translate | Migrates source files to the target language using battle-tested patterns | | Scoped | /project:drow-scope | Addresses cross-cutting concerns: observability, security, error handling, custom scopes |

Supported Stacks

Legacy Source Languages

COBOL, Perl, VB6, Fortran, SAS, Java (legacy), C, C++, PHP, Node.js (legacy), Ruby, stored procedures, FTP/batch jobs, and monoliths.

Modern Target Stacks

Spring Boot, FastAPI, Django, Go, Fastify/TypeScript, .NET 8, AWS Lambda, Kotlin, microservices (REST, event-driven), and more.

Compliance Profiles

SOC2, HIPAA, PCI-DSS, GDPR, LGPD, ISO 27001, FedRAMP.

Supported Environments

DROW generates native configuration for each environment you select during setup.

| Environment | How agents are invoked | |---|---| | Claude Code | /project:drow-discover, /project:drow-plan, etc. | | Cursor | @drow-discover, @drow-plan, @drow-translate | | Windsurf | drow-discover, drow-plan, drow-translate in Cascade chat | | Zed | drow-discover, drow-plan, drow-translate via inline assistant | | Neovim | :DrowDiscover, :DrowPlan, :DrowTranslate | | VS Code | @workspace drow-discover, @workspace drow-plan, etc. |

What Gets Scaffolded

After running npx create-drow, your project will contain:

.drow/
  drow.config.yaml          # Project metadata, language selections, compliance profile
  drow-context.md           # Shared agent memory — architecture decisions, module status, risk flags
  CLAUDE.md                 # Agent routing rules (Claude Code only)
  patterns/                 # 17 migration pattern playbooks (P01–P17) — shared by all environments
  agents/                   # Agent instructions + run outputs (when not Cursor-only); reports/artefacts still live here
  skills/                   # Flat skill .md files (non-Cursor environments, or alongside Cursor)
  hooks/                    # pre-execution.sh (non-Cursor environments, or alongside Cursor)

.cursor/                    # Cursor IDE — project rules, skills, slash commands, hooks (when Cursor is selected)
  rules/drow.mdc            # Always-on routing + session rules
  hooks.json                # Hook manifest (empty by default; add events as needed)
  hooks/pre-execution.sh    # Git snapshot script (Cursor-compatible stdin drain)
  agents/<role>.md          # One markdown file per agent (e.g. archaeologist.md) — not CLAUDE.md; Claude Code still uses .drow/agents/*/CLAUDE.md
  commands/drow-*.md       # Slash prompts: type /drow-discover, /drow-analyze, … in chat
  skills/<name>/SKILL.md    # Domain skills from templates + workflow skills (drow-discover, …) with next-step runbooks

# Environment-specific files (based on your selections):
.claude/commands/           # One .md per agent (Claude Code)
.windsurfrules              # Windsurf Cascade rules
.zed/assistant_instructions.md
.nvim/drow.lua + drow-instructions.md
.github/copilot-instructions.md + .vscode/settings.json

Cursor-only installs skip .drow/agents, .drow/skills, and .drow/hooks copies; agent instructions, skills, hooks, and slash commands live under .cursor/. Discovery and translation outputs (reports, charters, logs) still use .drow/agents/... paths defined in each agent’s instructions.

Starting in Cursor: open the repo, then type /drow-discover (or pick the drow-discover skill). Each command/skill tells the model to follow the matching .cursor/agents/<role>.md and to recommend the next slash step when it finishes (e.g. /drow-analyze after discovery).

Chat-first confirmations: DROW rules ask agents to collect approvals in the active session — not by opening report/charter files to edit or tick boxes. Artifacts under .drow/agents/ are still written as the audit trail and input for the next agent.

Interactive choices: DROW matches the GSD-style pattern: agents should call the AskUserQuestion tool when the session supports it — that works in Cursor Agent (picker UI) and Claude Code, not only in the terminal. Each question uses a few labeled options plus an Other / free-text path when needed. If AskUserQuestion is not available in a given chat/model setup, agents fall back to numbered lists and typed replies. Native quick-reply chips without going through a tool are still a Cursor platform request for some flows.

Migration Pattern Library

DROW ships 17 battle-tested migration patterns covering the most common legacy-to-modern paths. Each pattern documents translation challenges, precision traps, and parity checks the Transformer agent must pass before a file is considered done.

| Pattern | Source → Target | |---|---| | P01 | Batch/Cron → AWS Lambda / Cloud Functions | | P02 | Monolith → Microservices | | P03 | C/C++ → Java | | P04 | VB6 → C# / Python | | P05 | Perl → Python / Node.js | | P06 | FTP/File-based → REST API / Event-driven | | P07 | SAS → Python / R | | P08 | Stored Procedures → Service Layer | | P09 | C → Go | | P10 | COBOL → Java | | P11 | COBOL → Python | | P12 | COBOL → C# | | P13 | Fortran → Python / Julia | | P14 | Java Legacy → Modern Java / Kotlin | | P15 | Ruby → Go / Node.js / Python | | P16 | Fragmented Microservices → Consolidated Microservices | | P17 | PHP → Modern Stack |

Project Structure

create-drow/
  bin/
    create-drow.js          # Interactive CLI installer
  src/
    constants.js            # Agent definitions, language profiles, environment adapters
    writers.js              # Environment-specific config file generators
    generator.js            # Orchestrates file generation across selected environments
    detector.js             # Auto-detects legacy language from file extensions and sentinels
    context-reader.js       # Extracts migration intent from existing docs (README, BRIEF, etc.)
    assessor.js             # Hidden asset questionnaire (batch jobs, sprocs, integrations)
  templates/                # Agent instructions, skills, and migration patterns
  test/                     # Unit tests (Node.js built-in test runner)

Contributing

Contributions are welcome. The most valuable areas are:

• New migration patterns — add a P18+ file under templates/patterns/ following the existing structure (translation challenges, precision traps, parity checks)
• New source or target languages — extend SOURCE_LANGUAGES and TARGET_LANGUAGES in src/constants.js
• New environment adapters — implement a writeXxx() function in src/writers.js and register it in ENVIRONMENTS
• Bug reports and edge cases — especially around language detection and context extraction

Running Tests

node test/writers.test.js
node test/generator.test.js
node test/detector.test.js
node test/context-reader.test.js
node test/assessor.test.js

Or run the full suite:

npm test

Tests use Node.js's built-in node:test and assert/strict — no external test framework required.

License

MIT — see LICENSE.

FAQ

Does DROW modify my source code during discovery? No. Phases 1 agents are strictly read-only. Source files are only touched in Phase 3, and only after you approve the plan from Phase 2.

Do I need to run all agents? No. You can install a scoped subset during setup and run agents selectively. The Scoped agent (/project:drow-scope) can also target individual concerns like observability or security without a full migration.

What if my legacy language isn't listed? The context-reader will try to infer intent from your existing docs. You can also manually set sourceLanguage in .drow/drow.config.yaml and point the Transformer to the closest available pattern.

Can I use DROW without Claude Code? Yes. DROW generates environment-native configuration for Cursor, Windsurf, Zed, Neovim, and VS Code. Claude Code provides the richest experience (full 9-agent command set), but the core workflow is available on all supported tools.

Is DROW a SaaS product? No. DROW runs entirely in your local environment. There are no accounts, no telemetry, and no external services.