@cortex-context/cli 0.0.5

package/dist/templates/local/cortex.config.template.yaml

@@ -0,0 +1,50 @@
+# cortex.config.yaml — Configuração do Cortex Knowledge Graph
+# Gerado por: cortex-context init
+# Documentação: https://github.com/rodrigoroldan/cortex-context
+
+project:
+  # Nome do projeto (aparece como rótulo nos nós do grafo)
+  name: "meu-projeto"
+
+  # Ambiente padrão para o manifesto (dev, staging, production)
+  environment: "dev"
+
+  # Prefixo de IDs para specs (ex: "spec" → spec-001, spec-002...)
+  spec_prefix: "spec"
+
+  # Serviços do projeto (usado para enriquecer arestas de dependência)
+  services: []
+  # - name: "backend"
+  #   repo_path: "../backend"
+  # - name: "frontend"
+  #   repo_path: "../frontend"
+  # - name: "bff"
+  #   repo_path: "../bff"
+
+# Configuração de ingestão
+ingest:
+  # Padrões de arquivo a excluir do diff analysis
+  exclude_patterns:
+    - "*.lock"
+    - "*.sum"
+    - "node_modules/**"
+    - ".git/**"
+    - "dist/**"
+    - "build/**"
+    - "target/**"
+    - "__pycache__/**"
+    - "*.pyc"
+    - ".env"
+    - ".env.*"
+
+  # Padrões de arquivo de spec (nós do tipo "spec" são extraídos daqui)
+  spec_patterns:
+    - "specs/**/*.md"
+    - "docs/specs/**/*.md"
+
+# APM enrichment (opcional — adiciona dados de observabilidade aos nós)
+apm:
+  enabled: false
+  # provider: "openobserve"
+  # url: "https://logs.rolds.dev"
+  # token: "..."

package/dist/templates/local/docker-compose.local.yml

@@ -0,0 +1,57 @@
+# docker-compose.local.yml — Cortex stack local
+# Gerado por: cortex-context init --local
+#
+# Uso:
+#   docker compose -f docker-compose.local.yml up -d
+#   docker compose -f docker-compose.local.yml down
+#
+# Acesso:
+#   Cortex API:  http://localhost:8082
+#   Neo4j UI:    http://localhost:7474  (usuário: neo4j / senha: cortex-local)
+
+services:
+  neo4j:
+    image: neo4j:5.21-community
+    container_name: cortex-neo4j-local
+    environment:
+      NEO4J_AUTH: neo4j/cortex-local
+      NEO4J_PLUGINS: '["apoc"]'
+      NEO4J_dbms_security_procedures_unrestricted: apoc.*
+      NEO4J_dbms_memory_heap_initial__size: 256m
+      NEO4J_dbms_memory_heap_max__size: 512m
+    ports:
+      - "7474:7474"
+      - "7687:7687"
+    volumes:
+      - cortex_neo4j_data:/data
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:7474"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  cortex-api:
+    image: ghcr.io/rodrigoroldan/cortex-context:latest
+    container_name: cortex-api-local
+    environment:
+      NEO4J_URI: bolt://neo4j:7687
+      NEO4J_USER: neo4j
+      NEO4J_PASSWORD: cortex-local
+      CORTEX_API_TOKEN: ${CORTEX_API_TOKEN:-dev-token-local}
+      LOG_LEVEL: INFO
+    ports:
+      - "8082:8082"
+    depends_on:
+      neo4j:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8082/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+volumes:
+  cortex_neo4j_data:
+    driver: local

package/dist/templates/rules/copilot-instructions-cortex.md

