Skip to content

bug: ship missing on-demand playbooks referenced by squad.agent.md #1100

Closed

Description

@thecrockster

squad.agent.md currently references several .squad/templates/*.md playbooks that are not shipped by init or upgrade,
so a freshly initialized or upgraded repo can end up with coordinator instructions that point at files that do not
exist.

Missing referenced files

  • .squad/templates/ceremony-reference.md
  • .squad/templates/ralph-reference.md
  • .squad/templates/prd-intake.md
  • .squad/templates/human-members.md
  • .squad/templates/copilot-agent.md

What we found

  • The coordinator prompt references these as on-demand playbooks.
  • squad init and squad upgrade ship template files by copying from .squad-templates/.
  • These files are not present in the shipped template set, so they are never copied into .squad/templates/.

Why this matters

When one of these modes is triggered, the coordinator is instructed to read a playbook that the user’s repo does not
have. That means the prompt is ahead of the actual shipped assets, which creates drift and makes the modular prompt
architecture unreliable.

Expected behaviour

One of these should be true:

  1. The referenced playbooks exist in .squad-templates/ and are shipped into .squad/templates/ by init/upgrade, or
  2. squad.agent.md is updated to stop referencing these files and instead point to the correct existing source.

Suggested fix

  • Add the missing playbook files to .squad-templates/
  • Ensure template sync mirrors them to:
  • templates/
  • packages/squad-cli/templates/
  • packages/squad-sdk/templates/
  • user repos via init / upgrade
  • Add regression coverage so referenced .squad/templates/* files in squad.agent.md must exist in the shipped
    template set

Acceptance criteria

  • All .squad/templates/... references in squad.agent.md resolve to files actually shipped by init/upgrade
  • New repos created with squad init contain these files under .squad/templates/
  • Existing repos updated with squad upgrade receive them
  • A test fails if squad.agent.md references a non-shipped template file

Activity

  1. changed the title [-]Ship missing on-demand playbooks referenced by squad.agent.md[/-] [+]bug: ship missing on-demand playbooks referenced by squad.agent.md[/+] on May 8, 2026
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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions