Skip to content

fix(coordinator): persist agent results immediately after read_agent #684

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

fix(coordinator): persist agent results immediately after read_agent #684

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
27 changes: 20 additions & 7 deletions .github/agents/squad.agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -845,22 +845,35 @@ prompt: |
(2) "Server Error Retry Loop" — context overflow after fan-out. Mitigated by lean
post-work turn + Scribe delegation + compact result presentation. -->

**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) present compact results, (2) spawn Scribe. That's ALL. No orchestration logs, no decision consolidation, no heavy file I/O.
**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) persist results, (2) present compact results, (3) spawn Scribe. That's ALL. No decision consolidation, no heavy file I/O beyond the mandatory persistence write in step 2.

**⚡ Context budget rule:** After collecting results from 3+ agents, use compact format (agent + 1-line outcome). Full details go in orchestration log via Scribe.

After each batch of agent work:

1. **Collect results** via `read_agent` (wait: true, timeout: 300).

2. **Silent success detection** — when `read_agent` returns empty/no response:
2. **Persist results immediately** — `read_agent` data expires within ~2-3 minutes. Write each agent's result to `.squad/orchestration-log/{timestamp}-{agent-name}.md` **BEFORE** any other processing (presenting results, spawning Scribe, etc.). Create the directory if it doesn't exist. Use ISO 8601 UTC timestamp (e.g. `20260401T1423Z`). Format:
Comment on lines +848 to +856

Copilot AI Mar 29, 2026

Copy link

Choose a reason for hiding this comment

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

