teqo-backup/docs/plans/ops113-agentes-designer-e-designer-degraded.md

OPS113 — Agentes designer e designer-degraded: design hi-fi como fonte de verdade

Status: rascunho Atualizado em: 2026-09-15 Issue: #1056 Priority: P2 Impeccable: A — N/A sem UI de produto Rascunho UI: N/A — sem UI Appetite: ~0,5–1 dia eng; um outcome verificável Responsável: —

Intenção

O gate do plan-issue produz hoje um rascunho visual que, por doutrina, é proibido de ter brand, tokens e polish — e é descartável. A decisão visual em alta fidelidade não existe em lugar nenhum: ela é reinventada na implementação, sem referência para o humano aprovar antes e sem alvo estável para portar e criticar depois. O fim é previsível: a tela construída diverge do que foi aprovado e a crítica vira opinião.

Este item cria o papel de designer — especialista de julgamento visual que cria o design hi-fi de referência e critica a implementação contra o design aprovado — e eleva o artefato docs/plans/<slug>-ui-design.html a fonte de verdade do port: o implementador porta classe-a-classe para React/Next. Em paralelo, um designer degradado cobre quota/indisponibilidade do modelo frontier sem pular design em silêncio — mas nunca certifica.

Não é o retorno do design-vision (removido na OPS105): não é um describer de imagem, é design de criação/crítica com visão nativa. E não é entrega de UI de produto: nenhuma tela muda aqui.

Persona e fluxo

• Persona / contexto: fsolla no gate, abrindo o .html no browser para aprovar o design antes de qualquer código; agente implementador (work-issue/agent-work-issue) portando para React/Next.
• Job principal: ver e aprovar o design final hi-fi antes da implementação e, depois, portar e verificar paridade sem perder fidelidade.
• Fluxo desejado:
  1. Item com UI entra no plan-issue; o designer cria o artefato hi-fi (tokens reais, brand, copy pt-BR real).
  2. Humano abre o .html, itera com o designer e aprova; o artefato entra no PR do plano.
  3. Na implementação, o executor porta classe-a-classe do artefato.
  4. O designer critica a implementação contra o design aprovado; mudança material volta ao humano no PR.
  5. Se o frontier falhar, o ladder desce explicitamente e registra o tier; tier degradado marca DEGRADED e não certifica.
• Anti-goals de produto: não muda UI de produto; não é implementação disfarçada; não é um segundo Figma/Penpot nem substitui o MCP penpot; não ressuscita o describer de imagem da OPS105; o designer nunca escreve em src/; tier degradado nunca certifica; sem OpenRouter/Grok/Qwen no caminho de design.

Objetivo e aceite

• designer existe e é invocável (mode: all, temperature: 0.7, model: openai/gpt-5.6-sol) com os dois modos de tarefa — Criar hi-fi e Criticar implementação — e sem permissão de escrita em src/.
• designer-degraded existe e é invocável (mode: subagent, model: opencode-go/deepseek-v4.1-flash): cria/estende/critica, marca todo output DEGRADED e exige sign-off humano.
• A doutrina viva é ui-design-html.md (renomeada de ui-draft-html.md) e trata o artefato como fonte de verdade do port; tokens/brand/shadcn passam a ser esperados; o teto protetivo permanece.
• O ladder gpt-5.6-sol → gpt-6-astra → deepseek-v4.1-flash (DEGRADED) → deepseek-flash (DEGRADED, inline) está documentado e auditável: quota/indisponível desce explicitamente e registra o tier no PR — nunca pula design em silêncio.
• Pré-requisito operacional verificado antes de pinar: provider openai religado, auth feito, ids confirmados em opencode models | grep '^openai/' e visão funcionando no caminho OAuth.
• Artefato imutável como registro histórico no git; mutável durante o work-issue pelo designer, com mudança material voltando ao humano no PR.

Dados (intenção)

• Vou apresentar dados? Não — autoria de agente e doutrina de design; sem métrica ou superfície de dados.
• Decisões desbloqueadas: N/A.
• Forma: N/A.

Dados da decisão (literais)

