---
name: provider-compatibility
description: Garantir que artefatos, skills, comandos e complementos SDD funcionem com qualquer provider/modelo e qualquer client/harness. Use ao criar ou revisar skills, design flow, automações, prompts, comandos, integrações ou outputs que não podem depender de Codex, Claude, Gemini, OpenAI, opencode, tool calling, browser ou MCP específicos.
---

# Provider Compatibility SDD

## Objetivo

Manter a camada SDD portável. O contrato principal deve funcionar com qualquer provider configurado em `sdd.config.yaml`, inclusive OpenAI-compatible, Anthropic, Google, local CLI, offline e futuros providers.

## Regra central

Provider não é client. Provider/modelo gera raciocínio; client/harness executa ferramentas. Escreva skills para o contrato comum: Markdown, arquivos, comandos `sdd`, artifact store, validação e evidência.

Provider-neutral não significa ASCII-only. Artefatos Markdown em PT-BR devem preservar UTF-8, acentuação e diacríticos no texto humano gerado. Normalize para ASCII apenas quando o destino técnico exigir slug, path, branch, identificador, variável de ambiente, comando, schema, campo de API ou contrato externo literal.

## Contrato mínimo

Toda solução nova deve funcionar quando o provider tem apenas:

- Leitura de instruções em Markdown.
- Capacidade de produzir texto estruturado.
- Acesso indireto ao CLI `sdd` pelo harness, quando disponível.
- Persistência via arquivo local ou link externo canônico.

Capacidades opcionais devem ter fallback:

| Capacidade | Se existir | Fallback provider-neutral |
|---|---|---|
| Tool calling | executar comando/leitura diretamente | pedir ao harness executar ou registrar comando necessário |
| Browser/screenshot | capturar evidência visual | solicitar screenshot/anexo ou usar transcript/log |
| Subagents | paralelizar pareceres | rodar checklist sequencial no agente atual |
| MCP/API externa | ler/escrever sistema canônico | usar artifact store local e ponteiros |
| Modelo com visão | analisar imagem diretamente | registrar achados com base em descrição ou pedir evidência textual |
| Contexto longo | carregar artefatos grandes | resumir e referenciar arquivos por caminho |

## Ao escrever skills

- Não nomeie provider específico como requisito.
- Não dependa de `allowed-tools`, `model`, MCP, browser ou subagent para o comportamento essencial.
- Diga "se disponível" para capacidades avançadas e sempre ofereça alternativa.
- Use `sdd providers list` e `sdd providers doctor` quando precisar diagnosticar configuração.
- Cite `Provider resolvido`, `Modelo resolvido` e `Offline` quando o CLI já fornecer essa informação.
- Preserve outputs como Markdown validável por `sdd validate-artifact`.
- Preserve acentuação PT-BR em conteúdo humano mesmo quando o provider ou client preferir saídas ASCII por padrão.

## Prompts agent provider-neutral

Cada task deve conter um prompt standalone que funcione para qualquer LLM/client. O prompt não pode depender de memória da conversa, ferramenta exclusiva, browser, MCP, subagent ou sintaxe de um provider específico.

Inclua sempre:

- Papel: agente de código executando uma task SDD isolada.
- Origem: caminhos do PRD, Tech Spec, Tasks, diagramas e artifacts relevantes.
- Objetivo verificável: resultado esperado em uma frase.
- Escopo: o que alterar e o que não alterar.
- Contexto mínimo: regras de negócio, contratos, estados, dados e decisões necessárias para executar sem perguntar de novo.
- Arquivos prováveis: caminhos esperados e limites de ownership.
- Restrições: preservar mudanças locais, não reverter trabalho externo, não ampliar escopo, não remover acentos de conteúdo humano.
- Passos sugeridos: inspeção, implementação, testes e registro de evidência.
- Validação: comandos ou checks esperados; quando não forem conhecidos, pedir ao executor para descobrir comandos no projeto antes de rodar.
- Saída final: relatório Markdown curto com resumo, arquivos alterados, comandos, evidências, decisões, riscos e pendências.

Use linguagem imperativa e portátil: "inspecione", "altere", "rode", "registre". Evite "use a tool X" como requisito; escreva "se o harness permitir, execute o comando; caso contrário, registre o comando necessário".

## Saída recomendada

```md
## Compatibilidade de provider
- Provider/modelo exigido: nenhum | <motivo>
- Capacidades opcionais usadas:
- Fallback quando ausente:
- Evidência persistida:
- Risco residual:
```

## Regras

- Não aprove solução que só funciona em um provider se o requisito é portabilidade.
- Não transforme limitação de provider em bloqueio sem propor fallback.
- Não use comportamento não determinístico do modelo como fonte de verdade; persista artefato e evidência.
- Não confunda "plugin Codex" ou "Claude command" com contrato SDD. Esses são pacotes de distribuição, não o núcleo da solução.
