diff --git a/.changeset/coordinator-scope-persistence.md b/.changeset/coordinator-scope-persistence.md new file mode 100644 index 000000000..3b673e1d0 --- /dev/null +++ b/.changeset/coordinator-scope-persistence.md @@ -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. diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md index 5d8e66337..47dea3af4 100644 --- a/.github/agents/squad.agent.md +++ b/.github/agents/squad.agent.md @@ -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…" @@ -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 @@ -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 | diff --git a/.github/skills/reflect/SKILL.md b/.github/skills/reflect/SKILL.md index 6a85b5190..edc4fd1a4 100644 --- a/.github/skills/reflect/SKILL.md +++ b/.github/skills/reflect/SKILL.md @@ -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 --- @@ -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 @@ -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] │ @@ -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. --- @@ -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 @@ -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 ``` --- @@ -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 diff --git a/.squad-templates/skills/reflect/SKILL.md b/.squad-templates/skills/reflect/SKILL.md index 6a85b5190..edc4fd1a4 100644 --- a/.squad-templates/skills/reflect/SKILL.md +++ b/.squad-templates/skills/reflect/SKILL.md @@ -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 --- @@ -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 @@ -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] │ @@ -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. --- @@ -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 @@ -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 ``` --- @@ -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 diff --git a/.squad-templates/squad.agent.md b/.squad-templates/squad.agent.md index 5d8e66337..47dea3af4 100644 --- a/.squad-templates/squad.agent.md +++ b/.squad-templates/squad.agent.md @@ -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…" @@ -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 @@ -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 | diff --git a/packages/squad-cli/templates/skills/reflect/SKILL.md b/packages/squad-cli/templates/skills/reflect/SKILL.md index 6a85b5190..edc4fd1a4 100644 --- a/packages/squad-cli/templates/skills/reflect/SKILL.md +++ b/packages/squad-cli/templates/skills/reflect/SKILL.md @@ -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 --- @@ -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 @@ -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] │ @@ -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. --- @@ -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 @@ -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 ``` --- @@ -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 diff --git a/packages/squad-cli/templates/squad.agent.md.template b/packages/squad-cli/templates/squad.agent.md.template index 5d8e66337..47dea3af4 100644 --- a/packages/squad-cli/templates/squad.agent.md.template +++ b/packages/squad-cli/templates/squad.agent.md.template @@ -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…" @@ -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 @@ -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 | diff --git a/packages/squad-sdk/templates/skills/reflect/SKILL.md b/packages/squad-sdk/templates/skills/reflect/SKILL.md index 6a85b5190..edc4fd1a4 100644 --- a/packages/squad-sdk/templates/skills/reflect/SKILL.md +++ b/packages/squad-sdk/templates/skills/reflect/SKILL.md @@ -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 --- @@ -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 @@ -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] │ @@ -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. --- @@ -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 @@ -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 ``` --- @@ -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 diff --git a/packages/squad-sdk/templates/squad.agent.md.template b/packages/squad-sdk/templates/squad.agent.md.template index 5d8e66337..47dea3af4 100644 --- a/packages/squad-sdk/templates/squad.agent.md.template +++ b/packages/squad-sdk/templates/squad.agent.md.template @@ -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…" @@ -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 @@ -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 | diff --git a/templates/skills/reflect/SKILL.md b/templates/skills/reflect/SKILL.md index 6a85b5190..edc4fd1a4 100644 --- a/templates/skills/reflect/SKILL.md +++ b/templates/skills/reflect/SKILL.md @@ -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 --- @@ -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 @@ -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] │ @@ -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. --- @@ -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 @@ -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 ``` --- @@ -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 diff --git a/templates/squad.agent.md.template b/templates/squad.agent.md.template index 5d8e66337..47dea3af4 100644 --- a/templates/squad.agent.md.template +++ b/templates/squad.agent.md.template @@ -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…" @@ -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 @@ -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 | diff --git a/test/coordinator-scope-control.test.ts b/test/coordinator-scope-control.test.ts new file mode 100644 index 000000000..15c79afdf --- /dev/null +++ b/test/coordinator-scope-control.test.ts @@ -0,0 +1,53 @@ +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +import { describe, expect, it } from 'vitest'; + +const ROOT = resolve(import.meta.dirname, '..'); + +const COORDINATOR_PATHS = [ + '.squad-templates/squad.agent.md', + '.github/agents/squad.agent.md', + 'templates/squad.agent.md.template', + 'packages/squad-cli/templates/squad.agent.md.template', + 'packages/squad-sdk/templates/squad.agent.md.template', +]; + +const REFLECT_PATHS = [ + '.squad-templates/skills/reflect/SKILL.md', + '.github/skills/reflect/SKILL.md', + 'templates/skills/reflect/SKILL.md', + 'packages/squad-cli/templates/skills/reflect/SKILL.md', + 'packages/squad-sdk/templates/skills/reflect/SKILL.md', +]; + +function read(path: string): string { + return readFileSync(resolve(ROOT, path), 'utf8'); +} + +describe('coordinator scope and persistence rules', () => { + it.each(COORDINATOR_PATHS)('%s preserves user scope and forbids local proposal fallback', (path) => { + const content = read(path); + + expect(content).toContain('The Coordinator owns preserving the scope the user requested.'); + expect(content).toContain('Every specialist prompt must state the requested deliverable and explicit exclusions.'); + expect(content).toContain( + '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.', + ); + expect(content).toContain('Expanding scope requires explicit user approval.'); + expect(content).toContain('Never create a local or gitignored Markdown proposal'); + expect(content).toContain('make the minimum tracked source change'); + }); + + it.each(REFLECT_PATHS)('%s routes behavior changes to tracked source and PRs', (path) => { + const content = read(path); + + expect(content).toContain('Report adjacent improvements separately'); + expect(content).toContain('Do not create local or gitignored Markdown proposals'); + expect(content).toContain('update the minimum tracked governing source'); + expect(content).toContain('open a focused PR'); + expect(content).toContain( + 'Target: accountable tracked instruction via focused PR; governed runtime\n memory for context only', + ); + expect(content).not.toContain('Target: .squad/agents/{agent}/history.md'); + }); +});