doc-and-modernize

What it does

Guides a locally checked-out repository through two workflows: (1) Documentation mode to produce one definitive, cited architecture document describing the codebase from disk, suitable for onboarding and mapping the system; (2) Modernization mode to generate a phased plan to modernize, migrate, upgrade, or rewrite a legacy system. If no architecture document exists, it first runs Documentation mode and then proceeds to the modernization plan.

How it works

• Documentation mode reads local files to build a single Markdown document with sections: Whole-repo deep-dive, tech-stack, entry points, commands & verification inventory, directory layout, deployment surface, EOL/dependency notes, data/storage, APIs, plugins, CI/CD, and subsystems deep-dives.
• It anchors to the local checkout identity by executing git commands to verify remote, branch, and commit. It detects technology stacks from manifests and config files on disk. It maps the repo breadth before drilling into 2-3 hardest subsystems. It verifies cited files and line numbers for each claim.
• Output is a single Markdown document with local-file citations and a structured conventions section emphasizing traceability and [UNVERIFIED] or [INFERRED] as needed.
• Modernization mode uses the architecture document if available and produces a forward-looking plan with a safety ladder, feasibility spike, and phases for modernization. It avoids assuming a fully-green legacy CI gate and focuses on a time-boxed spike to determine a realistic migration path.

When to use it

• Use Documentation mode when you want to understand, map, document, research, or onboard onto a codebase (e.g., "research this repo", "write up the architecture", "do an architecture deep dive").
• Use Modernization mode when you want to modernize, migrate, upgrade, or rewrite a system (e.g., "modernize this", "plan the migration"). If no architecture document exists yet, it will run Documentation mode first.

What it can touch

• The workflow relies on local files and standard repo manifests (e.g., Go, npm, Python, Java configurations) present in the checked-out repository. It does not rely on remote sources unless necessary for verification notes, which it marks as [UNVERIFIED].

Caveats

• Assumes a locally checked-out repository and uses a local-first approach; remote facts (like star counts or full CI histories) may be out of scope unless explicitly determined and marked as [UNVERIFIED].
• The modernization plan emphasizes a safety ladder and feasibility spike rather than guaranteeing a green CI gate before any migration work.