dkod

Multi-Agent Workflows

How to orchestrate multiple AI agents working on the same codebase simultaneously — safely, efficiently, and without conflicts.

Why Multi-Agent?

A single AI agent can write, test, and ship code. But real-world projects have dozens of tasks that can be parallelized:

  • Add input validation to 50 API endpoints
  • Write tests for untested functions
  • Migrate a logging library across the codebase
  • Refactor database queries for performance
  • Update documentation for changed APIs

With Git, each agent needs its own clone, its own branch, and someone to resolve the inevitable merge conflicts. With dkod, all agents share one codebase and the platform handles coordination automatically.

Architecture

Loading diagram...

Each agent gets an isolated session. Changes are invisible to other agents until verified and merged. The WATCH operation provides real-time coordination.

Patterns

Pattern 1: Task Decomposition

Break a large task into independent sub-tasks and assign each to a different agent. For example, split "add input validation to all API endpoints" into separate agents for user endpoints, payment endpoints, and admin endpoints.

Since each agent works on different symbols (different API endpoints), all changes are auto-resolved — no conflicts. The platform handles integration automatically.

Pattern 2: Pipeline (Sequential Dependencies)

Some tasks depend on others. Agent A creates a new module and submits. Once integrated, Agent B connects and sees Agent A's changes in the codebase — it can then update all callers to use the new module.

The WATCH operation enables this coordination: Agent B can watch for Agent A's changeset to be integrated, then start its work with full context of what changed.

Pattern 3: Concurrent with Coordination

Multiple agents work simultaneously on related symbols, using WATCH to stay aware of each other. When one agent modifies a symbol that another agent depends on, the platform sends a real-time notification. The watching agent can refresh its context and adapt its approach before submitting.

This is especially useful when agents work on the same module but different functions — they stay informed without blocking each other.

Pattern 4: Review Agent

Designate one agent as a reviewer that watches all other agents' submissions. When any agent submits a changeset, the review agent receives a notification, analyzes the changes for security issues, code quality, or architectural concerns, and can approve or flag the submission before it's integrated.

dkod also provides built-in review intelligence. Every dk_submit returns an inline review score (1–5), and the full findings are available via dk_review. In the harness, the orchestrator gates approval on the review score — if a changeset scores below 3 or has error-level findings, the generator is re-dispatched to fix the issues before proceeding. See Code Review Intelligence for the full review workflow.

Conflict Resolution

dkod uses a three-tier conflict model designed for multi-agent workloads. Most concurrent changes are auto-resolved. Soft conflicts give agents early warnings. Hard conflicts are rare and surfaced with full context.

Prevention: Write-Time Warnings (Soft Conflicts)

When an agent writes to a symbol that another active session has already modified, the platform returns a soft conflict warning alongside the successful write. The write is not blocked — the warning is an early signal that a potential conflict exists.

The agent can use this signal to proactively adapt: re-read the current state of the contested symbol, adjust its approach, and avoid a hard conflict at submit time. Agents that handle soft conflicts early rarely encounter hard conflicts later.

Detection: Submit-Time Conflicts (Hard Conflicts)

When an agent submits its changeset and the platform detects that the same symbol was modified incompatibly by another session that already integrated, it returns a hard conflict with full context. For each conflicting symbol, the response includes the base version (before either agent touched it), what the other agent changed, and what this agent changed — giving the agent (or user) everything needed to resolve it.

The agent pauses, explains the conflict to the user with a clear summary, and presents the available resolution actions.

Resolution Options

  • proceed (recommended) — unblocks the merge. The agent should then reconnect, re-read the updated code, and re-submit its changeset. This preserves both agents' intent and is the preferred approach.
  • keep_yours — this agent's changes take priority for the conflicting symbols. The other agent's modifications to those specific symbols are overwritten. Non-conflicting changes from both agents are always preserved.
  • keep_theirs — the other agent's changes take priority. This agent's modifications to the conflicting symbols are discarded. Non-conflicting changes from both agents are always preserved.
  • manual — provide custom resolution content for the conflicting symbols. Use when neither version is correct and a hand-crafted merge is needed.
  • Dashboard — the user resolves visually via the web UI, viewing the three-way diff (base, theirs, yours) for each conflicting symbol and choosing a resolution with a single click.

Most multi-agent conflicts are false positives in Git (different functions in the same file) that dkod auto-resolves. True conflicts are rare and well-contextualized. See Conflict Types for the full taxonomy.

Conflict Timeline

This diagram shows how soft and hard conflicts flow between two agents working on overlapping symbols:

Loading diagram...

Best Practices

  • Decompose by symbol, not by file — assign agents to work on different functions/modules, not different files. This minimizes even semantic conflicts.
  • Use WATCH for dependencies — if your agent's work depends on specific symbols, watch them for changes
  • Set verification gates — ensure all agent submissions pass type checking and affected tests before merging
  • Start with auto-rebase — let dkod automatically rebase compatible changes. Only intervene for true conflicts.
  • Monitor with agent telemetry — track session count, submission rate, conflict rate to optimize your workflow

Next Steps