jarvis-ai-framework 3.0.0 → 4.0.0

package/templates/AGENTS.md

@@ -16,6 +16,7 @@ A pasta `templates/` contem **modelos de documentos** usados pelo framework para
 templates/
 ├── engineering/                    # Templates tecnicos
 │   ├── architecture-template.md    # Template de arquitetura
+│   ├── advisor-template.md         # Prompts e auditoria do Advisor
 │   ├── ARD-template.md             # Architecture Review Document
 │   ├── RFC-template.md             # Request For Comments
 │   ├── RFC-Playbook@1.0.0.md       # Playbook para RFCs
@@ -105,6 +106,7 @@ Use chaves `{...}` para indicar campos a serem preenchidos:
 | Template | Uso | Comando |
 |----------|-----|---------|
 | `architecture-template.md` | Design arquitetural | `/eng.start` |
+| `advisor-template.md` | Prompts do Advisor e modelo de auditoria | `/eng.start` |
 | `ARD-template.md` | Revisao de arquitetura | `/eng.create-ard` |
 | `RFC-template.md` | Proposta de mudanca | `/eng.create-rfc` |
 | `tech-spec-template.md` | Especificacao tecnica | `/eng.build-tech-spec` |

package/templates/ENV-template.md

@@ -58,12 +58,20 @@ RULES_FOLDER=.$IDE/rules
 SESSIONS_DIR=.jarvis/sessions
 
 # Pastas de produto (derivadas das de cima — em geral não precisa mexer)
+# PROD_DOCS: no projeto único (sem workspace), o /jarvis-init grava docs/jarvis/product
+# (com docs/jarvis/* no .gitignore); no modo workspace, $DOCS_FOLDER/$PROD_FOLDER_NAME.
 PROD_FOLDER_NAME=product
 PROD_RULES=$RULES_FOLDER/$PROD_FOLDER_NAME
 PROD_FLOWS=.$IDE/$FLOWS_FOLDER
 PROD_TEMPLATES=.$IDE/$TEMPLATES_FOLDER/$PROD_FOLDER_NAME
 PROD_DOCS=$DOCS_FOLDER/$PROD_FOLDER_NAME
 
+# Modo de condução dos comandos de produto (prod.*) e do eng.create-ard.
+#   product-led      = para PMs: fluxo direto, sem explicações extras (padrão se vazio)
+#   developer-guided = para devs e futuros PMs: uma pergunta por vez, explica cada termo e etapa
+# Perguntado sempre pelo /jarvis-init. Para trocar, rode o /jarvis-init ou edite aqui.
+PROD_MODE=
+
 
 # --- Especializações por área -------------------------------------------------
 # Skills especializados que o Jarvis carrega junto com o skill base de cada área.
@@ -144,6 +152,16 @@ SMTP=[google, ses, sendgrid]
 RTK_ENABLED=false
 
 
+# --- Advisor (opcional) ------------------------------------------------------
+# Modelos oferecidos quando o usuário escolhe usar o Advisor no início do eng.start,
+# separados por vírgula. Até 4 viram opções da pergunta; o resto fica em "Outro".
+# Vazio ou ausente = o Advisor usa "Sonnet 5.5" (fallback).
+# Tradução para a IDE pela família (primeira palavra, em minúsculas: Sonnet → sonnet,
+# Opus → opus, Fable → fable). No Claude Code só a família é respeitada: "Opus 5.5"
+# e "Opus 5" abrem o mesmo modelo; remova um deles se quiser só opções distintas.
+ADVISOR_MODELS="Sonnet 5.5,Opus 5.5,Opus 5,Fable 5.1"
+
+
 # --- Data Engineering (só se HUB=DATA) ---------------------------------------
 # Obrigatório quando HUB=DATA. Omitir o bloco inteiro se o HUB for outro.
 DATA_ORCHESTRATOR=[airflow, prefect, dagster, glue-scheduler]
@@ -188,11 +206,18 @@ JARVIS_PROJECT=https://github.com/phelipperibeiro/jarvis-framework
 
 
 # --- Central docs (opcional) -------------------------------------------------
-# Repo de documentação canônica (PRD, FRD, ARD, RFC). Em branco = desligado.
-CENTRAL_DOCS_REPO=
+# Onde fica a documentação canônica (PRD, FRD, épicos, ARD, RFC). Em branco = desligado.
+# Nunca dentro do versionamento de um repositório de código.
+#   CENTRAL_DOCS_STORAGE: filesystem (s3 e gdrive virão nas issues #144 e #145)
+#   CENTRAL_DOCS_LOCATION: pasta do Central docs, relativa à pasta do workspace ou absoluta.
+#     Padrão do /jarvis-init: ./central-docs (modo workspace, no .gitignore do workspace)
+#     ou docs/jarvis/central-docs (projeto único, com docs/jarvis/* no .gitignore).
+#   Se a pasta for um clone de um repositório de documentação (tem .git): git pull antes
+#   de ler e branch + commit + push + PR ao publicar. Sem .git: grava direto na pasta.
+CENTRAL_DOCS_STORAGE=
+CENTRAL_DOCS_LOCATION=
+# Só quando a pasta tem .git: branch lida no pull e branch base dos PRs.
 CENTRAL_DOCS_REF=main
 CENTRAL_DOCS_TARGET_BRANCH=main
