agentleFS
otavioserraotavioserra/conn2flow-ai-workspace/.claude/skills/c2f-resources-system/SKILL.md

c2f-resources-system

Skill4 starsChanged 33 days agoMITView on GitHub

LEIA ANTES de criar ou editar qualquer um dos 11 tipos de recursos nativos (pages, layouts, components, templates, variables, ai_prompts, etc.). Se não ler: recursos não entram no build, perdem vínculos, mantêm cache stale de JS/CSS e quebram o deploy.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

Sistema de Recursos do Conn2Flow (resources/)

⚡ Gatilho Obrigatório

  • TRIGGER: Criar, estruturar ou alterar arquivos dentro das pastas resources/<lang>/ de módulos ou projetos.
  • SKIP APENAS SE: Edição de arquivos não gerenciados pelo sistema de recursos (ex: scripts na raiz de scripts/).
  • CONSEQUÊNCIA DE IGNORAR: Recursos não sincronizados para o banco de dados SQL, ausência de compilação em *Data.json, mascaramento de bugs por cache stale de JavaScript/CSS e quebra de layouts no site publicado.

[!WARNING] REGRA MANDATÓRIA DE ARQUIVOS HTML, CSS E MARKDOWN: NUNCA crie arquivos .html, .css ou .md soltos na raiz do projeto, em pastas públicas estáticas ou na raiz de módulos PHP! TODO e QUALQUER conteúdo HTML, CSS ou Markdown para páginas, layouts, componentes, templates ou prompts no Conn2Flow DEVE OBRIGATORIAMENTE ser criado dentro da estrutura do Sistema de Recursos (resources/), para que possa ser compilado em *Data.json e sincronizado no Banco de Dados SQL pelo runtime.

1. Arquitetura de Recursos (Edição Física -> Compilação -> Banco)

Proporcionalidade de recompilação — REQ-075 / Core REQ-269

Classifique o diff antes de compilar:

  • Categoria A: backend PHP/APIs/migrations/regras de negócio sem alteração de HTML, classes Tailwind, CSS ou fontes/configuração de compilação. Não recompile Tailwind. Se sincronização local for necessária, use ./c2f project:deploy <id> ou ./c2f manager:update-all --skip-css. Core isolado usa o pipeline do sistema.
  • Categoria B: documentação, skills, testes unitários e memória MDD. Execute apenas os testes/checks locais pertinentes; nenhum pipeline de deploy no Lab.
  • Categoria C: telas/templates HTML/componentes/classes/CSS autoral/fontes de compilação. Execute o pipeline completo sem --skip-css; mudanças mistas com impacto visual também são C.

