feat: add 'squad watch' — Ralph local watchdog for persistent polling

[spboyer]

Summary

Replaces the aspirational in-session idle-watch polling (which can't actually work — a Copilot agent can't setTimeout to wake itself) with a mechanically sound approach: npx squad watch runs as a standalone local process that polls GitHub every N minutes for new squad work.

Problem

The previous idle-watch spec claimed Ralph could auto-poll on a timer inside a Copilot CLI session. This isn't possible — the agent is request-response. When it ""idles"", it's simply not running. There's no timer mechanism. Users had to manually say ""Ralph, go"" again when new work arrived.

Solution: Three Layers of Ralph

Instead of pretending the agent can schedule itself, we now have three honest, mechanically sound layers:

Layer	When to use	How it works
In-session	You're at the keyboard	""Ralph, go"" — active loop processes all work, then idles
Local watchdog	You're away but machine is on	npx squad watch --interval 10 — standalone process polls GitHub
Cloud heartbeat	Fully unattended	squad-heartbeat.yml — GitHub Actions cron every 30 min

npx squad watch

A new CLI subcommand that runs as a persistent local process:

npx squad watch                    # polls every 10 minutes (default)
npx squad watch --interval 5       # polls every 5 minutes  
npx squad watch --interval 30      # polls every 30 minutes

Each cycle it:

1. Queries GitHub for untriaged squad-labeled issues
2. Auto-triages based on team member roles and keywords
3. Assigns @copilot to squad:copilot issues (if auto-assign is enabled)
4. Reports status to the terminal
5. Waits for the next interval

Ctrl+C to stop. Requires gh CLI authenticated with a PAT.

Changes

index.js (+165 lines)

• Added watch subcommand with --interval N flag
• Help text updated to include watch command
• Uses gh CLI for GitHub API access (same as heartbeat workflow)
• Parses team roster from .ai-team/team.md for triage routing
• Keyword-based triage matching (same logic as squad-heartbeat.yml)

.github/agents/squad.agent.md

• Removed aspirational idle-watch self-scheduling claims
• Critical behavior block: back to honest ""loop until board clear"" semantics
• Removed ""Ralph, check every N minutes"" in-session trigger (moved to CLI)
• Added Watch Mode section documenting squad watch and three-layer architecture
• Simplified Ralph State back to active/idle (removed watching)
• Updated Integration with Follow-Up Work pipeline

docs/features/ralph.md

• Replaced idle-watch section with Watch Mode (npx squad watch) documentation
• Added three-layer table (in-session / local watchdog / cloud heartbeat)
• Updated triggers table and sample prompts
• Simplified state description

Testing

• All 45 existing tests pass
• No test changes needed (watch command requires gh CLI + GitHub repo context for integration testing)

[bradygaster]

