From df3dd825720b3fef26e0d088765653ada987fce2 Mon Sep 17 00:00:00 2001 From: "glm-5.1" Date: Mon, 11 May 2026 11:38:52 +0000 Subject: [PATCH] feat: add Safe Exit protocol for blocked tasks under new task file convention Agents no longer commit task files, so when an agent safe-exits: - Agent notifies coordinator with detailed blocking message (what happened, what was tried, suggested fix) - Agent commits any partial source code progress and pushes - Coordinator updates task file on main with status: blocked and the reason - Coordinator attempts resolution, spawns new agent if resolved Also removed stale 'task file conflicts' from merge workflow since agents no longer commit task files. --- .opencode/agents/coordinator.md | 53 +++++++++++++++---- .opencode/agents/implementation-specialist.md | 12 +++-- 2 files changed, 51 insertions(+), 14 deletions(-) diff --git a/.opencode/agents/coordinator.md b/.opencode/agents/coordinator.md index aa9c324..2e9d94b 100644 --- a/.opencode/agents/coordinator.md +++ b/.opencode/agents/coordinator.md @@ -70,11 +70,10 @@ This is the most critical coordinator responsibility. Follow it exactly: git merge feat/ --no-edit ``` - If merge conflicts occur: - - **Source code conflicts between parallel tasks** that modify the same file: Resolve them yourself. Read the conflicted file, understand both sides, and combine the changes. Both sets of changes are valid — they were just developed in parallel. - - **Task file conflicts** (`tasks/*.md`): These happen when multiple agents commit task files. Remove the conflicting task files before merging (`rm -rf tasks/`), merge, then restore from backup. Or use `git checkout --theirs tasks/` to accept the incoming versions. - - **Doc conflicts**: Read both sides and keep the most recent/complete version. Often one branch cleaned up drift tables while another updated status. - - **If truly unresolvable**: Message the original agent's session for guidance, or ask the user. + If merge conflicts occur: + - **Source code conflicts between parallel tasks** that modify the same file: Resolve them yourself. Read the conflicted file, understand both sides, and combine the changes. Both sets of changes are valid — they were just developed in parallel. + - **Doc conflicts**: Read both sides and keep the most recent/complete version. Often one branch cleaned up drift tables while another updated status. + - **If truly unresolvable**: Message the original agent's session for guidance, or ask the user. 3. **Validate after every merge:** ```bash @@ -110,6 +109,38 @@ When multiple tasks complete around the same time, merge them **one at a time** If two tasks modify the same source files and were developed in parallel, you WILL get merge conflicts. This is expected — resolve them. +### When an Agent Safe-Exits (Blocked) + +When an agent sends a `level: "blocking"` notification, it has hit an untenable situation and is exiting. This is the Safe Exit protocol — it's important, don't ignore it. + +1. **Read the blocking message carefully.** The agent should have included what it was trying to do, what went wrong, what it tried, and suggested resolution. + +2. **Get more context if needed:** + ```text + memory({tool: "messages", args: {sessionId: "ses_", role: "assistant"}}) + ``` + Read the agent's session to understand what actually happened. + +3. **Update the task file on main:** + ```bash + # Edit tasks/.md + # status: blocked + # ## Notes + # Blocked: + git add tasks/.md + git commit -m "blocked(): " + git push origin main + ``` + +4. **Try to resolve the blocker:** + - Missing context? Send it via `worktree({action: "message", ...})` — but you'll need to spawn a new agent/session for the same task + - Ambiguous architecture? Ask the user to clarify + - Scope too large? Decompose into smaller tasks + - External dependency (tool bug, env issue)? Escalate to user + +5. **If you can resolve it:** Spawn a new agent for the same task with the additional context or adjusted scope. + **If you can't:** Move on to other independent work and flag the blocked task for later resolution. + ## Spawning Agents ### Constructing the Spawn Prompt @@ -238,18 +269,18 @@ When multiple agents commit task files in parallel branches, merging causes conf ### Coordinator Responsibilities -After merging a task's source code changes into main, update the task file: +After a task completes and is merged, update the task file on main: 1. Find the task file in `tasks/` -2. Update frontmatter `status: completed` (or `blocked` / `failed`) +2. Update frontmatter `status: completed` (or `blocked` if the agent safe-exited) 3. Add a brief summary to the `## Summary` section (from the agent's completion notification) 4. Commit on main: `git commit -m "chore: update task status to completed"` +5. Push main ### If an Agent Accidentally Commits a Task File -If `git merge` complains about conflicting task files: -- Don't spend time resolving them — it's just metadata -- Use `git checkout --theirs tasks/` to accept the incoming version, or temporarily remove `tasks/` before merging -- After merge, update the task files on main with correct status +If `git merge` complains about conflicting task files (this shouldn't happen with the new convention, but just in case): +- Use `git checkout --theirs tasks/.md` to accept the incoming version, or remove the local copy before merging +- After merge, update the task file on main with the correct status ## Context Management diff --git a/.opencode/agents/implementation-specialist.md b/.opencode/agents/implementation-specialist.md index d0bddd6..2d2a0cf 100644 --- a/.opencode/agents/implementation-specialist.md +++ b/.opencode/agents/implementation-specialist.md @@ -149,11 +149,17 @@ When task becomes untendable: ### Process 1. **Stop** - don't force through -2. **Notify coordinator**: +2. **Notify coordinator** with a detailed blocking message. Include: + - What you were trying to do + - What went wrong (specific error, missing dep, ambiguous spec, etc.) + - What you've already tried + - What you think would resolve it (if you know) ```text - worktree({action: "notify", args: {message: "Blocked on : ", level: "blocking"}}) + worktree({action: "notify", args: {message: "Blocked on : ", level: "blocking"}}) ``` -3. **Exit** - coordinator handles escalation +3. **Commit any partial source code progress** if it's coherent (you may not have any — that's fine) +4. **Push your branch** so the coordinator can inspect your work if needed +5. **Exit** - coordinator handles escalation ### Wrong Directory Recovery