jarvis-ai-framework 3.2.0 → 4.0.0

package/skills/jarvis-docs-central/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: jarvis-docs-central
-description: Integração com repositório centralizado de documentação (GitLab, GitHub ou Bitbucket). Busca e publica PRDs, FRDs, ARDs e RFCs via API do vendor.
+description: Integração com o Central docs, a documentação aprovada (PRD, FRD, épicos, histórias, ARD, RFC) guardada por um adaptador de armazenamento (hoje uma pasta do disco, com git opcional). Busca, publica e indexa pelo CLI jarvis docs.
 argument-hint: "[contexto da tarefa]"
 allowed-tools: Bash Read Write
 disable-model-invocation: false
 license: AGPL-3.0
 metadata:
   author: jarvis-team
-  version: "3.0"
+  version: "4.0"
   area: global
 ---
 
@@ -15,47 +15,50 @@ metadata:
 
 ## Objetivo
 
-Integrar o framework com o repositório `central-docs` (`CENTRAL_DOCS_REPO`), permitindo:
-- Buscar docs relevantes automaticamente durante workflows
-- Publicar docs aprovados via MR com git flow seguro
-- Sincronização automática em /warm-up
+Integrar os comandos do framework com o **Central docs**: o lugar onde fica a documentação aprovada de todos os produtos do squad, com um índice (`{SQUAD}/index.md`) que os outros comandos consultam.
 
-## Fonte de Verdade
+- Buscar documentos relevantes durante os workflows (Modo 1)
+- Publicar documentos aprovados (Modo 2)
+- Reparar o índice (Modo 3)
 
-> **Antes de qualquer operação**, leia `$CENTRAL_DOCS_REPO/AGENTS.md`.
-> Ele define o contrato completo do repositório: estrutura, naming, frontmatter e regras de índice.
-> Este skill implementa esse contrato — não o duplica.
+## Adaptadores de armazenamento
+
+O Central docs não depende de um serviço: `CENTRAL_DOCS_STORAGE` escolhe o adaptador e `CENTRAL_DOCS_LOCATION` diz onde ele guarda. Os comandos são sempre os mesmos (`jarvis docs fetch | sync | publish`), venha o conteúdo de onde vier.
+
+| `CENTRAL_DOCS_STORAGE` | `CENTRAL_DOCS_LOCATION` | Situação |
+|---|---|---|
+| *(vazio)* | — | Desligado: os comandos pulam em silêncio |
+| `filesystem` | Pasta (relativa à pasta do workspace ou absoluta) | Disponível |
+| `s3`, `gdrive` | — | Ainda não suportados (o comando para com a mensagem de "não suportado") |
+
+**Camada git do `filesystem`:** se a pasta tiver `.git` (clone de um repositório de documentação), o adaptador:
+- faz `git pull --ff-only` em `CENTRAL_DOCS_REF` antes de ler (se falhar, avisa e lê a cópia local);
+- ao publicar: branch `docs/{caminho}` → cópia → índice → commit → push → Pull/Merge Request para `CENTRAL_DOCS_TARGET_BRANCH`, com `CENTRAL_DOCS_REVIEWERS` na descrição.
+
+Sem `.git`, grava direto na pasta.
+
+**Onde fica a pasta** (o `/jarvis-init` sugere): no modo workspace, `./central-docs` (no `.gitignore` do workspace); no projeto único, `docs/jarvis/central-docs` (com `docs/jarvis/*` no `.gitignore`). Nunca no versionamento de um repositório de código.
 
 ## Pré-condição
 
 Ler do `$IDE/ENV.md`:
-- `CENTRAL_DOCS_REPO` — URL do repo (GitLab, GitHub ou Bitbucket; se vazio: encerrar silenciosamente)
-- `CENTRAL_DOCS_REF` — branch para leitura (padrão: `main`)
-- `VERSION_CONTROL` — fallback se o hostname da URL não identificar o vendor
-- `SQUAD` — squad do usuário (formato: ALL-CAPS-COM-HIFEN)
-- `WORKSPACE` — nome do workspace em kebab-case
-- `AREA` — define quais tipos de doc buscar
-
-**Token VCS** (resolvido pelo adapter `bin/lib/utils/npmrc-parser.js` → `getVcsToken`):
-- GitLab: `.npmrc` `:_authToken=` ou `GITLAB_TOKEN`
-- GitHub: `gh auth token`, `GITHUB_TOKEN` ou `.npmrc` npm.pkg.github.com
-- Bitbucket: `BITBUCKET_TOKEN`
+- `CENTRAL_DOCS_STORAGE` e `CENTRAL_DOCS_LOCATION` (vazio: encerrar em silêncio)
+- `CENTRAL_DOCS_REF`, `CENTRAL_DOCS_TARGET_BRANCH`, `CENTRAL_DOCS_REVIEWERS` (só com `.git`)
+- `SQUAD` (ALL-CAPS-COM-HIFEN), `WORKSPACE` (vira a pasta do produto) e `AREA` (que tipos buscar)
 
