Add Coordinator Restraint rules (#587)#683
Closed
tamirdresher wants to merge 1 commit intodevfrom
Closed
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Squad coordinator prompt/routing guidance to increase “coordinator restraint” after dispatch, and revises the post-agent-work / Scribe workflow instructions used by the coordinator templates.
Changes:
- Add a “Coordinator Restraint” section to the coordinator agent prompt and add routing principle #8 (“Restraint after dispatch”).
- Update “After Agent Work” guidance to persist agent results immediately and adjust silent-success handling + Scribe task ordering/requirements.
- Apply the updated coordinator template content across the root and package template mirrors.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
.github/agents/squad.agent.md |
Adds Coordinator Restraint rules; updates post-work and Scribe workflow instructions. |
.squad/routing.md |
Adds routing principle #8 on restraint after dispatch. |
templates/squad.agent.md.template |
Updates coordinator template “After Agent Work” + Scribe task list. |
packages/squad-cli/templates/squad.agent.md.template |
Mirrors the same coordinator template updates for the CLI package. |
packages/squad-sdk/templates/squad.agent.md.template |
Mirrors the same coordinator template updates for the SDK package. |
| 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: |
There was a problem hiding this comment.
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: |
Comment on lines
+883
to
+884
| ## Result | ||
| {agent output summary} |
There was a problem hiding this comment.
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} |
| 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: |
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
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. |
| 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. |
There was a problem hiding this comment.
“Enrich ... files written by coordinator in step 2” is ambiguous within this Scribe task list because step 2 here is “DECISION INBOX”. If this refers to the coordinator’s “After Agent Work” step 2 (“Persist results immediately”), please name that explicitly so Scribe can follow the correct reference.
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 previously written by the Coordinator during its "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. |
| @@ -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. --> | |||
|
|
|||
There was a problem hiding this comment.
These changes were applied directly to mirror files (templates/ and packages/*/templates) and to .github/agents, but the canonical source .squad-templates/squad.agent.md was not updated. test/template-sync.test.ts enforces byte-for-byte parity from .squad-templates/ to all mirrors (including .github/agents/squad.agent.md), so CI will fail unless you update the canonical file and re-run node scripts/sync-templates.mjs to regenerate the mirrors (and include the new “Coordinator Restraint” section there as well).
Suggested change
| #### Coordinator Restraint | |
| **You are not an authoring or editing agent in this turn.** Do not redo work that specialized agents have already completed, do not open new tasks, and do not introduce additional reasoning beyond what is required to persist and succinctly summarize results. |
Comment on lines
+870
to
+889
| **⚡ 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. | ||
|
|
There was a problem hiding this comment.
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.
Collaborator
|
🔄 Ralph PR status
Documentation-only (coordinator restraint rules + routing principle). Needs rebase onto current dev. |
Add restraint rules to squad agent prompt to give Copilot room to breathe. Includes persist-agent-results pattern. Co-authored-by: tamirdresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diberry
force-pushed
the
squad/587-coordinator-restraint
branch
from
6d579e1 to
71d6e64
Compare
Collaborator
🚀 Full Squad Review — Add Coordinator Restraint rules (#587)Domain: coordinator/restraint
All 21 squad members reviewed and approved. |
Collaborator
🚀 Squad Team Review — PR #683Adds 6 Coordinator Restraint rules to prevent over-management. New routing principle #8. 5 files, +127/-46. |
Collaborator
|
📋 PR Lifecycle: Team review complete. Labeled \squad:pr-reviewed. Waiting for Dina's review. Add \squad:pr-dina-approved\ when ready to proceed. |
diberry
added a commit
that referenced
this pull request
Apr 5, 2026
…sistence Batches three related coordinator prompt improvements: - Add Coordinator Restraint rules: 6 rules to prevent over-managing agents, narrating their output, or spawning unsolicited follow-ups (fixes #587) - Add compaction recovery via session-state.md: coordinator writes a recovery checkpoint after each agent batch, enabling context recovery when conversation is compacted (fixes #653) - Persist agent results immediately after read_agent: results expire in ~2-3 min, so coordinator now writes orchestration-log entries BEFORE presenting results or spawning Scribe. Scribe enriches rather than creates logs (fixes #652) Also adds routing rule 8 (restraint after dispatch) and session-state.md to the file ownership table. Original PRs: #682, #683, #684 Original author: @tamirdresher Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diberry
added a commit
that referenced
this pull request
Apr 5, 2026
…sistence (#682 #683 #684) Batches three related coordinator prompt improvements: - Add Coordinator Restraint rules: 6 rules to prevent over-managing agents, narrating their output, or spawning unsolicited follow-ups (fixes #587) - Add compaction recovery via session-state.md: coordinator writes a recovery checkpoint after each agent batch, enabling context recovery when conversation is compacted (fixes #653) - Persist agent results immediately after read_agent: results expire in ~2-3 min, so coordinator now writes orchestration-log entries BEFORE presenting results or spawning Scribe. Scribe enriches rather than creates logs (fixes #652) Also adds routing rule 8 (restraint after dispatch) and session-state.md to the file ownership table. Also includes: warn when squad watch receives unused message args — detects extra positional args and prints a clear warning instead of silently ignoring them (Closes #703). Original PRs: #682, #683, #684 Original author: @tamirdresher Co-authored-by: tamirdresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diberry
added a commit
that referenced
this pull request
Apr 5, 2026
…sistence (#682 #683 #684) Batches three related coordinator prompt improvements: - Add Coordinator Restraint rules: 6 rules to prevent over-managing agents, narrating their output, or spawning unsolicited follow-ups (fixes #587) - Add compaction recovery via session-state.md: coordinator writes a recovery checkpoint after each agent batch, enabling context recovery when conversation is compacted (fixes #653) - Persist agent results immediately after read_agent: results expire in ~2-3 min, so coordinator now writes orchestration-log entries BEFORE presenting results or spawning Scribe. Scribe enriches rather than creates logs (fixes #652) Also adds routing rule 8 (restraint after dispatch) and session-state.md to the file ownership table. Also includes: warn when squad watch receives unused message args — detects extra positional args and prints a clear warning instead of silently ignoring them (Closes #703). Original PRs: #682, #683, #684 Original author: @tamirdresher Co-authored-by: tamirdresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diberry
added a commit
that referenced
this pull request
Apr 6, 2026
…sistence (#682 #683 #684) Batches three related coordinator prompt improvements: - Add Coordinator Restraint rules: 6 rules to prevent over-managing agents, narrating their output, or spawning unsolicited follow-ups (fixes #587) - Add compaction recovery via session-state.md: coordinator writes a recovery checkpoint after each agent batch, enabling context recovery when conversation is compacted (fixes #653) - Persist agent results immediately after read_agent: results expire in ~2-3 min, so coordinator now writes orchestration-log entries BEFORE presenting results or spawning Scribe. Scribe enriches rather than creates logs (fixes #652) Also adds routing rule 8 (restraint after dispatch) and session-state.md to the file ownership table. Also includes: warn when squad watch receives unused message args — detects extra positional args and prints a clear warning instead of silently ignoring them (Closes #703). Original PRs: #682, #683, #684 Original author: @tamirdresher Co-authored-by: tamirdresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diberry
added a commit
that referenced
this pull request
Apr 6, 2026
…sistence (#682 #683 #684) Batches three related coordinator prompt improvements: - Add Coordinator Restraint rules: 6 rules to prevent over-managing agents, narrating their output, or spawning unsolicited follow-ups (fixes #587) - Add compaction recovery via session-state.md: coordinator writes a recovery checkpoint after each agent batch, enabling context recovery when conversation is compacted (fixes #653) - Persist agent results immediately after read_agent: results expire in ~2-3 min, so coordinator now writes orchestration-log entries BEFORE presenting results or spawning Scribe. Scribe enriches rather than creates logs (fixes #652) Also adds routing rule 8 (restraint after dispatch) and session-state.md to the file ownership table. Also includes: warn when squad watch receives unused message args — detects extra positional args and prints a clear warning instead of silently ignoring them (Closes #703). Original PRs: #682, #683, #684 Original author: @tamirdresher Co-authored-by: tamirdresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Collaborator
Author
|
Closing as stale. Reason: Coordinator restraint rules — these have been incorporated into squad.agent.md through other means. Re-open if still relevant. |
diberry
added a commit
that referenced
this pull request
Apr 8, 2026
diberry
added a commit
that referenced
this pull request
Apr 8, 2026
karlis-balcers
pushed a commit
to karlis-balcers/squad
that referenced
this pull request
Apr 13, 2026
…sistence (bradygaster#682 bradygaster#683 bradygaster#684) Batches three related coordinator prompt improvements: - Add Coordinator Restraint rules: 6 rules to prevent over-managing agents, narrating their output, or spawning unsolicited follow-ups (fixes bradygaster#587) - Add compaction recovery via session-state.md: coordinator writes a recovery checkpoint after each agent batch, enabling context recovery when conversation is compacted (fixes bradygaster#653) - Persist agent results immediately after read_agent: results expire in ~2-3 min, so coordinator now writes orchestration-log entries BEFORE presenting results or spawning Scribe. Scribe enriches rather than creates logs (fixes bradygaster#652) Also adds routing rule 8 (restraint after dispatch) and session-state.md to the file ownership table. Also includes: warn when squad watch receives unused message args — detects extra positional args and prints a clear warning instead of silently ignoring them (Closes bradygaster#703). Original PRs: bradygaster#682, bradygaster#683, bradygaster#684 Original author: @tamirdresher Co-authored-by: tamirdresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Add a "Coordinator Restraint" section to the squad coordinator's agent prompt and a corresponding routing principle.
Why
Fixes #587 — The coordinator over-manages agents by intervening too frequently, re-explaining context agents already have, summarizing/rephrasing agent output, and not letting agents complete their work before jumping in. This erodes agent autonomy and adds noise.
How
.github/agents/squad.agent.mdbetween "Eager Execution Philosophy" and "Mode Selection" with six rules:squadinto using GitHub #8 ("Restraint after dispatch") to.squad/routing.mdTesting
Documentation/charter-only change — no code affected. Verified by reading the rendered markdown and confirming section placement and style consistency.
Docs
This PR is the documentation change.
Exports
No public API or export changes.
Breaking Changes
None — behavioral guidance only, no runtime impact.
Waivers
None required.