APAW/.kilo/rules/parallel-coordination.md

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)

## 🔒 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

<!-- GNS_EVENT: {
  "type": "task_claim",
  "agent": "lead-developer",
  "issue": 113,
  "files": ["app/Models/Product.php"],
  "worktree": ".kilo/worktrees/113/lead-developer/",
  "claimed_at": "2026-05-18T16:00:00Z",
  "estimated_duration_min": 15,
  "timestamp": "2026-05-18T16:00:00Z"
} -->

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):

## 🔓 Claim Released

| Field | Value |
|-------|-------|
| **Agent** | `{agent_name}` |
| **Issue** | #{issue_number} |
| **Released** | {timestamp} |
| **Files** | `{file1}`, `{file2}`, ... |
| **Status** | success / fail / blocked |

Footer:

<!-- GNS_EVENT: {
  "type": "task_claim_release",
  "agent": "lead-developer",
  "issue": 113,
  "files": ["app/Models/Product.php"],
  "released_at": "2026-05-18T16:15:00Z",
  "status": "success",
  "timestamp": "2026-05-18T16:15:00Z"
} -->

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