Skip to content

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

Open

Description

@jpapiez

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    wave:2-soonWave 2 — next 2-4 weeks

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions