# WürthFlow — Arquitetura & Processo do Workspace

> Documento vivo. Atualizado em cada sessão do agente Pulse.

---

## 1. Estrutura do Workspace

```
/root/.openclaw/workspace/
├── projetos/              ← Projetos ativos
│   └── @pulse-libs/       ← Biblioteca universal (reutilizável por todos)
├── libs/                  ← Conhecimento extraído das skills (biblioteca interna)
├── skills/                ← 22 skills instaladas (25 MAI 2026)
├── .learnings/            ← Loop de auto-melhoria
│   ├── LEARNINGS.md       ← Padrões bem-sucedidos
│   ├── ERRORS.md          ← Falhas a evitar
│   ├── FEATURE_REQUESTS.md
│   └── PATTERN_COUNTER.md ← Padrão 3x → nova skill
├── memory/                ← Logs diários (YYYY-MM-DD.md)
├── AGENTS.md              ← Perfil do agente + regras
├── SOUL.md                ← Personalidade
├── TOOLS.md               ← Cheatsheets de ferramentas
├── MEMORY.md              ← Curadoria de longo prazo
├── SESSION-STATE.md       ← RAM da sessão atual
├── HEARTBEAT.md           ← Tarefas periódicas
└── USER.md                ← Perfil do usuário
```

---

## 2. Filosofia de Trabalho

### Stack do agente
```
Frontend   → browser, E2E, vision, TS, React, Vue
Backend    → sql-toolkit, redis, python-script-generator
DevOps     → xcloud-docker-deploy, security-audit, openclaw-config
Sistema    → Linux commands, file management, logs
IA         → nova-self-improver (loop contínuo)
```

### Regra de Circuit Breaker
```
memory_search()          → primário (sempre tentar primeiro)
  ↓ falhou / sem results
grep + read arquivos      → backup offline
  ↓ falhou
"sem resultados" + log    → sem quebrar o fluxo
```

### Anti-fragilidade
- Todo erro → `ERRORS.md` IMEDIATAMENTE
- Padrão 3x → `PATTERN_COUNTER` → nova skill
- Usuário corrigiu → `LEARNINGS.md` (categoria `correction`)
- Funcionou bem → `LEARNINGS.md` (categoria `best_practice`)

---

## 3. Fluxo de Desenvolvimento de Projetos

```
Nova demanda
    ↓
1. CRIAR projeto em projetos/<nome>/
2. COPIAR libs/ → docs/dev-standards/ do projeto
3. DEFINIR Docker multi-stack desde dia 1
4. IMPLEMENTAR em ordem: types → utils → validators → hooks → components → pages
5. TESTAR: npm test (obrigatório antes de commit)
6. BUILD: npm run build
7. GIT: git add + commit semântico + push
8. DOCKER: docker build + push registry
9. CI/CD: .github/workflows/ci.yml
10. LOGAR em .learnings/ (entradas do processo)
```

---

## 4. Convenção de Commits

```
<type>(<escopo>): <descrição>

# Tipos
feat     → nova funcionalidade
fix      → correção de bug
docs     → documentação
refactor → refatoração sem mudança de comportamento
test     → adiciona/corrige testes
chore    → manutenção (deps, lint, build)
style    → formatação, espaços, ponto e vírgula
perf     → otimização de desempenho
ci       → CI/CD, deploy, GitHub Actions
```

```
Exemplo: feat(lib-core): add useClipboard hook + Zod CPF/CNPJ schema
```

---

## 5. Workflow WürthFlow (Visual ASCII)

```
┌──────────────────────────────────────────────────┐
│           USER → AGENT (nova demanda)            │
└────────────────────────────────┬─────────────────┘
                                 ↓
┌─────────────────────────────────────────────────────┐
│ PLAN   update_plan() — 3-10 passos                  │
│ SCAN   memory_search() → AGENTS.md → TOOLS.md       │
│ ANALYZE git status / ls / df -h                     │
└─────────────────────────┬───────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ BUILD  Implementar em ordem: types → utils → ...    │
│ TEST   vitest run — falha bloqueia commit            │
│ BUILD  tsup/build — 0 erros antes de commitar        │
└─────────────────────────┬───────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ VALID  Git diff review + typecheck antes de commit   │
├─────────────────────────────────────────────────────┤
│ [Git] git add → conventional commit → push          │
│ [Docker] docker build → registry push               │
│ [CI]   .github/workflows/ci.yml roda automaticamente │
└─────────────────────────┬───────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│ REFLECT                                            │
│  ✓ O que funcionou?  → LEARNINGS.md                 │
│  ✓ O que falhou?     → ERRORS.md IMEDIATAMENTE      │
│  ✓ Padrão 3x ocorreu? → PATTERN_COUNTER → skill     │
│  ✓ Relevante para sempre? → MEMORY.md / AGENTS.md   │
└─────────────────────────────────────────────────────┘
```

---

## 6. Stack Padrão por Tipo de Projeto

### Biblioteca Node (packages)
| Item | Padrão |
|------|--------|
| Linguagem | TypeScript ≥5.3 |
| Build | tsup v8 (ESM + CJS + DTS) |
| Teste | vitest + jsdom |
| Lint | eslint strict + @typescript-eslint |
| Docker | node:20-alpine multi-stage |
| CI/CD | GitHub Actions: test → build → npm publish |

### App React/Next.js
| Item | Padrão |
|------|--------|
| Framework | Next.js 15 App Router |
| Estilização | Tailwind CSS + `cn()` |
| Validação | Zod schemas de `@pulse-libs/core` |
| DB | Prisma ou PostgreSQL direto com libs |
| Docker | multi-stage + nginx reverse proxy |

### Backend Node
| Item | Padrão |
|------|--------|
| Runtime | Node 20 LTS |
| API | Fastify ou Express |
| Auth | JWT ou OAuth2 |
| DB | PostgreSQL + Redis para cache |
| Monitor | prom-client + /metrics |
| Process | PM2 ou Docker native restart |

### Full Stack
| Item | Padrão |
|------|--------|
| Frontend | React + Tailwind + Zustand |
| Backend | Fastify + tRPC ou REST |
| DB | PostgreSQL (+Redis) |
| Auth | JWT + refresh token |
| Cache | Redis multi-layer |
| Queue | Bull / BullMQ |
| Container | Docker Compose (dev) → K8s (prod) |

---

## 7. Checklist Pré-Deploy

```
[ ] npm test            → 0 falhas
[ ] npm run typecheck   → 0 erros TS
[ ] npm run build       → 0 erros, dist/ gerado
[ ] git diff review     → sem código sensível
[ ] Docker build OK     → image menor que limite
[ ] .env.example atualizado
[ ] README.md atualizado
[ ] CHANGELOG.md atualizado
[ ] Sem secrets hardcoded
[ ] CI/CD verde
```