@orchestrator-claude/cli 1.4.0

package/dist/templates/base/claude/skills/docs-guardian/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: docs-guardian
+description: Analisa e sincroniza documentacao do projeto contra DOCS-CONSTITUTION. Use para verificar compliance de documentacao, detectar docs deslocados, e identificar candidatos a arquivamento.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Documentation Guardian Skill
+
+## Descricao
+
+Esta skill analisa a documentacao do projeto verificando:
+1. **Consistencia de Versao**: package.json vs git tags
+2. **Estrutura de Diretorios**: project-guidelines/ vs docs/
+3. **Documentos Deslocados**: Docs tecnicos em docs/, docs usuario em project-guidelines/
+4. **Candidatos a Arquivamento**: Tracking files, docs obsoletos (30+ dias)
+
+## Quando Usar
+
+Use esta skill quando:
+- Apos concluir implementacao de uma feature
+- Para verificar estado geral da documentacao
+- Antes de criar releases
+- Periodicamente para manter docs organizados
+
+## Modos
+
+| Modo | Descricao | Status |
+|------|-----------|--------|
+| `status` | Apenas analisa e reporta issues | Implementado |
+| `sync` | Analisa e corrige com confirmacao | Phase 2 |
+| `auto` | Analisa e corrige automaticamente | Phase 3 |
+
+## Invocacao
+
+Exemplos de como invocar esta skill:
+
+```
+"Analise a documentacao do projeto"
+
+"Execute /docs-guardian para verificar compliance"
+
+"Verifique se ha documentos deslocados"
+
+"Identifique candidatos a arquivamento"
+```
+
+## Parametros
+
+| Parametro | Tipo | Obrigatorio | Descricao |
+|-----------|------|-------------|-----------|
+| `mode` | enum | Nao | status, sync, auto (default: status) |
+| `format` | enum | Nao | console, markdown, json (default: console) |
+
+## Output
+
+A skill retorna resultado estruturado:
+
+```json
+{
+  "success": true,
+  "data": {
+    "summary": {
+      "totalFiles": 45,
+      "errors": 2,
+      "warnings": 5,
+      "infos": 38
+    },
+    "checkersExecuted": [
+      "VersionConsistencyChecker",
+      "DirectoryStructureChecker",
+      "MisplacedDocsChecker",
+      "ArchiveCandidatesChecker"
+    ],
+    "hasIssues": true,
+    "hasErrors": true
+  },
+  "message": "Documentation Guardian: 2 errors, 5 warnings, 38 infos"
+}
+```
+
+## Checkers Disponiveis
+
+### VersionConsistencyChecker
+
+Verifica se package.json version corresponde ao latest git tag.
+
+**Issues Detectados:**
+- Version mismatch (error)
+- Missing git tags (warning)
+- Invalid package.json (error)
+
+### DirectoryStructureChecker
+
+Verifica existencia de diretorios e arquivos obrigatorios.
+
+**Estrutura Esperada:**
+```
+project-guidelines/
+  rfcs/
+  adrs/
+  README.md
+  MASTER-INDEX.md
+
+docs/
+  README.md
+  migration/
+  examples/
+```
+
+### MisplacedDocsChecker
+
+Detecta documentos em diretorios incorretos.
+
+**Regras:**
+- Docs tecnicos (RFC, ADR, TRACKING, design) -> project-guidelines/
+- Docs usuario (tutorial, guide, getting-started) -> docs/
+
+### ArchiveCandidatesChecker
+
+Identifica documentos que devem ser arquivados.
+
+**Criterios:**
+- Arquivos sem modificacao por 30+ dias
+- Tracking files de fases/bugs concluidos
+- Documentos marcados como deprecated
+
+## Formatos de Saida
+
+### Console (Default)
+
+```
+============================================
+  Documentation Guardian - Status Report
+============================================
+
+Summary
+-----------
+  Total Files: 45
+  Errors: 2
+  Warnings: 5
+  Infos: 38
+
+Errors (2)
+-----------
+  [version] Version mismatch: package.json (1.0.3) != latest git tag (1.2.0)
+    File: package.json
+    Suggestion: Update package.json version to 1.2.0
+
+Warnings (5)
+-----------
+  [misplaced] Technical document found in user docs: docs/MIGRATION-v1.0.md
+    Suggestion: Move to project-guidelines/
+```
+
+### Markdown
+
+Gera relatorio formatado para inclusao em issues ou PRs.
+
+### JSON
+
+Retorna estrutura completa para integracao com outras ferramentas.
+
+## Integracao com DOCS-CONSTITUTION
+
+Esta skill le regras de `.orchestrator/memory/knowledge-base/contextual/DOCS-CONSTITUTION.md`:
+
+1. **Separacao de Concerns**: Regras para project-guidelines/ vs docs/
+2. **Versionamento**: Regras para semver, tags, CHANGELOG
+3. **Arquivamento**: Criterios para arquivar documentos
+4. **RFC Lifecycle**: Estados e transicoes de RFCs
+5. **Convencoes de Nomenclatura**: Padroes para nomes de arquivos
+
+## Exemplos de Uso
+
+### Verificacao Rapida
+```
+User: "Como esta a documentacao?"
+Skill: /docs-guardian mode=status format=console
+```
+
+### Relatorio para PR
+```
+User: "Gere relatorio de docs para o PR"
+Skill: /docs-guardian mode=status format=markdown
+```
+
+### Integracao CI/CD
+```
+User: "Verifique docs em JSON para pipeline"
+Skill: /docs-guardian mode=status format=json
+```
+
+## Comportamento em Caso de Erro
+
+### DOCS-CONSTITUTION Nao Encontrada
+```json
+{
+  "success": false,
+  "error": {
+    "code": "CONSTITUTION_NOT_FOUND",
+    "message": "DOCS-CONSTITUTION.md not found in knowledge-base"
+  }
+}
+```
+
+### Modo Nao Implementado
+```json
+{
+  "success": false,
+  "error": {
+    "code": "INVALID_MODE",
+    "message": "Mode 'sync' not implemented. Only 'status' is available."
+  }
+}
+```
+
+## Notas Importantes
+
+1. Mode=status **NAO** modifica arquivos, apenas reporta
+2. Errors devem ser corrigidos antes de releases
+3. Warnings sao recomendacoes, nao bloqueiam
+4. Infos sao sugestoes para melhoria continua
+5. Integra-se com workflow do Orchestrator
+
+## Roadmap
+
+- **Phase 1** (Atual): Read-only analysis (mode=status)
+- **Phase 2**: Interactive sync (mode=sync com confirmacao)
+- **Phase 3**: Auto-sync hook (mode=auto pos-IMPLEMENT)
+

