forge:refactor

Automating safe code refactors requires a structured run and worktree pipeline that targets specific code areas, coordinating setup, review, and apply gates to ensure safety and traceability. This approach enforces explicit run creation and gated handoffs before applying changes.

A worktree pipeline for codebase refactoring is a structured process that creates a dedicated run and an isolated worktree for each task. Changes are planned and reviewed through staged approval gates before being applied, ensuring deterministic and traceable execution.

Gated reviews for an automated refactor pipeline are established by enforcing staged approvals within the run lifecycle. You create a run, manage the worktree, and route changes through review gates that ensure human approval before any apply phase begins.

You can scope an automated refactor to specific files or code areas by passing the target scope through ARGUMENTS. The pipeline supports any code area or file target, and allows for rework once the gated review is approved.

A dedicated run for code refactoring is needed when executing structured changes that require traceability and gated governance. It isolates the worktree setup and review process, ensuring changes are applied only after explicit human approval.

A key limitation of automating refactors with a gated pipeline is the enforced overhead: explicit run creation, worktree management, and staged review gates slow down execution. This approach prioritizes safety and traceability over rapid, unreviewed code changes.