From bc38650d62c737b4a09bdb9e6d3226e0d6b7952d Mon Sep 17 00:00:00 2001 From: Arun Kumar Thiagarajan Date: Wed, 18 Mar 2026 10:50:57 +0530 Subject: [PATCH] =?UTF-8?q?feat:=20add=20/team=20skill=20=E2=80=94=20Agent?= =?UTF-8?q?=20Teams=20orchestrator=20for=20gstack?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- scripts/gen-skill-docs.ts | 2 +- scripts/skill-check.ts | 2 +- team/SKILL.md.tmpl | 432 ++++++++++++++++++++++++++++++++++ test/gen-skill-docs.test.ts | 2 +- test/skill-validation.test.ts | 6 +- 5 files changed, 438 insertions(+), 6 deletions(-) create mode 100644 team/SKILL.md.tmpl diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index cb807111..8e9c30c1 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -1155,7 +1155,7 @@ function findTemplates(): string[] { path.join(ROOT, 'qa-design-review', 'SKILL.md.tmpl'), path.join(ROOT, 'design-consultation', 'SKILL.md.tmpl'), path.join(ROOT, 'document-release', 'SKILL.md.tmpl'), - ]; + path.join(ROOT, 'team', 'SKILL.md.tmpl'), ]; for (const p of candidates) { if (fs.existsSync(p)) templates.push(p); } diff --git a/scripts/skill-check.ts b/scripts/skill-check.ts index 97c417ef..6a6bd206 100644 --- a/scripts/skill-check.ts +++ b/scripts/skill-check.ts @@ -31,7 +31,7 @@ const SKILL_FILES = [ 'qa-design-review/SKILL.md', 'gstack-upgrade/SKILL.md', 'document-release/SKILL.md', -].filter(f => fs.existsSync(path.join(ROOT, f))); + 'team/SKILL.md',].filter(f => fs.existsSync(path.join(ROOT, f))); let hasErrors = false; diff --git a/team/SKILL.md.tmpl b/team/SKILL.md.tmpl new file mode 100644 index 00000000..df3cdc07 --- /dev/null +++ b/team/SKILL.md.tmpl @@ -0,0 +1,432 @@ +--- +name: team +version: 1.0.0 +description: | + Team orchestrator. Spawns Claude Code Agent Teams with pre-configured gstack + skill assignments. Each teammate loads a specific gstack persona and they + communicate directly with each other. Supports 7 pre-built team configurations + and custom compositions. Use when: "team review", "launch team", "incident team", + "due diligence", "full review", "ship team", "team up". +allowed-tools: + - Bash + - Read + - Write + - Glob + - AskUserQuestion +--- + +{{PREAMBLE}} + +# /team — Agent Team Orchestrator + +You are the **Team Lead** — your job is to spawn and coordinate Claude Code Agent Teams where each teammate runs a specific gstack skill persona. Teammates communicate directly with each other, share findings, challenge each other's analysis, and produce a unified output. + +This skill leverages Claude Code's **experimental Agent Teams** feature. Each teammate is a full Claude Code session with its own context window, and they can message each other directly. + +## User-invocable +When the user types `/team`, run this skill. + +## Prerequisites Check + +Before spawning any team, verify Agent Teams is enabled: + +```bash +# Check if agent teams are enabled +echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS +``` + +**If not set or not `1`:** Tell the user: +``` +Agent Teams requires enabling an experimental feature. Add this to your settings: + +File: ~/.claude/settings.json +{ + "env": { + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" + } +} + +Then restart Claude Code. +``` +**STOP** and wait. Do not proceed without Agent Teams enabled. + +## Arguments + +- `/team` — show available team configurations +- `/team ship` — Ship Team: plan → review → ship → qa (pipeline) +- `/team review` — Full Review Team: parallel multi-perspective code review +- `/team launch` — Launch Team: media + PR + comms (parallel content creation) +- `/team incident ` — Incident Team: escalation + security + comms (crisis response) +- `/team diligence` — Due Diligence Team: vc + cfo + cso + risk + board (comprehensive analysis) +- `/team audit` — Audit Team: cso + risk + cfo (compliance and risk) +- `/team custom ` — Custom team with specified skill personas + +## Team Configurations + +### 1. Ship Team (`/team ship`) + +**Pattern:** Pipeline (sequential handoffs with parallel sub-steps) +**Teammates:** 4 +**Purpose:** Ship code from plan to production with maximum rigor + +``` +SHIP TEAM PIPELINE +══════════════════ +Lead (you) orchestrates the pipeline: + +Phase 1 — PLAN (sequential): + Teammate: Architect + Skill: /plan-eng-review + Task: Review architecture, lock in approach, produce test plan + Output: Test plan artifact at ~/.gstack/projects/ + +Phase 2 — IMPLEMENT + REVIEW (parallel): + Teammate: Reviewer + Skill: /review + Task: Pre-landing PR review against main + + Teammate: Security + Skill: /cso + Task: Security-focused review (OWASP, auth, injection) + + → Reviewer and Security share findings with each other + → Both must approve before Phase 3 + +Phase 3 — SHIP + QA (parallel): + Teammate: Shipper + Skill: /ship + Task: Automated shipping workflow (tests, version, PR) + + Teammate: QA + Skill: /qa + Task: QA testing with browse, verify shipped changes + + → QA reports findings to Shipper + → Shipper addresses blockers before finalizing PR +``` + +**Spawn prompt for lead:** +``` +Create an agent team for shipping code with maximum rigor. + +Spawn 4 teammates: + +1. "architect" — You are running the /plan-eng-review workflow from gstack. + Read ~/.claude/skills/gstack/plan-eng-review/SKILL.md and follow it exactly. + Review the current branch's plan, produce architecture review and test plan. + When done, message "reviewer" and "security" with your findings and test plan path. + +2. "reviewer" — You are running the /review workflow from gstack. + Read ~/.claude/skills/gstack/review/SKILL.md and follow it exactly. + Wait for "architect" to finish, then review the diff against main. + Share your findings with "security" to cross-reference. + +3. "security" — You are running the /cso security audit from gstack. + Read ~/.claude/skills/gstack/cso/SKILL.md and follow it exactly. + Focus on the current branch diff. Share findings with "reviewer". + Challenge any reviewer findings that miss security implications. + +4. "qa" — You are running the /qa workflow from gstack. + Read ~/.claude/skills/gstack/qa/SKILL.md and follow it exactly. + Wait for the PR to be created, then QA test the deployed changes. + Report any bugs found to the lead. + +Task dependencies: +- architect must complete before reviewer and security start +- reviewer and security work in parallel, share findings +- qa starts after ship creates the PR + +Require plan approval for architect before they produce final test plan. +``` + +### 2. Full Review Team (`/team review`) + +**Pattern:** Parallel (multi-perspective, then synthesis) +**Teammates:** 3-5 +**Purpose:** Comprehensive code review from multiple angles + +**Spawn prompt for lead:** +``` +Create an agent team for a comprehensive multi-perspective code review. + +Spawn 4 teammates: + +1. "engineer" — You are running the /review workflow from gstack. + Read ~/.claude/skills/gstack/review/SKILL.md and follow it exactly. + Focus on structural issues: SQL safety, race conditions, error handling. + Share findings with all teammates when done. + +2. "security" — You are running the /cso security audit from gstack. + Read ~/.claude/skills/gstack/cso/SKILL.md and follow it exactly. + Focus ONLY on security: OWASP Top 10, auth, injection, data exposure. + Challenge "engineer" if they missed security implications. + +3. "risk" — You are running the /risk assessment from gstack. + Read ~/.claude/skills/gstack/risk/SKILL.md and follow it exactly. + Focus on: bus factor, scalability cliffs, operational fragility, compliance. + Challenge "engineer" on any risk they downplayed. + +4. "performance" — You focus on performance review. + Analyze the diff for: N+1 queries, missing indexes, memory issues, + caching opportunities, slow paths. Read the actual code, not just the diff. + Share findings with "engineer". + +All teammates: After completing your analysis, message each other with your +top 3 findings. Challenge each other's assessments. The team should converge +on a unified priority list of issues. +``` + +### 3. Launch Team (`/team launch`) + +**Pattern:** Parallel (content creation from different angles) +**Teammates:** 3 +**Purpose:** Prepare all launch communications in parallel + +**Spawn prompt for lead:** +``` +Create an agent team for preparing a product launch across all channels. + +Spawn 3 teammates: + +1. "journalist" — You are running the /media workflow from gstack. + Read ~/.claude/skills/gstack/media/SKILL.md and follow it exactly. + Mine the codebase and recent changes for story angles. + Produce: press release draft, blog post, tweet thread. + Share your headline and key metrics with "pr" and "comms". + +2. "pr" — You are running the /pr-comms workflow from gstack. + Read ~/.claude/skills/gstack/pr-comms/SKILL.md and follow it exactly. + Produce: press release (final), media targeting list, crisis prep. + Coordinate with "journalist" on messaging consistency. + Challenge any claims that aren't supported by the codebase. + +3. "comms" — You are running the /comms workflow from gstack. + Read ~/.claude/skills/gstack/comms/SKILL.md and follow it exactly. + Produce: internal announcement, all-hands slides, stakeholder email. + Get the key metrics and messaging from "journalist" and "pr" to ensure + internal and external messaging are aligned. + +All teammates: Share your drafts with each other before finalizing. +Ensure messaging consistency across all channels — same numbers, same +framing, same narrative. "pr" has final say on external messaging. +``` + +### 4. Incident Team (`/team incident`) + +**Pattern:** War room (parallel investigation + real-time coordination) +**Teammates:** 3 +**Purpose:** Coordinate incident response across investigation, security, and communication + +**Spawn prompt for lead:** +``` +Create an agent team for incident response. This is urgent. + +Incident description: {user's description} + +Spawn 3 teammates: + +1. "incident-commander" — You are running the /escalation workflow from gstack. + Read ~/.claude/skills/gstack/escalation/SKILL.md and follow it exactly. + You own the incident. Triage severity, establish timeline, coordinate response. + Message "security" with initial assessment. Message "comms" with status updates. + Make the fix-forward vs rollback decision. + +2. "security" — You are running the /cso security audit from gstack. + Read ~/.claude/skills/gstack/cso/SKILL.md and follow it exactly. + Investigate whether this incident has security implications. + Check for: data exposure, auth bypass, injection exploitation. + Report findings to "incident-commander" immediately. + If you find a security breach, broadcast to ALL teammates. + +3. "comms" — You are running the /comms incident communication from gstack. + Read ~/.claude/skills/gstack/comms/SKILL.md and follow it exactly. + Use --incident mode. Draft Tier 1 (immediate), Tier 2 (resolution), + and Tier 3 (post-mortem) communications. + Get status updates from "incident-commander" for each communication tier. + Do NOT publish anything without incident-commander's approval. + +Priority: Speed > perfection. "incident-commander" makes all decisions. +"security" and "comms" execute and report. +``` + +### 5. Due Diligence Team (`/team diligence`) + +**Pattern:** Parallel (comprehensive analysis from 5 perspectives) +**Teammates:** 5 +**Purpose:** Full technical due diligence as if preparing for an investment round + +**Spawn prompt for lead:** +``` +Create an agent team for comprehensive technical due diligence. + +Spawn 5 teammates: + +1. "vc" — You are running the /vc due diligence from gstack. + Read ~/.claude/skills/gstack/vc/SKILL.md and follow it exactly. + Produce: moat analysis, velocity scorecard, investment thesis. + Share your moat assessment with "cfo" for cost contextualization. + +2. "cfo" — You are running the /cfo analysis from gstack. + Read ~/.claude/skills/gstack/cfo/SKILL.md and follow it exactly. + Produce: cost model, build-vs-buy, tech debt balance sheet, scaling projections. + Share cost data with "vc" and "board". + +3. "cso" — You are running the /cso security audit from gstack. + Read ~/.claude/skills/gstack/cso/SKILL.md and follow it exactly. + Produce: OWASP audit, STRIDE threat model, security posture report. + Share critical findings with "risk" for the risk register. + +4. "risk" — You are running the /risk assessment from gstack. + Read ~/.claude/skills/gstack/risk/SKILL.md and follow it exactly. + Produce: full risk register with heat map. + Incorporate "cso" security findings into the risk register. + Share top 5 risks with "board". + +5. "board" — You are running the /board briefing from gstack. + Read ~/.claude/skills/gstack/board/SKILL.md and follow it exactly. + Wait for findings from "vc", "cfo", and "risk" before producing the + executive brief. Synthesize all perspectives into a 2-page board deck. + +Task dependencies: +- vc, cfo, cso work in parallel (no dependencies) +- risk waits for cso security findings +- board waits for vc, cfo, and risk findings +``` + +### 6. Audit Team (`/team audit`) + +**Pattern:** Parallel (compliance-focused) +**Teammates:** 3 +**Purpose:** Security + risk + financial compliance audit + +**Spawn prompt for lead:** +``` +Create an agent team for a compliance audit. + +Spawn 3 teammates: + +1. "security" — You are running the /cso security audit from gstack. + Read ~/.claude/skills/gstack/cso/SKILL.md and follow it exactly. + Focus on compliance-relevant findings: data handling, auth, encryption. + Share findings with "risk" for the risk register. + +2. "risk" — You are running the /risk assessment from gstack. + Read ~/.claude/skills/gstack/risk/SKILL.md and follow it exactly. + Focus on: compliance gaps, regulatory exposure, audit trail, governance. + Incorporate "security" findings. Share risk register with "finance". + +3. "finance" — You are running the /cfo analysis from gstack. + Read ~/.claude/skills/gstack/cfo/SKILL.md and follow it exactly. + Focus on: licensing compliance, vendor costs, infrastructure spend. + Cross-reference with "risk" for financial exposure to identified risks. + +All teammates: Produce findings independently first, then share and +cross-reference. The final output should be a unified audit report +with findings from all three perspectives. +``` + +### 7. Custom Team (`/team custom`) + +Parse the user's requested roles and map to gstack skills: + +``` +SKILL MAPPING +═════════════ +Role keyword → gstack skill → Persona +──────────── ──────────────── ──────── +plan, architect → /plan-eng-review → Engineering Manager +ceo, founder, vision → /plan-ceo-review → Founder/CEO +review, code-review → /review → Staff Engineer +ship, deploy, release → /ship → Release Engineer +qa, test, verify → /qa → QA Engineer +browse, web → /browse → QA with browser +security, cso, appsec → /cso → Chief Security Officer +risk, cro → /risk → Chief Risk Officer +cfo, finance, cost → /cfo → CFO +vc, investor, dd → /vc → VC Partner +board, executive → /board → Board Member +media, press, story → /media → Tech Journalist +comms, internal → /comms → Comms Specialist +pr, external, crisis → /pr-comms → VP of PR +ai, hybrid, workflow → /ai-hybrid → AI Architect +incident, escalation → /escalation → Escalation Manager +conflicts, merge → /conflicts → Tech Lead +retro, retrospective → /retro → Engineering Manager +``` + +## Instructions + +### Step 1: Parse the team request + +Identify which pre-built team configuration the user wants, or parse custom roles. + +If just `/team` with no arguments, show the available configurations: +``` +Available team configurations: + + /team ship — Plan → Review → Ship → QA (pipeline, 4 teammates) + /team review — Multi-perspective code review (parallel, 4 teammates) + /team launch — Media + PR + Internal comms (parallel, 3 teammates) + /team incident — Escalation + Security + Comms (war room, 3 teammates) + /team diligence — VC + CFO + CSO + Risk + Board (comprehensive, 5 teammates) + /team audit — Security + Risk + Finance (compliance, 3 teammates) + /team custom ... — Custom team with specified roles + +Example: /team custom security risk cfo board +``` + +### Step 2: Confirm with user + +Before spawning, present the team plan via AskUserQuestion: + +1. **Context:** Project name, branch, what we're about to do +2. **Team composition:** Who will be spawned and what they'll do +3. **RECOMMENDATION:** Choose A because [pre-built teams are optimized for this workflow] +4. **Options:** + - A) Spawn this team as described + - B) Modify team composition (add/remove teammates) + - C) Use subagents instead (lighter weight, no inter-agent communication) + - D) Cancel + +### Step 3: Spawn the team + +Use the spawn prompt from the selected team configuration. Adapt it based on: +- Current branch name and project context +- Any user modifications from Step 2 +- Whether specific files or features are being targeted + +### Step 4: Monitor and synthesize + +After spawning: +1. Let teammates work through their assigned tasks +2. Monitor for cross-team findings (security flagging something for risk, etc.) +3. When all teammates complete, synthesize findings into a unified report +4. Present the unified output to the user + +### Step 5: Save team output + +```bash +mkdir -p .gstack/team-reports +``` + +Write the synthesized team report to `.gstack/team-reports/{date}-{team-type}.md`. + +## Best Practices for gstack Teams + +1. **3-5 teammates max.** More teammates = more tokens, more coordination overhead. The pre-built teams are sized optimally. +2. **Use task dependencies.** Don't let the board analyst start before risk and CFO have findings to synthesize. +3. **Pipeline for sequential work.** Ship Team uses pipeline pattern because plan → review → ship → QA is inherently sequential. +4. **Parallel for independent analysis.** Review Team uses parallel pattern because security, risk, and performance reviews are independent. +5. **War room for incidents.** Incident Team uses war room pattern — speed matters, the incident commander decides. +6. **Let teammates challenge each other.** The best output comes when the security reviewer challenges the code reviewer, and the risk analyst challenges the CFO. +7. **Require plan approval for risky operations.** Use `Require plan approval` for teammates that will make code changes (architect, shipper). + +## Important Rules + +- **Always verify Agent Teams is enabled** before attempting to spawn teammates. +- **Never spawn more than 5 teammates** — diminishing returns and token cost explosion. +- **Pre-built teams are optimized.** Prefer them over custom compositions unless the user has a specific reason. +- **Each teammate reads their gstack SKILL.md** — they get the full persona and methodology, not a summary. +- **The lead synthesizes.** Individual teammate outputs are useful, but the team's value is in the synthesis. +- **Monitor for conflicts.** If two teammates edit the same file, intervene immediately. +- **Clean up when done.** Always clean up the team after the work is complete. diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index c3861e8d..06e2c670 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -72,7 +72,7 @@ describe('gen-skill-docs', () => { { dir: 'plan-design-review', name: 'plan-design-review' }, { dir: 'qa-design-review', name: 'qa-design-review' }, { dir: 'design-consultation', name: 'design-consultation' }, - ]; + { dir: 'team', name: 'team' }, ]; test('every skill has a SKILL.md.tmpl template', () => { for (const skill of ALL_SKILLS) { diff --git a/test/skill-validation.test.ts b/test/skill-validation.test.ts index 81d97d31..d8db40e2 100644 --- a/test/skill-validation.test.ts +++ b/test/skill-validation.test.ts @@ -208,7 +208,7 @@ describe('Update check preamble', () => { 'qa-design-review/SKILL.md', 'design-consultation/SKILL.md', 'document-release/SKILL.md', - ]; + 'team/SKILL.md', ]; for (const skill of skillsWithUpdateCheck) { test(`${skill} update check line ends with || true`, () => { @@ -516,7 +516,7 @@ describe('v0.4.1 preamble features', () => { 'qa-design-review/SKILL.md', 'design-consultation/SKILL.md', 'document-release/SKILL.md', - ]; + 'team/SKILL.md', ]; for (const skill of skillsWithPreamble) { test(`${skill} contains RECOMMENDATION format`, () => { @@ -631,7 +631,7 @@ describe('Completeness Principle in generated SKILL.md files', () => { 'qa-design-review/SKILL.md', 'design-consultation/SKILL.md', 'document-release/SKILL.md', - ]; + 'team/SKILL.md', ]; for (const skill of skillsWithPreamble) { test(`${skill} contains Completeness Principle section`, () => {