jarvis-ai-framework 7.0.0 → 8.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/AGENTS.md +2 -2
  2. package/README.md +11 -34
  3. package/agents/engineering/data/eng.data-engineer.agent.md +3 -3
  4. package/agents/engineering/eng.agent.md +13 -11
  5. package/agents/engineering/eng.dev-code-reviewer.md +19 -4
  6. package/agents/engineering/eng.docs-consolidator.agent.md +2 -2
  7. package/agents/engineering/eng.docs-writer.md +17 -2
  8. package/agents/engineering/qa/eng.qa.quality-champion-task-agent.md +2 -2
  9. package/agents/engineering/qa/eng.qa.test-planner.md +20 -5
  10. package/agents/product/prod.pm-checker.md +16 -1
  11. package/bin/README.md +4 -4
  12. package/bin/commands/init.js +237 -29
  13. package/bin/lib/cli/program.js +7 -11
  14. package/bin/lib/core/sync-engine.js +8 -4
  15. package/bin/lib/utils/frontmatter.js +1 -1
  16. package/bin/lib/utils/paths.js +2 -1
  17. package/bin/lib/utils/version.js +65 -0
  18. package/bin/postinstall.js +7 -31
  19. package/package.json +2 -2
  20. package/rules/AGENTS.md +1 -1
  21. package/rules/engineering/data/data-rules.md +2 -2
  22. package/rules/engineering/eng-rules.md +1 -1
  23. package/rules/engineering/eng-security-rules.md +1 -1
  24. package/rules/engineering/eng.integrations-rules.md +6 -2
  25. package/rules/rtk-rules.md +1 -1
  26. package/rules-on-demand/doc-links-rules.md +2 -2
  27. package/rules-on-demand/engineering/eng.breakdown-subtasks-rules.md +1 -1
  28. package/rules-on-demand/engineering/eng.plan-rules.md +2 -0
  29. package/rules-on-demand/engineering/eng.pr-rules.md +8 -6
  30. package/rules-on-demand/engineering/eng.pre-pr-rules.md +10 -3
  31. package/rules-on-demand/engineering/eng.start-rules.md +7 -5
  32. package/rules-on-demand/engineering/eng.tech-spec-rules.md +9 -7
  33. package/rules-on-demand/engineering/eng.transitions-rules.md +7 -6
  34. package/skills/AGENTS.md +2 -2
  35. package/skills/SKILLS-ROADMAP.md +3 -3
  36. package/skills/eng-backend-arch-c4/assets/example-container.md +4 -4
  37. package/skills/eng-backend-arch-c4/assets/example-context.md +6 -6
  38. package/skills/eng-backend-microservices-trace/SKILL.md +1 -1
  39. package/skills/eng-global-investigation/SKILL.md +4 -0
  40. package/skills/eng-global-pr/SKILL.md +15 -12
  41. package/skills/eng-global-task-comment/SKILL.md +11 -3
  42. package/skills/eng-global-tech-spec/references/delivery-spec.md +28 -21
  43. package/skills/jarvis-docs-central/README.md +4 -4
  44. package/skills/jarvis-docs-central/SKILL.md +5 -3
  45. package/skills/jarvis-evolution-architect/references/exemplos.md +3 -3
  46. package/skills/jarvis-init/SKILL.md +89 -24
  47. package/skills/jarvis-init/assets/setup-guide.md +1 -1
  48. package/skills/jarvis-report-issue/SKILL.md +37 -24
  49. package/skills/product-roadmap-report/SKILL.md +2 -2
  50. package/skills/product-roadmap-report/commands/status.memory.md +1 -1
  51. package/skills/product-roadmap-report/commands/status.roadmap.preview.md +2 -2
  52. package/skills/product-specs/SKILL.md +1 -1
  53. package/skills/product-specs-update/SKILL.md +138 -121
  54. package/templates/ENV-template.md +57 -27
  55. package/templates/cdd-aplicado-a-prompts.md +1 -1
  56. package/templates/engineering/AGENTS-template.md +2 -2
  57. package/templates/engineering/CONTACTS-template.md +1 -1
  58. package/templates/engineering/advisor-template.md +2 -2
  59. package/templates/engineering/architecture-template.md +14 -1
  60. package/templates/engineering/data-contract-template.md +1 -1
  61. package/templates/engineering/plan-template.md +2 -0
  62. package/templates/engineering/tech-spec-delivery-template.md +8 -8
  63. package/templates/engineering/tech-spec-template.md +3 -3
  64. package/templates/product/prod-frd-template.md +1 -1
  65. package/templates/product/prod-prd-template.md +1 -1
  66. package/workflows/AGENTS.md +1 -1
  67. package/workflows/README.md +1 -1
  68. package/workflows/engineering/data/data.contract.md +12 -8
  69. package/workflows/engineering/eng.breakdown-subtasks.md +2 -2
  70. package/workflows/engineering/eng.build-tech-spec.md +1 -1
  71. package/workflows/engineering/eng.create-ard-from-code.md +3 -5
  72. package/workflows/engineering/eng.create-ard.md +3 -5
  73. package/workflows/engineering/eng.create-rfc.md +5 -5
  74. package/workflows/engineering/eng.light-arch.md +1 -1
  75. package/workflows/engineering/eng.plan.md +10 -7
  76. package/workflows/engineering/eng.pr.md +26 -19
  77. package/workflows/engineering/eng.pre-pr.md +126 -27
  78. package/workflows/engineering/eng.spec-consolidate.md +5 -5
  79. package/workflows/engineering/eng.start.md +23 -9
  80. package/workflows/engineering/eng.work.md +4 -4
  81. package/workflows/engineering/qa/eng.qa-release-signoff.md +1 -66
  82. package/workflows/product/prod.roadmap.preview.md +10 -14
  83. package/workflows/product/prod.spec.ard.md +2 -2
  84. package/workflows/product/prod.spec.breakdown.md +2 -2
  85. package/workflows/product/prod.spec.epic.md +4 -4
  86. package/workflows/product/prod.spec.frd.md +3 -3
  87. package/workflows/product/prod.spec.issue.md +3 -3
  88. package/workflows/product/prod.spec.prd.md +5 -5
  89. package/bin/commands/qa-signoff.js +0 -115
@@ -44,7 +44,7 @@ B: História / Task — implementação específica, pronta para desenvolvimento
44
44
 
45
45
  **Se recebeu URL/ID do $TASK_MANAGER:**
46
46
 
47
- - Busque o card usando a API ou ferramenta disponível
47
+ - Leia o card pela CLI oficial do `$TASK_MANAGER` (ação `view` do catálogo, `eng.integrations-rules.md`), sem REST nem MCP; sem acesso, peça para colar o conteúdo
48
48
  - **Épico**: extraia título, descrição, objetivo de negócio, escopo e iniciativa relacionada
49
49
  - **História**: extraia título, descrição, critérios de aceitação, épico relacionado, comentários relevantes
50
50
 
@@ -322,8 +322,8 @@ Use as ferramentas de busca para identificar:
322
322
 
323
323
  Verifique se há documentação relevante:
324
324
 
325
- - **PRD relacionada**: `$DOCS_FOLDER/**/*prd*.md` ou anexos no Jira
326
- - **FRD relacionada**: `$DOCS_FOLDER/**/*frd*.md` ou anexos no Jira
325
+ - **PRD relacionada**: `$DOCS_FOLDER/**/*prd*.md` ou anexos no card (lidos pela CLI ou colados pelo usuário)
326
+ - **FRD relacionada**: `$DOCS_FOLDER/**/*frd*.md` ou anexos no card (lidos pela CLI ou colados pelo usuário)
327
327
  - **ADRs (Architecture Decision Records)**: `$DOCS_FOLDER/ARD/*.md` ou `./sessions/**/adr.md`
