From be1e7d948714e0bcf5c75b7f1a4fca7e0e82e5db Mon Sep 17 00:00:00 2001 From: Dina Berry Date: Mon, 9 Mar 2026 09:05:56 -0700 Subject: [PATCH] docs: add decision framework for when to add human members Adds a 'When to add a human member' section to the human team members feature page with a decision table, litmus test, and note about automatic identification via git config. Also adds a cross-reference link from the your-team concept page to the new decision framework section. Closes #313 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/concepts/your-team.md | 2 ++ .../docs/features/human-team-members.md | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/src/content/docs/concepts/your-team.md b/docs/src/content/docs/concepts/your-team.md index 6811cd886..63d0d18ad 100644 --- a/docs/src/content/docs/concepts/your-team.md +++ b/docs/src/content/docs/concepts/your-team.md @@ -97,6 +97,8 @@ Sarah appears on the roster with a 👤 Human badge. When work routes to a human, Squad **pauses** and tells you someone needs to act. You relay the task outside of Squad, then report back what happened. Stale reminders keep things moving. +Not sure whether someone should be a roster member or just a normal GitHub collaborator? See [When to add a human member](../features/human-team-members.md#when-to-add-a-human-member) for a decision framework. + --- ## Work Routing diff --git a/docs/src/content/docs/features/human-team-members.md b/docs/src/content/docs/features/human-team-members.md index ed2de7616..e6ce15798 100644 --- a/docs/src/content/docs/features/human-team-members.md +++ b/docs/src/content/docs/features/human-team-members.md @@ -77,6 +77,24 @@ Their entry moves to `.squad/agents/_alumni/`. They can be re-added later. --- +## When to add a human member + +Not every collaborator needs a roster entry. Use this table to decide: + +| Scenario | Add to roster? | Why | +|----------|---------------|-----| +| Approves architecture decisions before implementation | ✅ Yes | Decision gate — agents route and wait | +| Reviews all docs PRs as a standing reviewer | ✅ Yes | Recurring review gate | +| Makes the final ship/no-ship call | ✅ Yes | Approval gate | +| Occasionally reviews PRs when tagged | ❌ No | Use @mention on the PR instead | +| Files issues and contributes code | ❌ No | Normal GitHub collaboration | + +**Litmus test:** If you want agents to *stop and wait* for someone's input before proceeding, add them. If they review asynchronously through normal GitHub flows, a roster entry adds no value. + +**You don't need to add yourself.** Squad reads `git config user.name` every session, so the team always knows who's driving. Adding yourself to the roster is optional — it formalizes routing and review tracking but isn't required for day-to-day interaction. + +--- + ## Tips - Use human members for approval gates — design review, compliance, final sign-off.