When a single LLM query hits a wall on a large refactor, developers often resort to manual, error‑prone edits. In production‑grade codebases, a change that touches dozens of modules can’t be trusted to a one‑shot prompt. This post shows how to construct a multi‑step AI pipeline—what we call the model handshake—where each agent has a narrow responsibility and passes a clean, well‑structured output to the next stage.

---

Why a Single Prompt Falls Short

The scale problem

Even the most advanced language models struggle with context windows that exceed a few thousand tokens. A monolithic refactor that spans multiple files quickly overruns that limit, forcing the model to truncate important information.

Ambiguity and hallucination

When a prompt tries to do everything—identify the change, rewrite code, run tests, and generate documentation—the model’s internal reasoning becomes fuzzy. The result is often code that compiles but behaves incorrectly, or documentation that doesn’t match the implementation.

Lack of verification

A one‑off response gives you no built‑in checkpoint. If the model misinterprets a dependency graph, the entire change set can break the build.

---

Introducing the Model Handshake

The model handshake breaks a complex refactor into a series of deterministic stages. Each stage runs a specialized AI agent that consumes a well‑defined input and produces an output that the next agent can reliably parse. Think of it as a production line for code transformation.

Core stages

1. Scope Discovery – An agent scans the repository (or a subset) and produces a JSON manifest of files, symbols, and dependency edges that will be affected.
2. Change Specification – Using the manifest, a second agent drafts a concise, version‑controlled change plan (e.g., “Rename UserService to AccountService and update all imports”).
3. Code Generation – A code‑focused model receives the plan and emits diffs for each file, adhering to the project’s linting rules.
4. Static Validation – A lightweight analysis agent runs the diffs through a linter and type checker, flagging any violations.
5. Test Adaptation – An agent updates or creates unit tests based on the new signatures, ensuring coverage.
6. Documentation Update – The final agent rewrites inline comments and README sections to reflect the new API.

Each stage returns a JSON envelope that includes a status flag, a human‑readable summary, and the artifact (manifest, plan, diff, etc.). The envelope acts as the handshake token that guarantees the next model receives exactly what it expects.

---

Practical Workflow Example

Below is a simplified workflow that refactors a Node.js service from UserService to AccountService.

Step 1 – Change Specification

The next agent receives the manifest and outputs:

Step 2 – Code Generation

The code‑generation model consumes the plan and returns a diff per file:

Step 3 – Static Validation

A linting agent runs eslint and tsc (if TypeScript) on the diff. If it finds a missing import, it adds a corrective note to the envelope, prompting a retry.

Step 4 – Test Adaptation

The test‑update agent generates new test cases that reflect the renamed class and updated method signatures, ensuring the test suite remains green.

Step 5 – Documentation Update

Finally, the documentation agent rewrites JSDoc blocks and updates the README.md section that describes the service’s public API.

---

Implementing the Handshake in Code

Below is a minimal Node.js orchestrator that wires the stages together using async functions and a simple retry policy.

The orchestrator can be extended with parallelism (e.g., running validation on each diff concurrently) or integrated into CI/CD pipelines using GitHub Actions.

---

Key Takeaways

• Divide and conquer: Split a massive refactor into focused AI stages to stay within model context limits.
• Explicit contracts: Use JSON envelopes to define input/output schemas, reducing hallucination risk.
• Iterative validation: Feed linting or type‑checking results back into the generation stage for automatic correction.
• Automation-friendly: The handshake pattern fits naturally into CI pipelines, enabling zero‑touch refactors after initial configuration.
• Human oversight: Even with a robust pipeline, a final code review is essential; the model’s output should be treated as a draft, not production code.

---

Conclusion

The era of “single‑prompt” AI coding assistance is giving way to orchestrated pipelines where each model plays a specialized role. By adopting the model handshake, development teams can safely automate large‑scale refactors, keep code quality high, and free engineers to focus on architectural decisions rather than repetitive rename‑and‑replace chores. Start by prototyping the scope‑discovery and change‑spec stages in your own repo, then gradually add generation, validation, and documentation agents. The payoff—faster iteration cycles and fewer human errors—quickly becomes evident.

---

Source: The Model Handshake: How to Chain AI Agents for Complex Refactors