Tracking: Upstream contribution candidates from claude-teams-bot project

[habassa5]

Status

Tracking candidates for upstream contribution to garrytan/gstack. Do not file upstream yet — batch-evaluate when claude-teams-bot v1 ships, per the project's monthly contribute-back cadence.

Background

These patterns emerged from extensive multi-hour multi-agent work on the claude-teams-bot project (May 2026). Each addresses a real gap or pattern that gstack's existing skills don't cover. Logged here to preserve before claude-teams-bot session compaction.

Source: ~/.gstack/projects/claude-teams-bot/SESSION_STATE.md policy garrytan#23.

High-priority candidates (genuine gap-filling)

• Per-agent git worktrees for Agent Teams. New skill /team-spawn-isolated OR doc improvement to existing agent-teams skill. Codifies the pattern: each teammate gets git worktree add ../<repo>-<agent-name>. Auto-creates worktrees on team spawn. Solves the concurrent-write race conditions we observed (file clobbering, branch flipping mid-session). Empirical evidence: this pattern was the difference between wedged teammates and productive teammates in claude-teams-bot.

• SESSION_STATE.md pattern for multi-agent durability. Extension to existing /context-save to support team state, queued actions, calibration tracking, lessons learned. Current /context-save is single-agent-focused; team-lead sessions have different state needs.

• Wall-clock calibration tracker. New skill /calibrate maintaining a per-project tracker comparing time/cost estimates vs actuals. Tightens estimates over iterations. Empirical: we observed 3-5x over-estimation by default and benefited from explicit tracking.

• Named failure modes catalog for Agent Teams. Doc addition to agent-teams skill troubleshooting. Includes: stale-imperative-crossing-in-flight, message-queue-drain-noise, sonnet-quality-drift, sensitive-data-in-fixtures-via-user-CLAUDE-bleed, dirty-shared-worktree-phantom-typecheck-errors, idle-spam-from-turn-boundaries. Each with symptoms, root cause, fix.

Medium-priority candidates

• Per-phase parallelization heuristic table. Doc addition to /plan-eng-review or new /parallelize skill. The "if N independent units exist with minimal cross-deps, spawn N agents" rule with examples (multi-skill integration, multi-tab UI, multi-profile agents).

• QA-domain hyper-parallelization skill (/qa-parallel). New skill spawning N parallel qa-agents split by test domain (unit/integration/e2e/contract/coverage/codex/security-review). Per the insight that QA work is wall-clock-bound and benefits disproportionately from parallelization.

• Code-time vs runtime data-isolation distinction. Doc addition wherever projects discuss test fixtures, MOCK_MODE, or sensitive data. Subtle but important: codebase artifacts must never bake in business confidential, but runtime can engage with anything users discuss. Many projects conflate.

Why Garry probably hasn't done these himself

• Multi-agent + multi-worktree is a relatively new combination; specific bottlenecks emerge in extended multi-hour multi-agent sessions which may not be his typical pattern.
• Single-developer iteration speed > multi-agent orchestration at his typical scale; he may not need these yet.
• He ships fast and likely prioritizes new features over operational hygiene polish.

Don't contribute back (project-specific)

• ChatGPT Pro tier defaults (subscription-specific)
• Anything Pulse/Salim-personal
• Reject-Sonnet-by-default policy (project-specific quality-bar choice)

Next steps

1. After claude-teams-bot v1 ships and is fully tested, revisit this list
2. For each candidate: decide CONTRIBUTE / DEFER / REJECT
3. For CONTRIBUTE candidates: split into individual issues (file at garrytan/gstack), open PRs from this fork
4. Quality bar: each PR should be polished enough to reflect well on Salim's GitHub profile (better fewer good PRs than many half-baked)

[habassa5]

NEW ROOT-CAUSE-DIAGNOSED CANDIDATE: silent-429-stall recovery in Agent Teams

Confirmed via transcript inspection of qa-engineer-v2 (claude-teams-bot project, 2026-05-03):

The pattern previously named final-step-wedge is actually silent-429-stall — agents silently stall for hours after hitting an Anthropic API HTTP 429 ("Server is temporarily limiting requests · not your usage limit"). The Claude Code agent runtime doesn't retry, doesn't surface the error, doesn't recover.

