jarvis-ai-framework 1.0.0

package/skills/eng-arch-c4/SKILL.md

@@ -0,0 +1,358 @@
+---
+name: eng-arch-c4
+description: Cria e mantém documentação de arquitetura usando C4 Model. Use quando precisar documentar sistemas com diagramas de Contexto, Container, Componente e Código.
+argument-hint: "[nivel: context|container|component|code] [sistema-opcional]"
+disable-model-invocation: false
+allowed-tools: Read Write Edit Grep Glob Bash MCP
+---
+
+# Arch C4 - Documentação de Arquitetura
+
+Você é um **especialista em documentação de arquitetura de software** usando o modelo C4 para criar "mapas do código" em diferentes níveis de abstração.
+
+## Objetivo
+
+Criar e manter documentação de arquitetura usando os 4 níveis do C4:
+- **Context**: Visão geral do sistema e interações externas
+- **Container**: Aplicações e datastores dentro do sistema
+- **Component**: Componentes dentro de cada container
+- **Code**: Detalhes de implementação (classes, interfaces) - raramente usado
+
+> **Nota sobre Nível 4 (Code)**: Raramente documentado manualmente porque IDEs geram diagramas UML automaticamente, código muda rápido e o próprio código é a melhor documentação. Usar apenas para algoritmos complexos, padrões críticos ou código legado.
+
+## Entrada
+
+- `$ARGUMENTS` - Nível do diagrama (context, container, component, code) e opcionalmente o sistema
+
+**Exemplos de uso:**
+
+```
+/arch-c4 context                    # Criar/Atualizar diagrama de contexto
+/arch-c4 container                  # Criar/Atualizar diagrama de containers
+/arch-c4 component api-backend      # Detalhar componentes de um container
+/arch-c4 code user-service          # Diagrama de código (raro)
+```
+
+## Recursos
+
+- **Script de detecção**: `$IDE/scripts/detect-stack.sh`
+- **Template**: `$IDE/templates/engineering/c4-model-template.md`
+- **Saída**: `$DOCS_FOLDER/engineering/c4/`
+
+### Exemplos de Output
+
+| Nível | Arquivo |
+|-------|---------|
+| Context | `$IDE/skills/eng-arch-c4/assets/example-context.md` |
+| Container | `$IDE/skills/eng-arch-c4/assets/example-container.md` |
+| Component | `$IDE/skills/eng-arch-c4/assets/example-component.md` |
+| Code | `$IDE/skills/eng-arch-c4/assets/example-code.md` |
+
+---
+
+## Pré-requisito
+
+**IMPORTANTE**: Antes de executar, verificar se o `ENV.md` existe e está configurado:
+
+```bash
+cat $IDE/ENV.md 2>/dev/null || echo "⚠️ ENV.md não encontrado. Execute /init-jarvis primeiro."
+```
+
+---
+
+## Hierarquia C4
+
+```
+Context   -> Quem usa? Com quem integra?
+    | zoom
+Container -> Quais apps, APIs, bancos?
+    | zoom
+Component -> Quais módulos internos?
+    | zoom
+Code      -> Quais classes/interfaces críticas?
+```
+
+---
+
+## Fluxo de Trabalho
+
+### 1. Verificar Documentação Existente
+
+```bash
+ls -la $DOCS_FOLDER/engineering/c4/ 2>/dev/null || echo "Nenhum diagrama C4"
+ls -la $DOCS_FOLDER/architecture/adr/ 2>/dev/null
+```
+
+**Se existirem diagramas**: ler antes de modificar, propor atualizações incrementais.
+
+### 2. Detectar Stack e Padrões
+
+Executar script de detecção:
+
+```bash
+bash $IDE/scripts/detect-stack.sh
+```
+
+O script detecta automaticamente:
+- Linguagem e frameworks
+- ORM e bancos de dados
+- Mensageria e cache
+- Padrão arquitetural (Clean, Hexagonal, DDD, MVC)
+- Infraestrutura (Docker, CI/CD)
+
+### 3. Propor Diagrama (antes de criar)
+
+**IMPORTANTE**: Sempre apresentar proposta ao usuário antes de gerar o diagrama.
+
+```markdown
+## Proposta de Diagrama C4 - {Nível}
+
+### Elementos Identificados
+
+| Elemento | Tipo | Descrição |
+|----------|------|-----------|
+| {nome} | {Person/System/Container/Component} | {descrição} |
+
+### Relacionamentos
+
+| De | Para | Descrição |
+|----|------|-----------|
+| {origem} | {destino} | {ação} |
+
+### Perguntas Pendentes
+
+- [ ] {dúvida sobre o sistema que precisa ser esclarecida}
+
+---
+
+Posso prosseguir com a geração do diagrama?
+```
+
+> **Aguardar aprovação do usuário antes de gerar o diagrama.**
+
+### 4. Criar/Atualizar Diagrama
+
+| Nível | Quando Usar | Saída |
+|-------|-------------|-------|
+| Context | Primeiro diagrama, big picture | `01-context.md` |
+| Container | Arquitetura de alto nível | `02-container.md` |
+| Component | Detalhar um container | `03-component-{nome}.md` |
+| Code | Componentes complexos (raro) | `04-code-{nome}.md` |
+
+Ver templates em `$IDE/templates/engineering/c4-model-template.md`
+
+### 5. Validar Diagrama
+
+Após criar, verificar consistência:
+
+```bash
+# Comparar elementos do diagrama com código real
+ls -d src/*/ 2>/dev/null
+
+# Verificar se containers existem
+cat docker-compose.yml 2>/dev/null | grep -E "^\s+\w+:"
+```
+
+---
+
+## Guia por Nível
+
+### Context (Nível 1)
+
+**Perguntas a responder:**
+1. Quem são os usuários do sistema?
+2. Com quais sistemas externos ele se comunica?
+3. Qual o propósito principal do sistema?
+
+**Checklist:**
+- [ ] Sistema principal identificado
+- [ ] Usuários/personas mapeados
+- [ ] Sistemas externos identificados
+- [ ] Propósito claro
+
+### Container (Nível 2)
+
+**Perguntas a responder:**
+1. Quais aplicações compõem o sistema?
+2. Quais bancos de dados são usados?
+3. Como os containers se comunicam?
+4. Há filas ou mensageria?
+
+**Checklist:**
+- [ ] Todos os containers identificados
+- [ ] Tecnologias documentadas
+- [ ] Comunicação clara
+- [ ] Bancos e filas mapeados
+
+### Component (Nível 3)
+
+**Perguntas a responder:**
+1. Quais são os principais módulos/serviços?
+2. Como eles se relacionam?
+3. Quais padrões são usados (MVC, Clean, Hexagonal)?
+
+**Checklist:**
+- [ ] Componentes principais identificados
+- [ ] Responsabilidades claras
+- [ ] Dependências mapeadas
+
+### Code (Nível 4) - Raramente usado
+
+**Perguntas a responder:**
+1. Quais classes/interfaces são críticas?
+2. Há algoritmos complexos que precisam ser documentados?
+3. Existem padrões de design importantes (Factory, Strategy)?
+
+**Quando usar:** Apenas para algoritmos complexos, padrões críticos ou código legado difícil de entender.
+
+---
+
+## Formato do Documento
+
+```markdown
+# {Nível} - {Nome}
+
+## Visão Geral
+{Descrição breve}
+
+## Diagrama
+{PlantUML ou Mermaid}
+
+## Elementos
+| Elemento | Tipo | Descrição | Tecnologia |
+|----------|------|-----------|------------|
+
+## Relacionamentos
+| De | Para | Descrição | Protocolo |
+|----|------|-----------|-----------|
+
+## ADRs Relacionados
+| ADR | Título | Impacto |
+|-----|--------|---------|
+
+## Changelog
+### [Data] - vX.Y
+- Mudança: {descrição}
+- Motivo: {justificativa}
+```
+
+---
+
+## Fluxo de Atualização
+
+Quando já existem diagramas:
+
+```bash
+# Ver mudanças arquiteturais recentes
+git log --oneline -20 -- "src/" "docker-compose*" "Dockerfile*"
+git diff origin/main --name-only | grep -E "docker|config|src/(domain|infrastructure)"
+```
+
+| Mudança Detectada | Nível | Ação |
+|-------------------|-------|------|
+| Novo sistema externo | Context | Adicionar |
+| Novo container/serviço | Container | Adicionar |
+| Novo módulo/componente | Component | Atualizar |
+
+---
+
+## Integração com ADRs
+
+| Situação | ADR | C4 |
+|----------|-----|-----|
+| Novo sistema externo | Sim | Atualizar Context |
+| Novo banco de dados | Sim | Atualizar Container |
+| Mudança de pattern | Sim | Atualizar Component |
+
+---
+
+## Regras
+
+### Nunca
+- Inventar elementos que não existem no código
+- Documentar sem analisar o código real
+- Misturar níveis de abstração no mesmo diagrama
+- Criar novos diagramas sem verificar existentes
+- Gerar diagrama sem aprovação do usuário
+- Executar sem verificar o ENV.md
+
+### Sempre
+- Verificar ENV.md antes de iniciar
+- Analisar código antes de documentar
+- Verificar diagramas existentes primeiro
+- Propor antes de criar
+- Usar nomenclatura consistente com o código
+- Incluir tecnologias nos containers
+- Manter changelog atualizado
+- Referenciar ADRs relacionados
+
+---
+
+## Checklist de Conclusão
+
+- [ ] ENV.md verificado
+- [ ] Documentação existente verificada
+- [ ] Stack detectada com script
+- [ ] Proposta apresentada ao usuário
+- [ ] Aprovação obtida
+- [ ] Diagrama criado/atualizado
+- [ ] Consistência validada
+- [ ] Changelog adicionado
+- [ ] ADRs referenciados (se aplicável)
+
+---
+
+## Mensagem de Conclusão
+
+```
+✅ Diagrama C4 criado/atualizado!
+
+📄 Arquivo: $DOCS_FOLDER/engineering/c4/{arquivo}.md
+📊 Nível: {nivel}
+🏗️ Sistema: {nome}
+
+Stack detectada:
+- Linguagem: {language}
+- Framework: {framework}
+- Pattern: {pattern}
+
+Próximos passos:
+1. Revisar diagrama gerado
+2. Validar com o time
+3. Criar próximo nível se necessário
+
+Referência: https://c4model.com
+```
+
+---
+
+## Tratamento de Erros
+
+### ENV.md não encontrado
+- Interromper execução
+- Orientar usuário a executar `/init-jarvis` primeiro
+
+### Script de detecção não encontrado
+- Executar detecção manual com comandos básicos
+- Verificar `package.json`, `docker-compose.yml`
+
+### Diagrama existente desatualizado
+- Comparar com código atual
+- Propor atualizações incrementais
+- Não recriar do zero
+
+### Usuário não aprovou proposta
+- Perguntar o que ajustar
+- Refinar elementos/relacionamentos
+- Apresentar nova proposta
+
+---
+
+## Ferramentas
+
+| Ferramenta | Uso |
+|------------|-----|
+| PlantUML | Diagramas como código |
+| C4-PlantUML | Extensão C4 para PlantUML |
+| Mermaid | Alternativa mais simples |
+| Structurizr | Ferramenta oficial C4 |

