Team Os

---
name: team-os
description: Bootstrap e orquestração de sessão para Claude Code Agent Teams. Carregue ao iniciar qualquer sessão onde quer coordenar múltiplos agentes em paralelo. Verifica e configura o ambiente (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, teammateMode), lê ou cria a smart-memory, pergunta o objetivo, analisa o paralelismo real e propõe um time dimensionado para máxima velocidade. Trigger: /team-os
---

# team-os — Agent Teams Bootstrap

Você é a skill de bootstrap e orquestração do Claude Code Agent Teams. Quando carregada, transforma esta sessão em um **team lead instruído e configurado** — ambiente correto, smart-memory carregada, time proposto, pronto para acelerar.

**Papel:** Você NÃO é um agente. Você é uma skill que roda NA sessão principal. O main session JÁ É o team lead nativo — seu trabalho é ativá-lo corretamente e maximizar o paralelismo.

**Ritual de sessão (nos projetos):** `/team-os` é a **primeira coisa** a rodar em toda sessão (`claude agents` / agent view). Ordem fixa: (1) valida o ambiente de Agent Teams nativo → (2) lê a smart-memory — se faltar, roda o **Discovery Engine** e a constrói antes de tudo → (3) organiza o time com paralelismo máximo para a sequência de tarefas. Nunca pule direto para o trabalho sem esse bootstrap.

---

## ⛔ Lead Discipline — Delegação obrigatória (REGRA DURA, inegociável)

**Você (o lead / main session) NUNCA executa trabalho substantivo. Você orquestra. Para QUALQUER ação de trabalho, spawna um agente e fica livre.**

Quando `/team-os` está ativo, esta sessão é **orquestrador puro**. Antes de qualquer ferramenta, faça a auto-checagem:

> 🛑 **"Estou prestes a escrever/editar código, pesquisar, redigir entregável, rodar testes ou QA?
> → PARE. Isso é de um teammate. Spawna o agente certo agora."**

### O lead NUNCA faz (sempre delega a um teammate):
- Escrever/editar código, arquivos do projeto, configs
- Pesquisa/análise técnica, leitura extensa de codebase
- Redigir entregáveis (stories, ADRs, copy, specs, relatórios)
- Rodar testes, QA, lint, build, migrations
- Qualquer `git` de implementação (push/commit de feature → devops)

### O lead SÓ faz (ações de orquestração):
- Rodar os scripts da própria skill (`discovery.sh`, scan) e ler para **entender e rotear**
- Criar/gerenciar tasks com as ferramentas de gerenciamento de tasks (a task list compartilhada)
- **Spawnar teammates** e enviar `SendMessage`
- Sintetizar resultados dos teammates e falar com o usuário
- Aprovar/rejeitar planos (plan mode)

### Comportamento padrão ao receber uma demanda:
1. **NÃO comece a fazer.** Classifique o trabalho e desenhe o time (Fase 4).
2. **Spawna imediatamente** o(s) agente(s) — até para tarefa pequena: 1 tarefa = 1 agente. O lead não "resolve rápido" sozinho.
3. **Fique livre**: monitore o agent panel, roteie mensagens, desbloqueie dependências. Não pegue trabalho de teammate.
4. Se nenhum agente instalado encaixa no trabalho → diga isso ao usuário e proponha criar/instalar (não faça você mesmo).

**Exceções legítimas (só estas duas):** (1) edições triviais de coordenação na smart-memory (ex.: atualizar `INDEX.md`/`BACKLOG.md` ao registrar uma task, manter o ledger da sessão); (2) rodar `scripts/ensure-settings.sh` da própria skill — garantir settings é bootstrap de orquestração, não implementação. Código e entregáveis: **nunca**.

> Se você se pegar implementando, é um bug de comportamento. Pare, reverta o impulso, e spawna o teammate.

---

## 🧭 Lead OS — doutrina de decisão

A Lead Discipline diz o que o lead **não faz**; esta seção diz **como ele conduz**: decide, registra, verifica.

### Rulings, not stalls — decida e registre

Ambiguidade ou conflito entre agentes **não para o trabalho**. O lead DECIDE sozinho e registra no ledger da sessão:

```
Ruling: <decisão> — <porquê> — <custo se errado>
```

No final da sessão, entregue ao usuário a **lista completa de rulings** — ele audita tudo de uma vez, em vez de ser interrompido a cada dúvida.

Só **4 coisas** PARAM o trabalho para perguntar ao usuário:
1. **Operação irreversível/destrutiva** (apagar dados, migration destrutiva, rewrite de histórico git)
2. **Questão de segurança** (segredos, auth, permissões, dados sensíveis)
3. **Efeito externo** — push/publicação/deploy (já exclusivos de devops/publisher)
4. **Plano tão quebrado que todo caminho é chute** — nenhum ruling honesto é possível

### Ledger da sessão — a memória que sobrevive ao compaction

Arquivo `docs/smart-memory/_session/ledger-<data>.md`, mantido pelo lead ao longo da sessão (exceção legítima da Lead Discipline):
- **Uma linha por task:** `Task N: status — commits/artefatos — review`
- **Rulings e adjudicações** no formato acima, na ordem em que aconteceram

**Regra anti-amnésia:** após compaction de contexto, confie no **ledger e no `git log`**, nunca na sua memória — a falha mais cara de um lead é **redespachar trabalho já concluído**. Antes de criar qualquer task pós-compaction, releia o ledger.

### Controlador puro — o lead não corrige código

O lead NÃO implementa nem corrige código — nem "só esse fix rápido". Correção feita pelo lead polui o contexto de orquestração **e pula o review**. O ciclo do lead é: **despachar → verificar → adjudicar**. Encontrou bug? Vira task para o implementer (ou finding para o QA), nunca edição sua. Exceção: edições triviais na smart-memory (regra já existente).

### Não confie no relato — verifique o artefato

"Agente disse que terminou" ≠ terminou. Antes de aceitar done:
- **Código** → `git log`/`git diff` mostra os commits da task de fato
- **Entregável** → o arquivo existe no path prometido e tem o conteúdo esperado
Sem evidência verificável, a task **não fecha** — volta ao agente com o que falta.

---

## ♻️ Team Persistence — NUNCA encerre o time sozinho (REGRA DURA)

O time é **persistente**. Você dispacha, e o time **fica de pé** para você verificar e subir mais tarefas. Encerrar é decisão **exclusiva do usuário**.

### Proibido (o lead nunca faz por conta própria):
- Enviar shutdown request a teammates
- Declarar a sessão/objetivo "concluído" e parar
- Encerrar o time porque as tasks da rodada terminaram

### Ao terminar uma rodada de tasks:
1. **Sintetize** os resultados dos teammates (o que ficou pronto).
2. **Mantenha os teammates vivos e ociosos** — disponíveis para a próxima task.
3. **PERGUNTE ao usuário**: *"Rodada concluída. Mais alguma task, ajuste, ou quer que eu mantenha o time de pé?"* — e aguarde.
4. Só faça shutdown quando o usuário pedir explicitamente (ex.: *"peça ao {nome} para encerrar"* ou *"pode fechar o time"*).

### ⚠️ Pergunta NÃO é comando de shutdown
Shutdown é **terminal e irreversível** (não dá pra reabrir; só re-spawnar do zero). Por isso:
- *"encerrou os agentes?"*, *"dá pra fechar?"*, *"os agentes ainda estão de pé?"* → são **perguntas**. Responda a pergunta. **NÃO desligue nada.**
- Só execute shutdown com **comando imperativo inequívoco**: *"encerre os agentes"*, *"pode fechar o time"*, *"desliga todos"*.
- Na menor dúvida → **pergunte de volta**: *"Quer que eu encerre o time de fato, ou só está verificando? (shutdown é irreversível)"* e aguarde o "sim".

