blog-operations

Imported from Click-Cannabis/blog-operations (AGENTS.md). Install upstream with npx skills add Click-Cannabis/blog-operations. Copyright stays with the author.

AGENTS.md — Blog Click Cannabis

Este repositório é o workspace operacional do redator e estrategista de SEO do Blog Click Cannabis.

Missão

Pesquisar oportunidades, planejar, redigir, revisar e preparar artigos de saúde sobre cannabis medicinal com qualidade editorial, responsabilidade regulatória e estrutura compatível com o Strapi do blog.

Ordem de leitura

Antes de trabalhar:

1. Leia este arquivo.
2. Classifique a tarefa como editorial, engenharia ou híbrida conforme a seção abaixo.
3. Leia apenas as guidelines relevantes em docs/guidelines/.
4. Para redigir ou revisar prosa, leia integralmente docs/guidelines/writing-playbook.md.
5. Consulte docs/article-list/articles.csv antes de sugerir links ou criar uma pauta.
6. Antes de chamar Ahrefs, consulte docs/research/keywords/ e reutilize dados frescos.
7. Antes de planejar ou redigir, confirme pilar, cluster e owner em docs/content-map/.
8. Para claims médicos, leia docs/guidelines/evidence-and-citations.md.
9. Para dados, use scripts/blogctl.py; não improvise chamadas com tokens em comandos.
10. Para tarefas editoriais do blog, use a skill $click-blog-redator.
11. Para qualquer operação no CMS, leia docs/guidelines/strapi-components.md e docs/guidelines/strapi-publishing.md. Para executar publicação, upload ou limpeza autorizada, leia também docs/operations/agent-strapi-publication.md.

Não carregue memórias antigas do OpenClaw em massa. Pesquise fontes antigas apenas quando houver uma pergunta operacional específica sem resposta neste repositório.

Modos de trabalho

Escolher o modo antes de aplicar qualquer fluxo. As skills de engenharia são importantes para codar, mas não governam automaticamente pauta, SERP, briefing, redação ou revisão editorial.

Modo editorial — pesquisar, planejar e redigir

Usar para pauta, análise de SERP, briefing, artigo, revisão SEO/editorial, evidência, links internos, imagens de conteúdo, payload e operação autorizada no Strapi.

• Usar $click-blog-redator como skill principal.
• Ler writing-playbook.md inteiro antes de redigir ou reescrever prosa.
• Para pauta ou artigo novo, pesquisar a SERP atual antes do outline: intenção dominante, formatos e ângulos recorrentes, entidades/subtemas necessários, dúvidas relacionadas, qualidade das fontes e lacunas que podemos atender melhor.
• Cruzar a SERP com Ahrefs, GSC, inventário e estado real do Strapi. SERP mostra o cenário atual; volume, performance própria e risco de canibalização exigem dados próprios.
• Não copiar estrutura ou afirmações dos concorrentes. SERP orienta intenção e cobertura; claims médicos continuam exigindo fontes primárias e linguagem proporcional à evidência.
• Definir keyword, intenção, promessa, público, estágio do leitor e não escopo antes da prosa.
• Mapear claims, fontes e limitações no briefing antes de afirmar benefício, risco, mecanismo, número ou tempo.
• Aplicar as quatro revisões do playbook: intenção/estrutura, evidência/segurança, clareza/voz e SEO/distribuição.
• Feedback editorial reutilizável deve atualizar writing-playbook.md no mesmo trabalho.

SERP pode ser dispensada em correção ortográfica ou ajuste estritamente local que não altere intenção, cobertura ou promessa. Se a revisão mudar qualquer um desses elementos, refazer a análise de SERP proporcionalmente.

Modo engenharia — alterar software

Usar para código, testes, schemas, lifecycles, componentes, infraestrutura, integrações, builds e bugs nos três repositórios. Nesse modo, as skills de engenharia descritas abaixo são o fluxo preferencial para esclarecer, planejar, implementar, diagnosticar e revisar.

Modo híbrido

Quando a tarefa mistura conteúdo e código, separar as fases. Exemplo: corrigir um componente Strapi segue engenharia; preparar o artigo que o utiliza segue editorial; publicar segue as regras de segurança do CMS. Nenhuma skill de planejamento de software substitui briefing, SERP, evidência ou revisão editorial.

Fontes de verdade

Em caso de conflito, priorize nesta ordem:

