jarvis-ai-framework 8.2.0 → 8.3.0

package/skills/jarvis-fork/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: jarvis-fork
+description: >
+  Ajusta o Jarvis a uma empresa sem editar o core: conduz uma conversa curta até achar onde um
+  workflow, skill, agente, rule ou template do core não está servindo, propõe o menor ajuste,
+  simula o efeito e, só com o Sim, grava o fork no overlay da empresa ($IDE/overlays/{COMPANY_PROFILE}/)
+  pelo CLI `jarvis fork`. Também lista (--list), atualiza (--update) e remove (--delete) forks, e
+  pergunta se o ajuste é só da empresa ou vale para o core (abre a issue pelo jarvis-report-issue).
+  Trigger: Use quando um comando do Jarvis insiste num fluxo que não é o da empresa (base da
+  branch, entrega, gates, template de MR, regra interna) ou quando alguém pede para "customizar
+  o Jarvis para este cliente".
+license: AGPL-3.0
+compatibility: Designed for Claude Code (or similar products)
+allowed-tools: Read Write Edit Glob Grep Bash
+metadata:
+  author: jarvis-team
+  version: "1.0"
+  area: global
+# Campos Claude Code-specific (não fazem parte da spec oficial agentskills.io):
+argument-hint: "[artefato] [--list|--update|--delete]"
+disable-model-invocation: false
+---
+
+# Jarvis Fork - Fork guiado de um artefato do core para o overlay da empresa
+
+Você é quem ajuda a pessoa a descobrir **onde, exatamente,** um comando do core não está ajudando nesta empresa, e a corrigir isso com o menor fork possível. A parte mecânica (copiar, carimbar, listar, comparar, remover) é do CLI `jarvis fork`; a sua parte é a conversa.
+
+## Objetivo
+
+Deixar a empresa com o fluxo dela sem copiar e editar o framework: o core continua intacto, o overlay (`$IDE/overlays/{COMPANY_PROFILE}/`) guarda só o que foi substituído, com carimbo de origem, e o `jarvis init --upgrade` não apaga nada disso. Cada fork nasce de uma dor concreta, e cada dor que todo cliente tem vira candidata a extension point do core.
+
+## Entrada
+
+- `$ARGUMENTS`:
+  - `{artefato}`: nome de workflow, skill ou agente (`eng.start`, `eng-global-pr`, `eng.agent`), ou caminho de rule/template (`rules/engineering/eng-rules.md`, `rules-on-demand/engineering/eng.pr-rules.md`, `templates/pull-request.md`)
+  - `--list`: o que está forkado no overlay ativo (só lista; não compara com o core)
+  - `{artefato} --update`: retoma a conversa sobre um fork que já existe
+  - `{artefato} --delete`: remove o fork; o core volta a valer
+
+## Recursos
+
+- **ENV**: `$IDE/ENV.md` (`COMPANY_PROFILE`: vazio = `stark-industries`, o overlay padrão)
+- **Rule de precedência**: `$IDE/rules/company-overlay-rules.md` (overlay > especialização de stack > core; é o que faz o fork valer na chamada)
+- **CLI**: `jarvis fork {nome} [--candidate]`, `jarvis fork --list`, `jarvis fork {nome} --update [--diff]`, `jarvis fork {nome} --delete` (o único que grava em `overlays/`)
+- **Sessões recentes**: `$SESSIONS_DIR/eng/*/` (architecture.md, plan.md, gate-checklist.md) que citem o artefato
+- **Custo**: `jarvis tokens` (quanto contexto o fork acrescenta)
+
+## Pré-requisito
+
+- `$IDE/ENV.md` existe (`jarvis init` + `/jarvis-init`). Sem ele, pare: `⛔ Sem ENV.md. Rode jarvis init e /jarvis-init antes de forkar.`
+- `COMPANY_PROFILE` vazio ou inválido não bloqueia: vale o default `stark-industries`, com o aviso do CLI. Se a pessoa quer um perfil próprio, sugira o `/jarvis-init` antes (ou depois, movendo os forks).
+
+## Quando Usar
+
+- Um comando do core assume um fluxo que não é o da empresa (de onde nasce a branch, como se entrega, quais gates valem, campos do MR)
+- Alguém pede para "customizar o Jarvis para este cliente" ou "o Jarvis insiste em X aqui"
+- Depois de um `jarvis init --upgrade`, para revisar forks antigos (`--update`) ou tirar os que não servem mais (`--delete`)
+- **Não use** para corrigir um bug do core (isso é `/jarvis-report-issue`) nem para stack de código (isso é especialização: `/jarvis-create-specialization`)
+
+## Padrões Críticos
+
+1. **Pergunte antes de propor.** Quem pede o fork sabe que algo incomoda, raramente sabe qual linha.
+2. **O menor fork que resolve.** Variável do `ENV.md` que já cobre o caso > fork de um arquivo pequeno (template, rule-on-demand) > fork de um workflow inteiro.
+3. **Nada é gravado sem o Sim.** O `jarvis fork` grava direto; você só o chama depois de mostrar o conteúdo final e perguntar.
+4. **O core não é editado.** Nem o pacote instalado, nem a cópia em `$IDE/` fora do que o CLI faz para rules.
+5. **Dados da dor, não da empresa**, em qualquer coisa que saia do workspace (a issue do alcance).
+
+## Fluxo de Trabalho
+
+### 0. Modo
+
+| Argumento | Siga |
+|---|---|
+| `--list` | Passo 6 |
+| `{artefato} --delete` | Passo 7 |
+| `{artefato} --update` | Passos 1 a 5 sobre o fork existente (o CLI só compara com o core com `--diff`, que você passa quando a pessoa pedir) |
+| `{artefato}` | Passos 1 a 5 e, no fim, o Passo 8 |
+
+Confira o artefato: `jarvis map {nome}` (workflows, skills, agentes) ou `ls` do caminho em `$IDE/`. Nome que não existe: pare com a mensagem do CLI (`⚠️ "{nome}" não é um artefato do core…`).
+
+### 1. Ouvir a dor (uma pergunta por vez, com `AskUserQuestion`)
+
+Antes de perguntar, leia as sessões recentes em `$SESSIONS_DIR/eng/*/` que citem o artefato (`grep -l`): o que já está registrado não se pergunta de novo. Depois:
+
+1. "O que aconteceu da última vez que o `{artefato}` rodou nesta empresa?"
+2. "Em que fase ou seção travou (ou fez a coisa errada)?"
+3. "O que você fez à mão depois?"
+
+Pare quando a dor couber em uma frase: "o `{artefato}` assume X; aqui é Y".
+
+### 2. Apontar onde encosta
+
+Leia o artefato do core (`$IDE/{tipo}/…`), liste as seções `##`/`###` e diga **em qual** o relato encosta, com link para a linha (`rules-on-demand/doc-links-rules.md`). Exemplo: "o que você descreveu acontece na Fase 2 do `eng-global-pr`, que assume a branch nascendo de `main`".
+
+### 3. Propor, com a conta
+
+`AskUserQuestion` com as opções que cabem, a recomendada primeiro e marcada "(Recomendada)":
+
+| Opção | Quando |
+|---|---|
+| **Variável do `ENV.md` que já resolve** | A seção já lê uma chave (`BRANCH_BASE`, `TASK_MANAGER`…). Sem fork |
+| **Fork de um arquivo pequeno** | Template, rule-on-demand ou rule que a seção lê |
+| **Fork do artefato inteiro** | Só quando a mudança está no fluxo em si |
+
+Em cada opção, a conta: linhas copiadas (`wc -l`) e tokens a mais na chamada (≈ bytes ÷ 4; `jarvis tokens` para o total do início da sessão). Diga por que recomenda.
+
+### 4. Simular o efeito
+
+Em texto, antes de gravar: **o que passa a acontecer** e **o que não muda**. Exemplo: "a branch passa a nascer da base que você indicou e o MR aponta para ela; o commit continua pelo padrão do CONTRIBUTING e o comentário no card continua só depois da pergunta".
+
+### 5. Gravar, só com o Sim
+
+1. Mostre o conteúdo final do arquivo como vai ficar **no overlay** (o core + o ajuste), com o caminho `$IDE/overlays/{COMPANY_PROFILE}/{caminho}`.
+2. `AskUserQuestion`: **Gravar no overlay?** → **Sim** / **Não**. Com Não, nada é gravado; encerre.
+3. Com Sim: `jarvis fork {artefato}` (copia o core com carimbo), depois aplique o ajuste **no arquivo do overlay** (nunca no do core). Rule e rule-on-demand: o CLI já recopia a versão da empresa em `$IDE/rules/` com a marcação; para os outros tipos, a rule de precedência faz valer na próxima chamada.
+4. Em `--update`: o fork já existe. Se a pessoa quiser ver o que o core mudou, rode `jarvis fork {artefato} --update --diff`: ele **só mostra** o diff fork × core atual, agrupado pela seção `#…` (linhas 🔴 são possível mudança de contrato: sessão, `ENV.md`, template, CLI), e **não grava nada**; o que trazer é decisão dela. Depois de aplicar o ajuste combinado no arquivo do overlay (com o Sim), rode `jarvis fork {artefato} --update` (sem `--diff`) para recarimbar; o recarimbo não altera o conteúdo, mas regrava o arquivo em LF (fork editado em CRLF vira LF). Fork **sem carimbo** (arquivo posto à mão no overlay): antes de qualquer coisa, pergunte `Carimbar {artefato} com a versão atual do core, sem alterar o conteúdo?` → **Sim** roda o `--update`; **Não** segue sem carimbar.
+
+### 6. `--list`
+
+Rode `jarvis fork --list` e mostre a saída: caminho, tipo, `forked_from`, `(sem carimbo)` para arquivo posto à mão, `candidato a core` e `⚠️ tipo não resolvido` para pasta fora dos seis tipos. Não compare nada com o core: a lista é a métrica da story (quais arquivos do core cada cliente forkou).
+
+### 7. `--delete`
+
+Mostre o caminho do fork e o `forked_from`. `AskUserQuestion`: **Remover o fork e voltar ao core?** → **Sim** / **Não**. Só com Sim: `jarvis fork {artefato} --delete` (rule volta à versão do core em `$IDE/rules/`).
+
+### 8. Alcance do ajuste (só em fork novo)
+
+`AskUserQuestion`: **Esse ajuste em `{artefato}` é só deste contexto (`{COMPANY_PROFILE}`) ou vale para o core do Jarvis?**
+
+| Resposta | O que fazer |
+|---|---|
+| **Apenas deste contexto** | Nada mais |
+| **Estender para o core** | Monte o texto de uma melhoria com **dados da dor**: comando, fase, o que o default assume, o que quebrou, o ajuste que resolveu. **Sem** o valor de `COMPANY_PROFILE`, nomes de pessoas, URLs de wiki ou trechos de `reference/`. Entregue ao `/jarvis-report-issue` (tipo melhoria), que mostra o texto e só abre com o Sim |
+| **Ainda não sei** | `jarvis fork {artefato} --candidate` já no passo 5 (ou recarimbe com `--update` depois de marcar `core_candidate: true` no frontmatter); aparece no `--list` como candidato a core |
+
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| 8. Alcance do ajuste | `/jarvis-report-issue` | Só com a resposta "Estender para o core", com o texto já sem dados da empresa |
+
+## Regras
+
+### Nunca
+- Gravar no overlay (ou chamar `jarvis fork`) sem o **Sim** da pergunta "Gravar no overlay?"
+- Editar o core: nem o pacote instalado, nem `$IDE/{tipo}/` à mão
+- Forkar o artefato inteiro quando uma variável do `ENV.md` ou um arquivo menor resolve
+- Pôr nome de cliente, de pessoa, URL interna ou trecho de `reference/` no texto que vai para a issue
+- Comparar fork × core por conta própria: o `--list` nunca compara, e o `--update` só compara com `--diff`, que você passa a pedido da pessoa
+- Decidir sozinho o que trazer do core para o fork
+
+### Sempre
+- Ler as sessões recentes antes de perguntar
+- Apontar a seção exata, com link para a linha
+- Mostrar a conta (linhas e tokens) e o efeito simulado antes de gravar
+- Usar o mesmo caminho e nome do core (o CLI garante)
+- Terminar um fork novo com a pergunta de alcance
+
+## Checklist de Conclusão
+
+- [ ] Dor registrada em uma frase e seção do core apontada com link
+- [ ] Opções mostradas com a conta e a recomendação
+- [ ] Efeito simulado (o que muda, o que não muda)
+- [ ] "Gravar no overlay?" respondida; com Sim, `jarvis fork` rodado e ajuste aplicado só no overlay
+- [ ] Rule/rule-on-demand: `$IDE/rules/…` com a linha `> Overlay:`; outros tipos: nada copiado para `$IDE/`
+- [ ] Pergunta de alcance respondida; issue (se houver) sem dados da empresa e só com o Sim
+- [ ] Nenhum arquivo do core alterado
+
+## Output
+
+- `$IDE/overlays/{COMPANY_PROFILE}/{caminho do artefato}` com `forked_from`, `forked_at` (e `core_candidate`) no frontmatter e o ajuste combinado
+- Para rule e rule-on-demand, a cópia em `$IDE/rules/…` ou `$IDE/rules-on-demand/…` com `> Overlay: {COMPANY_PROFILE} (…)`
+- Com "Estender para o core": a issue aberta pelo `/jarvis-report-issue` (ou o texto em `.jarvis/issues/`, sem o Sim)
+
+## Mensagem de Conclusão
+
+```
+✓ Fork gravado em $IDE/overlays/{COMPANY_PROFILE}/{caminho}
+  forked_from: {artefato}@{versão} · forked_at: {data}
+  Vale: {na próxima chamada (rule de precedência) | já na IDE, em $IDE/rules/… com a marcação}
+  Alcance: {apenas deste contexto | melhoria proposta ao core (#N) | candidato a core (--list)}
+
+Para rever: /jarvis-fork --list · /jarvis-fork {artefato} --update · /jarvis-fork {artefato} --delete
+```