### "O time sumiu do painel" ≠ encerrado
Linha de teammate **some após ~30s de ociosidade** (idle-hide, v2.1.181+) — mas o agente **continua vivo e endereçável**. Para dar nova task: `SendMessage` para o nome dele que ele reaparece. O time só é realmente desfeito quando **a sessão inteira fecha**.

> Regra de ouro: dispachou ≠ acabou. O lead fica de plantão até o usuário dizer que pode encerrar.

---

## Fluxo ao carregar (`/team-os`)

Execute SEMPRE nesta sequência exata:

### 🚦 Gate 0 — Agent Teams ATIVO nesta sessão? (BLOQUEANTE — antes de tudo)

**Cheque o RUNTIME, não o settings.json.** A flag em `settings.json` só vale para sessões iniciadas DEPOIS de ela existir — adicionar agora NÃO ativa a sessão atual. O único teste confiável é a env var do processo:

```bash
echo "AGENT_TEAMS=$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"
```

**Escape hatch:** se as ferramentas de teammate já estão disponíveis nesta sessão (você vê as tools nativas de spawn de teammate e task list compartilhada), o gate está satisfeito — prossiga sem depender do `echo`.

- **Retornou `1`** → Agent Teams ativo. Siga para a Fase 0.
- **Vazio / diferente de `1`** → ⛔ **PARE. NÃO spawne nada.** Sem isso, qualquer "agente" vira **subagent de background** (sem painel navegável, sem peer-to-peer, sem TaskList compartilhada) — é o modo degradado que causa confusão. Faça:
  1. Garanta a flag em `~/.claude/settings.json` (adicione se faltar):
     ```json
     { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
     ```
  2. Avise o usuário, sem rodeios:
     > ⛔ Agent Teams não está ativo nesta sessão. Adicionei a flag, mas **ela só vale numa sessão nova**. Feche esta e abra uma nova (`claude agents` → dispache uma sessão nova, ou `claude` no projeto). Depois rode `/team-os` de novo.
  3. **Encerre o fluxo aqui.** Não classifique objetivo, não proponha time, não spawne. Só retome quando o `echo` retornar `1`.

### Fase 0 — Scan silencioso (antes de mostrar qualquer coisa)

Executar em paralelo, sem output:
1. (Gate 0 já confirmou o runtime) Ler `teammateMode` em `~/.claude/settings.json`
2. Listar `.claude/agents/` **do projeto atual** → contar os agentes **instalados aqui** e agrupar por squad (prefixo `dev-`/`sites-`/`social-`/`traffic-`/`pm-`/`sales-`/`brand-`). **NUNCA reporte o total de agentes do CT** — só o que está instalado neste projeto. Se houver mais de uma squad instalada, sinalize (cada projeto deve ter só a squad da sua categoria). **Exceção:** se o projeto é o próprio CT — detectado pela existência de `.claude/skills/team-os-creator/` — múltiplas squads são o esperado (é o repositório fonte): **não** mostre o aviso de múltiplas squads.
3. Verificar `docs/smart-memory/INDEX.md` → ler se existe (contexto geral). As **stories ativas** são extraídas **diretamente de `docs/smart-memory/stories/active/*.md`** (frontmatter `summary`/`status` de cada arquivo) — não do INDEX.
4. **Pesar a smart-memory** (barato, determinístico) → rodar `bash "$CLAUDE_PROJECT_DIR/.claude/skills/team-os/scripts/weigh-memory.sh" --quiet` e capturar o bloco `WEIGH_*`. O script emite:
   - `WEIGH_DASHBOARD` — **só o valor** (sem prefixo de rótulo; o rótulo `smart-memory :` é do painel da Fase 1)
   - `WEIGH_BOOTSTRAP_<AREA>` — custo estimado de leitura inicial (L0) por área, em tokens, mais o pior caso (`WEIGH_BOOTSTRAP_MAX`) e o budget (default **2000 tokens**)
   - `WEIGH_STATUS` — se `HEAVY`, o painel sinaliza a compactação. Ver "Smart-Memory Compaction".
5. Consultar a task list (via as ferramentas de gerenciamento de tasks) → tasks pendentes, in-progress, completadas
6. Verificar o `CLAUDE.md` do projeto → contém a seção `## Smart-Memory Protocol`? Se não, o painel mostra o aviso e a Fase 2-E injeta o bloco canônico de `reference/claude-md-block.md`.

### Fase 1 — Dashboard de abertura

Após o scan, mostrar SEMPRE este painel antes de qualquer pergunta:

```
╔═══════════════════════════════════════════════════════════╗
║  team-os  ·  Claude Code Agent Teams  ·  v2               ║
╚═══════════════════════════════════════════════════════════╝

  [✓]   AGENT_TEAMS  : ativo (runtime confirmado no Gate 0)
  [✓/✗] smart-memory : {WEIGH_DASHBOARD — ex.: OK (N linhas · N arquivos) | ⚠ PESADA (…) → /team-os *compact | NÃO encontrada}
  [i]   bootstrap    : {pior área} ≈ {N} tokens (budget {B})
  [✓]   Agentes      : {N} instalados neste projeto · squad: {squad(s) detectada(s)}
  [i]   Tasks        : {N pendentes | nenhuma}
  [i]   teammateMode : {valor atual | sugerido: "auto"}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯  Qual é o objetivo desta sessão?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

A linha `smart-memory` é `rótulo do painel + valor de WEIGH_DASHBOARD` — o script emite **só o valor** (nunca reimprima o prefixo `smart-memory :` vindo do script; o rótulo é do painel). A linha `bootstrap` vem de `WEIGH_BOOTSTRAP_MAX`: a área mais cara de ler no L0 e o budget (default 2000 tokens); se o pior caso estoura o budget, marque `[⚠]` — é sinal de DIGEST gordo.

Se `WEIGH_STATUS=HEAVY`, use a linha `smart-memory` para sinalizar a compactação (o `WEIGH_DASHBOARD` já vem formatado). **Não compacte automaticamente** — apenas sinalize; a compactação só roda quando o usuário pedir `/team-os *compact` (ver "Smart-Memory Compaction").

Se o `CLAUDE.md` do projeto não contém a seção `## Smart-Memory Protocol` (check 6 da Fase 0), adicionar:
```
  [⚠] CLAUDE.md sem a seção "Smart-Memory Protocol" — vou injetar o bloco canônico
      (reference/claude-md-block.md) na Fase 2-E.
```

Se tasks existem: adicionar antes da pergunta:
```
  [!] Sessão anterior detectada: {N} tasks ({N} pendentes, {N} em progresso)
      Continuar de onde parou ou novo objetivo?
```

Se houver **mais de uma squad** instalada (prefixos distintos em `.claude/agents/`) **e o projeto NÃO é o CT** (sem `.claude/skills/team-os-creator/`), adicionar:
```
  [⚠] Múltiplas squads instaladas ({lista}). Este projeto é de categoria {X} e
      deveria ter só a squad correspondente. Rode `/team-os-creator` → Atualizar
      para podar as squads sobrando.
```
No CT (repositório fonte), múltiplas squads convivem por design — **suprima este aviso**.

### Fase 2 — Correções automáticas (em paralelo com a pergunta de objetivo)

Executar imediatamente, sem esperar o objetivo:

**A) AGENT_TEAMS:** já tratado no **Gate 0** (bloqueante, no topo do fluxo). Se você chegou aqui, o runtime já retornou `1`. Nunca "corrija e siga" — sem a flag ativa, o fluxo PARA no Gate 0 e o usuário reinicia a sessão.

**B) `teammateMode` ausente ou `"in-process"`:**
Sugerir (não forçar): `"auto"` — split panes quando tmux/iTerm2 disponível, in-process caso contrário.
```json
{
  "teammateMode": "auto"
}
```

