---
name: repo-to-team
aliases:
  - agentic-team-builder
  - build-team
  - scaffold-team
  - research-team
description: "Dado um repo URL OU tópico de pesquisa, faz pesquisa profunda (codebase + web + Twitter + notas locais), compila conhecimento em wiki persistente, e monta um Agentic Team completo com agents, context docs e workflows."
tools: "Agent,Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch,AskUserQuestion"
---

# Research to Agentic Team — Deep Research & Knowledge Compilation

Transforma qualquer **repositório** ou **tópico de pesquisa** em um **Agentic Team** completo. Não é scaffolding mecânico — é pesquisa profunda multi-fonte seguida de compilação de conhecimento em wiki persistente.

**Core idea:** em vez de re-descobrir o domínio do zero a cada pergunta, o LLM **compila e mantém uma wiki persistente** — context docs interligados que acumulam conhecimento. Os agentes operam sobre essa base compilada.

```
Raw Sources                 →  Context Docs (wiki compilada)  →  Agents que operam sobre a wiki
 ├─ github (gh-axi)                   ↑                                    ↑
 ├─ web (docs, tutorials)     compilado uma vez,              definidos por papel,
 ├─ twitter (discussões)      mantido atualizado              não por código
 └─ notas locais
```

## Trigger

Use quando:
- O usuário fornece um **repo URL** e pede pra construir um time / especializar
- O usuário fornece um **tópico** e pede time / pesquisa profunda
- O usuário diz "repo to team", "build team for X", "quero um time pra esse repo/tema"
- O usuário quer transformar expertise de domínio em agentes especializados

## Inputs

- **Source** (obrigatório) — um de:
  - **Repo URL**: `https://github.com/org/repo`
  - **Tópico**: domínio/tecnologia/conceito (ex: "WebRTC", "indoor vertical farming", "Stripe billing")
  - **Misto**: repo URL + tópico mais amplo
- **Team name** (opcional) — default: `{Source Name} Agentic Team`
- **Focus area** (opcional) — aspecto específico
- **Existing knowledge** (opcional) — notas locais que o usuário já tem

Se a fonte estiver pouco clara, perguntar:

```
O que você quer que o time domine?
Pode ser:
- Um repo GitHub (ex: https://github.com/org/repo)
- Um tópico (ex: "WebRTC", "Stripe billing")
- Um repo + contexto mais amplo
```

## Pré-requisitos

- `gh-axi` ou `gh` CLI autenticado — pesquisa GitHub remota sem clonar
- Ferramenta de browsing (ex: `chrome-devtools-axi`) — para docs/tutorials
- `twitter` CLI (opcional, ex: `uv tool install twitter-cli`) — community sentiment
- Ferramenta de busca semântica nas notas locais (opcional, ex: `qmd`)

Se alguma faltar, a skill degrada graciosamente — flag o gap e prossegue com o que tiver.

---

## Workflow

### Phase 0 — Intake & Validation

**Classificar o input:**

| Tipo | Fontes primárias | Fontes secundárias |
|---|---|---|
| Repo URL | gh-axi (repo, issues, PRs) | web, twitter, notas locais |
| Tópico | web (docs, tutoriais, papers), twitter | notas locais, gh-axi search por repos relacionados |
| Repo + Tópico | gh-axi + web | twitter, notas, repos adjacentes |

**Para repos:**
1. Parsear URL — extrair `owner/repo`
2. Validar e pegar overview: `gh-axi repo view owner/repo`
3. **NÃO clonar.** Usar `gh-axi` pra navegar remotamente (código, issues, PRs, releases).
4. Só clonar se o usuário pedir explicitamente ("clona esse repo", "quero ter local").

**Para tópicos:**
1. Buscar repos relevantes: `gh-axi search repos "{topic}" --sort stars`
2. Identificar os top 2-3 repos do espaço

**Sempre:**
3. Checar se time agêntico já existe localmente
4. Se já existe, perguntar: "Já existe um time pra esse domínio. Quer atualizar ou criar do zero?"

**Output ao usuário:**

```
Fonte: {repo URL | topic | both}
Tipo: {repo | topic | mixed}
Linguagem/Stack: {if repo}
Já existe localmente: {sim/não}

Vou fazer pesquisa profunda. Fontes:
- [x] GitHub (gh-axi — remoto, sem clonar)   ← se repo
- [x] Web (docs oficiais, tutoriais)          ← sempre
- [x] Twitter (discussões, experts)           ← sempre
- [x] Notas locais                            ← sempre

Quer focar em algo específico ou pesquiso o domínio inteiro?
```

