team-os · v3.0 · 2026-09-26 · sha256 5a7a57b8aa17e07f
team-os v3.0A
Immutable. This exact content never changes and is served at /api/v1/blob/5a7a57b8aa17e07f.
---
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 (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"
user-invocable: true
argument-hint: "[*env | *memory | *compact [--auto] | *tasks | *spawn <objetivo> | *status]"
version: "3.0"
updated: "2026-09-25"
---
# 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 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 por conta própria:** enviar shutdown a teammates · declarar o objetivo "concluído" e parar · encerrar o time porque a rodada acabou.
**Ao terminar uma rodada:** (1) sintetize o que ficou pronto + a linha `WEIGH_REPORT` do placar (`weigh-memory.sh --report`); (2) mantenha os teammates **vivos e ociosos**; (3) **pergunte**: *"Rodada concluída. Mais alguma task, ajuste, ou quer que eu mantenha o time de pé?"* — e aguarde; (4) shutdown só com pedido explícito.
**Pergunta NÃO é comando de shutdown.** Shutdown é terminal e irreversível (só re-spawnar do zero). *"encerrou os agentes?"*, *"dá pra fechar?"*, *"ainda estão de pé?"* são **perguntas** — responda, **não desligue nada**. Só execute com imperativo inequívoco (*"encerre os agentes"*, *"pode fechar o time"*, *"desliga todos"*); na dúvida, pergunte de volta (*"Quer que eu encerre de fato, ou só está verificando? (irreversível)"*) e aguarde o "sim".
**"Sumiu do painel" ≠ encerrado:** a linha some após ~30s ocioso (idle-hide, v2.1.181+), mas o agente continua vivo e endereçável — `SendMessage` pelo nome e ele reaparece. O time só se desfaz quando a sessão inteira fecha.
> Regra de ouro: dispachou ≠ acabou — plantão até o usuário liberar.
---
## 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-`/`finance-`/`legal-`/`seo-`). **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 --save-start` e capturar o bloco `WEIGH_*` (o `--save-start` grava a baseline do **placar** da sessão). 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`.
7. **É o CT?** (existe `.claude/skills/team-os-creator/`) → marque `IS_CT=1`: no repositório fonte **não há smart-memory de produto nem bloco no CLAUDE.md** — as Fases 2-D e 2-E são **puladas** (ver Fase 2) e o painel diz isso.
### 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?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
Linha `smart-memory` = rótulo do painel + valor de `WEIGH_DASHBOARD` (o script emite só o valor). Linha `bootstrap` = `WEIGH_BOOTSTRAP_MAX` (área mais cara no L0) vs budget (2000 tokens); estourou → `[⚠]` (DIGEST gordo; o script já devolve `WEIGH_STATUS=HEAVY`). HEAVY dispara só a compactação **mecânica** automática (Fase 2-F); a semântica roda apenas quando o usuário pedir `/team-os *compact`.
Linhas condicionais (antes da pergunta): `[⚠] CLAUDE.md sem a seção "Smart-Memory Protocol" — vou injetar o bloco canônico na Fase 2-E` (check 6; **não** no CT); `[!] Sessão anterior detectada: {N} tasks ({N} pendentes, {N} em progresso) — continuar ou novo objetivo?` (se há tasks); `[⚠] Múltiplas squads instaladas ({lista}) — projeto de categoria {X} deveria ter só a squad correspondente; rode /team-os-creator → Atualizar para podar` (prefixos distintos em `.claude/agents/` **e** o projeto NÃO é o CT — no CT múltiplas squads convivem por design, **suprima**); `[i] Projeto é o CT — Fases 2-D/E puladas` (`IS_CT=1`).
### 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`), `guard-smart-memory-read.sh` (`Read|Bash`) e `guard-message-size.sh` (`SendMessage`), **TaskCreated** (`task-quality.sh` — rejeita task vaga) e **TaskCompleted** com os 5 gates (`check-story-progress.sh` — story só fecha com evidência; `check-social-progress.sh`, `check-proposal-progress.sh`, `check-finance-progress.sh`, `check-legal-progress.sh` — publicação, proposta, dinheiro e saída jurídica só com PASS + confirmação do usuário). 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** (⛔ **pular no CT**: com `IS_CT=1` não rode discovery/repair — o CT é o repositório fonte dos agentes, não um projeto com smart-memory; diga *"Projeto é o CT — Fases 2-D/E puladas"* e siga para a Fase 3):
- **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 `agents/<squad>/<área>/` da squad instalada, `DIGEST.md` de área, `_inbox/`, subpastas de `stories/`; ou layout antigo `agents/<área>/` sem squad): o **caminho padrão de conserto é `--repair`** — só completa o que falta, **nunca sobrescreve** conteúdo existente, e **migra** (`mv`, logado) `agents/<área>/` → `agents/<squad>/<área>/` quando há uma só squad instalada e `docs/smart-memory/pm/*.md` → `agents/pm/`:
```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 que o `discovery.sh` cria e como deriva as áreas `agents/<squad>/<área>/` → seção "Smart-Memory Discovery Engine".
**E) Protocolo no CLAUDE.md (passo OBRIGATÓRIO — verificado na Fase 0, corrigido aqui; ⛔ pular no CT, `IS_CT=1`):**
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.
**F) Compactação automática (mecânica, sem confirmação):** se `WEIGH_STATUS=HEAVY` **ou** `WEIGH_ARCHIVABLE>0`, rodar `compact-memory.sh --mechanical-only` (só `mv` de stories done, notas `resolved`/`superseded` e TTL vencido — nada é reescrito nem apagado), ler `COMPACT_MOVED=<n>`, re-pesar (`--quiet`) e mostrar no painel `compactado: N arquivados`. A fase semântica (archivist, DIGEST acima do teto) continua só no `*compact`. Opt-out: `TEAM_OS_AUTO_COMPACT=0`. No CT (sem smart-memory) nada acontece. Detalhe → `reference/compact-flow.md`.
### 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 conforme o trabalho genuinamente se beneficiar de mais paralelismo. **Sem teto fixo** — o dimensionamento não é um número mágico, é **independência real** (workstreams com ownership de arquivos disjunto) + budget de tokens: 15 workstreams genuinamente independentes justificam 15 teammates. Três teammates focados frequentemente superam cinco espalhados; não trate "mais agentes" como default nem imponha um limite arbitrário quando o paralelismo real justifica mais.
**1 workstream independente = 1 agente.** Workstream independente = ownership de arquivos **disjunto** e sem dependência de dados de outro. Mapeie-os, comece pelos 3-5 mais relevantes e adicione só com ganho real de paralelismo.
**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: cabeçalho (`objetivo · N agentes · N tasks · paralelo máximo`), um bloco por agente (`①` tipo → nome curto · **Ownership** = paths exclusivos · **Skills** `/…` · **Plan mode** SIM/NÃO com razão · **Missão** = spawn prompt com paths e entregável), lista de tasks com owner/self-claim/dependências, modelo e effort sugeridos, e as opções `[s] Spawnar [a] Ajustar [+] Mais agentes [p] Plan mode em todos [n] Cancelar`. Template completo → ler `reference/proposta-de-time.md` quando precisar.
**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): o título já vem de projeto+branch (hook `SessionStart`). Para fixar também a tarefa, imprima um `/rename {projeto}: {slug-curto-do-objetivo}` pronto para colar — slash command é input do usuário, a skill não o executa.
6. **Orientar**: lembrar ao usuário os controles do agent panel (↑↓ navegar · Enter abrir · Esc interromper · x parar · Ctrl+T task list; agente sumiu = idle, mande mensagem pelo nome) → detalhes em `reference/controle-do-time.md`.
---
## Settings e nomeação da sessão
Settings do projeto = o que o `ensure-settings.sh` garante (Fase 2-C); global = flag + `teammateMode` → `reference/settings-canonico.md`. O hook `SessionStart` global (`team-os-session-title.sh`, instalado pelo `*install`) nomeia toda sessão como `{projeto} · {branch}` — a skill não digita `/rename` (use o pronto da Fase 6) → `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
```
Detecta stack e módulos e gera `INDEX.md` (linka `[[agents/<squad>/<área>/DIGEST]]` e `[[stories/active/]]`), `project/*.md`, `stories/BACKLOG.md` + `stories/{backlog,active,in-review,done}/`, `decisions/`, `_inbox/` e as áreas **`agents/<squad>/<área>/`** — lidas da linha `**Área na smart-memory:**` de cada agente em `.claude/agents/` (fallback: tabela por squad) — cada uma com seu `DIGEST.md`. 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 (é o que o `*memory` verifica e o bloco do CLAUDE.md impõe a todo agente). **L0** (sempre, e só isto): `INDEX.md` + `DIGEST.md` da sua área (`agents/<squad>/<área>/DIGEST.md`, path na linha `**Área na smart-memory:**` do agente) + `stories/active/*.md`. O DIGEST tem "Core (permanente)" e "Contexto recente (expira ~14 dias)"; todo fato é atômico e datado, fato novo **substitui** o antigo. **L1**: `bash "$CLAUDE_PROJECT_DIR/.claude/skills/team-os/scripts/sm-find.sh" "<termo>"` — busca pelos `summary` e devolve `path / kind / status / summary` sem abrir nota. **L2**: nota inteira só com summary confirmando — **máx 3 notas por tarefa**. ⛔ Nunca ler pastas inteiras, `_archive/` ou notas "para ver se tem algo útil" — o hook `guard-smart-memory-read.sh` bloqueia `_archive/`, pasta inteira e a 4ª nota L2 sem nova busca (o `sm-find.sh` zera o contador). O custo do L0 por área é o `WEIGH_BOOTSTRAP_<AREA>` do `weigh-memory.sh` (budget 2000 tokens) — 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_MAX` acima do budget | `BOOTSTRAP_BUDGET_TOKENS` = 2.000 tokens | **HEAVY** — a pior área custa mais que o budget no L0 (DIGEST gordo); a linha `bootstrap` do painel marca `[⚠]` |
| `DIGEST.md` acima do teto | `DIGEST_MAX_LINES` = 60 linhas | **HEAVY** — `WEIGH_DIGEST_OVER`/`_LIST`; o archivist enxuga cada um para ~40 no `*compact` |
Qualquer limiar **HEAVY** cruzado (linhas, done, bootstrap > budget **ou** DIGEST > teto) → `WEIGH_STATUS=HEAVY` e a linha do painel vira `⚠ PESADA (…) → /team-os *compact`. Os sinais informativos (`resolved`/`expired`/fat) entram no `WEIGH_DASHBOARD` como "arquiváveis" mas não mudam o status sozinhos. HEAVY ou arquivável dispara a compactação mecânica automática (2-F); DIGEST gordo e bootstrap só se resolvem no `*compact`. O script emite `WEIGH_DASHBOARD` **sem** o prefixo `smart-memory :` (o rótulo é do painel).
### `*compact` — resumo
`/team-os *compact` = plano completo + **UMA** confirmação + execução integral; `--auto` aplica sem confirmar. Três frentes: (1) **mecânica** — `compact-memory.sh` arquiva `stories/done/*`, notas `resolved`/`superseded` e **TTL vencido** (`expires:`); **só faz `mv`, nunca `rm`**; nunca toca em stories ativas, `project/`, `decisions/`, INDEXes, DIGESTs, `kind: reference` (o `--archive-file` valida o alvo e recusa paths protegidos); reporta wikilinks órfãos e o `_inbox/` pendente; (2) **consolidação do `_inbox/`** — o teammate **archivist** (opus) lê todo o inbox de uma vez, funde/deduplica e aplica `supersedes` nos DIGESTs; depois `--clear-inbox`; (3) **semântica** — o archivist infere frontmatter (`kind`/`status`/`summary`/`expires`), 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 só consolida o plano e dispara os scripts. Órfãos corrigidos, re-pesagem e placar (`--report`) ao final. Passos, prompt do archivist e comandos → `reference/compact-flow.md`.
### Estrutura criada
`discovery.sh` cria `INDEX.md` · `_inbox/` · `project/{overview,tech-stack,conventions,architecture,modules}.md` · `decisions/` · `stories/BACKLOG.md` + `stories/{backlog,active,in-review,done}/` (story = `<id>-<slug>.md`, `<id>` livre por squad) · `agents/<squad>/<área>/DIGEST.md` (uma área por agente instalado; nota de squad inteira pode ficar em `agents/<squad>/`) · `_archive/` (fora do working set — o `weigh-memory.sh` o exclui e os agentes não o leem). Árvore completa e template do `INDEX.md` → ler `reference/estrutura-smart-memory.md` quando precisar.
**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) → contexto técnico (stack, padrões, constraints) → entregável ("done" = o quê, em qual path) → a quem reportar (`SendMessage`) → skills disponíveis (`/nome-skill`).
Exemplo ruim vs. excelente (scope exclusivo, stack, skills, entregável com path, a quem reportar) → `reference/spawn-prompts.md`.
### 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
Instrução de spawn em plan mode (critérios de aprovação/rejeição explícitos) → `reference/spawn-prompts.md`.
### Modelos por tipo de tarefa
Arquitetura/ADRs e review/veredicto → **Opus fixo no arquivo**; implementação → `inherit` (segue o lead); pesquisa → Haiku via prompt ou `inherit`. Tabela → `reference/spawn-prompts.md`.
**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
**Regra:** todo spawn prompt inclui `/verify-before-done` (obrigatória antes de declarar done) **e** as skills relevantes ao papel — as que o próprio agente cita no body (`.claude/agents/<nome>.md`) são a fonte da verdade. Tabela consolidada por agente → ler `reference/skills-por-agente.md` quando precisar. Nomes pós-fusão: `/sites-copy`, `/sites-frontend-stack`, `/accessibility` (não usar os antigos).
---
## Controle do time durante a sessão
**Agent panel** (teammates da sessão que rodou `/team-os`, abaixo do prompt) ≠ **agent view** (`claude agents`, sessões em background). Keybindings (↑↓ · Enter · Esc · x · Ctrl+T), como ter o painel navegável a partir do `claude agents`, estados de task e self-claim, redirecionar/encerrar/escalar agentes → ler `reference/controle-do-time.md` quando precisar.
### 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** (o hook `guard-message-size.sh` bloqueia >20 linhas ou >1.500 caracteres; 1ª linha `[handoff]` = resultado final ao lead, até 60 linhas). 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>
```
## Otimização de tokens
Custo é linear no nº de agentes ativos. As 8 alavancas — spawn prompt cirúrgico, plan mode antes de implementar, ownership exclusivo, self-claim (5-6 tasks/agente), Haiku para pesquisa, "leader's model" para `inherit`, paralelo só com independência real, smart-memory enxuta (L0/L1/L2 + `*compact`, com hooks e compactação automática) → ler `reference/otimizacao-de-tokens.md` quando precisar. **Placar:** `weigh-memory.sh --report` compara com a baseline da Fase 0 (linhas, bootstrap, notas arquivadas).
---
## Hooks de time
`TaskCreated` (`task-quality.sh` — rejeita task vaga) e `TaskCompleted` (`check-story-progress.sh` — story só fecha com evidência; `check-social-progress.sh`, `check-proposal-progress.sh`, `check-finance-progress.sh` e `check-legal-progress.sh` — publicação, envio de proposta, execução financeira e saída jurídica só com PASS + confirmação do usuário) fazem parte do **settings padrão** (garantidos pelo `ensure-settings.sh`/`*install`), junto com os PreToolUse de economia `guard-smart-memory-read.sh` e `guard-message-size.sh`. `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):** agentes criando branches extras = lead usou `isolation: worktree` (proibido — ownership disjunto resolve conflito); worktrees sem spawn manual = falta `"worktree": { "bgIsolation": "none" }` + hook `block-worktree.sh` no settings (Fase 2-C). Zumbis: `git worktree list` → `remove` + delete da branch (devops). Tabela → `reference/troubleshooting.md`.
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 + placar (--report)
```
> Subcomandos são **atalhos** para a fase correspondente (*env = Gate 0 + 2-A/B/C · *memory = 2-D/E + Discovery/Repair · *tasks = scan item 5 · *spawn = Gate 0 + Fases 4-5 · *status = painel + task list + `WEIGH_REPORT`). **Nenhum subcomando que spawna pula o Gate 0** (escape hatch: ferramentas de teammate já disponíveis = gate satisfeito).
**Dimensionamento:** a regra canônica é a da **Fase 4c** — 1 workstream independente = 1 agente; comece com 3-5; escale sem teto fixo conforme a independência real do trabalho; research adversarial = 3-5 pesquisadores. ("5-6 tasks por agente" é só o **throughput esperado** do self-claim, nunca regra de dimensionamento.)
**Spawn:** use os nomes de `.claude/agents/` (*"Spawn um teammate usando o agente dev-architect para…"*); modelo explícito quando diferir do lead (*"… chamado 'pesq' usando modelo haiku para…"*).
---
## Arquitetura de referência
Lead (esta sessão) → Agent Panel (teammates com ownership disjunto) → TaskList compartilhada (nativa, Ctrl+T) → `docs/smart-memory/` (INDEX + `agents/<squad>/<área>/DIGEST.md` + `stories/active/` + `_inbox/` + `_archive/`). Diagrama completo → ler `reference/arquitetura-de-referencia.md` quando precisar.