@@ -0,0 +1,22 @@
+## 🧠 Cortex Product Knowledge Graph
+
+Before implementing any feature, use the Cortex MCP tools to check for existing specs and context:
+
+- **`query_product_context`**: Semantic search — use with keywords before starting any work
+- **`get_spec_context`**: Get full details of a specific spec (spec-NNN) including related nodes
+- **`get_service_context`**: Understand what specs affect a given service
+- **`list_features`**: List features by status (planned, in-progress, completed, deprecated)
+- **`list_dimensions`**: Explore graph dimensions (specs, services, temporal workflows, etc.)
+- **`get_node_context`**: Explore any node + 1-hop neighbors
+
+**Rule**: Always call `query_product_context` before planning or implementing any feature.
+This prevents duplicate work and ensures you have full product context.
+
+**Example**:
+
+```
+# Before implementing payment feature:
+query_product_context("pagamento PIX rateio cobrança")
+get_spec_context("spec-042")  # if relevant spec found
+get_service_context("backend")  # understand service dependencies
+```

package/dist/templates/skills/cortex-dimensions/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: cortex-dimensions
+description: >
+  Skill para explorar dimensões genéricas do Cortex além de spec/service.
+  Use quando o usuário quiser listar ou explorar dimensões disponíveis, buscar
+  por workflows Temporal no grafo, explorar tipos de nós disponíveis, ou precisar
+  de informação sobre qualquer entidade que não seja spec ou serviço.
+  Triggers: "listar dimensões cortex", "dimensões disponíveis", "quais workflows temporal",
+  "explorar dimensão X", "temporal workflow no cortex", "temporal workflow context",
+  "que outros tipos de nós existem", "dimensão X do grafo".
+---
+
+# Skill: Cortex Dimensions — Discovery de Dimensões Genéricas
+
+## Propósito
+
+Explorar o grafo Cortex de forma **agnóstica** — sem assumir quais tipos de nós existem.
+O Cortex é extensível: além de `spec` e `service`, pode conter `temporal_workflow`,
+`bff_route`, e futuras dimensões adicionadas sem mudança no código do MCP.
+
+---
+
+## Quando Usar
+
+| Situação | Ação |
+|----------|------|
+| Não sabe quais dimensões existem | `list_dimensions()` primeiro |
+| Quer ver Temporal Workflows no grafo | `list_dimensions()` → `get_node_context("temporal_workflow", id)` |
+| "Quais workflows o Cortex conhece?" | `list_dimensions()` + `get_node_context` por dim_key |
+| Explorar qualquer dimensão nova | `list_dimensions()` → inspecionar dim_key → `get_node_context` |
+| Busca por entidade não-spec/service | `list_dimensions()` → identificar dim_key correto |
+
+---
+
+## Tools MCP Disponíveis
+
+### 1. `list_dimensions` — Discovery de dimensões
+
+**Sempre chame primeiro** quando não souber o `dim_key` correto.
+
+```
+Parâmetros: nenhum
+
+Retorna: tabela com {dim_key, node_label, contagem_de_nós}
+```
+
+Exemplo de resposta:
+```
+| dim_key           | node_label        | nós |
+|-------------------|------------------|-----|
+| spec              | Spec             | 122 |
+| service           | Service          | 8   |
+| temporal_workflow | TemporalWorkflow | 15  |
+```
+
+---
+
+### 2. `get_node_context` — Detalhe de qualquer nó
+
+Use após descobrir o `dim_key` correto via `list_dimensions`.
+
+```
+Parâmetros:
+  dim_key: str   # chave da dimensão, ex: "temporal_workflow"
+  node_id: str   # ID do nó, ex: "workflow-finance-reconciliation"
+
+Retorna: propriedades do nó + vizinhos 1-hop com tipo de relacionamento
+```
+
+---
+
+## Fluxo: Explorar Temporal Workflows no Cortex
+
+```
+1. list_dimensions()
+   → Confirma que "temporal_workflow" existe com N nós
+
+2. Para listar todos os workflows disponíveis:
+   Não existe um tool de listagem genérica por ID — use o output de list_dimensions
+   para confirmar a dimensão existe, então faça chamadas com IDs conhecidos.
+
+   IDs de TemporalWorkflow (nomenclatura padrão):
+   workflow-finance-reconciliation, workflow-overdue-installment,
+   workflow-psp-reconciliation, workflow-pricing-psp-review,
+   workflow-event-publication, workflow-outbound-execution,
+   workflow-invite-lifecycle, workflow-payment-expiration,
+   workflow-participant-lifecycle, workflow-notification-fallback,
+   workflow-accounting-snapshot, workflow-event-publication-monitoring,
+   workflow-participant-recalculation, workflow-payment-confirmation,
+   workflow-sandbox
+
+3. get_node_context("temporal_workflow", "workflow-finance-reconciliation")
+   → Retorna schedule, status, mode_resolver, service_id, replaces (job substituído)
+```
+
+---
+
+## Fluxo: Descoberta Completa
+
+Quando o usuário pergunta algo sobre uma entidade e você não sabe qual dimensão usar:
+
+```
+1. list_dimensions()
+   → Identifica dim_keys disponíveis
+
+2. Se a dimensão é clara: get_node_context(dim_key, node_id)
+   → Retorna detalhes do nó + vizinhos
+
+3. Se não encontrar o ID exato:
+   → Para specs: use get_spec_context ou list_features
+   → Para services: use get_service_context
+   → Para workflows: use os IDs padrão listados acima
+```
+
+---
+
+## Dimensões Conhecidas (Referência)
+
+| dim_key | Tipo de Entidade | Exemplos de node_id |
+|---------|-----------------|---------------------|
+| `spec` | Features/Specs | `spec-070`, `spec-147` |
+| `service` | Serviços do sistema | `service-bff`, `service-backend` |
+| `temporal_workflow` | Workflows Temporal.io | `workflow-finance-reconciliation` |
+
+> **Nota**: Esta lista pode estar desatualizada. Use `list_dimensions()` para ver
+> as dimensões reais em produção com contagem atual de nós.
+
+---
+
+## Sobre os Temporal Workflows no Grafo
+
+O Cortex rastreia os **15 Temporal Workflows ativos** do backend com:
+- `schedule`: cron schedule (para workflows agendados)
+- `mode`: estado atual (DISABLED/SHADOW/PRIMARY)
+- `replaces`: job legado substituído
+- `queue`: task queue do worker
+- `status`: ativo/inativo
+
+Use `get_node_context("temporal_workflow", workflow_id)` para ver o estado atual
+e as relações com specs que o criaram ou modificaram.
+
+---
+
+## Output Format
+
+Quando apresentar resultados de `get_node_context`:
+- Mostre **todas as propriedades** do nó claramente formatadas
+- Agrupe os vizinhos por `label` (Spec, Service, etc.)
+- Mostre a **direção** da relação (`→ AFFECTS`, `← IMPLEMENTS`, etc.)
+- Se for um TemporalWorkflow, destaque `mode` e `schedule`

