Skip to content

Commit e77c5f2

Browse files
bradygasterCopilot
andauthored
Enforce coordinator scope and tracked behavior changes (#2110)
* fix: enforce coordinator scope boundaries Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix: address scope control review Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 93aec83 commit e77c5f2

12 files changed

Lines changed: 289 additions & 155 deletions

File tree

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@bradygaster/squad-cli": patch
3+
"@bradygaster/squad-sdk": patch
4+
---
5+
6+
Require coordinators to preserve user-approved scope and prevent directive or reflection capture from falling back to local Markdown proposals.

‎.github/agents/squad.agent.md‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,7 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa
247247

248248
### Directive Capture
249249

250-
**Before routing any message, check: is this a directive?** A directive is a user statement that sets a preference, rule, or constraint the team should remember. Capture it to the decisions inbox BEFORE routing work.
250+
**Before routing any message, check: is this a directive?** A directive is a user statement that sets a preference, rule, or constraint the team should remember.
251251

252252
**Directive signals** (capture these):
253253
- "Always…", "Never…", "From now on…", "We don't…", "Going forward…"
@@ -262,19 +262,22 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa
262262

263263
**When you detect a directive:**
264264

265-
1. Capture the directive with governed memory tools when available:
266-
- Prefer `memory.write` with class `decision` to persist the directive through the governed pipeline:
265+
1. Capture the directive only with governed runtime memory tools when available:
266+
- Prefer `memory.write` with class `DECISION` to persist the directive through the governed pipeline:
267267
```
268268
memory.write({
269-
class: "decision",
270-
key: "copilot-directive-{timestamp}",
269+
class: "DECISION",
270+
title: "User directive - {timestamp}",
271+
author: "{user name} (via Copilot)",
271272
content: "### {timestamp}: User directive\n**By:** {user name} (via Copilot)\n**What:** {the directive, verbatim or lightly paraphrased}\n**Why:** User request — captured for team memory"
272273
})
273274
```
274-
- If `memory.write` is not available, fall back to `squad_decide` or `squad_state_write` to `decisions/inbox/copilot-directive-{timestamp}.md`.
275+
- If `memory.write` is unavailable, use another configured runtime state tool such as `squad_decide` or `squad_state_write`.
276+
- Never create a local or gitignored Markdown proposal, including `.squad/decisions/inbox/*.md`, as a persistence fallback. If no runtime state tool is available, acknowledge the directive without pretending it was persisted.
275277
- Do **not** run `git notes`, checkout `squad-state`, or manually commit mutable `.squad/` state. The runtime owns state persistence.
276278
2. Acknowledge briefly: `"📌 Captured. {one-line summary of the directive}."`
277-
3. If the message ALSO contains a work request, route that work normally after capturing. If it's directive-only, you're done — no agent spawn needed.
279+
3. If the directive changes repository behavior, dispatch the accountable specialist to make the minimum tracked source change, validate it, and open a focused PR. Runtime memory records context; it is not the implementation.
280+
4. If the message ALSO contains a work request, route that work normally after capturing. If it is directive-only and requires no repository change, no agent spawn is needed.
278281
279282
### Memory Governance Tools
280283
@@ -306,6 +309,15 @@ For `STATE_BACKEND ∈ {"local", "worktree"}`, file writes to `.squad/` are vali
306309
307310
### Routing
308311
312+
### Scope Control
313+
314+
The Coordinator owns preserving the scope the user requested.
315+
316+
- Every specialist prompt must state the requested deliverable and explicit exclusions.
317+
- Specialists must complete only that scope. Adjacent issues, cleanup opportunities, or follow-on ideas are reported separately and must not be implemented, edited, or delegated as part of the current work.
318+
- Expanding scope requires explicit user approval. The Coordinator must present the adjacent discovery separately and wait for that approval before routing additional work.
319+
- If expansion is approved, route it as distinct focused work; do not silently fold it into the original task or PR.
320+
309321
The routing table determines **WHO** handles work. After routing, use Response Mode Selection to determine **HOW** (Direct/Lightweight/Standard/Full).
310322
311323
| Signal | Action |

‎.github/skills/reflect/SKILL.md‎

Lines changed: 27 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,16 @@ Analyze conversations and propose improvements to squad knowledge based on what
1919

2020
**Reflect complements existing Squad knowledge systems:**
2121

22-
1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (append-only; each agent updates their own file; Scribe propagates cross-agent updates)
23-
2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect
24-
3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md
22+
1. **Governed runtime memory** — Durable observations and decisions persisted through configured state tools
23+
2. **Tracked governing source** — Coordinator prompts, skills, and other behavior-defining files changed through focused pull requests
24+
3. **`reflect` skill** — Identifies learnings that may warrant either runtime memory or an approved tracked behavior change
2525

2626
**Workflow:**
2727
- Use `reflect` during work to capture learnings
2828
- At session end, review captured learnings
29-
- Promote HIGH confidence patterns → lead agent for decision.md review
30-
- Promote agent-specific patterns → `{agent}/history.md` updates
29+
- Persist evidence through governed runtime memory when available
30+
- Promote accepted behavior changes through the accountable specialist as tracked source changes in a focused PR
31+
- Report adjacent improvements separately; do not expand the current scope without explicit user approval
3132

3233
---
3334

@@ -64,9 +65,9 @@ Analyze conversations and propose improvements to squad knowledge based on what
6465

6566
Determine what knowledge system should be updated:
6667

67-
1. **Agent-specific learning** → `.squad/agents/{agent}/history.md`
68-
2. **Team-wide decision** → `.squad/decisions/inbox/{agent}-{topic}.md`
69-
3. **Skill-specific improvement** → Document in session, recommend to skill owner
68+
1. **Observation or preference** → Governed runtime memory, when configured
69+
2. **Accepted team-wide behavior change** → The accountable tracked instruction or skill source, through a focused PR
70+
3. **Adjacent improvement** → Report separately and require explicit user approval before adding it to scope
7071

7172
### Phase 2: Analyze Conversation
7273

@@ -128,15 +129,15 @@ Present findings:
128129
│ │
129130
│ [HIGH] + Add constraint: "{specific constraint}" │
130131
│ Source: "{quoted user correction}" │
131-
│ Target: .squad/decisions/inbox/{agent}-{topic}.md │
132+
│ Target: tracked governing source via focused PR │
132133
│ │
133134
│ [MED] + Add preference: "{specific preference}" │
134135
│ Source: "{evidence from conversation}" │
135-
│ Target: .squad/agents/{agent}/history.md │
136+
│ Target: governed runtime memory │
136137
│ │
137138
│ [LOW] ~ Note for review: "{observation}" │
138139
│ Source: "{pattern observed}" │
139-
│ Target: Session notes only │
140+
│ Target: report only; no persistence │
140141
│ │
141142
├─────────────────────────────────────────────────────────────┤
142143
│ Apply changes? [Y/n/edit] │
@@ -158,17 +159,17 @@ Present findings:
158159

159160
After user approval:
160161

161-
1. **For Agent History:**
162-
- Append to `.squad/agents/{agent}/history.md` under `## Learnings` section
163-
- Format: Date, assignment context, key learning
162+
1. **For Runtime Memory:**
163+
- Use the configured governed memory or state tool.
164+
- If no runtime persistence tool is available, report the learning without claiming it was saved.
164165

165-
2. **For Team Decisions:**
166-
- Create `.squad/decisions/inbox/{agent}-{topic}.md`
167-
- Lead agent reviews and merges to `decisions.md` if appropriate
166+
2. **For Behavioral Changes:**
167+
- Route the accountable specialist to update the minimum tracked governing source.
168+
- Validate the change and open a focused PR.
168169

169-
3. **For Skills:**
170-
- Document recommendation in session notes
171-
- Squad lead reviews and routes to skill owner
170+
3. **Never Use Throwaway Proposal Files:**
171+
- Do not create local or gitignored Markdown proposals, including `.squad/decisions/inbox/*.md`, for reflection or directive capture.
172+
- Runtime memory may preserve context, but it does not replace the tracked source change required to alter behavior.
172173

173174
---
174175

@@ -186,7 +187,8 @@ User: "No, use the code search tools first, grep is too slow"
186187
```
187188
[HIGH] + Add constraint: "Use code intelligence tools before grep"
188189
Source: "No, use the code search tools first, grep is too slow"
189-
Target: .squad/agents/{agent}/history.md
190+
Target: accountable tracked instruction via focused PR; governed runtime
191+
memory for context only
190192
```
191193

192194
### Example 2: Success Pattern
@@ -201,7 +203,8 @@ User: "Perfect! This is exactly the format I want for all PRs"
201203
```
202204
[MED] + Add preference: "Include test plan in PR descriptions"
203205
Source: User praised detailed PR format
204-
Target: .squad/decisions/inbox/pr-format.md (for team adoption)
206+
Target: governed runtime memory; if adopted as team behavior, update the
207+
accountable tracked instruction in a focused PR
205208
```
206209

207210
---
@@ -224,6 +227,6 @@ User: "Perfect! This is exactly the format I want for all PRs"
224227

225228
## See Also
226229

227-
- `.squad/decisions.md` — Team-wide decisions
228-
- `.squad/agents/*/history.md` — Agent-specific learnings
230+
- `.squad/decisions.md` — Runtime-backed team decisions
231+
- `.github/agents/squad.agent.md` — Coordinator behavior
229232
- `.squad/routing.md` — Work assignment patterns

‎.squad-templates/skills/reflect/SKILL.md‎

Lines changed: 27 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,16 @@ Analyze conversations and propose improvements to squad knowledge based on what
1919

2020
**Reflect complements existing Squad knowledge systems:**
2121

22-
1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (append-only; each agent updates their own file; Scribe propagates cross-agent updates)
23-
2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect
24-
3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md
22+
1. **Governed runtime memory** — Durable observations and decisions persisted through configured state tools
23+
2. **Tracked governing source** — Coordinator prompts, skills, and other behavior-defining files changed through focused pull requests
24+
3. **`reflect` skill** — Identifies learnings that may warrant either runtime memory or an approved tracked behavior change
2525

2626
**Workflow:**
2727
- Use `reflect` during work to capture learnings
2828
- At session end, review captured learnings
29-
- Promote HIGH confidence patterns → lead agent for decision.md review
30-
- Promote agent-specific patterns → `{agent}/history.md` updates
29+
- Persist evidence through governed runtime memory when available
30+
- Promote accepted behavior changes through the accountable specialist as tracked source changes in a focused PR
31+
- Report adjacent improvements separately; do not expand the current scope without explicit user approval
3132

3233
---
3334

@@ -64,9 +65,9 @@ Analyze conversations and propose improvements to squad knowledge based on what
6465

6566
Determine what knowledge system should be updated:
6667

67-
1. **Agent-specific learning** → `.squad/agents/{agent}/history.md`
68-
2. **Team-wide decision** → `.squad/decisions/inbox/{agent}-{topic}.md`
69-
3. **Skill-specific improvement** → Document in session, recommend to skill owner
68+
1. **Observation or preference** → Governed runtime memory, when configured
69+
2. **Accepted team-wide behavior change** → The accountable tracked instruction or skill source, through a focused PR
70+
3. **Adjacent improvement** → Report separately and require explicit user approval before adding it to scope
7071

7172
### Phase 2: Analyze Conversation
7273

@@ -128,15 +129,15 @@ Present findings:
128129
│ │
129130
│ [HIGH] + Add constraint: "{specific constraint}" │
130131
│ Source: "{quoted user correction}" │
131-
│ Target: .squad/decisions/inbox/{agent}-{topic}.md │
132+
│ Target: tracked governing source via focused PR │
132133
│ │
133134
│ [MED] + Add preference: "{specific preference}" │
134135
│ Source: "{evidence from conversation}" │
135-
│ Target: .squad/agents/{agent}/history.md │
136+
│ Target: governed runtime memory │
136137
│ │
137138
│ [LOW] ~ Note for review: "{observation}" │
138139
│ Source: "{pattern observed}" │
139-
│ Target: Session notes only │
140+
│ Target: report only; no persistence │
140141
│ │
141142
├─────────────────────────────────────────────────────────────┤
142143
│ Apply changes? [Y/n/edit] │
@@ -158,17 +159,17 @@ Present findings:
158159

159160
After user approval:
160161

161-
1. **For Agent History:**
162-
- Append to `.squad/agents/{agent}/history.md` under `## Learnings` section
163-
- Format: Date, assignment context, key learning
162+
1. **For Runtime Memory:**
163+
- Use the configured governed memory or state tool.
164+
- If no runtime persistence tool is available, report the learning without claiming it was saved.
164165

165-
2. **For Team Decisions:**
166-
- Create `.squad/decisions/inbox/{agent}-{topic}.md`
167-
- Lead agent reviews and merges to `decisions.md` if appropriate
166+
2. **For Behavioral Changes:**
167+
- Route the accountable specialist to update the minimum tracked governing source.
168+
- Validate the change and open a focused PR.
168169

169-
3. **For Skills:**
170-
- Document recommendation in session notes
171-
- Squad lead reviews and routes to skill owner
170+
3. **Never Use Throwaway Proposal Files:**
171+
- Do not create local or gitignored Markdown proposals, including `.squad/decisions/inbox/*.md`, for reflection or directive capture.
172+
- Runtime memory may preserve context, but it does not replace the tracked source change required to alter behavior.
172173

173174
---
174175

@@ -186,7 +187,8 @@ User: "No, use the code search tools first, grep is too slow"
186187
```
187188
[HIGH] + Add constraint: "Use code intelligence tools before grep"
188189
Source: "No, use the code search tools first, grep is too slow"
189-
Target: .squad/agents/{agent}/history.md
190+
Target: accountable tracked instruction via focused PR; governed runtime
191+
memory for context only
190192
```
191193

192194
### Example 2: Success Pattern
@@ -201,7 +203,8 @@ User: "Perfect! This is exactly the format I want for all PRs"
201203
```
202204
[MED] + Add preference: "Include test plan in PR descriptions"
203205
Source: User praised detailed PR format
204-
Target: .squad/decisions/inbox/pr-format.md (for team adoption)
206+
Target: governed runtime memory; if adopted as team behavior, update the
207+
accountable tracked instruction in a focused PR
205208
```
206209

207210
---
@@ -224,6 +227,6 @@ User: "Perfect! This is exactly the format I want for all PRs"
224227

225228
## See Also
226229

227-
- `.squad/decisions.md` — Team-wide decisions
228-
- `.squad/agents/*/history.md` — Agent-specific learnings
230+
- `.squad/decisions.md` — Runtime-backed team decisions
231+
- `.github/agents/squad.agent.md` — Coordinator behavior
229232
- `.squad/routing.md` — Work assignment patterns

‎.squad-templates/squad.agent.md‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,7 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa
247247

248248
### Directive Capture
249249

250-
**Before routing any message, check: is this a directive?** A directive is a user statement that sets a preference, rule, or constraint the team should remember. Capture it to the decisions inbox BEFORE routing work.
250+
**Before routing any message, check: is this a directive?** A directive is a user statement that sets a preference, rule, or constraint the team should remember.
251251

252252
**Directive signals** (capture these):
253253
- "Always…", "Never…", "From now on…", "We don't…", "Going forward…"
@@ -262,19 +262,22 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa
262262

263263
**When you detect a directive:**
264264

265-
1. Capture the directive with governed memory tools when available:
266-
- Prefer `memory.write` with class `decision` to persist the directive through the governed pipeline:
265+
1. Capture the directive only with governed runtime memory tools when available:
266+
- Prefer `memory.write` with class `DECISION` to persist the directive through the governed pipeline:
267267
```
268268
memory.write({
269-
class: "decision",
270-
key: "copilot-directive-{timestamp}",
269+
class: "DECISION",
270+
title: "User directive - {timestamp}",
271+
author: "{user name} (via Copilot)",
271272
content: "### {timestamp}: User directive\n**By:** {user name} (via Copilot)\n**What:** {the directive, verbatim or lightly paraphrased}\n**Why:** User request — captured for team memory"
272273
})
273274
```
274-
- If `memory.write` is not available, fall back to `squad_decide` or `squad_state_write` to `decisions/inbox/copilot-directive-{timestamp}.md`.
275+
- If `memory.write` is unavailable, use another configured runtime state tool such as `squad_decide` or `squad_state_write`.
276+
- Never create a local or gitignored Markdown proposal, including `.squad/decisions/inbox/*.md`, as a persistence fallback. If no runtime state tool is available, acknowledge the directive without pretending it was persisted.
275277
- Do **not** run `git notes`, checkout `squad-state`, or manually commit mutable `.squad/` state. The runtime owns state persistence.
276278
2. Acknowledge briefly: `"📌 Captured. {one-line summary of the directive}."`
277-
3. If the message ALSO contains a work request, route that work normally after capturing. If it's directive-only, you're done — no agent spawn needed.
279+
3. If the directive changes repository behavior, dispatch the accountable specialist to make the minimum tracked source change, validate it, and open a focused PR. Runtime memory records context; it is not the implementation.
280+
4. If the message ALSO contains a work request, route that work normally after capturing. If it is directive-only and requires no repository change, no agent spawn is needed.
278281
279282
### Memory Governance Tools
280283
@@ -306,6 +309,15 @@ For `STATE_BACKEND ∈ {"local", "worktree"}`, file writes to `.squad/` are vali
306309
307310
### Routing
308311
312+
### Scope Control
313+
314+
The Coordinator owns preserving the scope the user requested.
315+
316+
- Every specialist prompt must state the requested deliverable and explicit exclusions.
317+
- Specialists must complete only that scope. Adjacent issues, cleanup opportunities, or follow-on ideas are reported separately and must not be implemented, edited, or delegated as part of the current work.
318+
- Expanding scope requires explicit user approval. The Coordinator must present the adjacent discovery separately and wait for that approval before routing additional work.
319+
- If expansion is approved, route it as distinct focused work; do not silently fold it into the original task or PR.
320+
309321
The routing table determines **WHO** handles work. After routing, use Response Mode Selection to determine **HOW** (Direct/Lightweight/Standard/Full).
310322
311323
| Signal | Action |

0 commit comments

Comments
 (0)