Use AskUserQuestion para confirmar escopo.

### Phase 1 — Deep Research (Multi-Source)

Spawnar **agentes de pesquisa em paralelo** — cada um especializado em um tipo de fonte. Todos rodam concorrentemente.

#### Agent A — GitHub Research (se repo, ou se tópico tem repos chave)

Spawn Agent (model: opus):

```
Pesquisa o repositório {owner}/{repo} via gh-axi (sem clonar).

Comandos disponíveis:

  gh-axi repo view {owner}/{repo}                # overview, descrição, stats
  gh-axi search code "keyword" -R {owner}/{repo} # buscar código
  gh-axi search code "import" -R {owner}/{repo} --ext go  # filtrar por extensão
  gh-axi issue list -R {owner}/{repo}            # issues abertas
  gh-axi issue list -R {owner}/{repo} --label bug
  gh-axi pr list -R {owner}/{repo}               # PRs abertos
  gh-axi release list -R {owner}/{repo}          # releases
  gh-axi api repos/{owner}/{repo}/contents       # listar arquivos
  gh-axi api repos/{owner}/{repo}/contents/{path}
  gh-axi api repos/{owner}/{repo}/readme

Para ler arquivos específicos remotamente:
  WebFetch https://raw.githubusercontent.com/{owner}/{repo}/main/{path}
  OU
  gh-axi api repos/{owner}/{repo}/contents/{path} | jq -r .content | base64 -d

Estratégia:
1. Overview: gh-axi repo view
2. README
3. Estrutura de diretórios
4. Arquivos-chave: CLAUDE.md, AGENTS.md, docs/, configs
5. 5-10 arquivos-fonte centrais pra entender arquitetura
6. Issues por dor: --label bug
7. PRs por trabalho ativo
8. Releases por maturidade

Reportar:
1. ARQUITETURA — estrutura, stack, build, padrões
2. DOMÍNIO — problema resolvido, conceitos-chave, vocabulário
3. WORKFLOWS — dev setup, fluxos de usuário, fluxos operacionais
4. KNOWLEDGE MAP — diretórios de lógica, configs, docs, integrações
5. NATURAL AGENT BOUNDARIES — papéis distintos, fronteiras de expertise

Específicos, não generalidades.
```

Se o usuário pedir clone: `gh repo clone {owner}/{repo} ~/repos/{repo-name}` — agentes posteriores leem arquivos locais.

#### Agent B — Web Research

Spawn Agent (model: sonnet):

```
Pesquisa "{topic/repo-name}" na web pra construir expertise de domínio.
Use WebSearch + ferramenta de browsing (ex: chrome-devtools-axi).

Estratégia:
1. WebSearch: "{topic} documentation", "{topic} tutorial", "{topic} architecture"
2. Browse top 3-5 páginas mais relevantes:
   - Docs oficiais
   - Architecture guides
   - Getting started
   - API reference
3. WebSearch: "{topic} best practices", "{topic} common pitfalls", "{topic} vs alternatives"
4. Browse 2-3 páginas comparativas/opinativas

Pra cada fonte, extrair:
- Conceitos-chave e como se relacionam
- Decisões arquiteturais e tradeoffs
- Padrões e anti-padrões comuns
- Ferramentas e ecossistema
- Consenso da comunidade em best practices

Reportar:
- CONCEITOS: vocabulário do domínio com definições
- ARQUITETURA: como o sistema funciona, decisões-chave
- ECOSSISTEMA: ferramentas relacionadas, alternativas, integrações
- BEST PRACTICES: o que experts recomendam
- ARMADILHAS: erros comuns e como evitar
- FONTES: URLs de tudo que leu (pra citação)

Não clicar à toa. Mirar páginas específicas dos resultados de busca.
```

#### Agent C — Twitter/Community Research

Spawn Agent (model: sonnet):

```
Pesquise o que estão dizendo sobre "{topic/repo-name}" no Twitter/X.

Use o twitter CLI:

1. Discussões:
   twitter search "{topic}" -t Latest --max 30 --yaml
   twitter search "{topic}" --filter --max 20 --yaml

2. Se repo, busque o nome:
   twitter search "{org}/{repo}" --max 20 --yaml
   twitter search "from:{org-twitter-handle}" --max 20 --yaml

3. Experts/thought leaders:
   twitter search "{topic} thread" --filter --max 15 --yaml

4. Dores e use cases:
   twitter search "{topic} problem OR issue OR bug" --max 15 --yaml
   twitter search "{topic} love OR amazing OR game-changer" --max 15 --yaml

Reportar:
- KEY VOICES: quem fala desse tópico, quem são os experts
- SENTIMENT: o que a comunidade pensa (positivo, negativo, nuançado)
- USE CASES: como pessoas estão usando de fato
- DORES: reclamações comuns
- TRENDS: o que tá mudando, o que é novo
- THREADS NOTÁVEIS: links pra discussões de alto sinal

Use --yaml pra output agent-friendly. Use --filter pra relevance scoring.
Sinal, não ruído — pular tweets promocionais e bots.

Se twitter CLI falhar ou retornar nada, reportar e seguir — não bloquear.
```