-❌ **NUNCA** colar o token no chat.
+`ENV.md` da versão anterior (com a variável do repositório remoto e sem `CENTRAL_DOCS_STORAGE`): os comandos pedem o Upgrade do `/jarvis-init`, que faz a migração.
 
-Se `CENTRAL_DOCS_REPO` não estiver definido, encerrar silenciosamente sem erro.
+Com `.git`, o PR usa o token do vendor pelo adaptador de VCS (GitLab `.npmrc`; GitHub `gh auth`/`GITHUB_TOKEN`; Bitbucket `BITBUCKET_TOKEN`). ❌ **Nunca** colar token no chat.
 
 ---
 
-## Convenções do central-docs (resumo operacional)
-
-### Estrutura de pastas
+## Estrutura do Central docs
 
 ```
 {SQUAD}/
-├── index.md                          # GERADO — não editar à mão
+├── index.md                          # GERADO a cada publicação — não editar à mão
 ├── product/
-│   └── {produto-em-kebab}/
+│   └── {produto}/                    # WORKSPACE do ENV.md (ou --produto)
 │       ├── prd-{id}-{nome}.md
 │       ├── frd-{id}-{nome}.md
 │       ├── feat-{id}-{nome}.md
@@ -63,226 +66,118 @@ Se `CENTRAL_DOCS_REPO` não estiver definido, encerrar silenciosamente sem erro.
 │       ├── story-{id}-{nome}.md
 │       └── task-{id}-{nome}.md
 ├── engineering/
-│   └── {produto-em-kebab}/
+│   └── {produto}/
 │       ├── ard-{id}-{nome}.md
-│       └── rfc-{id}-{nome}.md
-└── context/                          # opcional — só nasce com conteúdo
-    ├── CLAUDE.md
-    └── (pesquisas, dados, assets — formato livre)
+│       ├── rfc-{id}-{nome}.md
+│       ├── swagger-{nome}.{md|yaml|json}
+│       └── qa-report-{nome}.md
+└── context/                          # opcional — formato livre
 ```
 
-**Squads válidos** (pastas raiz ALL-CAPS): detectados dinamicamente pelo script.
-Fonte de verdade: `taxonomy.md` na raiz do repo.
+- **Nome do arquivo:** o do arquivo local, que já segue `{tipo}-{id}-{nome}.md` (`prod-rules.md`). Só quando o nome foge do padrão, `--feature {slug}` gera `{tipo}-{slug}.{ext}`.
+- **`{produto}`:** `WORKSPACE` (a pasta que contém o `$IDE/`), ou `--produto`.
 
-### Naming de arquivos
+### Frontmatter obrigatório (validado no `publish`)
 
-```
-{tipo}-{id}-{nome-em-kebab}.md
-```
+| Tipo | Campos |
+|------|--------|
+| `prd` | `id`, `name`, `version`, `status` |
+| `frd`, `feat`, `epic` | `id`, `name`, `version`, `status`, `related_prd` |
+| `story` | `id`, `name`, `status`, `related_prd` |
+| `task` | `id`, `name`, `status` |
+| `ard` | `id`, `name`, `version`, `status` |
+| `rfc` | `Status`, `Criado em`, `Proponente` |
+| `qa-report` | `period`, `squad`, `version` |
 
-Exemplos: `prd-001-minha-feature.md`, `ard-001-minha-api.md`, `story-TASK-4-meu-exemplo.md`
+**Status reconhecidos:**
+- produto: `icebox`, `in_review`, `backlog`, `in_progress`, `in_production`, `cancelled`, `deprecated`;
+- ARD: `proposed`, `in_progress`, `in_review`, `approved`;
+- RFC: `Draft`, `In Review`, `Ready for Decision`, `Accepted`, `Rejected`, `Superseded`.
 
-- Tipo sempre **lowercase**: `prd-`, `frd-`, `feat-`, `epic-`, `story-`, `task-`, `ard-`, `rfc-` , `swagger-`
-- Pasta de produto: `kebab-case`, um produto = uma pasta
+Status fora da lista só gera aviso.
 
-### Frontmatter obrigatório
+**Campos `related_*`:** só o **basename** do arquivo (sem path nem `./`).
 
-| Campo | PRD | FRD/FEAT/STORY | EPIC | TASK | ARD/RFC |
-|-------|-----|----------------|------|------|---------|
-| `id` | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `name` | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `version` | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `status` | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `created` / `updated` | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `created_by` / `last_editor` | ✓ | ✓ | ✓ | ✓ | ✓ |
-| `related_prd` | – | ✓ | ✓ | – | – |
-| `related_epic` | – | – | – | ✓ | – |
+### Índice
 
