@girardelli/architect 2.2.0 → 4.0.0

package/src/agent-generator/templates/core/index-md.ts

@@ -0,0 +1,260 @@
+import { TemplateContext } from '../../types.js';
+
+/**
+ * Generates enterprise-grade INDEX.md — master navigation guide for the agent framework.
+ * ~350+ lines with: mandatory reads, situational guide, agent catalog, templates, flow diagram.
+ */
+export function generateIndexMd(ctx: TemplateContext): string {
+  const { report, stack, projectName, stackLabel, plan, config } = ctx;
+
+  const agents = buildAgentCatalog(ctx);
+  const situationalGuide = buildSituationalGuide(ctx);
+  const templates = buildTemplatesCatalog();
+
+  return `# ${projectName} — Agent Framework
+
+> **Auto-generated by [Architect v3.1](https://github.com/camilooscargbaptista/architect)**
+> Stack: **${stackLabel}** | Score: **${report.score.overall}/100** | Files: **${report.projectInfo.totalFiles}** | Lines: **${report.projectInfo.totalLines.toLocaleString()}**
+
+---
+
+## ⛔ 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.
+
+${situationalGuide}
+
+---
+
+## 🤖 Agentes Disponíveis
+
+${agents}
+
+---
+
+## 📋 Templates Disponíveis
+
+${templates}
+
+---
+
+## 📁 Estrutura do Framework
+
+\`\`\`
+.agent/
+├── INDEX.md              ← VOCÊ ESTÁ AQUI
+├── agents/               → Agentes especializados
+│   ├── AGENT-ORCHESTRATOR.md
+${stack.hasBackend ? `│   ├── ${stack.primary.toUpperCase()}-BACKEND-DEVELOPER.md\n` : ''}${stack.hasFrontend ? `│   ├── FRONTEND-DEVELOPER.md\n` : ''}${stack.hasMobile ? `│   ├── FLUTTER-UI-DEVELOPER.md\n` : ''}${stack.hasDatabase ? `│   ├── DATABASE-ENGINEER.md\n` : ''}│   ├── 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 ≥ ${config.coverageMinimum}%
+│  (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: ${String(report.score.overall).padEnd(2)}/100                        │
+│  Meta: ${String(Math.min(100, report.score.overall + 10)).padEnd(3)}/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: ${report.score.overall}/100 · ${new Date().toISOString().split('T')[0]}**
+`;
+}
+
+function buildAgentCatalog(ctx: TemplateContext): string {
+  const { stack } = ctx;
+  const rows: string[] = [];
+
+  rows.push('| Agente | Role | Capabilities |');
+  rows.push('|--------|------|-------------|');
+  rows.push('| [AGENT-ORCHESTRATOR](./agents/AGENT-ORCHESTRATOR.md) | coordination | Decomposição, dispatch, consolidação, quality gate |');
+
+  if (stack.hasBackend) {
+    rows.push(`| [${stack.primary.toUpperCase()}-BACKEND-DEVELOPER](./agents/${stack.primary.toUpperCase()}-BACKEND-DEVELOPER.md) | development | APIs, serviços, lógica de negócio, migrations |`);
+  }
+  if (stack.hasFrontend) {
+    const fw = stack.frameworks.find(f => ['Angular', 'Vue', 'Next.js', 'React'].includes(f)) || 'FRONTEND';
+    rows.push(`| [${fw.toUpperCase().replace('.', '')}-FRONTEND-DEVELOPER](./agents/${fw.toUpperCase().replace('.', '')}-FRONTEND-DEVELOPER.md) | development | Componentes, state management, UX responsiva |`);
+  }
+  if (stack.hasMobile) {
+    rows.push('| [FLUTTER-UI-DEVELOPER](./agents/FLUTTER-UI-DEVELOPER.md) | development | Screens, widgets, navegação, integração API |');
+  }
+  if (stack.hasDatabase) {
+    rows.push('| [DATABASE-ENGINEER](./agents/DATABASE-ENGINEER.md) | development | Schema, migrations, indexação, performance |');
+  }
+
+  rows.push('| [SECURITY-AUDITOR](./agents/SECURITY-AUDITOR.md) | quality | Ameaças STRIDE, OWASP, LGPD, vulnerabilidades |');
+  rows.push('| [QA-TEST-ENGINEER](./agents/QA-TEST-ENGINEER.md) | quality | Planos de teste, BDD/TDD, cobertura, regressão |');
+  rows.push('| [TECH-DEBT-CONTROLLER](./agents/TECH-DEBT-CONTROLLER.md) | governance | Débito técnico, refatorações, metas de score |');
+
+  return rows.join('\n');
+}
+
+function buildSituationalGuide(ctx: TemplateContext): string {
+  const { stack } = ctx;
+  const rows: string[] = [];
+
+  rows.push('| Ação | Leia antes | Workflow | Agente principal |');
+  rows.push('|------|-----------|---------|-----------------|');
+  rows.push('| Nova feature | 00-general + PREFLIGHT | [new-feature](./workflows/new-feature.md) | ORCHESTRATOR |');
+  rows.push('| Corrigir bug | 00-general + PREFLIGHT | [fix-bug](./workflows/fix-bug.md) | ORCHESTRATOR |');
+
+  if (stack.hasBackend) {
+    rows.push(`| Mexer em backend | 00-general + 01-architecture | new-feature ou fix-bug | ${stack.primary.toUpperCase()}-BACKEND |`);
+  }
+  if (stack.hasFrontend) {
+    rows.push('| Mexer em frontend | 00-general + 01-architecture | new-feature ou fix-bug | FRONTEND |');
+  }
+  if (stack.hasMobile) {
+    rows.push('| Mexer no app | 00-general | new-feature ou fix-bug | FLUTTER-UI |');
+  }
+  if (stack.hasDatabase) {
+    rows.push('| Mexer em banco | 00-general + 01-architecture | new-feature | DATABASE-ENGINEER |');
+  }
+
+  rows.push('| Segurança | 02-security | — | SECURITY-AUDITOR |');
+  rows.push('| Testes | 00-general | — | QA-TEST-ENGINEER |');
+  rows.push('| Refatoração | QUALITY-GATES | — | TECH-DEBT-CONTROLLER |');
+  rows.push('| Code review | CODE-REVIEW-CHECKLIST | [review](./workflows/review.md) | QA-TEST-ENGINEER |');
+
+  return rows.join('\n');
+}
+
+function buildTemplatesCatalog(): string {
+  return `| 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 |`;
+}