jarvis-ai-framework 1.0.3 → 2.0.0

package/rules/engineering/eng.work-rules.md

@@ -8,7 +8,7 @@ trigger: always_on
 
 ## Propósito
 
-O workflow `work` tem como **único objetivo** implementar código seguindo o plano de execução (`plan.md`). É uma etapa de **codificação pura**, sem commits ou PRs.
+O workflow `work` tem como **único objetivo** implementar código seguindo o plano de execução (`plan.md`). É uma etapa de **codificação**: commita ao final de cada fase validada, mas nunca faz push nem abre PR.
 
 ---
 
@@ -67,19 +67,23 @@ Confirmar que está na branch certa? (s/n)
 
 ## Princípios Fundamentais
 
-### 1. Somente Codificação - NUNCA Commits ou PRs
+### 1. Codificação com commit por fase - NUNCA push ou PR
 
 O `work` é **estritamente proibido** de:
 
 
-| ❌ Proibido                                 | ✅ Permitido                        |
-| ------------------------------------------- | ----------------------------------- |
-| Fazer commits                               | Escrever código                    |
-| Criar Pull Requests                         | Criar/modificar arquivos de código |
-| Executar`git add`, `git commit`, `git push` | Ler arquivos da sessão             |
-| Mover cards no Jira                         | Executar testes locais              |
-| Fazer merge de branches                     | Atualizar`plan.md` com progresso    |
-| Sugerir "vamos fazer o PR agora"            | Validar código com o usuário      |
+| ❌ Proibido                                        | ✅ Permitido                                              |
+| -------------------------------------------------- | --------------------------------------------------------- |
+| Fazer `git push`                                   | Escrever código                                           |
+| Criar Pull Requests                                | Criar/modificar arquivos de código                        |
+| Usar `git add .`                                   | `git add` de arquivos específicos da fase                 |
+| Commitar sem aprovação do usuário na fase          | Commitar ao final da fase validada, com testes passando   |
+| Commitar com testes falhando                       | Executar testes locais                                    |
+| Mover cards no Jira                                | Ler arquivos da sessão                                    |
+| Fazer merge de branches                            | Atualizar `plan.md` com progresso                         |
+| Sugerir "vamos fazer o PR agora"                   | Validar código com o usuário                              |
+
+O commit segue o formato do workflow (`{TASK_MANAGER_KEY} {tipo}({escopo}): {descrição}`, com `Refs:`). Push e PR são responsabilidade do `eng.pr`.
 
 ### 2. Escopo de Atuação
 
@@ -187,7 +191,7 @@ O workflow segue um ciclo rígido:
 
     - Informar que a fase foi concluída
     - Perguntar se deseja iniciar próxima fase
-    - ⚠️ **NUNCA sugerir PR ou commit**
+    - ⚠️ **NUNCA sugerir push ou PR** (são do `eng.pr`)
 
 ---
 
@@ -243,9 +247,9 @@ O workflow **DEVE pausar e aguardar confirmação**:
 
 1. **Escapar para Git**
 
-   - "Vou fazer o commit dessas mudanças..."
    - "Agora podemos criar o PR..."
    - "Deixa eu dar push das alterações..."
+   - `git add .` ou commit com testes falhando
 2. **Pular validação**
 
    - Implementar várias fases sem pausar
@@ -291,7 +295,7 @@ Ao finalizar **TODAS as fases** do `plan.md`, informe:
 2. Execute os testes completos
 3. Quando estiver pronto, use `eng.pr` para criar o Pull Request
 
