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.
This commit is contained in:
@@ -70,11 +70,10 @@ This is the most critical coordinator responsibility. Follow it exactly:
|
||||
git merge feat/<task-name> --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/<task-id>.md
|
||||
# status: blocked
|
||||
# ## Notes
|
||||
# Blocked: <reason from agent's message>
|
||||
git add tasks/<task-id>.md
|
||||
git commit -m "blocked(<task-id>): <reason>"
|
||||
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 <id> 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/<file>.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
|
||||
|
||||
|
||||
@@ -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 <task-id>: <reason>", level: "blocking"}})
|
||||
worktree({action: "notify", args: {message: "Blocked on <task-id>: <detailed explanation including what was attempted, what failed, and suggested resolution>", 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user