328
328
  - **README e documentação técnica**: `README.md`, `ARCHITECTURE.md`, `API.md`
329
329
 
@@ -671,7 +671,7 @@ Para cada caso extremo/erro:
671
671
 
672
672
  Exemplo: `$SESSIONS_DIR/eng/story-123/tech-spec.md`
673
673
 
674
- > **IMPORTANTE**: A tech spec é salva na sessão e anexada no Jira. O Jira é a fonte da verdade, não o repositório.
674
+ > **IMPORTANTE**: A tech spec é salva na sessão. O anexo na issue é opcional e só sai na 6.4, depois da aprovação final e da pergunta.
675
675
 
676
676
  #### 6.2 Revisão de Qualidade
677
677
 
@@ -707,17 +707,23 @@ Apresente ao usuário:
707
707
 
708
708
  **Aguarde aprovação final do usuário.**
709
709
 
710
+ #### 6.4 Anexo da tech spec na issue (opcional, com pergunta)
711
+
712
+ Só com board configurado (no freelance não há issue: pule este passo). Só há pergunta quando o anexo vai sair: no Jira, com a `acli` logada que anexa arquivo (confira no `--help`) e `TASK_MANAGER_ACCESS=cli` (ou vazio). Nesse caso: para anexá-la na issue do board, depois da aprovação da 6.3, mostre o que vai e pergunte com `AskUserQuestion` (regra de ouro, `eng.integrations-rules.md`): **Sim, anexar** / **Não, manter só na sessão**; com o Sim, anexe pela `acli`; sem o Sim, a tech spec fica só na sessão. Nos demais casos (Jira sem a `acli` logada, `acli` que não anexa, acesso manual, GitHub ou GitLab, cuja CLI não anexa arquivo à issue) não há envio e, portanto, nenhuma pergunta: oriente a pessoa a anexar à mão. A mensagem da 8.2 diz o que aconteceu.
713
+
710
714
  ---
711
715
 
712
716
  ### ═══════════════════════════════════════════════
713
717
 
714
- ### FASE 7: Criação de Subtarefas no Jira
718
+ ### FASE 7: Criação de Subtarefas (automática só no Jira)
715
719
 
716
720
  ### ═══════════════════════════════════════════════
717
721
 
722
+ > **Escopo:** a criação automática de subtarefas é só no Jira, pela `acli`. Em GitHub ou GitLab, ou no Jira sem a `acli` logada ou com `TASK_MANAGER_ACCESS=manual`, esta fase entrega o template formatado e as instruções para a pessoa criar as subtarefas à mão; como não há envio, a 7.3 não faz a pergunta nesse caso. A generalização para `gh`/`glab` fica para uma issue à parte.
723
+
718
724
  #### 7.1 Preparação para Criação
719
725
 
720
- **Se o projeto usa Jira e a `acli` está logada (`acli jira workitem create`, conferindo os flags no `--help`), ou há uma ferramenta MCP do Jira configurada à mão:**
726
+ **Se o projeto usa Jira, a `acli` está logada e `TASK_MANAGER_ACCESS=cli` ou vazio (vazio vale como `cli`, com o aviso do `/jarvis-init`), com `acli jira workitem create` (conferindo os flags no `--help`; a criação só sai na 7.3, depois da pergunta, regra de ouro):**
721
727
 
722
728
  Para cada subtarefa no plano:
723
729
 
@@ -729,26 +735,27 @@ Para cada subtarefa no plano:
729
735
  - Estimativa: {X horas}
730
736
  - Labels: `tech-spec`, `{área}` (ex: backend, frontend)
731
737
 
732
- #### 7.2 Estrutura da Descrição no Jira
738
+ #### 7.2 Estrutura da Descrição no board
739
+
740
+ Use o formato **Descrição da subtarefa no board** de `$IDE/templates/engineering/tech-spec-delivery-template.md` (seções: Descrição, Arquivos a Modificar/Criar, Critérios de Aceitação, Testes Requeridos, Dependências, Referência).
733
741
 
734
- Use o formato **Descrição da subtarefa no Jira** de `$IDE/templates/engineering/tech-spec-delivery-template.md` (seções: Descrição, Arquivos a Modificar/Criar, Critérios de Aceitação, Testes Requeridos, Dependências, Referência).
742
+ #### 7.3 Criação (Jira pela `acli`; outros boards, template)
735
743
 
736
- #### 7.3 Criação no Jira
744
+ Só há pergunta quando a criação vai sair: no Jira, com a `acli` logada e `TASK_MANAGER_ACCESS=cli` (ou vazio). Nos demais casos (fora do Jira, sem a `acli` ou com acesso manual) não há envio e, portanto, nenhuma pergunta: entregue o template formatado direto. Quando a criação vai sair, antes de criar as subtarefas, mostre o texto e pergunte com `AskUserQuestion` (**Sim, publicar** / **Não, manter só na sessão**), regra de ouro de `eng.integrations-rules.md`; sem o Sim, entregue só o template formatado e deixe o texto na sessão. O comentário da 7.4 tem a sua própria pergunta, feita pelo `/eng-global-task-comment`.
737
745
 
738
- **Se houver API/ferramenta disponível:**
746
+ **No Jira, com a `acli` logada, `TASK_MANAGER_ACCESS=cli` (ou vazio) e o Sim:**
739
747
 
740
- - Use para criar subtarefas automaticamente
741
- - Vincule à história pai
742
- - Configure dependências entre subtarefas
748
+ - Crie as subtarefas com `acli jira workitem create` (flags no `--help`)
749
+ - Vincule à história pai e configure as dependências entre subtarefas no que a `acli` permitir (com o Sim acima); o resto vai no template manual abaixo
743
750
 
744
- **Se não houver ferramenta:**
751
+ **Em GitHub/GitLab, sem a `acli` logada (ou com `TASK_MANAGER_ACCESS=manual`), ou sem o Sim:**
745
752
 
746
- - Forneça ao usuário **template formatado** para copiar/colar no Jira
753
+ - Forneça ao usuário **template formatado** para copiar/colar no board (Jira, GitHub ou GitLab)
747
754
  - Forneça **instruções passo-a-passo** para criação manual
748
755
 
749
756
  #### 7.4 Atualização da História Original
750
757
 
751
- Adicione comentário na história original (STORY-XXX) com:
758
+ Publique o comentário na história original (STORY-XXX) com o `/eng-global-task-comment`, que mostra o texto e pergunta (regra de ouro). O comentário segue este formato:
752
759
 
753
760
  Use o formato **Comentário na história original** de `$IDE/templates/engineering/tech-spec-delivery-template.md`.
754
761
 
@@ -766,10 +773,10 @@ Valide que:
766
773
 
767
774
  - [ ] Tech Spec completa e aprovada pelo usuário
768
775
  - [ ] Arquivo salvo na sessão: `$SESSIONS_DIR/eng/{feature-name}/tech-spec.md`
769
- - [ ] Tech Spec anexada na issue do Jira
776
+ - [ ] Tech Spec anexada na issue (com o Sim), a anexar pela pessoa (orientado) ou deixada na sessão
770
777
  - [ ] Subtarefas documentadas com critérios claros
771
- - [ ] Subtarefas criadas no Jira (ou template fornecido)
772
- - [ ] História original atualizada com link para tech spec
778
+ - [ ] Subtarefas criadas no Jira pela `acli`, ou template fornecido (outros boards, sem a CLI, com acesso manual, sem o Sim ou sem board)
779
+ - [ ] História original atualizada com link para tech spec (com o Sim do comentário da 7.4) ou texto deixado na sessão
773
780
  - [ ] Decisões arquiteturais documentadas