-**Status válidos:** `draft`, `in_review`, `planejado`, `in_progress`, `in_production`, `icebox`, `deprecated`
+O `{SQUAD}/index.md` é **regenerado** a partir do frontmatter de todos os documentos a cada publicação (nunca editado, para duas publicações não apagarem a entrada uma da outra). Com `.git` e um `scripts/build-index.sh` no repositório de documentação, o adaptador usa o script dele (o CI do repositório confere o índice com ele).
 
-**Campos `related_*`:** sempre apenas o **basename** do arquivo, sem path nem `./`.
-```yaml
-# ✅ Certo
-related_prd: prd-001-minha-feature.md
+```markdown
+# CORE
 
-# ❌ Errado
-related_prd: ./prd-001-minha-feature.md
-related_prd: ../minha-feature/prd-001-minha-feature.md
-```
+## product
 
-### Índices — regra crítica
+### loja
+- [prd-001-checkout.md](product/loja/prd-001-checkout.md) | v1.0.0 | backlog | Checkout
 
-O arquivo `{SQUAD}/index.md` é **gerado pelo script** `scripts/build-index.sh`. **Nunca editar à mão.**
+## engineering
 
-```bash
-# Sempre rodar após qualquer add/move/remove de spec
-bash scripts/build-index.sh
+### loja
+- [ard-001-pagamentos.md](engineering/loja/ard-001-pagamentos.md) | v1.0.0 | approved | Pagamentos
 ```
 
-O script detecta squads dinamicamente (pastas raiz ALL-CAPS) e gera um único `index.md` por squad lendo o frontmatter de todos os specs em `product/` e `engineering/`, e listando o conteúdo de `context/`.
-
-O CI (`.gitlab-ci.yml`) **falha** se o `index.md` commitado divergir do que o script geraria.
-
 ---
 
 ## Quando Usar
 
-- `/warm-up` — carregar contexto do produto (Modo 1; aciona Modo 3 se índice ausente)
-- `/eng.start` — buscar PRD/ARD antes de iniciar feature (Modo 1)
-- `/eng.create-ard` — buscar PRD relacionado (Modo 1)
-- `/eng.pre-pr` — detectar docs desatualizados (Modo 1)
-- Publicação de doc aprovado (Modo 2)
-- Reparo de índices inconsistentes ou ausentes (Modo 3)
+- `/warm-up`: carregar o contexto do produto (Modo 1)
+- `/eng.start`, `/eng.create-ard`, `/eng.create-rfc`, `/eng.build-tech-spec`: buscar PRD/ARD/RFC relacionados (Modo 1)
+- `/prod.spec.*`: buscar specs existentes e publicar a aprovada (Modos 1 e 2)
+- `/eng.pre-pr`: detectar ARD novo ou desatualizado e oferecer a publicação (Modo 2)
+- Índice ausente ou divergente (Modo 3)
 
 ---
 
 ## Fluxo de Trabalho
 
-### Modo 1: Buscar Docs (usado em warm-up, eng.start)
-
-**Passo 1 — Buscar índice do squad**
-
-```bash
-jarvis docs sync
-
-# Internamente chama fetchFile() de bin/lib/docs/fetch-file.js, equivalente a:
-jarvis docs fetch "${SQUAD}/index.md" "${CENTRAL_DOCS_REF}"
-```
-
-**Passo 1.b — Fallback: navegar árvore (quando index.md não existe)**
-
-Se `jarvis docs sync` retornar exit code 2 (arquivo não encontrado):
-
-```bash
-# Fallback: clonar o CENTRAL_DOCS_REPO e listar arquivos locais
-# (funciona igual em GitLab, GitHub e Bitbucket)
-git ls-tree -r --name-only "${CENTRAL_DOCS_REF}" -- "${SQUAD}/product/${WORKSPACE}" "${SQUAD}/engineering/${WORKSPACE}"
-```
-
-**Identificar docs por caminho (naming padrão):**
-- `engineering/{produto}/ard-*.md` → ARD
-- `engineering/{produto}/rfc-*.md` → RFC
-- `product/{produto}/prd-*.md` → PRD
-- `product/{produto}/frd-*.md` → FRD
-- `product/{produto}/feat-*.md` → FEAT
-- `product/{produto}/story-*.md` → STORY
-- `context/` → artefatos de contexto (pesquisas, dados, assets)
-
-**Passo 2 — Identificar docs relevantes**
-
-Com base no contexto da tarefa (`TASK_MANAGER_KEY`, tags, descrição):
-- Buscar no `index.md` por `TASK_MANAGER_KEY` matching
-- Se não encontrar, buscar por tags semânticas
-- Filtrar por AREA:
-  - `PRODUCT` → PRDs e FRDs
-  - `ENGINEERING` → PRD (contexto) + ARDs + RFCs
-
-**Passo 3 — Buscar arquivos identificados**
+### Modo 1: Buscar docs
 
 ```bash
