afonsoft · afonsoft · May 19, 2026 · May 18, 2026
diff --git a/.agents/CONTEXT.md b/.agents/CONTEXT.md
@@ -0,0 +1,51 @@
+# Context Engineering — QRCoder.Core
+
+## Estratégias de Carregamento
+
+| Tipo | Quando | Arquivos |
+|------|--------|----------|
+| **Always-on** | Sempre carregado | `AGENTS.md`, `.agents/RULES.md` |
+| **Pattern-matched** | Por tipo de arquivo | `rules/*.instructions.md` (via `applyTo`) |
+| **On-demand** | Quando solicitado | `.agents/skills/`, `docs/`, `.agents/MEMORY.md` |
+| **Progressive disclosure** | Arquivos grandes | Headers → seções relevantes |
+
+## Hierarquia de Prioridade
+
+1. Instruções do usuário (chat/prompt)
+2. `AGENTS.md` (SSoT)
+3. Arquivo de plataforma (`CLAUDE.md`, `DEVIN.md`, `GEMINI.md`)
+4. `.agents/RULES.md`
+5. `rules/*.instructions.md`
+6. `.agents/skills/`
+7. `.agents/MEMORY.md`
+
+## Token Budget
+
+- Reservar 20% do contexto para output
+- `AGENTS.md` ≤ 500 linhas
+- Skills: carregar apenas as relevantes
+
+## Chunking
+
+- `QRCodeGenerator.cs`: arquivo grande — carregar por método/seção
+- Testes: agrupar por renderizador
+
+## Mapa de Diretórios
+
+```
+Prioridade alta:
+  QRCoder.Core/Generators/
+  QRCoder.Core/Renderers/
+  QRCoder.Core/Abstractions/
+  QRCoder.Core.Tests/
+
+Prioridade média:
+  QRCoder.Core/Models/
+  QRCoder.Core/Extensions/
+  docs/
+
+Prioridade baixa:
+  QRCoder.Core/Assets/
+  Docs/ (SHFB generated)
+  .vscode/
+```
diff --git a/.agents/MEMORY.md b/.agents/MEMORY.md
@@ -0,0 +1,30 @@
+# QRCoder.Core Agent Memory
+
+Este arquivo é mantido automaticamente pelo agente AI para persistir aprendizados sobre o codebase.
+
+## Decisões Técnicas
+
+| Data | Decisão | Motivo | Alternativas Descartadas |
+|------|---------|--------|--------------------------|
+| 2026-05 | SkiaSharp como engine de renderização | Cross-platform (Win/Linux/Mac) | System.Drawing (não cross-platform) |
+| 2026-05 | ObjectPool para QRCodeData | Performance em alta demanda | Criação por request |
+| 2026-05 | Multi-TFM (netstandard2.1, net8.0, net10.0, net48) | Máxima compatibilidade | Apenas net8.0+ |
+
+## Débitos Técnicos
+
+| Item | Impacto | Prioridade |
+|------|---------|-----------|
+| Cobertura 78% (target 90%) | Qualidade | Média |
+| PayloadGenerator sem testes completos | Risco de regressão | Média |
+
+## Lições Aprendidas
+
+| Contexto | Erro | Como Evitar |
+|----------|------|-------------|
+| Build net48 em Linux | Falha por falta de Windows Desktop | Usar `-f net10.0` para testes locais |
+| SkiaSharp em CI | Falta de dependências nativas | Instalar libfontconfig1, libfreetype6, etc. |
+
+## Políticas de Limpeza
+
+- Fatos desatualizados devem ser removidos
+- Memórias de branches deletadas devem ser descartadas
diff --git a/.agents/README.md b/.agents/README.md
@@ -0,0 +1,50 @@
+# Infraestrutura de Agentes — QRCoder.Core
+
+## Diagrama de Arquivos
+
+```
+AGENTS.md                 ← SSoT (≤500 linhas)
+CLAUDE.md                 ← Delta para Claude Code
+DEVIN.md                  ← Delta para Devin
+GEMINI.md                 ← Delta para Gemini CLI
+.aiignore                 ← Ignore JetBrains AI
+.claudeignore             ← Ignore Claude Code
+.cursorignore             ← Ignore Cursor
+.devinignore              ← Ignore Devin
+.geminiignore             ← Ignore Gemini CLI
+.windsurfignore           ← Ignore Windsurf
+.agents/
+├── CONTEXT.md            ← Estratégias de contexto
+├── RULES.md              ← Guardrails
+├── MEMORY.md             ← Estado cross-session
+├── TOOLS.md              ← Ferramentas e CI/CD
+├── WORKFLOWS.md          ← Workflows de automação
+├── README.md             ← Este arquivo
+└── skills/
+    ├── qrcode-development/   ← Desenvolvimento de QR Code
+    └── qrcode-testing/       ← Testes de QR Code
+rules/
+└── csharp-qrcoder.instructions.md  ← Rules C# (applyTo: **/*.cs)
+```
+
+## Como Adicionar Nova Skill
+
+1. Criar diretório em `.agents/skills/<nome-kebab-case>/`
+2. Criar `SKILL.md` com frontmatter YAML
+3. Documentar: What / When / Do NOT
+4. Atualizar este README
+
+## Compatibilidade
+
+| Feature | Claude | Devin | Gemini | Cursor | Windsurf |
+|---------|--------|-------|--------|--------|----------|
+| AGENTS.md | Sim | Sim | Sim | Sim | Sim |
+| Skills | Sim | Sim | Sim | Sim | Sim |
+| Rules | Sim | Sim | Sim | Sim | Sim |
+| Ignore | .claudeignore | .devinignore | .geminiignore | .cursorignore | .windsurfignore |
+
+## Referências
+
+- [AGENTS.md Spec](https://agents.md/)
+- [Agent Skills Spec](https://agentskills.io/specification)
+- [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/)
diff --git a/.agents/RULES.md b/.agents/RULES.md
@@ -0,0 +1,51 @@
+# RULES.md — QRCoder.Core Guardrails
+
+## Hard Rules (bloqueio imediato)
+
+| # | Regra | Verificação |
+|---|-------|-------------|
+| H1 | Todos os testes devem passar antes do merge | CI: `dotnet test` |
+| H2 | Cobertura de código não pode diminuir (baseline: 78%) | CI: coverlet |
+| H3 | Compatibilidade cross-platform obrigatória (Win/Linux/Mac) | CI: ubuntu-latest |
+| H4 | Manter suporte .NET Standard 2.1 | Build multi-TFM |
+| H5 | Nunca commitar secrets | `.gitignore` |
+| H6 | Não usar System.Drawing (deprecated, não cross-platform) | Code review |
+| H7 | Não push direto em `main` | Branch protection |
+
+## Soft Rules (warning + confirmação)
+
+| # | Regra | Ação |
+|---|-------|------|
+| S1 | Alterar `QRCodeGenerator.cs` (engine central) | Testes extensivos |
+| S2 | Adicionar dependência NuGet | Verificar compatibilidade multi-TFM |
+| S3 | Alterar formato de saída de renderizadores | Backward compatibility |
+| S4 | Modificar CI workflows | Requer revisão |
+| S5 | Alterar versão do SkiaSharp | Testar em todas as plataformas |
+
+## Permissões por Ambiente
+
+| Ambiente | Read | Write | Execute |
+|----------|------|-------|---------|
+| **dev** | Livre | Livre | Sandbox |
+| **CI** | Livre | Via PR | Automático |
+| **NuGet** | — | — | Via release workflow |
+
+## Tool Permissions
+
+- **Read-only**: busca, navegação, análise de código
+- **Write**: edição via PR
+- **Execute**: build, test em sandbox
+- **Publish**: apenas via CI/CD
+
+## Arquivos Imutáveis
+
+```
+bin/
+obj/
+Docs/ (SHFB generated)
+.git/
+.vs/
+.vscode/
+packages/
+TestResults/
+```
diff --git a/.agents/TOOLS.md b/.agents/TOOLS.md
@@ -0,0 +1,45 @@
+# TOOLS.md — QRCoder.Core Ferramentas
+
+## Ferramentas de Build
+
+| Ferramenta | Comando | Categoria |
+|-----------|---------|-----------|
+| dotnet restore | `dotnet restore QRCoder.Core.sln` | Read-only |
+| dotnet build | `dotnet build QRCoder.Core.sln --configuration Release` | Execute |
+| dotnet test | `dotnet test QRCoder.Core.sln --collect:"XPlat Code Coverage"` | Execute |
+| dotnet pack | `dotnet pack --configuration Release` | Execute |
+
+## Ferramentas de Qualidade
+
+| Ferramenta | Uso | Categoria |
+|-----------|-----|-----------|
+| SonarCloud | Análise de qualidade de código | Execute |
+| Codecov | Relatório de cobertura | Execute |
+| coverlet | Coleta de cobertura em testes | Execute |
+
+## Ferramentas de CI/CD
+
+| Workflow | Trigger | Descrição |
+|---------|---------|-----------|
+| `ci-build-test.yml` | push feature/*, PR main | Build + testes + cobertura |
+| `publish-all.yml` | tag release | Publicação NuGet |
+| `code-quality.yml` | PR | SonarCloud + Qodana |
+| `security-scan.yml` | schedule/PR | Scan de segurança |
+| `openhands-resolver.yml` | issue label | Auto-fix via OpenHands |
+| `auto-pr-from-main.yml` | push main | Sync automático |
+
+## APIs Externas
+
+| API | Uso | Headers |
+|-----|-----|---------|
+| NuGet.org | Publicação de pacotes | API Key via CI secrets |
+| SonarCloud | Qualidade | Token via CI secrets |
+| Codecov | Cobertura | Token via CI secrets |
+| GitHub API | CI/CD | GITHUB_TOKEN |
+
+## Dependências Nativas (Linux)
+
+```bash
+sudo apt-get install -y libfontconfig1 libfreetype6 libx11-6 libxext6 libxrender1 libxtst6
+sudo apt-get install -y libglib2.0-0 libgl1-mesa-dev
+```
diff --git a/.agents/WORKFLOWS.md b/.agents/WORKFLOWS.md
@@ -0,0 +1,85 @@
+# WORKFLOWS.md — QRCoder.Core Automação
+
+## Workflow: Novo Renderizador
+
+### Precondições
+- Formato de saída definido
+- Renderizador herda de `AbstractQRCode`
+
+### Passos
+1. Criar classe em `QRCoder.Core/Renderers/`
+2. Herdar de `AbstractQRCode`
+3. Implementar método `GetGraphic()`
+4. Criar testes em `QRCoder.Core.Tests/Renderers/`
+5. Documentar em `docs/en-US/` e `docs/pt-BR/`
+6. Atualizar README com novo formato
+7. Criar PR
+
+### Critérios de Sucesso
+- Testes passam em todos os TFMs
+- Cross-platform (sem System.Drawing)
+- Documentação bilíngue
+
+---
+
+## Workflow: Novo Payload
+
+### Precondições
+- Payload segue padrão da indústria (ex: vCard, WiFi QR)
+
+### Passos
+1. Criar classe em `PayloadGenerator`
+2. Implementar `ToString()` com formato padronizado
+3. Criar testes unitários
+4. Documentar exemplos de uso
+5. Criar PR
+
+---
+
+## Workflow: Bug Fix
+
+### Passos
+1. Reproduzir com teste que falha
+2. Implementar correção
+3. Verificar que teste passa
+4. Rodar suite completa: `dotnet test`
+5. Criar PR
+
+---
+
+## Verification Loop
+
+```
+Código → Build → Testes → Cobertura → CI → Review
+  ↑                                         |
+  └──── Ajustar (máx. 2x) ────────────────┘
+```
+
+### Execução Local
+```bash
+dotnet restore QRCoder.Core.sln
+dotnet build QRCoder.Core.sln --configuration Release
+dotnet test QRCoder.Core.sln --configuration Release --collect:"XPlat Code Coverage"
+```
+
+---
+
+## Workflow: Release
+
+### Passos
+1. Atualizar versão em `QRCoder.Core.csproj`
+2. Atualizar `CHANGELOG.md`
+3. Criar tag de release
+4. CI publica automaticamente no NuGet
+
+---
+
+## Trigger Conditions
+
+| Evento | Workflow |
+|--------|---------|
+| Push em `feature/*`, `bug/*`, `hotfix/*` | `ci-build-test.yml` |
+| PR para `main` | `ci-build-test.yml` + `code-quality.yml` |
+| Tag de release | `publish-all.yml` |
+| Push em `main` | `auto-pr-from-main.yml` |
+| Schedule | `security-scan.yml` |
diff --git a/.agents/skills/qrcode-development/SKILL.md b/.agents/skills/qrcode-development/SKILL.md
@@ -0,0 +1,51 @@
+---
+name: qrcode-development
+description: >
+  What: Guia para desenvolvimento de renderizadores, payloads e funcionalidades do QRCoder.Core.
+  When: Ao criar novos renderizadores, adicionar payloads, modificar o QRCodeGenerator, ou trabalhar com SkiaSharp.
+  Do NOT: Não usar para testes (ver qrcode-testing), CI/CD, ou documentação isolada.
+---
+
+## Contexto
+
+QRCoder.Core é uma biblioteca cross-platform para geração de QR Codes. A arquitetura segue:
+- `QRCodeGenerator` → engine central que gera `QRCodeData` (matriz de bits)
+- `AbstractQRCode` → classe base para renderizadores
+- Cada renderizador converte `QRCodeData` em um formato de saída específico
+
+## Atuação
+
+### Novo Renderizador
+1. Criar classe em `QRCoder.Core/Renderers/`
+2. Herdar de `AbstractQRCode`
+3. Implementar `GetGraphic()` com parâmetros de customização
+4. Manter compatibilidade cross-platform (sem System.Drawing)
+5. Usar SkiaSharp para renderização gráfica se necessário
+
+### Novo Payload
+1. Criar classe em `PayloadGenerator` (arquivo existente)
+2. Implementar `ToString()` retornando string formatada
+3. Seguir padrão da indústria (RFC, especificação oficial)
+4. Adicionar validação de inputs
+
+### Performance
+- Usar `ObjectPool<QRCodeData>` para reutilização de buffers
+- Usar `Span<T>` e `System.Buffers` para operações com arrays
+- Evitar alocações em hot paths
+
+## Restrições
+
+- Não usar System.Drawing (não é cross-platform)
+- Manter compatibilidade com .NET Standard 2.1
+- Não adicionar dependências nativas além do SkiaSharp
+- XML documentation obrigatória em APIs públicas
+
+## Exemplos
+
+```csharp
+// Gerar QR Code PNG
+var generator = new QRCodeGenerator();
+var data = generator.CreateQrCode("Hello", QRCodeGenerator.ECCLevel.M);
+var pngCode = new PngByteQRCode(data);
+byte[] pngBytes = pngCode.GetGraphic(20);
+```