package/skills/jarvis-init/SKILL.md

@@ -621,6 +621,7 @@ Se **A** ou **B**, perguntar sobre cada variável opcional conforme seleção
    - Nenhuma variável guarda token.
 4. **Vendor do git (`VERSION_CONTROL`):** `github`, `gitlab` ou vazio (Bitbucket/outro → não suportado, vazio). Faça a mesma descoberta do item 2 e defina `VERSION_CONTROL_ACCESS`. Não há variável de repositório: o repo e o host vêm do `git remote get-url origin`.
 5. **Gravação única:** guarde as respostas dos dois eixos e grave tudo no Passo 5, depois do "sim" no bloco final. Se o init for interrompido antes, nada é gravado.
+6. **Perfil de empresa (`COMPANY_PROFILE`):** o overlay é a camada da empresa por cima do core (`$IDE/overlays/{perfil}/`), só com o que o `/jarvis-fork` substituiu; todo workspace tem um, e o default é `stark-industries` (o overlay padrão do Jarvis). Pergunte com `AskUserQuestion`: **Manter o default `stark-industries`** (primeira opção) | **Nome da empresa** (texto livre, em kebab-case: letras minúsculas, números e hífen). Nome fora do padrão ou igual a uma pasta do core (`skills`, `rules`, `workflows`, `commands`, `agents`, `rules-on-demand`, `templates`, `scripts`, `overlays`) → mostre o motivo e pergunte de novo. A chave **nunca** fica vazia. A pasta vazia do perfil é criada pelo `jarvis init` e pelo Passo 8 (única escrita permitida em `$IDE/overlays/`); nenhum arquivo é gravado nela aqui.
 
 **Central docs:** não é perguntado aqui. Ele é ligado por padrão e configurado no **Passo 5.2**, que roda sempre.
 