-⚠️ Este workflow NÃO faz commits ou PRs.
+⚠️ Este workflow commita por fase, mas NÃO faz push nem PR.
    Use `eng.pr` quando estiver pronto para submeter.
 ```
 
@@ -307,6 +311,7 @@ Antes de considerar uma fase completa:
 - [ ]  Usuário validou o código
 - [ ]  `plan.md` atualizado com status
 - [ ]  Comentários adicionados no plan.md
-- [ ]  NENHUM commit foi feito
+- [ ]  Commit da fase feito (arquivos adicionados um a um, testes passando)
+- [ ]  NENHUM push foi feito
 - [ ]  NENHUM PR foi criado
 - [ ]  Próximos passos comunicados

package/rules/engineering/frontend/eng.frontend-rules.md

@@ -1,47 +1,50 @@
 ---
 name: eng.frontend-rules
 description: >
-  Padrões obrigatórios para devs com HUB: FRONTEND — componentes, TypeScript,
-  acessibilidade, performance, micro frontend e design system.
+  Padrões obrigatórios para devs com HUB: FRONTEND, neutros de stack — componentes,
+  tipagem, acessibilidade, performance, testes, arquiteturas distribuídas e tokens de design.
+  O que depende da stack vem das especializações registradas em FRONTEND_SPECIALIZATIONS.
 author: jarvis-team
-version: "1.0"
+version: "1.1"
 ---
 
 > **Applies to:** HUB: FRONTEND | POSITION: all | AREA: ENGINEERING | SQUAD: all
 
 # Regras de Engenharia Frontend
 
+> **Neutras de stack.** Estas regras valem para qualquer framework ou linguagem de frontend. Onde uma regra depende da stack (como se busca dados, como se organiza um módulo, qual ferramenta de teste usar), siga a **especialização registrada** em `FRONTEND_SPECIALIZATIONS` no `ENV.md` e o código existente do projeto. Sem especialização registrada, **pergunte** em vez de presumir uma stack. Ver `eng.specializations-rules.md`.
+
 ---
 
 ## 1. Componentes
 
 ### Estrutura obrigatória
-- Todo componente deve ter props tipadas com TypeScript — `any` é proibido sem justificativa documentada
-- Props obrigatórias devem ser declaradas sem `?`; opcionais com `?` e valor default explícito
+- Toda entrada de um componente (props, parâmetros ou atributos) é **tipada ou documentada**; tipo genérico solto (`any` ou equivalente) é proibido sem justificativa documentada
+- Entradas obrigatórias são declaradas como obrigatórias; opcionais têm valor default explícito
 - Componentes com mais de uma responsabilidade devem ser divididos (Single Responsibility)
-- Lógica de negócio não pertence ao componente de UI — usar hooks ou camada de serviço
+- Lógica de negócio não pertence ao componente de UI — usar a camada de lógica ou de serviço que o projeto adota
 
 ### Nomenclatura
-- Componentes: `PascalCase` (`UserCard`, `ProductTable`)
-- Hooks: `use` + `PascalCase` (`useUserData`, `useProductFilters`)
-- Arquivos de componente: `PascalCase.tsx` (`UserCard.tsx`)
-- Arquivos de hook: `camelCase.ts` (`useUserData.ts`)
+- Seguir a convenção de nomes **do projeto** (e da especialização registrada) para componentes, funções de lógica reutilizável e arquivos
+- Manter o padrão consistente: um mesmo tipo de arquivo, um mesmo estilo de nome
 
 ### Checklist mínimo por componente
-- [ ] Props tipadas (TypeScript)
+- [ ] Entradas tipadas ou documentadas
 - [ ] Estados visuais: normal, hover, focus, disabled, loading, erro, vazio
-- [ ] Semântica HTML correta (não usar `<div>` para botões, links ou listas)
-- [ ] Responsivo (mobile-first com breakpoints do design system)
-- [ ] Testável sem DOM real (lógica isolada em hooks)
+- [ ] Semântica HTML correta (não usar um contêiner genérico para botões, links ou listas)
+- [ ] Responsivo (mobile-first, nos tamanhos de tela do projeto)
+- [ ] Testável sem depender de um navegador real (lógica isolada da apresentação)
 
 ---
 
-## 2. TypeScript
+## 2. Tipagem e contratos
+
+Aplica-se quando a linguagem do projeto tem tipagem estática ou contratos explícitos.
 
-- `strict: true` obrigatório em `tsconfig.json`
-- Proibido: `as any`, `@ts-ignore` sem comentário explicativo, `!` (non-null assertion) sem verificação prévia
-- Types vs Interfaces: usar `interface` para objetos de domínio, `type` para uniões e utilitários
-- Exportar tipos públicos de componentes (`export type { ButtonProps }`)
+- O **modo estrito** de verificação do projeto fica ligado e não é relaxado
+- Proibido: tipo genérico solto, supressão de verificação de tipos sem comentário explicativo e asserção de "não nulo" sem verificação prévia
+- Modelar objetos de domínio de forma explícita e unir ou derivar tipos com os recursos da linguagem
+- Exportar o contrato público dos componentes, quando a linguagem permite
 
 ---
 
@@ -49,12 +52,12 @@ version: "1.0"
 
 - Semântica HTML nativa antes de ARIA (`<button>`, `<nav>`, `<main>`, `<article>`)
 - Todos os elementos interativos são navegáveis por teclado
-- Contraste mínimo: 4.5:1 para texto normal, 3:1 para texto grande e elementos UI
-- Imagens informativas têm `alt` descritivo; decorativas têm `alt=""`
-- Modais usam `role="dialog"`, `aria-modal="true"`, `aria-labelledby` e focus trap
-- Formulários: todo `<input>` tem `<label>` associado via `htmlFor` ou `aria-label`
+- Contraste mínimo: 4.5:1 para texto normal, 3:1 para texto grande e elementos de interface
+- Imagens informativas têm texto alternativo descritivo; decorativas têm texto alternativo vazio
+- Modais usam `role="dialog"`, `aria-modal="true"`, `aria-labelledby` e prendem o foco
+- Formulários: todo campo tem rótulo associado
 - Erros de formulário: exibidos com `role="alert"` ou `aria-live="polite"`
-- Screen reader: testar com VoiceOver (Mac) ou NVDA (Windows) em features críticas
+- Leitor de tela: testar com VoiceOver (Mac) ou NVDA (Windows) em features críticas
 
 ---
 
@@ -66,59 +69,56 @@ version: "1.0"
 - INP (Interaction to Next Paint): < 200ms
 
 ### Práticas obrigatórias
-- Imagens sempre com `width` e `height` definidos para evitar CLS
-- Componentes pesados com `lazy()` + `<Suspense fallback>`
-- Dependências novas: avaliar impacto no bundle antes de instalar (`bundlephobia.com`)
-- Sem `useEffect` para buscar dados — usar React Query / TanStack Query ou Server Components
-- Memoização apenas quando necessário e comprovado com profiler (não premature optimization)
+- Imagens sempre com largura e altura definidas, para evitar CLS
+- Carregamento tardio de componentes pesados, com o recurso que a stack oferece, e um substituto visual com o mesmo tamanho enquanto carrega
+- Dependências novas: avaliar o impacto no tamanho do pacote final antes de instalar
+- Busca de dados pela camada que o projeto adota para isso (conforme a especialização), e não por efeitos soltos no componente de apresentação
+- Otimização de renderização apenas quando necessária e **comprovada com medição** (não otimização prematura)
 
 ---
 
 ## 5. Testes
 
-- **Testing Library**: queries por acessibilidade primeiro (`getByRole`, `getByLabelText`)
-- **Proibido**: `getByTestId` como primeira opção (usar só quando sem alternativa acessível)
-- **Cobertura mínima**: fluxos críticos de usuário (happy path + estado de erro)
-- **Vitest**: unitários para lógica pura, hooks e utilitários
-- **Playwright / Cypress**: E2E para fluxos de usuário completos (login, checkout, etc.)
-- Mocks de módulos externos devem estar em `__mocks__/` ou `*.mock.ts`
+- **Consultas por acessibilidade primeiro** (por papel e por rótulo): focar no que o usuário vê e faz, não em detalhes de implementação
+- **Proibido** usar identificador de teste como primeira opção (só quando não houver alternativa acessível)
+- **Cobertura mínima:** fluxos críticos de usuário (caminho feliz e estado de erro)
+- **Testes unitários** para lógica pura e utilitários, com a ferramenta que o projeto já usa
+- **Testes de ponta a ponta** para fluxos completos de usuário (login, checkout etc.), com a ferramenta que o projeto já usa
+- Substitutos de módulos externos ficam num lugar previsível do projeto (por exemplo, uma pasta de mocks)
 
 ### Ferramentas disponíveis no framework
 
-- **TestSprite** (`/eng-qa-testsprite`): se o TestSprite estiver instalado no projeto, usá-lo para geração
-  e execução de testes de componente e E2E — ele gera planos de teste e código automaticamente.
+- **TestSprite** (`/eng-qa-testsprite`): se estiver instalado no projeto, usá-lo para gerar e executar testes de componente e de ponta a ponta — ele gera planos de teste e código automaticamente.
   Verificar: `ls node_modules/@testsprite 2>/dev/null || cat package.json | grep testsprite`
-
-- **Stagehand** (`/eng-scraper-robot-builder`, `/eng-qa-e2e`): para testes E2E em linguagem natural
-  ou automação de fluxos de usuário complexos, o Stagehand permite descrever o fluxo em português
-  e gera os steps Playwright automaticamente.
+- **Stagehand** (`/eng-scraper-robot-builder`, `/eng-qa-e2e`): para testes de ponta a ponta em linguagem natural ou automação de fluxos complexos, descrevendo o fluxo em português.
   Verificar: `cat package.json | grep stagehand`
 
-> Quando qualquer dessas ferramentas estiver disponível no projeto, **preferir sobre a implementação
-> manual** — reduz custo de manutenção e aumenta cobertura mais rapidamente.
+> Quando qualquer dessas ferramentas estiver disponível no projeto, **preferir sobre a implementação manual** — reduz o custo de manutenção e aumenta a cobertura mais rápido.
 
 ---
 
-## 6. Micro Frontend
+## 6. Arquiteturas distribuídas (se o projeto divide o frontend em partes)
+
+Aplica-se somente se o projeto divide o frontend em partes carregadas separadamente (por exemplo, uma aplicação principal que carrega módulos independentes). O detalhe da arquitetura em uso vem da especialização registrada. Princípios que valem em qualquer variante:
 
-- Todo remote deve ser versionado e publicado com URL de fallback definida
-- Contratos de interface entre shell e remotes são declarados em tipos TypeScript compartilhados
-- Nenhum remote depende diretamente de outro remote — comunicação via shell ou event bus
-- Shared dependencies declaradas explicitamente no `ModuleFederationPlugin` com `singleton: true`
-- Cada remote deve funcionar em modo standalone (sem shell) para desenvolvimento local
-- Testes de integração entre shell e remote são obrigatórios para cada ponto de montagem
-- Versionamento: breaking changes no contrato de um remote exigem bump de versão major
+- Cada módulo é **versionado e publicado** com uma alternativa definida quando não carrega
+- Os contratos de interface entre a aplicação principal e os módulos são declarados de forma explícita e compartilhada
+- Nenhum módulo depende diretamente de outro: a comunicação passa pela aplicação principal ou por um barramento de eventos
+- Dependências compartilhadas são declaradas explicitamente, para não serem carregadas em duplicidade
+- Cada módulo deve funcionar de forma isolada, para desenvolvimento local
+- Testes de integração entre a aplicação principal e cada módulo são obrigatórios em cada ponto de montagem
+- Mudança que quebra o contrato de um módulo exige aumento de versão **major**
 
 ---
 
-## 7. Design System
+## 7. Tokens de design e componentes compartilhados
 
-- Cores, tipografia, espaçamentos e breakpoints vêm **exclusivamente** dos tokens do design system
-- Proibido hardcodar valores de cor, fonte ou espaçamento fora dos tokens
-- Novos componentes de UI são criados no design system antes de serem usados nos remotes
-- Variantes de componente usam `cva` (class-variance-authority) como padrão
-- Componentes públicos do design system têm story no Storybook antes de serem liberados
-- Alterações na API pública de um componente (props) seguem semver
+- Cores, tipografia, espaçamentos e tamanhos de tela vêm **exclusivamente** dos tokens de design do projeto (quando o projeto tem)
+- Proibido fixar valores de cor, fonte ou espaçamento fora dos tokens
+- Novos componentes reutilizáveis nascem na biblioteca de componentes compartilhados do projeto (se existir) antes de serem usados nos módulos
+- Variantes de componente seguem o padrão que o projeto já usa
+- Componentes públicos da biblioteca compartilhada têm documentação visual antes de serem liberados, quando o projeto usa um catálogo de componentes
+- Alterações na interface pública de um componente seguem o versionamento semântico
 
 ---
 
@@ -126,22 +126,23 @@ version: "1.0"
 
 Ao revisar PR de frontend, verificar:
 
-- [ ] TypeScript sem `any` ou `@ts-ignore` injustificado
+- [ ] Tipagem sem tipo genérico solto nem supressões injustificadas (quando a linguagem tem tipagem)
 - [ ] Nenhuma lógica de negócio em componente de UI
 - [ ] Acessibilidade: semântica HTML, ARIA correto, navegação por teclado
-- [ ] Performance: sem re-renders desnecessários, lazy loading aplicado quando cabível
-- [ ] Tokens do design system usados (sem valores hardcodados)
-- [ ] Testes cobrem happy path e estado de erro
-- [ ] Responsividade verificada em mobile e desktop
-- [ ] Se micro frontend: contrato de interface atualizado, remote funciona standalone
+- [ ] Performance: sem renderizações desnecessárias comprovadas, carregamento tardio aplicado quando cabível
+- [ ] Tokens de design do projeto usados (sem valores fixos)
+- [ ] Testes cobrem o caminho feliz e o estado de erro
+- [ ] Responsividade verificada em celular e desktop
+- [ ] Se arquitetura distribuída: contrato de interface atualizado e módulo funciona de forma isolada
+- [ ] Itens exigidos pelas especializações registradas atendidos
 
 ---
 
 ## 9. Proibições Absolutas
 
-- `document.querySelector` / manipulação direta do DOM em contexto React
+- Manipulação direta do DOM fora do mecanismo que o framework do projeto prevê para isso
 - `!important` em CSS sem comentário explicativo
-- Fetch direto em componente de UI (usar hooks, queries ou Server Actions)
-- Importar de outro remote diretamente (rompe o isolamento do micro frontend)
-- Hardcodar tokens de design (cores, espaçamentos, fontes) fora do sistema de tokens
-- `console.log` em código commitado (usar logger estruturado ou remover)
+- Busca de dados direto no componente de apresentação (usar a camada que o projeto adota)
+- Importar diretamente de outro módulo de uma arquitetura distribuída (rompe o isolamento)
+- Fixar tokens de design (cores, espaçamentos, fontes) fora do sistema de tokens
+- Log de depuração (`console.log` ou equivalente) em código commitado (usar logger estruturado ou remover)

package/rules/product/README.md

@@ -12,6 +12,7 @@ Documentação didática (termos por extenso, exemplos, quando usar cada comando
 |---------|--------|
 | Guia de decisão (qual spec?) | [prod.spec.guide.md](../../docs/produto/prod.spec.guide.md) |
 | `/prod.spec` | [prod.spec.md](../../docs/produto/prod.spec.md) |
+| `/prod.spec.discovery` | [prod.spec.discovery.md](../../docs/produto/prod.spec.discovery.md) |
 | `/prod.spec.prd` | [prod.spec.prd.md](../../docs/produto/prod.spec.prd.md) |
 | `/prod.spec.frd` | [prod.spec.frd.md](../../docs/produto/prod.spec.frd.md) |
 | `/prod.spec.breakdown` | [prod.spec.breakdown.md](../../docs/produto/prod.spec.breakdown.md) |
@@ -22,3 +23,4 @@ Documentação didática (termos por extenso, exemplos, quando usar cada comando
 ## Arquivo normativo (agentes)
 
 - [`prod-rules.md`](./prod-rules.md) — ENV, pastas, status, convenção de nomes, formato de perguntas
+- [`prod.spec-rules.md`](./prod.spec-rules.md) — princípios de escrita de spec: critérios de aceitação por tipo de documento, contexto completo e terminologia consistente

package/rules/product/prod-rules.md

@@ -7,9 +7,9 @@ trigger: always_on
 ## Principais Regras
 - O idioma padrão é o português do Brasil. Mas mude caso o usuário solicite outro idioma.
 - Leia o `./$IDE/ENV.md` para entender as variáveis de ambiente do framework. Ele é importante para você saber caminhos de pastas e outras informações sobre projeto e usuário.
-  - Se não existir, use o skill `init-jarvis` para criar o `ENV.md`.
+  - Se não existir, use o skill `jarvis-init` para criar o `ENV.md`.
 - Procure `CLAUDE.md` ou `AGENTS.md` para entender informações sobre o contexto e objetivo do projeto.
-  - Se não existirem, use o skill `init-jarvis` para criar o `AGENTS.md` e após essa criação, copie o conteúdo do `AGENTS.md` para o `CLAUDE.md` (se não existir o CLAUDE.md, crie-o).
+  - Se não existirem, use o skill `jarvis-init` para criar o `AGENTS.md` e após essa criação, copie o conteúdo do `AGENTS.md` para o `CLAUDE.md` (se não existir o CLAUDE.md, crie-o).
 - Nunca invente ou presuma dados ou informações. Se não souber, pergunte, valide e confirme com o usuário.
 - Entenda se o projeto é novo ou existente, para criar ou modificar especificações de produto ou técnicas.
 
@@ -18,7 +18,7 @@ trigger: always_on
 IMPORTANTE: Para que você funcione como o previsto e tenha todas as informações necessárias, é importante que você leia e interprete o arquivo `./$IDE/ENV.md`. Esse é o arquivo que guardamos variáveis de informações importantes sobre o projeto, o usuário e estruturas de pastas e arquivos que você precisará para operar corretamente.
 
 - **Sempre no início de novas sessões ou interações, ANTES de executar qualquer comando ou workflow**, o agente **DEVE verificar** se o arquivo `$IDE/ENV.md` existe e está preenchido corretamente.
-- **Exceção**: O comando `/init-jarvis` é o único que pode ser executado sem o `ENV.md`, pois é ele que cria o arquivo.
+- **Exceção**: O comando `/jarvis-init` é o único que pode ser executado sem o `ENV.md`, pois é ele que cria o arquivo.
 - **Validação obrigatória**: O arquivo deve conter as seguintes variáveis preenchidas (não vazias):
   - `RULES_FOLDER`
   - `PROD_FOLDER_NAME`
@@ -30,7 +30,7 @@ IMPORTANTE: Para que você funcione como o previsto e tenha todas as informaçõ
 - **Se o ENV.md não existir ou estiver incompleto**, o agente deve:
   1. Interromper a execução do comando solicitado
   2. Informar ao usuário que não podemos avançar sem o ENV.md. Mensagem abaixo.
-  3. Após confirmação, executar via Skill tool o `init-jarvis`. No caso de negativa, o agente poderá avançar apenas para criar especificações de produto. E sempre que precisar salvar arquivos das especificações, deverá confirmar com o usuário. 
+  3. Após confirmação, executar via Skill tool o `jarvis-init`. No caso de negativa, o agente poderá avançar apenas para criar especificações de produto. E sempre que precisar salvar arquivos das especificações, deverá confirmar com o usuário. 
   ```
   ⚠️ O framework não foi inicializado.
 
@@ -42,7 +42,7 @@ Se o arquivo não existir ou no caso de recusa, crie o `$IDE/ENV.md` incluindo a
 RULES_FOLDER=.$IDE/rules
 PROD_FOLDER_NAME=product
 PROD_RULES=$RULES_FOLDER/$PROD_FOLDER_NAME
-PROD_FLOWS=.$IDE/$FLOWS_FOLDER/$PROD_FOLDER_NAME
+PROD_FLOWS=.$IDE/$FLOWS_FOLDER
 PROD_TEMPLATES=.$IDE/$TEMPLATES_FOLDER/$PROD_FOLDER_NAME
 PROD_DOCS=$DOCS_FOLDER/$PROD_FOLDER_NAME
 CENTRAL_DOCS_REPO=[USER:LOCAL_CENTRAL_DOCS_REPO]
@@ -95,6 +95,7 @@ Abaixo, segue uma descrição de algumas das variáveis mais importantes para as
 Sempre siga as instruções de acordo com as relações abaixo.  
 **Guia para humanos (desenvolvedores aprendendo produto):** `docs/produto/` — uma página por comando, termos por extenso.
 
+- `$PROD_FLOWS/prod.spec.discovery.md` — Investigação inicial de uma ideia (rascunho estruturado; não define tarefas) → [docs/produto/prod.spec.discovery.md](../../docs/produto/prod.spec.discovery.md)
 - `$PROD_FLOWS/prod.spec.prd.md` — Documento de Requisitos de Produto (*Product Requirements Document*) → [docs/produto/prod.spec.prd.md](../../docs/produto/prod.spec.prd.md)
 - `$PROD_FLOWS/prod.spec.frd.md` — Documento de Requisitos Funcionais (*Functional Requirements Document*) → [docs/produto/prod.spec.frd.md](../../docs/produto/prod.spec.frd.md)
 - `$PROD_FLOWS/prod.spec.breakdown.md` — Quebra de especificação grande em fatias → [docs/produto/prod.spec.breakdown.md](../../docs/produto/prod.spec.breakdown.md)
