RFC-002: Reorganização Arquitetural APEX Multi-BU¶

Status: ✅ Implementado (Fases 1-6 completas) Autor: Claude + Founder Data: 2026-01-18 Impacto: Alto (reestruturação de pastas)

Resumo Executivo¶

A arquitetura atual do APEX tem duplicação significativa entre core/ e sellsync/.claude/. Esta RFC propõe reorganizar para: - Centralizar componentes compartilhados em core/ - Manter apenas dados BU-específicos em cada tenant - Permitir que ArcosScale (e futuras BUs) usem a infraestrutura existente

Problema¶

Duplicação Atual¶

DUPLICADO: sellsync/.claude/agents/ replica core/agents/
DUPLICADO: sellsync/.claude/agents/GOVERNANCE.md replica core/governance/GOVERNANCE.md
DUPLICADO: sellsync/.claude/agents/ORCHESTRATOR.md replica core/governance/ORCHESTRATOR.md
DUPLICADO: sellsync/.claude/agents/ACTIVATION-MATRIX.md replica core/governance/ACTIVATION-MATRIX.md
... e mais 8 arquivos duplicados

Componentes Órfãos¶

ÓRFÃO: sellsync/.claude/hooks/ → Deveria ser compartilhado
ÓRFÃO: sellsync/.claude/skills/ → Deveria ser compartilhado
AUSENTE: arcosscale/.claude/ → Não existe, deveria usar core/
AUSENTE: arcosscale/DOCS/operations/learnings/ → Estrutura faltando

Arquitetura Proposta¶

Estrutura Final¶

apex/
├── CLAUDE.md                           ← Contexto raiz (já existe)
│
├── core/                               ← COMPARTILHADO
│   ├── agents/                         ← ✅ Manter (40 agentes)
│   ├── governance/                     ← ✅ Manter (regras)
│   ├── hooks/                          ← 🆕 CRIAR (mover de sellsync)
│   │   ├── README.md
│   │   ├── HOOKS-ARCHITECTURE.md
│   │   ├── 01-pre-session.md
│   │   ├── 02-pre-decision.md
│   │   ├── 03-pre-edit.md
│   │   ├── 04-post-edit.md
│   │   ├── 05-emergency.md
│   │   ├── 06-checkpoint.md
│   │   └── 07-post-edit-learning.md
│   ├── skills/                         ← 🆕 CRIAR (mover de sellsync)
│   │   ├── checkpoint.md
│   │   ├── classify.md
│   │   ├── hypothesis.md
│   │   ├── metrics.md
│   │   └── validate.md
│   ├── templates/                      ← 🆕 CRIAR
│   │   └── bu-docs/
│   │       ├── learnings/
│   │       │   └── hypotheses.md.template
│   │       ├── checkpoints/
│   │       │   └── WEEKLY_TEMPLATE.md
│   │       └── metrics/
│   │           └── WEEKLY_METRICS.md.template
│   ├── tests/                          ← ✅ Manter
│   └── tools/                          ← ✅ Manter
│
├── sellsync/                           ← BU-ESPECÍFICO
│   ├── CLAUDE.md                       ← ✅ Manter (contexto único)
│   ├── DOCS/                           ← ✅ Manter estrutura
│   │   ├── strategy/
│   │   ├── product/                    ← Específico SaaS
│   │   ├── engineering/                ← Específico SaaS
│   │   ├── operations/
│   │   │   ├── learnings/              ← HYPs SellSync
│   │   │   ├── checkpoints/            ← Checkpoints SellSync
│   │   │   ├── metrics/
│   │   │   ├── memory/
│   │   │   ├── reports/
│   │   │   └── runbooks/
│   │   ├── finance/
│   │   └── legal/
│   └── .claude/                        ← 🔄 REESTRUTURAR
│       └── overrides/                  ← Apenas customizações
│           └── (vazio por enquanto)
│
├── arcosscale/                         ← BU-ESPECÍFICO
│   ├── CLAUDE.md                       ← 🔄 EXPANDIR
│   ├── CONTEXT.md                      ← ✅ Manter
│   ├── DOCS/                           ← 🔄 EXPANDIR
│   │   ├── strategy/                   ← ✅ Existe
│   │   ├── operations/                 ← 🔄 EXPANDIR
│   │   │   ├── learnings/              ← 🆕 CRIAR
│   │   │   │   └── hypotheses.md
│   │   │   ├── checkpoints/            ← 🆕 CRIAR
│   │   │   ├── metrics/                ← 🆕 CRIAR
│   │   │   ├── ESTRUTURA_ORGANIZACIONAL.md
│   │   │   ├── AGENDA_EXECUTIVO.../
│   │   │   └── sla.md
│   │   ├── finance/                    ← ✅ Existe
│   │   └── legal/                      ← 🆕 CRIAR
│   ├── metrics/                        ← ✅ Manter (thresholds)
│   └── .claude/                        ← 🆕 CRIAR
│       └── overrides/                  ← Customizações B2B
│
└── shared/                             ← ✅ Manter
    └── mcp-server/