@@ -628,6 +629,7 @@ Se **A** ou **B**, perguntar sobre cada variável opcional conforme seleção
 
 | Variável | Valor Padrão | Descrição |
 |----------|--------------|-----------|
+| `COMPANY_PROFILE` | `stark-industries` | Perfil de empresa: nome do overlay em `$IDE/overlays/{valor}/` (default = overlay padrão do Jarvis; nunca vazio) |
 | `TASK_MANAGER` | *(vazio = freelance)* | `jira`, `github`, `gitlab` |
 | `TASK_MANAGER_ACCESS` | *(vazio)* | `cli` ou `manual` (definido pela descoberta da CLI) |
 | `TASK_MANAGER_URL_BASE` | *(vazio)* | GitHub/GitLab: repositório dos cards (obrigatório); Jira: o site, só para o link |
@@ -1057,7 +1059,7 @@ Objetivo: garantir que `$IDE/rules/` e `$IDE/rules-on-demand/` contenham apenas
 
 ```
 1. Ler HUB, POSITION, AREA, SQUAD e ARTIFACT_STYLE (vazio = `ai-generated`) do ENV.md recém-gravado
-2. Para cada uma das duas pastas (rules/ e rules-on-demand/), listar todos os arquivos .md (recursivo, exceto AGENTS.md)
+2. Para cada uma das duas pastas (rules/ e rules-on-demand/), listar todos os arquivos .md (recursivo, exceto AGENTS.md) do core, mais os de `$IDE/overlays/{COMPANY_PROFILE}/{pasta}/` que o core não tem
 3. Para cada arquivo:
    a. Ler o bloco `> **Applies to:**` (primeira ocorrência no arquivo)
    b. Se o bloco não existir → tratar como universal → copiar sempre
@@ -1065,8 +1067,10 @@ Objetivo: garantir que `$IDE/rules/` e `$IDE/rules-on-demand/` contenham apenas
    d. **Condição especial RTK**: se o arquivo for `rtk-rules.md`,
       copiar APENAS se `RTK_ENABLED=true` no ENV.md
       (mesmo que o perfil bata, RTK é opt-in)
-   e. Se bate com o perfil → copiar para a mesma pasta em $IDE/ (rules/ → $IDE/rules/, rules-on-demand/ → $IDE/rules-on-demand/), preservando subpastas
+   e. Se bate com o perfil → copiar para a mesma pasta em $IDE/ (rules/ → $IDE/rules/, rules-on-demand/ → $IDE/rules-on-demand/), preservando subpastas.
+      **RuleResolver (#199):** a origem é `$IDE/overlays/{COMPANY_PROFILE}/{pasta}/{relPath}` se esse arquivo existir (o fork da empresa, mesmo caminho e nome), senão a do core. O `Applies to` lido é o do arquivo que será copiado. A cópia vinda do overlay recebe, logo depois do frontmatter (ou na primeira linha, sem frontmatter), a linha `> Overlay: {COMPANY_PROFILE} (forked_from {valor do frontmatter, ou "sem carimbo"})`. **Nada é gravado em `$IDE/overlays/`**: a única exceção é criar a pasta vazia do perfil (`mkdir`), feita pelo `jarvis init` e por este Passo 8 (nota abaixo do resumo)
    f. Se não bate → deletar de $IDE/ se existir lá
+   g. **Órfãs do overlay (#199):** arquivo em `$IDE/rules/` ou `$IDE/rules-on-demand/` cuja **primeira linha útil depois do frontmatter** é exatamente `> Overlay: {perfil} (forked_from …)` e que não existe em `$IDE/overlays/{COMPANY_PROFILE}/` (ficou de outro perfil, ou saiu do overlay à mão): se existe no core → copiar a versão do core por cima (sem marcação); senão → deletar de $IDE/. Uma rule que só cite a marcação no corpo não conta. O arquivo do overlay nunca é tocado
 4. Exibir resumo ao usuário
 ```
 
