From a69a4d19d0238f26d9bb9e5022e5c3e4411d7999 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 28 Jan 2026 10:47:36 -0500 Subject: [PATCH] feat(projman): add file conflict prevention for parallel agents (#234) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add pre-dispatch conflict detection: - Analyze target files for each task before parallel dispatch - Check for file overlap between tasks in same batch - If overlap detected, sequentialize those specific tasks - Example analysis showing conflict detection workflow Branch isolation protocol: - Each task MUST have its own branch - Never have two agents work on the same branch - Sequential merge after completion (not simultaneous) - Handle merge conflicts by stopping second task Conflict resolution rules: - Same file → MUST sequentialize - Same directory → Usually safe, review - Shared config → Sequentialize - Shared test fixture → Sequentialize or assign different files This prevents parallel agents from modifying the same files and causing git merge conflicts. Closes #234 Co-Authored-By: Claude Opus 4.5 --- plugins/projman/agents/orchestrator.md | 71 +++++++++++++++++++++--- plugins/projman/commands/sprint-start.md | 61 ++++++++++++++++++++ 2 files changed, 123 insertions(+), 9 deletions(-) diff --git a/plugins/projman/agents/orchestrator.md b/plugins/projman/agents/orchestrator.md index ab5f21e..2d0b1c0 100644 --- a/plugins/projman/agents/orchestrator.md +++ b/plugins/projman/agents/orchestrator.md @@ -147,11 +147,56 @@ Relevant Lessons: Ready to start? I can dispatch multiple tasks in parallel. ``` -### 2. Parallel Task Dispatch +### 2. File Conflict Prevention (Pre-Dispatch) -**When starting execution:** +**BEFORE dispatching parallel agents, analyze file overlap.** -For independent tasks (same batch), spawn multiple Executor agents in parallel: +**Conflict Detection Workflow:** + +1. **Read each issue's checklist/body** to identify target files +2. **Build file map** for all tasks in the batch +3. **Check for overlap** - Same file in multiple tasks? +4. **Sequentialize conflicts** - Don't parallelize if same file + +**Example Analysis:** +``` +Analyzing Batch 1 for conflicts: + +#45 - Implement JWT service + → auth/jwt_service.py, auth/__init__.py, tests/test_jwt.py + +#48 - Update API documentation + → docs/api.md, README.md + +Overlap check: NONE +Decision: Safe to parallelize ✅ +``` + +**If Conflict Detected:** +``` +Analyzing Batch 2 for conflicts: + +#46 - Build login endpoint + → api/routes/auth.py, auth/__init__.py + +#49 - Add auth tests + → tests/test_auth.py, auth/__init__.py + +Overlap: auth/__init__.py ⚠️ +Decision: Sequentialize - run #46 first, then #49 +``` + +**Conflict Resolution:** +- Same file → MUST sequentialize +- Same directory → Usually safe, review file names +- Shared config → Sequentialize +- Shared test fixture → Assign different fixture files or sequentialize + +### 3. Parallel Task Dispatch + +**After conflict check passes, dispatch parallel agents:** + +For independent tasks (same batch) WITH NO FILE CONFLICTS, spawn multiple Executor agents in parallel: ``` Dispatching Batch 1 (2 tasks in parallel): @@ -167,6 +212,14 @@ Task 2: #48 - Update API documentation Both tasks running in parallel. I'll monitor progress. ``` +**Branch Isolation:** Each task MUST have its own branch. Never have two agents work on the same branch. + +**Sequential Merge Protocol:** +1. Wait for task to complete +2. Merge its branch to development +3. Then merge next completed task +4. Never merge simultaneously + **Branch Naming Convention (MANDATORY):** - Features: `feat/-` - Bug fixes: `fix/-` @@ -177,7 +230,7 @@ Both tasks running in parallel. I'll monitor progress. - `fix/46-login-timeout` - `debug/47-investigate-memory-leak` -### 3. Generate Lean Execution Prompts +### 4. Generate Lean Execution Prompts **NOT THIS (too verbose):** ``` @@ -222,7 +275,7 @@ Dependencies: None (can start immediately) Ready to start? Say "yes" and I'll monitor progress. ``` -### 4. Status Label Management +### 5. Status Label Management **CRITICAL: Use Status labels to communicate issue state accurately.** @@ -284,7 +337,7 @@ update_issue( - Remove Status labels when closing successfully - Always add comment explaining status changes -### 5. Progress Tracking (Structured Comments) +### 6. Progress Tracking (Structured Comments) **CRITICAL: Use structured progress comments for visibility.** @@ -380,7 +433,7 @@ add_comment( - Notify that new tasks are ready for execution - Update the execution queue -### 6. Monitor Parallel Execution +### 7. Monitor Parallel Execution **Track multiple running tasks:** ``` @@ -398,7 +451,7 @@ Batch 2 (now unblocked): Starting #46 while #48 continues... ``` -### 7. Branch Protection Detection +### 8. Branch Protection Detection Before merging, check if development branch is protected: @@ -428,7 +481,7 @@ Closes #45 **NEVER include subtask checklists in MR body.** The issue already has them. -### 8. Sprint Close - Capture Lessons Learned +### 9. Sprint Close - Capture Lessons Learned **Invoked by:** `/sprint-close` diff --git a/plugins/projman/commands/sprint-start.md b/plugins/projman/commands/sprint-start.md index d874958..65ca4f7 100644 --- a/plugins/projman/commands/sprint-start.md +++ b/plugins/projman/commands/sprint-start.md @@ -72,6 +72,67 @@ Parallel Execution Batches: **Independent tasks in the same batch run in parallel.** +## File Conflict Prevention (MANDATORY) + +**CRITICAL: Before dispatching parallel agents, check for file overlap.** + +**Pre-Dispatch Conflict Check:** + +1. **Identify target files** for each task in the batch +2. **Check for overlap** - Do any tasks modify the same file? +3. **If overlap detected** - Sequentialize those specific tasks + +**Example Conflict Detection:** +``` +Batch 1 Analysis: + #45 - Implement JWT service + Files: auth/jwt_service.py, auth/__init__.py, tests/test_jwt.py + + #48 - Update API documentation + Files: docs/api.md, README.md + + Overlap: NONE → Safe to parallelize + +Batch 2 Analysis: + #46 - Build login endpoint + Files: api/routes/auth.py, auth/__init__.py + + #49 - Add auth tests + Files: tests/test_auth.py, auth/__init__.py + + Overlap: auth/__init__.py → CONFLICT! + Action: Sequentialize #46 and #49 (run #46 first) +``` + +**Conflict Resolution Rules:** + +| Conflict Type | Action | +|---------------|--------| +| Same file in checklist | Sequentialize tasks | +| Same directory | Review if safe, usually OK | +| Shared test file | Sequentialize or assign different test files | +| Shared config | Sequentialize | + +**Branch Isolation Protocol:** + +Even for parallel tasks, each MUST run on its own branch: +``` +Task #45 → feat/45-jwt-service (isolated) +Task #48 → feat/48-api-docs (isolated) +``` + +**Sequential Merge After Completion:** +``` +1. Task #45 completes → merge feat/45-jwt-service to development +2. Task #48 completes → merge feat/48-api-docs to development +3. Never merge simultaneously - always sequential to detect conflicts +``` + +**If Merge Conflict Occurs:** +1. Stop second task +2. Resolve conflict manually or assign to human +3. Resume/restart second task with updated base + ## Branch Naming Convention (MANDATORY) When creating branches for tasks: