# Parallel Agent Coordination Rules Distributed task claiming protocol for parallel agent execution on the same codebase without conflicts. ## Problem When orchestrator spawns `lead-developer`, `frontend-developer`, and `backend-developer` in parallel β€” or multiple `lead-developer` invocations on different modules β€” they may: - Write to the same files (race condition) - Create migrations with colliding timestamps - Overwrite each other’s work when merging worktrees back to `dev` - Run conflicting `npm install` / `composer install` in shared workspace ## Principle: Gitea Comments as Lock Store The lock state lives in Gitea, not in RAM, files, or a new service. Every agent **reads** claims from issue comments before starting, and **writes** claims before modifying files. ## Claim Protocol ### 1. Claim Format (Gitea Comment) ```markdown ## πŸ”’ Task Claim | Field | Value | |-------|-------| | **Agent** | `{agent_name}` | | **Issue** | #{issue_number} | | **Claimed** | {timestamp} | | **Files** | `{file1}`, `{file2}`, ... | | **Worktree** | `.kilo/worktrees/{issue}/{agent}/` | ### Claimed Resources - `{filepath}` (type: file/module/migration) ### Estimated Duration {minutes} minutes ``` ### Machine-Readable Footer ```html ``` ### 2. Overlap Check (Orchestrator β€” Before Parallel Spawn) Before spawning ANY parallel group: ``` 1. For each agent in group: a. Extract `files_to_modify` from task prompt b. Normalize paths (absolute, deduplicated) 2. Compute intersection of all file sets 3. If intersection β‰  βˆ…: β†’ DO NOT spawn in parallel β†’ Serialize conflicting agents β†’ Log to `.kilo/logs/parallel-coordination.jsonl`: {"ts":"2026-05-18T16:00:00Z","action":"serialized","reason":"file_overlap","agents":[...],"overlapping_files":[...]} 4. If intersection = βˆ…: β†’ Post `## πŸ”’ Task Claims` comment with ALL agent claims β†’ Wait for Gitea API confirmation (comment visible) β†’ Only THEN spawn agents ``` ### 3. Agent Entry β€” Verify No Conflicts Every agent MUST execute on entry: ``` 1. Read issue body checkpoint 2. Read last 10 comments (descending) looking for "## πŸ”’ Task Claim" 3. Parse GNS_EVENT footers of type "task_claim" 4. If ANY claimed file intersects with agent's `files_to_modify`: β†’ STOP immediately β†’ Post `## 🚫 Blocked β€” File Claimed by Another Agent` β†’ Recommend retry or serialization to orchestrator 5. If no intersection β†’ proceed ``` ### 4. Claim Release On agent completion (success, fail, or blocked): ```markdown ## πŸ”“ Claim Released | Field | Value | |-------|-------| | **Agent** | `{agent_name}` | | **Issue** | #{issue_number} | | **Released** | {timestamp} | | **Files** | `{file1}`, `{file2}`, ... | | **Status** | success / fail / blocked | ``` Footer: ```html ``` ### 5. Deadlock Prevention (Lease Expiration) Claims auto-expire after a configurable timeout. Default = `checkpoint.budget.remaining * 0.05` minutes (e.g., 1000 tokens remaining = 50 min). **If an agent crashes** β†’ claim is stale when next orchestrator pass reads it. **Detection rule**: A claim is stale if `claimed_at + estimated_duration_min * 2 < now()`. Recovery: ``` 1. Orchestrator detects stale claim β†’ ignore it 2. Log: `{..., "action": "stale_claim_detected", "old_claim": {...}}` 3. Post comment: `## πŸ”„ Stale Claim Detected β€” Auto-Released` 4. Allow new agent to claim the same files ``` ### 6. Migration Timestamp Collision Prevention When multiple agents create migrations, orchestrator MUST assign sequential timestamps: ``` 1. Before spawning, reserve migration sequence: - Read latest migration timestamp from `database/migrations/` - Assign: `+1 min` per parallel agent - e.g., Agent A: `2026_05_18_160000`, Agent B: `2026_05_18_160001` 2. Include assigned timestamp in task prompt 3. Agent MUST use assigned timestamp (never self-generate) ``` ## Conflict Resolution Order When overlap is detected: 1. **Pre-emptive** (orchestrator level): Serialize agents with overlapping file sets. Serialize β€” do NOT abort. 2. **At runtime** (agent level): If an agent discovers a claim collision β†’ block and advise serialization. 3. **Post-merge** (git level): If two worktrees modified the same file β†’ `the-fixer` resolves merge conflict (only if explicit merge conflict detected). ## Orchestrator Integration ### When to Apply - Before ANY parallel group spawn in `orchestrator.md` Β§ Parallelization Protocol - Before spawning `implementation_phase` parallel group (lead-developer + frontend-developer + backend-developer) - When user requests explicit parallel work on multiple modules ### What to Modify in orchestrator.md Add between "identify parallel group" and "spawn agents" in Parallelization Protocol: ``` 2b. **Overlap Verification (MANDATORY before parallel spawn)**: - Extract `files_to_modify` from each agent's task prompt - Compute intersection of all file sets - If intersection β‰  βˆ… β†’ serialize conflicting agents - If intersection = βˆ… β†’ post ## πŸ”’ Task Claims comment - Wait for comment visibility via Gitea API - Only after confirmation β†’ spawn agents ``` ### Integration with Worktrees Claims are **per-worktree**: - Agent A claims `app/Models/Product.php` in `.kilo/worktrees/113/lead-developer/` - Agent B can also claim `app/Models/Product.php` in `.kilo/worktrees/113/backend-developer/` - But merge to `dev` will conflict β†’ serialization is required **before spawn** ## Prohibited Actions - DO NOT spawn parallel agents without overlap check - DO NOT let agent self-generate migration timestamps in parallel mode - DO NOT hold claim state in RAM only β€” always write to Gitea - DO NOT ignore stale claims β€” always detect and auto-release - DO NOT allow claim without Gitea comment visibility confirmation - DO NOT modify files outside claimed set - DO NOT block entire issue for one file conflict β€” only serialize conflicting agents