docs(workspace): WürthFlow — arquitetura do workspace + fluxo de projetos + stack padrao

Adicionado documento vivo com: - Estrutura completa do workspace - Filosofia anti-fragil e circuito breaker - Fluxo de desenvolvimento: types → utils → validators → hooks → components - Convencao de commits semantica - Stack padrao por tipo de projeto (biblioteca/node/app/backend/fullstack) - Checklist pré-deploy Arquivos: - WürthFlow.md: fluxo completo ASCII + convencoes - projetos/@pulse-libs/core/README.md atualizado com estrutura real 🤖 Pulse + nova-self-improver
2026-05-19 21:48:01 -03:00
parent 154e233d6d
commit 58e6b764c8
1 changed files with 197 additions and 0 deletions
@@ -0,0 +1,197 @@
+# 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
+```