-jarvis docs fetch "${SQUAD}/product/${WORKSPACE}/prd-feature.md" "main"
-jarvis docs fetch "${SQUAD}/engineering/${WORKSPACE}/ard-feature.md" "main"
+jarvis docs sync                         # lê {SQUAD}/index.md e resume o que há
+jarvis docs fetch {SQUAD}/index.md       # conteúdo do índice
+jarvis docs fetch {SQUAD}/product/{produto}/prd-001-checkout.md
 ```
 
-**Passo 4 — Retornar resultado**
+- Com `.git`, o primeiro acesso faz `pull`.
+- `docs fetch` sai com código **2** quando o arquivo não existe.
 
-```markdown
-# Contexto Carregado do Central Docs
+1. Buscar o índice do squad.
+2. Identificar os documentos pelo `TASK_MANAGER_KEY`, pelo nome ou pelo produto; filtrar por `AREA`:
+   - `PRODUCT` → PRD, FRD, épicos e histórias;
+   - `ENGINEERING` → PRD (contexto), ARD e RFC.
+3. Buscar cada arquivo com `jarvis docs fetch`.
+4. Devolver o conteúdo carregado, com um resumo (squad, produto, documentos e versões).
 
-## Squad: MEU-SQUAD / Produto: meu-produto
-
-### PRD-001: Minha Feature (v1.2.0)
-[conteúdo do PRD]
-
-### ARD-001: Arquitetura da Minha Feature (v1.5)
-[conteúdo do ARD]
-```
-
----
-
-### Modo 2: Publicar Doc
-
-**Uso:**
+### Modo 2: Publicar doc
 
 ```bash