774
781
  - [ ] Riscos identificados e mitigados
775
782
  - [ ] Dependências mapeadas
@@ -800,7 +807,7 @@ Use o formato **Mensagem de entrega** de `$IDE/templates/engineering/tech-spec-d
800
807
  - `$SESSIONS_DIR/eng/**/*.md` - Tech specs e ADRs de sessões anteriores
801
808
  - `README.md` - Visão geral do projeto
802
809
  - `ARCHITECTURE.md` - Arquitetura do sistema (se existir)
803
- - Anexos no Jira - PRD, FRD, ARD, RFC
810
+ - Anexos no card (lidos pela CLI ou colados) - PRD, FRD, ARD, RFC
804
811
 
805
812
  ### Templates
806
813
 
@@ -821,7 +828,7 @@ O diagrama do fluxo (épico x história, fases 0 a 8) está na seção **Fluxo r
821
828
 
822
829
  → Liste o que falta e peça ao usuário para completar
823
830
 
824
- ### Se não conseguir acessar o Jira:
831
+ ### Se não conseguir acessar o card no board:
825
832
 
826
833
  → Peça ao usuário para copiar/colar o conteúdo da história
827
834
 
@@ -5,7 +5,7 @@ Integração com o **Central docs**: o registro do que **foi implementado** em c
5
5
  ## Visão Geral
6
6
 
7
7
  - **Buscar** o que já foi implementado (`jarvis docs sync`, `jarvis docs fetch`)
8
- - **Publicar** a consolidação de cada entrega (`jarvis docs publish`, pelo `/eng.spec-consolidate`)
8
+ - **Publicar** a consolidação de cada entrega (`jarvis docs publish`, pelo `/eng.spec-consolidate`, depois da pergunta)
9
9
  - **Índice** regenerado a cada publicação (`{SQUAD}/index.md`)
10
10
 
11
11
  O Central docs funciona por **adaptador de armazenamento**: hoje uma pasta do disco (`filesystem`). Se essa pasta for um clone de um repositório de documentação (tem `.git`), a publicação vira branch + commit + push + Pull/Merge Request. S3 e Google Drive são as issues #144 e #145.
@@ -27,7 +27,7 @@ WORKSPACE=loja # vira a pasta do produto
27
27
 
28
28
  A pasta padrão é `docs/jarvis/central-docs` nos dois modos de trabalho, junto dos documentos de trabalho. No projeto único, `docs/jarvis/` no `.gitignore` a deixa fora do versionamento; no workspace (vários repositórios) a raiz não é versionada. Quem já usa `./central-docs` continua funcionando, e o Upgrade do `/jarvis-init` oferece mover a pasta.
29
29
 
30
- > Com `.git`, o PR é aberto pela CLI do host (`gh pr create` / `glab mr create`), com o login dela (`gh auth login`, `glab auth login`). Sem a CLI, ou com `VERSION_CONTROL_ACCESS` `manual`/inválido no `ENV.md` do projeto, a branch fica no remote e a publicação mostra o link para abrir o MR à mão. Nenhum token vai no chat nem no `ENV.md`.
30
+ > Com `.git` (e só depois da pergunta do `/eng.spec-consolidate`, regra de ouro), o PR é aberto pela CLI do host (`gh pr create` / `glab mr create`), com o login dela (`gh auth login`, `glab auth login`). Sem a CLI, ou com `VERSION_CONTROL_ACCESS` `manual`/inválido no `ENV.md` do projeto, a branch fica no remote e a publicação mostra o link para abrir o MR à mão. Nenhum token vai no chat nem no `ENV.md`.
31
31
 
32
32
  **Vindo da versão anterior (Central docs como repositório remoto)?** Rode `/jarvis-init` → Upgrade (C). Ele propõe `CENTRAL_DOCS_STORAGE=filesystem`, a pasta padrão e o `git clone` do repositório antigo.
33
33
 
@@ -36,8 +36,8 @@ A pasta padrão é `docs/jarvis/central-docs` nos dois modos de trabalho, junto
36
36
  ```bash
37
37
  jarvis docs sync # resumo: funcionalidades e entregas recentes
38
38
  jarvis docs fetch CORE/index.md # conteúdo de um arquivo (exit 2 se não existir)
39
- jarvis docs publish --file .../consolidation/feature-checkout.md --tipo feature # pelo /eng.spec-consolidate
40
- jarvis docs publish --file .../consolidation/delivery-2026-10-15-task-123.md --tipo delivery
39
+ jarvis docs publish --file .../consolidation/feature-checkout.md --tipo feature # pelo /eng.spec-consolidate, depois do Sim (regra de ouro)
40
+ jarvis docs publish --file .../consolidation/delivery-2026-10-15-task-123.md --tipo delivery # idem
41
41
  ```
42
42
 
43
43
  - **Tipos:** só `feature` (vai para `product/`) e `delivery` (vai para `engineering/`). PRD, ARD, SPEC e os outros documentos de trabalho são recusados, com a explicação de que ficam em `docs/jarvis/`.
@@ -24,7 +24,7 @@ Integrar os comandos do framework com o **Central docs**: o registro do que **de
24
24
  | Documentos de trabalho | PRD, FRD, épicos, histórias, ARD, RFC, SPEC, QA, swagger, robôs, C4: o que se pretende e se discute | `docs/jarvis/` (`$PROD_DOCS`, `$ENG_DOCS`), fora do versionamento |
25
25
  | **Central docs** | O que foi implementado: um documento **completo e autossuficiente** por funcionalidade (estado atual) e um **registro por entrega** (PR, commits, autores) | Pasta do Central docs (adaptador) |
26
26
 
27
- Quem escreve no Central docs é o **`/eng.spec-consolidate`** (agente `eng.docs-consolidator`), depois do merge do PR. Os documentos de trabalho nunca são publicados lá.
27
+ Quem escreve no Central docs é o **`/eng.spec-consolidate`** (agente `eng.docs-consolidator.agent`), depois do merge do PR. Os documentos de trabalho nunca são publicados lá.
28
28
 
29
29
  **Modos deste skill:**
30
30
  - buscar o que já foi implementado (Modo 1);
@@ -56,6 +56,8 @@ Ler do `$IDE/ENV.md`:
56
56
  - `CENTRAL_DOCS_REF`, `CENTRAL_DOCS_TARGET_BRANCH`, `CENTRAL_DOCS_REVIEWERS` (só com `.git`)
57
57
  - `SQUAD` (ALL-CAPS-COM-HIFEN) e `WORKSPACE` (vira a pasta do produto)
58
58
 
59
+ O `jarvis docs publish` só roda depois da pergunta do `/eng.spec-consolidate` (regra de ouro, `rules/engineering/eng.integrations-rules.md`).
60
+
59
61
  Com `.git`, o PR é aberto pela CLI do host (`gh pr create` / `glab mr create`), com o login dela, respeitando o `VERSION_CONTROL_ACCESS` do `ENV.md` do projeto (não do repositório do Central docs). Sem a CLI, sem login, ou com `manual`/valor inválido/ENV.md ilegível, a branch fica no remote e a publicação mostra o link para abrir o MR à mão. ❌ **Nunca** colar token no chat nem gravar no `ENV.md`.
60
62
 
61
63
  ---
@@ -157,12 +159,12 @@ jarvis docs publish --file .../consolidation/feature-checkout.md --tipo feature
157
159
  1. Validar o frontmatter.
158
160
  2. Calcular o destino.
159
161
  3. Sem `.git`: copiar e regenerar o índice.
160
- 4. Com `.git`: branch, cópia, índice, commit, push e PR.
162
+ 4. Com `.git`: branch, cópia, índice, commit, push e PR (só depois da pergunta, regra de ouro).
161
163
 
162
164
  ### Modo 3: Reparar o índice
163
165
 
164
166
  - **Sem `.git`:** a próxima publicação regenera o índice.
165
- - **Com `.git`:** no clone, rodar `bash scripts/build-index.sh` (se existir) e abrir um PR `repair/index-{SQUAD}-{data}`.
167
+ - **Com `.git`:** no clone, rodar `bash scripts/build-index.sh` (se existir) e abrir um PR `repair/index-{SQUAD}-{data}` (só depois de mostrar o que será enviado e perguntar, regra de ouro).
166
168
 
167
169
  ### Skills invocados durante a execução do skill
168
170
 
@@ -152,7 +152,7 @@ Consolidar skills **não é a resposta**. Problema é **organização e document
152
152
  **O Que Eu Mudaria:**
153
153
  1. Criar um **INDEX.md** principal que agrupa skills por contexto
154
154
  2. Adicionar tags em metadatas das skills
155
- 3. Criar uma skill `/jarvis-find-skill` que busca
155
+ 3. Criar uma skill de busca de skills (hipotética; não existe no framework)
156
156
  4. Melhorar `metadata.area` e `metadata.tags`
157
157
 
158
158
  **O Que Eu Não Faria:**
@@ -263,7 +263,7 @@ Quando você invoca a skill:
263
263
  ```
