jarvis-ai-framework 3.2.0 → 4.0.0

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

@@ -1,313 +1,101 @@
 # jarvis-docs-central
 
-Integração com repositório centralizado de documentação canônica (PRDs, FRDs, ARDs, RFCs) — GitLab, GitHub ou Bitbucket.
+Integração com o **Central docs**: a documentação aprovada (PRD, FRD, épicos, histórias, ARD, RFC) de todos os produtos do squad, com um índice que os outros comandos consultam.
 
 ## Visão Geral
 
-Esta skill permite:
-- **Buscar** documentação do central-docs via API do vendor (GitLab / GitHub / Bitbucket)
-- **Publicar** documentos aprovados via MR/PR (git flow seguro)
-- **Sincronizar** automaticamente em /warm-up
+- **Buscar** documentos (`jarvis docs sync`, `jarvis docs fetch`)
+- **Publicar** documentos aprovados (`jarvis docs publish`)
+- **Índice** regenerado a cada publicação (`{SQUAD}/index.md`)
 
-## Pré-requisitos
+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.
 
-1. **Token VCS** (GitLab `.npmrc`, GitHub `gh auth` / `GITHUB_TOKEN`, Bitbucket `BITBUCKET_TOKEN`)
-2. **ENV.md** com variáveis do central-docs
+## Configuração
 
-> ℹ️ Cache local via `redis-cli` é opcional. Sem Redis, a busca vai direto na API.
-
-> ⚠️ Token **nunca** vai no chat. GitLab: `.npmrc`. GitHub: `gh auth` ou `GITHUB_TOKEN`. Bitbucket: `BITBUCKET_TOKEN`.
-
-### Configuração Mínima
+Pelo `/jarvis-init` (pergunta "Onde fica a documentação central?": pasta local, repositório git ou não usar), ou à mão no `ENV.md`:
 
 ```ini
-# .windsurf/ENV.md
-CENTRAL_DOCS_REPO=https://gitlab.com/org/group/central-docs.git
+CENTRAL_DOCS_STORAGE=filesystem
+CENTRAL_DOCS_LOCATION=./central-docs     # relativo à pasta do workspace, ou absoluto
+# Só se a pasta tiver .git:
 CENTRAL_DOCS_REF=main
-CENTRAL_DOCS_TARGET_BRANCH=dev
-SQUAD=core
-WORKSPACE=meu-workspace
-```
-
-```ini
-# .npmrc (projeto ou ~/.npmrc)
-//gitlab.com/api/v4/packages/npm/:_authToken=glpat-seu-token-aqui
+CENTRAL_DOCS_TARGET_BRANCH=main
+CENTRAL_DOCS_REVIEWERS=
+SQUAD=CORE
+WORKSPACE=loja                           # vira a pasta do produto
 ```
 
-## Comandos Disponíveis
+| Modo de trabalho | Pasta padrão | Fora do versionamento por |
+|---|---|---|
+| Workspace (vários repositórios) | `./central-docs` | `central-docs/` no `.gitignore` do workspace |
+| Projeto único | `docs/jarvis/central-docs` | `docs/jarvis/*` no `.gitignore` do projeto |
 
-### Sincronizar Docs
+> Com `.git`, o PR usa o token do vendor (GitLab `.npmrc`, GitHub `gh auth`/`GITHUB_TOKEN`, Bitbucket `BITBUCKET_TOKEN`). O token **nunca** vai no chat nem no `ENV.md`.
 
-```bash
-# Sincronizar docs do squad
-jarvis docs sync
-
-# Modo silencioso (sem output)
-jarvis docs sync --silent
+**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.
 
-# Modo verbose (mostra conteúdo)
-jarvis docs sync --verbose
-```
-
-### Publicar Documento
+## Comandos
 
 ```bash
-# Publicar ARD
-jarvis docs publish \
-  --file ./docs/engineering/ard-api-wallet.md \
-  --tipo ard \
-  --feature api-wallet-auth-jwt
-
-# Publicar PRD
-jarvis docs publish \
-  --file ./docs/product/prd-gestao-carteiras.md \
-  --tipo prd \
-  --feature gestao-carteiras
-
-# Publicar Swagger/OpenAPI (YAML)
-jarvis docs publish \
-  --file ./docs/engineering/swagger/api-wallet.yaml \
-  --tipo swagger \
-  --feature wallet
-
-# Com override de squad/workspace:
-jarvis docs publish \
-  --file ./docs/engineering/ard-api-wallet.md \
-  --tipo ard \
-  --feature api-wallet-auth-jwt \
-  --squad core \
-  --workspace meu-workspace
+jarvis docs sync                                  # resumo do índice do squad
+jarvis docs fetch CORE/index.md                   # conteúdo de um arquivo (exit 2 se não existir)
+jarvis docs publish --file ./docs/product/prd-001-checkout.md --tipo prd
+jarvis docs publish --file ./ard-001-x.md --tipo ard --produto outro-produto
+jarvis docs publish --file ./openapi.yaml --tipo swagger --feature api-wallet
 ```
 
