📚 Os 6 Módulos da Trilha
Clique para pular direto a um módulo, ou role para ver os tópicos expansíveis.
Conteúdo Detalhado
🔌 BYOK Proxy & Multi-modelo
Trocar motor entre Claude Code, Codex, Ollama, MiMo, DeepSeek, OpenRouter, vLLM — sabendo trade-off de cada.
Endpoint do daemon: aceita {baseUrl, apiKey, model, messages} e faz pass-through SSE para qualquer endpoint OpenAI-compatible.
É o "atalho universal" para qualquer LLM que fale OpenAI chat. Sem mudança de código no OD.
SSE pass-through · OpenAI-compat · {baseUrl, apiKey, model, messages}
Bloqueio na borda do daemon: rejeita destinos loopback (127.x), link-local (169.254.x), RFC1918 (10.x, 172.16-31.x, 192.168.x).
Sem isso, baseUrl="http://internal-service" expõe rede interna. Defesa em profundidade.
SSRF · loopback · RFC1918 · edge guard
Padrão de fato: /v1/chat/completions com messages[] + role + content. Quase todo provider implementa.
Aprendendo um schema, você fala com 20+ providers. Não precisa de SDK por provider.
/v1/chat/completions · messages array · streaming · tool calls
KNOWN_PROVIDERS no config: presets com baseUrl + model default. Pasta um clique para popular.
Cada um tem trade-off: MiMo (custo no CN), DeepSeek (custo global), Groq (velocidade), OpenRouter (variedade).
KNOWN_PROVIDERS · presets · trade-off por provider
baseUrl=http://localhost:11434/v1. Modelo: qwen2.5-coder:32b > generalistas para HTML/CSS.
100% local, zero custo, dados sensíveis ok. Mas: hardware exigente (32B+ modelos).
localhost:11434 · qwen2.5-coder · privacidade · GPU exigente
MiMo tem schema de tools malcomportado em geração free-form. OD força tool_choice:'none' automaticamente.
Quirks de provider. Mostra que OD compensa por trás dos panos.
Provider quirks · tool_choice · free-form · auto-fix
CLI agent (Claude Code) tem skills locais. BYOK proxy não. Trade-off: custo vs capacidades.
Claude Code dá Read/Write/Bash REAIS. BYOK só tem chat. Decisão consciente.
CLI vs proxy · skills · capacidades · custo
🔗 Agent Client Protocol (ACP) & adapters
JSON-RPC stdio bidirecional ("LSP para coding agents"). 11 CLIs, 6 famílias de stream format. Como adicionar adapter novo.
JSON-RPC 2.0 sobre stdio, bidirecional simétrico. Editor e agente podem iniciar requests.
É o "LSP para coding agents". Vai virar padrão. Saber agora = adoção cedo.
JSON-RPC 2.0 · stdio · bidirecional · simétrico · LSP-like
Process isolation, language independence, sem porta, sem CORS, sem rede.
stdio é mais simples e mais seguro que HTTP local. Spawn-and-talk.
Process boundary · zero port · zero CORS · spawn
Taxonomia: claude-stream-json, copilot-stream-json, json-event-stream (Codex/Gemini/OpenCode/Cursor), acp-json-rpc (Hermes/Kimi/Kiro), pi-rpc, plain (Qwen).
Saber qual fala qual protocolo te ajuda a debugar quando um para de funcionar.
6 stream formats · 11 CLIs · per-CLI parser
PATH scan no boot do daemon. Cada bin encontrado vira candidato. Available/unavailable.
Sem config. Plug-and-play. Adicione binary ao PATH e aparece no picker.
PATH scan · which · zero config · auto-detection
Cada CLI tem argv builder próprio. Windows ENAMETOOLONG fallback: prompt via stdin ou file.
Prompts compostos passam de 32KB no Windows. Argv não aguenta. Stdin sim.
argv builder · ENAMETOOLONG · stdin fallback · 32KB limit
Array em apps/daemon/src/agents.ts com {id, bin, streamFormat, eventParser, models, ...}.
Single source of truth. Editar = adicionar/modificar CLI suportada.
AGENT_DEFS · descritor · streamFormat enum
Uma entrada em AGENT_DEFS + um eventParser (se streamFormat=json-event-stream).
Você pode plugar CLI custom em ~30min. PR de upstream relativamente simples.
+1 entry · eventParser fn · upstream PR pattern
🎨 Brand-Spec Extraction Avançada
Extrair sistema visual de URL/screenshot do cliente sem inventar cores. Protocolo 5 passos.
LLM "tem na memória" cores aproximadas. Pede laranja Stripe, vem qualquer laranja.
É a fonte #1 de output que parece "quase certo mas não". Cores aproximadas matam credibilidade.
Hallucinated colors · approximation · brand mismatch
Locate · Download · grep hex · Codify · Vocalise. Protocolo determinístico.
Cada passo elimina uma fonte de erro. Não inventar = chave do output bom.
5 passos · determinístico · evidence-based
Convencionalmente marcas têm /brand, /press ou /about com brand assets.
Saber onde procurar antes de scrap aleatório.
/brand /press /about · convenções · WebFetch
Qualquer artefato disponível: CSS público, PDF brand guide, screenshots.
Quanto mais artefato, mais robusta a extração. Diversificar fontes.
CSS público · PDF guides · screenshots · multi-source
Regex captura todos hex codes. Ordena por frequência. Top 6 = probable palette.
Extração mecânica. Zero alucinação. Reproduzível.
Regex hex · sort by freq · top 6 · mecânico
Escrever brand-spec.md no projeto: 6 tokens OKLch + 3 font stacks + 3-5 posture rules.
Formato canônico. Próximas sessões herdam. Versionável.
brand-spec.md · 6 tokens · OKLch · 3 font stacks · 3-5 rules
"warm cream background, single rust accent at oklch(58% 0.15 35), Newsreader display + system body".
Usuário pode redirecionar barato. "Não, queria mais frio." Antes de gerar 5 telas.
One-sentence summary · cheap redirect · pre-build check
Conversão direta perde nuance. Preservar L (lightness percebida) mantém WCAG.
Dark mode automático fica predictível. Não precisa eyeball ajuste.
L preservation · WCAG predictable · dark mode auto
🔄 Critique 5-dim como Loop
Crítica não como ferramenta avulsa, mas como gate pre-emit em todo turn. Auto-crítica integrada.
skills/critique/ = relatório HTML rich. Crítica embutida em discovery.ts = silent gate.
Duas modalidades para dois usos: deep audit vs continuous quality.
Manual skill · embedded gate · 2 modalidades
Philosophy · Hierarchy · Execution · Specificity · Restraint. Cada uma com perguntas concretas.
Sem definição operacional, "execução boa" é vibes. Definição = score reproduzível.
5 dim · operacional · perguntas concretas · reproduzível
0-10 = relatório rico, granularidade fina. 1-5 = gate rápido, decisão binária.
Escolha de escala = escolha de granularidade. Cada uso pede uma.
Granularidade · 0-10 vs 1-5 · escolha consciente
Hard rule: qualquer dimensão abaixo de 3/5 = não emite, refaz. Re-score. 2 passes normais.
Gate explícito > "tente fazer melhor". Comportamento previsível.
Hard threshold · 3/5 · refaz · 2 passes
Esperado: 1º draft, 1ª crítica (encontra problema), fix, 2ª crítica (passa). Mais que 3 = brief errado.
Saber quando parar. Loop infinito = sintoma de problema upstream.
2 passes · diminishing returns · brief signal
Lint encontra problemas estruturais (artifact framing, missing assets). Findings alimentam crítica.
Crítica não é só "vibes" — é vibes + evidências de lint estrutural.
Lint findings · evidence-grounded · vibes + dados
references/checklist.md por skill define P0 customizados. Você pode adicionar "no rounded cards" como P0.
Skill especializada exige checklist especializada.
P0 customizado · per-skill checklist · barra por contexto
Specificity = "every word/number/image specific to THIS brief?" Slop = filler, generic. Blacklist captura.
Specificity é a dimensão mais difícil. Blacklist torna ela mais objetiva.
Specificity · blacklist · filler detection · objetiva
🛠️ Criando uma Skill Própria
Escrever skill end-to-end: SKILL.md + assets/template.html + references/{layouts,checklist}.md, instalar, agente usa.
Estender se a base é 80% certa. Criar nova se semantics diferentes (mobile vs desktop, deck vs prototype).
Evitar duplicação. Ecossistema mais limpo.
DRY · semantic boundary · 80% rule
<skill-name>/{SKILL.md, assets/, references/}. Convenção fixa.
Padrão = OD discovery automático. Sem padrão = skill invisível.
3 partes · convenção · auto-discovery
name (kebab-case, único), description (multi-line), triggers (multi-idioma), od:{...} extensions.
Cada campo tem efeito específico no UX do picker.
YAML frontmatter · campos obrigatórios · od: opcional
Tokens em :root + class system + comentários por seção. Seed bem opinionado.
Quanto mais opinionado o seed, mais consistente o output. Não tenha medo de ser específico.
:root tokens · class system · comentários por seção
Skeletons de seção/tela/slide que o agente cola e adapta. Não escreve do zero.
Paste-ready é o segredo da qualidade consistente. Agente improvisa menos.
Paste-ready · skeletons · classes esperadas
Lista P0/P1/P2 específica da skill. P0 são "faltou? não emite". P1 = fix antes de export. P2 = nice.
P0 errados = bloqueia agente. P0 certos = qualidade automática.
P0/P1/P2 · hard gate · pragmatismo
Prompt exemplo aparece no picker como tooltip. Ajuda usuário decidir se a skill é a certa.
UX: usuário não tem que abrir SKILL.md inteiro pra entender o que faz.
UX picker · tooltip · concrete example
~/.claude/skills/<nome>/ (global) ou ./skills/ (repo). Restart daemon: pnpm tools-dev stop && start.
Sem restart, picker não mostra skill nova.
Locais · restart · FS-watch (futuro)
PR pattern: skills/<sua-skill>/ + entry no skills/AGENTS.md (se houver). Apache-2.0.
Sua skill vira parte do produto. Outros se beneficiam. Bonifica reputação.
PR upstream · Apache-2.0 · ecossistema
⚙️ Daemon, Sidecar IPC & Multi-namespace
Engenharia do daemon. Operar múltiplos namespaces em paralelo. Debugar via inspect tools.
Subcommands: start/stop/run/status/logs/inspect/check. Lifecycle 100% via tools-dev.
Não tem pnpm dev. Não tem pnpm start. Tudo via tools-dev. Único caminho.
7 subcommands · single entrypoint · no pnpm dev
app · mode · namespace · ipc · source. Carregados em todo processo (daemon/web/desktop).
Process discovery sem heurística. ps aux + grep stamp = encontrou.
5 campos · process discovery · sem regex · type-safe
Unix socket em /tmp/open-design/ipc/<ns>/<app>.sock. JSON-RPC por cima.
Automação E2E sem framework próprio. tools-dev inspect desktop screenshot.
Unix socket · JSON-RPC · 6 commands · E2E sem harness
OD_DATA_DIR muda raiz dos dados. --namespace muda subdir dentro da raiz.
Permite rodar Playwright + dev + projetos reais sem colisão de SQLite.
env var · CLI flag · isolamento · sem colisão
Casos de uso reais: Playwright (testes), beta channel, projetos de cliente, experiments.
Sem namespaces, testes apagam projetos reais. Com, tudo coexiste.
Test isolation · beta channels · multi-client · safety
Tira screenshot do desktop Electron via IPC. Sem Playwright. Sem framework.
E2E desktop sem dependência pesada. Útil para CI.
SCREENSHOT command · sem Playwright · CI-ready
Renderer sandboxed. Descobre URL do web via IPC do daemon. Não adivinha porta.
Port discovery via IPC > scan de porta. Robusto a mudanças.
Sandboxed renderer · IPC discovery · sem port scan
3 packages com responsabilidade clara: proto (contrato OD), sidecar (runtime genérico), platform (OS primitives).
Separação genérico vs específico. Reusável fora do OD.
3 layers · genérico/específico · reuso
.tmp/tools-dev/<namespace>/logs/<app>/latest.log. JSON quando --json.
Debugging sério. Por namespace, por app, JSON parseable.
Log estruturado · per-namespace · JSON · latest.log
Comando que retorna logs em JSON. Pipe pra jq, grep estruturado.
Debug eficiente. jq '.message | select(. | contains("error"))'.
--json flag · jq pipe · structured grep