package/dist/templates/skills/cortex-generate-spec/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: cortex-generate-spec
+description: >
+  Synthetic PM skill — gera specs de features a partir de pedidos vagos.
+  Usa o Cortex para pesquisa semântica de contexto existente, faz perguntas
+  de refinamento ao usuário, e produz um plan.md completo pronto para revisão.
+  Use quando: "gerar spec", "criar plan.md", "quero especificar a feature X",
+  "escreve um plan.md para", "generate spec", "spec para feature", "criar spec",
+  "planejar feature", "planeja isso pra mim".
+---
+
+# Skill: Generate-Spec — Synthetic Product Manager
+
+## Propósito
+
+Agir como um **Product Manager técnico** para transformar uma ideia vaga em uma
+spec estruturada (`plan.md`) com contexto do produto, escopo definido, e plano
+de implementação. Usa o **Cortex Vector RAG + FTS** para encontrar features
+relacionadas antes de perguntar qualquer coisa ao usuário.
+
+---
+
+## Fluxo Obrigatório
+
+```
+1. PESQUISA CORTEX
+   ↓
+2. ANÁLISE DE IMPACTO
+   ↓
+3. PERGUNTAS DE REFINAMENTO (3-5 perguntas)
+   ↓
+4. GERAÇÃO DO PLAN.MD
+   ↓
+5. SALVAR ARQUIVO
+```
+
+---
+
+## Fase 1: Pesquisa Cortex (SEMPRE fazer antes de perguntar)
+
+### 1a. Busca Semântica (Vector RAG)
+
+Use o endpoint do Cortex para encontrar specs semanticamente relacionadas:
+
+```http
+POST {CORTEX_URL}/api/v1/query/semantic
+Authorization: Bearer {CORTEX_API_TOKEN}
+Content-Type: application/json
+
+{
+  "query": "{descrição da feature do usuário}",
+  "top_k": 10,
+  "hops": 1
+}
+```
+
+> **Fallback**: Se Vector RAG não estiver disponível (503), use FTS:
+> `GET /api/v1/query?keywords={keywords}&limit=10`
+
+### 1b. Busca por Keywords (FTS cross-validation)
+
+```http
+GET {CORTEX_URL}/api/v1/query?keywords={keywords_extraídas}&limit=8
+Authorization: Bearer {CORTEX_API_TOKEN}
+```
+
+### 1c. Checar Features em Andamento
+
+```http
+POST {CORTEX_URL}/api/v1/nodes
+Authorization: Bearer {CORTEX_API_TOKEN}
+Content-Type: application/json
+
+{
+  "query": "MATCH (n:Spec) WHERE n.status IN ['in-progress', 'planned'] RETURN n ORDER BY n.id LIMIT 20"
+}
+```
+
+---
+
+## Fase 2: Análise de Impacto
+
+Com os resultados do Cortex, analisar:
+
+1. **Há specs existentes sobre o mesmo tema?**
+   - Se sim: notar IDs (spec-NNN) e status — não duplicar esforço
+   - Se outra spec está `in-progress`: alertar usuário sobre conflito potencial
+
+2. **Quais serviços são afetados?**
+   - Extrair dos edges `AFFECTS` → Service nodes
+   - Montar lista: Frontend / BFF / Backend / Lambda / etc.
+
+3. **Há dependências críticas?**
+   - Edges `DEPENDS_ON` / `SUPERSEDES` / `MOTIVATED_BY`
+   - Specs bloqueantes ou que serão impactadas
+
+4. **Há ADRs relevantes?** (se dimensão `adr` ativa)
+   - Decisões arquiteturais que condicionam a feature
+
+---
+
+## Fase 3: Perguntas de Refinamento
+
+Formule **3-5 perguntas** focadas nos gaps identificados. Apresente ao usuário
+**antes** de gerar o plan.md. Exemplos de perguntas úteis:
+
+### Perguntas de Escopo
+- "O fluxo precisa funcionar offline (WebView sem conexão) ou sempre requer rede?"
+- "Há usuários com role diferente que precisam de comportamento distinto?"
+- "Isso precisa ser retroativo (afetar dados existentes) ou só novos registros?"
+
+### Perguntas de Impacto Financeiro / Legal
+- "Há movimentação financeira envolvida? Se sim, precisa de rastro contábil?"
+- "Há dados pessoais (PII) no fluxo? Impacto em LGPD?"
+
+### Perguntas de Conflito com Features Existentes
+- Se detectado spec em andamento: "A spec-NNN já cobre parte disso. Quer expandir ela ou criar uma nova?"
+- "Isso substitui algum comportamento atual? O que deve ser mantido?"
+
+### Perguntas de Critérios de Aceite
+- "Como saberemos que a feature está pronta? Qual é o happy path mínimo?"
+- "Há casos de erro específicos que precisam de UX dedicada?"
+
+### Perguntas de Prioridade / Ondas
+- "Precisa entregar tudo de uma vez ou pode ser incremental em ondas?"
+- "Qual é o prazo crítico, se houver?"
+
+---
+
+## Fase 4: Geração do plan.md
+
+### Estrutura obrigatória
+
+```markdown
+# Plan de Execução — Feature {NNN}
+
+## Visão Geral
+
+{Descrição clara do problema e da solução. 2-4 parágrafos.}
+
+**Specs relacionadas**: spec-NNN (status), spec-MMM (status)
+**Serviços afetados**: Frontend, BFF, Backend [, outros]
+**ADRs relevantes**: adr-slug (se houver)
+
+## Contexto de Produto
+
+{Por que isso é importante agora? Qual dor resolve? Qual oportunidade captura?}
+
+## Ondas de Implementação
+
+### Onda 1 — {Nome descritivo}
+
+- {Tarefa concreta}
+- {Tarefa concreta}
+
+**Resultado esperado**: {O que estará funcionando ao final desta onda}
+
+### Onda 2 — {Nome descritivo}
+{... mesmo formato}
+
+## Critérios de Aceite
+
+- [ ] {Critério testável e verificável}
+- [ ] {Critério testável e verificável}
+- [ ] {Critério testável e verificável}
+
+## Riscos e Mitigações
+
+| Risco | Probabilidade | Impacto | Mitigação |
+|-------|--------------|---------|-----------|
+| {risco} | Alta/Média/Baixa | Alto/Médio/Baixo | {mitigação} |
+
+## Decisões Técnicas Chave
+
+{Decisões que o time precisa tomar antes ou durante a implementação.}
+
+## Interfaces de API (se aplicável)
+
+{Novos endpoints, mudanças em contratos, DTOs relevantes.}
+
+## Notas Adicionais
+
+{Contexto de produto, histórico de decisões, links externos relevantes.}
+
+---
+**Criado em**: {data}
+**Status**: planned
+**Spec ID**: spec-{NNN}
+```
+
+### Numeração da Spec
+
+Para determinar o próximo NNN:
+
+```http
+GET {CORTEX_URL}/api/v1/nodes?label=Spec&limit=200
+Authorization: Bearer {CORTEX_API_TOKEN}
+```
+
+Pegar o maior número encontrado em `spec-{NNN}` e incrementar em 1.
+Se não conseguir via API, inspecionar `ls <seu-workspace>/specs/` e usar o maior número + 1.
+
+---
+
+## Fase 5: Salvar Arquivo
+
+### Criar diretório e arquivo
+
+```bash
+mkdir -p <seu-workspace>/specs/{NNN}-{slug}/
+```
+
+Salvar em:
+```
+<seu-workspace>/specs/{NNN}-{slug}/plan.md
+```
+
+**Slug**: kebab-case da feature. Máximo 5 palavras. Sem acentos.
+Exemplo: `078-withdraw-flow-v2`, `079-admin-event-moderation`
+
+---
+
+## Saída Final ao Usuário
+
+Após salvar, apresentar:
+
+```
+✅ Spec gerada: specs/{NNN}-{slug}/plan.md
+
+**Contexto encontrado**:
+- {N} specs relacionadas encontradas (spec-NNN, spec-MMM)
+- {N} serviços afetados (Frontend, BFF, Backend)
+- {N} conflitos/dependências identificados
+
+**Próximos passos sugeridos**:
+1. Revisar o plan.md gerado
+2. Ajustar prioridade das ondas se necessário
+3. Quando pronto: `Start Implementation` para iniciar o loop autônomo
+```
+
+---
+
+## Regras de Qualidade
+
+1. **NÃO gere a spec sem pesquisar o Cortex primeiro** — evita duplicação
+2. **NÃO invente informações técnicas** — pergunte se não tiver certeza
+3. **Faça perguntas ANTES de escrever** — a spec precisa do contexto do usuário
+4. **Seja conciso nas ondas** — cada onda deve ser entregável independente
+5. **Marque dependências externas** — se depende de spec não concluída, diga
+6. **Use o NNN correto** — nunca reutilize um número de spec existente
+
+---
+
+## Variáveis de Ambiente
+
+| Variável | Valor |
+|----------|-------|
+| `CORTEX_URL` | URL do seu servidor Cortex (ex: `http://localhost:8082`) |
+| `CORTEX_API_TOKEN` | Token definido no `.env` do seu servidor Cortex |
+
+Para obter o token localmente:
+```bash
+# Via .env do cortex
+cat <seu-cortex-dir>/.env | grep CORTEX_API_TOKEN
+```