You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Docs: Add decision framework for when to add human members #313
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/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.md docs page
Brief mention added to your-team.md (link to full framework)
Template file includes the framework (if created — see companion issue)
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)