package/skills/eng-arch-c4/assets/example-code.md

@@ -0,0 +1,189 @@
+# Code - Skill Validator
+
+## Visão Geral
+
+Diagrama de código (Nível 4) do componente Skill Validator, mostrando as classes e interfaces responsáveis por validar a estrutura dos skills.
+
+> **Nota**: Este nível é raramente usado. Documentado aqui apenas como exemplo de referência para algoritmos complexos ou padrões críticos.
+
+## Diagrama
+
+```plantuml
+@startuml
+!theme plain
+skinparam classAttributeIconSize 0
+skinparam classFontStyle bold
+
+title Diagrama de Código - Skill Validator
+
+' === INTERFACES ===
+interface ISkillValidator {
+  +validate(skill: Skill): ValidationResult
+  +validateFrontmatter(frontmatter: Frontmatter): ValidationResult
+  +validateContent(content: string): ValidationResult
+}
+
+interface IValidationRule {
+  +name: string
+  +validate(value: any): boolean
+  +getErrorMessage(): string
+}
+
+interface ISkillRepository {
+  +findByName(name: string): Promise<Skill>
+  +exists(name: string): Promise<boolean>
+}
+
+' === VALUE OBJECTS ===
+class SkillName <<Value Object>> {
+  -value: string
+  +{static} create(value: string): SkillName
+  +validate(): boolean
+  +toString(): string
+  +isKebabCase(): boolean
+}
+
+class SkillDescription <<Value Object>> {
+  -value: string
+  -trigger: string
+  +{static} create(value: string): SkillDescription
+  +hasTrigger(): boolean
+  +getTrigger(): string
+}
+
+' === ENTIDADES ===
+class Skill <<Entity>> {
+  -name: SkillName
+  -description: SkillDescription
+  -argumentHint: string
+  -allowedTools: string[]
+  -content: string
+  --
+  +{static} create(props: CreateSkillProps): Skill
+  +getName(): SkillName
+  +getDescription(): SkillDescription
+  +getAllowedTools(): string[]
+  +hasRequiredFields(): boolean
+}
+
+class Frontmatter <<Value Object>> {
+  -name: string
+  -description: string
+  -argumentHint: string
+  -disableModelInvocation: boolean
+  -allowedTools: string[]
+  --
+  +{static} parse(yaml: string): Frontmatter
+  +toSkill(): Skill
+  +isValid(): boolean
+}
+
+class ValidationResult <<Value Object>> {
+  -isValid: boolean
+  -errors: ValidationError[]
+  --
+  +{static} success(): ValidationResult
+  +{static} failure(errors: ValidationError[]): ValidationResult
+  +addError(error: ValidationError): void
+  +hasErrors(): boolean
+  +getErrors(): ValidationError[]
+}
+
+class ValidationError <<Value Object>> {
+  -field: string
+  -message: string
+  -rule: string
+  --
+  +{static} create(field: string, message: string, rule: string): ValidationError
+  +toString(): string
+}
+
+' === REGRAS DE VALIDAÇÃO ===
+class RequiredFieldRule <<Rule>> {
+  -fieldName: string
+  +validate(value: any): boolean
+  +getErrorMessage(): string
+}
+
+class KebabCaseRule <<Rule>> {
+  +validate(value: string): boolean
+  +getErrorMessage(): string
+}
+
+class DescriptionTriggerRule <<Rule>> {
+  +validate(value: string): boolean
+  +getErrorMessage(): string
+}
+
+' === SERVIÇO DE VALIDAÇÃO ===
+class SkillValidator <<Service>> {
+  -rules: IValidationRule[]
+  -repository: ISkillRepository
+  --
+  +validate(skill: Skill): ValidationResult
+  +validateFrontmatter(frontmatter: Frontmatter): ValidationResult
+  +validateContent(content: string): ValidationResult
+  -applyRules(value: any, rules: IValidationRule[]): ValidationError[]
+}
+
+' === RELACIONAMENTOS ===
+Skill -- SkillName : identity
+Skill -- SkillDescription : contains
+Skill ..> Frontmatter : created from
+
+Frontmatter ..> Skill : creates
+
+ValidationResult -- ValidationError : contains
+
+SkillValidator ..|> ISkillValidator : implements
+SkillValidator --> IValidationRule : uses
+SkillValidator --> ISkillRepository : uses
+SkillValidator ..> ValidationResult : returns
+SkillValidator ..> Skill : validates
+
+RequiredFieldRule ..|> IValidationRule
+KebabCaseRule ..|> IValidationRule
+DescriptionTriggerRule ..|> IValidationRule
+
+@enduml
+```
+
+## Elementos
+
+| Elemento | Tipo | Descrição | Responsabilidade |
+|----------|------|-----------|------------------|
+| ISkillValidator | Interface | Contrato de validação de skills | Define métodos de validação |
+| IValidationRule | Interface | Contrato de regra de validação | Define estrutura de regras |
+| ISkillRepository | Interface | Contrato de repositório | Acesso a skills existentes |
+| SkillName | Value Object | Nome do skill | Validação de formato kebab-case |
+| SkillDescription | Value Object | Descrição com trigger | Extração de trigger de uso |
+| Skill | Entity | Entidade principal | Representa um skill completo |
+| Frontmatter | Value Object | Metadados YAML | Parse e validação de frontmatter |
+| ValidationResult | Value Object | Resultado da validação | Agrupa erros encontrados |
+| ValidationError | Value Object | Erro individual | Representa um erro específico |
+| RequiredFieldRule | Rule | Regra de campo obrigatório | Valida presença de campo |
+| KebabCaseRule | Rule | Regra de formato | Valida formato kebab-case |
+| DescriptionTriggerRule | Rule | Regra de trigger | Valida presença de "Use quando" |
+| SkillValidator | Service | Serviço de validação | Orquestra validação completa |
+
+## Padrões Utilizados
+
+| Padrão | Onde | Por quê |
+|--------|------|---------|
+| Value Object | SkillName, ValidationResult | Imutabilidade e validação no construtor |
+| Strategy | IValidationRule | Regras intercambiáveis |
+| Repository | ISkillRepository | Abstração de acesso a dados |
+| Result Object | ValidationResult | Evita exceções para fluxo de validação |
+
+## ADRs Relacionados
+
+| ADR | Título | Impacto |
+|-----|--------|---------|
+| ADR-005 | Padrão de validação | Define uso de Result Object |
+| ADR-006 | Value Objects para domínio | Define imutabilidade |
+
+## Changelog
+
+### [2025-01-24] - v1.0
+- Criação: Diagrama de código do Skill Validator
+- Motivo: Documentar padrões de validação como referência