@@ -129,6 +130,7 @@ Dentro das pastas do projeto, os caminhos de pastas e o nome dos arquivos finais
 - Documento de Requisitos Funcionais: `$PROD_DOCS/prd-{id}-{nome-do-pai}/frd-{id}-{nome}.md`
 - Épico: `$PROD_DOCS/prd-{id}-{nome-do-pai}/issues/epic-{id}-{nome}.md`
 - História / tarefa: `$PROD_DOCS/prd-{id}-{nome-do-pai}/issues/{story|task}-{id}-{nome}.md`
+- Discovery (rascunho de uma ideia, anterior ao PRD): `$PROD_DOCS/discoveries/discovery-{id}-{nome}.md`. Usa `status` (`in_review` enquanto o rascunho existe; `cancelled` se o veredito for não seguir) e `verdict` (vazio durante a entrevista, `proceed`, `investigate_more` ou `do_not_proceed`). O veredito é uma recomendação; um PRD, FRD, épico ou issue criado depois prevalece como fonte da verdade.
 
 O ID deve ser iterado nos novos arquivos seguindo a sequência existente.
 

package/{skills/prod-specs/rules/prod-spec-rules.md → rules/product/prod.spec-rules.md}

@@ -2,75 +2,39 @@
 trigger: always_on
 ---
 
