Agentic Planning For Cross Package Refactors Implementation Guide: practical systems guide

Large-scale refactors that span multiple packages often fail not because the transformation is complex, but because planning doesn't account for how changes ripple. When you rename a function used in fifteen packages, or change an interface contract, or migrate a shared utility, the work splits into independent subtasks that must happen in a specific order. Manual orchestration of these changes burns hours in dependency tracking and merge conflicts. Agentic systems that can plan, constrain, and validate atomic changes across package boundaries turn multi-day coordination exercises into repeatable workflows.

Why cross-package refactors break traditional workflows

Most teams approach cross-package refactors with a "big bang" PR or a careful sequencing of manual PRs. The big bang fails review: a diff touching 40 files across six packages is unauditable. Manual sequencing works but requires constant context switching—you open PR 1 in package A, wait for CI, then realize package B depends on an old signature and now you're rebasing.

The core issue is **lack of explicit dependency modeling**. Your build tool knows package dependencies, but your refactor plan lives in a ticket or a Slack thread. When the agent can't see that `@core/auth` must change before `@api/users`, it proposes changes in arbitrary order or bundles them incorrectly.

Building an agent loop that respects package graphs

An effective planning loop for cross-package work treats the dependency graph as a first-class constraint. Start with a topological sort of affected packages, then chunk the refactor into stages:

1. **Leaf packages first**: Changes that have no downstream dependents in the refactor scope go first. If you're renaming `logger.info()` to `logger.log()`, packages that *only* consume the logger get updated before packages that re-export it.

2. **Strict validation gates**: Each stage must pass full compile + lint + test before the next stage begins. This surfaces contract mismatches immediately—if stage 1 changes an export shape but stage 2 assumes the old shape, the compile gate catches it.

3. **Explicit handoff points**: The plan should encode "package A change complete → unblock package B changes." Goatfied's constraint system lets you specify pre-conditions: "only propose changes to `@api/handlers` after `@core/schema` diffs have passed CI."

Here's a minimal example plan structure:

refactor: rename-auth-method

stages:

  - name: Update core interfaces

    packages: ['@core/auth']

    changes:

      - file: src/auth.ts

        operation: rename_export

        from: validateToken

        to: verifyToken

    validation:

      - compile

      - test:unit

  

  - name: Update direct consumers

    depends_on: [Update core interfaces]

    packages: ['@api/users', '@api/sessions']

    changes:

      - pattern: 'import.*validateToken.*from.*@core/auth'

        replace: 'import { verifyToken } from "@core/auth"'

    validation:

      - compile

      - lint

      - test:integration

This isn't hypothetical YAML—it's the kind of structured plan an agent can execute sequentially, retrying individual stages on failure without restarting from scratch.

Constraining diff size for reviewability

Even with correct ordering, a cross-package refactor can produce diffs too large to review. The fix is to **bound changes per PR by impact surface**, not by package. A single package might need three PRs if it has high churn; two small packages might combine into one PR if the changes are trivial import updates.

Set a maximum changed-line budget per PR—150 lines works well for most teams. When the agent plans a stage that would exceed the budget, split it:

• **By file clusters**: Group files that change together (a module and its test) into one PR, separate from unrelated files in the same package.
• **By change type**: Pure renames separate from signature changes. The rename PR is mechanical and fast to review; the signature change PR gets more scrutiny.

Goatfied enforces this through edit constraints: when you configure `max_diff_lines: 150`, the agent automatically splits planned work into multiple branches. Each branch gets its own compile/lint/test cycle, so you never merge a partial change that breaks CI.

Handling breaking changes across package boundaries

The hardest refactors involve breaking changes—removing a deprecated API, tightening a type, or changing a return value. If downstream packages haven't updated their usage, they break.

The standard answer is a two-phase migration: introduce the new API alongside the old, update consumers, then remove the old. Agentic planning makes this tractable:

1. **Phase 1 (additive)**: Agent adds the new API to the core package, marks the old one deprecated, ships it. No downstream breakage yet.

2. **Phase 2 (migration)**: Agent updates each consuming package to use the new API. Because the old API still exists, each update compiles independently. These can happen in parallel or sequentially depending on your CI capacity.

3. **Phase 3 (removal)**: Once all consumers migrate, agent removes the deprecated API from core. The validation gate confirms zero usage before proceeding.

This requires the agent to understand "safe intermediate states." Goatfied's plan-then-validate loop checks each intermediate commit against the full test suite, not just the final state. If phase 2 breaks a consumer, the retry logic can adjust the migration PR before you ever see a red CI badge.

Practical workflows: manual trigger vs. continuous

Two common patterns emerge:

**On-demand refactor runs**: An engineer writes a high-level plan (e.g., "rename validateToken to verifyToken across all packages"), the agent expands it into stages, executes sequentially, and opens one PR per stage. Human reviews each PR before the next stage starts. This fits teams that want tight control and have moderate refactor volume.

**Continuous dependency updates**: For repetitive tasks like bumping a shared library version across packages, the agent runs on a schedule (nightly or per-release). It generates a multi-stage plan, executes it, and auto-merges PRs that pass all gates. Teams using this pattern typically require code-owner approval for core package changes but allow bot-driven updates for leaf packages.

Both workflows rely on the same core loop: plan → constrain → edit → validate → retry. The difference is human gating between stages.

When to keep humans in the loop

Not every cross-package refactor belongs in an agentic workflow. If the refactor involves subtle logic changes—performance optimizations, security fixes, or algorithm updates—human judgment matters at every file. Agents excel at mechanical transformations (renames, import updates, config changes) where correctness is verifiable by the compiler and test suite.

A good heuristic: if you can describe the refactor as a find-and-replace with context-aware constraints, it's a candidate for agentic planning. If the description includes "depending on usage patterns, choose strategy A or B," keep a human in the loop for the decision points and let the agent handle execution.

Related reading

• [Self-hosted AI coding assistants: a complete Goatfied deployment guide](/blog/self-hosted-ai-coding-assistants-goatfied-deployment-guide)
• [Deployment playbook #2: practical Goatfied tactics for shipping PRs](/blog/goatfied-deployment-playbook-2)