Ignorar CSS não significa ignorar dados: recursos alterados ainda precisam gerar seus *Data.json e chegar ao banco pelo pipeline. A flag dispensa Tailwind e CSS derivado, preservando as demais etapas. A via cirúrgica de Core/banco não compila recursos do projeto. Mantenha version bump e invalidação de cache para scripts/estilos alterados. Não faça build completo em A nem deploy em B; não prometa duração <45 segundos sem medir no ambiente real.

  • Fonte (Source): Desenvolvedores criam/editam arquivos físicos em resources/<idioma>/<tipo>/<id>/<id>.<ext>.
  • Recursos de Módulo: modulos/<modulo-id>/resources/<idioma>/<tipo>/<id>/<id>.<ext>.
  • Natural Key: O nome da pasta do recurso (<id>) é a chave primária natural no Banco de Dados.
  • Compilação: O comando c2f resources:sync lê os fontes e gera arquivos estáticos em gestor/db/data/*Data.json (PaginasData.json, LayoutsData.json, ComponentesData.json).
  • Sincronização: O runtime aplica Upsert no Banco respeitando proteções de user_modified = 1 e project.

2. Os 11 Tipos de Recursos Nativos

TipoTabela SQLArquivo FonteUso
pages (paginas)paginas<id>/<id>.html + <id>.cssPáginas com URL, vinculadas a layout via id_layouts
layoutslayouts<id>/<id>.html + <id>.cssEstrutura externa (header/footer) com slot de inserção
components (componentes)componentes<id>/<id>.html + <id>.cssBlocos reutilizáveis de HTML/CSS
templatestemplates<id>/<id>.htmlTemplates de email, notificação, etc.
variables (variaveis)variaveisvariables.jsonMensagens, labels e textos multilíngues
ai_promptsprompts<id>/<id>.mdPrompts e instruções de IA em Markdown
ai_modesmodos<id>/<id>.mdSystem prompts e modos de IA
ai_prompts_targetsprompts_targets<id>/<id>.mdTargets de prompts de IA
forms (formularios)formularios<id>/<id>.htmlFormulários HTML reutilizáveis
widgetswidgets<id>/<id>.html + <id>.cssWidgets visuais de interface

🏷️ 3. Regra Mandatória de Version Bump (Cache-Busting)

Ao criar ou editar qualquer script JavaScript (<id>.js) ou folha de estilo (<id>.css) em resources/:

  • O agente DEVE OBRIGATORIAMENTE realizar o version bump (incremento de versão, ex: "versao": "1.0.0" ➔ "1.0.1") no arquivo de metadados do recurso (<id>.json) ou no manifest do módulo (<modulo>.json).
  • Isso assegura que, ao rodar c2f resources:sync, a query string <script src="...&v=1.0.1"> seja atualizada, forçando o navegador a invalidar o cache antigo imediatamente e prevenindo erros por execução de assets obsoletos (stale cache).

🗄️ 3.1. Fonte da Verdade em Runtime (Banco vs Disco)

[!IMPORTANT] O runtime do Conn2Flow serve HTML e CSS exclusivamente do BANCO DE DADOS (gestor.php:2782). O diretório resources/ é lido diretamente apenas sob DEVELOPMENT_ENV=true.

Fluxo Arquitetural:

resources/ (disco) → c2f resources:sync → *Data.json → Upsert no Banco SQL → Runtime serve do Banco
  • Disco (resources/): É a semente de compilação — a fonte de autoria onde desenvolvedores criam e editam.
  • Banco de Dados: É a fonte da verdade em runtime — o que o visitante vê e o que o Gestor edita.
  • Pipeline Oficial: Alterações em disco SÓ chegam ao runtime após execução de c2f manager:update-all (para o sistema) ou c2f project:deploy <id> (para projetos).

Ao investigar o comportamento de uma página publicada:

  1. Inspecione o banco PRIMEIRO (tabelas paginas, layouts, componentes).
  2. Compare com resources/ para identificar divergências.
  3. NUNCA assuma que o conteúdo em disco é o que está sendo servido.

4. Convenções de HTML e Seções

  • Em arquivos de página (pages/<id>/<id>.html), adicione obrigatoriamente os atributos às tags <section>:
    <section class="text-center mb-16" data-id="1" data-title="hero">
        <!-- Conteúdo da seção -->
    </section>
    • data-id: Índice numérico sequencial iniciando em 1.
    • data-title: Nome semântico simples da seção (ex: hero, recursos, contato).

5. Extensibilidade Dinâmica de Recursos

Tabelas customizadas podem se tornar novos tipos de recursos automaticamente usando sync_resources: true em tables_config.json ou <modulo>.json:

{
  "tabelas": {
    "minha_tabela": {
      "nome": "minha_tabela",
      "config": {
        "sync_resources": true,
        "resources_dir": "minha_tabela",
        "metadata_file": "minha_tabela.json",
        "field_types": {
          "html": "file:html",
          "css": "file:css",
          "conteudo": "file:md",
          "config": "json"
        }
      }
    }
  }
}

Os field_types suportados são:

  • file:html — Arquivo HTML físico em <id>/<id>.html
  • file:css — Arquivo CSS físico em <id>/<id>.css
  • file:md — Arquivo Markdown físico em <id>/<id>.md
  • json — Dados JSON inline no metadado

A compilação gera [PascalCase]Data.json (ex: MinhaTabelaData.json) automaticamente.

Nota de autoria: na via cirúrgica Core/banco, --core-resources preserva o dono das sementes do Core. Dados e recursos próprios do projeto exigem sua sincronização específica; não use essa flag para transferir autoria.

REQ-077 — Pipeline, worktrees e preservação (DEC-136)

  • Projeto: ./c2f project:deploy <id> é o padrão (95% dos casos). Core: ./c2f manager:update-all. ./c2f project:update-all <id> é proibido na rotina de projeto; permitido exclusivamente em lote que altera Core e projeto simultaneamente.
  • Antes de deploy, confira git branch --show-current e git status --short na origem; não publique trabalho alheio/inacabado. Confira o destino e sua autorização. Categoria B (skills/documentação/testes/memória): somente checks locais, sem deploy. Execução sequencial, foreground, logs e locks continuam obrigatórios.
  • Worktrees por conveniência são proibidas. Só criar com concorrência multi-agente comprovada no mesmo repositório; em dúvida, consultar o humano antes. Registre raiz original, caminho temporário e concorrência na requisição e lote. Ao concluir/homologar, audite trabalho único, integração na main e junctions, então git worktree remove <caminho> e git worktree prune. Nunca use força para destruir trabalho não integrado; preserve e reporte impedimentos.
  • DEC-136: manter por padrão; nada é removido (arquivo, status='D', DELETE) sem confirmação explícita do operador humano. Retirada vira choque pendente; --confirmar-retirada só quando pedido pelo operador. Fonte incompleta não autoriza retirada.

REP-002 — manifestos por camada e choques

Precedência: projeto > plugin:<id> > core. Arquivos usam installation/manifests/<camada>.json; dados usam recursos-<dono>.json. Dados homônimos em db/data/ não mudam de dono: a etapa Core lê a entrega Core; a etapa projeto lê a entrega projeto.

ChoqueSituação
editadoArquivo local difere da versão entregue pela camada
sobrepostoCamada superior tem precedência sobre a entrega
retiradoDono deixou de entregar; manter até decisão humana
retirado-editadoArquivo retirado também possui edição local
original-ausenteOriginal necessário à comparação não está disponível

Registrar choques antes de gravar o manifesto; versões novas ficam em backups/overrides/<versão>/. Nunca reconciliar em massa sem simulação e confirmação humana (DEC-136).

Nota REQ-077: --skip-css refere-se aos comandos que a implementam (manager:update-all e à exceção project:update-all). O wrapper ProjectDeployCommand.php repassa somente projeto e --contents; não prescreva essa flag a project:deploy.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.