-## Principais Regras
-- O idioma padrão é o português do Brasil. Mas mude caso o usuário solicite outro idioma.
-- Sempre procure por arquivos de configuração e documentação do projeto antes de executar qualquer comando ou workflow.
-- Leia o `README.md` do projeto para saber contexto e detalhes importantes.
-- Nunca invente ou presuma dados ou informações. Se não souber, pergunte, valide e confirme com o usuário.
-- Entenda se o projeto é novo ou existente, para criar ou modificar especificações de produto ou técnicas.
-- Identifique se o produto é versionado com git e leia o histórico de commits para entender as últimas atualizações.
+> **Applies to:** HUB: all | POSITION: all | AREA: PRODUCT | SQUAD: all
 
+# Regras de Escrita de Especificação de Produto
 
-## Diretórios e Variáveis dessa Skill
+## Objetivo
 
-Utilize essas variáveis para interpretar corretamente o contexto as instruções dessa skill. Os endereços são relativos ao diretório raiz desse plugin:
+Definir os princípios que todo documento de especificação de produto (PRD, FRD, épico, história, tarefa e bug) deve seguir: o nível certo de critérios de aceitação em cada tipo de documento, contexto completo, terminologia consistente e o uso opcional de um discovery como insumo.
 
-**Diretório da skill:** `${CLAUDE_SKILL_DIR}`
+## Escopo
 
