[mavaali]

What

Adds an explicit prompt-placement contract for custom squad watch and
squad loop agent commands:

• one standalone {prompt} argv token is replaced with the complete generated
  prompt;
• commands without the token keep the existing -p <prompt> behavior; and
• multiple standalone tokens fail before the child process is spawned.

The same helper now serves the live watch capability path, the
backward-compatible watch helper, and loop execution.

Why

--agent-cmd is documented as a custom runner override, but every command
builder previously appended Copilot CLI's -p flag. Alternate engines with
another prompt contract could not be invoked directly. Boundary's --task
flag is one motivating example; this change is generic and adds no Boundary
dependency.

Closes #1707.

How

• Added one exact-token parser in watch/agent-spawn.ts.
• Reused it from every reachable watch and loop custom-command builder.
• Added regression coverage for replacement, legacy fallback, embedded tokens,
  duplicate rejection, multi-word prompts, backward-compatible watch exports,
  and loop.
• Documented that custom engines do not inherit --copilot-flags, automatic MCP
  injection, or squad_state_* tools.
• Added a patch changeset for @bradygaster/squad-cli.

Local validation

• 112 targeted watch/loop tests passed.
• SDK and CLI TypeScript checks passed.
• npm run build -w packages/squad-cli passed.
• Changed TypeScript files reported no ESLint errors.

The corporate npm proxy did not contain two locked root dev packages
(eslint-plugin-n@18.3.0 and @types/node@26.2.0), so the exact full-root
commands are left to PR CI rather than bypassing the approved feed.

---

Quick Check

• Changeset added for the CLI source change.

PR Readiness Checklist

Branch & Commit

• Branch created from dev.
• Branch is up to date with dev.
• Verified diff contains only intended changes.
• PR is not in draft mode.
• Commit history is one clean commit.

Build & Test

• npm run build passes in exact CI dependencies.
• npm test passes in exact CI dependencies.
• Package TypeScript checks pass.
• npm run lint:eslint passes in exact CI dependencies.

Changeset

• Changeset added via .changeset/agent-command-prompt-placeholder.md.

Docs

• README and Ralph/CLI reference docs updated.

Exports

• N/A. No new package subpath.

---

Breaking Changes

None. Commands without {prompt} retain the current -p <prompt> behavior.

Waivers

None requested. Exact full-root checks are pending PR CI.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 0c2a54e

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 3 item(s) to address before review

Status	Check	Details
❌	Single commit	2 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	No Copilot review threads
❌	CI passing	6 check(s) still running

Files Changed (10 files, +125 −20)

File	+/−
.changeset/agent-command-prompt-placeholder.md	+5 −0
README.md	+4 −5
docs/src/content/docs/features/ralph.md	+11 −2
docs/src/content/docs/reference/cli.md	+1 −1
packages/squad-cli/src/cli/commands/loop.ts	+3 −3
packages/squad-cli/src/cli/commands/watch/agent-spawn.ts	+22 −6
packages/squad-cli/src/cli/commands/watch/index.ts	+2 −2
test/cli/loop.test.ts	+14 −0
test/cli/watch-agent-spawn.test.ts	+41 −1
test/cli/watch-execute.test.ts	+22 −0

Total: +125 −20

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🟡 Impact Analysis — PR #1708

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	10
Files added	1
Files modified	9
Files deleted	0
Modules touched	4
Critical files	1

🎯 Risk Factors

• 10 files changed (6-20 → MEDIUM)
• 4 modules touched (2-4 → MEDIUM)
• Critical files touched: packages/squad-cli/src/cli/commands/watch/index.ts

📦 Modules Affected

docs (2 files)

• docs/src/content/docs/features/ralph.md
• docs/src/content/docs/reference/cli.md

root (2 files)

• .changeset/agent-command-prompt-placeholder.md
• README.md

squad-cli (3 files)

• packages/squad-cli/src/cli/commands/loop.ts
• packages/squad-cli/src/cli/commands/watch/agent-spawn.ts
• packages/squad-cli/src/cli/commands/watch/index.ts

tests (3 files)

• test/cli/loop.test.ts
• test/cli/watch-agent-spawn.test.ts
• test/cli/watch-execute.test.ts

⚠️ Critical Files

• packages/squad-cli/src/cli/commands/watch/index.ts

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

👋 Friendly nudge — this PR has had no activity for 7 days.

What needs attention:

• 👀 No approving reviews yet. Request a review from a teammate.
• ⬇️ 30 commits behind dev. Rebase to pick up latest changes.

---

If this PR is abandoned, please close it. If it's blocked on something external, leave a comment so the team knows.
This is an automated check that runs on weekdays. It won't nudge the same PR more than once per week.