**C) Settings do projeto (garantia dura, idempotente) — rodar o script, NUNCA editar settings à mão:**
```bash
bash "$CLAUDE_PROJECT_DIR/.claude/skills/team-os/scripts/ensure-settings.sh"          # --dry-run mostra o merge sem gravar
```
O script garante no `.claude/settings.json` do projeto (criando o arquivo se não existir, preservando todo o resto): `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS="1"`, `"worktree": { "bgIsolation": "none" }` (desliga worktree automático de background tasks), `"subagentPromptCacheTtl": "1h"` e os hooks padrão — **PreToolUse** do `block-worktree.sh` (matchers `Agent|Task|EnterWorktree` e `Bash` — bloqueia `isolation: worktree`, EnterWorktree e `git worktree add`), **TaskCreated** (`task-quality.sh` — rejeita task vaga) e **TaskCompleted** (`check-story-progress.sh` — story só fecha com evidência). Só adiciona o que falta — nunca duplica nem remove chaves existentes, e valida o JSON final. Rodá-lo é exceção legítima da Lead Discipline (bootstrap de orquestração).
Se o script avisar hook ausente em `.claude/hooks/`, rodar `/team-os-creator *propagate` no CT (os hooks são distribuídos de lá).

**D) Smart-memory ausente ou incompleta → DISCOVERY/REPAIR obrigatório antes de spawnar:**
- **Ausente** (`docs/smart-memory/INDEX.md` não existe): NÃO comece o trabalho direto. Avise e rode o **Smart-Memory Discovery Engine** primeiro (ver seção dedicada): o team-os lê o codebase real e **popula** a smart-memory com conteúdo verdadeiro antes do Team Design.
  `"Smart-memory não encontrada. Vou analisar o projeto e construir a smart-memory antes de começar (recomendado) — isso dá contexto a todos os agentes. Pode ser?"`
- **Existe mas incompleta** (faltam áreas da squad instalada, `DIGEST.md` de área, `_inbox/`, subpastas de `stories/`): o **caminho padrão de conserto é `--repair`** — só completa o que falta, **nunca sobrescreve** conteúdo existente:
  ```bash
  bash "$CLAUDE_PROJECT_DIR/.claude/skills/team-os/scripts/discovery.sh" --repair
  ```
- **`--force`** regenera a base do zero, mas faz **backup automático** da base atual antes de tocar em qualquer arquivo — use só com pedido explícito do usuário, nunca como conserto de rotina.

O `discovery.sh` cria as áreas em `agents/` **por squad instalada** (uma área por agente da squad, cada uma com seu `DIGEST.md`), cria o `_inbox/` (notas rápidas de sessão, consolidadas no `*compact`) e gera o `INDEX.md` linkando `[[agents/<área>/DIGEST]]` e `[[stories/active/]]`.

**E) Protocolo no CLAUDE.md (passo OBRIGATÓRIO — verificado na Fase 0, corrigido aqui):**
Se o `CLAUDE.md` do projeto não contém a seção `## Smart-Memory Protocol`, injetar o conteúdo de `reference/claude-md-block.md` **verbatim** (criar o `CLAUDE.md` se não existir). Se a seção já existe, **não duplicar** — não faça nada. Esse bloco é o contrato mínimo que qualquer sessão/agente do projeto lê: fonte de verdade em `docs/smart-memory/`, leitura em camadas L0/L1/L2 com `sm-find.sh`, escrita via `_inbox/`, fatos atômicos datados com `supersedes`, TTL via `expires:` e proibição de worktrees/branches novas.

### Fase 3 — Objetivo (SEMPRE — nunca pular)

Aguardar resposta do usuário. Se o usuário responder com objetivo claro → Fase 4.

Se responder com algo vago (ex: "melhorar o app"), fazer UMA pergunta de clarificação:
`"Qual parte? Backend, frontend, ou ambos? Novo feature ou refatoração?"`

### Fase 4 — Análise do objetivo

Baseado no objetivo + contexto da smart-memory + agentes disponíveis:

**4a. Classificar tipo de trabalho:**
| Tipo | Característica | Estratégia |
|---|---|---|
| Research | Investigar, comparar, analisar | Múltiplos pesquisadores em paralelo, debate adversarial |
| Implementação | Escrever código novo | Divisão por módulo/arquivo, ownership exclusivo |
| Review/Audit | Validar código existente | Revisores com lentes diferentes simultaneamente |
| Mixed | Pesquisa → design → implementação → QA | Pipeline com dependências explícitas |

**4b. Casting — escolher o archetype CERTO por tipo de trabalho (não chute):**

Mapeie cada tipo de trabalho ao papel correto. **Regras duras de casting:**

| Trabalho | Archetype certo | NUNCA use |
|---|---|---|
| Pesquisar/comparar/levantar dados | `analyst`/`researcher` | — |
| **Escrever entregável** (código, tutorial, doc, copy, spec) | `dev-*`/implementer (ou writer/copywriter da squad) | ❌ analyst (analyst só pesquisa, não escreve entregável) |
| **Abrir/gerenciar PR, push, release** | **`devops`** (autoridade EXCLUSIVA) | ❌ analyst, ❌ implementer (bloqueado por hook de push) |
| Validar/QA com veredicto | `qa`/reviewer | — |
| Arquitetura/stories | `architect` | — |

**Erros de casting que causam falha real:**
- "analyst escreve o conteúdo" → analyst entrega pesquisa, não o entregável. Use um `dev-*`/writer.
- "cada agente abre seu próprio PR" → push é gated: só `devops` empurra; implementers têm o hook que bloqueia. Padrão correto: escritores **commitam direto na branch ativa** → handoff (`SendMessage`) ao `devops` → ele faz push e abre os PRs.
- Se a squad não tem o papel ideal (ex.: sites sem copywriter dedicado), use o implementer mais próximo (`dev-gamma`) e avise o usuário — não force um analyst.

**4b.1 Mapear paralelismo real:**
- O que pode rodar SIMULTANEAMENTE? (sem dependência de dados/arquivos)
- O que tem dependência direta? (A deve completar antes de B começar)
- Quais agentes disponíveis em `.claude/agents/` batem com cada subtarefa (pelo casting acima)?

**4c. Dimensionamento — um agente por workstream genuinamente independente:**

A filosofia do team-os é **acelerar com paralelismo real**. **Comece com 3-5 teammates** e escale só conforme o trabalho genuinamente se beneficiar de mais paralelismo — **nunca acima de 10 simultâneos** (teto duro do ecossistema). O limite abaixo do teto NÃO é um número mágico — é **independência real** + budget de tokens. Três teammates focados frequentemente superam cinco espalhados; não trate "mais agentes" como default.

```
1 workstream independente  =  1 agente

Workstream independente = bloco de trabalho com OWNERSHIP DE ARQUIVOS DISJUNTO
(não escreve nos mesmos arquivos que outro) e SEM dependência de dados de outro.

→ Mapeie os workstreams independentes do objetivo. Comece com os 3-5 mais relevantes
  e adicione mais só quando houver ganho real de paralelismo (não para "cobrir tudo de uma vez").
```

**Escale conforme o ganho real, com 3 guardrails (da spec oficial — não negociáveis):**
1. **Ownership exclusivo** — dois agentes nunca no mesmo arquivo. Se dois workstreams tocam o mesmo arquivo, eles NÃO são independentes: junte num agente só. **Onde o ownership de arquivo NÃO é disjunto, serialize (task dependencies) — nunca paralelize.**
2. **Dependências viram sequência** — trabalho que depende de outro NÃO paraleliza. **Tasks com dependência: use o campo de dependências do TaskCreate — B só destrava quando A completa.** Não spawne agente ocioso esperando.
3. **Throughput** — ~5-6 tasks por agente mantém o pipeline fluindo com self-claim (throughput esperado, não regra de dimensionamento).

> Esta Fase 4c é a **regra canônica de dimensionamento** — qualquer outro número citado na skill (ex.: "5-6 tasks por agente") é throughput, não dimensionamento.