-# Revisores padrão dos MRs (separados por vírgula).
+# Revisores padrão dos PRs (separados por vírgula; vão na descrição).
 CENTRAL_DOCS_REVIEWERS=
-# TTL do cache opcional (redis-cli, se existir). 3600 = 1 hora.
-CENTRAL_DOCS_CACHE_TTL=3600

package/templates/engineering/ARD-template.md

@@ -1,3 +1,39 @@
+---
+# Modelo de IA recomendado para trabalhar neste documento. Se a sessão estiver em outro,
+# o comando avisa e segue (você decide se troca). Opções: opus | sonnet | haiku
+recommended_model: opus
+
+# Identificador único do ARD, em sequência (ex.: ARD-001). Vai no nome do arquivo.
+id: [ARD-xxx]
+
+# Título da arquitetura. Vai no título e, em kebab-case, no nome do arquivo.
+name: [Título da Arquitetura]
+
+# Versão do documento (X.Y.Z). Atualize a cada alteração.
+version: [1.0.0]
+
+# Em que ponto este ARD está no ciclo de vida.
+# Opções: proposed | in_progress | in_review | approved
+# proposed = proposta, ainda em discussão | in_progress = arquitetura em desenvolvimento
+# in_review = em validação com os revisores | approved = finalizada e aprovada
+status: [um dos valores acima]
+
+# Documentos relacionados: RFC (proposta técnica), FRD (requisitos funcionais), PRD (requisitos de produto).
+related: [RFC-xxx, FRD-xxx, PRD-xxx]
+
+# Data de criação (YYYY-MM-DD).
+created_at: [YYYY-MM-DD]
+
+# Data da última alteração (YYYY-MM-DD).
+updated_at: [YYYY-MM-DD]
+
+# Quem criou o documento (Tech Lead ou arquiteto responsável).
+created_by: [nome]
+
+# Quem editou o documento por último.
+last_editor: [nome]
+---
+
 # 🧱 ARD Template — Architecture Requirement Document
 
 **Arquivo:** /docs/engineering/ARD/ARD-xxx-nome-da-arquitetura.md
@@ -6,12 +42,9 @@
 
 ## 🏗️ ARD-[número] — [Título da Arquitetura]
 
-**Status:** Proposta / Em desenvolvimento / Em validação / Finalizada  
-**Data:** [dd/mm/yyyy]  
-**Autor:** [Tech Lead / Arquiteto responsável]  
-**Revisores:** [Chapter Leads, Eng. de Plataforma, etc.]  
-**Relacionado a:** [RFC-xxx], [FRD-xxx], [PRD-xxx]  
-**Versão:** [1.0]
+**Revisores:** [Chapter Leads, Eng. de Plataforma, etc.]
+
+> Status, versão, datas, autor e documentos relacionados ficam no frontmatter (topo do arquivo).
 
 ---
 

package/templates/engineering/advisor-template.md

