fix(templates): make coordinator read ralph-instructions.md before dispatch by pujitha24 · Pull Request #2304 · github/squad

pujitha24 · 2026-10-24T11:40:28Z

What

Adds a "User-owned rules" line to the Ralph section of squad.agent.md so the in-app coordinator reads .squad/ralph-instructions.md before dispatching issue work. Also replaces the self-reference in ralph-reference.md (which pointed at itself as its "on-demand reference") with a pointer to that file. The canonical .squad-templates copies were edited and propagated with scripts/sync-templates.mjs, the tracked .squad/templates copy was updated, and a changeset was added. This is prompt text only.

Why

.squad/ralph-instructions.md is the user-owned file for Ralph's repo rules, but only squad watch --execute told the session to read it. The in-app coordinator's Ralph section and ralph-reference.md never mentioned it, so those rules were skipped when the coordinator dispatched issue work.

Closes #2233

How

Added a "User-owned rules" line to the Ralph section of squad.agent.md.
Replaced the self-reference in ralph-reference.md.
Edited the canonical .squad-templates copies and propagated them with scripts/sync-templates.mjs, plus the tracked .squad/templates copy.
Added a changeset.

Validation: ran npm run build and npx vitest run test/ralph-reference-authority.test.ts test/cli/init-upgrade-parity.test.ts test/cli/upgrade-portability.test.ts test/template-sync.test.ts (463 passed). I did not run a live coordinator session, so the effect on model output is not observed. The full test suite and eslint were not run.

⚠️ Quick Check