264
264
  "Qual skill devo usar para X?"
265
265
  ```
266
- ❌ Isso não é pergunta arquitetural. Use `/jarvis-find-skill` em vez disso.
266
+ ❌ Isso não é pergunta arquitetural. Consulte o mapeamento comando → skill em `skills/AGENTS.md` em vez disso.
267
267
 
268
268
  ### ✅ Fazer isso:
269
269
  ```
@@ -286,7 +286,7 @@ Quando você invoca a skill:
286
286
  | "Devo criar um novo agent?" | ✅ SIM |
287
287
  | "Essa feature deveria ser skill ou workflow?" | ✅ SIM |
288
288
  | "Acho que essa feature está complexa demais" | ✅ SIM |
289
- | "Qual skill usa para X?" | ❌ NÃO (use `/jarvis-find-skill`) |
289
+ | "Qual skill usa para X?" | ❌ NÃO (consulte `skills/AGENTS.md`) |
290
290
  | "Como implement feature X?" | ❌ NÃO (use skill específica) |
291
291
  | "Devemos adotar X tendência?" | ✅ SIM |
292
292
  | "Qual a diferença entre SDD e CDD?" | ✅ SIM |
@@ -29,6 +29,7 @@ Regras que **substituem** qualquer trecho legado deste skill ou dos assets:
29
29
  8. **Autonomia** — qualquer `POSITION` (JUNIOR…CTO / PM) pode rodar o card ponta a ponta (`/eng.start` → `/eng.pr`). Sem gate obrigatório de TL/PM no init.
30
30
  9. **Fonte do ENV** — só `templates/ENV-template.md`. Não inventar variáveis. `JARVIS_PROJECT` default: `https://github.com/phelipperibeiro/jarvis-framework` (sempre a URL completa; trocar só para um fork interno).
31
31
  10. **IDEs** — windsurf, claude, cursor, codex, opencode, gemini/antigravity, kiro.
32
+ 11. **Instalação só global** — `npm install -g jarvis-ai-framework`. O `jarvis init` roda dentro do projeto e copia os assets do Jarvis global; cópia local no projeto (`node_modules` ou dependência no `package.json`) é ignorada. Antes de tudo, confira a versão (Passo 0).
32
33
 
33
34
  ## Objetivo
34
35
 
@@ -59,6 +60,8 @@ Regras que **substituem** qualquer trecho legado deste skill ou dos assets:
59
60
  ```
60
61
  ┌─────────────────────────────────────────────────────────────┐
61
62
  │ │
63
+ │ 0. CONFERIR VERSÃO → jarvis-lock.json × jarvis --version │
64
+ │ ↓ │
62
65
  │ 1. DETECTAR IDE → Identificar ambiente │
63
66
  │ ↓ │
64
67
  │ 2. VERIFICAR → Se ENV.md já existe │
@@ -79,6 +82,8 @@ Regras que **substituem** qualquer trecho legado deste skill ou dos assets:
79
82
  │ ↓ │
80
83
  │ 9. STACKS → Adicionar as stacks (opcional, pulável) │
81
84
  │ ↓ │
85
+ │ 9.5 VALIDAR ENV.md → Arquivo inteiro × template (sempre) │
86
+ │ ↓ │
82
87
  │ 10. CONFIRMAR → Com usuário │
83
88
  │ │
84
89
  └─────────────────────────────────────────────────────────────┘
@@ -88,6 +93,21 @@ Regras que **substituem** qualquer trecho legado deste skill ou dos assets:
88
93
 
89
94
  ## Fluxo de Trabalho Detalhado
90
95
 
96
+ ### 0. Conferir a versão (antes de tudo)
97
+
98
+ O texto deste skill e dos assets em `$IDE/` é o da versão que fez o último sync (`jarvis-lock.json`). Se ela estiver atrás do Jarvis global, você estaria seguindo regras antigas.
99
+
100
+ 1. Leia o `version` do `jarvis-lock.json` da pasta do workspace. Sem o arquivo, o projeto é novo: siga para o Passo 1.
101
+ 2. Rode `jarvis --version` (o Jarvis global). Sem o `jarvis` no PATH, explique que o Jarvis é instalado só global (`npm install -g jarvis-ai-framework`) e pergunte com `AskUserQuestion` se segue mesmo assim (**Instalar antes** | **Seguir assim mesmo**).
102
+ 3. Compare as duas versões (`x.y.z`):
103
+ - **Lock mais antigo que o global:** explique em uma frase ("os assets deste projeto são da {lock}; o seu Jarvis global é a {global}") e pergunte com `AskUserQuestion`: **Atualizar os assets agora (Recomendada)** | **Seguir assim mesmo**. Para atualizar, na pasta do workspace:
104
+ - com `$IDE/ENV.md`: `jarvis init --upgrade --ide {ide}`;
105
+ - sem `$IDE/ENV.md` (o projeto passou pelo `jarvis init` e ainda não pelo `/jarvis-init`): `jarvis init --ide {ide} --force`, porque o `--upgrade` exige o `ENV.md`.
106
+
107
+ Depois, recomece este skill pelo Passo 0, porque o texto dele pode ter mudado.
108
+ - **Lock mais novo que o global:** avise que o Jarvis global está desatualizado (`npm install -g jarvis-ai-framework`) e siga. Não rode o `jarvis init` com esse global: ele rebaixaria os assets.
109
+ - **Iguais:** siga.
110
+
91
111
  ### 1. Resolver identidade local (sem login)
92
112
 
93
113
  Não existe OAuth. `USER` vem do ambiente local.
@@ -186,14 +206,15 @@ Identificar qual IDE o usuário está utilizando:
186
206
  ⚠️ O arquivo ENV.md já existe. O que deseja fazer?
187
207
  A: Sobrescrever completamente
188
208
  B: Atualizar apenas variáveis específicas
189
- C: Upgrade — adicionar variáveis novas do template (não toca nos valores existentes)
209
+ C: Upgrade — adicionar variáveis novas do template (não troca valor existente sem a sua resposta)
190
210
  D: Cancelar
191
211
  ```