Moving to v0.5.0 — this is a feature, and 0.4.1 is focused on QOL/polish. The npx path fix from this PR has been cherry-picked into dev separately. The Ralph watch feature will land in 0.5.0 after the .ai-team → .squad rename (#69).

[bradygaster]

Which honestly? Could be like in half an hour. Or we could do a 0.4.2 and add this. I'm easy here.

[bradygaster]

Keaton's Architectural Review — PR #57

VERDICT: APPROVE with defer to post-v0.5.0 + REQUEST CHANGES (scope)

---

1. Architectural Assessment ✅

The three-layer Ralph design is architecturally sound:

In-session ("Ralph, go"): Active loop processes work → self-chains → idles when clear
Local watchdog (npx squad watch): Standalone process for persistent polling
Cloud heartbeat (Actions cron): Fully unattended monitoring

This correctly addresses the fundamental constraint: agents are request-response and cannot self-schedule. The aspirational idle-watch spec claimed Ralph could poll on a timer inside a Copilot session, but that's impossible — agents can't setTimeout themselves.

The separation of concerns is clean:

• In-session: Ralph remains the coordinator, doesn't pretend to do background scheduling
• Local: Developer machine polling for active work
• Cloud: Truly unattended monitoring via GitHub Actions

This architecture enables new features rather than closing doors — the local watchdog can evolve independently (adding Slack notifications, metric tracking, etc.) without touching Ralph's core coordination logic.

---

2. Code Quality ✅ (with minor notes)

index.js watch implementation (lines 74-238):

• ✅ Clean CLI parsing with --interval flag validation
• ✅ Proper error handling (gh CLI check, team.md existence)
• ✅ Member parsing logic is maintainable
• ✅ Role-based routing heuristics are reasonable (frontend/UI, backend/API, test/QA)
• ✅ Graceful Ctrl+C handling
• ✅ Good use of execSync with error suppression where needed
• ⚠️ Minor: The routing logic is keyword-based and fragile (e.g., "CSS" → frontend). This is fine for v1, but consider extracting to a configurable routing map in team.md for future iterations.
• ⚠️ Minor: No rate limit handling for gh CLI calls — could hit secondary rate limits on busy repos

docs/features/ralph.md:

• ✅ Clear documentation of the three layers
• ✅ Removes aspirational idle-watch claims
• ✅ Honest about what's possible ("Ralph idles — run squad watch for persistence")

squad.agent.md changes:

• ❓ Not visible in diff review — PR description claims "Removed aspirational idle-watch self-scheduling claims, added Watch Mode section" but I couldn't extract the specific changes from the diff. Assuming the changes match the docs/features/ralph.md updates, this should be fine.

---

3. Scope Assessment ⚠️ NEEDS SPLIT

29 files changed — blast radius is TOO LARGE for a single PR:

Core feature (merge together ✅):

• index.js — watch command
• docs/features/ralph.md — Watch Mode docs
• .github/agents/squad.agent.md — Ralph behavior updates (if they exist)
• README.md / CONTRIBUTING.md — watch command mentions

Separate PRs needed:

1. PR: Blog relocation (14 files)

   • docs/blog/*.md moves from team-docs/blog/
   • docs/build.js — new static site generator
   • docs/assets/* — CSS/JS/HTML templates
   • templates/workflows/squad-docs.yml — GitHub Pages deployment
   • Justification: This is a documentation infrastructure change, orthogonal to the Ralph watch feature. It's adding a whole static site build system.

2. PR: Guard policy update (2 files)

   • templates/workflows/squad-main-guard.yml — removes blog exception
   • docs/scenarios/release-process.md — updates forbidden paths docs
   • Justification: This is a policy change ("blog content no longer ships with main"), not a technical feature. Should be discussed separately.

3. PR: Package.json cleanup (1 file)

   • Removes docs/**/* from npm package files
   • Justification: This is a distribution change that should be validated independently.

Why this matters: If any of these secondary changes break something (e.g., the docs build system has a bug, or the guard policy causes workflow failures), it will block the Ralph watch feature — which is high-value and low-risk.

---

4. v0.5.0 Timing ✅

Status: Brady already moved this to v0.5.0 (Feb 15 comment). Smart call.

Conflicts:

• ❌ MERGEABLE: CONFLICTING — PR has merge conflicts with dev
• This needs rebase after Rename .ai-team/ to .squad/ with backward-compatible migration #69 (rename) lands

Recommendation:

• Defer to post-Rename .ai-team/ to .squad/ with backward-compatible migration #69 — the .ai-team → .squad rename will touch team.md, which this PR parses
• Target: v0.5.0 Week 2 — after Rename .ai-team/ to .squad/ with backward-compatible migration #69, Squads in GitHub Enterprise Copilot- Invalid config "Prompt" exceeds max length 30000 #76, Squad undid its own uncommited changes from a previous session #86 are merged
• Risk: LOW — orthogonal to critical v0.5.0 work, doesn't block other issues

---

5. Community Recognition 🎉

This is excellent community work:

• @spboyer identified a real problem (aspirational idle-watch spec was impossible)
• Proposed the correct architectural fix (three-layer Ralph)
• Implemented it cleanly with documentation
• First contributor to tackle Ralph's coordination logic

Suggested recognition:

1. ✅ Blog post: "Community Spotlight: @spboyer Builds Ralph's Watch Mode" (Wave 0.5.0 recap)
2. ✅ CONTRIBUTORS.md: Add @spboyer with "Ralph watch mode architecture & implementation"
3. ✅ GitHub Release Notes: Call out the three-layer Ralph design in v0.5.0 release

---

Final Verdict

APPROVE the core Ralph watch feature — architecture is sound, code is clean, solves a real problem.

REQUEST CHANGES for scope:

1. Split blog relocation into separate PR
2. Split guard policy update into separate PR
3. Rebase after Rename .ai-team/ to .squad/ with backward-compatible migration #69 lands to resolve merge conflicts

Timeline:

• ✅ Merge core watch feature in v0.5.0 Week 2 (post-Rename .ai-team/ to .squad/ with backward-compatible migration #69)
• ✅ Defer blog/docs infrastructure to v0.6.0 or separate PR stream

---

@bradygaster — your call on whether to ask @spboyer to split the PR, or cherry-pick the watch command changes ourselves. Either way, the Ralph watch architecture is solid and should ship.

Keaton (Lead)
Squad v0.5.0 Week 1 Day 2

[diberry]

❌ NEEDS REVISION

Issue: PR #57 bundles TWO separate docs when it should only contain the notification routing guide. The \�uilding-resilient-agents.md\ file belongs in PR #58 (circuit breaker guide).

Notification Routing Doc ✅

• Content: Concise, scannable, follows Brady's directive (no bloat). Excellent use of real-world example.
• Structure: Clear progression (problem → solution → config → examples → reference).
• Style: Sentence-case headings ✅, active voice ✅, uses 'you' ✅
• Nav placement: Correctly positioned after 'Notifications' in Features ✅
• Test: 'notification-routing' correctly added alphabetically ✅
• Links: All references valid ✅
• Frontmatter: Correct ✅

Building Resilient Agents Doc ⚠️

• This file should not be in this PR. It's a separate guide for PR team.md section title incorrect for assigning labels to auto work #58 (circuit breaker docs).
• Remove from this branch; let PR team.md section title incorrect for assigning labels to auto work #58 own it.

Action Required

1. Remove \docs/src/content/docs/guide/building-resilient-agents.md\ from this PR
2. Revert the 'Building Resilient Agents' nav entry (line 34 in navigation.ts)
3. Revert 'building-resilient-agents' from test arrays
4. Keep only the notification routing file and its nav/test entries
5. Let PR team.md section title incorrect for assigning labels to auto work #58 handle the circuit breaker guide