Add Coordinator Restraint rules (#587) by tamirdresher · Pull Request #683 · bradygaster/squad

tamirdresher · 2026-03-29T14:57:51Z

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

Added a Coordinator Restraint section to .github/agents/squad.agent.md between "Eager Execution Philosophy" and "Mode Selection" with six rules:
1. Don't re-explain context agents already have in their charter
2. Don't intervene while an agent is still running
3. Don't summarize/rephrase agent output — present it directly
4. Don't add unsolicited analysis on top of agent output
5. Don't spawn follow-up agents unless the user requests or routing rules mandate it
6. Keep coordinator commentary to 1-2 sentences max
Added a self-test heuristic for the coordinator to verify its own restraint
Added routing principle Please Don't Lock squad into using GitHub #8 ("Restraint after dispatch") to .squad/routing.md

Testing

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.

…652) read_agent data expires within ~2-3 minutes, causing silent data loss when the coordinator takes too long between collecting results and processing them. Changes to After Agent Work flow: - Add mandatory step 2: write results to orchestration-log BEFORE any other processing (presenting results, spawning Scribe, etc.) - Update silent-success detection (now step 3) to check orchestration-log for files agents may have written directly - Update Scribe task 3 to enrich coordinator-written logs rather than create from scratch - Renumber steps 3-6 to 4-7 - Update LEAN instruction to acknowledge persistence write as the one permitted file I/O operation Refs #652 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Addresses over-managing behavior where the coordinator intervenes too frequently, re-explains context agents already have, and narrates on top of agent output. Changes: - Add 'Coordinator Restraint' section to squad.agent.md near the Eager Execution Philosophy section with six restraint rules - Add routing principle #8 (restraint after dispatch) to routing.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

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.

Copilot · 2026-03-29T15:02:19Z

.github/agents/squad.agent.md

 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:


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 · 2026-03-29T15:02:20Z

.github/agents/squad.agent.md

+   ## Result
+   {agent output summary}


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 · 2026-03-29T15:02:20Z

.github/agents/squad.agent.md

 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:


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 · 2026-03-29T15:02:20Z

.github/agents/squad.agent.md

  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.


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 · 2026-03-29T15:02:20Z

templates/squad.agent.md.template

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


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

Copilot · 2026-03-29T15:02:20Z

templates/squad.agent.md.template

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



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.

Copilot · 2026-03-29T15:02:21Z

.github/agents/squad.agent.md

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


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 and others added 2 commits March 29, 2026 17:55

Copilot AI review requested due to automatic review settings March 29, 2026 14:57

Copilot started reviewing on behalf of tamirdresher March 29, 2026 14:58 View session

Copilot AI reviewed Mar 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Coordinator Restraint rules (#587)#683

Add Coordinator Restraint rules (#587)#683
tamirdresher wants to merge 2 commits intodevfrom
squad/587-coordinator-restraint

tamirdresher commented Mar 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Copilot AI Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	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.

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



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

Conversation

tamirdresher commented Mar 29, 2026

What

Why

How

Testing

Docs

Exports

Breaking Changes

Waivers

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants