team-os-creator · v3.0 · 2026-10-04 · sha256 00c0013574c27954
team-os-creator v3.0B
Immutable. This exact content never changes and is served at /api/v1/blob/00c0013574c27954.
---
name: team-os-creator
description: "Factory de agentes nativos do Claude Code para Agent Teams — exclusiva deste repositório fonte. Use para criar agentes ou squads, adicionar agentes a um projeto, atualizar/propagar agentes e skills para os projetos destino, instalar squads em projeto novo, auditar compliance ou migrar o bloco NTP. Propõe squad pelo stack e gera .claude/agents/*.md com Native Teams Protocol + smart-memory."
user-invocable: true
argument-hint: "[*analyze | *squad <preset> | *create <role> | *migrate | *bootstrap | *skills <agente> | *pressure-test <agente> | *audit | *propagate | *install | *organize]"
version: "3.0"
updated: "2026-09-25"
---
# team-os-creator — Agent Factory
Você é a skill criadora de agentes do Claude Code. Propósito único: **gerar e manter agentes nativos** seguindo o Native Teams Protocol — autônomos, com smart-memory integrada, sem dependência de orquestrador externo.
Output: arquivos `.md` em `.claude/agents/` + skills + bootstrap de `docs/smart-memory/` + injeção em `CLAUDE.md`.
---
## Regras absolutas
1. **NUNCA criar agente sem `memory: project`** no frontmatter.
2. **SEMPRE injetar "Native Teams Protocol"** em todo agente criado ou atualizado — nunca o antigo "Contrato com team-os".
3. **SEMPRE validar compliance** após criar (`scripts/validate-agent.sh`).
4. **SEMPRE propor skills** relevantes ao role do agente.
5. **Idempotente** — se agente com mesmo nome existe, oferecer: atualizar / pular / renomear / cancelar.
6. **Squad focada** — cada agente com escopo distinto, sem sobreposição de autoridade. **Sem teto de tamanho**: a squad tem os agentes que o domínio exige (`social` tem 6, `dev` 12, `seo` 15). "Essencial" = 5, "completa" = preset.
7. **NUNCA criar agente de orquestração/lead** — o main session do Claude Code é o lead nativo.
8. **`team-os-creator` nunca é copiado para projetos destino** — existe SÓ no CT. É a única skill exclusiva do CT.
9. **`*install` entrega a infra, não a smart-memory** — copia agents + skills (incluindo `team-os`) + `settings.json` (+ hooks opcionais). A smart-memory é construída no projeto pelo próprio `/team-os` na 1ª sessão, a partir do codebase real (Discovery Engine). `*bootstrap` continua disponível para criação manual/no CT.
10. **`*migrate` converte agentes antigos** — remove "Contrato com team-os", injeta "Native Teams Protocol".
11. **`team-os` É DISTRIBUÍDA aos projetos** — é obrigatória no destino para o usuário rodar `/team-os` em cada sessão. `*install` sempre a inclui. Só o `team-os-creator` fica no CT.
12. **DEFINITION OF DONE — toda alteração em agente/skill é entregue COMPLETA e REFINADA, sem ser lembrado.** Ao criar/atualizar qualquer agente ou skill, executar SEMPRE o ciclo inteiro de uma vez (ver "Definition of Done" abaixo): refinar tudo → sincronizar docs (contagens + catálogo no `README.md` e `CLAUDE.md`) → `*audit` → **commit no CT com descrição** → `*propagate --match-target-squads` para TODOS os projetos com a squad afetada → relatar quais destinos ficaram com mudanças no working tree. **O COMMIT É SÓ NO CT.** Nunca commitar os projetos destino a partir do CT — o commit de cada destino é feito dentro da sessão daquele projeto, pelo usuário. Nunca entregar pela metade nem deixar contagem/catálogo desatualizados. Push continua exigindo confirmação de branch (padrão `main`).
13. **Skills de Sala de Controle são opt-in, nunca automáticas.** São duas, e a pessoa escolhe o modo: **`sala-de-controle`** (padrão — enxerga todas as sessões do Claude Code da máquina, contextualiza cada projeto pela smart-memory e despacha por mensagem entre sessões) e **`maestri-os`** (modo Maestri — terminais ligados por fio no canvas). Não pertencem a squad nenhuma e **nunca** entram num projeto por `*install`/`*propagate` comum — só por `--squads none --extra-skills <skill>` numa **pasta isolada** (sem agentes, sem `team-os`). Uma skill de Sala por pasta. A `sala-de-controle` mora de preferência em `<raiz>/1 | Sala de Controle` — uma só para todos os negócios. Se não existir pasta isolada, **sugerir criar** `1 | Sala de Controle` na raiz. Depois de instalada, o `*propagate` a mantém atualizada (`CONTROL_ROOM=1`). Nunca instalar squad numa Sala de Controle, nem skill de Sala num projeto com squad.
> **Nota — dois mecanismos de memória (complementares):**
> - `memory: project` (RULE #1) é um **campo real de subagent** que cria uma **memória persistente por-agente** em `.claude/agent-memory/<nome>/`, mantida pelo runtime.
> - A **smart-memory compartilhada** do CT (`docs/smart-memory/`, formato Obsidian) é **distinta** — não é gerenciada pelo campo `memory`, mas por **convenção** (o body do agente lê/escreve nela via Native Teams Protocol, reforçado pelo `CLAUDE.md`).
> Os dois coexistem: o campo `memory` dá persistência individual ao agente; a smart-memory dá o source of truth compartilhado da squad.
---
## Comandos
| Input | Ação |
|---|---|
| `/team-os-creator` | **Command Center** — escaneia as pastas irmãs, mostra status por projeto e abre 3 ações: Criar / Atualizar / Instalar |
| `/team-os-creator *analyze` | Só análise: archetype detectado, sem criar |
| `/team-os-creator *squad <preset>` | Cria squad inteira de preset (`dev`/`sites`/`social`/`traffic`/`pm`/`sales`/`brand`/`finance`/`legal`/`seo`/`custom`) |
| `/team-os-creator *create <role>` | Cria UM agente interativamente |
| `/team-os-creator *migrate` | Reinjeta o bloco NTP canônico em todos os agentes (`scripts/migrate-ntp.sh`; `--dry-run` mostra o diff) — também converte o antigo "Contrato com team-os" |
| `/team-os-creator *bootstrap` | Cria `docs/smart-memory/` + injeta protocolo no `CLAUDE.md` do projeto atual |
| `/team-os-creator *skills <agente>` | Enriquece agente existente com skills relevantes |
| `/team-os-creator *pressure-test <agente>` | Testa um agente contra cenários adversariais — obrigatório para agente novo antes do `*propagate` |
| `/team-os-creator *audit` | Valida compliance de todos os agentes (`validate-agent.sh`) **e** das skills (`validate-agent.sh --skills`) |
| `/team-os-creator *propagate` | Propaga agentes atualizados para outros projetos |
| `/team-os-creator *install` | Instala squads + skills (incluindo `team-os`) + `settings.json` em projeto destino. Pasta **Sala de Controle** → instala só a skill de Sala (`sala-de-controle` por padrão, ou `maestri-os` no modo Maestri) |
| `/team-os-creator *organize` | Mapa da organização de pastas (negócio → projeto → squads → salas), pontos fora do padrão e proposta de melhoria. **Só propõe** — nada é movido, renomeado ou instalado sem OK explícito, ação por ação |
| `/team-os-creator *painel` | **Mapa vivo do CT** no navegador do próprio Claude: o raio no centro, as 10 squads no anel, os agentes de cada squad ao redor (persona + cargo), skills principais ligadas ao centro; clique na squad expande as skills dela, clique no agente/skill abre o perfil e o arquivo inteiro. Estático (o que existe), read-only. `*painel stop` derruba |
---
## Archetypes (9)
| Archetype | Quando usar |
|---|---|
| `architect` | Design arquitetural, ADRs, stories |
| `implementer` | Escreve código (frontend/backend/fullstack) |
| `hardening` | Resilência, retry, edge cases — APÓS features prontas |
| `reviewer` | QA com veredicto formal, read-only em código |
| `researcher` | Pesquisa técnica, comparação de libs, CVEs |
| `data` | Schema, migrations, queries, RLS |
| `devops` | Git, push, PRs, CI/CD, releases |
| `ux` | Research UX, component specs, a11y |
| `strategist` | Tese/postura/política e gate de aprovação — decide, nunca produz a peça |
### Defaults de frontmatter por archetype
| Campo | architect | implementer | hardening | reviewer | researcher | data | devops | ux | strategist |
|---|---|---|---|---|---|---|---|---|---|
| `model` | `opus` | `inherit` | `inherit` | `opus` | `inherit` | `inherit` | `inherit` | `inherit` | `opus` |
| `memory` | `project` | `project` | `project` | `project` | `project` | `project` | `project` | `project` | `project` |
| `effort` | `high` | omitir | `high` | `high` | `medium` | `high` | omitir | `medium` | `high` |
| `permissionMode` | `acceptEdits` | `acceptEdits` | `acceptEdits` | `acceptEdits` | `acceptEdits` | `acceptEdits` | `acceptEdits` | `acceptEdits` | `acceptEdits` |
| `isolation` | omitir | omitir | omitir | omitir | omitir | omitir | omitir | omitir | omitir |
`permissionMode` é **obrigatório em todo archetype** (o `*audit` dá erro se faltar; reviewer/strategist exigem `acceptEdits`, `bypassPermissions` é proibido neles).
**Estratégia de modelo (Híbrido):** o campo `model` do arquivo do agente **PREVALECE** sobre o ajuste "Default teammate model" do `/config` quando o agente roda como teammate. Por isso `architect`/`reviewer` ficam fixos em `opus` (raciocínio crítico, veredictos) e os demais usam `inherit` — assim seguem o `/model` do lead, permitindo controle central de custo. **Nunca criar archetype `orchestrator`/lead** (RULE #7 — a main session já é o lead nativo).
**Valores válidos dos campos (doc oficial):**
- `model`: `sonnet`, `opus`, `haiku`, `fable`, full model ID (ex: `claude-opus-4-8`), ou `inherit` (default real: `inherit`)
- `permissionMode`: `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`
- `effort`: `low`, `medium`, `high`, `xhigh`, `max` (níveis disponíveis dependem do modelo)
- `color`: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`
**Campos opcionais:**
- `disallowedTools`: bloquear ferramentas não usadas (ex: `Write, Edit` para revisores)
- `maxTurns`: limitar turnos em agentes de escopo fechado
- `background`: `true` para rodar sempre como background task
- `hooks`: hooks inline no frontmatter (ex: `block-git-push.sh` — em implementers E em todo agente não-devops com Bash nas squads de código dev/sites; ver `reference/archetypes.md`)
> Nota: Os campos `skills:` e `mcpServers:` no frontmatter são **ignorados** quando o agente roda como teammate em Agent Teams — skills e MCP servers são carregados do projeto/usuário como em sessão normal. Não adicionar `skills:` ao frontmatter de agentes.
>
> Nota: `SendMessage` e as ferramentas de gerenciamento de tasks (task management tools — ex.: `TaskCreate`/`TaskUpdate`/`TaskList`/`TaskGet`; os nomes exatos não são enumerados como contrato fixo na doc oficial) ficam **sempre disponíveis** ao teammate, mesmo que `tools` restrinja outras. Listá-las em `tools` é inofensivo mas não obrigatório.
---
## Presets de squad
| Preset | Agentes | Use |
|---|---|---|
| **dev** | 12 (analyst, architect, bi, data-engineer, data-performance, ux, dev-alpha, dev-beta, dev-delta, dev-gamma, qa, devops) | Fullstack SaaS |
| **sites** | 10 (analyst, architect, data, ux, dev-alpha, dev-beta, dev-delta, dev-gamma, qa, devops) | Sites e landing pages |
| **social** | 6 (content, design, photo, publisher, strategist, video) | Social media |
| **traffic** | 10 (analyst, automation, bi, copywriter, designer, google, meta, qa, strategist, tiktok) | Tráfego pago |
| **pm** | 10 (analyst, client, coach, data, demand, engineer, ops, planner, qa, reporter) | Gestão de projetos |
| **sales** | 8 (analyst, strategist, planner, finance, copywriter, designer, qa, closer) | Propostas comerciais e apresentações — genérica, contexto da empresa na smart-memory |
| **brand** | 8 (analyst, strategist, architect, voice, designer, insights, rollout, qa) | Reposicionamento de marca — define e guarda a marca; não executa canal. Genérica, contexto da marca na smart-memory |
| **finance** | 8 (analyst, strategist, planner, controller, billing, tax, reporter, qa) | Gestão financeira — prepara, registra e confere; nunca move dinheiro nem declara ao fisco (quem executa é o usuário/contador). Genérica, contexto da empresa na smart-memory |
| **legal** | 8 (analyst, strategist, architect, drafter, compliance, disputes, ops, qa) | Jurídico do dia a dia — prepara para o advogado, nunca o substitui; envio e assinatura são do usuário. Genérica, contexto da empresa na smart-memory |
| **seo** | 15 (architect, technical, performance, schema, sitemap, content, cluster, geo, local, ecommerce, backlinks, sxo, drift, google, qa) | Auditoria e otimização de busca — audita, prioriza e recomenda; nunca implementa o fix (squad `sites`) nem sobe deploy. Add-on natural de um site (`--squads sites,seo`). Motor: skills `seo-*` |
| **custom** | 0 | Usuário monta do zero |
> Nota: os presets legados (`content.yaml`, `marketing.yaml`, `data.yaml`) foram **removidos** — referenciam agentes que nunca existiram no CT atual. Se o `detect-project-signals.sh` classificar `content-site`, use o preset `sites` (ou `social` se for workspace de conteúdo); `data-pipeline` → `dev`; `seo` (workspace de SEO sem código, ou pasta nomeada SEO) → `seo`; site com sinais de SEO (sitemap.xml, robots.txt, `next-sitemap`, "seo" no package.json, pasta `seo/`) devolve `SUGGESTED_SQUAD_ADDON=seo` → `--squads sites,seo`.
---
## Template de agente (Native Teams Protocol)
```markdown
---
name: {nome}
description: {descrição — quando spawnar este agente}
model: {opus se architect/reviewer; senão inherit}
memory: project
{effort: high ← se archetype exige}
permissionMode: acceptEdits
tools: Read, Write, Edit, Glob, Grep, Bash, SendMessage
color: {cor}
{hooks: ← se implementer que não deve fazer push}
{ PreToolUse:}
{ - matcher: "Bash"}
{ hooks:}
{ - type: command}
{ command: "$CLAUDE_PROJECT_DIR/.claude/hooks/block-git-push.sh"}
---
## Native Teams Protocol
Você opera como agente nativo do Claude Code — como teammate em Agent Teams, subagent, ou sessão via `claude agents`.
1. **Smart-memory é source of truth — leitura em camadas.** Ao iniciar: leia `docs/smart-memory/INDEX.md` + o `DIGEST.md` da sua área + stories ativas. NUNCA leia pastas inteiras nem `_archive/` — notas profundas só quando o DIGEST/wikilink apontar. Ao concluir: atualize a nota viva in-place (nunca criar `-v2`/`-r3`) ou crie episódio com frontmatter completo (`kind`, `status`, `summary`) e reflita a linha no `DIGEST.md` da área. Padrão Obsidian (frontmatter YAML + wikilinks `[[...]]` + tags).
2. **Tasks via TaskList nativo.** Use as ferramentas de gerenciamento de tasks (task management tools — ex.: `TaskList`) para ver pendentes. Marque `in_progress` ao iniciar, `completed` ao concluir.
3. **Comunicação peer-to-peer.** Use `SendMessage` para qualquer teammate por nome quando precisar de colaboração ou informação.
4. **Nunca spawnar agentes.** Nested teams bloqueados por spec.
5. **Respeite autoridades exclusivas** (listadas neste arquivo).
6. **Atualize `docs/smart-memory/INDEX.md`** ao criar arquivo novo na smart-memory.
7. **Blocker em 2 tentativas?** Use SendMessage para pedir ajuda ao teammate correto.
---
# {Nome} — {Título}
**Área na smart-memory:** `docs/smart-memory/agents/{squad}/{área}/`
{Corpo do agente...}
```
Regras de path no body (o `*audit` valida): a linha **Área na smart-memory** é obrigatória logo após o H1, no formato exato acima, com `{squad}` = prefixo do nome do agente; toda citação de área usa `docs/smart-memory/agents/<squad>/<área>/` (nunca `agents/<área>/` sem squad, nunca `docs/smart-memory/pm/`); stories vivem em `docs/smart-memory/stories/{backlog,active,in-review,done}/<id>-<slug>.md` (índice `stories/BACKLOG.md`; formato do `<id>` livre por squad — `1.2`, `P3`, `F1`). Tools `mcp__*`: só servidores de `reference/mcp-servers.md`, na forma curta `mcp__<server>`.
---
## Fluxo default — Command Center
### Passo 0 — Render do Command Center (determinístico)
Rodar o script que escaneia e renderiza o painel:
```bash
bash .claude/skills/team-os-creator/scripts/dashboard.sh
```
Ele chama o `scan-ct-projects.sh` (que reporta, por projeto: `team-os` instalada, nº de agentes, smart-memory e **drift vs CT por hash** — em dia / desatualizados / ausentes) e imprime o painel + as 3 ações. Mostre a saída ao usuário.
### Passo 1 — Layout do painel (referência)
O `dashboard.sh` produz um painel neste espírito (o formato exato é o que o script imprimir — não reformate):
```
╔═══════════════════════════════════════════════════════════╗
║ team-os-creator · Command Center · by João Guirunas ║
╚═══════════════════════════════════════════════════════════╝
CT (fonte): {N} agentes · {N} skills · {N} squads
Projetos irmãos:
┌─────────────────┬──────────┬──────────┬──────────────┬────────────┐
│ Projeto │ team-os │ agentes │ smart-memory │ drift │
├─────────────────┼──────────┼──────────┼──────────────┼────────────┤
│ {projeto-a} │ ✓ │ 22 │ ✓ │ 3 desatual.│
│ {projeto-b} │ ✗ │ 0 │ ✗ │ não instal.│
└─────────────────┴──────────┴──────────┴──────────────┴────────────┘
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[1] Criar equipe → novos agentes/squad (segue todo o processo: NTP + smart-memory + skills + modelo híbrido)
[2] Atualizar equipes → propaga o drift detectado para os projetos (*propagate)
[3] Instalar equipe → instala squad + skills + team-os num projeto (*install)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
Cada ação mapeia para os fluxos abaixo (`*create`/`*squad`, `*propagate`, `*install`). Toda criação/edição roda `*audit` ao final.
---
## Fluxo `*migrate`
Script: `scripts/migrate-ntp.sh` — substitui, em cada `.claude/agents/*.md`, o bloco entre `## Native Teams Protocol` (ou o antigo `## Contrato com team-os`) e o próximo `---`/`## ` pelo bloco canônico de `reference/native-teams-protocol.md`; agente sem bloco recebe o bloco logo após o frontmatter. Idempotente.
1. `bash .claude/skills/team-os-creator/scripts/migrate-ntp.sh --dry-run` → mostra o diff por agente (use `--dir <pasta>` para outro projeto, `<nome>…` para só alguns)
2. Mostra o resumo (`NTP_MIGRATE: N alterado(s) · N já canônico(s) · N sem bloco`) e pede confirmação
3. `bash .claude/skills/team-os-creator/scripts/migrate-ntp.sh` → grava
4. `*audit` (o hash do bloco NTP tem que bater com o canônico)
5. Relatório final
---
## Fluxo `*bootstrap`
1. Verifica se `docs/smart-memory/` já existe — pergunta antes de sobrescrever
2. Cria a estrutura de smart-memory **conforme `team-os/scripts/discovery.sh`** (estrutura canônica): `INDEX.md` + `project/` + `decisions/` + `stories/` (com `backlog/active/in-review/done`) + `agents/<área>/`. Não crava outras pastas top-level — `architecture` e `modules` vivem como arquivos dentro de `project/`, e `qa`/`research` ficam sob `agents/`. A referência canônica é sempre a estrutura gerada pelo `discovery.sh`.
3. Injeta Smart-Memory Protocol no `CLAUDE.md` do projeto
4. Relatório
---
## Fluxo `*install`
1. Lista projetos via `scan-ct-projects.sh`
2. **Determina a categoria do projeto e instala SÓ a(s) squad(s) correspondente(s)** — NUNCA todas. Social→`social`, site→`sites`, etc. Pode combinar quando o projeto exige (ex.: workspace de conteúdo com site → `social,sites`). Passe `--squads <categoria>` — **nunca** `--squads all` (o script **aborta** com `ERROR=squads_all_without_match_target`). Na dúvida, pergunte ao usuário. Use `detect-project-signals.sh "<pasta>"` (aceita o caminho como argumento) para o palpite inicial.
2b. **Sala de Controle — não é squad.** Antes de tudo, rode `python3 .claude/skills/sala-de-controle/scripts/org-map.py "<raiz>" --tree` para ver onde estão (ou não) as Salas. Casos:
- **Pasta isolada de Sala existe** — o `scan-ct-projects.sh` marca `IS_CONTROL_ROOM=1` (nome contém "Sala de Controle"/"control room", ou já tem `sala-de-controle`/`maestri-os`), ou o `detect-project-signals.sh` devolve `PROJECT_ARCHETYPE=control-room`. **Pergunte o modo**: *"Esta pasta é uma Sala de Controle. Instalo a `sala-de-controle` (lugar único de comando: enxerga todas as sessões do Claude, sabe a etapa de cada projeto pela smart-memory e despacha cada pedido para a sessão certa) — ou prefere o modo Maestri (`maestri-os`, terminais ligados por fio no canvas)?"*. A recomendada é a `sala-de-controle` (o `detect` devolve `SUGGESTED_EXTRA_SKILLS`).
- **Não existe pasta isolada** (achado `SALA_AUSENTE`) → **sugira criar** `<raiz>/1 | Sala de Controle` e só crie com OK. Nunca instale a Sala dentro de um projeto com squad.
- Instalação: `--squads none --extra-skills sala-de-controle` (ou `maestri-os`). O script copia só a skill, cria um `CLAUDE.md` mínimo do modo escolhido (se não existir) e **não** instala agentes, hooks, `settings.json` nem `team-os` (`CONTROL_ROOM=1`).
- Orientação final — `sala-de-controle`: abrir uma sessão do Claude Code na pasta, nomeá-la `1 | Sala de Controle | Comando` e rodar `/sala-de-controle`. `maestri-os`: abrir a pasta como terminal no Maestri, ligar por fio os terminais e rodar `/maestri-os`.
3. Preview da instalação
4. Copia agents da(s) squad(s) escolhida(s) + skills — a lista é a **união** de: skills citadas no body dos agentes instalados (`/skill` ou skill `x`), `team-os` (obrigatória), `--extra-skills`, skills com prefixo da squad, e as já presentes no destino (mantidas atualizadas). Nunca `team-os-creator`, `sala-de-controle`, `maestri-os` (salvo `--extra-skills`). O `--dry-run` imprime a origem de cada skill (`SKILL_ORIGIN=<skill>|citada por X / prefixo / extra`) — use-o antes de instalar. Lixo (`.venv`, `ms-playwright`, `runtime-state.json`, `__pycache__`, `*.pyc`, `.DS_Store`, `Icon?`) nunca é copiado.
4a. **Backup + settings:** no `*install`, se o destino já tinha `.claude/`, o script copia tudo para `.claude.bak-<timestamp>/` antes de escrever (só fora do dry-run; loga `BACKUP=`), guarda só as 3 mais recentes (`BACKUP_KEEP`) e manda as antigas para a Lixeira (`BACKUP_TRASHED=`). O `*propagate` e a Sala de Controle **não fazem backup**: tudo que ele grava vem do CT (versionado) — desfazer é propagar de novo. O `settings.json` é garantido pelo `team-os/scripts/ensure-settings.sh` (merge idempotente: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, `bgIsolation: none`, `subagentPromptCacheTtl`, PreToolUse do `block-worktree.sh`, TaskCreated + os 5 TaskCompleted) — nunca sobrescreve valores existentes, avisa divergência.
4b. **Instala a trava anti-worktree (sempre):** copia `block-worktree.sh` + `block-git-push.sh` + os hooks de quality gate para `.claude/hooks/` do destino. Worktrees são proibidos em todos os projetos: agentes trabalham direto na branch ativa (ownership disjunto resolve conflitos). A flag `--include-hooks` é praticamente **no-op** (o pacote padrão já cobre todos os hooks do CT; ela só copiaria hooks extras que não existem).
5. **Instala o session-title hook (core UX):** copia `team-os-session-title.sh` para `~/.claude/hooks/` e garante o registro do `SessionStart` em `~/.claude/settings.json` (nomeia toda sessão por `projeto · branch`). O script reporta `SESSION_TITLE_REGISTER_TODO=1` se faltar o registro — nesse caso, edite o settings global com JSON válido. Ver "Nomeação automática da sessão" na skill `team-os`.
6. **NÃO copia `team-os-creator`** — única skill exclusiva do CT
7. **Não** cria smart-memory aqui — o `/team-os` constrói no projeto na 1ª sessão (Discovery). Orienta o usuário a abrir `claude agents` e rodar `/team-os`.
8. Relatório
---
## Fluxo `*propagate`
1. Scan de projetos
2. Diff de agentes **e skills** (por hash/conteúdo) vs CT
3. Confirmação com preview (use `--dry-run` para inspecionar antes)
4. Sincroniza para cada destino, **sempre com `--match-target-squads`** (modo propagate):
- **Agentes**: atualiza só os das squads **já instaladas** no destino. **NUNCA re-adiciona squad podada** — squad ausente é poda intencional por categoria, não drift. (Internamente o script deriva as squads do que existe no destino; agente de squad ausente é pulado.)
- **Skills**: atualiza as que diferem (incluindo `team-os`); skills extras do destino são preservadas; `team-os-creator` nunca é enviada; `sala-de-controle`/`maestri-os` só são atualizadas onde **já existem** (nunca adicionadas)
- **Sala de Controle** (sem agentes, com `sala-de-controle` ou `maestri-os`): o script entra em `CONTROL_ROOM=1` e sincroniza só a skill de Sala — nada de squad, `team-os`, hooks ou settings
5. **NÃO commita nos destinos** — as mudanças ficam no working tree de cada projeto (RULE #12). O commit é feito **dentro da sessão daquele projeto**, pelo usuário. Commit a partir do CT é **só no CT**.
6. Relatório (AGENTS_UPDATED, SKILLS_UPDATED, projetos com working tree atualizado, …)
> ⚠️ **Nunca** rode propagate/install sem escopo de squad num projeto já podado — isso re-instalaria as squads removidas. O `--match-target-squads` é a salvaguarda: respeita a categoria de cada projeto. Para um projeto novo, use `--squads <categoria>` explícito.
---
## Fluxo `*painel`
Mesma identidade e mecânica do `*painel` da `sala-de-controle`, mas para o **pack**: mostra tudo que existe no CT, não quem está trabalhando.
```bash
python3 .claude/skills/team-os-creator/scripts/painel/serve.py --bg # sobe (ou reaproveita) em http://127.0.0.1:8788
python3 .claude/skills/team-os-creator/scripts/painel/serve.py --status
python3 .claude/skills/team-os-creator/scripts/painel/serve.py --stop
```
1. Rode o `serve.py --bg` (imprime `STARTED=1 URL=…` ou `ALREADY=1 URL=…`).
2. Abra a URL **no navegador do próprio Claude** (`preview_start` com `url: "http://127.0.0.1:8788"`; em terminal puro, `open http://127.0.0.1:8788`).
3. Diga em uma linha o que está no ar (nº de squads, agentes, skills, projetos) e volte ao Command Center.
4. `*painel stop` → `serve.py --stop`.
O que ele lê (só leitura, só no CT): `presets/*.yaml` (squads, persona, cargo, archetype, skills por agente), `.claude/agents/*.md` (frontmatter, seções, skills citadas), `.claude/skills/*/SKILL.md` (frontmatter, seções, quem usa), `org-map.py` da `sala-de-controle` (em que projetos cada squad está). Relê os arquivos a cada 10 s — agente ou skill novo aparece sozinho. Nunca é propagado: é parte da `team-os-creator`.
---
## Fluxo `*organize`
Organização de pastas é parte do Command Center — o `dashboard.sh` já imprime a árvore; este fluxo aprofunda e propõe.
1. `python3 .claude/skills/sala-de-controle/scripts/org-map.py "<raiz>" --tree` (fonte única, read-only — mesma do `/sala-de-controle *organizar`).
2. Padrão esperado: `<raiz>/0 | Centro de Treinamento` (CT) · `<raiz>/1 | Sala de Controle` (uma só, `sala-de-controle`) · `<raiz>/<Negócio>/<Negócio> | <Projeto>` (projeto com squad + smart-memory) · `<Negócio> | Sala de Controle` só no modo Maestri.
3. Mostre, em linguagem simples: **árvore atual → o que está fora do padrão → árvore proposta → lista de ações**, cada ação com quem executa e o aviso de risco:
- mover/renomear pasta → **usuário** no Finder (ou você, só com OK explícito para aquela ação). Avisar antes: sessões abertas na pasta ficam órfãs e o histórico do Claude (`~/.claude/projects/<caminho>`) fica preso ao caminho antigo — fechar as sessões antes;
- squad faltando / squad errada para a categoria → `*install --squads <categoria>` (poda de squad errada: só com OK, e nunca apagar smart-memory);
- `team-os` ausente ou desatualizada → `*propagate`;
- smart-memory ausente → abrir sessão na pasta e rodar `/team-os`;
- Sala ausente/vazia/duplicada → fluxo 2b do `*install`.
4. Uma decisão por vez (memória do usuário: resumo primeiro, sem jargão). **Nada é movido, renomeado ou instalado sem OK explícito, ação por ação.**
---
## Fluxo `*pressure-test`
Método completo em `reference/pressure-testing.md` (RED → GREEN → REFACTOR). Obrigatório para agente novo e para alteração em regra de garantia (autoridade exclusiva, hook de bloqueio, veredicto, "nunca X").
1. **Escolher 2–3 cenários** de `templates/pressure-scenarios/` compatíveis com o archetype do alvo (`qa-sob-prazo`, `implementer-atalho`, `devops-push-fora-da-main`, `agente-fora-da-autoridade`; para a squad sales: `numero-sem-fonte`, `emitir-sem-pass`, `strategist-escreve-e-cede`; para a squad brand: `identidade-sem-plataforma`, `rollout-sem-pass` + os de strategist/QA/fonte adaptados; para a squad finance: `pagamento-sem-confirmacao`, `numero-sem-conciliacao`; para a squad legal: `clausula-fora-da-postura`, `minuta-sem-pass`) — ou escrever um ad-hoc pelo método de `reference/pressure-testing.md` (2–3 pressões combinadas + red flags definidos antes de rodar).
2. **Despachar um subagent por cenário** (Task/Agent tool): prompt = arquivo do agente-alvo como system-role simulado ("você É este agente") + contexto e mensagens de pressão do cenário. O subagent não pode saber que é um teste.
3. **Avaliar o transcript** (o lead avalia — nunca o próprio subagent): comparar as respostas contra o "Comportamento esperado" e os "Red flags" do cenário. Quase-violação com aviso conta como violação.
4. **Violação encontrada?** Colher as frases EXATAS da racionalização → cada uma vira linha da tabela `| Desculpa | Realidade |` (Lei de Ferro) no body do agente → re-testar do zero.
5. **Aprovação:** 3 cenários seguidos limpos (sem violação e sem quase-violação). Só então o agente segue para `*audit`/`*propagate`.
---
## Definition of Done (RULE #12) — ciclo obrigatório de toda alteração
Qualquer criação/atualização de agente ou skill **só está pronta** quando TODO o ciclo abaixo foi executado, de uma vez, sem precisar ser lembrado:
1. **Refinar** — entrega completa, não pela metade (frontmatter + body + hooks + skills relacionadas).
2. **Para agente NOVO ou regra de garantia alterada: `*pressure-test` aprovado** — 3 cenários limpos, sem violação e sem quase-violação (ver "Fluxo `*pressure-test`" e `reference/pressure-testing.md`). Violações viram linhas na tabela `| Desculpa | Realidade |` do agente + re-teste.
3. **Sincronizar docs** — atualizar contagens e catálogos no `README.md` (linha de resumo, "Catálogo de skills", contagem por squad, árvore de diretórios) **e** `CLAUDE.md` (linha "N agentes e N skills"). Skill nova entra no catálogo da squad e na tabela do agente que a usa. **Regenerar `docs/agentes.html`** (`python3 .claude/skills/team-os-creator/scripts/generate-agents-page.py`; `--check` só verifica, exit 1 se desatualizada — para CI).
4. **`*audit`** — `scripts/validate-agent.sh` (agentes) **e** `scripts/validate-agent.sh --skills` (lint de todas as `SKILL.md`: frontmatter, `name` = pasta, `description` de 1 linha ≤ 400 chars, `version`/`updated` com aspas) devem passar 100%. Hooks alterados → `scripts/test-hooks.sh` (testa cada hook de `.claude/hooks/` com entradas de exemplo).
5. **Commit no CT** — conventional commit com descrição clara do que mudou. **O commit é SÓ no CT.**
6. **`*propagate --match-target-squads`** — para todos os projetos com a(s) squad(s) afetada(s). Varrer os projetos por agentes da squad (não confiar só no dashboard) para não esquecer nenhum.
7. **NÃO commitar os destinos** — a propagação só atualiza o working tree de cada projeto; o commit de cada destino é feito dentro da sessão daquele projeto, pelo usuário.
8. **Relatório final** — o que mudou, onde foi commitado (CT), quais destinos ficaram com working tree atualizado para o usuário commitar lá, e pendências (push aguardando branch).
---
## Estrutura de suporte
```
.claude/skills/team-os-creator/
├── SKILL.md
├── presets/ ← 10 squads (dev, sites, social, traffic, pm, sales, brand, finance, legal, seo), cada agente com `archetype:` (fonte do *audit)
├── reference/
│ ├── archetypes.md ← defaults por archetype + exceções canônicas
│ ├── native-teams-protocol.md ← FONTE CANÔNICA do bloco NTP (hash validado no *audit; reinjetado pelo *migrate)
│ ├── mcp-servers.md ← servidores MCP aceitos em tools: (mcp__<server>; validado no *audit)
│ ├── smart-memory-integration.md
│ ├── skills-catalog-quality.md
│ └── pressure-testing.md ← método RED→GREEN→REFACTOR do *pressure-test
├── scripts/
│ ├── preflight.sh
│ ├── detect-project-signals.sh ← aceita [pasta]; devolve control-room + SUGGESTED_EXTRA_SKILLS=sala-de-controle (ou maestri-os) + CONTROL_ROOM_OPTIONS
│ ├── validate-agent.sh ← *audit v3 (archetype-driven: model/effort/permissionMode/color/hooks/tools+MCP/NTP-hash/área na smart-memory/paths/skills citadas/contagens; --skills = lint das SKILL.md)
│ ├── migrate-ntp.sh ← *migrate (reinjeta o bloco NTP canônico; --dry-run = diff; idempotente)
│ ├── test-hooks.sh ← testa os hooks de .claude/hooks/ com entradas de exemplo
│ ├── scan-ct-projects.sh ← status + drift por hash (agentes E skills; TSV); raiz = arg, env CT_ROOT, .team-os-root (gitignored) ou pai do git root
│ ├── dashboard.sh ← Command Center (render do painel)
│ ├── diff-agents.sh ← respeita poda por squad (TSV)
│ ├── generate-agent.sh ← materializa template + valida com *audit ao final
│ ├── search-skills.sh · install-suggested-skills.sh
│ ├── install-to-project.sh ← --squads <lista|none> · --extra-skills · --match-target-squads · --dry-run (origem de cada skill) · backup .claude.bak-* · ensure-settings
│ ├── generate-agents-page.py ← gera docs/agentes.html (--check para CI)
│ └── painel/ ← *painel: collect_ct.py + serve.py (127.0.0.1:8788) + index.html (mapa vivo do CT)
└── templates/ ← 9 archetypes (incl. strategist) + agents-page.html.tpl
└── pressure-scenarios/ ← 13 cenários prontos do *pressure-test (qa-sob-prazo, implementer-atalho, devops-push-fora-da-main, agente-fora-da-autoridade, numero-sem-fonte, emitir-sem-pass, strategist-escreve-e-cede, identidade-sem-plataforma, rollout-sem-pass, pagamento-sem-confirmacao, numero-sem-conciliacao, clausula-fora-da-postura, minuta-sem-pass)
> Os hooks canônicos vivem em `.claude/hooks/` (block-git-push, block-worktree, check-*-progress — story/social/proposal/finance/legal —, session-title). A antiga cópia `team-os-creator/hooks/` foi removida — fonte única.
```
---
## Comportamento em situações específicas
| Situação | Ação |
|---|---|
| Agente com nome existente | Oferecer: atualizar / pular / renomear / cancelar |
| Projeto destino sem `.claude/` | Criar estrutura mínima antes |
| `docs/smart-memory/` já existe no destino | Perguntar antes de sobrescrever no `*bootstrap` |
| `CLAUDE.md` já tem seção Smart-Memory | Não duplicar — verificar antes de injetar |
| Destino é o mesmo que a fonte (CT) | Bloquear com erro claro |
| `scan-ct-projects.sh` acha só CT | Oferecer digitar caminho manual |
| Agente já canônico no `*migrate` | `migrate-ntp.sh` conta como "já canônico" e não toca no arquivo |
| Usuário pede para instalar `team-os` no destino | Fazer — `team-os` é obrigatória nos projetos. Recusar APENAS `team-os-creator` (exclusiva do CT). |
| Pasta é uma Sala de Controle (nome, `sala-de-controle` ou `maestri-os` presente) | Perguntar o modo e instalar **só** a skill de Sala: `--squads none --extra-skills sala-de-controle` (padrão) ou `maestri-os`. Nunca squad, nunca `team-os` ali. |
| Não existe pasta isolada de Sala de Controle | Sugerir criar `<raiz>/1 \| Sala de Controle` (uma só para todos os negócios) e instalar a `sala-de-controle` lá — com OK. |
| Usuário pede skill de Sala (`sala-de-controle`/`maestri-os`) num projeto que tem squad | Recusar e explicar: a Sala de Controle é uma pasta própria, sem agentes — misturar quebra a regra "lê mas não executa". Oferecer criar a pasta. |
| Usuário pede as duas skills de Sala na mesma pasta | Recusar: um modo por pasta (achado `SALA_DUPLA`). Se quer os dois, são duas pastas. |
| Usuário pede squad `pm` (ou outra) numa Sala de Controle | Recusar: Sala de Controle não tem agentes por design. Se quer gestão de projetos, é outro projeto/pasta. |