• N/A — sem dados de produto. Os literais fixados nesta entrega são de configuração de agente/doutrina e estão verbatim em "Escopo e entregáveis" (modelos, modos, temperatura, caminhos e nomes) — não são decisão de dados.

Escopo e entregáveis (literais)

• Doutrina — rename + reescrita: .agents/skills/plan-issue/ui-draft-html.md → .agents/skills/plan-issue/ui-design-html.md. Eleva: tokens reais/brand/shadcn OK e esperados; o HTML é fonte de verdade do port (não mais descartável). Mantém: zero JS de comportamento; estados como cenas estáticas; 390/1280; copy pt-BR real; sem imports de src/; sem decisão de engenharia; claims só os aprovados no plano; NEEDS ASSET; LGPD/TSE; um CTA primário.
• Artefato: docs/plans/<slug>-ui-design.html (autossuficiente, Tailwind v4 browser CDN) + docs/plans/<slug>-ui-design-assets/*.svg quando ícones/ilustrações próprios forem necessários.
• SVG: lucide/shadcn primeiro; custom só quando não houver equivalente; grid 24px, currentColor, stroke no padrão lucide; salvar em -ui-design-assets/.
• designer: .opencode/agent/designer.md — mode: all, temperature: 0.7, model: openai/gpt-5.6-sol; visão nativa, com parada fail-closed se o modelo não enxergar (nunca descrever o que não viu).
• designer-degraded: .opencode/agent/designer-degraded.md — mode: subagent, model: opencode-go/deepseek-v4.1-flash; nunca certifica.
• Ladder: openai/gpt-5.6-sol → openai/gpt-6-astra (mesmo pool Plus; crítica contestada/pixel-critical) → opencode-go/deepseek-v4.1-flash (flat; DEGRADED) → deepseek/deepseek-flash (direto; DEGRADED; o orquestrador faz inline).
• Pré-requisito operacional (fora do repo): remover openai de disabled_providers no config global, opencode auth login openai, confirmar os ids expostos antes de pinar e confirmar imagem/visão no caminho OAuth. Verificado em 2026-09-15: provider religado + OAuth conectado; openai/gpt-5.6-sol e openai/gpt-6-astra expostos (15 ids no total); smoke de visão OK (PNG sólido lido corretamente pelo Sol).
• Doc operacional (opcional, 1 parágrafo): docs/AGENT-OPS.md — autoria/pin/fallback de agente, apontando para a doutrina.

Direção no codebase (hipótese)

• Áreas prováveis: .agents/skills/plan-issue/ (doutrina), .opencode/agent/ (novos agentes), docs/plans/ (artefatos), docs/AGENT-OPS.md (opcional).
• Precedente a olhar: .opencode/agent/designer-campanha-solla.md (frontmatter mode/temperature e bloco de visão nativa/fail-closed, L63–65); OPS105 (o que não ressuscitar); OPS101 (proibição de model: vale para .opencode/commands/, não para agentes).
• Risco de acoplamento: OPS114 consome o nome novo da doutrina e OPS115 os triggers no work-issue; nenhum teste/guard lê .opencode/agent/*.md hoje — o pin é contrato de prompt, não de teste.

Dependências

• Nenhuma dura. OPS114 (atualiza consumidores do nome antigo) vem depois deste rename; OPS115 (triggers no work-issue) consome o contrato daqui — ambos fora de escopo.

Fora de escopo

• Atualizar consumidores de ui-draft-html.md (template, SKILL.md, outras skills) → OPS114.
• Triggers/não-triggers de quando o designer entra no work-issue → OPS115.
• Arquivo de escalada designer-astra → pergunta aberta.
• Qualquer mudança em UI de produto ou src/, mudança no MCP penpot, e guard/teste novo lendo .opencode/agent/*.md.

Rabbit holes de produto

• "Já que existe designer, redesenha o produto inteiro." Se alguém "só completar": novo shell, paleta global, telas fora do item. Corte neste item: um artefato por item de UI, do escopo do item.
• "Deixa o designer editar src/ e já entregar a tela." Se alguém "só completar": o artefato vira implementação e o gate perde a função. Corte neste item: output só em docs/plans/<slug>-ui-design.*.
• "Cria designer-astra.md por simetria." Se alguém "só completar": prompt gêmeo, drift garantido. Corte neste item: pergunta aberta abaixo, com recomendação de não criar arquivo extra.

Questões em aberto (produto)

• designer-astra (openai/gpt-6-astra): arquivo extra ou só troca via /models? Opções: A) arquivo .opencode/agent/designer-astra.md gêmeo | B) um só designer.md, com troca de modelo via /models quando a crítica for contestada/pixel-critical | C) partial compartilhado + dois arquivos. Recomendação: B — evita twin/drift (AGENTS.md: "Edit the owner, don't twin") e o tier fica registrado no PR; reavaliar com evidência só se precisar de frontmatter distinto. (assumido — validar no gate)
• Documentar autoria/pin/fallback de agente em docs/AGENT-OPS.md? Opções: A) sim, 1 parágrafo curto linkando a doutrina | B) deixar só na doutrina | C) item futuro. Recomendação: A — o doc é o ponto de entrada da operação de agentes; sem isso o ladder fica enterrado na skill. (assumido)

Fases (ordem de entrega)

1. F1 — Doutrina: rename + reescrita de ui-design-html.md (contrato elevado, teto mantido, regras de SVG e o ladder). Consumidores do nome antigo ficam para OPS114.
2. F2 — Agentes: criar designer e designer-degraded com frontmatter pinado, modos Criar/Criticar, proibição de escrita em src/, rótulo DEGRADED e sign-off humano.
3. F3 — Operacional e verificação: pré-requisito (provider/auth/ids/visão), smoke dos dois agentes, formatação e o parágrafo opcional em docs/AGENT-OPS.md.

Verificação

• opencode models | grep '^openai/' lista openai/gpt-5.6-sol (e o id de escalada, se exposto) antes do pin; opencode-go/deepseek-v4.1-flash já é o modelo em uso. Se o id fixado não existir: parar e escalar o humano — não pinar adivinhação nem trocar de modelo em silêncio.
• Os dois agentes carregam na sessão; o designer cria um artefato de exemplo e o diff só toca docs/plans/ (nada em src/).
• O designer-degraded rotula DEGRADED no output e recusa certificar sem sign-off.
• Busca pelo nome antigo (ui-draft-html) não encontra referências nos arquivos desta entrega; consumidores restantes são dívida declarada do OPS114.
• pnpm exec prettier --check nos arquivos tocados (.opencode/ não está no .prettierignore); o artefato de exemplo abre no browser via Tailwind CDN.

Riscos

• Pinar id não exposto pelo OAuth. O openai está hoje em disabled_providers; pinar antes da verificação quebra o agente em silêncio. Mitigação: pré-requisito primeiro; fail-closed e escalada se o id não existir.
• Certificação degradada por atalho. PR que trata DEGRADED como design aprovado. Mitigação: rótulo obrigatório + sign-off humano + tier registrado no PR.
• Teto protetivo relaxado demais. Com brand/tokens permitidos, o artefato tenta virar implementação (JS, estado, decisões). Mitigação: a doutrina mantém o teto explícito e a proibição de src/.
• Drift entre os dois prompts. designer e designer-degraded duplicam regras e divergem. Mitigação: doutrina como fonte única; prompts apontam para ela, não a copiam.
• Referências quebradas ao nome antigo entre F1 e OPS114. Dívida declarada; este item não edita consumidores (template, SKILL.md, etc.).

Referências

• GitHub Issue #OPS113 (a registrar; placeholder)
• .agents/skills/plan-issue/ui-draft-html.md — doutrina atual, a renomear; intention-template.md/SKILL.md — consumidores (OPS114)
• .opencode/agent/designer-campanha-solla.md — precedente de frontmatter e visão nativa/fail-closed (L63–65)
• docs/changelog/2026-09-14-ops105.md — design-vision removido; não ressuscitar
• tests/unit/opencodeCommands.unit.spec.ts (41–44) — proibição de model: em comandos não cobre agentes
• ~/.config/opencode/opencode.jsonc — config global (fora do repo); hoje openai em disabled_providers
• docs/AGENT-OPS.md; AGENTS.md ("Edit the owner, don't twin")