reforge

Reforge: cleaning up a messy repository

Analysis comes from tools, not from reading files. Every finding is a question to check, not a fact to act on.

1. Prerequisites

The ten reforge MCP tools must be registered: scan_repo, get_chunk, write_fix, git_commit, read_memory, write_memory, infer_architecture, score_risk, get_health_score, generate_changelog.

If they are missing, give the user these two commands and stop — do not substitute grep or manual reading:

pip install reforge-mcp
claude mcp add reforge -- reforge-mcp

No API key is needed. The repository must be a git repository with a clean working tree; only git-tracked files are analysed, so ask the user to git add new work first or it is invisible.

Note the argument names: scan_repo takes root_path, get_chunk and write_fix take file_path plus repo_root, and everything else takes repo_path.

2. Workflow

1. Scan. scan_repo(root_path=...). Read summary first — it is never truncated. Then parse_failures, summary.unscanned_source_files and dep_graph.unresolved_relative_imports. Long lists are capped on the wire: truncated names every shortened key and <key>_total gives its real length.
2. Score. get_health_score(repo_path=...) for the 0–100 baseline and its coverage. Low coverage means the score describes a fraction of the repo — say so before quoting it.
3. Understand the shape. infer_architecture(repo_path=...) for the pattern, entry points and modules. It stores architecture_hypothesis.
4. Plan, then save it. Rank findings worst-first, weighted by score_risk(symbol=..., file=..., repo_path=...) — prefer low risk and high payoff. Save the ordered plan with write_memory(key="pending_work", value=[...], repo_path=...) before touching anything, and read_memory it back when resuming.
5. Read only what you need. get_chunk(file_path=..., start_line=..., end_line=...) for each symbol you intend to change. Confirm the finding is real in the code you just read; drop it from the plan if it is not.
6. One fix. Build a unified diff and apply it with write_fix(file_path=..., diff_str=..., test_command=...). Always pass a test_command when the project has one. The file ends up either correctly changed or byte-identical. If the result carries a backup path, git could not have recovered the file — report that path to the user and leave it alone.
7. Commit it. git_commit(repo_path=..., files=[...], message=...), one fix per commit, message saying what was removed and why it was safe.
8. Repeat from step 5 until the plan is empty or the budget stops you.
9. Finish. get_health_score again, then generate_changelog(repo_path=...) to write REFORGE_CHANGES.md.