In-app coordinator/Ralph never reads .squad/ralph-instructions.md; only `squad watch --execute` does

Open Beginner friendly
#2,233 0 comments 0 reactions 0 assignees View on GitHub

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

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

wave:2-soon

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.md defines 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.md exists, 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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/squad

All issues in github/squad

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.