Evidence:

• qa-engineer-v2 hit a 429 at 19:40:18 UTC (right after last productive commit)
• Sat silent until shutdown at 23:31 UTC (~3h 51m of pure rate-limit-induced silence)
• Session WAS alive (responded to shutdown in <1 sec) — just couldn't make API calls

Proposed fixes (Claude Code infra level, not gstack-specific but worth feature-requesting):

1. Retry-with-backoff on 429 in agent runtime (currently: no retry, just stall)
2. Surface 429 errors to team-lead via SendMessage so team can intervene
3. Configurable resume after timeout — if agent hasn't generated output in N minutes, attempt new prompt

This may belong upstream in Claude Code itself rather than gstack, but worth raising with Anthropic / Garry to discuss. Add to candidates list. May be the highest-impact contribution since this appears to be the actual root cause of the multi-hour QA wedges we've been observing.

[habassa5]

Two more candidates from May 3 evening session

Candidate: pr-reviewer skill (NEW)

Pattern: A gstack skill that wraps Qodo Merge / PR-Agent (OSS, MIT) as the foundation, layered with an LLM Council pattern (Claude + ChatGPT + Grok in parallel) + an anti-rubber-stamp rubric.

Why gstack-worthy: gstack already has the building blocks (/codex, /security-review, /health, /ship) but no integrated approve+merge wrapper that handles three-way outcomes (✅ approve+merge / ⚠️ request-changes / ❌ block) AND enforces anti-rubber-stamp discipline. Most "AI auto-merge" tools are rubber stamps in practice — they run CI and emit ✅. The novel value is the 10-phase rubric + WHY-check + edge-case enumeration + adversarial mindset.

Differentiator over Qodo Merge alone: Qodo Merge is a single-tool reviewer; this skill orchestrates Qodo + LLM Council + adversarial rubric for a multi-perspective evaluation. Tests on real PRs in claude-teams-bot will provide empirical evidence of how this catches what single-tool review misses (Sonnet PR garrytan#56 leaked sensitive data + Opus migrator's first commit had missing JWT auth — both caught only by independent /codex, not by the originating agent's self-check).

Sources to reference: Qodo Merge (https://github.com/qodo-ai/pr-agent), Greptile (closed-source but architectural inspiration), CodeRabbit (large user base reference), our anti-rubber-stamp rubric in CLAUDE.md policy #40a.

---

Candidate: claude-research-mode skill (NEW)

Pattern: TypeScript port of claude.ai Research mode using @anthropic-ai/sdk — orchestrator-worker + parallel synthesizer pattern that mirrors what claude.ai's web UI does, but exposed as a callable primitive any agent can use.

Why gstack-worthy: claude.ai Research mode is a UI feature, NOT API-accessible. Many developers want to programmatically invoke equivalent research depth. langchain-ai/open_deep_research (https://github.com/langchain-ai/open_deep_research, 11.3K ⭐) provides this in Python. There's no equivalent TypeScript-native implementation. A gstack skill that gives any TypeScript-stack project a one-line claudeResearch({ topic }) primitive (with parallel workers + synthesis + citations + cost tracking) fills a real gap.

Differentiator: Built on Anthropic's own documented orchestrator-worker pattern (https://www.anthropic.com/engineering/multi-agent-research-system, 90.2% improvement over single-agent Opus). References open_deep_research's prompt/architecture patterns. TypeScript-native (no Python sidecar). Bakes in Anthropic's documented gotchas (constrain over-spawning, parallelize tools, defend SEO content, primary-source hierarchy, token economics).

Sources to reference: Anthropic engineering blog (multi-agent research system), open_deep_research (canonical OSS reference), Anthropic Cookbook patterns (https://platform.claude.com/cookbook/patterns-agents-basic-workflows).

---

Both candidates emerged from real failure modes in claude-teams-bot work. Neither exists as a packaged skill in the gstack-or-similar ecosystem today. Both should remain candidates only — file upstream after claude-teams-bot v1 ships and patterns are battle-tested.