-**Tipos válidos:** `prd`, `frd`, `ard`, `rfc`, `swagger`
+- **Tipos:** `prd, frd, feat, epic, story, task` (vão para `product/`) e `ard, rfc, swagger, qa-report` (vão para `engineering/`).
+- **Nome no Central docs:** o do arquivo local, quando ele segue `{tipo}-{id}-{nome}`. Se não seguir, use `--feature {slug}`.
 
-## Estrutura do Repositório Central
+## Estrutura e índice
 
 ```
-central-docs/
-└── {squad}/
-    ├── index.md                      # Lista todos os docs do squad
-    ├── product/
-    │   └── {workspace}/
-    │       ├── prd-{feature}.md
-    │       └── frd-{feature}.md
-    └── engineering/
-        └── {workspace}/
-            ├── ard-{feature}.md
-            ├── rfc-{feature}.md
-            └── swagger-{feature}.md  (ou api-{service}.yaml / api-{service}.json)
+{SQUAD}/
+├── index.md                 # gerado; não editar
+├── product/{produto}/       # prd-, frd-, feat-, epic-, story-, task-
+├── engineering/{produto}/   # ard-, rfc-, swagger-, qa-report-
+└── context/                 # opcional
 ```
 
-**Exemplos reais:**
-
-```
-central-docs/
-└── core/
-    ├── index.md
-    ├── product/
-    │   └── gestao-de-carteiras/
-    │       ├── prd-gestao-carteiras.md
-    │       └── frd-gestao-carteiras-onboarding.md
-    └── engineering/
-        └── api-wallet/
-            ├── ard-api-wallet.md
-            └── rfc-api-wallet-idempotencia.md
-```
-
-## Formato do index.md
-
-O `index.md` fica na raiz do squad (`{squad}/index.md`) e lista todos os documentos organizados por área e produto:
-
 ```markdown
-# core
+# CORE
 
 ## product
 
-### gestao-de-carteiras
-- [prd-gestao-carteiras.md](product/gestao-de-carteiras/prd-gestao-carteiras.md) | v1.2.0 | in_progress | jira: WAL-001 | tags: carteiras,onboarding
-- [frd-gestao-carteiras-onboarding.md](product/gestao-de-carteiras/frd-gestao-carteiras-onboarding.md) | v1.0.0 | in_review | jira: WAL-123 | tags: onboarding,cadastro
-
-## engineering
-
-### api-wallet
-- [ard-api-wallet.md](engineering/api-wallet/ard-api-wallet.md) | v2.1 | Finalizada | tags: arquitetura,rest,api
-- [rfc-api-wallet-idempotencia.md](engineering/api-wallet/rfc-api-wallet-idempotencia.md) | Accepted | tags: idempotencia,redis
-```
-
-## Frontmatter Obrigatório
-
-### PRD/FRD
-
-```yaml
----
-id: PRD-001
-name: Gestão de Carteiras
-version: 1.2.0
-status: in_progress
-task_link: https://jira.com/WAL-001
-related_repo: api-wallet,wallet-worker
----
+### loja
+- [prd-001-checkout.md](product/loja/prd-001-checkout.md) | v1.0.0 | backlog | Checkout
 ```
 
-### ARD/RFC
-
-```yaml
----
-Status: Proposta
-Data: 2026-03-10
-Autor: João Silva
-Versão: 1.0
----
-```
+Com `.git` e `scripts/build-index.sh` no repositório de documentação, o índice vem do script dele.
 
 ## Integração com Workflows
 
-### /warm-up
-
-Carrega contexto do produto:
-
-```markdown
-✅ Docs sincronizados do central-docs
-📊 5 documentos disponíveis:
-   - 1 PRD(s)
-   - 1 FRD(s)
-   - 2 ARD(s)
-   - 1 RFC(s)
-```
-
-### /eng.start
-
-Busca docs relacionados ao Jira ID antes de iniciar feature.
-
-### /eng.pre-pr
-
-Detecta docs desatualizados e oferece publicação.
-
-## Troubleshooting
-
-### Token não encontrado
-
-```
-❌ Token GitLab não encontrado no .npmrc
-```
-
-**Solução:** Adicionar ao `.npmrc`:
-```
-//gitlab.com/api/v4/packages/npm/:_authToken=glpat-seu-token
-```
-
-### Arquivo não encontrado
-
-```
-❌ Arquivo não encontrado no central-docs: core/index.md
-```
-
-**Solução:** Verificar se o squad existe no central-docs ou criar o `index.md` do squad.
-
-### Frontmatter inválido
-
-```
-❌ Campos obrigatórios ausentes no frontmatter de ARD:
-  - Status
-  - Data
-```
-
-**Solução:** Adicionar campos obrigatórios ao YAML.
+| Comando | Uso |
+|---|---|
+| `/warm-up` | `jarvis docs sync` (se `CENTRAL_DOCS_STORAGE` estiver configurado) |
+| `/eng.start`, `/eng.create-ard`, `/eng.create-rfc`, `/eng.build-tech-spec` | Buscar PRD, ARD e RFC relacionados |
+| `/prod.spec.*` | Buscar specs existentes e publicar a aprovada |
+| `/eng.pre-pr` | Oferecer a publicação de um ARD novo ou atualizado |
 
 ## Arquitetura
 