-- `$SKILL_TEMPLATE_FOLDER`: `${CLAUDE_SKILL_DIR}/templates/`
-- `$SKILL_REFERENCES_FOLDER`: `${CLAUDE_SKILL_DIR}/references/`
+Aplica-se a todos os comandos `prod.spec.*` que escrevem ou alteram um documento. Complementa o `prod-rules.md` (variáveis de ambiente, comandos, nomes de arquivos, status e perguntas ao usuário), que continua sendo a regra geral de produto.
 
+## Regras
 
-## Perguntas para guiar o usuário
+### Princípio: Critérios de aceitação e requisitos
 
-Para fazer perguntas ao usuário:
-1. Tente usar o tool `AskUserQuestion` se ele estiver disponível no seu ambiente (ex: Claude Desktop, Claude Cowork, Claude Code CLI).
-2. Se não estiver disponível, use **obrigatoriamente** (se possível) o formato de tabela abaixo. Caso não possível no formato de tabela, faça perguntas em texto corrido.
-3. Nunca avance sem coletar as respostas necessárias.
+#### Critérios de aceitação específicos do documento
 
-```
-|     | {Aqui fica a pergunta que você deve fazer para o usuário. Seja objetivo e direto ao ponto:} |
-| --- | ----------------------------------------------------------------------------------------- |
-| A   | {Resposta 1}                                                                                |
-| B   | {Resposta 2}                                                                                |
-| C   | {Resposta 3}                                                                                |
-| D   | {Resposta 4}                                                                                |
-```
-
-**NUNCA** pergunte tudo de uma vez, sempre faça perguntas separadas e aguarde a resposta antes de prosseguir.
-
-
-## Descrição dos Status
-
-Em itens e especificações, utilizamos status para identificar quais etapas do desenvolvimento cada item está. Isso é representado pela variável `$ITEM_STATUS`. 
-
-- icebox: Lista de ideias, necessidades e desejos. Item que está aguardando priorização ou definição de escopo.
-- in_review: Item que está sendo estudado, descoberto, revisado ou analisado.
-- backlog: Item já foi estudado, sabemos o que fazer e está aguardando priorização de implementação.
-- in_progress: Item que está em desenvolvimento.
-- in_production: Item que está em produção.
-- cancelled: Item que foi descontinuado ou cancelado.
-
-
-## Princípio: Critérios de aceitação e requisitos
-
-### Critérios de aceitação específicos do documento
-
-#### Para PRDs (nível macro)
+##### Para PRDs (nível macro)
 Concentre-se no "o quê" e no "porquê":
 - Definir capacidades gerais do produto
 - Definir regras e restrições de negócios
 - Estabelecer métricas de sucesso
 - Descrições sempre levando em consideração as soluções macro do Projeto, baseando-se nas FRDs
 
