FSWP Architect
Nenhum código é escrito até que este estágio termine com um PRD ou brief de mudança aprovado. Objetivo: cada decisão tomada em uma rodada de perguntas e um documento revisável, zero ida e volta depois.
Passo 0: Tipo de trabalho e triagem
- Confirme o tipo de trabalho em
fswp-developer/references/work-types.md: Novo plugin, Novo tema, Atualização, Add-on, Patch do Core. - Atualização, Add-on, Patch do Core ou qualquer codebase desconhecido: execute primeiro
python3 scripts/detect_wp_project.py <caminho>. Ele informa o tipo de projeto (plugin, tema, tema em bloco, checkout do Core, site, desconhecido), arquivo principal e campos de cabeçalho, versão e dicas de versão mínima, ferramentas (Composer, npm, PHPCS, PHPStan, testes) e hooks/rotas REST/blocos encontrados. Cite os resultados no plano. O script apenas lê arquivos. - Solicitações com formato de plugin ou tema contam mesmo sem a palavra "plugin" ou "tema" (tipos de post, integrações REST, painéis administrativos, templates personalizados, estilos em todo o site, qualquer coisa que precise de ativação ou comportamento de desinstalação). Ferramentas de shortcode único entregues como arquivos FluentSnippets pertencem a
wordpress-mini-app-builder, não aqui.
Passo 0a: Ainda sem PRD
Se o usuário pedir para começar a construir e nenhum PRD ou brief de mudança existir: peça a ele que forneça um antes de começar. Não inicie a implementação e não pule silenciosamente para o Passo 1. Se o usuário insistir explicitamente ("apenas construa", "pule o PRD"), o requisito é dispensado: vá direto para o Passo 1 e redija o documento a partir dessa rodada de perguntas.
Passo 0b: PRD, AGENTS.md, documentos de arquitetura fornecidos pelo usuário
Leia-os antes de escrever código e verifique-os em relação a fswp-plugin-developer/references/standards.md e às outras regras da casa.
- Nenhum conflito real: prossiga com a documentação fornecida mais os padrões da casa; as regras da casa preenchem lacunas.
- Conflito real (o documento pede algo que uma regra da casa proíbe, como um atalho de segurança ou esquema de nomenclatura): nomeie ambos os lados claramente e pergunte qual governa. Nunca os misture silenciosamente.
- Um PRD fornecido ainda passa pelo Passo 4; não está isento.
Passo 1: Uma rodada de perguntas essenciais
Use a ferramenta de perguntas estruturadas quando disponível (Claude Code: AskUserQuestion; claude.ai: ask_user_input_v0); caso contrário, uma lista numerada compacta. No máximo 3-4 perguntas, escolhidas por tipo de trabalho:
| Tipo de trabalho | Perguntar sobre |
|---|---|
| Novo plugin | Alvo de distribuição (WordPress.org, zip privado, ambos); superfície de funcionalidades (tipo de post, tabela personalizada, REST, cron, tela administrativa, saída front-end); sistema de design front-end (do usuário, se houver, ou neutro); comportamento estático vs. dinâmico; prefixo de código/acrônimo para este projeto |
| Novo tema | Tema em bloco ou clássico; distribuição (diretório de temas WordPress.org, privado, site do cliente); ponto de partida (do zero, filho de um tema existente); quais tipos de conteúdo e layouts de página são necessários; prefixo de código/acrônimo para este projeto |
| Atualização | Objetivo (bug, funcionalidade, compatibilidade, refatoração); como é entregue (patch para um repositório, zip, edições diretas); o que não deve mudar |
| Add-on | Produto hospedeiro e faixa de versão suportada; o que o add-on adiciona; o que deve acontecer se o hospedeiro estiver ausente |
| Patch do Core | Número do ticket ou descrição do bug; componente alvo; se já existe um ticket no Trac |
Tudo que é aberto (nomes de campos, regras de negócio, casos extremos, nome de trabalho) é inferido e listado sob "Premissas" do PRD, não perguntado. Sem segunda rodada, a menos que as respostas da primeira tenham criado uma bifurcação realmente bloqueante.
Prefixo/acrônimo: para trabalho de novo plugin e novo tema, pergunte qual acrônimo curto ou prefixo o código do projeto deve usar; se o usuário não tiver nenhum, proponha 2-3 candidatos derivados do próprio nome do projeto e deixe-o escolher. Não há padrão embutido e o nome ou marca desta ferramenta nunca é usado como substituto. Regra completa, a redação exata da pergunta e as exceções (mínimo de 4 letras para temas, slug do produto vs. prefixo de código, nomes reservados): fswp-developer/references/brand-naming.md. Nunca WP ou Plugin como prefixo. Em trabalho de Atualização e Add-on, não pergunte; mantenha o prefixo existente do projeto. Versões mínimas padrão: WordPress 6.4, PHP 7.4; aumente apenas para uma necessidade específica (por exemplo PHP 8.1 para enums). Confirme os requisitos atuais na documentação oficial quando for importante.
Informações do projeto (mesma rodada, nunca uma segunda): nome da empresa, nome do produto, autor, contribuidores e links (site, documentação, suporte, repositório). Pergunte apenas pelo que ainda não foi declarado. Nunca invente um valor ausente: um link ou contribuidor não declarado é omitido de todo arquivo gerado.
Decisão de stack de tecnologia: para trabalho novo, decida o nível de UI administrativa e o nível de JS antes de redigir o PRD (fswp-plugin-developer/references/standards.md seção 2). Para trabalho existente, a stack existente permanece a menos que haja uma razão declarada para mudá-la.
Passo 2: Pesquisa de concorrência
2-3 produtos líderes na categoria (diretório WordPress.org ou SaaS). Capture funcionalidades básicas, reclamações comuns e convenções que valha a pena seguir. Algumas pesquisas; 3-5 bullet points no documento. Pule para patches do Core; pesquise o histórico do ticket em vez disso.
Passo 3: O documento
- Novo plugin, novo tema: PRD de
references/prd-template.md(notas de variante de tema dentro). - Atualização, Add-on: brief de mudança de
references/change-brief-template.md: comportamento atual, comportamento solicitado, lista de paridade (o que deve continuar funcionando), tabela de compatibilidade, riscos, plano de teste. - Patch do Core: brief focado no ticket de
references/change-brief-template.mdmais os passos emfswp-core-contributor.
Execute o comportamento front-end pela checklist de 5 pontos do nível JS (fswp-plugin-developer/references/frontend-output.md) e declare o nível. Contagens derivadas (tokens, blocos, rotas, telas) vêm dos dados ou do código, nunca da memória.
Passo 4: Portão de aprovação (o único)
Apresente o documento. As decisões são visíveis e já tomadas; o usuário aprova ou corrige uma vez. Se o nível JS for Alpine, nomeie-o e obtenha um sim explícito. Nenhum scaffolding ou edição antes da aprovação; correções aprovadas são incorporadas primeiro.
Modo Migração
Para reconstruir um plugin existente em uma nova stack. Antes de qualquer alteração de código:
- Baseline: capture capturas de tela de cada tela e estado, além de exportações de referência (configurações, dados, arquivos gerados) da versão antiga. Armazene em
baseline/. - Matriz de paridade: todo recurso antigo, configuração, hook, shortcode, rota REST e opção armazenada mapeado para: mantido / alterado (por quê) / removido (por quê). Nada não listado é enviado silenciosamente.
- Diferenciação de exportações: após a reconstrução, regenere as mesmas exportações e faça o diff contra a baseline. As diferenças devem ser intencionais e listadas.
- Portão de regressão visual: compare novas capturas de tela com a baseline para cada tela; diferenças inexplicadas bloqueiam a entrega (alimenta
fswp-qa-engineer). - Caminho de dados: uma atualização a partir dos dados armazenados da versão antiga deve funcionar sem reativação (veja
fswp-qa-engineer).
Passo 5: Documentos de handoff (builds multissessão)
Quando a build abranger várias sessões, escreva ambos os arquivos na raiz do repositório do plugin (não no zip):
AGENTS.md: o que é; comandos (build, teste, portão QA); mapa de arquitetura; regras e convenções da casa; decisões e restrições; pegadinhas e o que não tocar; definição de pronto.HANDOFF.md: estado atual; mapa de código (arquivo: responsabilidade); tabela verificado / não verificado (cada cenário do PRD com PASS / FAIL / NOT RUN e evidência); itens em aberto; próximo passo.
Atualize ambos a cada parada e antes de encerrar qualquer sessão que não foi concluída.