Skip to content

Add Coordinator Restraint rules (#587) #683

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

Add Coordinator Restraint rules (#587) #683

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
49 changes: 42 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 @@ -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.

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 @@ -845,22 +867,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:
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.

The filename timestamp format here (20260401T1423Z) doesn’t match the filename-safe timestamp format the CLI expects when parsing .squad/orchestration-log/ entries (see SAFE_TIMESTAMP_RE in packages/squad-cli/src/cli/commands/cost.ts). If the coordinator writes files with this format, squad cost will ignore them. Align the documented format with the existing YYYY-MM-DDTHH-MM-SSZ... convention (or update the parser/convention consistently).

Suggested change
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:
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 a filename-safe ISO 8601 UTC timestamp matching `YYYY-MM-DDTHH-MM-SSZ...` (e.g. `2026-04-01T14-23-45Z`). Format:

Copilot uses AI. Check for mistakes.
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.

Writing these “persisted results” files into .squad/orchestration-log/ blurs responsibilities with the existing orchestration log design (elsewhere in this prompt it says Scribe writes orchestration logs, and the orchestration-log template is structured as a pre-spawn manifest used by tooling like squad cost). Consider using a separate directory for transient/raw agent result capture (or extend the existing orchestration-log format in a backward-compatible way) to avoid mixing incompatible file formats in the same folder.

Copilot uses AI. Check for mistakes.
```markdown
# {Agent Name} — {ISO 8601 UTC timestamp}
## Task
{what was asked}
## Result
{agent output summary}
Comment on lines +883 to +884
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 persistence format asks for an “agent output summary”, which conflicts with the new “Don’t summarize or rephrase agent output” rule above and with the repo’s verbatim raw-output conventions. To preserve auditability (and avoid coordinator paraphrase), persist the agent output verbatim (or clearly separate a labeled summary from the raw output) so the stored record reflects exactly what read_agent returned.

Suggested change
## Result
{agent output summary}
## Raw Output
{verbatim agent output from read_agent}

Copilot uses AI. Check for mistakes.
## 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 +870 to +889
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.

The PR description focuses on adding “Coordinator Restraint” and a routing principle, but this hunk also changes the coordinator’s post-work workflow (mandatory persistence writes, silent-success flow changes) and the Scribe task ordering/requirements. Please either reflect these additional behavioral changes in the PR description (and linked issue scope) or split them into a separate PR to keep review scope clear.

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.
- 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 +913,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.
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.

In the Scribe task list, “files written by coordinator in step 2” is ambiguous because within this numbered list step 2 is “DECISION INBOX”. If you mean the coordinator’s “After Agent Work” step 2 (“Persist results immediately”), call that out explicitly to avoid mis-execution by Scribe.

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}.md files written by coordinator during the Coordinator "After Agent Work" step 2 ("Persist results immediately"). 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 +923,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
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.
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
Loading
Loading