@@ -0,0 +1,65 @@
+# Advisor — prompts e auditoria
+
+> Usado pelo `eng.start` (e, por exceção, pelo `eng.plan` e pelo `eng.work`) com o agente `eng.advisor.agent`. Os campos `{...}` são preenchidos pelo agente principal.
+
+## Prompt 1 — Carga inicial (uma vez por tarefa, na primeira questão em aberto)
+
+```
+Você é o Advisor desta tarefa ({TASK_MANAGER_KEY}). Você esclarece as questões em aberto que eu enviar, uma por vez, e devolve a sugestão mais adequada; ela é adotada como decisão final. Eu (agente principal) faço a análise do card, a documentação, a execução e os registros.
+
+Agora, somente leitura (não edite, não troque de branch, não faça commit; no GitHub, só consulta): leia as fontes de contexto do seu arquivo de agente — card, documentos de especificação ($PROD_DOCS, seguindo task_link e related_*), pastas de sessão ({SESSAO_ENG} e {SESSAO_PROD}) e, se preciso, o repositório {REPO}.
+
+Etapas da tarefa:
+| Etapa | O que acontece | Onde o Advisor entra |
+| Alerta no início do eng.start | O usuário escolhe usar o Advisor e o modelo | Ainda não existe |
+| eng.start | Escrevo o architecture.md; o que diverge do código ou é ambíguo vira "Questões em Aberto" | Aqui: você orienta cada questão |
+| Orientação acatada | Atualizo o architecture.md e registro | Não |
+| Registro da auditoria | Posto um comentário na issue com as questões e as suas sugestões (sem TASK_MANAGER, só no architecture.md) | Não |
+| eng.plan / eng.work | Plano e implementação | Só por exceção: questão nova em aberto |
+| Commit e PR | Um commit; o usuário valida em "Files changed" | Não |
+| Merge e fechamento | O usuário faz o merge | Não |
+
+Responda SOMENTE com "Contexto lido" + os caminhos que leu + uma frase de até 20 palavras sobre o objetivo da tarefa. Se o contexto for insuficiente para orientar, responda "Preciso de ajuda para localizar o contexto", dizendo onde procurou e o que precisa.
+```
+
+## Prompt 2 — Questão em aberto (uma mensagem por questão)
+
+```
+Questão {QN} de {TOTAL} ({TASK_MANAGER_KEY}). Texto completo na seção 8 do architecture.md ({CAMINHO}).
+
+Contexto: {por que a dúvida existe e o impacto na implementação}
+Arquivos/componentes envolvidos: {arquivo — relação}
+Dúvida: {o que precisa ser decidido}
+Opções:
+1. {opção} — como funciona, vantagens, desvantagens, impacto
+2. {opção} — ...
+3. {opção} — ...
+4. Outra (sua, se houver)
+Sugestão do agente principal: {N}, porque {motivo}
+
+Analise o repositório só se precisar para ter certeza (sem chutar). Responda (até ~250 palavras):
+1. SUGESTÃO DO ADVISOR (opção 1-3 ou a 4 detalhada) · 2. DIVERGÊNCIA · 3. BASE · 4. ANÁLISE NO REPOSITÓRIO · 5. RELAÇÃO COM OUTRAS TAREFAS · 6. CERTEZA (escrito / confirmado no código / inferência). Não altere arquivos; aponte o risco se uma opção for destrutiva ou fugir do card.
+```
+
+## Modelo do comentário de auditoria (postado pelo agente principal)
+
+```
+## Auditoria — questões do architecture.md
+
+Questões levantadas no `architecture.md` desta issue e a sugestão do Advisor ({modelo}). **A sugestão do Advisor prevalece e é a decisão adotada.** Análise, documentação, execução e este registro são do agente principal.
+
+### {QN} — {título}
+- **Contexto:** {...}
+- **Arquivos envolvidos:** {...}
+- **Opções:** 1 — {...} · 2 — {...} · 3 — {...} · 4 — Outra
+- **Sugestão do agente principal:** {N}
+- **Sugestão do Advisor (decisão adotada):** **{N}**
+- **Divergência:** {motivo técnico, ou "sem divergência"}
+- **Base:** {...}
+- **Análise no repositório:** {arquivos e linhas, ou "não foi necessário"}
+- **Certeza:** {alta|média|baixa} — escrito: {...}; confirmado no código: {...}; inferência: {...}
+- **Impacto da decisão:** {...}
+- **Levantada em:** {eng.start | eng.plan | eng.work} (fora do eng.start, é lacuna a citar no PR)
+
+Link do PR: {#PR} (preenchido quando existir; se a decisão for revista na execução, atualizar este mesmo comentário)
+```

package/templates/engineering/architecture-template.md

@@ -5,7 +5,9 @@
 
 > **Criado em:** {DATA}  
 > **Issue:** {JIRA_ISSUE_KEY}  
-> **Status:** 🔄 Em Revisão | ✅ Aprovado | ❌ Rejeitado
+> **Branch base:** {main | dev | outra — perguntada no eng.start; destino do PR no eng.pr}  
+> **Status:** 🔄 Em Revisão | ✅ Aprovado | ❌ Rejeitado  
+> **Advisor:** {modelo escolhido no início do eng.start} | não utilizado
 
 ---
 
@@ -245,9 +247,56 @@ graph TD
 
 ## 8. Questões em Aberto
 