#### Agent D — Local Notes Research

Spawn Agent (model: sonnet):

```
Buscar nas notas locais do usuário conhecimento existente sobre "{topic/repo-name}".

1. Busca semântica (se disponível):
   qmd query "{topic}"
   qmd query "{related-term-1}"
   qmd query "{related-term-2}"

2. Busca por arquivo:
   Glob: *{topic}*, *{related-term}*
   Grep: "{topic}" em arquivos .md

3. Times agênticos relacionados:
   Ler READMEs de quaisquer times que tenham overlap

4. Clippings/recortes:
   Glob por arquivos com o tema

Reportar:
- NOTAS EXISTENTES: lista relevante com paths e resumos de 1 linha
- TIMES RELACIONADOS: agentic teams que tocam nesse domínio
- KNOWLEDGE GAPS: o que falta nas notas que vamos precisar construir
- CONEXÕES: como esse novo time deve se ligar a conteúdo existente
```

**Após todos os agentes retornarem:** sintetizar achados num brief unificado. Identificar:
- Onde fontes concordam (alta confiança)
- Onde fontes discordam (precisa input do usuário)
- O que está faltando (gaps a sinalizar)

### Phase 2 — Team Design (Validação com Usuário)

Apresentar a estrutura proposta baseada em TODA a pesquisa:

```
## Proposta de Time: {Name} Agentic Team

### Missão
{1-2 frases}

### Tese Central
{O insight não-óbvio — a ideia chave do domínio que vai guiar decisões}

### Fontes Pesquisadas
- Codebase: {sim/não, summary}
- Web: {N páginas, fontes-chave}
- Twitter: {N tweets, sentiment}
- Notas locais: {N notas relacionadas}

### Agentes Propostos

| Agent | Model | Papel | Delega para |
|-------|-------|-------|-------------|
| @{name}-master | opus | Coordinator — {routing} | todos |
| @{name}-{role1} | sonnet | {responsabilidade} | — |
| @{name}-{role2} | sonnet | {responsabilidade} | — |
| @{name}-{role3} | sonnet | {responsabilidade} | — |

### Workflows Propostos
1. **{workflow-1}** — {quando usar, o que faz}
2. **{workflow-2}** — {quando usar, o que faz}
3. **{workflow-3}** — {quando usar, o que faz}

### Context Docs Propostos
- `architecture.md` — design do sistema, abstrações
- `domain-glossary.md` — conceitos-chave e relações
- `tools-stack.md` — CLIs, APIs, configuração
- `current-state.md` — estado atual, WIP, issues
- `{domain-specific}.md` — {se necessário}

---

Quer ajustar antes de eu montar?
```

Use AskUserQuestion. Iterar até o usuário aprovar.

### Phase 3 — Knowledge Compilation

Compilar a pesquisa raw em context docs persistentes e interligados.

Spawnar **agentes de compilação em paralelo** (model: sonnet), um por context doc.

**Cada context doc deve:**
- Ter frontmatter consistente (type: resource, tags incluindo agentic-team + domínio)
- Ser auto-contido — um agente lendo SÓ esse arquivo consegue agir nele
- Incluir fatos específicos: paths exatos, comandos reais, nomes verdadeiros
- Incluir `last-compiled: YYYY-MM-DD` no frontmatter pra detecção de staleness
- Citar fontes onde aplicável (path no repo, URL, tweet)

**Context docs padrão:**

#### `architecture.md`
- Design do sistema (árvore com anotações)
- Entry points (o que roda quando você faz X?)
- Abstrações-chave (3-5 conceitos pra entender o sistema)
- Fluxo de dados (como informação se move)
- Pontos de extensão (onde adicionar funcionalidade)
- Fontes: análise do repo + docs oficiais

#### `domain-glossary.md`
- Cada termo do domínio com definição
- Relações entre conceitos
- Desambiguações
- Exemplos pra conceitos abstratos
- Fontes: todos os agentes de pesquisa

#### `tools-stack.md`
- Comandos CLI com sintaxe exata
- API endpoints com exemplos
- Arquivos de configuração e formato
- Variáveis de ambiente
- Passos de dev setup
- Fontes: repo + web