-#### Para FRDs (nível médio)
+##### Para FRDs (nível médio)
 Retrata as soluções macro do produto. É ponte entre estratégia e implementação:
 - Definir requisitos de nível de recurso
 - Definir limites para histórias relacionadas
 - Incluir pontos de integração
 - Definir requisitos não funcionais
 
-### Para histórias (detalhadas, funcionais)
+#### Para histórias (detalhadas, funcionais)
 
 Concentre-se em comportamentos específicos e testáveis com base em designs:
 
@@ -104,7 +68,7 @@ Concentre-se em comportamentos específicos e testáveis com base em designs:
 - **Épico**: escopo em nível de recurso e abordagem técnica
 - **Issues (História/Tarefa)**: detalhes específicos de implementação e comportamento da UI
 
-## Princípio: Contexto completo
+### Princípio: Contexto completo
 
 **Princípio**: Cada documento deve ser compreensível por si só, sem exigir conhecimento tribal.
 
@@ -147,7 +111,7 @@ As pessoas juntam-se em equipas, o contexto perde-se, as memórias desaparecem.
 - **Bugs rápidos**: ambiente do documento, etapas, comportamento esperado
 - **Tarefas rápidas**: explique por que esse trabalho é importante
 
-## Princípio: Terminologia Consistente
+### Princípio: Terminologia Consistente
 
 **Princípio**: Use os mesmos termos para os mesmos conceitos em toda a documentação.
 