212
+ A (que segue o fluxo completo), B e C terminam pelo **passo 9.5 (validar o ENV.md)**; D não toca no arquivo.
192
213
 
193
214
  **Se opção C (Upgrade):**
194
215
 
195
216
  > No terminal, rode antes `jarvis init --upgrade --ide {ide}`: ele atualiza os arquivos do framework, acrescenta as variáveis novas e move os documentos para as pastas novas (itens 1–8, 10 a 12). Aqui ficam o Central docs antigo (item 9), as pendências que ele listar e o passo das stacks.
196
- > **O upgrade só acrescenta chaves novas:** nenhuma chave já existente, preenchida ou não, é alterada, salvo as exceções declaradas no item 9 (`CENTRAL_DOCS_LOCATION` e `TOKEN_TASK_MANAGER`, com confirmação; `JARVIS_PROJECT` vazio, automático).
217
+ > **O upgrade só acrescenta chaves novas:** nenhuma chave já existente, preenchida ou não, é alterada, salvo as exceções declaradas no item 9 (`CENTRAL_DOCS_LOCATION` e `TOKEN_TASK_MANAGER`, com confirmação; `JARVIS_PROJECT` vazio, automático). Depois, a validação final (passo 9.5) pode reorganizar o arquivo, mover chaves para o assunto delas e corrigir valores fora das opções, sempre perguntando: nenhum valor muda sem a resposta da pessoa.
197
218
  > Trocou o `ARTIFACT_STYLE` (ou HUB, POSITION, AREA, SQUAD) à mão? O Passo 8 copia ou remove as rules desse perfil.
198
219
 
199
220
  1. Ler todas as chaves do `templates/ENV-template.md`
@@ -205,14 +226,14 @@ Identificar qual IDE o usuário está utilizando:
205
226
  ```
206
227
  ✅ ENV.md já está atualizado. Nenhuma variável nova encontrada.
207
228
  ```
208
- Oferecer o **passo 9 (adicionar as stacks)**, que a pessoa pode pular, e então encerrar.
229
+ Oferecer o **passo 9 (adicionar as stacks)**, que a pessoa pode pular, rodar o **passo 9.5 (validar o ENV.md)** e então encerrar.
209
230
  7. Se houver diff, exibir prévia:
210
231
  ```
211
232
  🔍 Variáveis novas encontradas no template:
212
233
  + NOVA_VAR_1=
213
234
  + NOVA_VAR_2=valor-padrão
214
235
 
215
- Serão adicionadas ao final do ENV.md sem alterar os valores existentes.
236
+ Serão adicionadas no assunto de cada uma, na posição do template, sem alterar os valores existentes.
216
237
  ```
217
238
  8. **Exceção — documentos nos caminhos antigos:** procure documentos de trabalho em `$DOCS_FOLDER/product`, `$DOCS_FOLDER/engineering/{ARD,RFC,qa,swagger,openapi,robots,c4}`, `docs/engineering/{robots,swagger,openapi,c4}` e os discoveries em `$PROD_DOCS/discoveries/`.
218
239
  - Se houver, liste o que encontrou e pergunte com `AskUserQuestion` (uma pergunta para todos) se move para `docs/jarvis/…` (`$PROD_DOCS`, `$ENG_DOCS/…` e, para os discoveries, `$DISCOVERIES_DOCS`). Use `git mv` quando o arquivo for versionado e `mv` quando não for e, só se a raiz do workspace tiver `.git`, garanta `docs/jarvis/` no `.gitignore`.
@@ -228,18 +249,13 @@ Identificar qual IDE o usuário está utilizando:
228
249
  10. **Exceção — `PROD_MODE`:** se `PROD_MODE` estiver entre as chaves novas, grave pelo `AREA`: `ENGINEERING` → `developer-guided`, `PRODUCT` → `product-led`. Com outra `AREA` (ou vazia), faça a mesma pergunta do Passo 3 (Pergunta 8 — modo de condução) e grave a resposta. `PROD_MODE` que já existe, mesmo vazia, não muda. As demais chaves continuam sem pergunta.
229
250
  - **`WORKSPACE_MODE`:** o `jarvis init --upgrade` já grava o modo detectado (raiz sem `.git` e 1+ subpastas com `.git/` = `workspace`; raiz com `.git` = `project`). Se a chave existir vazia, detecte do mesmo jeito e grave; se existir preenchida, não muda.
230
251
  - **`.gitignore` numa raiz sem `.git` (ex.: `WORKSPACE_MODE=workspace`):** a raiz não é versionada, então esse arquivo não tem efeito. Não o apague; só avise: `ℹ️ O .gitignore da raiz do workspace não tem efeito (a raiz não é um repositório). Pode removê-lo se quiser.`
231
- 11. Appender as novas variáveis ao final do `ENV.md` com comentário de data:
232
- ```
233
- # --- Upgrade YYYY-MM-DD ---
234
- NOVA_VAR_1=
235
- NOVA_VAR_2=valor-padrão
236
- ```
252
+ 11. Acrescentar as novas variáveis no assunto de cada uma, na posição do template, junto das chaves do mesmo assunto (ex.: uma `DATA_*` nova vai para o bloco Data Engineering, ao lado das irmãs), com o comentário do template. Sem bloco datado no fim. O `jarvis init --upgrade` (terminal) acrescenta no fim, num bloco `# --- Upgrade ... ---`, por ser determinístico; o passo 9.5 põe essas chaves no lugar.
237
253
  12. Confirmar:
238
254
  ```
239
255
  ✅ ENV.md atualizado! N variável(is) nova(s) adicionada(s).
240
256
  ⚠️ Preencha os valores em branco antes de usar os novos recursos.
241
257
  ```
242
- 13. Oferecer o **passo 9 (adicionar as stacks)**, que a pessoa pode pular, e então encerrar (não continuar para o fluxo de onboarding completo).
258
+ 13. Oferecer o **passo 9 (adicionar as stacks)**, que a pessoa pode pular, rodar o **passo 9.5 (validar o ENV.md)** e então encerrar (não continuar para o fluxo de onboarding completo).
243
259
 
244
260
  **⚠️ OBRIGATÓRIO - Criação do ENV.md**:
245
261
 
@@ -632,7 +648,6 @@ Se **A** ou **B**, perguntar sobre cada variável opcional conforme seleção
632
648
  | `SMTP` | *(vazio)* | `google`, `ses`, `sendgrid` |
633
649
  | `CODE_QUALITY_TOOL` / `_URL` / `_TOKEN` | *(vazio)* | SonarQube etc. |
634
650
  | `TEST_FOLDER` | *(vazio)* | Pasta de testes |
635
- | `QA_SIGNOFF_BRANCHES` / `QA_SIGNOFF_MAX_AGE` | `main,release/*` / `24` | Sign-off QA |
636
651
  | `JARVIS_PROJECT` | `https://github.com/phelipperibeiro/jarvis-framework` | URL completa do repo do framework (`/jarvis-report-issue`); trocar só para um fork |
637
652
  | `CENTRAL_DOCS_STORAGE` / `_LOCATION` | `filesystem` / pasta padrão do modo de trabalho | Central docs (o que foi implementado), configurado no Passo 5.2; vazio = desligado |
638
653
  | `JARVIS_DOCS` / `ENG_DOCS` | `$DOCS_FOLDER/jarvis` / `$JARVIS_DOCS/engineering` | Documentos de trabalho (não perguntar; `docs/jarvis/` no `.gitignore` só se a raiz tiver `.git`) |
@@ -770,10 +785,12 @@ if (IDE === "claude") {
770
785
  }