-| ID  | Questão                        | Responsável | Deadline | Status   |
-| --- | ------------------------------ | ----------- | -------- | -------- |
-| Q1  | {questão ainda não respondida} | {quem}      | {data}   | 🔄 Aberta |
+> Tudo que for **diferente do código ou ambíguo no card** vira uma questão aqui, detalhada a ponto de outro agente entendê-la sem reconstruir a análise. No mínimo 3 opções, mais a **4 — Outra**.
+> **Com Advisor** (cabeçalho), a sugestão do Advisor prevalece e é a decisão adotada; o agente principal não a substitui nem contesta. **Sem Advisor**, "Sugestão do Sub-Agent (Advisor)" e "Divergência" ficam "N/A (Advisor não utilizado)", a regra em destaque é omitida e a decisão é a do usuário ao revisar o documento.
+> Questão levantada depois do `eng.start` (consulta por exceção) entra aqui, numerada em sequência, marcada "levantada no `eng.plan`" ou "no `eng.work`". Sem questão em aberto, escreva "Nenhuma" e o motivo em uma frase.
+
+| ID | Questão                      | Responsável                 | Deadline | Status                     |
+| -- | ---------------------------- | --------------------------- | -------- | -------------------------- |
+| Q1 | {resumo objetivo da questão} | {Advisor \| nome do usuário} | {— \| data} | {✅ Decidida \| 🔄 Aberta} |
+
+### Q1 — {Título da questão}
+
+**Contexto:**
+{Explicação detalhada do problema e por que a decisão é necessária.}
+
+**Arquivos/componentes envolvidos:**
+* `{arquivo/caminho}` — {relação com a questão}
+
+**Dúvida:**
+{Descrição clara e inequívoca do que precisa ser decidido.}
+
+**Opções:**
+
+**1. {Opção 1}**
+* Como funciona: {descrição}
+* Vantagens: {vantagens}
+* Desvantagens: {desvantagens}
+* Impacto: {impacto}
+
+**2. {Opção 2}** (mesmo formato)
+
+**3. {Opção 3}** (mesmo formato)
+
+**4. Outra**
+* Alternativa adicional identificada pelo Sub-Agent/Advisor, detalhada caso ele entenda que nenhuma das opções anteriores é a melhor abordagem.
+
+**Sugestão do Agente Principal (Architect):**
+{recomendação do agente principal + justificativa técnica}
+
+**Sugestão do Sub-Agent (Advisor):**
+{recomendação independente do Advisor + justificativa técnica}
+
+**Decisão adotada:**
+**{recomendação do Sub-Agent/Advisor}**
+
+> **Regra:** a recomendação do Advisor sempre prevalece e deve ser adotada na implementação, independentemente de ser igual ou diferente da recomendação do Agente Principal.
+
+**Divergência:**
+{se houver diferença entre as recomendações, explicar objetivamente por que o Advisor escolheu uma abordagem diferente.}
+
+**Impacto da decisão:**
+{consequências da decisão adotada para a arquitetura e implementação.}
 
 ---
 

package/templates/product/prod-breakdown-template.md

@@ -1,8 +1,26 @@
 ---
-name: [Name from PRD]  
+# Modelo de IA recomendado para trabalhar neste documento. Se a sessão estiver em outro,
+# o comando avisa e segue (você decide se troca). Opções: opus | sonnet | haiku
+recommended_model: opus
+
+# Nome do breakdown (o mesmo do PRD ou FRD que está sendo fatiado).
+name: [Name from PRD]
+
+# Time (squad) responsável pela entrega.
 team: [Team Name]
+
+# Em que ponto este documento está no ciclo de vida (lista em rules/product/prod-rules.md).
+# Opções: icebox | in_review | backlog | in_progress | in_production | cancelled | deprecated
+# icebox = ideia aguardando priorização | in_review = sendo estudado ou revisado | backlog = definido, aguardando implementação
+# in_progress = em desenvolvimento | in_production = em produção
+# cancelled = cancelado antes de ser entregue | deprecated = esteve em produção e foi descontinuado
+status: [um dos valores acima]
+
+# Data de criação (YYYY-MM-DD).
 created_at: [YYYY-MM-DD]
-last_updated: [YYYY-MM-DD]  
+
+# Data da última alteração (YYYY-MM-DD).
+updated_at: [YYYY-MM-DD]
 ---
 
 ## Resumo do plano detalhado (breakdown)

package/templates/product/prod-discovery-template.md

@@ -1,11 +1,34 @@
 ---
+# Modelo de IA recomendado para trabalhar neste documento. Se a sessão estiver em outro,
+# o comando avisa e segue (você decide se troca). Opções: opus | sonnet | haiku
+recommended_model: opus
+
+# Identificador único, em sequência (ex.: discovery-001). Vai no nome do arquivo e nos campos related_* de outros documentos.
 id: {discovery-001}
+
+# Nome curto do documento. Vai no título e, em kebab-case, no nome do arquivo.
 name: {nome dessa ideia}