package/dist/templates/base/claude/skills/kb-lookup/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: kb-lookup
+description: Busca informacoes na knowledge base do projeto (CONSTITUTION, ARCHITECTURE, artifacts). Use quando precisar consultar regras, decisoes arquiteturais, ou padroes do projeto.
+allowed-tools: Read, Grep, Glob
+---
+
+# Knowledge Base Lookup Skill
+
+## Descricao
+
+Esta skill busca informacoes na knowledge base do projeto, organizada em 3 tiers:
+
+### Tier 1: Core (Imutavel)
+- `.orchestrator/memory/knowledge-base/core/CONSTITUTION.md` - Regras fundamentais
+
+### Tier 2: Contextual (Projeto)
+- `.orchestrator/memory/knowledge-base/contextual/project-context.md` - Contexto do projeto
+- `.orchestrator/memory/knowledge-base/contextual/tech-stack.md` - Stack tecnologica
+- `.orchestrator/memory/knowledge-base/contextual/decisions/` - ADRs
+
+### Tier 3: Research (Cache)
+- `.orchestrator/memory/knowledge-base/research/` - Resultados de pesquisa Perplexity (TTL 24h)
+
+### Documentacao Adicional
+- `project-guidelines/ARCHITECTURE.md` - Decisoes arquiteturais
+- `project-guidelines/*.md` - Documentacao geral
+- `.orchestrator/artifacts/` - Artefatos de workflows
+
+## Quando Usar
+
+Use esta skill quando:
+- Precisar consultar regras de negocio do projeto
+- Verificar decisoes arquiteturais existentes
+- Buscar padroes usados anteriormente
+- Encontrar referencias em documentacao
+- Consultar artefatos de workflows anteriores
+
+## Invocacao
+
+Exemplos de como invocar esta skill:
+
+```
+"Busque na knowledge base sobre regras de autenticacao"
+
+"Consulte a CONSTITUTION sobre validacao de dados"
+
+"Encontre decisoes arquiteturais sobre persistencia"
+
+"Busque exemplos de especificacoes anteriores"
+
+"Qual o padrao de nomenclatura definido no projeto?"
+```
+
+## Parametros
+
+| Parametro | Tipo | Obrigatorio | Descricao |
+|-----------|------|-------------|-----------|
+| `query` | string | Sim | Termo ou pergunta a buscar |
+| `sources` | array | Nao | constitution, architecture, artifacts, docs, all (default: all) |
+| `limit` | number | Nao | Maximo de resultados (default: 10) |
+| `include_context` | boolean | Nao | Incluir contexto ao redor do match (default: true) |
+
+### Valores de sources
+
+- **constitution**: Busca apenas em CONSTITUTION.md
+- **architecture**: Busca apenas em ARCHITECTURE.md
+- **artifacts**: Busca em artefatos gerados (.orchestrator/artifacts/)
+- **docs**: Busca em project-guidelines/
+- **all**: Busca em todas as fontes
+
+## Output
+
+```json
+{
+  "query": "regras de autenticacao",
+  "searchedAt": "2025-12-09T10:30:00Z",
+  "sources": ["constitution", "architecture"],
+
+  "results": [
+    {
+      "source": "constitution",
+      "file": "project-guidelines/CONSTITUTION.md",
+      "section": "Seguranca > Autenticacao",
+      "relevance": 0.95,
+      "content": "## Autenticacao\n\nTodas as rotas da API devem ser protegidas...",
+      "context": {
+        "before": "# Regras de Seguranca\n\n",
+        "after": "\n\n## Autorizacao\n\n"
+      },
+      "lineNumbers": {
+        "start": 145,
+        "end": 162
+      }
+    },
+    {
+      "source": "architecture",
+      "file": "project-guidelines/ARCHITECTURE.md",
+      "section": "Infrastructure > Authentication",
+      "relevance": 0.88,
+      "content": "### Authentication Layer\n\nUsamos JWT tokens...",
+      "context": {
+        "before": "## Camada de Infraestrutura\n\n",
+        "after": "\n\n### Authorization Layer\n\n"
+      },
+      "lineNumbers": {
+        "start": 456,
+        "end": 478
+      }
+    }
+  ],
+
+  "summary": {
+    "totalResults": 2,
+    "sourcesSearched": 2,
+    "topRelevance": 0.95
+  },
+
+  "relatedQueries": [
+    "JWT tokens",
+    "autorizacao",
+    "seguranca API"
+  ]
+}
+```
+
+## Fontes de Conhecimento
+
+### Tier 1: Core (.orchestrator/memory/knowledge-base/core/)
+**Imutavel sem processo formal**
+- `CONSTITUTION.md`: Regras fundamentais, principios, padroes obrigatorios
+
+### Tier 2: Contextual (.orchestrator/memory/knowledge-base/contextual/)
+**Atualizado conforme projeto evolui**
+- `project-context.md`: Contexto do projeto atual
+- `tech-stack.md`: Stack tecnologica escolhida
+- `decisions/`: ADRs (Architecture Decision Records)
+
+### Tier 3: Research (.orchestrator/memory/knowledge-base/research/)
+**Cache com TTL de 24 horas**
+- Resultados de pesquisas Perplexity
+- Auto-invalidado apos expiracao
+- Regenerado sob demanda
+
+### Documentacao (project-guidelines/)
+**Documentacao tecnica do projeto**
+- `ARCHITECTURE.md`: Arquitetura completa
+- `INTEGRACAO-CLAUDE-CODE.md`: Integracao com Claude Code
+- `PLANO-EXECUCAO-v2.md`: Plano de execucao
+- Outros documentos de referencia
+
+### Artifacts (.orchestrator/artifacts/)
+**Artefatos gerados por workflows**
+- Especificacoes (specify/)
+- Planos (plan/)
+- Backlogs (tasks/)
+- Implementacoes (implement/)
+- Pesquisas (research/)
+
+## Integracao com TypeScript
+
+Esta skill invoca o handler TypeScript:
+
+```typescript
+// src/presentation/skills/KBLookupSkillHandler.ts
+
+export class KBLookupSkillHandler {
+  async handle(params: LookupParams): Promise<LookupResult> {
+    // 1. Parseia query para termos de busca
+    // 2. Seleciona fontes baseado em params.sources
+    // 3. Executa busca em cada fonte
+    // 4. Rankeia resultados por relevancia
+    // 5. Extrai contexto ao redor dos matches
+    // 6. Retorna resultados agregados
+  }
+}
+```
+
+## Exemplos de Uso
+
+### Busca em Fonte Especifica
+```
+User: "Consulte a CONSTITUTION sobre validacao"
+Skill: kb-lookup com sources=["constitution"]
+```
+
+### Busca Ampla
+```
+User: "Busque tudo sobre autenticacao no projeto"
+Skill: kb-lookup com sources=["all"]
+```
+
+### Busca em Artefatos
+```
+User: "Encontre especificacoes similares a OAuth"
+Skill: kb-lookup com sources=["artifacts"], query="OAuth"
+```
+
+## Comportamento de Busca
+
+### Matching
+- Busca case-insensitive
+- Suporta stemming (autentica -> autenticacao)
+- Busca em titulos tem peso maior
+- Matches exatos tem prioridade
+
+### Ranking de Relevancia
+```
+relevance = (
+  title_match * 0.4 +
+  section_match * 0.3 +
+  content_match * 0.2 +
+  recency * 0.1
+)
+```
+
+### Contexto
+- Inclui 3 linhas antes e depois por default
+- Preserva formatacao markdown
+- Indica secao/header pai
+
+## Casos Especiais
+
+### Query Ambigua
+Se query pode ter multiplos significados:
+- Retorna resultados de todas interpretacoes
+- Sugere queries mais especificas em `relatedQueries`
+
+### Sem Resultados
+```json
+{
+  "query": "blockchain",
+  "results": [],
+  "summary": {
+    "totalResults": 0,
+    "message": "Nenhum resultado encontrado para 'blockchain'"
+  },
+  "suggestions": [
+    "Verifique a ortografia",
+    "Tente termos mais genericos",
+    "Considere buscar na web se for tecnologia nova"
+  ]
+}
+```
+
+### Muitos Resultados
+Se mais de `limit` resultados:
+- Retorna os mais relevantes
+- Indica total disponivel
+- Sugere refinar query
+
+## Notas Importantes
+
+1. Esta skill e **read-only** - nao modifica knowledge base
+2. Resultados sao cacheados por 5 minutos
+3. Busca em artifacts considera apenas artefatos validados
+4. Relevancia < 0.5 indica match fraco - considere refinar query
+5. Use para informar decisoes, nao como fonte unica de verdade