npm package: @giovannyesposito/titan-agents
Description: TITAN Method - Multi-agent framework with 6 specialized agents for product development
Author: Giovanny Esposito
Latest version: 1.2.1

# 🎭 TITAN Method™ — Framework Multi-Agente de IA para Desenvolvimento de Produtos

[![NPM Version](https://img.shields.io/npm/v/@giovannyesposito/titan-agents.svg)](https://www.npmjs.com/package/@giovannyesposito/titan-agents)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Status: Production Ready](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)]()
[![Language: Portuguese](https://img.shields.io/badge/Language-Portuguese%20🇧🇷-blue)]()

---

## 🚀 1-Comando Install

**Uma linha. Pronto.**

```bash
npx @giovannyesposito/titan-agents
```

Isso é tudo! Os 7 agentes TITAN Method (incluindo Ragni, o Skill Builder) agora estão disponíveis em VS Code. ✨

---

## 📋 O que é TITAN Method™?

**TITAN Method™** é um framework de IA multi-agente que traz **7 especialistas virtuais** para sua equipe de desenvolvimento de produtos. Após instalar, acesse cada agente com um simples `@` no GitHub Copilot.

### 👥 Os 7 Agentes Especializados

| Agente | Especialidade | Invocar |
|--------|---------------|---------|
| **Odin** | Orquestração & Coordenação | `@odin` |
| **Bragi** | Análise & Descoberta | `@bragi` |
| **Thor** | Product Management | `@thor` |
| **Freyja** | UX/Design | `@freyja` |
| **Heimdall** | Arquitetura & Tech | `@heimdall` |
| **Frigg** | QA & Backlog | `@frigg` |
| **Ragni** | Skill Builder & Context Architect | `@ragni` |

### 🎯 Casos de Uso

✅ **Descoberta** — Bragi faz market research e valida ideias  
✅ **Estratégia** — Thor cria PRDs e roadmaps  
✅ **Design** — Freyja desenha interfaces e fluxos  
✅ **Arquitetura** — Heimdall escolhe tech stacks e escalabilidade  
✅ **Qualidade** — Frigg valida stories e gerencia testes  
✅ **Orquestração** — Odin coordena múltiplos agentes em workflows  

---

## ⚡ Início Rápido (30 segundos)

### Pré-requisitos

- ✅ [VS Code](https://code.visualstudio.com/)
- ✅ [Extensão GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
- ✅ Node.js 14+ (ou use `npx` direto)
- ✅ Qualquer projeto local

### 1️⃣ Instale

```bash
npx @giovannyesposito/titan-agents
```

### 2️⃣ Recarregue o VS Code

`Ctrl+Shift+P` → "Developer: Reload Window"

### 3️⃣ Comece a Usar

Abra o GitHub Copilot Chat e digite:

```
@bragi ajude-me com pesquisa de mercado para essa funcionalidade
```

---

## � Como Usar os Agentes

Abra o **GitHub Copilot Chat** em VS Code e digite `@` seguido do nome do agente.

### 📊 Bragi — Descoberta & Análise

```
@bragi faça pesquisa de mercado de ferramentas de e-learning
@bragi identifique oportunidades no mercado de IA
@bragi analise a concorrência do nosso produto
```

**Especialidades:** Pesquisa de mercado, ideação, análise competitiva, validação de hipóteses

---

### 📦 Thor — Estratégia de Produto

```
@thor crie um PRD para autenticação com OAuth
@thor faça priorização com RICE dos itens de backlog
@thor defina o roadmap para Q1 2026
```

**Especialidades:** PRD, roadmap, priorização (RICE/MoSCoW), OKRs, go-to-market

---

### 🎨 Freyja — Design & UX

```
@freyja desenhe fluxo de onboarding para novos usuários
@freyja melhore a acessibilidade desta interface
@freyja padronize componentes em um design system
```

**Especialidades:** UI/UX, wireframes, design systems, WCAG 2.1, micro-interações

---

### 🏗️ Heimdall — Arquitetura & Tecnologia

```
@heimdall escolha tech stack para escalar 1M usuários
@heimdall desenhe arquitetura de microserviços
@heimdall otimize performance do banco de dados
```

**Especialidades:** Arquitetura de sistemas, DDD, escolha de tecnologia, escalabilidade, performance

---

### ✅ Frigg — Qualidade & Backlog

```
@frigg valide essas histórias de usuário
@frigg gere critérios de aceitação para esta funcionalidade
@frigg priorize o backlog de testes
```

**Especialidades:** Refinamento de histórias, critérios de aceitação, gerenciamento de backlog, planejamento de sprints

---

### 🎭 Odin — Orquestrador Mestre

```
@odin coordene Descoberta + Design + Dev para lançar nova funcionalidade
@odin agende um workshop com todos os agentes
```

**Especialidades:** Coordenação multi-agente, orquestração de workflows, planejamento cross-funcional

---

### ✨ Ragni — Skill Builder & Context Architect

```
@ragni criar skill customizado para autenticacao baseado em .rag/
@ragni adapte backend-dev-guidelines para meu projeto fintech
@ragni leia .rag/project-context/ e gere expertise especializada
```

**Especialidades:** Criar/variar Skills customizados, integração com `.rag/`, transformação de documentação em expertise

**O que faz:**
- 🔍 Lê documentação de projeto em `.rag/documents/` e `.rag/project-context/`
- 🎨 Varia Skills existentes adaptando-os para seu domínio
- ✨ Cria Skills novos do zero com contexto específico do projeto
- ✅ Valida YAML frontmatter e qualidade

---

## 🎯 Exemplo Prático: Lançar uma Funcionalidade

**Workflow completo com coordenação de agentes:**

```
1. @bragi descubra o problema real que usuários têm
   "Qual é o principal problema de gestores de projetos?"
   
2. @thor converta isso em PRD e roadmap
   "Organize os requisitos em PRD + roadmap de lançamento"
   
3. @freyja desenhe a experiência do usuário
   "Crie wireframes para o fluxo de onboarding"
   
4. @heimdall escolha a arquitetura e tech stack
   "Qual arquitetura escalável para 100k usuários?"
   
5. @frigg refine histórias e critérios de aceitação
   "Quebre essas funcionalidades em histórias com critérios de aceitação"
   
6. @ragni adapte skills para domínio específico
   "Crie skill backend-payment adaptado para nosso contexto"
   
7. @odin coordene apresentação integrada
   "Copie todos aqui e apresente a visão completa"
```

**Resultado:** Você tem um plano completo, validado por 7 especialistas (com expertise customizada), em minutos.

---

## 📦 O que Você Recebe

**38+ Skills Especializados** cobrindo:

- **Descoberta (4):** Pesquisa de mercado, análise competitiva, testes A/B, análise de dados
- **Design (2):** UI/UX, design systems
- **Backend (5):** Fullstack, REST/GraphQL, arquitetura de banco de dados, segurança
- **Arquitetura (8):** Padrões, DDD (estratégia + tática), ADRs, conformidade
- **Frontend (1):** React, Next.js, design responsivo
- **QA (6):** TDD, debugging, automação de navegador, testes e2e, code review
- **DevOps (6):** Observabilidade, rastreamento, SLOs, resposta a incidentes, performance
- **Segurança (8):** Segurança de API, padrões de autenticação, OWASP, varredura de vulnerabilidades

**MAIS:** Sistema `.rag/` para documentação perene de projeto + geração automática de Skills customizados

---

## 🏗️ Arquitetura

Após `npx @giovannyesposito/titan-agents`, sua estrutura fica assim:

```
seu-projeto/
├── .github/
│   ├── agents/                    ← Oculto do usuário
│   │   ├── 01-odin-orquestrador/
│   │   ├── 02-bragi-analista/
│   │   ├── 03-thor-gerente-produtos/
│   │   ├── 04-freyja-ux-designer/
│   │   ├── 05-heimdall-arquiteto/
│   │   ├── 06-frigg-qa/
│   │   ├── 07-ragni-skill-builder/
│   │   └── README.md
│   ├── skills/                    ← 38 especialidades
│   └── instructions/              ← Sistema de instruções
├── .rag/                          ← Repositório de contexto (NOVO)
│   ├── README.md
│   ├── documents/                 ← Documentação perene
│   └── project-context/           ← Contexto por projeto
├── .vscode/
│   └── agents-index.json          ← Auto-configurado
├── .hooks/
│   └── pre-commit                 ← Proteção de secrets
├── .env.example                   ← Documentação de variáveis
├── setup-security.ps1             ← Configuração de segurança
├── package.json
└── seu-codigo/
```

**Nada exposto.** Usuários só veem `@agente` no VS Code.

---

---

## ✨ Recursos Principais

| Recurso | Status |
|--------|--------|
| **7 Agentes especializados** | ✅ |
| **38+ Skills técnicas** | ✅ |
| **Instalação NPM (1 comando)** | ✅ |
| **Zero configuração manual** | ✅ |
| **Orquestração multi-agente** | ✅ |
| **Construtor de Skills (Ragni)** | ✅ |
| **Repositório .rag integrado** | ✅ |
| **Proteção de segurança (v1.1.0)** | ✅ |
| **38+ MB de conhecimento** | ✅ |

---

## 📚 Repositório .rag — Documentação Perene e Context de Projeto

### O que é .rag/?

O repositório `.rag/` (**Resilient Architecture & Guidelines**) é um sistema de documentação perene integrado que permite você:

- 📝 **Manter documentação centralizada** do seu projeto em um formato estruturado
- 🎯 **Criar Skills customizados** baseados no contexto específico do seu domínio
- 🔄 **Compartilhar conhecimento** entre todos os 7 agentes
- 🚀 **Escalar expertise** sem duplicação ou inconsistência

### Estrutura do .rag/

Após instalação, você terá um repositório `.rag/` assim:

```
.rag/
├── README.md                                  ← Guia completo do .rag
│
├── documents/                                 ← Documentação perene (versão global)
│   ├── business-rules.md                      ← Regras de negócio e constraints
│   ├── domain-glossary.md                     ← Dicionário de termos & linguagem ubíqua
│   ├── technical-decisions.md                 ← ADRs (Architecture Decision Records)
│   ├── api-specifications.md                  ← Especificações de API
│   ├── database-schema.md                     ← Esquema e padrões de banco de dados
│   ├── TEMPLATE-business-rules.md             ← Template pronto para copiar
│   └── README.md                              ← Índice de documentação
│
└── project-context/                           ← Contexto específico por projeto/produto
    ├── [seu-projeto-1]/
    │   ├── context.md                         ← Visão geral do projeto
    │   ├── stakeholders.md                    ← Stakeholders e roles
    │   ├── constraints.md                     ← Constraints técnicas & comerciais
    │   ├── goals.md                           ← Objetivos & OKRs
    │   └── tech-stack.md                      ← Stack tecnológico específico
    │
    └── [seu-projeto-2]/
        ├── context.md
        └── ...
```

### 🎯 Como Usar Ragni com .rag/

**Passo 1:** Preencha documentação

```bash
# Editar documentação global
vim .rag/documents/business-rules.md
vim .rag/documents/domain-glossary.md

# Editar contexto específico do seu projeto
vim .rag/project-context/[seu-projeto]/context.md
vim .rag/project-context/[seu-projeto]/constraints.md
```

**Passo 2:** Peça ao Ragni para criar/adaptar Skills

```
@ragni "Criar skill backend customizado para [seu-projeto]
        lendo contexto de .rag/project-context/[seu-projeto]/context.md
        e aplicando regras de .rag/documents/business-rules.md"

ou

@ragni "Adaptar skill 'backend-dev-guidelines' para
        o domínio de [seu-projeto], usando glossário de .rag/documents/domain-glossary.md
        e constraints de .rag/project-context/[seu-projeto]/"
```

**Passo 3:** Use os Skills customizados nos outros agentes

```
@heimdall "Usando o contexto de .rag/project-context/[seu-projeto]/tech-stack.md,
          escolha arquitetura ótima para escala de 1M usuários"

@frigg "Leia .rag/project-context/[seu-projeto]/constraints.md
       e crie acceptance criteria validando essas constraints"
```

### 💡 Benefício Real

**Seus agentes falam a mesma linguagem que seu projeto**, com:
- ✅ Regras e constraints reais do negócio
- ✅ Glossário consistente (domínio de linguagem ubíqua)
- ✅ Decisões técnicas já contextualizadas
- ✅ Constraints comerciais e financeiras consideradas
- ✅ Stack tecnológico específico respeitado

### 📖 Mais Informações

Veja [.rag/README.md](.rag/README.md) para guia detalhado de como estruturar documentação e integrar com workflows.

---

## 📖 Documentação

- **[NPM Package](https://www.npmjs.com/package/@giovannyesposito/titan-agents)** — Instalação via npm
- **[GitHub Repository](https://github.com/giovannyesposito/titan-agile-projects-agents)** — Código fonte
- **[INSTALLATION.md](INSTALLATION.md)** — Guia completo de instalação
- **[SECURITY.md](SECURITY.md)** — 🔒 Políticas de segurança & proteções
- **[.rag README](.rag/README.md)** — Guia do repositório de contexto
- **[Issues & Suporte](https://github.com/giovannyesposito/titan-agile-projects-agents/issues)** — Reporte bugs

---

## 🛠️ Comandos Úteis

```bash
# Instalar TITAN Agents no seu projeto
npx @giovannyesposito/titan-agents

# Re-instalar (atualizar agentes)
npx @giovannyesposito/titan-agents --force

# Configurar segurança (recomendado)
pwsh setup-security.ps1

# Verificar instalação
ls .github/agents/
cat .vscode/agents-index.json
cat .rag/README.md
```

---

## ⚠️ Resolução de Problemas

### Agentes não aparecem em VS Code

1. Execute `npx @giovannyesposito/titan-agents` novamente
2. Recarregue o VS Code: `Ctrl+Shift+P` → "Developer: Reload Window"
3. Abra o GitHub Copilot Chat e digite `@`

### Node.js não está instalado

```bash
# Instale Node.js em https://nodejs.org/
# Ou use npm globalmente:
npm install -g @giovannyesposito/titan-agents
```

### Secrets aparecem no histórico do git

Execute o setup de segurança para instalar proteção:

```bash
pwsh setup-security.ps1
```

Isso ativa:
- ✅ Pre-commit hook para detectar secrets
- ✅ Criação automática de `.env` isolado
- ✅ Validação de `.gitignore`

---

## 🎉 Comece Agora

```bash
# 1. Instale (30 segundos)
npx @giovannyesposito/titan-agents

# 2. Configure segurança (recomendado)
pwsh setup-security.ps1

# 3. Recarregue o VS Code
# Ctrl+Shift+P → "Developer: Reload Window"

# 4. Use os agentes!
# Abra GitHub Copilot Chat (Ctrl+I) e digite:
@bragi descubra oportunidades no nosso mercado
```

---

## 📄 Licença

Licenciado sob [MIT License](LICENSE). Uso livre em projetos comerciais.

---

## 👤 Autor

**Giovanny Esposito**  
📧 [giovannyesposito@gmail.com](mailto:giovannyesposito@gmail.com)  
🐙 [@giovannyesposito](https://github.com/giovannyesposito)  

---

## 🙏 Agradecimentos

- OpenAI e Anthropic por IA extraordinária
- GitHub por Copilot
- Comunidade open-source por inspiração

---

<div align="center">

### ⭐ Gostou? Deixe uma estrela no [repositório](https://github.com/giovannyesposito/titan-agile-projects-agents)! ⭐

**TITAN Method™ v1.1** — Production Ready com Segurança ✅

</div>