-status: {in_review enquanto o rascunho existe | cancelled se o veredito for do_not_proceed}
+
+# Situação do rascunho. O discovery tem ciclo próprio (rules/product/prod-rules.md).
+# Opções: in_review | cancelled
+# in_review = rascunho em andamento ou concluído | cancelled = o veredito foi do_not_proceed
+status: {in_review | cancelled}
+
+# Recomendação do discovery: vale seguir com essa ideia? Fica vazio durante a entrevista.
+# Opções: proceed | investigate_more | do_not_proceed
+# proceed = vale especificar | investigate_more = há lacuna crítica | do_not_proceed = não seguir (status passa a cancelled)
 verdict: {vazio durante a entrevista | proceed | investigate_more | do_not_proceed}
+
+# Data de criação (YYYY-MM-DD).
 created_at: {YYYY-MM-DD}
+
+# Data da última alteração (YYYY-MM-DD).
 updated_at: {YYYY-MM-DD}
+
+# Quem criou o documento.
 created_by: {nome de quem criou esse doc}
+
+# Quem editou o documento por último.
 last_editor: {nome de quem editou por último}
 ---
 

package/templates/product/prod-epic-template.md

@@ -1,15 +1,46 @@
 ---
+# Modelo de IA recomendado para trabalhar neste documento. Se a sessão estiver em outro,
+# o comando avisa e segue (você decide se troca). Opções: opus | sonnet | haiku
+recommended_model: opus
+
+# Identificador único, em sequência (ex.: EPIC-001). Vai no nome do arquivo e nos campos related_* de outros documentos.
 id: {EPIC-001}
+
+# Nome curto do documento. Vai no título e, em kebab-case, no nome do arquivo.
 name: {nome desse épico}
+
+# Versão do documento (X.Y.Z). Atualize a cada alteração.
 version: {X.Y.Z - atualizar sempre que houver alteração}
-status: {icebox|in_review|in_progress|in_production|deprecated}
+
+# Em que ponto este documento está no ciclo de vida (lista em rules/product/prod-rules.md).
+# Opções: icebox | in_review | backlog | in_progress | in_production | cancelled | deprecated
+# icebox = ideia aguardando priorização | in_review = sendo estudado ou revisado | backlog = definido, aguardando implementação
+# in_progress = em desenvolvimento | in_production = em produção
+# cancelled = cancelado antes de ser entregue | deprecated = esteve em produção e foi descontinuado
+status: {um dos valores acima}
+
+# Link do card no task manager do projeto (TASK_MANAGER no ENV.md). Remova a linha se não houver.
 task_link: {URL referêncial no $TASK_MANAGER - se existir. Se não, ignore essa linha}
+
+# PRD relacionado (Product Requirements Document: o problema e o que vamos construir).
 related_prd: {path PRD relacionado, exemplo /master-docs/product/prd-001.md}
+
+# FRD relacionado (Functional Requirements Document: o comportamento detalhado de uma funcionalidade).
 related_frd: {path FRD relacionado, exemplo /master-docs/product/frds/frd-001.md}
+
+# Discovery de origem (o rascunho da ideia, anterior ao PRD). Remova a linha se não houver.
 related_discovery: {path do discovery de origem, exemplo $PROD_DOCS/discoveries/discovery-001-nome.md. Se não existir, ignore essa linha}
+
+# Data de criação (YYYY-MM-DD).
 created_at: {YYYY-MM-DD}
+
+# Data da última alteração (YYYY-MM-DD).
 updated_at: {YYYY-MM-DD}
+
+# Quem criou o documento.
 created_by: {nome de quem criou esse doc}
+
+# Quem editou o documento por último.
 last_editor: {nome de quem editou por último}
 ---
 

package/templates/product/prod-frd-template.md

@@ -1,13 +1,40 @@
 ---
+# Modelo de IA recomendado para trabalhar neste documento. Se a sessão estiver em outro,
+# o comando avisa e segue (você decide se troca). Opções: opus | sonnet | haiku
+recommended_model: opus
+
+# Identificador único, em sequência (ex.: FRD-001). Vai no nome do arquivo e nos campos related_* de outros documentos.
 id: {FRD-001}
+
+# Nome curto do documento. Vai no título e, em kebab-case, no nome do arquivo.
 name: {nome desse frd}
+
+# Versão do documento (X.Y.Z). Atualize a cada alteração.
 version: {X.Y.Z - atualizar sempre que houver alteração}
-status: {$ITEM_STATUS}
+
+# Em que ponto este documento está no ciclo de vida (lista em rules/product/prod-rules.md).
+# Opções: icebox | in_review | backlog | in_progress | in_production | cancelled | deprecated
+# icebox = ideia aguardando priorização | in_review = sendo estudado ou revisado | backlog = definido, aguardando implementação
+# in_progress = em desenvolvimento | in_production = em produção
+# cancelled = cancelado antes de ser entregue | deprecated = esteve em produção e foi descontinuado
+status: {um dos valores acima}
+
+# Quem editou o documento por último.
 last_editor: {nome de quem editou por último}
