feat: GitHub Issues intake, PRD mode, and human team members

[spboyer]

Summary

Three new capabilities added to the Squad coordinator prompt (squad.agent.md), plus 27 validation tests.

1. 🐙 GitHub Issues Mode

Connect Squad to a GitHub repo's issues and manage the full lifecycle:

• Connect: User says "pull issues from owner/repo" → Squad lists open issues as a backlog table
• Filter: Optional label/milestone filtering
• Route: User picks issues → coordinator routes to agents based on routing.md
• Branch: Agents create squad/{issue-number}-{slug} feature branches
• PR: Agents open PRs with Closes #{issue-number} linking
• Review: User says "there's feedback on PR #X" → coordinator spawns agent to address comments
• Merge: User says "merge PR #X" → gh pr merge --squash --delete-branch, auto-closes linked issue

Issue source is stored in team.md under a new ## Issue Source section.

2. 📄 PRD Mode

Ingest a Product Requirements Document and use it to drive the team's work:

• File path: "read the PRD at docs/prd.md" → reads and processes
• Inline: User pastes spec content directly in chat
• Decomposition: Lead agent (sync) breaks PRD into prioritized work items (WI-1, WI-2, etc.) with size estimates, agent assignments, and dependencies
• Approval gate: Work items presented to user before routing begins
• Mid-project updates: "the PRD changed" → Lead diffs old vs new decomposition, surfaces added/modified/removed items

PRD reference stored in team.md under a new ## PRD section.

3. 👤 Human Team Members

Humans can join the Squad roster alongside AI agents:

• Add: "add Brady as PM" or "I'm on the team as designer"
• Roster: Humans get a 👤 Human badge (vs ✅ Active for AI agents)
• No casting: Humans use their real names — not drawn from fictional universes
• No charter: Humans don't have charter.md or history.md files
• Routing: When work routes to a human, coordinator pauses: "This one's for {Name} — {what's needed}. Let me know when it's done."
• Blocked tracking: Coordinator tracks items waiting on humans, sends stale reminders
• Multiple humans: Fully supported (e.g., Brady as PM, Sarah as Designer)

4. 🔧 Init Mode Updates

Init Mode (step 3) now asks three new questions after "What are you building?":

• "Do you have a PRD or spec document?"
• "Is there a GitHub repo with issues I should pull from?"
• "Are any humans joining the team?"

All are optional/skippable. Post-setup wiring (step 9) automatically runs the relevant intake flows.

5. 🗺️ Routing Table

Three new routing signals added to the Team Mode routing table for issues, PRD, and human member management.

---

Files Changed

File	Change
.github/agents/squad.agent.md	+316 lines — three new sections, Init Mode updates, routing table entries
test/index.test.js	+128 lines — 27 new prompt validation tests

---

How to Test

Automated tests (prompt validation)

# All 55 tests should pass (28 existing + 27 new)
node --test test/*.test.js

The 27 new tests validate that squad.agent.md contains all expected sections, trigger phrases, formats, and routing entries. They catch regressions if sections are accidentally removed during upgrades.

Manual smoke test — GitHub Issues Mode

# 1. Create a test project
mkdir /tmp/squad-issues-test && cd /tmp/squad-issues-test && git init

# 2. Install squad (from this branch)
npx github:spboyer/squad#feature/issues-prd-humans

# 3. Open Copilot, select Squad agent
copilot

# 4. Try these prompts:
#    "I'm building a Node.js API"              → normal init
#    "Pull issues from owner/repo"               → should list open issues
#    "Work on issue #1"                           → should route to agent, create branch, open PR
#    "There's feedback on PR #2"               → should spawn agent for review comments
#    "Merge PR #2"                                → should merge and close linked issue
#    "Show the backlog"                           → should re-list open issues

Manual smoke test — PRD Mode

# In same or new test project with Squad initialized:

# Option A: File path
#    Create a docs/prd.md with requirements, then:
#    "Read the PRD at docs/prd.md"
#    → Lead should decompose into work items table
#    → Should ask for approval before routing

# Option B: Inline
#    Paste requirements text, then say "here's the PRD"
#    → Same decomposition flow

Manual smoke test — Human Team Members

# In a Squad-initialized project:
#    "Add Brady as PM"                            → should add to roster with 👤 badge
#    "Sarah is our designer"                      → should add second human
#    Route work that matches a human's domain   → should pause, not spawn
#    "Brady approved" or "Brady is done"          → should unblock waiting items

Manual smoke test — Init Mode

# Fresh project, run Squad init:
#    After "What are you building?" answer, Squad should ask about:
#    1. PRD or spec document
#    2. GitHub repo with issues
#    3. Human team members
#    Skipping all three should work (backward compatible)

---

Design Decisions

• Agent prompt only — all features live in squad.agent.md. No CLI changes, no new template files. Keeps the tool lightweight.
• gh CLI dependency — GitHub Issues features use gh CLI at runtime. This is already available in Copilot CLI environments.
• Humans are roster-only — they appear in team.md and routing.md but can't be spawned. The coordinator pauses and waits for user relay.
• PRD decomposition is gated — the Lead proposes work items, but the user must approve before agents start. Prevents runaway work from a misunderstood spec.
• Backward compatible — all new Init Mode questions are optional. Existing squads work unchanged.

[bradygaster]

The Squad squad is working atm, but, they've reviewed this PR and are taking it into account in this afternoon's pre-Super Bowl sprint. We should have it in by halftime. I'll text you, @spboyer

[bradygaster]

Hey @spboyer! 🎉 We took your work and integrated it into our wave-2 branch with some review fixes applied (see Proposal 025 for the full review).

What we kept (all of it!):

• GitHub Issues Mode — full lifecycle, branch naming convention, PR review handling
• PRD Mode — Lead decomposition, approval gate, mid-project updates
• Human Team Members — pause-and-present pattern, stale reminders, mixed roster
• All 33 prompt validation tests (adapted)
• Routing table additions

Review fixes we applied:

• Added \gh\ CLI detection (Prerequisites section) before first \gh\ command
• Moved Init Mode questions to step 8 (post-setup) instead of step 3 (pre-casting) to keep init fast
• Added worktree guidance for parallel issue work
• Added ceremony integration note for multi-issue batches
• Referenced standard spawn template (RESPONSE ORDER) in issue spawn prompts
• Added decomposition guidelines (granularity targets, priority scheme, splitting rules)
• Added human block continuation guidance (non-dependent work proceeds)
• Added human reviewer integration with the rejection protocol

Your branch naming convention (\squad/{issue-number}-{slug}) is particularly brilliant — we love it. And the test suite for prompt validation is infrastructure we didn't have before. Strong contribution. 🙏

Closing this PR since the content has been integrated via commit ea7e24f on wave-2 with \Co-authored-by\ credit. It'll flow through our branch strategy: wave-2 → dev → release → main.

[spboyer]

Cool thanks for the note, would be better to get actual commit credit here. Perhaps the squad could figure out a way to ask for changes in the PR in lieu of copying the code submitted? @bradygaster

[bradygaster]

Yes in the future that'll be easier. Velocity got in the way this time. Thanks for the contribution, @spboyer; that was one i just aimed the squad at during development and they brought in as main had moved a lot.