-jarvis docs publish \
-  --file ./docs/engineering/ard-001-minha-feature.md \
-  --squad MEU-SQUAD \
-  --produto meu-produto \
-  --tipo ard
+jarvis docs publish --file ./docs/product/prd-001-checkout.md --tipo prd
+jarvis docs publish --file ./docs/engineering/ARD/ard-001-pagamentos.md --tipo ard --produto loja
+jarvis docs publish --file ./openapi.yaml --tipo swagger --feature api-wallet
 ```
 
-**Fluxo interno:**
-
-1. Validar frontmatter YAML (campos obrigatórios conforme tabela acima)
-2. Validar naming do arquivo (`{tipo}-{id}-{nome-em-kebab}.md`)
-3. Validar que `related_*` usam apenas basename
-4. Determinar destino: `{SQUAD}/engineering/{produto}/` ou `{SQUAD}/product/{produto}/`
-5. Criar branch `docs/{SQUAD}/{area}/{produto}/{tipo}-{id}-{nome}`
-6. Commit via API do vendor (GitLab / GitHub / Bitbucket) com o doc
-7. Rodar `bash scripts/build-index.sh` localmente no clone e incluir o `{SQUAD}/index.md` atualizado no mesmo commit atômico
-8. Criar MR → main
-9. Retornar URL do MR
-
-**Commit atômico (doc + index):**
-
-```
-actions:
-  - { action: "create_or_update", file_path: "{SQUAD}/engineering/{produto}/ard-001-feature.md", content: "..." }
-  - { action: "create_or_update", file_path: "{SQUAD}/index.md", content: "..." }
-```
-
-> Usar `POST /repository/commits` com array `actions`.
-> O `index.md` é o output de `build-index.sh` — nunca construído manualmente.
-
-**Output:**
-
-```
-✅ MR criado: docs/MEU-SQUAD/engineering/meu-produto/ard-001-minha-feature → main
-URL: {url do MR/PR retornada pelo adapter}
-```
-
----
-
-### Modo 3: Reparar Índices
-
-> Detecta `{SQUAD}/index.md` ausente ou divergente e abre MR de reparo.
-
-**Quando ativar:**
-
-- Durante Modo 1, se o fallback de árvore encontrar docs que não aparecem no `index.md`
-- Durante warm-up, se `index.md` não existir
-- Quando o usuário pedir explicitamente
+Tipos: `prd, frd, feat, epic, story, task` (em `product/`) e `ard, rfc, swagger, qa-report` (em `engineering/`).
 
 **Fluxo:**
-
-```
-1. Clonar ou usar clone local de central-docs
-2. Rodar: bash scripts/build-index.sh
-3. Comparar output com os index.md commitados (git diff)
-4. Se há divergência:
-   a. Criar branch: repair/index-{SQUAD}-{timestamp}
-   b. Commitar os index.md atualizados
-   c. Abrir MR → main
-5. Reportar ao usuário
-```
-
-> O `build-index.sh` detecta squads dinamicamente — não é necessário listar squads manualmente.
-
-**Output ao usuário:**
-
-```
-🔍 Verificando índices do central-docs (MEU-SQUAD)...
-
-⚠️  MEU-SQUAD/index.md divergente — 3 docs ausentes no índice
-
-📋 Abrindo MR de reparo...
-   Branch: repair/index-MEU-SQUAD-20260510
-   Arquivo: MEU-SQUAD/index.md
-
-✅ MR aberto:
-   URL: {CENTRAL_DOCS_REPO}/-/merge_requests/44
-```
+1. Validar o frontmatter (tabela acima).
+2. Calcular o destino `{SQUAD}/{área}/{produto}/{nome}`.
+3. Sem `.git`: copiar o arquivo e regenerar `{SQUAD}/index.md`.
+4. Com `.git`:
+   1. `checkout` + `pull` de `CENTRAL_DOCS_TARGET_BRANCH`;
+   2. branch `docs/{SQUAD}/{área}/{produto}/{nome}`;
+   3. cópia + índice;
+   4. commit e push;
+   5. PR para `CENTRAL_DOCS_TARGET_BRANCH`;
+   6. voltar para a branch base.
+5. Mostrar o destino, o índice e a URL do PR (com `.git`).
+
+Antes de publicar, **confirmar com o usuário**. Sem `.git` não há PR: a confirmação é a única revisão.
+
+### Modo 3: Reparar o índice
+
+Quando o índice não existe ou não lista todos os documentos:
+- **Sem `.git`:** publicar de novo qualquer documento do squad regenera o índice. Na prática, o próximo `jarvis docs publish` já corrige.
+- **Com `.git`:** no clone, rodar `bash scripts/build-index.sh` (se existir) e abrir um PR `repair/index-{SQUAD}-{data}` com o índice atualizado.
 
 ### Skills invocados durante a execução do skill
 
@@ -296,97 +191,32 @@ URL: {url do MR/PR retornada pelo adapter}
 
 ### Nunca
 
-- Publicar doc sem validar frontmatter
-- Push direto para main (sempre via MR)
-- Buscar docs se `CENTRAL_DOCS_REPO` vazio (encerrar silenciosamente)
-- Inventar metadados (version, status, id)
-- Editar `{SQUAD}/index.md` manualmente — sempre via `build-index.sh`
-- Usar path em campos `related_*` — sempre basename apenas
-- Usar squad em minúsculas (ex: `core`) — sempre ALL-CAPS-COM-HIFEN: `MEU-SQUAD`
-- Criar subpastas `engineering/index.md` ou `product/index.md` (não existem neste repo)
+- Publicar documento sem validar o frontmatter
+- Editar `{SQUAD}/index.md` à mão
+- Push direto para a branch base quando a pasta tem `.git` (sempre por PR)
+- Buscar docs com `CENTRAL_DOCS_STORAGE` vazio (encerrar em silêncio)
+- Inventar metadados (`version`, `status`, `id`)
+- Usar path em campos `related_*`
+- Colocar o Central docs no versionamento de um repositório de código
 
 ### Sempre
 
-- Ler `$CENTRAL_DOCS_REPO/AGENTS.md` antes de operar
-- Usar GitLab API (não `git archive` ou `git clone` desnecessário)
-- Invalidar cache local (`redis-cli`) ao publicar, se o comando existir
-- Seguir git flow (branch → MR → main)
-- Extrair token do `.npmrc` automaticamente
-- Validar naming do arquivo antes de publicar
-- Incluir `{SQUAD}/index.md` (gerado por `build-index.sh`) em todo commit de publicação
+- Ler e publicar só pelo CLI (`jarvis docs fetch | sync | publish`), nunca lendo a pasta por fora do adaptador
+- Se o Central docs tiver `AGENTS.md` na raiz, lê-lo antes de operar
+- Confirmar com o usuário antes de publicar
+- Usar `SQUAD` em ALL-CAPS-COM-HIFEN
 
 ---
 
 ## Troubleshooting
 
-### Erro: Token VCS não encontrado
-
-GitLab: `.npmrc` `:_authToken=` ou `GITLAB_TOKEN`.
-GitHub: `gh auth login` ou `GITHUB_TOKEN`.
-Bitbucket: `BITBUCKET_TOKEN`.
-
-### Erro: index.md não encontrado (Modo 1)
-
-```
-❌ Arquivo não encontrado: MEU-SQUAD/index.md
-```
-
-**Causa:** Squad ainda sem docs publicados. Índice só existe após o primeiro `publish`.
-
-**Solução:** Publicar ao menos um doc via `jarvis docs publish`. O MR já incluirá o `index.md`.
-
-### Erro: Frontmatter inválido
-
-```
-❌ Campos obrigatórios ausentes: name, version, created_by
-```
-
-**Solução:** Adicionar campos conforme tabela de frontmatter obrigatório acima.
-
-### Erro: Naming inválido
-
-```
-❌ Nome do arquivo não segue o padrão: {tipo}-{id}-{nome-em-kebab}.md
-   Recebido: ARD-001-MinhaFeature.md
-   Esperado: ard-001-minha-feature.md
-```
-
-**Solução:** Renomear o arquivo seguindo o padrão lowercase com hífens.
-
-### CI falha com "Índices stale"
-
-```
-❌ Índices stale. Rode 'bash scripts/build-index.sh' localmente,
-   commita o resultado e empurre de novo.
-```
-
-**Solução:** O `{SQUAD}/index.md` no commit diverge do que o script geraria. Sempre incluir o output de `build-index.sh` no mesmo commit do doc.
-
----
-
-## Integração com Workflows
-
-### /warm-up
-
-```markdown
-Se CENTRAL_DOCS_REPO configurado:
-1. jarvis docs sync
-2. Exibir resumo de docs disponíveis do squad/produto
-```
-
-### /eng.start
-
-```markdown
-Se CENTRAL_DOCS_REPO definido:
-- Buscar docs relacionados ao `TASK_MANAGER_KEY` no index.md do squad
-- Carregar PRD + ARDs relevantes antes de criar architecture.md
-```
-
-### /eng.pre-pr
-
-```markdown
-1. Detectar mudanças arquiteturais no diff
-2. Verificar se ARD local existe e está atualizado vs central-docs
-3. Se desatualizado ou novo: perguntar "Publicar no central-docs?"
-4. Se sim: jarvis docs publish
-```
+| Mensagem | Causa | O que fazer |
+|---|---|---|
+| `Central docs desligado (CENTRAL_DOCS_STORAGE vazio)` | Não configurado | `/jarvis-init` → Central docs |
+| `… não é mais usado. Rode o /jarvis-init e escolha Upgrade (C)` | `ENV.md` da versão anterior | `/jarvis-init` → Upgrade (C) |
+| `Armazenamento "s3" ainda não suportado` | Valor de `STORAGE` sem adaptador | Use `filesystem` |
+| `Pasta do Central docs não encontrada` | `LOCATION` errado ou pasta não criada | Criar a pasta ou ajustar `LOCATION` |
+| `Arquivo não encontrado no Central docs: {SQUAD}/index.md` | Squad sem publicação ainda | Publicar o primeiro documento |
+| `Campos obrigatórios ausentes` | Frontmatter incompleto | Completar conforme a tabela |
+| `O arquivo "…" não segue o padrão` | Nome fora de `{tipo}-{id}-{nome}` | Renomear ou usar `--feature` |
+| `git pull`/`push` falhou (com `.git`) | Rede, permissão ou pasta suja | `git status` na pasta; o commit local fica para repetir |

package/skills/jarvis-init/SKILL.md

@@ -195,12 +195,12 @@ Identificar qual IDE o usuário está utilizando:
 3. Ler `HUB` do ENV.md existente
 4. Se `HUB≠DATA`: excluir do diff todas as chaves `DATA_*` — não propor adicioná-las
 5. Calcular diff: chaves no template que **não existem** no ENV.md atual (respeitando exclusão de DATA_* para não-DATA)
-4. Se não houver diff:
+6. Se não houver diff:
    ```
    ✅ ENV.md já está atualizado. Nenhuma variável nova encontrada.
    ```
    Oferecer o **passo 9 (adicionar as stacks)**, que a pessoa pode pular, e então encerrar.
-5. Se houver diff, exibir prévia:
+7. Se houver diff, exibir prévia:
    ```
    🔍 Variáveis novas encontradas no template:
      + NOVA_VAR_1=
