In-app coordinator/Ralph never reads .squad/ralph-instructions.md; only `squad watch --execute` does
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 78/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- github, typescript
- Domain
- developer-experience, tooling
Research direction
Read .github/agents/squad.agent.md and .squad/templates/ralph-reference.md, then compare their instructions with the behavior described for squad watch --execute. Update the Ralph dispatch instructions to load .squad/ralph-instructions.md when it exists, and fix the reference file's self-reference. Done when in-app dispatch paths follow the user-owned instructions and the reference chain points to the intended file.
Written by the indexing model from the issue text.
Description
Problem
.squad/ralph-instructions.md is the user-owned file for Ralph's repo rules. Its own header says squad init creates it and squad upgrade never overwrites it. But only squad watch --execute tells the spawned session to read it.
The in-app path never mentions the file. "Ralph, go" and coordinator-driven issue dispatch run from .github/agents/squad.agent.md (coordinator v1.0.1) and its on-demand .squad/templates/ralph-reference.md, and neither references .squad/ralph-instructions.md. So any rule a user writes there is skipped whenever the coordinator, rather than watch --execute, dispatches issue work.
Observed with squad-cli 1.0.1 on Windows:
- The repo's
ralph-instructions.mddefines a multi-host claim protocol: assign the issue, comment "Claimed by ", and run an election over the issue timeline. - An in-app coordinator session dispatched about 10 issue sessions without claiming any of them.
- Two issues were worked twice by the same coordinator across context windows, which a claim check would have prevented.
- Other rules in that file are skipped too, including host concurrency limits and the round-report format.
.squad/templates/ralph-reference.md line 11 also points to itself ("Read .squad/templates/ralph-reference.md…"), so the reference chain ends there.
Expected
Every Ralph/coordinator work-dispatch path loads .squad/ralph-instructions.md when it exists, with the same precedence watch --execute gives it. That way the user-owned rules apply no matter how work is dispatched.
Suggested fix
- In
squad.agent.md, in the Ralph section and before any issue dispatch: "If{TEAM_ROOT}/.squad/ralph-instructions.mdexists, read it and follow it before selecting or dispatching issue work." - Fix the self-reference in
templates/ralph-reference.md. - Optionally, have the coordinator load it once per session alongside
team.md/routing.md.
Workaround
Add a pointer in .github/copilot-instructions.md, which squad upgrade does not manage.
Related: #1314 (documenting the escape hatch).
- Dominant language
- TypeScript
- Stars
- 3.4k
- Forks
- 516
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 116
Getting set up
- Ships a Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from github/squad
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 67/100
ilan-pinto/roaring-lions#1552 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
bug: [React Native/Android] KeepAliveService never starts when CAMERA is not granted (Android 14+)Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
cloudflare/realtimekit-ui#208 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
usebruno/bruno-vscode#235 ·
Maintainers usually reply within 3 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day