771
786
  ```
772
787
 
773
- O arquivo `$IDE/ENV.md` deve seguir a **estrutura e ordem** de `templates/ENV-template.md` (não um dump reordenado). Blocos mínimos esperados após o init:
788
+ O arquivo `$IDE/ENV.md` deve seguir a **estrutura e ordem** de `templates/ENV-template.md` (não um dump reordenado), com cada assunto na moldura de `# ====` do template; o passo 9.5 confere no fim. Blocos mínimos esperados após o init (os títulos são os do template; os comentários de cada bloco foram omitidos):
774
789
 
775
790
  ```markdown
776
- # --- Workspace e identidade ---
791
+ # =============================================================================
792
+ # Workspace e identidade
793
+ # =============================================================================
777
794
  WORKSPACE=
778
795
  WORKSPACE_REPOS=
779
796
  WORKSPACE_MODE={workspace|project}
@@ -781,17 +798,17 @@ USER={resolvido}
781
798
  MAX_AI_EXECUTION_PERCENTAGE={60-100}
782
799
  ENABLE_CDD=true
783
800
 
784
- # --- Organização ---
801
+ # =============================================================================
802
+ # Organização (obrigatório — opções vêm do taxonomy.md)
803
+ # =============================================================================
785
804
  SQUAD={valor}
786
805
  HUB={valor}
787
806
  AREA={valor}
788
807
  POSITION={valor}
789
808
 
790
- # --- Condução e estilo ---
791
- PROD_MODE={product-led|developer-guided}
792
- ARTIFACT_STYLE={ai-generated|human-generated}
793
-
794
- # --- IDE e pastas ---
809
+ # =============================================================================
810
+ # IDE e pastas
811
+ # =============================================================================
795
812
  IDE={valor}
796
813
  DOCS_FOLDER=docs
797
814
  FLOWS_FOLDER={commands|workflows}
@@ -807,16 +824,22 @@ PROD_TEMPLATES=...
807
824
  PROD_DOCS=...
808
825
  DISCOVERIES_FOLDER_NAME=discoveries
809
826
  DISCOVERIES_DOCS=...
827
+ PROD_MODE={product-led|developer-guided}
828
+ ARTIFACT_STYLE={ai-generated|human-generated}
810
829
 
811
- # --- Task manager (opcional; vazio = freelance) ---
830
+ # =============================================================================
831
+ # Task manager (opcional)
832
+ # =============================================================================
812
833
  TASK_MANAGER=
813
834
  TASK_MANAGER_ACCESS=
814
835
  TASK_MANAGER_URL_BASE=
815
836
 
816
- # --- Controle de versão / chat / demais opcionais do template ---
837
+ # =============================================================================
838
+ # Controle de versão (opcional)
839
+ # =============================================================================
817
840
  VERSION_CONTROL=
818
841
  VERSION_CONTROL_ACCESS=
819
- # ... restante do template (MESSAGE_*, DATABASE, JARVIS_PROJECT, CENTRAL_DOCS_*, etc.)
842
+ # ... restante do template, cada assunto na sua moldura (MESSAGE_*, DATABASE, JARVIS_PROJECT, CENTRAL_DOCS_*, etc.)
820
843
  JARVIS_PROJECT=https://github.com/phelipperibeiro/jarvis-framework
821
844
  ```
822
845
 
@@ -1142,6 +1165,47 @@ O tempo de ~10 minutos é referência, não limite. Nunca leia `.env*`, chaves o
1142
1165
 
1143
1166
  ---
1144
1167
 
1168
+ ### 9.5 Validar o ENV.md (sempre, no fim)
1169
+
1170
+ Roda no fim de todo caminho que grava o `ENV.md`: criação (opção A ou ENV.md novo), atualização de variáveis (B) e Upgrade (C, inclusive "já atualizado"), depois do passo 9. Não roda ao cancelar (D). Objetivo: o arquivo fica **100% correto** e **separado por assunto**, na estrutura e na ordem de `templates/ENV-template.md`, com cada assunto na moldura de `# ====`:
1171
+
1172
+ ```
1173
+ # =============================================================================
1174
+ # Workspace e identidade
1175
+ # =============================================================================
1176
+ ```
1177
+
1178
+ **Nunca mostre valor de variável**: nas perguntas e na saída vão só o nome da chave e se a linha tem algo depois do `=`.
1179
+
1180
+ **1. Conferir o arquivo inteiro contra o template.** Cada item que falhar é um problema:
1181
+
1182
+ | Verificação | Exemplo | Correção sugerida (primeira opção, "(Recomendada)") |
1183
+ |---|---|---|
1184
+ | Chave do template ausente | falta `WORKSPACE_MODE` | Acrescentar no assunto dela, com o padrão do template. Não conta como ausente uma `DATA_*` (exceto `DATA_SPECIALIZATIONS`) quando o HUB não exige o bloco DATA (regra do bloco DATA, abaixo) |
1185
+ | 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 |
1186
+ | Chave duplicada | `HUB=` duas vezes | Manter a preenchida (ou a última) |
1187
+ | 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) |
1188
+ | Obrigatória vazia | `SQUAD=` | A mesma pergunta do passo 3 |
1189
+ | Lista de exemplo não escolhida | `TASK_MANAGER=[jira, github, gitlab]` | Escolher uma ou esvaziar |
1190
+ | Fora da ordem ou do assunto | blocos `# --- Upgrade ... ---` no fim; uma `DATA_*` longe das irmãs | Regravar na ordem do template |
1191
+ | Comentários ou separadores diferentes dos do template | comentário antigo; `# --- Assunto ---` | Trocar pelos do template (a pergunta avisa que comentários próprios se perdem) |
1192
+ | Bloco DATA fora da regra do HUB | `DATA_*` com `HUB=BACKEND` | Regra do bloco DATA (sempre exceto `DATA_SPECIALIZATIONS`, obrigatória em qualquer HUB): `HUB=DATA` exige o bloco (as que faltarem contam como ausentes); `HUB=FULLCYCLE` o deixa opcional (nem ausente, nem a remover), como a criação (passo 5) e o Upgrade (item 4) já fazem; outro HUB: sugerir remover o bloco |
1193
+
1194
+ Não pergunte de novo o que as exceções 9 a 9.3 do Upgrade já resolveram nesta execução.
1195
+
1196
+ **2. Perguntar cada problema** com `AskUserQuestion`: **uma pergunta por problema**, em chamadas de até 4 abas, agrupadas por tipo de verificação. Cada pergunta tem a correção sugerida como primeira opção, marcada "(Recomendada)", e uma opção que mantém o arquivo como está (ex.: "Manter como está"). Nada é corrigido sem resposta. Sem problema nenhum, não pergunte: avise `✅ ENV.md conferido: nada a corrigir.`
1197
+
1198
+ **3. Regravar (só o que foi aceito).**
1199
+ - **Reorganização aceita:** use a estrutura do template (ordem, comentários e molduras), mas só com as chaves que o arquivo já tem mais as acrescentadas por resposta: chave que a pessoa recusou acrescentar não entra, e um bloco inteiro que o arquivo não tem (como o DATA, fora da regra do HUB) não volta. Ponha o valor atual de cada chave no lugar dela, cada uma no seu assunto e junto das irmãs, e desfaça os blocos datados. As chaves fora do template vão para o último bloco, "Variáveis fora do template", cada uma com `# (descontinuada)` logo acima. **Nenhuma chave é apagada**, salvo as que a pessoa mandou remover numa resposta (como o bloco DATA). O comentário fica numa linha própria: na mesma linha da chave, o CLI o leria como parte do valor.
1200
+ - **Reorganização recusada:** grave só as correções de conteúdo aceitas, no lugar em que cada chave está, sem mover o resto.
1201
+ - **Conferência antes de gravar:** o **conjunto de chaves** depois é o de antes, mais as acrescentadas e menos as removidas por resposta; e o mapa chave → valor das chaves mantidas é igual (só mudam as corrigidas por resposta). Se não for, não grave e avise: `⚠️ A regravação mudaria chaves ou valores que não foram respondidos: nada gravado.`
1202
+
1203
+ **4. Rules do perfil.** Se uma correção mudou `HUB`, `POSITION`, `AREA`, `SQUAD`, `ARTIFACT_STYLE` ou `RTK_ENABLED`, rode o **passo 8** de novo: ele já rodou com os valores antigos, e as rules em `$IDE/rules/` seriam de outro perfil.
1204
+
1205
+ **5. Resumo.** Liste o que foi corrigido e o que ficou pendente (respostas "Manter como está"), só com nomes de chave, e se o passo 8 rodou de novo.
1206
+
1207
+ ---
1208
+
1145
1209
  ### 10. Confirmar Criação
