Integration Guides as Agent Outputs

The typical parallel agent build ends the same way: four modules completed in parallel, zero time saved in integration.

The integration agent opens four codebases, reads each module, guesses at the constructor signature, misreads a required config key, wires two modules in the wrong order, and produces a bot.py that crashes on startup. You spend the next two hours in the files yourself, doing what the agent should have done.

The InDecision discord bot build did not end that way.

Four modules. Four agents. Built in parallel. Zero merge conflicts. Single integration pass. The integration agent never opened a source file. It read four documents and wired four modules without a single question.

The difference was the integration guide.

What the Build Looked Like

Four modules were built simultaneously by four separate agents:

• price_alerts.py — monitors price thresholds, sends alerts to Discord channels
• bias_monitoring.py — tracks InDecision framework bias signals, reports on schedule
• signal_notifications.py — receives external signals, formats and delivers to Discord
• admin_commands.py — slash commands for runtime config changes

Each agent's scope was explicit: build the module AND produce a *_integration.md file alongside it. Not a comment block. Not a docstring. A standalone document with exact wiring instructions for an integration agent that has never seen your code.

What the Integration Guide Contains

The format that worked:

# price_alerts_integration.md

## Module: price_alerts.py
## Entry point: PriceAlertMonitor(config, discord_client)

## bot.py wiring — add to setup_hook():
price_monitor = PriceAlertMonitor(config=bot.config, discord_client=bot)
await price_monitor.start()

## bot.py wiring — add to on_ready():
await price_monitor.sync_channels()

## Required config keys:
PRICE_ALERT_CHANNEL_ID=<channel_id>
PRICE_CHECK_INTERVAL=60  # seconds

## Do NOT:
- Import price_alerts.py directly into on_message handlers
- Call PriceAlertMonitor.start() more than once

Six sections. Every section is exact. No section requires interpretation.

The entry point is the full constructor call, not "instantiate the class." The wiring instructions name the exact method in bot.py and the exact call to add. The config section shows the key names and example values, not descriptions of what the config should contain. The DO NOT section encodes the failure modes the module author already discovered.

Why Zero Merge Conflicts

Merge conflicts happen when two agents write to the same lines of the same file. In a parallel build without coordination, the probability of this approaches 1 as module count grows — every module needs a line in bot.py, and four agents writing to bot.py simultaneously is a conflict waiting to happen.

The integration guide pattern eliminates the source conflict entirely. Module agents do not touch bot.py. They write only their module files. The integration agent is the sole author of bot.py changes, applying guides sequentially.

Sequential application of four guides to bot.py:

1. Apply price_alerts_integration.md — add two lines to setup_hook(), one line to on_ready()
2. Apply bias_monitoring_integration.md — add two lines to setup_hook()
3. Apply signal_notifications_integration.md — add one line to setup_hook(), register one event handler
4. Apply admin_commands_integration.md — register slash command group

Four guides. Twelve lines added to bot.py. No exploration required. No conflicts possible.

The Prompt Addition That Produces Good Guides

Module agents do not produce integration guides by default. You have to ask for them explicitly, and you have to specify the format:

After implementing the module, produce integration_guide.md with:
1. The exact class/function signature (full constructor call, not pseudocode)
2. The exact lines to add to bot.py/main.py, with context:
   which function they go in, and before/after what existing code
3. Required config keys with example values
4. Explicit DO NOT instructions for common misuse patterns

The integration agent will use ONLY this guide. It will not read your source code.
Write the guide assuming the integration agent is competent but has zero context
about your module's implementation.

The final sentence is the most important. "The integration agent will not read your source code" forces the module agent to put everything the integration agent needs into the guide. Without that constraint, agents write guides that say "refer to the module docstrings for details" — which reintroduces the exploration step.

The Broader Principle

The integration guide pattern is an instance of a broader rule: every parallel work unit should produce a handoff artifact.

Code is not a handoff artifact. Code requires exploration, interpretation, and inference. A guide that specifies exact interfaces, exact wiring points, and exact failure modes is a handoff artifact. It converts the integration phase from "explore and guess" to "read and apply."

The pattern applies anywhere an integration step follows a parallel build:

• FastAPI routers wired into an application factory
• Background worker modules registered to a scheduler
• Webhook handlers added to an event dispatcher
• Plugin modules loaded by a host process

Any system where N independently-built modules need to share a host entry point is a candidate. The Discord bot is the example. The pattern is the principle.

The One Discipline the Pattern Requires

Module agents must produce guides with exact copy-paste instructions — not pseudocode, not descriptions, not references to source code.

"Add the monitor to setup_hook" is pseudocode. It requires the integration agent to look up what monitor means, what setup_hook looks like, and how to add something to it.

price_monitor = PriceAlertMonitor(config=bot.config, discord_client=bot) on a line inside setup_hook() is exact copy-paste. It requires nothing from the integration agent except the ability to place text at the right position.

The discipline is enforced in the module agent prompt: "Write the guide assuming the integration agent will not read your source code." That constraint produces guides that can stand alone. Guides that stand alone produce integrations that complete without human intervention.

Four agents. Four modules. Four guides. One integration pass. Zero merge conflicts.

That is the pattern.