PRD: Monorepo subfolder support — full story #974

Problem Statement

When users run squad init from a subfolder of a monorepo, the old behavior ran git init — creating a broken nested .git/ directory inside the subfolder. This corrupted the parent repo's view of the subfolder and caused cascading problems with workflows, upgrades, and agent resolution.

PR #944 fixes the init path (phase 1), but the full monorepo story has gaps:

• Upgrade doesn't know about monorepo layouts — it re-stamps files at CWD instead of git root
• Workflows conflict when multiple squads coexist in one repo
• Shared agent file works today but has limitations if squads need different coordinator policies
• Migration path is manual for users who already hit the bug

Related: #939 (original bug report), #944 (phase 1 fix)

Platform Constraint

Copilot custom agents (.github/agents/*.md) only resolve from the git root. This is a Copilot platform constraint — Squad cannot change it.

Implications:

This is actually a clean design — the coordinator is a router, and .squad/ is the state store. The constraint becomes a feature.

Phase 1 — Bug Fix ✅

Status: Done — PR #944

What shipped

• squad init no longer runs git init in subfolders
• Agent file (.github/agents/squad.agent.md) placed at git root, not CWD
• .squad/ directory placed in the subfolder (CWD)
• Workflows skipped in monorepo mode (with console warning explaining why)
• CWD-first .squad/ resolution baked into the coordinator template

Validation

• 20 unit tests passing
• 7 E2E scenarios validated:
  1. Standalone repo (baseline, no regression)
  2. Monorepo subfolder — first squad
  3. Monorepo subfolder — second squad alongside first
  4. No-git directory (error path)
  5. Git root init (same as standalone)
  6. Re-init in same subfolder (idempotent)
  7. Agent file content verification (CWD resolution present)

Phase 2 — Upgrade Awareness

Status: Not started

Problem

squad upgrade currently assumes CWD == git root. In a monorepo, it re-stamps the agent file at the wrong location and doesn't detect pre-fix damage (nested .git/ directories).

Requirements

Acceptance criteria

• squad upgrade from a monorepo subfolder updates agent file at git root
• squad upgrade from a monorepo subfolder updates .squad/ in CWD
• Warning emitted when nested .git/ detected
• squad migrate-monorepo moves agent file, removes nested .git/, preserves .squad/
• Existing standalone upgrade behavior is unchanged (no regression)

Phase 3 — Multi-Squad Workflows

Status: Not started — needs design spike

Problem

GitHub Actions only reads workflow files from <repo-root>/.github/workflows/. When multiple squads coexist in one monorepo, they can't each have independent heartbeat/triage workflows without conflicts.

Options to evaluate

Additional considerations

• Squad labels: Need namespacing? E.g., squad:alpha:member vs squad:beta:member — or do squad labels already scope by repo convention?
• Workflow skip in phase 1: Currently squad init skips workflows entirely in monorepo mode and prints a warning. Phase 3 should remove this limitation.
• Cron schedule: Should all squads share one heartbeat cadence, or can they differ?

Acceptance criteria

• Design doc produced (pick one option or hybrid)
• squad init in monorepo generates appropriate workflow(s)
• Multiple squads in one repo can run independent heartbeats without conflict
• Labels are properly namespaced (if needed)

Phase 4 — Per-Squad Coordinator Customization (If Needed)

Status: Future — may not be needed

Problem

Today one shared squad.agent.md means the coordinator behavior is identical for all squads. This works when squads only differ in team state (roster, decisions, history). It breaks if squads need:

• Different casting policies (e.g., alpha uses strict casting, beta uses relaxed)
• Different ceremony configs (e.g., alpha has weekly retros, beta doesn't)
• Different routing rules or tool restrictions

Possible solution

A squad.config.json (or similar) in each subfolder's .squad/ directory with coordinator overrides:

{
  "casting": { "policy": "strict", "maxRetries": 2 },
  "ceremonies": { "retro": "weekly", "standup": "daily" },
  "routing": { "securityIssues": "worf", "docs": "seven" }
}

The coordinator template would read this config from CWD and adjust behavior accordingly.

Non-goal

Per-squad agent files (e.g., squad-alpha.agent.md) — blocked by Copilot platform constraint. Agent files resolve from .github/agents/ by name, not by CWD.

Non-Goals

Migration Path

For users who already ran squad init in a monorepo subfolder before the fix in PR #944:

Manual steps (available now)

# 1. Navigate to the subfolder where squad was incorrectly initialized
cd my-monorepo/team-alpha

# 2. Remove the broken nested .git/
rm -rf .git

# 3. Move the agent file to git root
mkdir -p ../..github/agents
mv .github/agents/squad.agent.md ../../.github/agents/squad.agent.md
rm -rf .github  # if empty after move

# 4. Keep .squad/ in place — it's already correct
ls .squad/  # roster.md, decisions.md, etc. should be here

# 5. Verify
git status  # should show changes at repo root, not nested repo

Automated (phase 2)

cd my-monorepo/team-alpha
squad upgrade  # or: squad migrate-monorepo

Testing Strategy

Links

• squad init: Squad init should not run git init in a sub-folder of a repository (or ever) #939 — Original bug report (monorepo subfolder creates nested .git/)
• fix: monorepo subfolder support — never run git init (#939) #944 — Phase 1 implementation (init fix)
• Platform docs — Copilot custom agents resolve from .github/agents/ at git root only