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)

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

```markdown
## 🔓 Claim Released

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

Footer:
```html
<!-- 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