Plano de Execução¶

Fase 1: Preparação (Sem Risco)¶

Objetivo: Criar estrutura em core/ sem modificar nada existente

#	Ação	Comando/Descrição
1.1	Criar `core/hooks/`	`mkdir -p core/hooks`
1.2	Criar `core/skills/`	`mkdir -p core/skills`
1.3	Criar `core/templates/bu-docs/`	`mkdir -p core/templates/bu-docs/{learnings,checkpoints,metrics}`

Fase 2: Migração de Hooks e Skills¶

Objetivo: Copiar (não mover ainda) hooks/skills para core/

#	Ação	De	Para
2.1	Copiar hooks	`sellsync/.claude/hooks/*.md`	`core/hooks/`
2.2	Copiar skills	`sellsync/.claude/skills/*.md`	`core/skills/`
2.3	Adaptar skills	Remover referências hardcoded a "sellsync"	Usar `{tenant}` ou param

Fase 3: Estrutura ArcosScale¶

Objetivo: Criar estrutura faltante em arcosscale/

#	Ação	Descrição
3.1	Criar learnings	`arcosscale/DOCS/operations/learnings/hypotheses.md`
3.2	Criar checkpoints	`arcosscale/DOCS/operations/checkpoints/`
3.3	Criar metrics	`arcosscale/DOCS/operations/metrics/`
3.4	Criar legal	`arcosscale/DOCS/legal/`
3.5	Criar .claude/overrides	`arcosscale/.claude/overrides/`
3.6	Expandir CLAUDE.md	Adicionar seções faltantes

Fase 4: Limpeza SellSync (Com Cuidado)¶

Objetivo: Remover duplicatas após validar que core/ funciona

#	Ação	Descrição	Risco
4.1	Remover agents duplicados	`sellsync/.claude/agents/*.md` (exceto overrides)	Médio
4.2	Remover governance duplicada	`sellsync/.claude/agents/{GOVERNANCE,ORCHESTRATOR,...}.md`	Médio
4.3	Remover hooks originais	`sellsync/.claude/hooks/` → usar `core/hooks/`	Baixo
4.4	Remover skills originais	`sellsync/.claude/skills/` → usar `core/skills/`	Baixo
4.5	Criar symlinks ou referências	Apontar para core/	-

Fase 5: Atualização de Referências¶

Objetivo: Garantir que CLAUDE.md aponte para locais corretos

#	Ação	Arquivo
5.1	Atualizar APEX CLAUDE.md	`/apex/CLAUDE.md` - documentar nova estrutura
5.2	Atualizar SellSync CLAUDE.md	Referenciar `core/hooks`, `core/skills`
5.3	Atualizar ArcosScale CLAUDE.md	Referenciar `core/hooks`, `core/skills`

Fase 6: Limpeza de Métricas ArcosScale¶

Objetivo: Remover métricas de teste do SSoT

#	Ação	Métrica
6.1	Remover test_metric_new	`apexDeleteMetric` ou SQL direto
6.2	Remover test_debug	idem
6.3	Remover test_approval	idem
6.4	Remover cac_test	idem
6.5	Corrigir inconsistências	Alinhar CLAUDE.md com SSoT real

Detalhamento das Mudanças¶

Hooks a Mover para core/hooks/¶

Arquivo	Descrição	Mudanças Necessárias
`01-pre-session.md`	Carrega contexto	Nenhuma (genérico)
`02-pre-decision.md`	Valida decisões	Nenhuma (genérico)
`03-pre-edit.md`	Guarda antes de editar	Nenhuma (genérico)
`04-post-edit.md`	Verifica após editar	Nenhuma (genérico)
`05-emergency.md`	Detecta burnout/stress	Nenhuma (genérico)
`06-checkpoint.md`	Checkpoint semanal	Parametrizar tenant
`07-post-edit-learning.md`	Registra HYPs	Nenhuma (genérico)
`HOOKS-ARCHITECTURE.md`	Documentação	Atualizar paths
`README.md`	Documentação	Atualizar paths

