Refactor large codebases

Discovery before edits

The protocol pushes read-before-write. repo_map gives a shallow tree; grep_file and find_files locate symbols; ast_grep and symbol_index help on TypeScript/JavaScript. read_file_with_imports can pull related modules when AGENT_SPECULATIVE_READS is on.

recall_relevant and memory_query surface prior decisions from earlier sessions in the same workspace fingerprint — useful when a migration spans days.

• rename_symbol — project-wide TS/JS rename via the language service.
• multi_file_apply — atomic batch edits with rollback on failure.
• git_checkpoint / git_rollback — safe points before risky waves.

Closing the loop: tests and lint

run_tests and run_lint are first-class. With AGENT_SELF_HEAL_LINT=1, the harness tracks successful edit tools and runs a bounded diagnose→fix→verify loop on changed files (escalating scope if needed). Failures append to .agent_failures.jsonl for failure_review later.

Dynamic workflows for module-wide sweeps

When intent inference marks a turn as workflowSuitable (large parallel sub-tasks), the harness can auto-activate the workflow family. plan_workflow → run_workflow fans out forkChild() agents in concurrency waves, stores full outputs in .agent_workflows/<runId>/ (out of parent context), and folds only distilled phase summaries back — so you get a final report without stuffing hundreds of tool outputs into one context window.

Cross-phase work publishes to the session SharedMemoryBus under ctx/wf/<runId>/<phaseId> so downstream agents inherit upstream findings.

Practical pattern for a migration

• 1. Decompose: decompose_goal or plan with explicit acceptance criteria.
• 2. Map: repo_map + grep on old API surface.
• 3. Wave edits: multi_file_apply per directory or workflow phase per package.
• 4. Verify: run_tests; enable self-heal lint for type errors.
• 5. Remember: remember() or vault_write for conventions the next session should reuse.