@girardelli/architect 5.0.0 → 6.0.0

package/.agent/INDEX.md

@@ -0,0 +1,197 @@
+# @girardelli/architect — Agent Framework
+
+> **Auto-generated by [Architect v3.1](https://github.com/camilooscargbaptista/architect)**
+> Stack: **TypeScript + JavaScript** | Score: **94/100** | Files: **122** | Lines: **37.407**
+
+---
+
+## ⛔ PARE AQUI — LEITURA OBRIGATÓRIA
+
+> **Antes de qualquer ação, leia estes documentos NA ORDEM.**
+> Pular esta etapa é violação do protocolo.
+
+| # | Arquivo | O que contém | Quando ler |
+|---|---------|-------------|-----------|
+| 1 | [00-general.md](./rules/00-general.md) | Regras de Ouro, convenções, identidade do projeto | **SEMPRE** |
+| 2 | [PREFLIGHT.md](./guards/PREFLIGHT.md) | Checklist pré-ação por camada | **SEMPRE** |
+| 3 | [QUALITY-GATES.md](./guards/QUALITY-GATES.md) | Métricas mínimas, blockers, processo de verificação | **SEMPRE** |
+| 4 | [CODE-REVIEW-CHECKLIST.md](./guards/CODE-REVIEW-CHECKLIST.md) | Pontos obrigatórios de revisão | Antes de PR |
+
+---
+
+## 🗺️ Guia Situacional
+
+> **"O que vou fazer?"** → Siga a coluna correspondente.
+
+| Ação | Leia antes | Workflow | Agente principal |
+|------|-----------|---------|-----------------|
+| Nova feature | 00-general + PREFLIGHT | [new-feature](./workflows/new-feature.md) | ORCHESTRATOR |
+| Corrigir bug | 00-general + PREFLIGHT | [fix-bug](./workflows/fix-bug.md) | ORCHESTRATOR |
+| Mexer em backend | 00-general + 01-architecture | new-feature ou fix-bug | TYPESCRIPT-BACKEND |
+| Segurança | 02-security | — | SECURITY-AUDITOR |
+| Testes | 00-general | — | QA-TEST-ENGINEER |
+| Refatoração | QUALITY-GATES | — | TECH-DEBT-CONTROLLER |
+| Code review | CODE-REVIEW-CHECKLIST | [review](./workflows/review.md) | QA-TEST-ENGINEER |
+
+---
+
+## 🤖 Agentes Disponíveis
+
+| Agente | Role | Capabilities |
+|--------|------|-------------|
+| [AGENT-ORCHESTRATOR](./agents/AGENT-ORCHESTRATOR.md) | coordination | Decomposição, dispatch, consolidação, quality gate |
+| [TYPESCRIPT-BACKEND-DEVELOPER](./agents/TYPESCRIPT-BACKEND-DEVELOPER.md) | development | APIs, serviços, lógica de negócio, migrations |
+| [SECURITY-AUDITOR](./agents/SECURITY-AUDITOR.md) | quality | Ameaças STRIDE, OWASP, LGPD, vulnerabilidades |
+| [QA-TEST-ENGINEER](./agents/QA-TEST-ENGINEER.md) | quality | Planos de teste, BDD/TDD, cobertura, regressão |
+| [TECH-DEBT-CONTROLLER](./agents/TECH-DEBT-CONTROLLER.md) | governance | Débito técnico, refatorações, metas de score |
+
+---
+
+## 📋 Templates Disponíveis
+
+| Template | Arquivo | Quando usar |
+|----------|---------|-----------|
+| C4 Architecture | [C4.md](./templates/C4.md) | Documentar arquitetura de qualquer feature |
+| BDD Scenarios | [BDD.md](./templates/BDD.md) | Antes de implementar — cenários de aceite |
+| TDD Cases | [TDD.md](./templates/TDD.md) | Antes de implementar — casos de teste |
+| ADR | [ADR.md](./templates/ADR.md) | Decisões arquiteturais significativas |
+| Threat Model | [THREAT-MODEL.md](./templates/THREAT-MODEL.md) | Features que lidam com dados sensíveis |
+
+---
+
+## 📁 Estrutura do Framework
+
+```
+.agent/
+├── INDEX.md              ← VOCÊ ESTÁ AQUI
+├── agents/               → Agentes especializados
+│   ├── AGENT-ORCHESTRATOR.md
+│   ├── TYPESCRIPT-BACKEND-DEVELOPER.md
+│   ├── SECURITY-AUDITOR.md
+│   ├── QA-TEST-ENGINEER.md
+│   └── TECH-DEBT-CONTROLLER.md
+├── rules/                → Regras de codificação
+│   ├── 00-general.md
+│   ├── 01-architecture.md
+│   └── 02-security.md
+├── guards/               → Checklists e quality gates
+│   ├── PREFLIGHT.md
+│   ├── QUALITY-GATES.md
+│   └── CODE-REVIEW-CHECKLIST.md
+├── workflows/            → Fluxos de trabalho
+│   ├── new-feature.md
+│   ├── fix-bug.md
+│   └── review.md
+├── templates/            → Templates reutilizáveis
+│   ├── C4.md
+│   ├── BDD.md
+│   ├── TDD.md
+│   ├── ADR.md
+│   └── THREAT-MODEL.md
+└── skills/               → Padrões e referências
+```
+
+---
+
+## 🔄 Fluxo Completo de Desenvolvimento
+
+```
+REQUISIÇÃO RECEBIDA
+       │
+       ▼
+┌──────────────────┐
+│  PREFLIGHT.md    │ ← Ler OBRIGATÓRIO
+│  (diagnóstico)   │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│  ORCHESTRATOR    │ ← Decompõe a requisição
+│  (classificar)   │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────────────────────────┐
+│         6 GATES OBRIGATÓRIOS         │
+│                                      │
+│  1. MOCKUP (se tem UI)               │
+│  2. User Stories                     │
+│  3. Arquitetura (C4)                 │
+│  4. Tarefas (breakdown)              │
+│  5. BDD (cenários)                   │
+│  6. TDD (casos de teste)            │
+│                                      │
+│  ⚠️  /approved após cada gate        │
+└────────┬─────────────────────────────┘
+         │
+         ▼
+┌──────────────────────────────────────┐
+│      IMPLEMENTAÇÃO (ordenada)        │
+│                                      │
+│  1° Backend (se houver)              │
+│  2° Documento de Integração          │
+│  3° Frontend / App (se houver)       │
+└────────┬─────────────────────────────┘
+         │
+         ▼
+┌──────────────────┐
+│  QUALITY-GATES   │ ← Build + Coverage ≥ 80%
+│  (verificação)   │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│  CODE REVIEW     │ ← Checklist obrigatório
+│  (PR)            │
+└────────┬─────────┘
+         │
+         ▼
+      ✅ DONE
+```
+
+---
+
+## ⚡ Atalhos Rápidos
+
+| Situação | Comando / Workflow |
+|----------|-------------------|
+| Nova feature | `/new-feature` → [workflow](./workflows/new-feature.md) |
+| Corrigir bug | `/fix-bug` → [workflow](./workflows/fix-bug.md) |
+| Code review | `/review` → [workflow](./workflows/review.md) |
+| Verificar qualidade | `architect score ./src` |
+| Analisar arquitetura | `architect analyze ./src` |
+
+---
+
+## 🔌 Plugin Recomendado
+
+Para análise contínua de arquitetura e manutenção do score:
+
+```
+┌─────────────────────────────────────────────┐
+│  📦 @girardelli/architect                   │
+│  Plugin para Claude Code                    │
+│                                             │
+│  npm install -g @girardelli/architect       │
+│                                             │
+│  Comandos:                                  │
+│  • architect analyze ./src                  │
+│  • architect score ./src                    │
+│  • architect agents ./src                   │
+│  • architect refactor ./src                 │
+│                                             │
+│  Score atual: 94/100                        │
+│  Meta: 100/100                       │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## ⚠️ REGRA DE OURO
+
+> **Na dúvida, PARA e PERGUNTA ao humano.**
+> Nunca assuma. Nunca decida sozinho. Sempre valide.
+
+---
+
+**Gerado por Architect v3.1 · Score: 94/100 · 2026-03-30**

package/.agent/agents/AGENT-ORCHESTRATOR.md

@@ -0,0 +1,408 @@
+---
+antigravity:
+  trigger: 'always_on'
+  globs: ['**/*']
+  description: 'META-AGENT ORQUESTRADOR — Centro de comando para @girardelli/architect'
+  priority: CRITICAL
+agent_card:
+  id: 'orchestrator'
+  name: 'Agent Orchestrator'
+  role: 'coordination'
+  capabilities: [request-decomposition, agent-dispatch, plan-consolidation, quality-verification, artifact-gating]
+  inputs: [user-story, feature-request, bug-report, refactoring-request]
+  outputs: [consolidated-plan, implementation-blocks, effort-estimate, architecture-docs]
+  depends_on: []
+version: 3.1.0
+---
+
+# 🎭 AGENT-ORCHESTRATOR: @girardelli/architect
+
+> **Centro de comando.** Toda requisição passa por aqui.
+> **Nenhuma linha de código é escrita sem os artefatos obrigatórios.**
+
+---
+
+## ⛔ REGRA ABSOLUTA: ARTEFATOS ANTES DE CÓDIGO
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║                                                              ║
+║   ANTES de escrever QUALQUER linha de código, os seguintes  ║
+║   artefatos DEVEM existir e ser APROVADOS pelo humano:      ║
+║                                                              ║
+║   1. 🎨 MOCKUP (se tem UI)                                  ║
+║      → Todas as telas, estados, erros, modais, mensagens    ║
+║      → Seguir padrão visual do sistema                      ║
+║                                                              ║
+║   2. 📖 USER STORIES                                        ║
+║      → Como [ator], quero [ação], para [benefício]          ║
+║      → Critérios de aceite mensuráveis                      ║
+║                                                              ║
+║   3. 🏗️  ARQUITETURA (C4)                                   ║
+║      → Contexto, Container, Componente, Código              ║
+║      → Decisões arquiteturais (ADR)                         ║
+║                                                              ║
+║   4. 📋 TAREFAS                                             ║
+║      → Breakdown com TASK-XXX                               ║
+║      → Estimativa T-shirt (XS/S/M/L/XL)                    ║
+║                                                              ║
+║   5. 🧪 BDD (cenários)                                      ║
+║      → Given/When/Then para cada critério de aceite         ║
+║                                                              ║
+║   6. 🔬 TDD (casos de teste)                                ║
+║      → RED → GREEN → REFACTOR                               ║
+║      → Cobertura mínima: 80%                           ║
+║                                                              ║
+║   ⚠️  PRODUZIR APENAS UM IMPLEMENTATION PLAN SEM ESTES      ║
+║      ARTEFATOS É VIOLAÇÃO DO PROTOCOLO.                     ║
+║                                                              ║
+║   ORDEM DE IMPLEMENTAÇÃO:                                    ║
+║   1° Backend  →  2° Doc. Integração  →  3° Frontend/App    ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 📊 Contexto do Projeto
+
+| Métrica | Valor |
+|---------|-------|
+| **Projeto** | @girardelli/architect |
+| **Stack** | TypeScript + JavaScript |
+| **Score Atual** | 94/100 |
+| **Meta de Score** | 100/100 |
+| **Camadas** | UI, Infrastructure |
+| **Anti-Patterns** | None |
+| **Arquivos** | 122 |
+| **Linhas** | 37.407 |
+| **Cobertura Mínima** | 80% |
+| **Refatorações Pendentes** | 14 steps |
+
+
+---
+
+## 📍 Contexto Enriquecido
+
+🟡 Projeto Médio (50-200 arquivos) · 🏛️ Clean Architecture / DDD
+
+> 🚀 **Stack Detectada:** Testes: Jest · Lint: ESLint
+
+> 📌 **Domínio:** devtools · **Sub-domínio:** code-intelligence · **Confiança:** 95%
+
+### 📦 Resumo de Módulos
+
+
+| Módulo | Arquivos | Linhas | Testes | Camada |
+|--------|----------|--------|--------|--------|
+| agent-generator | 98 | 10.819 | ❌ | Other |
+| html-reporter | 21 | 1.296 | ❌ | Infrastructure |
+| summarizer | 15 | 497 | ❌ | Other |
+| scripts | 13 | 598 | ❌ | Other |
+| rules | 10 | 586 | ❌ | Other |
+| detectors | 10 | — | ❌ | Other |
+| analyzers | 4 | — | ❌ | Other |
+| enrichers | 3 | — | ❌ | Other |
+| architect.js | 2 | 281 | ❌ | Other |
+| app | 1 | 7 | ❌ | UI |
+
+> ... e mais 41 módulos.
+
+### Integrações Externas Detectadas
+
+- **AWS S3** (storage) — detectado em `s3`
+
+## 🔧 Toolchain Detectado
+
+```bash
+# Build
+npm run build
+
+# Testes
+npm test
+
+# Lint
+npm run lint
+
+# Coverage
+npm run test -- --coverage
+
+# Dev Server
+npm run dev
+
+# Instalar dependências
+npm install
+
+```
+
+> **Deps file:** `package.json`
+
+
+---
+
+## 🔄 Protocolo de Orquestração (5 Fases)
+
+### FASE 0: Parsing da Requisição
+
+Ao receber qualquer requisição, CLASSIFICAR imediatamente:
+
+```
+✓ Nome da feature/fix: _______________
+✓ Tipo: [ ] Feature  [ ] Bug Fix  [ ] Refactoring  [ ] Documentation
+✓ Camadas tocadas: [ ] Backend  [ ] Frontend  [ ] Mobile  [ ] Database
+✓ Tem UI: [ ] Sim  [ ] Não
+✓ Complexidade: [ ] XS (<2h)  [ ] S (2-4h)  [ ] M (4-8h)  [ ] L (1-3d)  [ ] XL (3d+)
+✓ Assunções (listar): _______________
+✓ Riscos identificados: _______________
+```
+
+Se houver QUALQUER dúvida na classificação → **PERGUNTAR ao humano**.
+
+### FASE 1: Interrogação de Negócio
+
+Antes de qualquer design, RESPONDER estas perguntas:
+
+- **Q1: Quem são os atores envolvidos? (personas)**
+- **Q2: Qual o impacto em receita/negócio?**
+- **Q3: Existem regras de negócio específicas?**
+- **Q4: Quais métricas de sucesso?**
+- **Q5: Há requisitos de compliance (LGPD, PCI, etc)?**
+- **Q6: Quais módulos/serviços são afetados?**
+- **Q7: Quais entidades de banco são tocadas?**
+- **Q8: Existe fluxo de dados entre sistemas?**
+- **Q9: Precisa de versionamento de API?**
+- **Q10: Há integrações externas envolvidas?**
+- **Q11: Como isso se alinha com o domínio devtools?**
+- **Q13: Como essa mudança afeta as integrações com AWS S3?**
+- **Q13: Quem precisa de autenticação?**
+- **Q14: Quais permissões são necessárias?**
+- **Q15: Há dados sensíveis envolvidos?**
+- **Q16: Quais ameaças são relevantes?**
+
+> **Se não conseguir responder ≥ 70% das perguntas relevantes → PERGUNTAR ao humano.**
+
+### FASE 2: Disparo de Agentes (Paralelo)
+
+```
+ORQUESTRADOR decompõe a requisição
+    │
+    ├──→ [TYPESCRIPT-BACKEND-DEVELOPER] (agent-generator, html-reporter, summarizer)
+    │    • Arquitetura de serviços e APIs
+    │    • Lógica de negócio e validações
+    │    • Entities, DTOs, migrations
+    │
+    ├──→ [SECURITY-AUDITOR]
+    │    • Análise de ameaças (STRIDE)
+    │    • Compliance check
+    │
+    ├──→ [QA-TEST-ENGINEER]
+    │    • Plano de testes
+    │    • Cobertura mínima: 80%
+    │
+    └──→ [TECH-DEBT-CONTROLLER]
+         • Débito técnico existente
+         • Refatorações pré-requisito
+    │
+    └──→ CONSOLIDAÇÃO
+```
+
+Cada agente recebe:
+- Contexto do projeto (score, stack, anti-patterns)
+- Requisição decomposta (sua parte)
+- Constraints (regras, patterns proibidos)
+- Output esperado (formato e escopo)
+
+### FASE 3: Consolidação
+
+O orquestrador consolida as respostas dos agentes em:
+
+1. **Plano Unificado** com:
+   - Diagrama de arquitetura (C4)
+   - Cenários BDD
+   - Casos de teste TDD
+   - Estimativa de esforço (T-shirt)
+   - Riscos e mitigações
+   - Decisões arquiteturais (ADR)
+
+2. **6 Gates para Aprovação** (apresentar um de cada vez):
+   - Gate 1: MOCKUP → `/approved`
+   - Gate 2: User Stories → `/approved`
+   - Gate 3: Arquitetura → `/approved`
+   - Gate 4: Tasks → `/approved`
+   - Gate 5: BDD → `/approved`
+   - Gate 6: TDD → `/approved`
+
+### FASE 4: Implementação (Após Todas Aprovações)
+
+```
+╔════════════════════════════════════════════════╗
+║  ORDEM OBRIGATÓRIA DE IMPLEMENTAÇÃO:          ║
+║                                                ║
+║  1° BACKEND                                    ║
+║     └─→ Controllers, Services, Entities, DTOs  ║
+║     └─→ Testes unitários + integração          ║
+║     └─→ Migrations (se houver)                 ║
+║                                                ║
+║  2° DOCUMENTO DE INTEGRAÇÃO                    ║
+║     └─→ Endpoints, payloads, erros             ║
+║     └─→ Exemplos de request/response           ║
+║     └─→ Contrato para frontend/app             ║
+║                                                ║
+║  3° FRONTEND / APP                             ║
+║     └─→ Baseado no documento de integração     ║
+║     └─→ Componentes, pages, state              ║
+║     └─→ Testes e2e                             ║
+╚════════════════════════════════════════════════╝
+```
+
+### FASE 5: Verificação e Entrega
+
+```
+□ Build compila sem erros
+□ Todos os testes passam
+□ Cobertura ≥ 80%
+□ Score ≥ 70/100
+□ Zero anti-patterns CRITICAL novos
+□ Sem regressão de score
+□ Lint sem warnings
+□ Documentação atualizada
+```
+
+---
+
+## 📐 Templates Inline
+
+### Template: User Story
+
+```markdown
+## US-XXX: [Título]
+
+**Como** [ator],
+**Quero** [ação],
+**Para** [benefício].
+
+### Critérios de Aceite
+
+- CA1: [critério mensurável]
+- CA2: [critério mensurável]
+- CA3: [critério mensurável]
+
+### Regras de Negócio
+
+- RN1: [regra]
+- RN2: [regra]
+
+### Notas Técnicas
+
+- [observação relevante]
+```
+
+### Template: Task Breakdown
+
+```markdown
+## TASK-XXX: [Título]
+
+**User Story:** US-XXX
+**Estimativa:** [XS|S|M|L|XL]
+**Camada:** [Backend|Frontend|App|Database]
+**Agente:** [nome do agente]
+
+### Descrição
+[o que precisa ser feito]
+
+### Critério de Done
+- [ ] Implementado
+- [ ] Testado (cobertura ≥ 80%)
+- [ ] Code review
+- [ ] Documentação
+```
+
+### Template: ADR (Architecture Decision Record)
+
+```markdown
+## ADR-XXX: [Título da Decisão]
+
+**Status:** [proposed | accepted | deprecated | superseded]
+**Data:** [YYYY-MM-DD]
+
+### Contexto
+[Por que essa decisão é necessária?]
+
+### Decisão
+[O que foi decidido?]
+
+### Consequências
+[Positivas e negativas]
+
+### Alternativas Consideradas
+1. [alternativa 1] — descartada porque...
+2. [alternativa 2] — descartada porque...
+```
+
+---
+
+## ⚖️ Matriz de Risco
+
+| Risco | Probabilidade | Impacto | Mitigação |
+|-------|-------------|---------|-----------|
+| Regressão de testes | Média | Alto | CI/CD com gate obrigatório |
+| Degradação de score | Média | Médio | architect score antes de PR |
+| Breaking changes em API | Alta | Crítico | Versionamento + integration doc |
+| Security vulnerability | Baixa | Crítico | SECURITY-AUDITOR em toda feature |
+| Performance degradation | Média | Alto | Benchmark antes/depois |
+
+---
+
+## 🏷️ T-Shirt Sizing
+
+| Size | Duração | Scope | Gates |
+|------|---------|-------|-------|
+| **XS** | < 2h | Fix pontual, 1 arquivo | Simplificado (skip mockup se sem UI) |
+| **S** | 2-4h | Fix + teste, 2-3 arquivos | Gates 2, 5, 6 obrigatórios |
+| **M** | 4-8h | Feature pequena, 1 camada | Todos os 6 gates |
+| **L** | 1-3 dias | Feature multi-camada | Todos + ADR |
+| **XL** | 3+ dias | Feature épica | Todos + ADR + Threat Model |
+
+---
+
+## 🔀 Protocolo de Conflitos
+
+Quando dois agentes discordam:
+
+1. **Identificar** o ponto de conflito
+2. **Documentar** ambas as posições com prós/contras
+3. **Escalar** ao humano com recomendação
+4. **Registrar** a decisão como ADR
+
+> **NUNCA resolver conflitos automaticamente.** O humano decide.
+
+---
+
+## 🔧 Quality Gates (Enforcement)
+
+```
+╔══════════════════════════════════════════╗
+║  BUILD GATE                              ║
+║  $ npm run build
+║  Resultado: PASS ou BLOCK                ║
+╠══════════════════════════════════════════╣
+║  TEST GATE                               ║
+║  $ npm test
+║
+║  Resultado: PASS ou BLOCK                ║
+╠══════════════════════════════════════════╣
+║  COVERAGE GATE                           ║
+║  Mínimo: 80%                            ║
+║  Resultado: PASS ou BLOCK                ║
+║  ⚠️  INEGOCIÁVEL                         ║
+╠══════════════════════════════════════════╣
+║  SCORE GATE                              ║
+║  $ architect score ./src                 ║
+║  Mínimo: 70/100                        ║
+║  Regressão: NÃO PERMITIDA               ║
+╚══════════════════════════════════════════╝
+```
+
+---
+
+**Gerado por Architect v3.1 · Score: 94/100 · 2026-03-30**