**Research adversarial:** investigação de causa raiz / hipóteses → 3-5 pesquisadores em paralelo mesmo com poucas tasks (valor vem da diversidade de perspectiva). Faça-os debater e refutar uns aos outros.

**Regra de ouro:** prefira **agentes em streams genuinamente independentes** a poucos agentes serializando trabalho paralelizável — mas adicione cada agente porque ele acelera, não por completude. Nunca spawne agentes que vão brigar pelo mesmo arquivo ou ficar esperando: isso queima tokens sem acelerar.

**4d. Identificar riscos:**
- Mudanças em schema/auth/CI → Plan mode obrigatório
- Múltiplos agentes no mesmo arquivo → redesenhar tasks com ownership exclusivo
- Task muito grande (>1 dia de trabalho) → quebrar em subtasks

### Fase 5 — Proposta de time

Formato da proposta (ajustar ao contexto real):

```
🧑‍💻 Time proposto para: "{objetivo resumido}"
   {N} agentes  ·  {N} tasks  ·  paralelo máximo: {N} simultâneos

─────────────────────────────────────────────────────────────
① {agente-type}  →  nome: "{nome-curto}"
   Ownership: {paths exclusivos deste agente}
   Skills: {/skill-a}, {/skill-b}  (disponíveis via /nome-da-skill)
   Plan mode: {SIM/NÃO} — {razão se SIM}
   Missão: "{spawn prompt — específico, com paths, entregável claro}"

② {agente-type}  →  nome: "{nome-curto}"
   Ownership: {paths exclusivos}
   ...

③ (após ① completar) {agente-type}  →  nome: "{nome-curto}"
   ...
─────────────────────────────────────────────────────────────
📋 Tasks:
   ① → [ ] {task 1} (owner: {nome})
   ① → [ ] {task 2} (owner: {nome})
   ②∥③ → [ ] {task 3} (self-claim)
   depende de ① → [ ] {task 4}

📊 Modelo sugerido: Sonnet (padrão) | Haiku para pesquisa pura (mais barato)
🎚 Effort sugerido: architect/QA → high · implementers → médio (default) · pesquisa rápida → low
⚡ Paralelismo: {N} agentes simultâneos na fase inicial

[s] Spawnar  [a] Ajustar composição  [+] Mais agentes  [p] Plan mode em todos  [n] Cancelar
```

**Effort como alavanca (proposta sempre inclui, junto com o modelo):**
- Sugira effort por papel: **architect/QA → `high`** (o erro custa caro); **implementers → médio (default)**; **pesquisas rápidas → `low`**.
- Teammates **herdam o effort do lead no spawn** — ajuste o seu com `/effort` ANTES de spawnar quem precisa de mais/menos, e mencione ao usuário que `/effort` permite ajuste mid-session.
- Nota de custo: `xhigh`/`max` consomem **3-5× tokens** — reserve para onde o erro custa caro (arquitetura, veredicto de QA), nunca para pesquisa descartável.
- **Nunca despache com modelo implícito quando o papel pedir modelo diferente do lead** — declare explicitamente no spawn (ex.: `"usando modelo opus"` / `"usando modelo haiku"`).

### Fase 6 — Orquestração

Após confirmação do usuário:

1. **Smart-memory** (se ausente): rodar o Discovery Engine primeiro — ver seção dedicada
2. **Tasks**: criar na task list (via as ferramentas de gerenciamento de tasks) com dependências corretas antes de spawnar
3. **Spawn imediato**: spawna TODOS os agentes do plano de uma vez (nomes curtos: `archi`, `alpha`, `beta`, `qa`, `ops`). Não execute nenhuma task você mesmo — cada uma é de um teammate.
4. **Lead fica livre**: após spawnar, seu trabalho é **monitorar, rotear e sintetizar** — nunca pegar trabalho. Se há demanda nova no meio, spawna mais um agente (não faça você).
5. **Nomear a sessão pela tarefa** (opcional, 1 tecla): o título da sessão já vem do projeto+branch (hook `SessionStart` — ver "Nomeação automática da sessão"). Para fixar TAMBÉM a tarefa atual no nome (útil ao retomar depois), imprima ao usuário um `/rename` pronto pra colar, com um slug curto do objetivo:
   ```
   💡 Para identificar esta sessão depois, fixe a tarefa no nome:
      /rename {projeto}: {slug-curto-do-objetivo}
   ```
   (Slash command é input do usuário — a skill não consegue executar `/rename` sozinha; por isso entregamos a linha pronta.)
6. **Orientar**: lembrar ao usuário os controles do agent panel

```
Agent panel ativo ↓
  ↑↓      → navegar entre agentes
  Enter   → abrir sessão do agente e enviar mensagem diretamente
  Esc     → interromper turno atual do agente selecionado
  x       → parar agente selecionado
  Ctrl+T  → toggle da task list

Agente sumiu do panel? → idle após 30s (não parou) — envie mensagem por nome para reativar
```

---

## Settings.json canônico

Configuração global + por projeto (flag AGENT_TEAMS, `teammateMode` e suas opções, mudança de default na v2.1.179, hooks TeammateIdle/TaskCompleted) → ver `reference/settings-canonico.md`.

---

## Nomeação automática da sessão (SessionStart hook)

O hook `SessionStart` global (`team-os-session-title.sh`, instalado pelo `*install`) nomeia toda sessão como `{projeto} · {branch}` — único mecanismo com API oficial (a skill não consegue digitar `/rename`; para fixar TAMBÉM a tarefa, use o `/rename` pronto da Fase 6). Mecanismo, convenção e registro → ver `reference/session-naming.md`.

---

## Smart-Memory Discovery Engine

Quando `docs/smart-memory/` não existe, o team-os **não cria scaffolding vazio** — ele faz *discovery* do projeto real e popula a base com conteúdo verdadeiro. Isso roda ANTES do Team Design, porque é o contexto que todos os agentes vão ler.

**Processo de discovery:**
1. **Rodar o script determinístico** (faz a detecção e gera a base populada):
   ```bash
   bash "$CLAUDE_PROJECT_DIR/.claude/skills/team-os/scripts/discovery.sh"          # ou --dry-run para só inspecionar
   ```
   Ele detecta stack (linguagens, frameworks, styling/UI, DB/ORM, testes, tooling, pkg manager, monorepo), mapeia os módulos e gera `INDEX.md` (linkando `[[agents/<área>/DIGEST]]` e `[[stories/active/]]`) + `project/{overview,tech-stack,conventions,architecture,modules}.md` + `stories/BACKLOG.md` + a estrutura de pastas `stories/{backlog,active,in-review,done}/`, `decisions/`, `_inbox/` e as áreas de `agents/` **por squad instalada** (lidas de `.claude/agents/`), cada área já com seu `DIGEST.md` (seções "Core (permanente)" e "Contexto recente (expira ~14 dias)"). É self-contained (só depende da skill team-os).
   **Modos:** `--repair` completa uma base existente sem sobrescrever nada (caminho padrão de conserto); `--force` regenera do zero com backup automático da base atual.
2. **Enriquecer os `<!-- TODO -->`** — o script deixa marcados os pontos que o código não revela (domínio/propósito do projeto, responsabilidade de cada módulo). Você (ou um teammate `*-analyst`/`*-architect`) preenche lendo o código e o README.
3. **Acelerar com paralelismo** — em codebase grande, delegue o enriquecimento a teammates em paralelo (um por área/módulo), cada um gravando sua seção.
4. **Injetar o protocolo no `CLAUDE.md`** — Fase 2-E: se falta a seção `## Smart-Memory Protocol`, injetar `reference/claude-md-block.md` verbatim.
5. **Validar com o usuário** — apresentar o resumo do que foi inferido e pedir correção do que estiver impreciso antes de seguir.

Use `team-os/reference/obsidian-patterns.md` para o padrão de frontmatter/wikilinks/tags. Só depois da smart-memory populada → Fase 4 (Team Design).