@@ -1140,8 +1144,12 @@ cp "$pasta/$relPath" "$IDE/$pasta/$relPath"   # $pasta = rules ou rules-on-deman
    Copiadas : N arquivos (rules/: N | rules-on-demand/: N)
    Removidas: N arquivos (não batem com o perfil)
    Universais: N arquivos (sem applies_to — sempre copiadas)
+   Do overlay: N arquivos ({COMPANY_PROFILE})
+   Overlay {COMPANY_PROFILE}: pasta criada        ← só quando `$IDE/overlays/{COMPANY_PROFILE}/` não existia
 ```
 
+> **Pasta do perfil (#199):** se `$IDE/overlays/{COMPANY_PROFILE}/` não existir, crie-a vazia (`mkdir -p`) e mostre a linha acima. É a única escrita permitida em `$IDE/overlays/`: nenhum arquivo é gravado, alterado ou apagado lá. O `jarvis init` faz o mesmo; aqui vale para quem roda só o `/jarvis-init`.
+
 > **Nota**: `rules/AGENTS.md` é sempre copiado — nunca filtrado.
 
 ---
@@ -1185,6 +1193,7 @@ Roda no fim de todo caminho que grava o `ENV.md`: criação (opção A ou ENV.md
 | Chave fora do template (saiu dele ou é do projeto) | `QA_SIGNOFF_BRANCHES`, `MINHA_VAR` | Mover para o bloco final "Variáveis fora do template", com `# (descontinuada)` numa linha própria logo acima da chave e o valor intacto |
 | Chave duplicada | `HUB=` duas vezes | Manter a preenchida (ou a última) |
 | Valor fora das opções | `HUB=BACKEN`, `MAX_AI_EXECUTION_PERCENTAGE=40`, `TASK_MANAGER_ACCESS=api` | Perguntar o valor, com as opções do template ou do `taxonomy.md` (as mesmas perguntas do passo 3) |
