DX: .squad/ralph-instructions.md is an undocumented escape hatch in squad watch --execute — document it or remove it #1314

Summary

squad watch --execute contains an undocumented escape hatch at .squad/ralph-instructions.md. The code reads the file if present and points the spawned copilot session at it, but:

• No template ships in packages/squad-cli/templates or packages/squad-sdk/templates
• No README/docs mention it — gh search code "ralph-instructions" --repo bradygaster/squad --extension md returns empty
• No issue introduces it — only the implementation and its test know it exists
• squad init / squad upgrade do not create one
• Format is unconstrained — anyone creating one is inventing the shape

This is a real DX trap: users (and AI assistants helping them) who discover the code path naturally describe it as "the way to customize Ralph's behavior," but there's nothing to guide format, stability, or supported keys — and a future refactor could silently break every user who took the bait.

Where it lives

packages/squad-cli/src/cli/commands/watch/capabilities/execute.ts:

const hasInstructions = existsSync(path.join(teamRoot, '.squad', 'ralph-instructions.md'));
if (hasInstructions) {
  return [
    'Ralph, Go! Read .squad/ralph-instructions.md for your full instructions. Follow ALL sections there. MAXIMIZE PARALLELISM — spawn agents for ALL actionable issues simultaneously.',
    '',
    'Here are the current open squad issues:',
    issueList,
    // ...
  ].join('\n');
}
// fallback prompt — never mentions ralph-instructions.md

Both branches are asserted in test/cli/watch-capabilities.test.ts, so the feature is intentional, just unsurfaced.

How users hit this

Real scenario from --execute adoption: user has MCPs wired into Copilot (Teams, WorkIQ, calendar), runs squad watch --execute, expects the spawned session to use the MCPs (e.g., post Teams notifications). Nothing happens. Looking at the code, the natural fix surfaces: "there's a file the agent will read if it exists." User creates one, invents a format, it works today — and silently breaks the day someone refactors execute.ts.

Asks

Pick one:

Option A — Promote to a documented feature (preferred if the maintainers want the extension point):

• Ship a template at packages/squad-cli/templates/ralph-instructions.md (referenced from TEMPLATE_MANIFEST in templates.ts) so squad init / squad upgrade create a stub with comments showing supported placeholders
• Document in CLI README under squad watch --execute
• Specify the contract — what the file CAN influence (extra agent instructions, post-task hooks, Teams/email notifications) and what it CANNOT (parallelism, eligibility filters)

Option B — Remove the dead code path:

• Delete the existsSync branch in execute.ts and the corresponding test
• All Ralph customization happens via issue body content (already the documented path)

Related closed issue: #1081 (spawned session does not receive specialist charter — different root cause but same surface area).

Repro

# In any squad-initialized repo:
ls .squad/ralph-instructions.md   # → not found
gh search code "ralph-instructions" --repo bradygaster/squad --extension md  # → []
grep -r "ralph-instructions" packages/squad-cli/templates/  # → no template
grep -r "ralph-instructions" packages/squad-sdk/templates/  # → no template

# But the code branches on it:
grep -n "ralph-instructions" packages/squad-cli/src/cli/commands/watch/capabilities/execute.ts

Verified against @bradygaster/squad-cli@0.9.6-insider.3.