Template parity: these edits were applied to mirror copies, but the canonical template .squad-templates/squad.agent.md still has the old “After Agent Work” steps. The repo’s template-sync tests enforce byte-for-byte equality from .squad-templates/ to templates/, packages/*/templates/, and .github/agents/ (see test/template-sync.test.ts:4-6,118-141), so this PR will fail CI and/or get reverted the next time node scripts/sync-templates.mjs runs. Please apply the change to .squad-templates/squad.agent.md and re-run the sync script so all mirrors match.

Copilot uses AI. Check for mistakes.
```markdown
# {Agent Name} — {ISO 8601 UTC timestamp}
## Task
{what was asked}
## Result
{agent output summary}
## Files Modified
{list of files the agent created or changed, or "None detected"}
```
This is the ONE exception to "no file I/O" — it is mandatory because results are unrecoverable once expired.
Comment on lines +856 to +866

Copilot AI Mar 29, 2026

Copy link

Choose a reason for hiding this comment

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

The new persistence step writes coordinator output into .squad/orchestration-log/{timestamp}-{agent-name}.md using a new header-based format, but this conflicts with existing orchestration-log conventions in this repo: templates/orchestration-log.md defines a table-based entry and says entries are created BEFORE spawning (and append-only), and this same squad.agent prompt elsewhere says “Scribe writes one entry per agent … format matches the existing orchestration log entry template.” Either adjust the persistence location/filename (e.g., a separate “raw results” log) or update the orchestration-log template + the earlier sections so the coordinator-written file format and timing are consistent.

Copilot uses AI. Check for mistakes.

3. **Silent success detection** — when `read_agent` returns empty/no response:
- Check `.squad/orchestration-log/` for a file the agent may have written directly during its run.
Comment on lines +856 to +869

Copilot AI Mar 29, 2026

Copy link

Choose a reason for hiding this comment

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

Flow ambiguity: step 2 is written as mandatory “persist results immediately” for each agent, but step 3 is specifically for the case where read_agent returns empty/no response (i.e., there is no result content to persist). Please clarify the conditional behavior (e.g., only persist when read_agent returns content, or persist a stub that explicitly records the loss) so the numbered procedure is executable as written.

Copilot uses AI. Check for mistakes.
- Check filesystem: history.md modified? New decision inbox files? Output files created?
- Files found → `"⚠️ {Name} completed (files verified) but response lost."` Treat as DONE.
- No files → `"❌ {Name} failed — no work product."` Consider re-spawn.

3. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`
4. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`

4. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:
5. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:

```
agent_type: "general-purpose"
Expand All @@ -878,7 +891,7 @@ prompt: |
0. PRE-CHECK: Stat decisions.md size and count inbox/ files. Record measurements.
1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step.
2. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate.
3. ORCHESTRATION LOG: Write .squad/orchestration-log/{timestamp}-{agent}.md per agent. Use ISO 8601 UTC timestamp.
3. ORCHESTRATION LOG: Enrich .squad/orchestration-log/{timestamp}-{agent}.md files written by coordinator in step 2. Add detail from agent history if available. Write new entries for any agents not yet logged. Use ISO 8601 UTC timestamp.

Copilot AI Mar 29, 2026

Copy link

Choose a reason for hiding this comment

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

Placeholder/filename inconsistency: coordinator step 2 uses {timestamp}-{agent-name}.md, while the Scribe task refers to {timestamp}-{agent}.md. To avoid Scribe missing files or generating duplicates, please standardize on one placeholder and explicitly state it should use the spawned agent name (lowercase cast id) as the filename-safe identifier.

Suggested change
3. ORCHESTRATION LOG: Enrich .squad/orchestration-log/{timestamp}-{agent}.md files written by coordinator in step 2. Add detail from agent history if available. Write new entries for any agents not yet logged. Use ISO 8601 UTC timestamp.
3. ORCHESTRATION LOG: Enrich .squad/orchestration-log/{timestamp}-{agent-name}.md files written by coordinator in step 2, where `agent-name` is the spawned agent `name` (cast id), lowercased and made filename-safe. Add detail from agent history if available. Write new entries for any agents not yet logged. Use ISO 8601 UTC timestamp.

Copilot uses AI. Check for mistakes.
4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
5. CROSS-AGENT: Append team updates to affected agents' history.md.
6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
Expand All @@ -888,9 +901,9 @@ prompt: |
Never speak to user. ⚠️ End with plain text summary after all tool calls.
```

5. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.
6. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.

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. **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.

### Ceremonies

Expand Down
41 changes: 28 additions & 13 deletions packages/squad-cli/templates/squad.agent.md.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -845,22 +845,35 @@ prompt: |
(2) "Server Error Retry Loop" — context overflow after fan-out. Mitigated by lean
post-work turn + Scribe delegation + compact result presentation. -->

**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) present compact results, (2) spawn Scribe. That's ALL. No orchestration logs, no decision consolidation, no heavy file I/O.
**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) persist results, (2) present compact results, (3) spawn Scribe. That's ALL. No decision consolidation, no heavy file I/O beyond the mandatory persistence write in step 2.

**⚡ Context budget rule:** After collecting results from 3+ agents, use compact format (agent + 1-line outcome). Full details go in orchestration log via Scribe.

After each batch of agent work:

1. **Collect results** via `read_agent` (wait: true, timeout: 300).

2. **Silent success detection** — when `read_agent` returns empty/no response:
2. **Persist results immediately** — `read_agent` data expires within ~2-3 minutes. Write each agent's result to `.squad/orchestration-log/{timestamp}-{agent-name}.md` **BEFORE** any other processing (presenting results, spawning Scribe, etc.). Create the directory if it doesn't exist. Use ISO 8601 UTC timestamp (e.g. `20260401T1423Z`). Format:
```markdown
# {Agent Name} — {ISO 8601 UTC timestamp}
## Task
{what was asked}
## Result
{agent output summary}
## Files Modified
{list of files the agent created or changed, or "None detected"}
```
This is the ONE exception to "no file I/O" — it is mandatory because results are unrecoverable once expired.

3. **Silent success detection** — when `read_agent` returns empty/no response:
- Check `.squad/orchestration-log/` for a file the agent may have written directly during its run.
- Check filesystem: history.md modified? New decision inbox files? Output files created?
- Files found → `"⚠️ {Name} completed (files verified) but response lost."` Treat as DONE.
- No files → `"❌ {Name} failed — no work product."` Consider re-spawn.

3. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`
4. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`

4. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:
5. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:

```
agent_type: "general-purpose"
Expand All @@ -875,20 +888,22 @@ prompt: |
SPAWN MANIFEST: {spawn_manifest}

Tasks (in order):
1. ORCHESTRATION LOG: Write .squad/orchestration-log/{timestamp}-{agent}.md per agent. Use ISO 8601 UTC timestamp.
2. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
3. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate.
4. CROSS-AGENT: Append team updates to affected agents' history.md.
5. DECISIONS ARCHIVE: If decisions.md exceeds ~20KB, archive entries older than 30 days to decisions-archive.md.
6. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
7. HISTORY SUMMARIZATION: If any history.md >12KB, summarize old entries to ## Core Context.
0. PRE-CHECK: Stat decisions.md size and count inbox/ files. Record measurements.
1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step.
2. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate.
3. ORCHESTRATION LOG: Enrich .squad/orchestration-log/{timestamp}-{agent}.md files written by coordinator in step 2. Add detail from agent history if available. Write new entries for any agents not yet logged. Use ISO 8601 UTC timestamp.
4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
5. CROSS-AGENT: Append team updates to affected agents' history.md.
6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
7. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized.

Never speak to user. ⚠️ End with plain text summary after all tool calls.
```

5. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.
6. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.

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. **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.

### Ceremonies

Expand Down
41 changes: 28 additions & 13 deletions packages/squad-sdk/templates/squad.agent.md.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -845,22 +845,35 @@ prompt: |
(2) "Server Error Retry Loop" — context overflow after fan-out. Mitigated by lean
post-work turn + Scribe delegation + compact result presentation. -->

**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) present compact results, (2) spawn Scribe. That's ALL. No orchestration logs, no decision consolidation, no heavy file I/O.
**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) persist results, (2) present compact results, (3) spawn Scribe. That's ALL. No decision consolidation, no heavy file I/O beyond the mandatory persistence write in step 2.

**⚡ Context budget rule:** After collecting results from 3+ agents, use compact format (agent + 1-line outcome). Full details go in orchestration log via Scribe.

After each batch of agent work:

1. **Collect results** via `read_agent` (wait: true, timeout: 300).

2. **Silent success detection** — when `read_agent` returns empty/no response:
2. **Persist results immediately** — `read_agent` data expires within ~2-3 minutes. Write each agent's result to `.squad/orchestration-log/{timestamp}-{agent-name}.md` **BEFORE** any other processing (presenting results, spawning Scribe, etc.). Create the directory if it doesn't exist. Use ISO 8601 UTC timestamp (e.g. `20260401T1423Z`). Format:
```markdown
# {Agent Name} — {ISO 8601 UTC timestamp}
## Task
{what was asked}
## Result
{agent output summary}
## Files Modified
{list of files the agent created or changed, or "None detected"}
```
This is the ONE exception to "no file I/O" — it is mandatory because results are unrecoverable once expired.

3. **Silent success detection** — when `read_agent` returns empty/no response:
- Check `.squad/orchestration-log/` for a file the agent may have written directly during its run.
- Check filesystem: history.md modified? New decision inbox files? Output files created?
- Files found → `"⚠️ {Name} completed (files verified) but response lost."` Treat as DONE.
- No files → `"❌ {Name} failed — no work product."` Consider re-spawn.

3. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`
4. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`

4. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:
5. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:

```
agent_type: "general-purpose"
Expand All @@ -875,20 +888,22 @@ prompt: |
SPAWN MANIFEST: {spawn_manifest}

Tasks (in order):
1. ORCHESTRATION LOG: Write .squad/orchestration-log/{timestamp}-{agent}.md per agent. Use ISO 8601 UTC timestamp.
2. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
3. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate.
4. CROSS-AGENT: Append team updates to affected agents' history.md.
5. DECISIONS ARCHIVE: If decisions.md exceeds ~20KB, archive entries older than 30 days to decisions-archive.md.
6. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
7. HISTORY SUMMARIZATION: If any history.md >12KB, summarize old entries to ## Core Context.
0. PRE-CHECK: Stat decisions.md size and count inbox/ files. Record measurements.
1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step.
2. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate.
3. ORCHESTRATION LOG: Enrich .squad/orchestration-log/{timestamp}-{agent}.md files written by coordinator in step 2. Add detail from agent history if available. Write new entries for any agents not yet logged. Use ISO 8601 UTC timestamp.
4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
5. CROSS-AGENT: Append team updates to affected agents' history.md.
6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
7. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized.

Never speak to user. ⚠️ End with plain text summary after all tool calls.
```

5. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.
6. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.

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. **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.

### Ceremonies

Expand Down
41 changes: 28 additions & 13 deletions templates/squad.agent.md.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -845,22 +845,35 @@ prompt: |
(2) "Server Error Retry Loop" — context overflow after fan-out. Mitigated by lean
post-work turn + Scribe delegation + compact result presentation. -->

**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) present compact results, (2) spawn Scribe. That's ALL. No orchestration logs, no decision consolidation, no heavy file I/O.
**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) persist results, (2) present compact results, (3) spawn Scribe. That's ALL. No decision consolidation, no heavy file I/O beyond the mandatory persistence write in step 2.

**⚡ Context budget rule:** After collecting results from 3+ agents, use compact format (agent + 1-line outcome). Full details go in orchestration log via Scribe.

After each batch of agent work:

1. **Collect results** via `read_agent` (wait: true, timeout: 300).

2. **Silent success detection** — when `read_agent` returns empty/no response:
2. **Persist results immediately** — `read_agent` data expires within ~2-3 minutes. Write each agent's result to `.squad/orchestration-log/{timestamp}-{agent-name}.md` **BEFORE** any other processing (presenting results, spawning Scribe, etc.). Create the directory if it doesn't exist. Use ISO 8601 UTC timestamp (e.g. `20260401T1423Z`). Format:
```markdown
# {Agent Name} — {ISO 8601 UTC timestamp}
## Task
{what was asked}
## Result
{agent output summary}
## Files Modified
{list of files the agent created or changed, or "None detected"}
```
This is the ONE exception to "no file I/O" — it is mandatory because results are unrecoverable once expired.

3. **Silent success detection** — when `read_agent` returns empty/no response:
- Check `.squad/orchestration-log/` for a file the agent may have written directly during its run.
- Check filesystem: history.md modified? New decision inbox files? Output files created?
- Files found → `"⚠️ {Name} completed (files verified) but response lost."` Treat as DONE.
- No files → `"❌ {Name} failed — no work product."` Consider re-spawn.

3. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`
4. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`

4. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:
5. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:

```
agent_type: "general-purpose"
Expand All @@ -875,20 +888,22 @@ prompt: |
SPAWN MANIFEST: {spawn_manifest}

Tasks (in order):
1. ORCHESTRATION LOG: Write .squad/orchestration-log/{timestamp}-{agent}.md per agent. Use ISO 8601 UTC timestamp.
2. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
3. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate.
4. CROSS-AGENT: Append team updates to affected agents' history.md.
5. DECISIONS ARCHIVE: If decisions.md exceeds ~20KB, archive entries older than 30 days to decisions-archive.md.
6. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
7. HISTORY SUMMARIZATION: If any history.md >12KB, summarize old entries to ## Core Context.
0. PRE-CHECK: Stat decisions.md size and count inbox/ files. Record measurements.
1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step.
2. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate.
3. ORCHESTRATION LOG: Enrich .squad/orchestration-log/{timestamp}-{agent}.md files written by coordinator in step 2. Add detail from agent history if available. Write new entries for any agents not yet logged. Use ISO 8601 UTC timestamp.
4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
5. CROSS-AGENT: Append team updates to affected agents' history.md.
6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
7. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged.
8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized.

Never speak to user. ⚠️ End with plain text summary after all tool calls.
```

5. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.
6. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.

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. **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.

### Ceremonies

Expand Down
Loading