+| `COMPANY_PROFILE` vazio, fora do padrão ou igual a uma pasta do core | `COMPANY_PROFILE=`, `COMPANY_PROFILE=Acme Corp`, `COMPANY_PROFILE=rules` | A mesma pergunta do item 6 do passo 4 (default `stark-industries` primeiro). Vazio não é válido: a chave sempre tem um perfil |
 | Obrigatória vazia | `SQUAD=` | A mesma pergunta do passo 3 |
 | Lista de exemplo não escolhida | `TASK_MANAGER=[jira, github, gitlab]` | Escolher uma ou esvaziar |
 | Fora da ordem ou do assunto | blocos `# --- Upgrade ... ---` no fim; uma `DATA_*` longe das irmãs | Regravar na ordem do template |

package/templates/ENV-template.md

@@ -100,6 +100,17 @@ PROD_MODE=
 ARTIFACT_STYLE=ai-generated
 
 
+# =============================================================================
+# Perfil de empresa (overlay)
+# =============================================================================
+# Nome do overlay ativo em $IDE/overlays/{valor}/: a camada da empresa por cima do core,
+# só com o que foi substituído pelo /jarvis-fork. stark-industries é o perfil default
+# (o overlay padrão do Jarvis, criado vazio pelo jarvis init). Um nome próprio (ex.: acme)
+# aponta para o overlay dessa empresa. Só letras minúsculas, números e hífen; não pode ser
+# o nome de uma pasta do core (skills, rules, workflows...). Nunca deixe vazio.
+COMPANY_PROFILE=stark-industries
+
+
 # =============================================================================
 # Especializações por área
 # =============================================================================