1146
1210
 
1147
1211
  ```
@@ -1425,7 +1489,8 @@ Bem-vindo! 🎉
1425
1489
  - [ ] Detectou IDE corretamente
1426
1490
  - [ ] Verificou se ENV.md já existe
1427
1491
  - [ ] Se ENV.md existe: ofereceu opção de Upgrade (C) além de Sobrescrever/Atualizar/Cancelar
1428
- - [ ] Se Upgrade: calculou diff template vs ENV.md e appendou apenas variáveis faltantes
1492
+ - [ ] Se Upgrade: calculou diff template vs ENV.md e acrescentou apenas as variáveis faltantes, no assunto de cada uma (sem bloco datado)
1493
+ - [ ] **Validou o ENV.md inteiro no passo 9.5**: uma pergunta por problema, regravação na ordem do template com as molduras de `# ====`, chaves fora do template no fim com `# (descontinuada)`, nenhum valor exibido nem trocado sem resposta
1429
1494
  - [ ] Coletou todas as variáveis obrigatórias
1430
1495
  - [ ] USER gravado no ENV.md a partir da identidade local
1431
1496
  - [ ] Validou MAX_AI_EXECUTION_PERCENTAGE (60-100) - para campos livres
@@ -339,7 +339,7 @@ Execute o checklist:
339
339
  - [ ] Framework JARVIS inicializado (`/jarvis-init`)
340
340
  - [ ] IDE detectada corretamente (Windsurf/Cursor/Claude/VS Code)
341
341
  - [ ] MCP Context7 instalado e respondendo (**obrigatório**)
342
- - [ ] MCP de task manager só se `TASK_MANAGER` estiver no ENV (não bloqueia)
342
+ - [ ] Board e git pela CLI oficial (`gh`/`glab`/`acli`), sem MCP; a CLI logada só importa se `TASK_MANAGER` estiver no ENV (não bloqueia)
343
343
  - [ ] IDE reiniciada após configurar MCPs (se configurou)
344
344
 
345
345
  Problemas Comuns
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: jarvis-report-issue
3
- description: Reporta um bug ou propõe uma melhoria no próprio framework Jarvis. Classifica o report (bug ou melhoria), monta o issue no formato do tipo e o abre no repo do Jarvis (o JARVIS_PROJECT, hoje no GitHub) pela CLI do host (gh issue create), com a label certa; sem a CLI, deixa o issue pronto em .jarvis/issues/.
3
+ description: Reporta um bug ou propõe uma melhoria no próprio framework Jarvis. Classifica o report (bug ou melhoria), monta a issue no formato do tipo e a abre no repo do Jarvis (o JARVIS_PROJECT, hoje no GitHub) pela CLI do host (gh issue create), com a label certa, só depois de mostrar o texto e o usuário dizer Sim (regra de ouro); sem a CLI ou sem o Sim, deixa a issue pronta em .jarvis/issues/.
4
4
  argument-hint: "[descrição opcional do problema ou da melhoria]"
5
5
  disable-model-invocation: false
6
6
  allowed-tools: Read Bash Grep Glob
@@ -13,7 +13,7 @@ metadata:
13
13
 
14
14
  # jarvis-report-issue — Bug ou melhoria no Framework Jarvis
15
15
 
16
- Você abre um issue no repositório do Jarvis: um **bug** (uma instrução do Jarvis induziu um erro) ou uma **melhoria** (funcionalidade nova ou mudança de comportamento pedida pelo usuário).
16
+ Você abre uma issue no repositório do Jarvis: um **bug** (uma instrução do Jarvis induziu um erro) ou uma **melhoria** (funcionalidade nova ou mudança de comportamento pedida pelo usuário).
17
17
 
18
18
  O usuário não precisa preencher nada — você é o autor do report.
19
19
 
