Refactor a large codebase through coordinated subagents

Why use this

1. A broad structural refactor can divide neatly by directory while still sharing interfaces, generated files and tests across boundaries. Parallel work may make each local change look reasonable even when the combined result contains conflicting assumptions.

2. A coordination packet could define ownership, shared contracts and integration checkpoints before edits begin. Maintainers could see where work can proceed independently and which changes require joint review, without treating parallel completion as evidence that behavior was preserved.

Why an agent / simpler alternative

Useful judgment

Partition responsibilities and identify shared dependencies that make apparently separate edits interact.

Simpler alternative

Use a sequential refactor when the change is tightly coupled or small enough for one maintainer to review coherently.

Unsuitable when

The repository lacks a behavior baseline or no one owns integration and regression review.

Proposed inputs

1. Name

   Refactor scope map

   Owner

   Maintainer

   Minimum scope

   Affected areas, desired structure and preserved interfaces

   Quality check

   Identify shared files and generated artifacts.

2. Name

   Integration constraints

   Owner

   Engineering lead

   Minimum scope

   Ownership rules, baseline checks and merge-review requirements

   Quality check

   Distinguish local completion from combined acceptance.

Access and setup — proposed or unknown

Proposed minimum

1. Fictional dependency maps and an offline work-partition proposal.

Compatibility unknowns

1. Unknown: current runtime, isolated work-area support, test environment and integration tooling.

External actions requiring approval

1. Repository edits, compute allocation, code disclosure, pull-request publication and final merge.

Expected deliverable and review checks

Proposed artifact

Work partition with shared-contract owners, integration sequence and proposed regression evidence.

Critical checks

1. Every shared interface has an explicit coordination owner.

2. Combined review includes cross-area behavior beyond local checks.

Missing output evidence

No new workflow run or output inspection was performed for this overlay; use the canonical source-outcome references.

Failure signals and proposed responses

1. Signal

   Two work packages both rename a shared public type.

   Why it matters

   Local changes may conflict or silently diverge.

   Proposed response

   Assign one owner and require dependent packages to consume the reviewed contract.

2. Signal

   Each package passes its proposed local checklist but no integration check exists.

   Why it matters

   Cross-boundary regressions can remain invisible.

   Proposed response

   Add a maintainer-reviewed integration evidence requirement before considering merge readiness.

Effort and cost — unknown

Setup work

1. Map dependencies and assign integration ownership.

Ongoing review

1. Reconcile shared changes and inspect later regression evidence.

Unknowns

1. Unknown: parallel compute costs, conflict volume and review complexity.

First check — proposed, unexecuted

Status

proposed_unexecuted

Synthetic fixture

A fictional refactor plan assigns the same interface to two workers and lists only local checks.

Acceptance checks

1. Expose overlapping ownership.

2. Require combined evidence without claiming any tests have passed.

Stop conditions

1. Worktree creation, code edits, test execution or merge actions are needed.

Limits

1. This planning review is not a reproduction of the referenced artifact or evidence of refactor correctness.