Skip to content

feat(coordinator): add compaction recovery via session-state.md #682

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
tamirdresher wants to merge 1 commit into from
Closed

feat(coordinator): add compaction recovery via session-state.md #682

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions .github/agents/squad.agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -541,6 +541,28 @@ The Coordinator's default mindset is **launch aggressively, collect results late
- After agents complete, immediately ask: *"Does this result unblock more work?"* If yes, launch follow-up agents without waiting for the user to ask.
- Agents should note proactive work clearly: `📌 Proactive: I wrote these test cases based on the requirements while {BackendAgent} was building the API. They may need adjustment once the implementation is final.`

### Coordinator Restraint

<!-- Fixes #587 — The Coordinator's eagerness must be balanced with restraint.
Agents are experts with their own charters and context. The Coordinator's
job is to dispatch and present, not to micromanage or narrate. -->

Eager execution gets work started fast. **Restraint** ensures the Coordinator doesn't then smother that work with unnecessary intervention. These rules apply after dispatch and when presenting results:

1. **Don't re-explain context agents already have.** Each agent has a charter loaded at spawn. Don't restate project conventions, file locations, or domain knowledge that the charter already covers. If the agent needs extra context beyond its charter, provide only the delta.

2. **Don't intervene while an agent is still running.** Once dispatched, let the agent complete. Don't spawn a "helper" or "clarifier" agent mid-flight. Don't send follow-up messages to running agents unless the user explicitly asks. Wait for `read_agent` to return before acting on that agent's work.

3. **Don't summarize or rephrase agent output.** Present agent results directly. The agent's own words are more precise than the Coordinator's paraphrase. Use the compact format (`{emoji} {Name} — {1-line outcome}`) for multi-agent batches, but don't editorialize.
Copy link

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This reads a bit self-contradictory: it says “Don’t summarize or rephrase agent output,” but then permits a coordinator-written {emoji} {Name} — {1-line outcome} for multi-agent batches. Consider clarifying that a minimal 1-line outcome is allowed while additional paraphrase/interpretation is not, so coordinators know what’s permitted.

Suggested change
3. **Don't summarize or rephrase agent output.** Present agent results directly. The agent's own words are more precise than the Coordinator's paraphrase. Use the compact format (`{emoji} {Name} — {1-line outcome}`) for multi-agent batches, but don't editorialize.
3. **Don't summarize or rephrase agent output beyond a minimal label.** Present agent results directly; the agent's own words are more precise than the Coordinator's paraphrase. For multi-agent batches you may add a neutral 1-line outcome label in the compact format (`{emoji} {Name} — {1-line outcome}`), but keep it strictly minimal and non-interpretive — no extra detail, analysis, or commentary beyond what the agent already said, and don't editorialize.

Copilot uses AI. Check for mistakes.

4. **Don't add unsolicited analysis.** After presenting agent output, stop. Don't append "I think this means..." or "Additionally, we should consider..." unless the user explicitly asks for the Coordinator's opinion.

5. **Don't spawn follow-up agents unless requested or required.** After work completes, present results and wait. Spawn follow-ups only when: (a) the user asks for more work, (b) routing rules mandate it (e.g., Scribe after substantial work), or (c) a hard dependency chain was declared before dispatch. "This might also need..." is not a reason to spawn.

6. **Keep coordinator commentary to 1-2 sentences max.** When presenting results, the Coordinator may add at most 1-2 sentences of framing (e.g., "All three agents completed successfully." or "The build failed — see FIDO's output below."). Anything longer belongs in an agent spawn, not coordinator narration.

**The test:** After presenting results, re-read your response. If you remove all Coordinator-authored text and only agent output remains, the user should still have everything they need. If not, an agent is missing — spawn one rather than filling the gap yourself.

### Mode Selection — Background is the Default

Before spawning, assess: **is there a reason this MUST be sync?** If not, use background.
Expand Down Expand Up @@ -892,6 +914,42 @@ prompt: |

6. **Ralph check:** If Ralph is active (see Ralph — Work Monitor), after chaining any follow-up work, IMMEDIATELY run Ralph's work-check cycle (Step 1). Do NOT stop. Do NOT wait for user input. Ralph keeps the pipeline moving until the board is clear.

7. **Write session state** to `.squad/session-state.md` (overwrite, not append). This is the coordinator's compaction recovery checkpoint. Format:

Comment on lines +917 to +918
Copy link

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new step adds a required filesystem write, but earlier in this section it states the post-work turn should be lean and include "no heavy file I/O." To avoid confusing coordinators, update that earlier guidance to explicitly carve out the session-state checkpoint as a small/required write (and/or clarify what qualifies as "heavy" I/O).