@@ -184,3 +148,44 @@ A terminologia inconsistente cria confusão. "Cliente" vs "Usuário" vs "Cliente
 - **Planos**: use os termos exatos do PRD
 - **Histórias**: Combine a terminologia do PRD e do Plano
 - **Questões rápidas**: use terminologia estabelecida ou defina novos termos
+
+### Princípio: Discovery como insumo
+
+**Princípio**: O discovery (`$PROD_DOCS/discoveries/discovery-{id}-{nome}.md`) é um rascunho de suposições. Ele pode servir de contexto para um PRD, FRD, épico ou issue, mas nunca é obrigatório e nunca é tratado como verdade.
+
+**O discovery é opcional**:
+- Sem discovery apontado, siga o fluxo do comando normalmente, sem procurar na pasta `discoveries/` e sem perguntar nada sobre discovery. Ter arquivos nessa pasta não tem relação com o comando.
+- Exemplos: `/prod.spec.prd já sei o que quero` segue o fluxo de sempre; `/prod.spec.prd discovery-002` carrega o discovery.
+
+**Como apontar e achar o discovery**:
+- O usuário aponta por caminho, nome ou id (como `discovery-002`); procure em `$PROD_DOCS/discoveries/`.
+- Se o arquivo não existir: informe, liste os discoveries da pasta e pergunte qual usar, ou se o usuário prefere seguir sem discovery.
+- Se a pasta `discoveries/` não existir: siga sem discovery e não crie a pasta.
+- Se mais de um arquivo casar com o que o usuário apontou: pergunte qual usar, sem escolher sozinho.
+
+**Como usar o discovery**:
+- Leia o discovery como **contexto, não como resposta**: é um rascunho e pode estar defasado.
+- **Questione e repasse tudo com o usuário**, seção por seção: mostre o que está registrado e pergunte se ainda vale ou se mudou.
+- Hipóteses e perguntas em aberto do discovery são perguntadas como tais; o que o comando exige e o discovery não cobre é perguntado normalmente.
+- Nada do discovery entra no documento novo como fato sem o usuário ter passado por aquilo. O que ficar sem validação continua marcado como suposição.
+
+**Avisos conforme a situação do discovery**:
+- `verdict: do_not_proceed` (ou `status: cancelled`): avise que a recomendação foi não seguir, mostre o motivo registrado e só continue com confirmação explícita do usuário.
+- `verdict: investigate_more`, `verdict` vazio ou `status: in_review` (discovery ainda em entrevista): avise que há lacunas críticas, liste as perguntas em aberto e pergunte se o usuário quer retomar o discovery antes ou seguir assumindo o risco.
+- `verdict: proceed`: siga normalmente.
+
+**O documento novo é o oficial**:
+- O PRD, FRD, épico ou issue é a fonte da verdade. O discovery **nunca é alterado** por estes comandos: ele permanece como o registro do momento da investigação.
+- O documento novo referencia o discovery de origem no campo `related_discovery` do frontmatter.
+- Quando a informação do documento novo divergir do discovery, **avise o usuário na conversa** e crie no documento novo a seção **"Divergências"** (somente quando houver), com o que mudou e por quê, em poucas linhas.
+
+## Exceções
+
+Quando o usuário pedir explicitamente outro formato ou nível de detalhe para um documento, registre a decisão no próprio documento e siga o pedido.
+
+## Referências
+
+- `prod-rules.md`: regras gerais de produto (ambiente, comandos, nomes de arquivos, status e perguntas ao usuário)
+- `../../templates/product/`: templates dos documentos
+- `../../workflows/product/`: os comandos `prod.spec.*`
+- `prod.spec.discovery.md` (workflow) e `prod-discovery-template.md`: o comando e o formato do discovery, o rascunho que os comandos acima podem usar como insumo