Skills a Mover para core/skills/¶

Arquivo	Descrição	Mudanças Necessárias
`checkpoint.md`	/checkpoint	Remover "SellSync" hardcoded
`classify.md`	/classify	Nenhuma (usa tenant param)
`hypothesis.md`	/hypothesis	Parametrizar path do hypotheses.md
`metrics.md`	/metrics	Nenhuma (usa tenant param)
`validate.md`	/validate	Nenhuma (genérico)

Arquivos a REMOVER de sellsync/.claude/agents/¶

# Duplicados com core/agents/ (REMOVER)
00-zero-ceo-orchestrator.md    → usar core/agents/ceo-zero.md
01-catarina-category-designer.md → usar core/agents/category-designer.md
... (todos os 30+ agentes duplicados)

# Duplicados com core/governance/ (REMOVER)
GOVERNANCE.md                  → usar core/governance/GOVERNANCE.md
ORCHESTRATOR.md               → usar core/governance/ORCHESTRATOR.md
ACTIVATION-MATRIX.md          → usar core/governance/ACTIVATION-MATRIX.md
AGENT-INTERFACES.md           → usar core/governance/AGENT-INTERFACES.md
DEPENDENCY-MAP.md             → usar core/governance/DEPENDENCY-MAP.md
LEARNING-SYSTEM.md            → usar core/governance/LEARNING-SYSTEM.md
MEMORY-SYSTEM.md              → usar core/governance/MEMORY-SYSTEM.md
PROTOCOLS.md                  → usar core/governance/PROTOCOLS.md
REASONING-FRAMEWORK.md        → usar core/governance/REASONING-FRAMEWORK.md
WORKFLOWS.md                  → usar core/governance/WORKFLOWS.md
USAGE-LOG.md                  → usar core/governance/USAGE-LOG.md

Conteúdo dos Novos Arquivos¶

arcosscale/DOCS/operations/learnings/hypotheses.md¶

# Hypotheses Log - ArcosScale

> Registro de hipóteses e aprendizados da BU ArcosScale.
> Última atualização: 2026-01-18

---

## Hipóteses Pendentes

| ID | Hipótese | Método de Validação | Critério de Sucesso | Status |
|----|----------|---------------------|---------------------|--------|
| HYP-A001 | (template) | - | - | ⏳ Pending |

---

## Hipóteses Validadas

(nenhuma ainda)

---

## Hipóteses Invalidadas

(nenhuma ainda)

---

## Como Usar

1. Novas hipóteses: Adicionar na seção "Pendentes"
2. Ao validar: Mover para "Validadas" com evidência
3. Ao invalidar: Mover para "Invalidadas" com motivo
4. IDs: Usar prefixo HYP-A (A = ArcosScale)

Riscos e Mitigações¶

Risco	Probabilidade	Impacto	Mitigação
Quebrar referências	Média	Alto	Fase 2 copia antes de mover
Claude não achar hooks	Baixa	Médio	Atualizar CLAUDE.md antes
Perder histórico git	Baixa	Baixo	Usar `git mv` quando possível
Confusão durante transição	Média	Baixo	Executar em uma sessão só

Checklist de Aprovação¶

EXECUTADO EM 2026-01-18:

[x] Concordo com a nova estrutura proposta ✅
[x] Concordo em remover duplicatas de sellsync/.claude/agents/ ✅ (49 arquivos removidos)
[x] Concordo em mover hooks/skills para core/ ✅ (9 hooks + 5 skills)
[x] Concordo em limpar métricas de teste do ArcosScale ✅ (5 métricas removidas via REST API)
[x] Entendo que será uma mudança significativa ✅ (55.722 linhas removidas)

Cronograma Sugerido¶

Fase	Descrição	Estimativa
1	Preparação (criar pastas)	2 min
2	Migração hooks/skills	5 min
3	Estrutura ArcosScale	5 min
4	Limpeza SellSync	10 min
5	Atualização referências	10 min
6	Limpeza métricas	5 min
Total		~37 min

Resultado Esperado¶

Após execução:

core/ será a única fonte de verdade para componentes compartilhados
sellsync/ e arcosscale/ terão apenas dados BU-específicos
Novas BUs poderão ser criadas copiando estrutura de DOCS/ + CLAUDE.md
Zero duplicação de agentes, hooks, skills, governance
ArcosScale terá paridade estrutural com SellSync

Aguardando aprovação do founder para execução.