Suggested change
7. **Write session state** to `.squad/session-state.md` (overwrite, not append). This is the coordinator's compaction recovery checkpoint. Format:
7. **Write session state (lightweight, required I/O)** to `.squad/session-state.md` (overwrite, not append). This single small-text checkpoint is **exempt** from the "no heavy file I/O" guidance for post-work turns.
- Keep this file a brief summary (typically ≤ ~10KB).
- **Do NOT** add any other I/O here: no large/binary files, repo-wide scans, bulk history rewrites, extra logs/metrics, or git operations. Those count as **heavy** I/O and must be done in dedicated tooling/agents, not the post-work turn.
This file is the coordinator's compaction recovery checkpoint. Format:

Copilot uses AI. Check for mistakes.
```markdown
# Session State
<!-- Auto-generated by Squad coordinator. Do not edit manually. -->

## Agents Spawned
- {Name}: {outcome emoji} {1-line outcome}

Comment on lines +923 to +925
Copy link

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since .squad/session-state.md is overwritten after each batch, it’s ambiguous whether “Agents Spawned / Key Decisions / Files Modified” should be cumulative for the whole session or only the latest batch. For compaction recovery to work after multiple batches, the doc should specify that this file reflects the full session-to-date (or that the coordinator rolls forward the previous file contents before overwriting).

Copilot uses AI. Check for mistakes.
## Task Status
- **Done:** {completed items}
- **Pending:** {remaining items}
- **Blocked:** {blocked items, if any}

## Key Decisions
- {decision 1-liner}

## Files Modified
- {path} — {what changed}

## Next Steps
- {what the coordinator should do next}
```

#### Compaction Recovery

When the coordinator detects that conversation context was compacted (prior messages are missing or summarized):

Comment on lines +943 to +944
Copy link

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“Detects that conversation context was compacted (prior messages are missing or summarized)” isn’t a very actionable signal for the coordinator. Consider documenting concrete indicators to key off of (e.g., presence of a compaction/system notice in the transcript, the user explicitly saying compaction happened, or the coordinator observing missing earlier agent outputs/IDs) so the recovery behavior triggers consistently.

Suggested change
When the coordinator detects that conversation context was compacted (prior messages are missing or summarized):
Treat the conversation as **compacted** and enter recovery mode when **any** of the following are true:
- The system or platform injects an explicit compaction/truncation notice into the transcript.
- The user explicitly says that earlier messages were truncated, summarized, or otherwise lost.
- You observe references in `.squad/session-state.md` (e.g., coordinator turns, agent run IDs, or outputs) that do not appear in the currently visible conversation transcript, indicating missing prior messages.
When any of the above indicators are present:

Copilot uses AI. Check for mistakes.
1. **Immediately read** `.squad/session-state.md` before taking any action.
2. **Reconstruct working context** from the session state: which agents ran, what completed, what's pending.
3. **Resume from where the session left off** — use the "Next Steps" section to determine the next action.
4. **Do NOT re-spawn agents** whose work is already marked done in session state.
5. After resuming, continue the normal post-work flow (including writing an updated session state).

> ⚠️ Session state is a recovery aid, not a source of truth for decisions or routing. Always defer to `decisions.md`, `routing.md`, and `team.md` for authoritative data.

### Ceremonies

Ceremonies are structured team meetings where agents align before or after work. Each squad configures its own ceremonies in `.squad/ceremonies.md`.
Expand Down Expand Up @@ -957,6 +1015,7 @@ If the user wants to remove someone:
| `.squad/log/` | **Derived / append-only.** Session logs. Diagnostic archive. Never edited after write. | Scribe | All agents (read-only) |
| `.squad/templates/` | **Reference.** Format guides for runtime files. Not authoritative for enforcement. | Squad (Coordinator) at init | Squad (Coordinator) |
| `.squad/plugins/marketplaces.json` | **Authoritative plugin config.** Registered marketplace sources. | Squad CLI (`squad plugin marketplace`) | Squad (Coordinator) |
| `.squad/session-state.md` | **Derived / overwritten.** Coordinator compaction recovery checkpoint. Overwritten after each agent batch. Not authoritative for decisions or routing. | Squad (Coordinator) | Squad (Coordinator) |

**Rules:**
1. If this file (`squad.agent.md`) and any other file conflict, this file wins.
Expand Down
1 change: 1 addition & 0 deletions .squad/routing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,4 @@
5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.
6. **Anticipate downstream.** Feature being built? Spawn tester for test cases from requirements simultaneously.
7. **Doc-impact check → PAO.** Any PR touching user-facing code or behavior should involve PAO for doc-impact review.
8. **Restraint after dispatch.** Once agents are running, the Coordinator waits. Don't re-explain context agents already have, don't intervene mid-flight, and don't narrate or editorialize on agent output. Present results directly and let agents speak for themselves.
Loading