@@ -208,18 +208,20 @@ Identificar qual IDE o usuário está utilizando:
 
    Serão adicionadas ao final do ENV.md sem alterar os valores existentes.
    ```
-6. Appender as novas variáveis ao final do `ENV.md` com comentário de data:
+8. **Exceção — Central docs antigo:** se o `ENV.md` tiver `CENTRAL_DOCS_REPO` preenchido e não tiver `CENTRAL_DOCS_STORAGE`, propor a migração (só com confirmação): `CENTRAL_DOCS_STORAGE=filesystem`, `CENTRAL_DOCS_LOCATION` com o padrão do modo de trabalho (Passo 4, "Central docs") e `git clone {CENTRAL_DOCS_REPO} {LOCATION}`. Depois, comentar a linha antiga (`# CENTRAL_DOCS_REPO=… (migrado em YYYY-MM-DD)`) e `CENTRAL_DOCS_CACHE_TTL`. Sem confirmação, não mexe e avisa que os comandos de docs vão pedir o Upgrade.
+9. **Exceção — `PROD_MODE`:** se `PROD_MODE` estiver entre as chaves novas, faça a mesma pergunta do Passo 3 (Pergunta 8 — modo de condução) e grave a resposta no lugar do valor vazio. As demais chaves continuam sem pergunta.
+10. Appender as novas variáveis ao final do `ENV.md` com comentário de data:
    ```
    # --- Upgrade YYYY-MM-DD ---
    NOVA_VAR_1=
    NOVA_VAR_2=valor-padrão
    ```