-### Componentes
-
 ```
 bin/
 ├── commands/
-│   ├── docs-sync.js           # CLI: jarvis docs sync
-│   └── docs-publish.js        # CLI: jarvis docs publish
-└── lib/
-    ├── utils/
-    │   ├── npmrc-parser.js    # Extrai token do .npmrc
-    │   └── git-parser.js      # Parseia URL GitLab
-    ├── vcs/
-    │   └── api.js             # fetchRawFile/createMergeRequest/commitFiles — GitLab/GitHub/Bitbucket
-    └── docs/
-        ├── validate-frontmatter.js  # Valida YAML
-        ├── redis-cache.js     # Cache best-effort via redis-cli (get/setex/del)
-        ├── fetch-file.js      # Busca via vcs/api.js — CLI: jarvis docs fetch
-        └── publish-file.js    # Publica via vcs/api.js + MR — CLI: jarvis docs publish
-```
-
-### Fluxo de Publicação
-
+│   ├── docs-sync.js           # jarvis docs sync
+│   └── docs-publish.js        # jarvis docs publish
+└── lib/docs/
+    ├── fetch-file.js          # openStorageFromEnv + fetchFile (jarvis docs fetch)
+    ├── publish-file.js        # tipos, destino e publicação
+    ├── validate-frontmatter.js
+    └── storage/
+        ├── index.js           # getStorage(env): escolhe o adaptador pelo CENTRAL_DOCS_STORAGE
+        ├── filesystem.js      # pasta + camada git (pull, branch, commit, push, PR)
+        └── build-index.js     # gera {SQUAD}/index.md a partir do frontmatter
 ```
-1. Validar frontmatter YAML
-2. Extrair metadados (version, status, jira)
-3. Criar branch: docs/{squad}/{area}/{produto}/{tipo}-{feature}
-4. Commit via GitLab API:
-   - Adicionar arquivo em {squad}/{area}/{produto}/{tipo}-{feature}.md
-   - Atualizar {squad}/index.md
-5. Criar MR → dev
-6. Retornar URL do MR
-```
-
-## Variáveis de Ambiente
-
-| Variável | Obrigatória | Padrão | Descrição |
-|----------|-------------|--------|-----------|
-| `CENTRAL_DOCS_REPO` | Sim | - | URL do repo GitLab |
-| `CENTRAL_DOCS_REF` | Não | `main` | Branch para leitura |
-| `CENTRAL_DOCS_TARGET_BRANCH` | Não | `dev` | Branch para MRs |
-| `CENTRAL_DOCS_CACHE_TTL` | Não | `3600` | TTL do cache (segundos) |
-| `SQUAD` | Sim | - | Squad do usuário |
-| `WORKSPACE` | Sim | - | Nome do workspace |
-
-## Exemplos Completos
-
-### Exemplo 1: Setup Inicial
 
-```bash
-# 1. Configurar token
-echo '//gitlab.com/api/v4/packages/npm/:_authToken=glpat-xxx' >> .npmrc
-
-# 2. Configurar ENV.md
-cat >> .windsurf/ENV.md << EOF
-CENTRAL_DOCS_REPO=https://gitlab.com/org/group/central-docs.git
-CENTRAL_DOCS_REF=main
-CENTRAL_DOCS_TARGET_BRANCH=dev
-EOF
-
-# 3. Sincronizar
-jarvis docs sync
-```
+Um adaptador novo (S3, Drive) implementa o mesmo contrato do `filesystem.js` (`fetch`, `list`, `publish`, `buildIndex`) e entra no `storage/index.js`.
 
-### Exemplo 2: Publicar ARD
-
-```bash
-# 1. Criar ARD localmente
-cat > docs/engineering/ard-api-wallet-auth.md << EOF
----
-Status: Proposta
-Data: 2026-03-10
-Autor: João Silva
-Versão: 1.0
----
-
-# ARD-CORE-API-AUTH — Autenticação JWT
-
-...
-EOF
-
-# 2. Publicar
-jarvis docs publish \
-  --file docs/engineering/ard-api-wallet-auth.md \
-  --tipo ard \
-  --feature api-wallet-auth
-
-# 3. Resultado
-# ✅ MR criado: docs/core/engineering/api-wallet/ard-api-wallet-auth → dev
-# URL: https://gitlab.com/.../merge_requests/42
-```
-
-## Referências
+## Troubleshooting
 
-- [SKILL.md](SKILL.md) - Documentação completa da skill
-- [GitLab API Docs](https://docs.gitlab.com/ee/api/) - API do GitLab
+Ver a tabela "Troubleshooting" do `SKILL.md`.