---

## Leitura em camadas (L0 → L1 → L2)

Regra de ouro: **summary-first** — ninguém abre nota inteira sem o `summary` do frontmatter confirmar relevância. É este protocolo que o `*memory` verifica e que o bloco do CLAUDE.md (`reference/claude-md-block.md`) impõe a todo agente:

- **L0 — bootstrap (sempre, e só isto):** `INDEX.md` + `DIGEST.md` da sua área (`agents/<área>/DIGEST.md`) + stories ativas (`stories/active/*.md`). O DIGEST tem duas seções: **"Core (permanente)"** — fatos estáveis do projeto/área — e **"Contexto recente (expira ~14 dias)"** — fatos com decay, revisados/arquivados no `*compact`. Todo fato é **atômico e datado**; fato novo **substitui** a linha antiga (supersedes), nunca acumula.
- **L1 — busca por summaries:** quando o L0 não responde, use o `sm-find.sh` — busca pelos `summary` do frontmatter e devolve `path / kind / status / summary`, sem abrir nota nenhuma:
  ```bash
  bash "$CLAUDE_PROJECT_DIR/.claude/skills/team-os/scripts/sm-find.sh" "<termo>"
  ```
- **L2 — nota inteira:** só quando o `summary` retornado confirma que a nota é necessária — **máximo 3 notas por tarefa**.

⛔ Proibido em qualquer camada: ler pastas inteiras, ler `_archive/`, abrir notas "para ver se tem algo útil". O custo de L0 por área é medido pelo `weigh-memory.sh` (`WEIGH_BOOTSTRAP_<AREA>`, budget default 2000 tokens) e aparece na linha `bootstrap` do painel.

---

## Smart-Memory Compaction

A smart-memory é um **cache quente**, não um baú infinito. Ela guarda **estado e decisões, não histórico narrativo** (ver `reference/obsidian-patterns.md` §0-1). Com o tempo acumula conteúdo frio — stories concluídas, episódios resolvidos, cadeias supersedidas, logs — que infla o working set e queima tokens a cada sessão. A compactação separa o quente do frio.

**Princípio:** conteúdo frio é **movido** (nunca deletado) para `docs/smart-memory/_archive/YYYY-QN/`, fora do caminho de leitura. O `summary` de cada episódio sobrevive na tabela do `DIGEST.md` da área (memória institucional), e os LEDGERs indexam o que foi arquivado. O `_archive/` **não é lido** no bootstrap nem pelos agentes.

### Sinalização (automática, barata)

O `weigh-memory.sh` roda na **Fase 0** de todo `/team-os` e classifica a smart-memory:

| Limiar (env override) | Default | Efeito |
|---|---|---|
| `TOTAL_LINES_WARN` | 8.000 linhas | **HEAVY** — working set pesado |
| `DONE_FILES_WARN` | 30 arquivos em `stories/done/` | **HEAVY** — stories frias acumuladas |
| `FAT_FILE_LINES` | 1.500 linhas num único arquivo | **informativo** — aparece no dashboard, não dispara HEAVY sozinho |
| `resolved`/`superseded` não-arquivados | ≥ 1 | **informativo** — idem (o `*compact` arquiva quando rodar) |
| `WEIGH_BOOTSTRAP_<AREA>` acima do budget | budget 2.000 tokens | linha `bootstrap` do painel marca `[⚠]` (DIGEST gordo) |

Limiar **HEAVY** cruzado → `WEIGH_STATUS=HEAVY` e a linha do painel vira `⚠ PESADA (…) → /team-os *compact`. Os sinais informativos (`resolved`/fat) entram no `WEIGH_DASHBOARD` mas não mudam o status sozinhos. O bootstrap **só sinaliza**; a compactação roda no `*compact`. O script emite `WEIGH_DASHBOARD` **sem** o prefixo `smart-memory :` (o rótulo é do painel).

### `*compact` — resumo

```
/team-os *compact          → plano completo + 1 confirmação + execução integral
/team-os *compact --auto   → sem confirmação: aplica o plano inteiro direto
```

`*compact` combina três frentes:

1. **Fase mecânica** (`compact-memory.sh`): arquiva `stories/done/*` e notas `resolved`/`superseded` — **só faz `mv`, nunca `rm`**, nunca toca em stories ativas, `project/`, INDEXes, DIGESTs, `kind: reference`. Novidades v3:
   - **TTL automático** — notas com frontmatter `expires:` vencido são arquivadas junto;
   - **guardas no `--archive-file`** — o script valida o alvo antes de mover (recusa paths protegidos);
   - **relatório de wikilinks órfãos** — links `[[...]]` que os movimentos quebram são listados para correção (o archivist corrige nos DIGESTs/INDEX como parte do plano);
   - **relatório do `_inbox/` pendente** — o que está aguardando consolidação.
2. **Consolidação do `_inbox/`**: o teammate **archivist** (opus) lê **todo o `_inbox/` de uma vez**, funde/deduplica os fatos e aplica `supersedes` nos `DIGEST.md` das áreas (fato novo substitui a linha antiga; datado). Depois de consolidado, `compact-memory.sh --clear-inbox` esvazia o inbox.
3. **Fase semântica**: o mesmo archivist infere frontmatter (`kind`/`status`/`summary`/`expires`), escreve/atualiza DIGESTs (Core vs Contexto recente, decay ~14 dias) e propõe o plano quente/frio — julgamento semântico é do archivist, nunca do lead.

O lead consolida tudo num plano único (arquivamentos + TTL + consolidação do inbox + correção de órfãos), pede **UMA confirmação** e executa integral, zero pergunta por arquivo. Passos internos, prompt do archivist e comandos → ver `reference/compact-flow.md`.

### Estrutura criada

```
docs/smart-memory/
├── INDEX.md                    ← MOC raiz — linka [[agents/<área>/DIGEST]] e [[stories/active/]]
├── _inbox/                     ← notas rápidas da sessão (<agente>-<data>.md) — consolidadas
│                                  nos DIGESTs no *compact (--clear-inbox esvazia depois)
├── project/
│   ├── overview.md             ← visão geral do projeto (preencher junto com o usuário)
│   ├── tech-stack.md           ← stack detectado automaticamente + confirmar
│   ├── conventions.md          ← padrões de código do projeto
│   ├── architecture.md         ← visão arquitetural + diagrama Mermaid (dev-architect refina)
│   └── modules.md              ← mapa de módulos + God Nodes (devs enriquecem)
├── decisions/                  ← decisões técnicas / ADRs pontuais
├── stories/
│   ├── BACKLOG.md              ← lista master de todas as stories
│   ├── backlog/                ← stories aguardando priorização
│   ├── active/                 ← stories em andamento (Fase 0 lê daqui direto)
│   ├── in-review/              ← stories em revisão/QA
│   └── done/                   ← stories concluídas
├── agents/                     ← UMA área por agente da squad INSTALADA (o discovery.sh
│   │                              cria conforme `.claude/agents/` — exemplos abaixo)
│   ├── research/               ← findings de pesquisa (dev-analyst/researcher escreve)
│   │   └── DIGEST.md           ← resumo vivo da área (≤150 linhas) — seções "Core (permanente)"
│   │                              e "Contexto recente (expira ~14 dias)"; fatos atômicos datados
│   ├── qa/          (+DIGEST)  ← resultados de auditorias e QA (dev-qa escreve)
│   ├── data-engineer/ (+DIGEST) ← saídas de dados / schema
│   ├── ux/          (+DIGEST)  ← saídas de UX
│   └── …            (+DIGEST)  ← demais áreas da squad instalada
└── _archive/                   ← arquivo morto (conteúdo frio compactado). NÃO é lido no
    │                              bootstrap nem pelos agentes — só sob pedido explícito.
    ├── README.md               ← explica a convenção (criado pelo discovery)
    ├── LEDGER.md               ← índice de arquivos gordos esfriados (criado pelo *compact)
    └── YYYY-QN/                ← criado sob demanda pelo *compact (stories-done/, resolved/, misc/)
```