+
+# Data da última alteração (YYYY-MM-DD).
 updated_at: {YYYY-MM-DD}
+
+# PRD relacionado (Product Requirements Document: o problema e o que vamos construir).
 related_prd: {Lista de PRDs que são relacionadas a esse PRD, se forem vários, utilize sintaxe compatível com YAML}
+
+# Discovery de origem (o rascunho da ideia, anterior ao PRD). Remova a linha se não houver.
 related_discovery: {path do discovery de origem, exemplo $PROD_DOCS/discoveries/discovery-001-nome.md. Se não existir, ignore essa linha}
+
+# Data de criação (YYYY-MM-DD).
 created_at: {YYYY-MM-DD}
+
+# Quem criou o documento.
 created_by: {nome de quem criou esse doc}
 ---
 
@@ -138,7 +165,7 @@ Ele é um sistema de gestão de dados pessoais de saúde, que agrega informaçõ
 - {Exclusão adicional}
 
 ## Especificações relacionadas
-{liste todos os PRDs, FRDs ou outros documentos relacionados a este FRD fazendo uma análise prévia do projeto e das especificações existentes no `$CENTRAL_DOCS_REPO`. Pergunte para o usuário se existe outras relações que ele conheça. Antes de adicionar as sugestões, confirme com o usuário se elas estão corretas.}
+{liste todos os PRDs, FRDs ou outros documentos relacionados a este FRD fazendo uma análise prévia do projeto e das especificações existentes no Central docs (`jarvis docs sync`). Pergunte para o usuário se existe outras relações que ele conheça. Antes de adicionar as sugestões, confirme com o usuário se elas estão corretas.}
 
 **PRDs relacionadas**:
 | ID | Título | Descrição |

package/templates/product/prod-issue-template.md

@@ -1,16 +1,51 @@
 ---
+# Modelo de IA recomendado para trabalhar neste documento. Se a sessão estiver em outro,
+# o comando avisa e segue (você decide se troca). Opções: opus | sonnet | haiku
+recommended_model: opus
+
+# Identificador único, em sequência (ex.: STORY-001, TASK-001, BUG-001). Vai no nome do arquivo e nos campos related_* de outros documentos.
 id: {issue_type-001}
+
+# Nome curto do documento. Vai no título e, em kebab-case, no nome do arquivo.
 name: {nome dessa issue}
+
+# Tipo da issue.
+# Opções: Story | Task | Bug
+# Story = história de usuário (valor para quem usa) | Task = tarefa técnica | Bug = defeito a corrigir
 type: {Story, Task, Bug}
+
+# PRD relacionado (Product Requirements Document: o problema e o que vamos construir).
 related_prd: {path PRD relacionado, exemplo /master-docs/product/prd-001.md}
+
+# Épico ao qual esta issue pertence (o agrupador de histórias e tarefas). Remova a linha se não houver.
 related_epic: {nome do Epico relacionado, exemplo /master-docs/product/epics/epic-001.md. Se não existir, ignore essa linha}
+
+# FRD relacionado (Functional Requirements Document: o comportamento detalhado de uma funcionalidade).
 related_frd: {path FRD relacionado, exemplo /master-docs/product/frds/frd-001.md}
+
+# Discovery de origem (o rascunho da ideia, anterior ao PRD). Remova a linha se não houver.
 related_discovery: {path do discovery de origem, exemplo $PROD_DOCS/discoveries/discovery-001-nome.md. Se não existir, ignore essa linha}
+
+# Data de criação (YYYY-MM-DD).
 created_at: {YYYY-MM-DD}
+
+# Data da última alteração (YYYY-MM-DD).
 updated_at: {YYYY-MM-DD}
+
+# Link do card no task manager do projeto (TASK_MANAGER no ENV.md). Remova a linha se não houver.
 task_link: {URL referêncial no $TASK_MANAGER - se existir. Se não, ignore essa linha}
-status: {icebox|in_review|in_progress|in_production|deprecated}
+
+# Em que ponto este documento está no ciclo de vida (lista em rules/product/prod-rules.md).
+# Opções: icebox | in_review | backlog | in_progress | in_production | cancelled | deprecated
+# icebox = ideia aguardando priorização | in_review = sendo estudado ou revisado | backlog = definido, aguardando implementação
+# in_progress = em desenvolvimento | in_production = em produção
+# cancelled = cancelado antes de ser entregue | deprecated = esteve em produção e foi descontinuado
+status: {um dos valores acima}
+
+# Quem criou o documento.
 created_by: {nome de quem criou esse doc}
+
+# Quem editou o documento por último.
 last_editor: {nome de quem editou por último}
 ---
 