#### `current-state.md`
- O que tá pronto e funcionando
- O que é WIP ou instável
- Issues conhecidas / tech debt
- Sentimento da comunidade (do Twitter)
- Perguntas em aberto
- Fontes: issues do repo + twitter + web

Docs adicionais conforme necessário (ex: `auth-and-access.md`, `api-reference.md`, `ecosystem.md`).

### Phase 4 — Agent Assembly

Pra cada agente aprovado na Phase 2:

```markdown
---
name: {agent-name}
description: {1 linha de papel}
tools: {lista separada por vírgula}
model: {opus|sonnet}
---

# {Título completo}

{2-3 frases. Escrito como prompt "Você é..."}

## Context Loading — MANDATORY

Antes de QUALQUER tarefa, ler TODOS estes arquivos:

- `<team-dir>/context/{file1}.md`
- ...

## {Seções específicas do papel}

{Conhecimento de domínio, decision flows, routing tables}

## Boundaries — Não negociáveis

{5-10 regras duras}

## Reporting Format

{Template de output}
```

**Atribuição de modelo:**
- **Opus**: Coordinator/architect (max 1 por time)
- **Sonnet**: Specialist/executor (2-4 por time)

### Phase 5 — Workflow Assembly

Pra cada workflow aprovado na Phase 2:

```markdown
---
name: {workflow-name}
description: {quando/por quê}
type: workflow
tags: [{domain-tags}]
---

# {Título}

## Quando usar
{Condições}

## Pré-requisitos
- [ ] {checklist}

## Passos
### 1. {Passo}
{Instruções detalhadas}

## Nunca fazer
- {anti-pattern}
```

### Phase 6 — README & CLAUDE-SPECIALIST

#### README do time

```markdown
---
aliases:
  - {team-slug}
tags:
  - agentic-team
  - {domain-tags}
---

# {Team Name} Agentic Team

{Missão — 2-3 frases}

## Contexto
{Tabela de context files com referências}

## A tese
{Insight central não-óbvio sobre esse domínio}

## Agentes
{Pra cada: descrição, arquivo, invocação, model, outputs, ferramentas}

## Workflows
{Pra cada: referência + 1 linha de descrição}

## Regras Gerais
{7-10 regras não-negociáveis}

## Quando NÃO usar este time
{Boundaries — o que outros times tratam}
```

#### CLAUDE-SPECIALIST.md

Prompt portátil pra colar no `CLAUDE.md` de qualquer projeto:

```markdown
---
aliases:
  - {team}-claude-specialist
type: guide
source: internal synthesis
tags:
  - resource
  - {domain}
  - prompt
  - specialist
---

# CLAUDE.md — {Domain} Specialist

> Cole este conteúdo no CLAUDE.md de qualquer projeto {domain}.

{Condensado: stack, regras, APIs principais, arquitetura, formato de resposta}
```

### Phase 7 — Integração

1. **Verificar referências internas**: cada arquivo tem ≥1 referência de entrada e saída
2. **Verificar frontmatter**: consistência
3. **Verificar kebab-case**: todos os filenames
4. **Atualizar índices**: adicionar a MOC ou índice de recursos relevante
5. **Registrar agentes**: se aplicável, em `.claude/settings.json` (subagent_type)
6. **Reindexar busca semântica**: se aplicável

**Final report:**

```
## Time Montado: {Team Name} Agentic Team

### Localização
{path do diretório}

### Fontes usadas
- GitHub: {owner/repo via gh-axi, ou N/A}
- Web: {N fontes, top 3 URLs}
- Twitter: {N tweets, sentiment}
- Notas locais: {N notas linkadas}

### Arquivos criados
- README: {path}
- CLAUDE-SPECIALIST: {path}
- Agents: {lista}
- Context: {lista}
- Workflows: {lista}

### Próximos passos
1. Revisar os context docs — você conhece o domínio melhor que eu
2. Testar: @{master-name} com uma tarefa real
3. Ajustar boundaries conforme uso

### Para usar num repo
Cole o conteúdo de `{TEAM}-CLAUDE-SPECIALIST.md` no CLAUDE.md do projeto.
```

---

## Reference de Ferramentas

### gh-axi (GitHub research — PRIMARY pra repos)