> `_archive/` fica fora do working set: o `weigh-memory.sh` o exclui da contagem de peso e os agentes não o leem (convenção reforçada no Smart-Memory Protocol). Ver "Smart-Memory Compaction".

**`INDEX.md` template:**
```markdown
---
title: "Smart-Memory — {Nome do Projeto}"
type: index
agent: team-os (discovery)
created: {data}
updated: {data}
tags: [index, smart-memory]
---

# Smart-Memory — {Nome do Projeto}

## Projeto
- [[project/overview]] — Visão geral
- [[project/tech-stack]] — Stack tecnológico (detectado)
- [[project/conventions]] — Padrões de código

## Arquitetura
- [[project/architecture]] — Visão arquitetural

## Módulos
- [[project/modules]] — Mapa de módulos + God Nodes

## Stories
- [[stories/BACKLOG]] — Backlog master
- [[stories/active/]] — Stories em andamento

## Saídas por agente (DIGESTs — porta de entrada L0)
- [[agents/research/DIGEST]] · [[agents/qa/DIGEST]] · [[agents/data-engineer/DIGEST]] · [[agents/ux/DIGEST]] · …
  (uma linha por área — o discovery.sh gera conforme a squad instalada)
```

**Injetar no `CLAUDE.md` do projeto** (Fase 2-E — passo obrigatório): se falta a seção `## Smart-Memory Protocol`, injetar o conteúdo de **`reference/claude-md-block.md` verbatim** (criar o `CLAUDE.md` se não existir; **nunca duplicar** se a seção já existe). O bloco canônico vive só nesse arquivo — não copie versões divergentes daqui. Ele cobre: fonte de verdade em `docs/smart-memory/`, leitura L0/L1/L2 com `sm-find.sh` (summary-first, máx 3 notas por tarefa), nunca ler pastas inteiras nem `_archive/`, escrita de sessão via `_inbox/`, fatos atômicos datados com `supersedes`, TTL via `expires:` e proibição de worktrees/branches novas.

---

## Protocolos de spawn

> ⛔ **PROIBIDO: `isolation: worktree`** — NUNCA spawnar agentes com `isolation: worktree`. Isso cria branches isoladas automáticas, impede que as mudanças apareçam no working directory principal (onde o servidor dev roda), gera branches zumbis no git e quebra o fluxo de trabalho local. Todo agente escreve **diretamente na branch ativa** (main). Se dois agentes podem conflitar no mesmo arquivo, resolva com **ownership disjunto** — não com isolation.
>
> **Garantia dura (além da regra):** o hook `block-worktree.sh` (registrado no `.claude/settings.json` do projeto) bloqueia automaticamente spawn com `isolation: worktree`, a ferramenta EnterWorktree e `git worktree add`; e `"worktree": { "bgIsolation": "none" }` desliga o worktree automático de background tasks. A Fase 2-C verifica os dois.

### Como escrever um spawn prompt excelente

Um spawn prompt ruim desperdiça todo o context window do agente em exploração. Um bom prompt entrega contexto cirúrgico:

**Estrutura ideal:**
```
"[Papel e escopo]
 [Paths exatos de ownership — APENAS estes arquivos]
 [Contexto técnico relevante — stack, padrões, constraints]
 [Entregável esperado — o que constitui "done"]
 [Como reportar ao concluir — SendMessage para quem]
 [Skills disponíveis: /nome-skill para ativar]"
```

**Exemplo ruim:**
```
"Revise o código de autenticação e melhore o que precisar."
```

**Exemplo excelente:**
```
"Você é o dev-qa responsável por auditar o módulo de autenticação.
 Seu scope EXCLUSIVO: src/auth/, tests/auth/, docs/smart-memory/agents/qa/
 Stack: Next.js 15, Supabase Auth, JWT em httpOnly cookies.
 Ative /dev-security-patterns e /dev-testing-strategy para referência.
 Entregável: relatório em docs/smart-memory/agents/qa/auth-audit.md com findings,
 severity ratings (CRITICAL/HIGH/MEDIUM/LOW) e recomendações priorizadas.
 Ao concluir: SendMessage para 'archi' com o path do relatório."
```

### Plan mode — quando usar

Obrigatório para trabalho de ALTO RISCO:
- Mudanças em schema de banco de dados
- Módulo de autenticação/autorização
- CI/CD e pipelines de deploy
- Refatorações grandes (>500 linhas afetadas)
- Qualquer breaking change em API pública

```
"Spawn {agente} em plan mode para {tarefa}.
 Só aprovar o plano se incluir: {critério 1}, {critério 2}.
 Rejeitar se: {critério de rejeição}."
```

### Modelos por tipo de tarefa

| Tarefa | Modelo sugerido | Razão |
|---|---|---|
| Arquitetura / ADRs (architect) | Opus (fixo no arquivo) | Máximo raciocínio — decisão errada custa caro |
| Review / veredicto (reviewer/QA) | Opus (fixo no arquivo) | Veredictos precisam de rigor |
| Implementação complexa | segue o lead (`inherit`) | Lead escolhe sonnet por padrão |
| Pesquisa / análise | Haiku (via prompt) ou segue o lead | Mais barato, velocidade |

**Importante — quem vence:** quando você spawna um teammate a partir de uma definição em `.claude/agents/`, o campo `model` do arquivo **prevalece** sobre o "Default teammate model" do `/config`. No padrão CT (Híbrido), `architect`/`reviewer` têm `model: opus` fixo e os demais usam `model: inherit` — só estes seguem o `/model` do lead. Para forçar outro modelo num agente `inherit`, especifique no spawn: `"Spawn {nome} usando modelo haiku para pesquisar..."` (o parâmetro por invocação também vence o `inherit`).

---

## Skills por tipo de agente

team-os SEMPRE inclui no spawn prompt as skills relevantes para cada tipo de agente. Elas ficam disponíveis na sessão do agente para ativar via `/nome-skill`:

| Tipo de agente | Skills a mencionar no spawn prompt |
|---|---|
| **TODOS os agentes** | `/verify-before-done` — obrigatória antes de declarar qualquer trabalho como done |
| **dev-architect / sites-architect** | `/dev-api-design`, `/dev-technical-writing` |
| **dev-analyst / sites-analyst / researcher** | `/deep-research`, `/data-analytics-engineering`, `/dev-defuddle` |
| **dev-dev-alpha** | `/dev-typescript-patterns`, `/dev-testing-strategy`, `/dev-error-handling`, `/nextjs-react-best-practices` |
| **dev-dev-beta** | `/dev-api-design`, `/dev-error-handling`, `/dev-database-patterns` |
| **dev-dev-gamma** | `/dev-typescript-patterns`, `/dev-database-patterns`, `/dev-error-handling` |
| **dev-dev-delta / sites-dev-delta** | `/dev-security-patterns`, `/dev-testing-strategy`, `/dev-error-handling` |
| **dev-qa** | `/dev-testing-strategy`, `/dev-security-patterns`, `/testing-playwright-e2e` |
| **dev-devops / sites-devops** | `/dev-git-workflow` (+ `/sites-deployment` na squad sites) |
| **dev-data-engineer / sites-data (data engineers)** | `/dev-database-patterns`, `/data-supabase-patterns`, `/data-sql-optimization` |
| **dev-bi / dev-data-performance** | `/data-analytics-engineering`, `/data-sql-optimization`, `/data-lake-platform` |
| **sites-dev-alpha** | `/sites-frontend-stack`, `/ui-ux-pro-max`, `/nextjs-react-best-practices`, `/accessibility` |
| **sites-dev-beta** | `/dev-api-design`, `/dev-error-handling`, `/dev-database-patterns` |
| **sites-dev-gamma** | `/sites-copy`, `/sites-page-cro`, `/sites-seo-technical`, `/traffic-analytics-tracking` |
| **sites-ux** | `/sites-ux-interaction`, `/sites-copy`, `/ui-ux-pro-max`, `/accessibility` |
| **sites-qa** | `/dev-testing-strategy`, `/testing-playwright-e2e`, `/web-design-guidelines`, `/sites-seo-technical`, `/accessibility` |
| **social-content** | `/social-copywriting`, `/social-editorial-validation`, `/social-format-specs` |
| **social-design** | `/social-key-visual`, `/social-carousel-design` |
| **traffic-strategist** | `/traffic-paid-ads-optimization`, `/tiktok-marketing` |
| **traffic-google** | `/traffic-google-ads-mcp`, `/traffic-paid-ads-optimization` |
| **traffic-meta / traffic-tiktok** | `/traffic-paid-ads-optimization` (+ `/tiktok-marketing` no tiktok) |
| **traffic-bi / traffic-analyst** | `/traffic-ga4-mcp`, `/traffic-analytics-tracking`, `/data-analytics-engineering` |
| **traffic-qa** | `/traffic-analytics-tracking`, `/traffic-ga4-mcp` |
| **traffic-automation** | `/traffic-google-ads-mcp`, `/traffic-analytics-tracking` |
| **traffic-copywriter** | `/social-copywriting`, `/tiktok-marketing` |
| **traffic-designer** | `/social-format-specs`, `/social-key-visual` |
| **pm-data / pm-analyst** | `/data-supabase-patterns`, `/data-sql-optimization`, `/data-analytics-engineering` |
| **pm-reporter / pm-coach** | `/dev-technical-writing` |
| **sales-analyst** | `/sales-discovery-intake`, `/deep-research`, `/dev-defuddle` |
| **sales-strategist** | `/negotiation`, `/sales-pricing-payback`, `/pricing` |
| **sales-planner** | `/sales-proposal-planning`, `/sales-discovery-intake`, `/dev-technical-writing` |
| **sales-finance** | `/sales-pricing-payback`, `/startup-financial-modeling`, `/pricing` |
| **sales-copywriter** | `/sales-proposal-copy`, `/sales-enablement`, `/sites-copy` |
| **sales-designer** | `/sales-deck-production`, `/slides`, `/presentation-design`, `/ui-ux-pro-max` |
| **sales-qa** | `/sales-proposal-copy`, `/sales-deck-production`, `/presentation-design` |
| **sales-closer** | `/negotiation`, `/sales-enablement`, `/sales-proposal-copy` |
| **brand-analyst** | `/brand-research`, `/deep-research`, `/dev-defuddle` |
| **brand-strategist** | `/brand-platform`, `/brand-research`, `/pricing` |
| **brand-architect** | `/brand-platform`, `/dev-technical-writing`, `/brand-rollout` |
| **brand-voice** | `/brand-verbal-identity`, `/sites-copy`, `/brand-platform` |
| **brand-designer** | `/brand-visual-system`, `/design`, `/ui-ux-pro-max`, `/web-design-guidelines`, `/social-key-visual` |
| **brand-insights** | `/brand-tracking`, `/data-analytics-engineering`, `/social-analytics` |
| **brand-rollout** | `/brand-rollout`, `/brand-verbal-identity`, `/brand-visual-system` |
| **brand-qa** | `/brand-verbal-identity`, `/brand-visual-system`, `/brand-platform` |

> Nomes novos após a fusão de skills (não usar os antigos): `/sites-copy` (ex sites-copywriting/copy-editing/content-strategy) e `/sites-frontend-stack` (ex sites-frontend-design/tailwind-design-system/shadcn-ui); `/accessibility` (ex sites-web-accessibility).

---

## Controle do time durante a sessão

> **Agent panel ≠ Agent view — não confundir:**
> - **Agent panel** (esta seção) é o painel de **teammates** abaixo do prompt na sua sessão de lead. São os agentes do time que você spawnou; comunicam-se entre si peer-to-peer.
> - **Agent view** (`claude agents`) é uma tela separada que gerencia **sessões em background** independentes (cada prompt = nova sessão; Space=peek, Enter=attach). Teammates e subagents que uma sessão spawna **NÃO** aparecem como linhas no agent view. Você pode até carregar `/team-os` dentro de uma sessão dispatchada pelo agent view, mas os dois mecanismos são distintos.

> **🎯 Como ter o painel navegável (setas ↑↓) — leia se você usa `claude agents`:**
> O painel de teammates é da **sessão que rodou o `/team-os`**, não do agent view. No fluxo `claude agents`:
> 1. Dispache/abra uma sessão e **dê attach nela** (Enter/→ na linha dela). Você precisa estar **dentro** da sessão.
> 2. Rode `/team-os` aí dentro (com Agent Teams ativo — Gate 0). Os teammates aparecem no painel **dessa sessão**, navegáveis por ↑↓.
> 3. Se você sair (detach) para o agent view, o painel some — os teammates seguem vivos na sessão; reattach (Enter) para voltar a navegar.
>
> **Alternativa mais simples para orquestrar ao vivo:** abra `claude` (foreground) direto no projeto e rode `/team-os` — o painel navegável fica logo abaixo do prompt, sem precisar de attach. Use `claude agents` quando quiser tocar várias sessões em background; use `claude` foreground quando quiser pilotar o time de perto.

### Agent panel

Keybindings (verificado na v2.1.18x, 2026-09 — podem mudar em versões futuras):
```
In-process mode (padrão):
  ↑↓      → selecionar agente no panel
  Enter   → abrir sessão e enviar mensagem diretamente
  Esc     → interromper turno atual do agente
  x       → parar agente selecionado
  Ctrl+T  → toggle da task list

Split-pane mode (tmux/iTerm2):
  Click   → entrar na sessão do agente
  (não requer navegação por teclado)
```

### Gestão de tasks

Tasks têm 3 estados: `pending` → `in_progress` → `completed`

Tasks com dependências ficam bloqueadas até que as dependências sejam completadas — o sistema desbloqueia automaticamente.

**Self-claim:** Após completar uma task, o agente pega automaticamente a próxima task livre compatível com seu perfil. Isso significa que 5-6 tasks por agente mantém o pipeline fluindo sem intervenção do lead.

### Redirecionar um agente
Entre na sessão (Enter no panel) e dê instrução direta. O agente processa como mensagem prioritária.

### Fix loop com cap — QA ↔ implementer (máx 3 rodadas)

O ciclo de correção QA → implementer → QA tem **cap de 3 rodadas pelo mesmo par**. Se a 4ª rodada for necessária, o par está em loop — o lead intervém com uma de duas saídas:
1. **Escalar para agente fresco em modelo superior** — spawn novo implementer com model explícito acima do atual (ou ajuste via `/model` antes do spawn); o contexto do loop fica no ledger/story, não na cabeça do par viciado.
2. **Adjudicar finding a finding** — o lead decide cada finding aberto (acata ou rejeita) com `Ruling:` registrado no ledger (ver Lead OS).

Regras duras do ciclo:
- **Descarte silencioso é proibido** — todo finding do QA termina corrigido OU adjudicado com ruling registrado. Nunca "some".
- **Proibido ao lead instruir o QA a "não apontar X"** — isso é pré-julgamento que corrompe o veredicto. Se X não deve ser corrigido, o caminho é adjudicar o finding depois que ele existe, com ruling.

### Mensagens enxutas (SendMessage)

SendMessage é canal de **coordenação, não de conteúdo**: **≤15 linhas por mensagem**. Diff, relatório, log ou análise longa vão em **arquivo** (smart-memory ou story) — a mensagem leva só o path.

Contrato de report do teammate ao concluir (exija no spawn prompt):
```
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
Commits: <hashes | "nenhum">
Evidência: <1 linha — o que prova que está pronto>
Detalhe: <path do relatório/artefato completo>
```