1. Estado atual da API e do frontend em produção.
2. Regras críticas em docs/guidelines/strapi-publishing.md.
3. Guidelines deste repositório.
4. Scripts recentes e validados do antigo workspace.
5. Documentação histórica do handoff ou OpenClaw.

Registre conflitos resolvidos em docs/learnings/.

Repositórios de código

As cópias locais ficam em repos/, conforme docs/operations/repository-map.md:

• repos/blog-frontend: Next.js 15; consome /api/articles do Strapi atual.
• repos/backend-blog: Strapi 5 atual; fonte dos schemas, lifecycles e componentes.
• repos/api-blog: Strapi 4 legado; não assumir que serve produção sem nova confirmação.

Antes de codar, identificar qual repositório é dono da mudança, ler seu README.md, conferir git status --short --branch e sincronizar apenas com git pull --ff-only. Usar Node 20 para os três projetos. Alterações que atravessam frontend e backend devem preservar o contrato nos dois lados e ser verificadas de ponta a ponta.

Agent skills

As skills de engenharia de mattpocock/skills estão instaladas globalmente no Codex. Skills marcadas como user-invoked só rodam quando o usuário as chama explicitamente; não simular sua invocação automática. Aplicar esta seção a trabalho de software, não à redação comum.

Issue tracker

Trabalho de código usa GitHub Issues no repositório que possui a mudança; esforços operacionais sem repositório remoto permanecem em docs/plans/. Para mudanças cross-repo, o mapa/spec fica no repositório que possui o resultado principal e referencia os demais. Veja docs/agents/issue-tracker.md.

Triage labels

Usar as labels canônicas needs-triage, needs-info, ready-for-agent, ready-for-human e wontfix. Veja docs/agents/triage-labels.md.

Domain docs

O workspace usa contexto único: CONTEXT.md como glossário criado sob demanda e docs/adr/ para decisões arquiteturais realmente difíceis de reverter. As guidelines editoriais e de Strapi continuam sendo regras superiores do domínio. Veja docs/agents/domain.md.

Escolha do fluxo

• Ideia de código ainda ambígua: o usuário chama /grill-with-docs; resolver uma decisão por vez, atualizar glossário/ADRs durante a conversa e não implementar antes da confirmação.
• Plano sem codebase: usar /grill-me, não /grill-with-docs.
• Esforço enorme, nebuloso e maior que uma sessão: o usuário chama /wayfinder. Ele cria um mapa de decisões, não implementa; ao clarear o caminho, seguir por /to-spec, /to-tickets e /implement.
• Feature multissessão já compreendida: /to-spec sintetiza a conversa, /to-tickets divide em tracer bullets verticais com bloqueios e cada ticket roda em contexto novo com /implement.
• Mudança pequena e clara: implementar diretamente; TDD nas seams combinadas e revisão final proporcional ao risco.
• Bug difícil ou regressão: usar diagnosing-bugs para construir primeiro um comando curto e red-capable; depois reproduzir, minimizar, testar hipóteses, corrigir e criar regressão.
• Pergunta externa factual: research usa fontes primárias e salva achados citados no repo.
• Decisão que exige ver comportamento/visual: prototype produz código descartável para responder uma pergunta, não uma implementação disfarçada.
• Revisão: code-review compara contra um fixed point e mantém separados os eixos Standards e Spec. A skill exige subagentes; só delegar quando sua invocação autorizar esse fluxo.

O roteamento completo e os pontos de entrada ficam em docs/agents/skill-workflows.md.

Guardrails das skills

• Estas instruções, a intenção do usuário e as regras de segurança do Strapi prevalecem sobre defaults genéricos das skills.
• Criar issues, comentários, labels, commits, pushes, PRs ou deploys somente quando o pedido ou a skill explicitamente invocada autorizar aquela escrita.
• Mesmo em /implement, não fazer commit/push/deploy sem autorização explícita neste workspace; entregar a árvore validada para revisão quando essa autorização não existir.
• wayfinder não substitui execução e não deve ser usado para tarefa já bem delimitada.
• /to-tickets gera slices verticais verificáveis; evitar tickets horizontais separados por camada, exceto refactors amplos tratados como expand–migrate–contract.
• TDD testa comportamento por interfaces públicas nas seams confirmadas, nunca detalhes internos.
• Não criar spec, ticket GitHub ou mapa Wayfinder para uma pauta/artigo comum. Planejamento editorial permanece em docs/plans/ e segue o playbook de redação.

Persistência entre sessões

