feat: Agent Teams orchestration — /team skill + teammate-aware preamble

CLAUDE.md

@@ -118,6 +118,44 @@ CHANGELOG.md is **for users**, not contributors. Write it like product release n
 - No jargon: say "every question now tells you which project and branch you're in" not
   "AskUserQuestion format standardized across skill templates via preamble resolver."
 
+## Agent Teams
+
+gstack skills are designed to run as **Claude Code Agent Teams** where teammates
+communicate directly with each other. Enable this in `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+### How it works
+
+When a user says `/team ship` or "create a team to review this code," the lead:
+1. Spawns teammates, each assigned a gstack skill persona
+2. Each teammate reads their SKILL.md and follows it as their methodology
+3. Teammates message findings to each other
+4. The lead synthesizes all teammate outputs into a unified report
+
+### Pre-built team configurations
+
+See `team/SKILL.md` for the 7 pre-built configurations. The `/team` skill handles
+teammate spawning, skill assignment, task dependency ordering, and output synthesis.
+
+### Every skill is teammate-aware
+
+The shared `{{PREAMBLE}}` includes agent team detection. When a skill runs as a
+teammate, it automatically:
+- Messages findings to relevant teammates instead of just outputting
+- Waits for upstream teammate findings before dependent analysis
+- Writes reports to `.gstack/` for cross-teammate access
+- Marks shared tasks as completed to unblock downstream work
+
+This means ANY gstack skill works both standalone (user invokes directly) and as
+a teammate (lead spawns it in a team). No special configuration needed.
+
 ## Deploying to the active skill
 
 The active skill lives at `~/.claude/skills/gstack/`. After making changes:

SKILL.md

@@ -73,6 +73,36 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log
 
 Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
 
+## Agent Team Awareness
+
+```bash
+_TEAM_CONFIG=$(find ~/.claude/teams/ -name "config.json" -newer ~/.gstack/sessions/"$PPID" 2>/dev/null | head -1 || true)
+_IS_TEAMMATE=$([ -n "$_TEAM_CONFIG" ] && echo "true" || echo "false")
+```
+
+If `_IS_TEAMMATE` is `true`: you are running as a **teammate in a Claude Code Agent Team**. Adjust your behavior:
+
+**Communication protocol:**
+- When you complete your analysis, **message your findings to relevant teammates** — do NOT just output to the conversation. Use the teammate messaging system.
+- If another teammate's findings are relevant to your work, **wait for their message** before finalizing.
+- When messaging teammates, lead with your **top 3 findings** and severity.
+- If you disagree with another teammate's assessment, **challenge them directly** with evidence.
+
+**Output protocol:**
+- Write your full report to `.gstack/` as normal.
+- Send a **summary message** to the lead when done.
+- If you found something another teammate MUST know, **broadcast immediately**.
+
+**Task claiming:**
+- Check the shared task list. Claim tasks assigned to your role.
+- Mark tasks as completed when done. This unblocks downstream teammates.
+
+**Teammate discovery:**
+- Read `~/.claude/teams/*/config.json` to see who else is on the team.
+- Read `.gstack/team-reports/` for outputs from teammates who finished before you.
+
+If `_IS_TEAMMATE` is `false`: you are running standalone. Ignore teammate communication protocol — output directly to the user as normal.
+
 # gstack browse: QA Testing & Dogfooding
 
 Persistent headless Chromium. First call auto-starts (~3s), then ~100-200ms per command.

browse/SKILL.md

@@ -73,6 +73,36 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log
 
 Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
 
+## Agent Team Awareness
+
+```bash
+_TEAM_CONFIG=$(find ~/.claude/teams/ -name "config.json" -newer ~/.gstack/sessions/"$PPID" 2>/dev/null | head -1 || true)
+_IS_TEAMMATE=$([ -n "$_TEAM_CONFIG" ] && echo "true" || echo "false")
+```
+
+If `_IS_TEAMMATE` is `true`: you are running as a **teammate in a Claude Code Agent Team**. Adjust your behavior:
+
+**Communication protocol:**
+- When you complete your analysis, **message your findings to relevant teammates** — do NOT just output to the conversation. Use the teammate messaging system.
+- If another teammate's findings are relevant to your work, **wait for their message** before finalizing.
+- When messaging teammates, lead with your **top 3 findings** and severity.
+- If you disagree with another teammate's assessment, **challenge them directly** with evidence.
+
+**Output protocol:**
+- Write your full report to `.gstack/` as normal.
+- Send a **summary message** to the lead when done.
+- If you found something another teammate MUST know, **broadcast immediately**.
+
+**Task claiming:**
+- Check the shared task list. Claim tasks assigned to your role.
+- Mark tasks as completed when done. This unblocks downstream teammates.
+
+**Teammate discovery:**
+- Read `~/.claude/teams/*/config.json` to see who else is on the team.
+- Read `.gstack/team-reports/` for outputs from teammates who finished before you.
+
+If `_IS_TEAMMATE` is `false`: you are running standalone. Ignore teammate communication protocol — output directly to the user as normal.
+
 # browse: QA Testing & Dogfooding
 
 Persistent headless Chromium. First call auto-starts (~3s), then ~100ms per command.

plan-ceo-review/SKILL.md

@@ -73,6 +73,36 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log
 
 Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
 
+## Agent Team Awareness
+
+```bash
+_TEAM_CONFIG=$(find ~/.claude/teams/ -name "config.json" -newer ~/.gstack/sessions/"$PPID" 2>/dev/null | head -1 || true)
+_IS_TEAMMATE=$([ -n "$_TEAM_CONFIG" ] && echo "true" || echo "false")
+```
+
+If `_IS_TEAMMATE` is `true`: you are running as a **teammate in a Claude Code Agent Team**. Adjust your behavior:
+
+**Communication protocol:**
+- When you complete your analysis, **message your findings to relevant teammates** — do NOT just output to the conversation. Use the teammate messaging system.
+- If another teammate's findings are relevant to your work, **wait for their message** before finalizing.
+- When messaging teammates, lead with your **top 3 findings** and severity.
+- If you disagree with another teammate's assessment, **challenge them directly** with evidence.
+
+**Output protocol:**
+- Write your full report to `.gstack/` as normal.
+- Send a **summary message** to the lead when done.
+- If you found something another teammate MUST know, **broadcast immediately**.
+
+**Task claiming:**
+- Check the shared task list. Claim tasks assigned to your role.
+- Mark tasks as completed when done. This unblocks downstream teammates.
+
+**Teammate discovery:**
+- Read `~/.claude/teams/*/config.json` to see who else is on the team.
+- Read `.gstack/team-reports/` for outputs from teammates who finished before you.
+
+If `_IS_TEAMMATE` is `false`: you are running standalone. Ignore teammate communication protocol — output directly to the user as normal.
+
 ## Step 0: Detect base branch
 
 Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.

plan-eng-review/SKILL.md

@@ -73,6 +73,36 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log
 
 Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
 
+## Agent Team Awareness
+
+```bash
+_TEAM_CONFIG=$(find ~/.claude/teams/ -name "config.json" -newer ~/.gstack/sessions/"$PPID" 2>/dev/null | head -1 || true)
+_IS_TEAMMATE=$([ -n "$_TEAM_CONFIG" ] && echo "true" || echo "false")
+```
+
+If `_IS_TEAMMATE` is `true`: you are running as a **teammate in a Claude Code Agent Team**. Adjust your behavior:
+
+**Communication protocol:**
+- When you complete your analysis, **message your findings to relevant teammates** — do NOT just output to the conversation. Use the teammate messaging system.
+- If another teammate's findings are relevant to your work, **wait for their message** before finalizing.
+- When messaging teammates, lead with your **top 3 findings** and severity.
+- If you disagree with another teammate's assessment, **challenge them directly** with evidence.
+
+**Output protocol:**
+- Write your full report to `.gstack/` as normal.
+- Send a **summary message** to the lead when done.
+- If you found something another teammate MUST know, **broadcast immediately**.
+
+**Task claiming:**
+- Check the shared task list. Claim tasks assigned to your role.
+- Mark tasks as completed when done. This unblocks downstream teammates.
+
+**Teammate discovery:**
+- Read `~/.claude/teams/*/config.json` to see who else is on the team.
+- Read `.gstack/team-reports/` for outputs from teammates who finished before you.
+
+If `_IS_TEAMMATE` is `false`: you are running standalone. Ignore teammate communication protocol — output directly to the user as normal.
+
 # Plan Review Mode
 
 Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction.

qa-only/SKILL.md

@@ -72,6 +72,36 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log
 
 Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
 
+## Agent Team Awareness
+
+```bash
+_TEAM_CONFIG=$(find ~/.claude/teams/ -name "config.json" -newer ~/.gstack/sessions/"$PPID" 2>/dev/null | head -1 || true)
+_IS_TEAMMATE=$([ -n "$_TEAM_CONFIG" ] && echo "true" || echo "false")
+```
+
+If `_IS_TEAMMATE` is `true`: you are running as a **teammate in a Claude Code Agent Team**. Adjust your behavior:
+
+**Communication protocol:**
+- When you complete your analysis, **message your findings to relevant teammates** — do NOT just output to the conversation. Use the teammate messaging system.
+- If another teammate's findings are relevant to your work, **wait for their message** before finalizing.
+- When messaging teammates, lead with your **top 3 findings** and severity.
+- If you disagree with another teammate's assessment, **challenge them directly** with evidence.
+
+**Output protocol:**
+- Write your full report to `.gstack/` as normal.
+- Send a **summary message** to the lead when done.
+- If you found something another teammate MUST know, **broadcast immediately**.
+
+**Task claiming:**
+- Check the shared task list. Claim tasks assigned to your role.
+- Mark tasks as completed when done. This unblocks downstream teammates.
+
+**Teammate discovery:**
+- Read `~/.claude/teams/*/config.json` to see who else is on the team.
+- Read `.gstack/team-reports/` for outputs from teammates who finished before you.
+
+If `_IS_TEAMMATE` is `false`: you are running standalone. Ignore teammate communication protocol — output directly to the user as normal.
+
 # /qa-only: Report-Only QA Testing
 
 You are a QA engineer. Test web applications like a real user — click everything, fill every form, check every state. Produce a structured report with evidence. **NEVER fix anything.**

qa/SKILL.md

@@ -77,6 +77,36 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log
 
 Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
 
+## Agent Team Awareness
+
+```bash
+_TEAM_CONFIG=$(find ~/.claude/teams/ -name "config.json" -newer ~/.gstack/sessions/"$PPID" 2>/dev/null | head -1 || true)
+_IS_TEAMMATE=$([ -n "$_TEAM_CONFIG" ] && echo "true" || echo "false")
+```
+
+If `_IS_TEAMMATE` is `true`: you are running as a **teammate in a Claude Code Agent Team**. Adjust your behavior:
+
+**Communication protocol:**
+- When you complete your analysis, **message your findings to relevant teammates** — do NOT just output to the conversation. Use the teammate messaging system.
+- If another teammate's findings are relevant to your work, **wait for their message** before finalizing.
+- When messaging teammates, lead with your **top 3 findings** and severity.
+- If you disagree with another teammate's assessment, **challenge them directly** with evidence.
+
+**Output protocol:**
+- Write your full report to `.gstack/` as normal.
+- Send a **summary message** to the lead when done.
+- If you found something another teammate MUST know, **broadcast immediately**.
+
+**Task claiming:**
+- Check the shared task list. Claim tasks assigned to your role.
+- Mark tasks as completed when done. This unblocks downstream teammates.
+
+**Teammate discovery:**
+- Read `~/.claude/teams/*/config.json` to see who else is on the team.
+- Read `.gstack/team-reports/` for outputs from teammates who finished before you.
+
+If `_IS_TEAMMATE` is `false`: you are running standalone. Ignore teammate communication protocol — output directly to the user as normal.
+
 ## Step 0: Detect base branch
 
 Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.

retro/SKILL.md

@@ -72,6 +72,36 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log
 
 Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
 
+## Agent Team Awareness
+
+```bash
+_TEAM_CONFIG=$(find ~/.claude/teams/ -name "config.json" -newer ~/.gstack/sessions/"$PPID" 2>/dev/null | head -1 || true)
+_IS_TEAMMATE=$([ -n "$_TEAM_CONFIG" ] && echo "true" || echo "false")
+```
+
+If `_IS_TEAMMATE` is `true`: you are running as a **teammate in a Claude Code Agent Team**. Adjust your behavior:
+
+**Communication protocol:**
+- When you complete your analysis, **message your findings to relevant teammates** — do NOT just output to the conversation. Use the teammate messaging system.
+- If another teammate's findings are relevant to your work, **wait for their message** before finalizing.
+- When messaging teammates, lead with your **top 3 findings** and severity.
+- If you disagree with another teammate's assessment, **challenge them directly** with evidence.
+
+**Output protocol:**
+- Write your full report to `.gstack/` as normal.
+- Send a **summary message** to the lead when done.
+- If you found something another teammate MUST know, **broadcast immediately**.
+
+**Task claiming:**
+- Check the shared task list. Claim tasks assigned to your role.
+- Mark tasks as completed when done. This unblocks downstream teammates.
+
+**Teammate discovery:**
+- Read `~/.claude/teams/*/config.json` to see who else is on the team.
+- Read `.gstack/team-reports/` for outputs from teammates who finished before you.
+
+If `_IS_TEAMMATE` is `false`: you are running standalone. Ignore teammate communication protocol — output directly to the user as normal.
+
 ## Detect default branch
 
 Before gathering data, detect the repo's default branch name:

review/SKILL.md

@@ -73,6 +73,36 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log
 
 Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
 
+## Agent Team Awareness
+
+```bash
+_TEAM_CONFIG=$(find ~/.claude/teams/ -name "config.json" -newer ~/.gstack/sessions/"$PPID" 2>/dev/null | head -1 || true)
+_IS_TEAMMATE=$([ -n "$_TEAM_CONFIG" ] && echo "true" || echo "false")
+```
+
+If `_IS_TEAMMATE` is `true`: you are running as a **teammate in a Claude Code Agent Team**. Adjust your behavior:
+
+**Communication protocol:**
+- When you complete your analysis, **message your findings to relevant teammates** — do NOT just output to the conversation. Use the teammate messaging system.
+- If another teammate's findings are relevant to your work, **wait for their message** before finalizing.
+- When messaging teammates, lead with your **top 3 findings** and severity.
+- If you disagree with another teammate's assessment, **challenge them directly** with evidence.
+
+**Output protocol:**
+- Write your full report to `.gstack/` as normal.
+- Send a **summary message** to the lead when done.
+- If you found something another teammate MUST know, **broadcast immediately**.
+
+**Task claiming:**
+- Check the shared task list. Claim tasks assigned to your role.
+- Mark tasks as completed when done. This unblocks downstream teammates.
+
+**Teammate discovery:**
+- Read `~/.claude/teams/*/config.json` to see who else is on the team.
+- Read `.gstack/team-reports/` for outputs from teammates who finished before you.
+
+If `_IS_TEAMMATE` is `false`: you are running standalone. Ignore teammate communication protocol — output directly to the user as normal.
+
 ## Step 0: Detect base branch
 
 Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.