package/skills/eng-arch-c4/assets/example-component.md

@@ -0,0 +1,105 @@
+# Component - Skills Engine
+
+## Visão Geral
+
+Diagrama de componentes do Skills Engine, detalhando os módulos internos responsáveis por processar e executar skills do JARVIS Framework.
+
+## Diagrama
+
+```plantuml
+@startuml C4_Component
+!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
+
+LAYOUT_WITH_LEGEND()
+
+title Skills Engine - Componentes
+
+Container_Boundary(skills, "Skills Engine") {
+
+    ' === ENTRADA ===
+    Component(parser, "Skill Parser", "Markdown Parser", "Interpreta frontmatter e conteúdo do skill")
+    Component(validator, "Skill Validator", "TypeScript", "Valida estrutura e campos obrigatórios")
+    Component(loader, "Skill Loader", "Filesystem", "Carrega skills do diretório")
+    
+    ' === PROCESSAMENTO ===
+    Component(resolver, "Variable Resolver", "TypeScript", "Resolve variáveis como $IDE, $DOCS_FOLDER")
+    Component(executor, "Skill Executor", "MCP/Shell", "Executa comandos e ferramentas permitidas")
+    Component(context, "Context Manager", "TypeScript", "Gerencia contexto da sessão")
+    
+    ' === SAÍDA ===
+    Component(formatter, "Output Formatter", "Markdown", "Formata saída para o usuário")
+    Component(logger, "Activity Logger", "Filesystem", "Registra atividades e erros")
+}
+
+' === EXTERNOS ===
+Container(cli, "CLI Interface", "Shell")
+Container(templates, "Template Engine", "Markdown")
+Container(rules, "Rules Engine", "Markdown")
+ContainerDb(env, "ENV Config", "Markdown")
+ContainerDb(sessions, "Sessions", "Filesystem")
+
+' === FLUXO DE ENTRADA ===
+Rel(cli, loader, "Solicita skill")
+Rel(loader, parser, "Envia conteúdo")
+Rel(parser, validator, "Valida estrutura")
+
+' === FLUXO DE PROCESSAMENTO ===
+Rel(validator, resolver, "Skill válido")
+Rel(resolver, env, "Lê variáveis")
+Rel(resolver, executor, "Skill resolvido")
+Rel(executor, context, "Atualiza contexto")
+Rel(executor, templates, "Usa templates")
+Rel(executor, rules, "Aplica regras")
+
+' === FLUXO DE SAÍDA ===
+Rel(executor, formatter, "Resultado")
+Rel(formatter, cli, "Resposta formatada")
+Rel(executor, logger, "Registra atividade")
+Rel(context, sessions, "Persiste sessão")
+
+@enduml
+```
+
+## Elementos
+
+| Elemento | Tipo | Descrição | Tecnologia |
+|----------|------|-----------|------------|
+| Skill Parser | Componente | Interpreta frontmatter e conteúdo do skill | Markdown Parser |
+| Skill Validator | Componente | Valida estrutura e campos obrigatórios | TypeScript |
+| Skill Loader | Componente | Carrega skills do diretório | Filesystem |
+| Variable Resolver | Componente | Resolve variáveis como $IDE, $DOCS_FOLDER | TypeScript |
+| Skill Executor | Componente | Executa comandos e ferramentas permitidas | MCP/Shell |
+| Context Manager | Componente | Gerencia contexto da sessão | TypeScript |
+| Output Formatter | Componente | Formata saída para o usuário | Markdown |
+| Activity Logger | Componente | Registra atividades e erros | Filesystem |
+
+## Relacionamentos
+
+| De | Para | Descrição | Protocolo |
+|----|------|-----------|-----------|
+| CLI Interface | Skill Loader | Solicita skill | Função |
+| Skill Loader | Skill Parser | Envia conteúdo | Interno |
+| Skill Parser | Skill Validator | Valida estrutura | Interno |
+| Skill Validator | Variable Resolver | Skill válido | Interno |
+| Variable Resolver | ENV Config | Lê variáveis | Filesystem |
+| Variable Resolver | Skill Executor | Skill resolvido | Interno |
+| Skill Executor | Context Manager | Atualiza contexto | Interno |
+| Skill Executor | Template Engine | Usa templates | Filesystem |
+| Skill Executor | Rules Engine | Aplica regras | Filesystem |
+| Skill Executor | Output Formatter | Resultado | Interno |
+| Output Formatter | CLI Interface | Resposta formatada | Função |
+| Skill Executor | Activity Logger | Registra atividade | Filesystem |
+| Context Manager | Sessions | Persiste sessão | Filesystem |
+
+## ADRs Relacionados
+
+| ADR | Título | Impacto |
+|-----|--------|---------|
+| ADR-002 | Integração via MCP | Define protocolo do executor |
+| ADR-004 | Variáveis de ambiente | Define comportamento do resolver |
+
+## Changelog
+
+### [2025-01-24] - v1.0
+- Criação: Diagrama de componentes do Skills Engine
+- Motivo: Documentar arquitetura interna do processador de skills