If SDK/CLI source files changed: completed the applicable Changeset step below (npx changeset add / .changeset/*.md, direct CHANGELOG.md entry for maintainers, or skip-changelog label for no user-facing changes)

PR Readiness Checklist

The PR readiness bot will validate these automatically after push.
Check each item before requesting review. See CONTRIBUTING.md for full details.

Branch & Commit

Branch created from dev (not main)
Branch is up to date with dev (git fetch upstream && git rebase upstream/dev)
Verified diff contains only intended changes (git diff --cached --stat)
PR is not in draft mode (mark ready when checks pass)
Commit history is clean (squash fixups before review)

Build & Test

npm run build passes
npm test passes (all tests green)
npm run lint passes (type check clean)
npm run lint:eslint passes
For migration PRs (>20 files): include test output summary in PR description

Changeset

Changeset added via npx changeset add (if packages/squad-sdk/src/ or packages/squad-cli/src/ changed)
Or direct CHANGELOG.md entry (maintainers only — write-protected for external contributors)
Or skip-changelog label applied (if no user-facing changes)

Docs

N/A. This only changes prompt text in templates, with no new feature or user-facing capability.

README section updated (if new feature/module)
Docs feature page (if new user-facing capability)

Exports

N/A. No new modules.

package.json subpath exports updated (if new module)

Breaking Changes

None

Waivers

Not requested for the PR-readiness items above. I did not run the full npm test suite, npm run lint or npm run lint:eslint. Only the targeted vitest files listed in "How" were run.

AI assistance: this change was drafted with Claude Code.

…spatch Motivation: .squad/ralph-instructions.md is the user-owned file for Ralph's repo rules, but only `squad watch --execute` told the session to read it. The in-app coordinator's Ralph section and ralph-reference.md never mentioned it, so those rules were skipped when the coordinator dispatched issue work. ralph-reference.md also pointed at itself as its "on-demand reference". Approach: add a "User-owned rules" line to the Ralph section of squad.agent.md and replace the self-reference in ralph-reference.md. Edited the canonical .squad-templates copies and propagated with scripts/sync-templates.mjs, plus the tracked .squad/templates copy. Added a changeset. This is prompt text only. Validation: ran `npm run build` and `npx vitest run test/ralph-reference-authority.test.ts test/cli/init-upgrade-parity.test.ts test/cli/upgrade-portability.test.ts test/template-sync.test.ts` (463 passed). Did not run a live coordinator session, so the behavioural effect on model output is not observed; the full test suite and eslint were not run. Report: https://github.com/bradygaster/squad/issues/2233 Signed-off-by: Pujitha Paladugu <10557236+pujitha24@users.noreply.github.com> Assisted-by: claude-sonnet-5-5 (via Claude Code)

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

github-actions · 2026-10-24T11:40:39Z

🟠 Impact Analysis — PR #2304

Risk tier: 🟠 HIGH

📊 Summary

Metric	Count
Files changed	18
Files added	1
Files modified	17
Files deleted	0
Modules touched	8

🎯 Risk Factors

18 files changed (6-20 → MEDIUM)
8 modules touched (5-8 → HIGH)

📦 Modules Affected

ci-workflows (1 file)

.github/agents/squad.agent.md

docs (1 file)

docs/src/content/docs/features/ralph.md

root (4 files)

.changeset/ralph-instructions-coordinator.md
templates/ralph-instructions.md
templates/ralph-reference.md
templates/squad.agent.md.template

squad-cli (3 files)

packages/squad-cli/templates/ralph-instructions.md
packages/squad-cli/templates/ralph-reference.md
packages/squad-cli/templates/squad.agent.md.template

squad-sdk (3 files)

packages/squad-sdk/templates/ralph-instructions.md
packages/squad-sdk/templates/ralph-reference.md
packages/squad-sdk/templates/squad.agent.md.template

squad-state (2 files)

.squad/ralph-instructions.md
.squad/templates/ralph-reference.md

templates (3 files)

.squad-templates/ralph-instructions.md
.squad-templates/ralph-reference.md
.squad-templates/squad.agent.md

tests (1 file)

test/ralph-reference-authority.test.ts

This report is generated automatically for every PR. See #733 for details.

github-actions · 2026-10-24T11:40:41Z

⚠️ Squad File Leakage Detected

Authoritative evidence: base-controlled pull_request_target reporter.

The following .squad/ files were modified in this PR:

.squad/ralph-instructions.md
.squad/templates/ralph-reference.md

These files affect team routing, agent charters, and decisions.
If intentional, ensure approval from the team lead.

github-actions · 2026-10-24T11:40:42Z

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit c63ae7d

PR Scope: 🔧 Infrastructure

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	4 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	⚠️ PR includes 2 .squad/ file(s) — ensure these are intentional
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	No Copilot review threads
❌	CI passing	16 check(s) still running

Files Changed (18 files, +55 −6)

File	+/−
`.changeset/ralph-instructions-coordinator.md`	+6 −0
`.github/agents/squad.agent.md`	+2 −0
`.squad-templates/ralph-instructions.md`	+3 −0
`.squad-templates/ralph-reference.md`	+1 −1
`.squad-templates/squad.agent.md`	+2 −0
`.squad/ralph-instructions.md`	+3 −0
`.squad/templates/ralph-reference.md`	+1 −1
`docs/src/content/docs/features/ralph.md`	+1 −1
`packages/squad-cli/templates/ralph-instructions.md`	+3 −0
`packages/squad-cli/templates/ralph-reference.md`	+1 −1
`packages/squad-cli/templates/squad.agent.md.template`	+2 −0
`packages/squad-sdk/templates/ralph-instructions.md`	+3 −0
`packages/squad-sdk/templates/ralph-reference.md`	+1 −1
`packages/squad-sdk/templates/squad.agent.md.template`	+2 −0
`templates/ralph-instructions.md`	+3 −0
`templates/ralph-reference.md`	+1 −1
`templates/squad.agent.md.template`	+2 −0
`test/ralph-reference-authority.test.ts`	+18 −0

Total: +55 −6

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

tamirdresher · 2026-10-24T11:59:28Z

Thanks for picking up #2233 — the placement in the Ralph section and the template propagation (all five copies of each file match, .squad/templates hand-synced as ralph-reference-authority.test.ts requires) look right. One thing I think needs fixing before merge, plus a couple of smaller notes:

1. Path bug (blocking). In squad.agent.md, TEAM_ROOT is the .squad directory — see Worktree Awareness ("team root is the local .squad/ directory… All subsequent .squad/ path references use this root") and the existing {TEAM_ROOT}/team.md / {TEAM_ROOT}/decisions.md references. So {TEAM_ROOT}/.squad/ralph-instructions.md resolves to .squad/.squad/…, the "if it exists" guard is false, and the rule is skipped — the same symptom as the issue. It should be {TEAM_ROOT}/ralph-instructions.md. (The issue's suggested text borrowed the CLI's teamRoot = repo-root convention from execute.ts.)

2. "Same precedence as squad watch --execute" — in watch mode the file replaces the fallback prompt, and the stock file says "work on every open, unblocked, unassigned issue". Read literally before work on #42, that widens scope. Suggest: "apply its rules on top of this file; it does not widen the requested scope or replace Ralph's monitor-only role."

3. Docs: ralph-instructions.md's header and docs/features/ralph.md still say only watch --execute reads the file — worth one sentence each.

4. CONTRIBUTING asks for an E2E run on .squad-templates/*.md changes; a quick squad init + "Ralph, status" would have caught (1). An assertion on the {TEAM_ROOT}/ralph-instructions.md path in ralph-reference-authority.test.ts would keep it from regressing.

…clarify scope, add docs and test Signed-off-by: Pujitha Paladugu <10557236+pujitha24@users.noreply.github.com>

pujitha24 · 2026-10-24T12:30:58Z

You're right about the path: TEAM_ROOT is the .squad dir, so the old text resolved to .squad/.squad/ and the guard never fired. All five coordinator copies now say {TEAM_ROOT}/ralph-instructions.md, and I replaced the "same precedence as watch --execute" line with "apply its rules on top of this file... does not widen the requested scope or replace Ralph's monitor-only role". I added a sentence to the ralph-instructions.md header (all five copies) and to docs/src/content/docs/features/ralph.md, plus a test in ralph-reference-authority.test.ts that checks the path in each coordinator file.

I ran ralph-reference-authority.test.ts and it passes. I haven't done the squad init + "Ralph, status" E2E run, so that's still open. Locally, upgrade-portability.test.ts fails with and without my change (it expects the node binary path but gets npx), and init-upgrade-parity.test.ts fails to load because of an SDK import error. I didn't dig into either.

github-actions · 2026-11-02T14:06:21Z

👋 Friendly nudge — this PR has had no activity for 8 days.

What needs attention:

👀 No approving reviews yet. Request a review from a teammate.
⬇️ 31 commits behind dev. Rebase to pick up latest changes.

If this PR is abandoned, please close it. If it's blocked on something external, leave a comment so the team knows.
This is an automated check that runs on weekdays. It won't nudge the same PR more than once per week.

pujitha24 requested review from bradygaster and tamirdresher as code owners October 24, 2026 11:40

Copilot AI balanced review requested due to automatic review settings October 24, 2026 11:40

Copilot AI reviewed Oct 24, 2026

pujitha24 added 2 commits October 24, 2026 05:29

Merge remote-tracking branch 'upstream/dev' into auto/issue-2233

ddba26b

fix(templates): resolve ralph-instructions.md relative to TEAM_ROOT, …

1aaec7d

…clarify scope, add docs and test Signed-off-by: Pujitha Paladugu <10557236+pujitha24@users.noreply.github.com>

Merge branch 'dev' into auto/issue-2233

c63ae7d

Navigation Menu

Repository navigation

fix(templates): make coordinator read ralph-instructions.md before dispatch - #2304

fix(templates): make coordinator read ralph-instructions.md before dispatch#2304
pujitha24 wants to merge 4 commits into
github:devfrom
pujitha24:auto/issue-2233

pujitha24 commented Oct 24, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 24, 2026 •

edited

Loading

Uh oh!

tamirdresher commented Oct 24, 2026

Uh oh!

pujitha24 commented Oct 24, 2026

Uh oh!

github-actions Bot commented Nov 2, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

pujitha24 commented Oct 24, 2026

What

Why

How

⚠️ Quick Check

PR Readiness Checklist

Branch & Commit

Build & Test

Changeset

Docs

Exports

Breaking Changes

Waivers

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟠 Impact Analysis — PR #2304

📊 Summary

🎯 Risk Factors

📦 Modules Affected

Uh oh!

github-actions Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Squad File Leakage Detected

Uh oh!

github-actions Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛫 PR Readiness Check

⚠️ 3 item(s) to address before review

Files Changed (18 files, +55 −6)

Uh oh!

tamirdresher commented Oct 24, 2026

Uh oh!

pujitha24 commented Oct 24, 2026

Uh oh!

github-actions Bot commented Nov 2, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Oct 24, 2026 •

edited

Loading

github-actions Bot commented Oct 24, 2026 •

edited

Loading

github-actions Bot commented Oct 24, 2026 •

edited

Loading