package/templates/product/prod-prd-template.md

@@ -1,15 +1,46 @@
 ---
+# Modelo de IA recomendado para trabalhar neste documento. Se a sessão estiver em outro,
+# o comando avisa e segue (você decide se troca). Opções: opus | sonnet | haiku
+recommended_model: opus
+
+# Identificador único, em sequência (ex.: PRD-001). Vai no nome do arquivo e nos campos related_* de outros documentos.
 id: {PRD-001}
+
+# Nome curto do documento. Vai no título e, em kebab-case, no nome do arquivo.
 name: {nome desse prd}
+
+# Versão do documento (X.Y.Z). Atualize a cada alteração.
 version: {X.Y.Z - atualizar sempre que houver alteração}
-status: {$ITEM_STATUS}
+
+# Em que ponto este documento está no ciclo de vida (lista em rules/product/prod-rules.md).
+# Opções: icebox | in_review | backlog | in_progress | in_production | cancelled | deprecated
+# icebox = ideia aguardando priorização | in_review = sendo estudado ou revisado | backlog = definido, aguardando implementação
+# in_progress = em desenvolvimento | in_production = em produção
+# cancelled = cancelado antes de ser entregue | deprecated = esteve em produção e foi descontinuado
+status: {um dos valores acima}
+
+# Quem editou o documento por último.
 last_editor: {nome de quem editou por último}
+
+# Data da última alteração (YYYY-MM-DD).
 updated_at: {YYYY-MM-DD}
+
+# Repositórios de código onde este produto é implementado.
 related_repo: {URLs de repositórios relacionados, se forem vários, utilize sintaxe compatível com YAML}
+
+# PRD relacionado (Product Requirements Document: o problema e o que vamos construir).
 related_prd: {Lista de PRDs que são relacionadas a esse PRD, se forem vários, utilize sintaxe compatível com YAML}
+
+# FRD relacionado (Functional Requirements Document: o comportamento detalhado de uma funcionalidade).
 related_frd: {Lista de FRDs que são relacionadas a esse PRD, se forem vários, utilize sintaxe compatível com YAML}
+
+# Discovery de origem (o rascunho da ideia, anterior ao PRD). Remova a linha se não houver.
 related_discovery: {path do discovery de origem, exemplo $PROD_DOCS/discoveries/discovery-001-nome.md. Se não existir, ignore essa linha}
+
+# Data de criação (YYYY-MM-DD).
 created_at: {YYYY-MM-DD}
+
+# Quem criou o documento.
 created_by: {nome de quem criou esse doc}
 ---
 
@@ -148,7 +179,7 @@ Estes são indicadores que podem ser usados para medir o sucesso dessa solução
 
 
 ## Especificações relacionadas
-{liste todos os PRDs, FRDs ou outros documentos relacionados a este FRD fazendo uma análise prévia do projeto e das especificações existentes no `$CENTRAL_DOCS_REPO`. Pergunte para o usuário se existe outras relações que ele conheça. Antes de adicionar as sugestões, confirme com o usuário se elas estão corretas.}
+{liste todos os PRDs, FRDs ou outros documentos relacionados a este FRD fazendo uma análise prévia do projeto e das especificações existentes no Central docs (`jarvis docs sync`). Pergunte para o usuário se existe outras relações que ele conheça. Antes de adicionar as sugestões, confirme com o usuário se elas estão corretas.}
 
 **PRDs relacionadas**:
 | ID | Título | Descrição |

package/workflows/engineering/eng.build-tech-spec.md

@@ -54,7 +54,7 @@ Transformar uma história de usuário (user story) do Jira em uma **Tech Spec co
 | Passo | Skill | Condição |
 |-------|-------|----------|
 | Processo de Criação › verificação de necessidade de RFC | `/eng.create-rfc` | Se a Tech Spec atender aos critérios que exigem RFC e o usuário escolher "A: Criar uma RFC agora" |
-| Caminho A › 2A.2 Análise de Documentação de Produto | `/jarvis-docs-central` | Se `CENTRAL_DOCS_REPO` estiver configurado (buscar PRD/FRD relacionados do épico) |
+| Caminho A › 2A.2 Análise de Documentação de Produto | `/jarvis-docs-central` | Se `CENTRAL_DOCS_STORAGE` estiver configurado (buscar PRD/FRD relacionados do épico) |
 | FASE 7 › 7.3 Criação no Jira | `ferramenta MCP/API do Jira` (referência a confirmar) | Se o projeto usar Jira e houver ferramenta MCP ou API disponível; senão fornecer template para criação manual (o texto não nomeia a ferramenta) |
 
 ---