-7. Confirmar:
+11. Confirmar:
    ```
    ✅ ENV.md atualizado! N variável(is) nova(s) adicionada(s).
    ⚠️ Preencha os valores em branco antes de usar os novos recursos.
    ```
-8. 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).
+12. 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).
 
 **⚠️ OBRIGATÓRIO - Criação do ENV.md**:
 
@@ -261,6 +263,7 @@ Fluxo correto:
 - **IDE** (7 opções) → mostrar em texto numerado
 - **SQUAD** (do taxonomy) → mostrar em texto numerado
 - **POSITION** (do taxonomy) → mostrar em texto numerado
+- **PROD_MODE** (2 opções: product-led, developer-guided) → AskUserQuestion, sempre perguntado e sem opção sugerida
 
 ```
 // Exemplo 1: HUB (5 opções) - MOSTRAR EM TEXTO
@@ -401,6 +404,15 @@ Pergunta 7 (opções fixas - POSITION do taxonomy - texto se >4):
 
 *[Mostrar TODAS as opções de POSITION do taxonomy.md e aguardar]*
 
+```
+Pergunta 8 (opções fixas - 2 opções - usar AskUserQuestion) — PROD_MODE:
+Como você quer que os comandos de produto (prod.*) e o eng.create-ard conduzam a conversa?
+- Product-Led: para PMs. Fluxo direto, com os termos de PM, sem explicações extras.
+- Developer-Guided: para devs e futuros PMs. Uma pergunta por vez, explicando cada termo e etapa enquanto você faz.
+```
+
+*[Perguntar **sempre**, para qualquer `AREA` e qualquer `POSITION` (inclusive `GENERALIST` e PM). **Não** marcar nenhuma opção como recomendada nem sugerir padrão por área ou cargo. Gravar `PROD_MODE=product-led` ou `PROD_MODE=developer-guided`.]*
+
 **Regras de Implementação:**
 - **Opções fixas com ≤4 opções** → usar AskUserQuestion
 - **Opções fixas com >4 opções** (HUB com DATA, IDE, SQUAD, POSITION) → mostrar em texto numerado
@@ -424,6 +436,7 @@ Pergunta 7 (opções fixas - POSITION do taxonomy - texto se >4):
 | `MAX_AI_EXECUTION_PERCENTAGE` | Limite de execução da AI | Número entre 60 e 100 |
 | `USER` | Identidade do usuário (email ou nome) | ENV.md → git `user.email` → usuário do SO. Sem login |
 | `POSITION` | Cargo do usuário | Deve estar em `taxonomy.md` → Positions. Autonomia ponta a ponta em qualquer cargo |
+| `PROD_MODE` | Modo de condução dos comandos de produto e do `eng.create-ard` | `product-led` ou `developer-guided`. Sempre perguntado, sem opção sugerida (Pergunta 8) |
 
 > **💡 Nota**:
 > - As opções para SQUAD, HUB, AREA e POSITION são definidas em `taxonomy.md` e podem ser customizadas por organização.
@@ -560,6 +573,20 @@ Token NÃO vai no ENV.md:
 Nunca grave TOKEN_VERSION_CONTROL (chave removida do template).
 ```
 
+**Central docs (onde fica a documentação aprovada — PRD, FRD, épicos, ARD, RFC):**
+```
+Onde fica a documentação central?
+A. Pasta local
+B. Repositório de documentação (git)
+C. Não usar → CENTRAL_DOCS_STORAGE= vazio
+```
+- **A ou B** → `CENTRAL_DOCS_STORAGE=filesystem` e `CENTRAL_DOCS_LOCATION` com o padrão do **modo de trabalho** (a pessoa pode digitar outro caminho):
+  - **modo workspace** (2+ subpastas com `.git`): `./central-docs`, e `central-docs/` no `.gitignore` do workspace;
+  - **projeto único** (só a raiz tem `.git`): `docs/jarvis/central-docs` (já coberto por `docs/jarvis/*` no `.gitignore`, ver Passo 5).
+- **A**: `mkdir -p {LOCATION}` e criar `{LOCATION}/AGENTS.md` mínimo explicando a estrutura `{SQUAD}/{product|engineering}/{produto}/` e que o `{SQUAD}/index.md` é gerado pelo `jarvis docs publish`.
+- **B**: pedir a URL do repositório e rodar `git clone {URL} {LOCATION}`. Se `{LOCATION}` já existir com `.git`, só usar. Perguntar `CENTRAL_DOCS_TARGET_BRANCH` (padrão `main`).
+- Nunca colocar o Central docs no versionamento de um repositório de código.
+
 #### Variáveis Opcionais (alinhar ao `templates/ENV-template.md`)
 
 | Variável | Valor Padrão | Descrição |