@@ -55,13 +55,13 @@ Responda internamente às perguntas abaixo. Use o contexto da conversa atual:
55
55
  ```
56
56
 
57
57
  Se não houver contexto suficiente na conversa, pergunte ao usuário **uma** coisa antes de continuar:
58
- > "Para abrir o issue, preciso saber: qual skill ou workflow estava sendo executado?"
58
+ > "Para abrir a issue, preciso saber: qual skill ou workflow estava sendo executado?"
59
59
 
60
60
  ---
61
61
 
62
- ## Fase 2 — Montar o issue
62
+ ## Fase 2 — Montar a issue
63
63
 
64
- Com as respostas da Fase 1, monte o issue no formato abaixo.
64
+ Com as respostas da Fase 1, monte a issue no formato abaixo.
65
65
 
66
66
  **Título:** `[BUG] {artefato}: {descrição curta do problema em até 80 chars}`
67
67
 
@@ -134,7 +134,7 @@ Com `ARTIFACT_STYLE=human-generated`, troque a linha por `- **Reportado por:** {
134
134
  - **Reportado por:** IA, a partir do pedido do usuário
135
135
  ```
136
136
 
137
- Antes de abrir, se o pedido tiver pontos em conflito com as regras atuais ou ambíguos, pergunte ao usuário (uma pergunta por ponto) e registre as respostas em "Decisões".
137
+ Antes de abrir, se o pedido tiver pontos em conflito com as regras atuais ou ambíguos, pergunte ao usuário (uma pergunta por ponto) e registre as respostas em "Decisões". Além disso, a Fase 4 sempre mostra o texto e pergunta antes de abrir.
138
138
 
139
139
  ---
140
140
 
@@ -149,10 +149,10 @@ Se o projeto não estiver definido:
149
149
 
150
150
  > `🚫 BLOQUEADO: defina JARVIS_PROJECT=https://github.com/phelipperibeiro/jarvis-framework no ENV.md (URL completa).`
151
151
 
152
- Sem host (`grupo/repo`), o vendor não é adivinhado: o `jarvis vcs create-issue` sai com `3` e o issue vai para o fallback da Fase 4.
152
+ Sem host (`grupo/repo`), o vendor não é adivinhado: o `jarvis vcs create-issue` sai com `3` e a issue vai para o fallback da Fase 4.
153
153
  > → PARAR
154
154
 
155
- Login: o da CLI do host (`gh auth login`; no GitLab, `glab auth login`). Nenhum token é lido ou pedido. O `VERSION_CONTROL_ACCESS` do projeto não se aplica aqui: o issue vai para o repositório do Jarvis.
155
+ Login: o da CLI do host (`gh auth login`; no GitLab, `glab auth login`). Nenhum token é lido ou pedido. O `VERSION_CONTROL_ACCESS` do projeto não se aplica aqui: a issue vai para o repositório do Jarvis.
156
156
 
157
157
  Versão do Jarvis:
158
158
 
@@ -162,11 +162,13 @@ grep '"version"' package.json | head -1 | sed 's/.*"version": *"\([^"]*\)".*/\1/
162
162
 
163
163
  ---
164
164
 
165
- ## Fase 4 — Abrir o issue
165
+ ## Fase 4 — Abrir a issue
166
+
167
+ **Antes de abrir, mostre e pergunte (regra de ouro, `eng.integrations-rules.md`).** Mostre o título, a label e o corpo da issue e pergunte com `AskUserQuestion`: **"Abrir esta issue no repositório do Jarvis?"** → **Sim, abrir a issue** / **Não, manter só em `.jarvis/issues/`**. A pergunta vale mesmo quando o usuário pediu o report direto, porque ele ainda não viu o texto final. Com **Não**, grave o fallback abaixo (rode `unset STATUS` antes: indefinido conta como "não abriu") e não rode o `jarvis vcs create-issue`.
166
168
 
167
169
  ```bash
168
170
  BODY_FILE=$(mktemp)
169
- # gravar o corpo markdown do issue em $BODY_FILE
171
+ # gravar o corpo markdown da issue em $BODY_FILE
170
172
 
171
173
  REPO=$(grep -E '^(JARVIS_PROJECT|JARVIS_GITLAB_PROJECT)=' $IDE/ENV.md | tail -1 | cut -d= -f2-)
172
174
 
@@ -178,25 +180,25 @@ jarvis vcs create-issue \
178
180
  STATUS=$?
179
181
  ```
180
182
 
181
- **Cadeia (`rules/engineering/eng.integrations-rules.md`).** `0` → aberto. `1` (uso: arquivo do corpo inexistente, título vazio) → corrija a chamada e rode de novo. `3` (indisponível: CLI ausente, sem login, `JARVIS_PROJECT` sem host; nada enviado) → rode a CLI direto, se ela estiver logada (`gh issue create --repo {host}/{dono}/{repo} --title "$ISSUE_TITLE" --body-file "$BODY_FILE" --label "$LABEL"`); se também não der, o fallback abaixo. `4` (enviado com erro) → **não** repita: grave o fallback e avise para conferir no repositório se o issue foi aberto.
183
+ **Cadeia (`rules/engineering/eng.integrations-rules.md`).** `0` → aberta. `1` (uso: arquivo do corpo inexistente, título vazio) → corrija a chamada e rode de novo. `3` (indisponível: CLI ausente, sem login, `JARVIS_PROJECT` sem host; nada enviado) → rode a CLI direto, se ela estiver logada (`gh issue create --repo {host}/{dono}/{repo} --title "$ISSUE_TITLE" --body-file "$BODY_FILE" --label "$LABEL"`); se também não der, o fallback abaixo. `4` (enviado com erro) → **não** repita: grave o fallback e avise para conferir no repositório se a issue foi aberta.
182
184
 
183
- **Fallback — sem CLI ou sem conexão com o repositório.** Se a cadeia não abrir o issue, **não descarte o report**. Grave o issue montado em `.jarvis/issues/issue-{desc}.md`, na pasta do workspace (a que contém `$IDE/`), para a pessoa abrir manualmente:
185
+ **Fallback — sem CLI ou sem conexão com o repositório.** Se a cadeia não abrir a issue, **não descarte o report**. Grave a issue montada em `.jarvis/issues/issue-{desc}.md`, na pasta do workspace (a que contém `$IDE/`), para a pessoa abrir manualmente:
184
186
 
185
187
  - `{desc}` é o slug do título, sem o prefixo de tipo: minúsculas, sem acentos, palavras separadas por `-`, até 60 caracteres (ex.: `[MELHORIA] jarvis-init: Central docs padrão` → `issue-jarvis-init-central-docs-padrao.md`). Se o arquivo já existir, acrescente `-2`, `-3`…
186
188
  - Conteúdo: um cabeçalho com o que vai nos campos do formulário e, depois, o corpo exatamente como seria enviado:
187
189
 
188
190
  ```markdown
189
- <!-- Abrir em: {URL de novo issue} · Label: {LABEL} -->
190
- # {título do issue}
191
+ <!-- Abrir em: {URL de nova issue} · Label: {LABEL} -->
192
+ # {título da issue}
191
193
 
192
- {corpo do issue}
194
+ {corpo da issue}
193
195
  ```
194
196
 
195
- - `{URL de novo issue}` vem de `JARVIS_PROJECT` pelo vendor: GitHub `{repo}/issues/new`, GitLab `{repo}/-/issues/new`.
197
+ - `{URL de nova issue}` vem de `JARVIS_PROJECT` pelo vendor: GitHub `{repo}/issues/new`, GitLab `{repo}/-/issues/new`.
196
198
  - `.jarvis/` já fica fora do versionamento, então o arquivo não vai para nenhum commit.
197
199
 
198
200
  ```bash
199
- if [ "$STATUS" -ne 0 ]; then
201
+ if [ "${STATUS:-1}" -ne 0 ]; then # STATUS indefinido = o usuário disse Não, ou o envio falhou
200
202
  mkdir -p .jarvis/issues
201
203
  # gravar cabeçalho + "# $ISSUE_TITLE" + corpo em .jarvis/issues/issue-{desc}.md
202
204
  fi
@@ -210,31 +212,42 @@ rm -f "$BODY_FILE"
210
212
  Sucesso (exit 0):
211
213
 
212
214
  ```
213
- ✅ Issue aberto com sucesso!
215
+ ✅ Issue aberta com sucesso!
214
216
 
215
- Título : {título do issue}
217
+ Título : {título da issue}
216
218
  Artefato: {caminho do arquivo com problema}
217
219
  URL : {url retornada}
218
220
 
219
221
  O time do Jarvis vai revisar e corrigir o artefato.
220
222
  ```
221
223
 
224
+ Sem o Sim (o usuário recusou; o fallback da Fase 4 gravou o arquivo):
225
+
226
+ ```
227
+ ℹ️ Issue não aberta, como você pediu. O texto ficou em:
228
+ Arquivo : .jarvis/issues/issue-{desc}.md
229
+ Título : {título da issue}
230
+ Label : {LABEL}
231
+
232
+ Quando quiser abrir, peça para abrir a issue a partir desse arquivo.
233
+ ```
234
+
222
235
  Erro (o fallback da Fase 4 gravou o arquivo):
223
236
 
224
237
  ```
225
- ⚠️ Não consegui abrir o issue: {mensagem}
238
+ ⚠️ Não consegui abrir a issue: {mensagem}
226
239
 
227
- O issue ficou pronto para você abrir manualmente:
240
+ A issue ficou pronta para você abrir manualmente:
228
241
  Arquivo : .jarvis/issues/issue-{desc}.md
229
- Título : {título do issue}
242
+ Título : {título da issue}
230
243
  Label : {LABEL}
231
- Abrir em: {URL de novo issue}
244
+ Abrir em: {URL de nova issue}
232
245
 
233
246
  Cole o título no campo de título e o conteúdo abaixo do título no corpo.
234
247
  Para abrir direto da próxima vez, faça `gh auth login` (ou o login da CLI do host) e confira o JARVIS_PROJECT (URL completa).
235
248
  ```
236
249
 
237
- Com a CLI logada depois, a pessoa pode pedir para abrir o issue a partir desse arquivo, sem montar o report de novo. Depois que o issue for aberto, o arquivo pode ser apagado.
250
+ Com a CLI logada depois, a pessoa pode pedir para abrir a issue a partir desse arquivo, sem montar o report de novo. Depois que a issue for aberta, o arquivo pode ser apagado.
238
251
 
239
252
  ### Skills invocados durante a execução do skill
240
253