Dari-docs: How Parallel Coding Agents Optimize Documentation Without Merge Conflicts

Documentation drift is a coordination problem, not a writing problem. When multiple agents try to fix outdated docs in parallel, they step on each other. Dari-docs solves this by treating documentation updates as a distributed write problem with git worktrees as isolation boundaries.

The core insight: partition the documentation tree spatially, give each agent its own worktree, and merge only after all agents finish their isolated work. This avoids the lock-and-wait pattern that kills parallelism.

The Parallel Agent Problem

Running multiple coding agents against the same repository creates three failure modes:

1. File-level collisions: Two agents edit the same Markdown file simultaneously.
2. Semantic conflicts: Agent A updates a code example while Agent B rewrites the explanation that references it.
3. State drift: Agent B reads a file that Agent A is halfway through modifying.

Traditional solutions serialize agent execution or use pessimistic locking. Dari-docs takes a different approach: spatial partitioning with git worktrees.

Architecture: Worktrees as Agent Sandboxes

Each agent gets its own git worktree, a separate working directory that shares the same .git folder but maintains independent HEAD pointers and staging areas.

Orchestration flow:

1. Task decomposition: The coordinator analyzes the documentation tree and splits it into non-overlapping subtrees (e.g., /api-reference, /guides, /tutorials).
2. Worktree provisioning: For each subtree, create a new worktree from the current branch.
3. Agent dispatch: Assign one agent per worktree with a scoped task (e.g., “update all code examples in /api-reference to match v2.0 API”).
4. Parallel execution: Agents run simultaneously, each modifying only files within their assigned subtree.
5. Sequential merge: After all agents complete, merge worktrees back to the main branch one at a time.

# Coordinator creates isolated worktrees
git worktree add ../dari-api-ref main
git worktree add ../dari-guides main
git worktree add ../dari-tutorials main

# Each agent works in its own directory
agent-1 --workspace=../dari-api-ref --task="update-code-examples"
agent-2 --workspace=../dari-guides --task="fix-broken-links"
agent-3 --workspace=../dari-tutorials --task="add-missing-prerequisites"

# Merge results sequentially
cd ../dari-api-ref && git add -A && git commit -m "Agent 1: API ref updates"
cd ../main-repo && git merge dari-api-ref-branch

Task Distribution Strategy

The coordinator must partition work to minimize cross-agent dependencies. Dari-docs uses a file-tree analysis pass before dispatching agents:

• Dependency graph construction: Parse Markdown files to identify cross-references (links, includes, shared code snippets).
• Clustering: Group files with high inter-dependency into the same partition.
• Boundary enforcement: Agents receive a whitelist of allowed file paths. Attempts to modify files outside the whitelist trigger a coordinator escalation.

Partition Strategy	Parallelism Gain	Conflict Risk	Use Case
Directory-based	High	Low	Modular docs with clear boundaries
Dependency-aware	Medium	Low	Docs with heavy cross-referencing
File-level	Maximum	High	Independent pages (blog posts, changelogs)
Semantic clustering	Medium	Medium	Mixed content types

Conflict Detection and Resolution

Even with spatial partitioning, conflicts can occur when agents need to modify shared resources (e.g., a global glossary, navigation config, or shared code snippet library).

Detection mechanisms:

• Pre-flight check: Before agent dispatch, the coordinator identifies files that appear in multiple task scopes and flags them as contended.
• Runtime monitoring: Agents report file access patterns. If two agents touch the same file, the coordinator pauses the second agent.
• Post-merge validation: After merging all worktrees, run a diff to detect semantic conflicts (e.g., inconsistent terminology across sections).

Resolution strategies:

1. Serialize contended files: If a file is flagged as contended, only one agent can modify it. Other agents skip it or wait.
2. Last-write-wins with review: Merge all changes, then surface conflicts to a human reviewer.
3. Semantic merge: Use an LLM to reconcile conflicting edits by understanding intent (e.g., “both agents tried to update the same example, but Agent A’s version is more complete”).

State Management and Observability

Each agent maintains a local state file in its worktree:

{
  "agent_id": "agent-2",
  "task": "fix-broken-links",
  "workspace": "/tmp/dari-guides",
  "files_modified": ["guides/quickstart.md", "guides/advanced.md"],
  "status": "in_progress",
  "started_at": "2026-05-23T10:15:00Z"
}

The coordinator aggregates these state files to provide a real-time view of progress. If an agent crashes, the coordinator can restart it from the last checkpoint or reassign the task.

Observability hooks:

• File-level telemetry: Track which files each agent touched, how many lines changed, and whether the changes passed validation (e.g., Markdown linting, link checking).
• Agent health checks: Ping agents every 30 seconds. If an agent stops responding, kill the worktree and reassign the task.
• Merge conflict log: Record every conflict detected during the merge phase, along with the resolution strategy applied.

Deployment Shape

Dari-docs runs as a CLI tool or GitHub Action. The typical deployment:

1. Trigger: Manual invocation or scheduled cron job.
2. Coordinator: Runs on a single machine (or GitHub Actions runner) with enough disk space for multiple worktrees.
3. Agents: Spawn as separate processes or containers, each with access to its own worktree directory.
4. Merge: Happens on the coordinator machine after all agents report completion.

For large documentation repositories, the coordinator can distribute agents across multiple machines using a shared filesystem (NFS, S3 with FUSE) or by cloning the repository multiple times.

Failure Modes

Agent hangs or crashes: The coordinator detects stale agents via health checks and kills the worktree. The task is either retried or marked as failed.

Merge conflict: If the sequential merge fails (e.g., two agents modified the same line in a shared file), the coordinator surfaces the conflict to a human reviewer. The system does not attempt automatic resolution beyond simple three-way merges.

Disk space exhaustion: Each worktree is a full checkout of the repository. For large repos, this can consume significant disk space. The coordinator should monitor disk usage and fail fast if space runs low.

Semantic inconsistency: Agents may introduce contradictory information (e.g., Agent A says “use method X” while Agent B says “method X is deprecated”). Post-merge validation can catch some of these issues, but manual review is often required.

Security Boundaries

Agents run with file system access limited to their assigned worktree. However, they still execute arbitrary code (e.g., running linters, building examples). Sandboxing strategies:

• Containerization: Run each agent in a Docker container with read-only access to the main repository and read-write access to its worktree.
• Network isolation: Block outbound network access unless the agent explicitly needs to fetch external resources (e.g., checking link validity).
• Credential scoping: If agents need to commit changes, use scoped Git credentials that only allow writes to specific branches.

Technical Verdict

Use Dari-docs when:

• Your documentation is modular with clear boundaries (e.g., separate directories for API reference, guides, tutorials).
• You need to apply bulk updates across many files (e.g., updating code examples after an API change).
• You can tolerate occasional merge conflicts and have a human in the loop for review.

Avoid it when:

• Your documentation is highly interconnected with frequent cross-references.
• You need real-time collaboration (worktrees add latency and complexity).
• Your repository is too large to clone multiple times (disk space constraints).

The worktree-based approach trades simplicity for parallelism. It works well for batch documentation updates but is overkill for small, incremental changes. If your agents rarely conflict, the overhead of managing multiple worktrees may not be worth it.

Source Links

• Dari-docs GitHub Repository
• Hacker News Discussion