```bash
gh-axi                                              # dashboard
gh-axi repo view {owner}/{repo}                     # overview
gh-axi search repos "{topic}" --sort stars          # achar repos por tópico
gh-axi search code "keyword" -R {owner}/{repo}      # buscar código
gh-axi search code "func main" -R {owner}/{repo} --ext go
gh-axi issue list -R {owner}/{repo}                 # issues
gh-axi issue list -R {owner}/{repo} --label bug
gh-axi issue view {number} -R {owner}/{repo}
gh-axi pr list -R {owner}/{repo}
gh-axi pr view {number} -R {owner}/{repo}
gh-axi release list -R {owner}/{repo}
gh-axi api repos/{owner}/{repo}/contents
gh-axi api repos/{owner}/{repo}/contents/{path}
```

Ler arquivos específicos remotamente:

```bash
# Via raw URL (melhor pra arquivos completos):
WebFetch https://raw.githubusercontent.com/{owner}/{repo}/main/{path}

# Via API + base64:
gh-axi api repos/{owner}/{repo}/contents/{path} | jq -r .content | base64 -d
```

Use pra: estrutura do repo, código-fonte, issues, PRs, releases, saúde do projeto.
**Nunca clonar a menos que o usuário peça.** gh-axi faz tudo remotamente.

> **Nota:** se você não tiver `gh-axi`, o `gh` CLI oficial faz a maioria dessas operações com sintaxe parecida.

### Browsing (web)

Exemplo com `chrome-devtools-axi`:

```bash
chrome-devtools-axi open <url>          # navegar
chrome-devtools-axi snapshot            # ler página (UIDs)
chrome-devtools-axi snapshot --full     # página completa
chrome-devtools-axi click @uid=N        # clicar elemento
chrome-devtools-axi scroll down
```

Use pra: documentação oficial, tutoriais, architecture guides, blog posts, comparativos.
Padrão: `WebSearch` pra achar URLs → ferramenta de browsing pra ler conteúdo.

### twitter CLI (community research)

```bash
twitter search "topic" -t Latest --max 30 --yaml    # busca recente
twitter search "topic" --filter --max 20 --yaml      # com scoring
twitter search "topic" --from user --max 15 --yaml
twitter user-posts username --max 20 --yaml
twitter tweet <url>
```

Use pra: sentimento da comunidade, opiniões de experts, casos reais, dores, tendências.
Sempre `--yaml` pra output agent-friendly e `--max` pra evitar bans.

### Busca semântica em notas locais

Exemplo com `qmd`:

```bash
qmd query "topic"
```

Use pra: conhecimento existente, notas relacionadas, evitar duplicação.

---

## Rules

- **Pesquisa antes de scaffolding** — Phase 1 tem que ser profunda. Arquivos vazios são inúteis.
- **Multi-source sempre** — mesmo pra repo, checar web + twitter + notas. Contexto é tudo.
- **Usuário valida o design** — nunca pular Phase 2. O usuário conhece o domínio melhor.
- **Context docs > agent prompts** — invista mais em context/ que em arquivos de agent. Bom contexto faz agentes simples efetivos.
- **Compile uma vez, mantenha incrementalmente** — context docs ficam de pé sozinhos.
- **Específicos > generalidades** — paths exatos, comandos reais, nomes verdadeiros.
- **Cite fontes** — context docs devem traçar de onde o conhecimento veio.
- **Remote-first** — use gh-axi pra navegar repos remotamente. Só clona se o usuário pedir. Nunca clona dentro de pasta de notas.
- **Um opus máximo** — coordinator é opus, specialists são sonnet.
- **Mostrar antes de escrever** — apresentar estrutura antes de criar arquivos.
- **Frontmatter sempre** — todo arquivo tem frontmatter.
- **Sem órfãos** — todo arquivo tem entrada e saída de referências.
- **Degradação graciosa** — se twitter falhar ou web não retornar nada, prosseguir. Sinalize gaps.

## Anti-patterns

- **Scaffolding vazio** — arquivos com headings mas sem conteúdo. 2 docs ricos > 6 vazios.
- **Copy-paste** — context docs são síntese compilada, não dump raw de qualquer fonte.
- **Clonar por padrão** — gh-axi lê tudo remotamente. Clonar desperdiça disco e tempo a menos que o usuário precise de dev local.
- **Agentes genéricos** — "@code-reviewer" é inútil. "@migration-safety-checker" é útil.
- **Context monolito** — um arquivo de 500 linhas derrota o propósito. Quebrar por preocupação.
- **Workflows prematuros** — não invente workflows pra hipotéticos. Comece com 2-3 reais.
- **Research rabbit holes** — limitar browsing web a 5-7 páginas. Limitar twitter a 50 tweets. Retornos decrescentes.
- **Ignorar conhecimento local** — sempre checar busca semântica antes. Pode já existir o que você precisa.