Repository navigation
Closed
Description
Problem
The docs explain what human members are and how they work (pausing, routing, stale reminders), but they don't answer the key question new users ask:
When should I add someone as a human member vs. just @mention them on PRs?
This came up during onboarding — the distinction between a casual contributor and a roster-listed human isn't documented anywhere.
What's missing
Decision framework (the litmus test)
- Add to roster when the person is a decision gate — someone the team should actively route to, wait on, and track (e.g.,
Brady needs to approve architecture decisions before we build) - Don't add when the person is a collaborator you interact with through normal GitHub flows — commenting on PRs, reviewing code, filing issues
Specific gaps across docs
| Question | Current coverage |
|---|---|
| When should I add a human vs. @mention them? | Not addressed |
| Casual contributors vs. roster members? | Not addressed |
| What if I have 20 people — do all go on roster? | Not addressed |
| Solo project — should I roster myself? | Not addressed |
Where this guidance should live
.squad/templates/human-members.md— the authoritative template (see companion issue for creating this file)docs/src/content/docs/features/human-team-members.md— user-facing docs pagedocs/src/content/docs/concepts/your-team.md— team composition overview
Proposed decision framework
Add a section like:
When to add a human member
| Scenario | Add to roster? | Why |
|---|---|---|
| Approves architecture decisions before implementation | ✅ Yes | Decision gate — team should route and wait |
| Reviews all docs PRs as a standing reviewer | ✅ Yes | Recurring review gate |
| Occasionally reviews PRs when tagged | ❌ No | Use @mention on the PR |
| Files issues and contributes code | ❌ No | Normal GitHub collaboration |
| Makes final ship/no-ship call | ✅ Yes | Approval gate |
The litmus test: If you want agents to stop and wait for someone's input before proceeding on a specific type of work, add them. If they review asynchronously via GitHub, don't bother.
Acceptance criteria
- Decision framework added to
human-team-members.mddocs page - Brief mention added to
your-team.md(link to full framework) - Template file includes the framework (if created — see companion issue)
Metadata
Metadata
Assignees
Labels
No labels
Activity
diberry commentedon Mar 9, 2026
cc @bradygaster — decision framework for when to add humans. Companion to #312. Both need
squad:paolabeling for the docs agent.docs: add decision framework for when to add human members
docs(squad): log PR github#131 issue creation
feat: remote squad mode + doctor command + docs cleanup
docs: add decision framework for when to add human members (github#317)