@@ -585,7 +612,8 @@ Nunca grave TOKEN_VERSION_CONTROL (chave removida do template).
 | `TEST_FOLDER` | *(vazio)* | Pasta de testes |
 | `QA_SIGNOFF_BRANCHES` / `QA_SIGNOFF_MAX_AGE` | `main,release/*` / `24` | Sign-off QA |
 | `JARVIS_PROJECT` | `https://github.com/phelipperibeiro/jarvis-framework` | Repo do framework (`/jarvis-report-issue`) |
-| `CENTRAL_DOCS_REPO` / `_REF` / `_TARGET_BRANCH` / `_REVIEWERS` / `_CACHE_TTL` | *(opcional)* | Docs centrais |
+| `CENTRAL_DOCS_STORAGE` / `_LOCATION` | *(vazio = desligado)* | Central docs: `filesystem` + pasta (padrão por modo de trabalho) |
+| `CENTRAL_DOCS_REF` / `_TARGET_BRANCH` / `_REVIEWERS` | `main` / `main` / *(vazio)* | Só quando a pasta do Central docs tem `.git` |
 | `SESSIONS_DIR` | `.jarvis/sessions` | Não perguntar — gravar fixo |
 | `RTK_ENABLED` | `false` (ou true se detectar `rtk`) | Token Killer |
 | `ADVISOR_MODELS` | `"Sonnet 5.5,Opus 5.5,Opus 5,Fable 5.1"` | Advisor do `eng.start` — não perguntar, gravar o padrão |
@@ -649,6 +677,13 @@ cat templates/ENV-template.md
 mkdir -p .jarvis/sessions/eng .jarvis/sessions/prod .jarvis/sessions/qa
 # Garantir .jarvis/ no .gitignore do workspace
 grep -qxF '.jarvis/' .gitignore 2>/dev/null || echo '.jarvis/' >> .gitignore
+
+# 8. Modo de trabalho (detectado no Passo 3, Pergunta 1):
+#    - Projeto único (só a raiz tem .git): PROD_DOCS=docs/jarvis/product e
+#      docs/jarvis/ fora do versionamento (uma docs/ já existente não é tocada):
+grep -qxF 'docs/jarvis/*' .gitignore 2>/dev/null || echo 'docs/jarvis/*' >> .gitignore
+#    - Modo workspace: PROD_DOCS=$DOCS_FOLDER/$PROD_FOLDER_NAME (padrão do template) e, se o
+#      Central docs ficar dentro do workspace: grep -qxF 'central-docs/' .gitignore || echo 'central-docs/' >> .gitignore
 ```
 
 **⚠️ REGRA CRÍTICA — Bloco DATA:**
@@ -1234,7 +1269,10 @@ Pergunta 6: Qual o limite de execução da AI? (60-100)
 Pergunta 7: Qual seu cargo?
 [mostrar opções em texto numerado]
 
-Pergunta 8 (opcional): Usa task manager? jira/linear/github/asana ou Nenhum (freelance)
+Pergunta 8: Modo dos comandos de produto?
+[AskUserQuestion: Product-Led | Developer-Guided, sem opção sugerida]
+
+Pergunta 9 (opcional): Usa task manager? jira/linear/github/asana ou Nenhum (freelance)
 ```
 
 **Agente**: *(cria ENV.md + `.jarvis/sessions/{eng,prod,qa}`, valida Context7, cria AGENTS.md e confirma)*
@@ -1281,6 +1319,7 @@ Bem-vindo! 🎉
 - [ ] **Perguntou UMA variável POR VEZ** (nunca fez múltiplas perguntas juntas)
 - [ ] **Usou AskUserQuestion só para ≤4 opções** (AREA se aplicável — HUB com DATA vai em texto)
 - [ ] **Mostrou em texto numerado para >4 opções** (HUB, IDE, SQUAD, POSITION)
+- [ ] **Perguntou o `PROD_MODE`** (Product-Led ou Developer-Guided), sem opção sugerida, qualquer que seja a área ou o cargo
 - [ ] **Mostrou TODAS as opções disponíveis** (HUB inclui DATA; nunca omitiu)
 - [ ] **Incluiu descrição útil em cada opção** (seja AskUserQuestion ou texto)
 - [ ] **Validou respostas em texto contra lista de opções válidas**