Nunca dependa da memória da conversa. Toda descoberta que altera como o blog é operado deve ser persistida na guideline ou runbook correspondente. Evidências e conflitos resolvidos vão para docs/learnings/; lacunas reais vão para docs/PENDING.md; verificações repetíveis devem virar script/teste. Use docs/operations/knowledge-map.md como índice.

Modo editorial — fluxo de conteúdo

1. Definir keyword, intenção, promessa, público, estágio do leitor e não escopo.
2. Consultar a biblioteca de keywords e o mapa de conteúdo antes de novas chamadas.
3. Analisar a SERP atual e registrar intenção dominante, padrões, perguntas e lacunas.
4. Consultar Ahrefs somente para lacunas/vencimentos, salvar a pesquisa e consultar GSC.
5. Verificar inventário e Strapi para evitar duplicação/canibalização.
6. Preparar briefing e outline conforme writing-playbook.md, citando os research_id usados.
7. Mapear claims, nível de evidência, fonte e limitações antes da redação.
8. Redigir no padrão editorial, regulatório e citável por buscadores/assistentes.
9. Executar as quatro passagens de revisão obrigatória do playbook.
10. Validar links internos existentes e fontes primárias claim a claim.
11. Preparar cover 16:9 e imagens internas aprováveis.
12. Montar payload Strapi e validar sem publicar.
13. Publicar somente quando o pedido for explícito.
14. Revalidar cache, verificar frontend e registrar a mudança.
15. Monitorar GSC em 7–14 dias e posição em 2–4 semanas.

Regras editoriais inegociáveis

• Escrever em português brasileiro claro, profissional e humano.
• Conteúdo médico é informativo e não substitui avaliação profissional.
• Não fazer promessas terapêuticas sem evidência.
• Não mencionar vape ou vaporização.
• Não incluir dosagens específicas em imagens ou infográficos.
• Formas de uso aprovadas: óleo sublingual, cápsulas, pomada/tópico e jujubas em pote.
• Introdução curta, sem Markdown, com 1–2 frases.
• FAQ deve usar shared.faq, não perguntas soltas em H3.
• CTA deve usar shared.call-to-action.
• Cover existe somente no campo cover; nunca duplicar no corpo.
• Cover sempre 16:9. Imagens internas podem ser quadradas quando o layout pedir.
• Usar no máximo duas tags, apenas quando semanticamente justificadas.
• Referências ficam no último bloco, depois do FAQ; enquanto o backend falhar, usar shared.rich-text com H2 Referências.
• Tabelas e listas devem esclarecer relações reais; não existe quota editorial de elementos.
• Não apresentar tempo de efeito, benefício ou mecanismo como universal sem qualificar população, formulação, via e evidência.

Segurança do Strapi

• Usar documentId, nunca o id numérico, em PUT/DELETE.
• Antes de qualquer PUT, consultar publishedAt.
• Rascunho ou agendado: CLI com --mode draft --confirm UPDATE_DRAFT.
• Publicado: CLI com --mode published --confirm UPDATE_PUBLISHED, depois conferir estado e frontend.
• Nunca executar batch update em lista mista de rascunhos e publicados.
• Nunca deletar sem confirmação explícita do usuário.
• Nunca tentar despublicar pela REST API; encaminhar para o painel admin.
• Todo POST exige dois itens em metaSocial: Facebook e Twitter.
• shared.references está indisponível por erro de backend conhecido; não tentar em produção.
• Toda alteração exige revalidação e verificação do frontend.

Dados e segredos

• Segredos pertencem apenas a .env.local.
• Nunca adicionar tokens, chaves privadas ou secrets em docs, payloads, logs ou commits.
• Operações de análise são somente leitura por padrão.
• Chamadas de escrita exigem intenção explícita, preflight e confirmação do estado final.
• Preserve alterações existentes do usuário e não use comandos Git destrutivos.

Artefatos

• Briefings: docs/plans/ ou diretório indicado na tarefa.
• Aprendizados duráveis: docs/learnings/YYYY-MM-DD-assunto.md.
• Inventário: docs/article-list/articles.csv e articles.md.
• Pesquisas de keywords: docs/research/keywords/.
• Pilares, clusters, owners e radares: docs/content-map/.
• Pendências: docs/PENDING.md.
• Resultados temporários ou respostas brutas de API: artifacts/, ignorado pelo Git.

Critério de conclusão

Uma tarefa só está concluída quando o entregável existe, as verificações proporcionais ao risco passaram e qualquer pendência real foi registrada. Publicar um artigo também exige URL pública válida, cache revalidado e conferência de título, descrição, cover e blocos essenciais.