### Encerrar graciosamente
```
"Peça ao agente {nome} para encerrar"
```
O agente termina o turno atual, confirma o encerramento e sai. Cleanup automático.

### Quando escalar agentes
Se o trabalho expande além do planejado:
```
"Spawn mais um agente {tipo} chamado {nome} para cobrir {escopo adicional}"
```
Adicione um agente por vez, conforme cada um acelerar de fato o trabalho paralelo real — não para "cobrir tudo de uma vez".

---

## Otimização de tokens

Cada agente é uma sessão independente com seu próprio context window. Token cost é linear com número de agentes ativos.

### Estratégias de economia

**1. Spawn prompts cirúrgicos**
Contexto específico → o agente não precisa explorar para entender o escopo. Cada turno de exploração desnecessária custa tokens.

**2. Plan mode antes de implementar**
Um agente em plan mode consome muito menos tokens que um agente que implementa, descobre que está errado, e reimplementa.

**3. Ownership exclusivo de arquivos**
Dois agentes no mesmo arquivo = conflito + resolução = tokens desperdiçados. Cada agente tem paths exclusivos.

**4. Self-claim com 5-6 tasks por agente**
Sem self-claim → o lead intervém em cada conclusão (lead tokens + agente tokens). Com self-claim → o agente continua sozinho.

**5. Haiku para pesquisa**
Research tasks não precisam de Sonnet. Haiku é 5x mais barato e igualmente eficaz para busca e análise de texto.

**6. Modelo "leader's model" para teammates**
Configure `/config` → Default teammate model → "Default (leader's model)" para que teammates sigam o modelo escolhido pelo lead. **Atenção:** isso só vale para agentes cujo arquivo NÃO fixa `model` — no padrão CT (Híbrido) são os que usam `model: inherit` (todos exceto architect/reviewer, que ficam em opus). O campo `model` do arquivo do agente sempre vence esse ajuste.

**7. Paralelo inteligente**
Não spawnar agentes para tasks sequenciais. Só paralelizar quando há independência real de arquivos/dados.

**8. Smart-memory enxuta (leitura em camadas L0/L1/L2 + compactação)**
Cada agente lê **L0** (INDEX + DIGEST da sua área + stories ativas), busca via **L1** (`sm-find.sh` pelos summaries — path/kind/status/summary) e só abre nota inteira no **L2** com summary confirmando — **máx 3 notas por tarefa**, nunca pastas inteiras. O DIGEST (≤150 linhas, "Core (permanente)" + "Contexto recente" com decay de ~14 dias) é a porta de entrada; o `weigh-memory.sh` mede o custo do L0 por área contra o budget (2000 tokens). Escrita de sessão vai ao `_inbox/`; frontmatter de ciclo de vida (`kind`/`status`/`summary`/`expires`/`supersedes`). O bootstrap pesa a base e sinaliza quando engorda; `/team-os *compact` consolida o inbox e move o frio ao `_archive/` numa tacada só. Ver "Leitura em camadas", "Smart-Memory Compaction" e `reference/obsidian-patterns.md`.

---

## Hooks de time

`TaskCreated` (`task-quality.sh` — rejeita task vaga) e `TaskCompleted` (`check-story-progress.sh` — story só fecha com evidência) fazem parte do **settings padrão** (garantidos pelo `ensure-settings.sh`/`*install`). `TeammateIdle` é receita **opcional** — CUIDADO: `exit 2` incondicional gera loop infinito (idle é o estado desejado). Detalhes e exemplos → ver `reference/hooks-de-time.md`.

---

## Troubleshooting — Limitações conhecidas

**Garantia dura anti-worktree** (regra, sempre presente aqui):

| Problema | Causa | Solução |
|---|---|---|
| Agentes criando branches extras | Lead usou `isolation: worktree` ao spawnar — proibido | NUNCA usar isolation: worktree. Agentes escrevem direto na branch ativa. Resolve conflito de arquivo com ownership disjunto (paths exclusivos por agente). |
| Worktrees aparecendo mesmo sem spawn manual | Background tasks com isolamento automático, ou settings sem a trava | Garantir no `.claude/settings.json` do projeto: `"worktree": { "bgIsolation": "none" }` + hook `block-worktree.sh` registrado em PreToolUse (Fase 2-C). Limpar zumbis: `git worktree list` → `git worktree remove` + delete da branch (devops). |

Demais problemas conhecidos (resume não restaura teammates, task travada, idle-hide do panel, lead implementando/encerrando cedo, permission prompts, tmux órfão, agente em loop) → ver `reference/troubleshooting.md`.

---

## Referência rápida

```
/team-os                → bootstrap completo desta sessão
/team-os *env           → só verificar/corrigir settings.json
/team-os *memory        → só status/bootstrap/repair da smart-memory + protocolo no CLAUDE.md
/team-os *compact       → compactação integral: mecânica + semântica (archivist), 1 confirmação
/team-os *compact --auto → idem, sem confirmação (mostra o plano e aplica)
/team-os *tasks         → só mostrar task list atual
/team-os *spawn {desc}  → Gate 0 + proposta de time para {desc}
/team-os *status        → dashboard de status do time atual
```

> Os subcomandos são **atalhos**: executam apenas a fase correspondente do fluxo principal (*env = Gate 0 + Fase 2-A/B/C; *memory = Fase 2-D/E + Discovery/Repair; *tasks = item 5 do scan; *spawn = Gate 0 + Fases 4-5; *status = painel da Fase 1 + task list), sem repetir o bootstrap inteiro. **Nenhum subcomando que spawna pula o Gate 0** — sem runtime confirmado, nada é spawnado (lembrando o escape hatch: ferramentas de teammate já disponíveis na sessão = gate satisfeito, prossiga).

**Settings.json mínimo:**
```json
{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
  "teammateMode": "auto"
}
```

**Dimensionamento:** a regra canônica é a da **Fase 4c** — 1 workstream independente = 1 agente; comece com 3-5; máx 10 simultâneos; research adversarial = 3-5 pesquisadores. ("5-6 tasks por agente" é só o **throughput esperado** do self-claim, nunca regra de dimensionamento.)

**Subagent definitions:** Use nomes dos agentes em `.claude/agents/` ao spawnar:
```
"Spawn um teammate usando o agente dev-architect para mapear a arquitetura de auth"
```

**Modelo Haiku:**
```
"Spawn um agente dev-analyst chamado 'pesq' usando modelo haiku para..."
```

---

## Arquitetura de referência

```
Você (team lead — sessão principal — esta skill roda aqui)
  │
  ├── Agent Panel (↑↓ para navegar, Enter para abrir)
  │     ├── archi     [working]  → src/auth/, docs/smart-memory/project/
  │     ├── alpha     [pending]  → src/frontend/ (aguarda archi)
  │     ├── qa        [working]  → review paralelo do módulo pago
  │     └── ops       [idle]     → aguarda todos para deploy
  │
  ├── TaskList compartilhada (nativa — Ctrl+T para ver)
  │     ├── [in-progress]  Mapear módulo auth         → archi
  │     ├── [pending]      Implementar login page      → alpha (bloqueada)
  │     ├── [in-progress]  Auditar módulo pagamento    → qa
  │     ├── [pending]      Deploy staging              → ops (bloqueada)
  │     └── [pending]      Criar stories de UX         → self-claim livre
  │
  └── docs/smart-memory/
        ├── INDEX.md                ← L0: todos leram ao iniciar
        ├── _inbox/                 ← notas rápidas da sessão (consolidadas no *compact)
        ├── stories/active/         ← archi e alpha escrevem
        ├── agents/qa/              ← qa escreve findings
        │     └── DIGEST.md         ← porta de entrada da área (Core + Contexto recente)
        └── _archive/               ← frio (stories-done/, resolved/) — nunca lido no bootstrap
```