Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 6 additions & 0 deletions .changeset/coordinator-scope-persistence.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@bradygaster/squad-cli": patch
"@bradygaster/squad-sdk": patch
---

Require coordinators to preserve user-approved scope and prevent directive or reflection capture from falling back to local Markdown proposals.
26 changes: 19 additions & 7 deletions .github/agents/squad.agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,7 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa

### Directive Capture

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

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

**When you detect a directive:**

1. Capture the directive with governed memory tools when available:
- Prefer `memory.write` with class `decision` to persist the directive through the governed pipeline:
1. Capture the directive only with governed runtime memory tools when available:
- Prefer `memory.write` with class `DECISION` to persist the directive through the governed pipeline:
```
memory.write({
class: "decision",
key: "copilot-directive-{timestamp}",
class: "DECISION",
title: "User directive - {timestamp}",
author: "{user name} (via Copilot)",
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"
})
```
- If `memory.write` is not available, fall back to `squad_decide` or `squad_state_write` to `decisions/inbox/copilot-directive-{timestamp}.md`.
- If `memory.write` is unavailable, use another configured runtime state tool such as `squad_decide` or `squad_state_write`.
- 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.
- Do **not** run `git notes`, checkout `squad-state`, or manually commit mutable `.squad/` state. The runtime owns state persistence.
2. Acknowledge briefly: `"📌 Captured. {one-line summary of the directive}."`
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.
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.
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.

### Memory Governance Tools

Expand Down Expand Up @@ -306,6 +309,15 @@ For `STATE_BACKEND ∈ {"local", "worktree"}`, file writes to `.squad/` are vali

### Routing

### Scope Control

The Coordinator owns preserving the scope the user requested.

- Every specialist prompt must state the requested deliverable and explicit exclusions.
- 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.
- Expanding scope requires explicit user approval. The Coordinator must present the adjacent discovery separately and wait for that approval before routing additional work.
- If expansion is approved, route it as distinct focused work; do not silently fold it into the original task or PR.

The routing table determines **WHO** handles work. After routing, use Response Mode Selection to determine **HOW** (Direct/Lightweight/Standard/Full).

| Signal | Action |
Expand Down
51 changes: 27 additions & 24 deletions .github/skills/reflect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,16 @@ Analyze conversations and propose improvements to squad knowledge based on what

**Reflect complements existing Squad knowledge systems:**

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

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

---

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

Determine what knowledge system should be updated:

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

### Phase 2: Analyze Conversation

Expand Down Expand Up @@ -128,15 +129,15 @@ Present findings:
│ │
│ [HIGH] + Add constraint: "{specific constraint}" │
│ Source: "{quoted user correction}" │
│ Target: .squad/decisions/inbox/{agent}-{topic}.md │
│ Target: tracked governing source via focused PR │
│ │
│ [MED] + Add preference: "{specific preference}" │
│ Source: "{evidence from conversation}" │
│ Target: .squad/agents/{agent}/history.md │
│ Target: governed runtime memory │
│ │
│ [LOW] ~ Note for review: "{observation}" │
│ Source: "{pattern observed}" │
│ Target: Session notes only │
│ Target: report only; no persistence │
│ │
├─────────────────────────────────────────────────────────────┤
│ Apply changes? [Y/n/edit] │
Expand All @@ -158,17 +159,17 @@ Present findings:

After user approval:

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

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

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

---

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

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

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

## See Also

- `.squad/decisions.md` — Team-wide decisions
- `.squad/agents/*/history.md` — Agent-specific learnings
- `.squad/decisions.md` — Runtime-backed team decisions
- `.github/agents/squad.agent.md` — Coordinator behavior
- `.squad/routing.md` — Work assignment patterns
51 changes: 27 additions & 24 deletions .squad-templates/skills/reflect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,16 @@ Analyze conversations and propose improvements to squad knowledge based on what

**Reflect complements existing Squad knowledge systems:**

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

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

---

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

Determine what knowledge system should be updated:

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

### Phase 2: Analyze Conversation

Expand Down Expand Up @@ -128,15 +129,15 @@ Present findings:
│ │
│ [HIGH] + Add constraint: "{specific constraint}" │
│ Source: "{quoted user correction}" │
│ Target: .squad/decisions/inbox/{agent}-{topic}.md │
│ Target: tracked governing source via focused PR │
│ │
│ [MED] + Add preference: "{specific preference}" │
│ Source: "{evidence from conversation}" │
│ Target: .squad/agents/{agent}/history.md │
│ Target: governed runtime memory │
│ │
│ [LOW] ~ Note for review: "{observation}" │
│ Source: "{pattern observed}" │
│ Target: Session notes only │
│ Target: report only; no persistence │
│ │
├─────────────────────────────────────────────────────────────┤
│ Apply changes? [Y/n/edit] │
Expand All @@ -158,17 +159,17 @@ Present findings:

After user approval:

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

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

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

---

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

### Example 2: Success Pattern
Expand All @@ -201,7 +203,8 @@ User: "Perfect! This is exactly the format I want for all PRs"
```
[MED] + Add preference: "Include test plan in PR descriptions"
Source: User praised detailed PR format
Target: .squad/decisions/inbox/pr-format.md (for team adoption)
Target: governed runtime memory; if adopted as team behavior, update the
accountable tracked instruction in a focused PR
Comment thread
bradygaster marked this conversation as resolved.
Resolved
```

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

## See Also

- `.squad/decisions.md` — Team-wide decisions
- `.squad/agents/*/history.md` — Agent-specific learnings
- `.squad/decisions.md` — Runtime-backed team decisions
- `.github/agents/squad.agent.md` — Coordinator behavior
- `.squad/routing.md` — Work assignment patterns
26 changes: 19 additions & 7 deletions .squad-templates/squad.agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,7 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa

### Directive Capture

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

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

**When you detect a directive:**

1. Capture the directive with governed memory tools when available:
- Prefer `memory.write` with class `decision` to persist the directive through the governed pipeline:
1. Capture the directive only with governed runtime memory tools when available:
Comment thread
bradygaster marked this conversation as resolved.
Resolved
- Prefer `memory.write` with class `DECISION` to persist the directive through the governed pipeline:
```
memory.write({
class: "decision",
key: "copilot-directive-{timestamp}",
class: "DECISION",
title: "User directive - {timestamp}",
author: "{user name} (via Copilot)",
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"
})
```
- If `memory.write` is not available, fall back to `squad_decide` or `squad_state_write` to `decisions/inbox/copilot-directive-{timestamp}.md`.
- If `memory.write` is unavailable, use another configured runtime state tool such as `squad_decide` or `squad_state_write`.
- 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.
- Do **not** run `git notes`, checkout `squad-state`, or manually commit mutable `.squad/` state. The runtime owns state persistence.
2. Acknowledge briefly: `"📌 Captured. {one-line summary of the directive}."`
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.
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.
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.

### Memory Governance Tools

Expand Down Expand Up @@ -306,6 +309,15 @@ For `STATE_BACKEND ∈ {"local", "worktree"}`, file writes to `.squad/` are vali

### Routing

### Scope Control

The Coordinator owns preserving the scope the user requested.

- Every specialist prompt must state the requested deliverable and explicit exclusions.
- 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.
- Expanding scope requires explicit user approval. The Coordinator must present the adjacent discovery separately and wait for that approval before routing additional work.
- If expansion is approved, route it as distinct focused work; do not silently fold it into the original task or PR.

The routing table determines **WHO** handles work. After routing, use Response Mode Selection to determine **HOW** (Direct/Lightweight/Standard/Full).

| Signal | Action |
Expand Down
Loading
Loading