@@ -264,7 +264,7 @@ Foco em entender o sistema como um todo — não arquivos específicos, mas fron
 #### 2A.2 Análise de Documentação de Produto
 
 - Verifique se há PRD ou FRD relacionado ao épico em `$DOCS_FOLDER` ou no $TASK_MANAGER
-- Se `CENTRAL_DOCS_REPO` configurado: buscar docs via skill `jarvis-docs-central`
+- Se `CENTRAL_DOCS_STORAGE` configurado: buscar docs via skill `jarvis-docs-central`
 
 #### 2A.3 Identificação de Restrições
 

package/workflows/engineering/eng.create-ard-from-code.md

@@ -22,8 +22,8 @@ priorizando a **arquitetura observada no código do repositório**, usando o tem
 | Passo | Skill | Condição |
 |-------|-------|----------|
 | Objetivo | `eng.agent` (agente) | Sempre — identidade do workflow (alinhamento com `eng.agent.md`) |
-| Passo 1 – Verificar PRD | `/jarvis-docs-central` (via `jarvis docs sync --silent`) | Se `CENTRAL_DOCS_REPO` estiver definido no ENV.md |
-| Passo 7 – Publicar no Central Docs | `/jarvis-docs-central` (via `jarvis docs publish --tipo ard`) | Se `CENTRAL_DOCS_REPO` estiver definido, o ARD estiver aprovado e o usuário aceitar publicar |
+| Passo 1 – Verificar PRD | `/jarvis-docs-central` (via `jarvis docs sync --silent`) | Se `CENTRAL_DOCS_STORAGE` estiver definido no ENV.md |
+| Passo 7 – Publicar no Central Docs | `/jarvis-docs-central` (via `jarvis docs publish --tipo ard`) | Se `CENTRAL_DOCS_STORAGE` estiver definido, o ARD estiver aprovado e o usuário aceitar publicar |
 
 ---
 
@@ -60,7 +60,7 @@ priorizando a **arquitetura observada no código do repositório**, usando o tem
 - Defina o `ARD-ID` automaticamente assim:
   - Se a pasta `$DOCS_FOLDER/engineering/ARD/` existir e houver arquivos no padrão `ARD-###-*.md`, use o maior `###` + 1.
 - Defina:
-  - `Status`
+  - `Status` (campo `status` no frontmatter: `proposed | in_progress | in_review | approved`)
   - `Caminho do arquivo` (`$DOCS_FOLDER/engineering/ARD/{ARD-ID}-{slug}.md` ou caminho fornecido para iteração)
 
 ---
@@ -69,7 +69,7 @@ priorizando a **arquitetura observada no código do repositório**, usando o tem
 
 ### 1.1 – Buscar PRD no Central Docs (condicional)
 
-Se `CENTRAL_DOCS_REPO` definido no ENV.md:
+Se `CENTRAL_DOCS_STORAGE` definido no ENV.md:
 
 1. Executar busca automática no central-docs:
    ```bash
@@ -238,7 +238,7 @@ Entregar:
 
 ## Passo 7 – Publicar no Central Docs (condicional)
 
-Se `CENTRAL_DOCS_REPO` definido no ENV.md **E** o usuário aprovar o ARD:
+Se `CENTRAL_DOCS_STORAGE` definido no ENV.md **E** o usuário aprovar o ARD:
 
 1. Perguntar ao usuário:
    ```
@@ -248,20 +248,18 @@ Se `CENTRAL_DOCS_REPO` definido no ENV.md **E** o usuário aprovar o ARD:
    ```
 
 2. Se **Sim**:
-   - Extrair o slug do nome do arquivo (ex: `ARD-001-api-wallet-auth.md` → `api-wallet-auth`)
    - Executar:
      ```bash
      jarvis docs publish \
        --file {caminho_do_ard} \
-       --tipo ard \
-       --feature {slug}
+       --tipo ard
      ```
    
 3. Informar resultado:
-   - ✅ Sucesso: "ARD publicado no central-docs. MR criado: [URL]"
+   - ✅ Sucesso: "ARD publicado no Central docs." (com git: "PR aberto: [URL]")
    - ❌ Erro: Exibir mensagem de erro e orientar troubleshooting
 
 4. Se **Não**:
-   - Informar: "Para publicar depois, execute: `jarvis docs publish --file {caminho} --tipo ard --feature {slug}`"
+   - Informar: "Para publicar depois, execute: `jarvis docs publish --file {caminho} --tipo ard`"
 
-> **Nota**: A publicação cria um Merge Request no GitLab. O ARD só será visível no central-docs após aprovação e merge do MR.
+> **Nota**: se a pasta do Central docs for um repositório git, a publicação abre um Pull/Merge Request e o ARD só entra na branch base depois do merge. Sem git, o documento é gravado direto e o índice é regenerado.