jarvis-ai-framework 1.0.0

package/skills/prod-specs/references/prod.spec.prd.md

@@ -0,0 +1,118 @@
+---
+name: prod.spec.prd
+description: Instruções para alterar ou criar um especificação de produto PRD - Product Requirement Document seguindo o template e as melhores prática de mercado, de forma que possa ser utilizado e expandido por agentes de IA e humanos.
+auto_execution_mode: 3
+env_file: "@/ENV.md"
+allowed-tools: Read, Grep
+recommended_model: claude-sonnet-4-20250514
+model_tier: high
+model_justification: PRDs requerem análise profunda de requisitos, estruturação de documentos complexos e compreensão de contexto de negócio
+---
+
+# PRD - Product Requirement Document
+
+Utilize o `$ARGUMENTS` que o usuário passar como ponto de partida e para entender o contexto do que foi pedido.
+<requirement>
+#$ARGUMENTS
+</requirement>
+
+# Quando usar
+- Ao iniciar uma nova especificação de PRD (Product Requirment Document)
+- Precisar modificar um PRD existente
+- Quando documentação abrangente é necessária
+- Como fonte única de verdade para o desenvolvimento do produto e base para derivar histórias e tarefas
+
+## Princípios Fundamentais
+1. **Sempre use o template** desta skill localizado em `$SKILL_TEMPLATE_FOLDER/prod-prd-template.md` dessa skill para o output final
+2. **Nunca crie o arquivo final com suposições não validadas** — sempre confirme sugestões primeiro
+3. **Seja inteligente, não robótico** — analise o contexto e proponha sugestões inteligentes, não faça perguntas vazias
+
+---
+
+## Fluxo de Trabalho
+
+O fluxo é dividido em checkpoints obrigatórios (gates). Você NÃO DEVE avançar para o próximo gate até que o usuário aprove explicitamente o atual. NUNCA gere o arquivo final até que TODOS os gates sejam aprovados.
+
+Não busque validação de tudo de uma vez; valide os gates de forma incremental.
+
+### Gate 1: Reconhecer e esclarecer
+- Reconheça o que o usuário forneceu (liste o que foi recebido).
+- Identifique o que foi fornecido explicitamente vs. o que está faltando
+- Evite fazer novas buscas ou leitura de arquivos se você já recebeu informações suficientes para prosseguir. Caso contrário, peça mais informações para o usuário. Diga exatamente o que você precisa para preencher o template completamente.
+- Faça 2–3 perguntas estratégicas sobre: clareza do problema, limites de escopo, restrições técnicas
+- **PARE e aguarde a resposta do usuário antes de prosseguir**
+
+### Gate 2: Sugerir conteúdo para seções ausentes
+- Para CADA seção do template que o usuário NÃO forneceu conteúdo explicitamente, apresente suas sugestões com justificativa. Se o usuário pular, não coloque o bloco no output final.
+- Agrupe sugestões relacionadas (ex.: todos os indicadores de sucesso juntos, todas as evoluções futuras juntas)
+- Formato: "Para [Nome da Seção], sugiro: [conteúdo]. Justificativa: [por quê]. Devo incluir, modificar ou remover?"
+- Seções que DEVEM ser validadas se não fornecidas pelo usuário: TL;DR, Contexto, Definição do Problema, Indicadores de Sucesso, O que esta Iniciativa Não É, Evoluções Futuras, Fora do Escopo
+- **PARE e aguarde o usuário aprovar, modificar ou rejeitar CADA grupo de sugestões antes de prosseguir**
+
+### Gate 3: Confirmar lista de FRDs
+O FRD representa funcionalidades e características do produto/solução. Não são tarefas, histórias ou micro ações dentro da funcionalidade. O FRD decompõe o PRD em soluções de médio porte que, juntas, formam a solução final.
+
+- Utilize primariamente a lista de FRDs que o usuário deve ter fornecido. 
+- Se usuário não forneceu qualquer tipo de FRD, apresente uma lista sugestiva a partir das informações do projeto que você tem até agora e use práticas e seu conhecimento de mercado para sugerir uma lista completa de FRDs que podem ser concluídos, com ID, nome e uma descrição em uma linha
+- Separe claramente: FRDs baseados no input do usuário vs. FRDs que você está sugerindo
+- **PARE e aguarde a confirmação do usuário antes de prosseguir**
+
+### Gate 4: Gerar output final
+- Se está modificando um PRD existente, apenas atualize as seções que foram alteradas ou adicionadas ou especificadas pelo usuário. Não modifique o arquivo sem pedido explicito do usuário.
+- Somente após os Gates 1–3 aprovados, gere o output final usando o template localizado em `$SKILL_TEMPLATE_FOLDER/prod-prd-template.md`
+- O output final deve conter APENAS: conteúdo fornecido pelo usuário + sugestões aprovadas pelo usuário, seguindo o template
+- Se uma seção não tiver conteúdo fornecido ou aprovado, deixe em branco com um marcador TODO e informe o usuário
+- Antes de disponibilizar o output final, valide se está seguindo todos os padrões estabelecidos no template
+- Disponibilize o output final como artefato para o usuário ou para o Agente AI utilizado, conforme a necessidade
+
+---
+
+## Abordagens por Contexto
+
+**Contexto rico** (documento/requisitos detalhados fornecidos):
+- Analise o que está completo vs. o que está faltando
+- Sugira complementos com raciocínio: "Com base em X, sugiro Y porque Z. Está correto?"
+- Agrupe sugestões relacionadas (ex.: todos os indicadores de sucesso juntos)
+
+**Contexto mínimo** (apenas uma ideia):
+- Faça perguntas direcionadas para o TL;DR (O QUÊ / POR QUÊ / COMO)
+- Infira contexto adicional e valide: "A partir das suas respostas, infiro X. Devo incluir isso?"
+
+**Projeto existente**:
+- Leia o código-fonte, documentos e commits recentes primeiro
+- Sugira o TL;DR com base na análise para confirmação
+
+**Funcionalidades mencionadas**:
+- Sugira a lista de FRDs e confirme antes de incluir
+
+---
+
+## Padrões de Qualidade
+
+✅ **Boa sugestão**: Contextual, específica, demonstra entendimento do domínio
+```
+Com base em ser um plugin de sincronização para criadores, sugiro:
+- Confiabilidade de Sincronização: taxa de sucesso de 99,5%
+- Tempo Economizado: redução de 15 min/publicação
+- Adoção: 70% usando 3+ vezes/semana após 30 dias
+
+Esses indicadores estão alinhados com "eliminar o atrito da sincronização manual." Posso usá-los?
+```
+
+❌ **Má sugestão**: Genérica, sem raciocínio
+```
+Quais métricas? A) Engajamento B) Receita C) Outro
+```
+
+---
+
+## Evite
+- Perguntas vazias sem sugestões quando há contexto disponível
+- Perguntar sobre cada pequeno detalhe separadamente
+- Sugestões genéricas que se aplicam a qualquer produto
+- Inventar pesquisas de usuário, dados de concorrentes ou restrições técnicas
+- Criar o documento final antes de o usuário validar as suposições
+- Usar frases e termos como:
+  - "Vamos construir uma solução", "Vamos criar", "Vamos planejar"
+  - Os PRDs descrevem o produto como se ele já existisse, não como se fosse ser construído no futuro
+  - Em vez disso, use: "Esta é uma solução", "Nossa solução", "Nossa abordagem", "Este produto", "Esta funcionalidade"

package/skills/prod-specs/rules/prod-spec-rules.md

@@ -0,0 +1,186 @@
+---
+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.
+
+
+## Diretórios e Variáveis dessa Skill
+
+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:
+
+**Diretório da skill:** `${CLAUDE_SKILL_DIR}`
+
+- `$SKILL_TEMPLATE_FOLDER`: `${CLAUDE_SKILL_DIR}/templates/`
+- `$SKILL_REFERENCES_FOLDER`: `${CLAUDE_SKILL_DIR}/references/`
+
+
+## Perguntas para guiar o usuário
+
+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.
+
+```
+|     | {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)
+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)
+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)
+
+Concentre-se em comportamentos específicos e testáveis com base em designs:
+
+```
+### Fluxo de autenticação
+- Quando o usuário clica no botão "Login" na página inicial, o sistema exibe o modal de login
+- Quando o usuário insere o email no campo email, o sistema valida o formato em tempo real
+- Quando o usuário insere um formato de e-mail inválido, o sistema exibe o erro "Insira um e-mail válido" abaixo do campo
+- Quando o usuário insere a senha e clica em "Enviar", o sistema tenta a autenticação
+- Quando a autenticação é bem-sucedida, o sistema fecha o modal e redireciona para o painel
+- Quando a autenticação falha, o sistema exibe o erro "Credenciais inválidas" acima do formulário
+- Quando o usuário clica no link "Esqueci minha senha", o sistema exibe o modo de redefinição de senha
+
+### Fluxo de redefinição de senha
+- Quando o usuário insere o e-mail no formulário de redefinição e clica em "Enviar link de redefinição", o sistema envia o e-mail de redefinição
+- Quando o sistema envia um e-mail, o sistema exibe a confirmação "Verifique seu e-mail para obter o link de redefinição"
+- Quando o usuário não recebe o e-mail em 1 minuto, o sistema mostra o botão "Reenviar e-mail"
+```
+
+**Observe a diferença:**
+- PRD/Epics: "O sistema deve suportar autenticação" (o quê, por que)
+- Histórias/Tasks: "Quando o usuário clica no botão 'Login'..." (específicas, testáveis, baseadas em design)
+
+**Detalhamento Progressivo**:
+1. **PRD (Porquê)**: "O sistema deve suportar autenticação do usuário para proteger os dados do usuário"
+2. **Épico (O que)**: "Implementar sistema de autenticação com e-mail/senha e login social"
+3. **Issues (Como)**: "Como usuário, posso fazer login com meu e-mail e senha para poder acessar minha conta"
+
+**Principais diferenças**:
+- **PRD**: objetivos de negócios e requisitos de alto nível
+- **É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**: Cada documento deve ser compreensível por si só, sem exigir conhecimento tribal.
+
+**O que isso significa**:
+- Incluir todos os antecedentes necessários
+- Definir abreviações e jargões na primeira utilização
+- Link para documentos relacionados utilizando formato markdown
+- Explique “por que” as decisões foram tomadas
+- Documentar suposições
+- Não presuma que todos estavam na reunião
+
+**Por que é importante**:
+As pessoas juntam-se em equipas, o contexto perde-se, as memórias desaparecem. Documentos independentes garantem que todos possam contribuir, independentemente de quando aderiram.
+
+**Perguntas de validação**:
+- Um novo membro da equipe poderia entender isso?
+- Todas as abreviaturas estão definidas?
+- O “porquê” está explicado?
+- Os documentos relacionados estão vinculados?
+- Isso faria sentido em 6 meses?
+
+**Exemplos**:
+
+✅ **Bom**:
+- "Estamos criando notificações por e-mail porque 73% dos usuários relataram a falta de atualizações importantes (consulte o documento de pesquisa do usuário). Este recurso abordará a reclamação número 1 dos usuários nas pesquisas do terceiro trimestre."
+- "A latência da API (Interface de Programação de Aplicativo) deve ser <200 ms porque nosso SLA (Acordo de Nível de Serviço) se compromete com tempos de resposta inferiores a um segundo."
+
+❌ **Ruim**:
+- "Pela reunião, estamos fazendo notificações"
+- "Porque Bob disse isso"
+- "Todo mundo sabe porque isso é importante"
+- Referências a discussões sem links ou resumos
+- Decisões técnicas inexplicáveis
+
+**Aplicação a Fluxos de Trabalho**:
+- **PRDs**: inclua o contexto do problema, por que agora, iniciativas relacionadas
+- **Planos**: consulte o PRD, explique as decisões de faseamento
+- **Histórias**: Inclui plano de fundo, ajuste-se ao contexto épico
+- **Histórias rápidas**: forneça contexto suficiente para executar sem fazer perguntas
+- **Bugs rápidos**: ambiente do documento, etapas, comportamento esperado
+- **Tarefas rápidas**: explique por que esse trabalho é importante
+
+## Princípio: Terminologia Consistente
+
+**Princípio**: Use os mesmos termos para os mesmos conceitos em toda a documentação.
+
+**O que isso significa**:
+- Escolha um termo e cumpra-o
+- Crie um glossário para os principais conceitos
+- Não use sinônimos para entidades principais
+- Alinhe a terminologia entre PRD → Plano → Histórias
+- Use termos padrão do setor quando aplicável
+
+**Por que é importante**:
+A terminologia inconsistente cria confusão. "Cliente" vs "Usuário" vs "Cliente" - são iguais? Diferente? Ninguém sabe, então todo mundo perde tempo esclarecendo.
+
+**Perguntas de validação**:
+- Estamos usando o mesmo termo que usamos no PRD?
+- Temos vários termos para a mesma coisa?
+- Um novo membro da equipe ficaria confuso?
+- Existe um glossário se os termos forem complexos?
+
+**Exemplos**:
+
+✅ **Bom**:
+- **Consistente**: Sempre use "espaço de trabalho" (às vezes não "espaço", "área", "sala")
+- **Glossário**: "Espaço de trabalho: uma área colaborativa onde os membros da equipe compartilham documentos"
+- **Termos padrão**: use termos do setor como "API", "SaaS", "MRR"
+
+❌ **Ruim**:
+- **Inconsistente**: “espaço de trabalho” no PRD, “espaço” no Plano, “sala” nas histórias
+- **Termos inventados**: "doohickey" em vez do "widget" padrão
+- **Jargão indefinido**: uso de abreviações específicas da empresa sem definição
+
+**Aplicação a Fluxos de Trabalho**:
+- **PRDs**: definir termos-chave no glossário
+- **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

package/skills/prod-specs/templates/prod-breakdown-template.md

@@ -0,0 +1,136 @@
+---
+name: [Name from PRD]  
+team: [Team Name]
+created_at: [YYYY-MM-DD]
+last_updated: [YYYY-MM-DD]  
+---
+
+## Resumo do plano detalhado (breakdown)
+
+{3-4 frases: O que estamos construindo, Por que estamos construindo, como resolveremos isso e o impacto esperado}
+
+---
+
+## Relacionamento com entregas
+
+```
+Versão 1 {Período quando fornecido. Caso contrário, ignore este campo}
+  ├── Epic 1.1 {Data quando fornecida. Caso contrário, ignore este campo}
+  │ ├── História/Tarefa 1.1.1
+  │ └── História/Tarefa 1.1.2
+  └── Epic 1.2 {Data quando fornecida. Caso contrário, ignore este campo}
+      ├── História/Tarefa 1.2.1
+      └── História/Tarefa 1.2.2
+
+Versão 2 {Período quando fornecido. Caso contrário, ignore este campo}
+  ├── Epic 2.1 {Data quando fornecida. Caso contrário, ignore este campo}
+  │ └── História/Tarefa 2.1.1
+  └── Epic 2.2 {Data quando fornecida. Caso contrário, ignore este campo}
+      └── História/Tarefa 2.2.1
+```
+
+{após criar esse relacionamento, pede para validar se o relacionamento está correto. Isso é importante para evitar erros no plano detalhado.}
+
+---
+
+## Lançamentos
+
+### Versão 1: {Nome}
+
+**Meta**: {O que esta versão alcança. Ponto de vista do usuário, sem detalhes técnicos.}  
+**Épicos, histórias e tarefas incluídas nesta versão**:
+- {Nome épico 1.1}
+   - {História 1.1.1}
+   - {História 1.1.2}
+- {Nome épico 1.2}
+   - {História 1.2.1}
+   - {História 1.2.2}
+
+**Dependências**:
+- {escreva uma lista de dependências com base no produto de design e nas lacunas tecnológicas identificadas ou não fornecidas pelo usuário}
+
+**Riscos e preocupações**:
+- {escrever uma lista de riscos com base no design do produto e nas lacunas tecnológicas identificadas ou não fornecidas pelo usuário}
+
+---
+
+#### Épico 1.1: {Nome}
+
+**Resultado entregue**: {O que esta entrega realiza}
+
+**Expectativas do usuário**: {Como usuário, que valor esse épico oferece?}
+
+**Histórias que contam este épico**:
+1. {Título da história 1.1.1}
+2. {Título da história 1.1.2}
+3. {Título da história 1.1.3}
+
+**Critérios de aceitação (nível épico)**:
+- [ ] {Lista de critérios de alto nível. Este critério é usado para validar o épico e criar histórias detalhadas}
+
+**Dias úteis**: {soma dos dias úteis úteis com base na velocidade ou prazo de entrega - se fornecido. Caso contrário, ignore este campo}
+
+---
+
+##### Épico 1.1.2: {Nome épico}
+
+{Mesma estrutura do Epic 1.1.1}
+
+---
+
+### Versão 2: {Nome}
+
+{Mesma estrutura da versão 1}
+
+---
+
+## Dependências e sequenciamento
+
+### Caminho Crítico
+
+```
+Épico 1.1.1
+   ↓
+Épico 1.1.2 ──→ Épico 1.2.1
+                   ↓
+                Épico 2.1.1
+```
+
+### Matriz de Dependência
+{se pedir para criar a matriz de dependência, crie-a. Caso contrário, ignore esta seção}
+
+| Épico | Depende de | Blocos | Estado |
+|------|------------|--------|--------|
+| Épico 1.1.1 | - | Épico 1.1.2 | Não iniciado |
+| Épico 1.1.2 | Épico 1.1.1 | Épico 1.2.1 | Não iniciado |
+| Épico 1.2.1 | Épico 1.1.2 | Épico 2.1.1 | Não iniciado |
+
+### Dependências Externas
+{se pedir para criar as dependências externas, crie-as. Caso contrário, ignore esta seção}
+
+- **{Dependência 1}**: {Descrição}
+- **{Dependência 2}**: {Descrição}
+
+---
+
+## Gestão de Risco
+{se pede para criar o gerenciamento de risco, crie. Caso contrário, ignore esta seção}
+
+### Riscos de alto nível
+
+| Risco | Impacto | Probabilidade | Mitigação | Proprietário | Estado |
+|------|----|------------|------------|-------|--------|
+| [Risco 1] | H/M/L | H/M/L | [Estratégia] | [Nome] | [Estado] |
+| [Risco 2] | H/M/L | H/M/L | [Estratégia] | [Nome] | [Estado] |
+
+### Planos de Contingência
+
+**Se ocorrer [Risco 1]**:
+1. [Ação 1]
+2. [Ação 2]
+3. [Opção substituta]
+
+**Se ocorrer [Risco 2]**:
+1. [Ação 1]
+2. [Ação 2]
+3. [Opção substituta]

package/skills/prod-specs/templates/prod-epic-template.md

@@ -0,0 +1,76 @@
+---
+id: {EPIC-001}
+name: {nome desse épico}
+version: {X.Y.Z - atualizar sempre que houver alteração}
+status: {icebox|in_review|in_progress|in_production|deprecated}
+task_link: {URL referêncial no $TASK_MANAGER - se existir. Se não, ignore essa linha}
+related_prd: {path PRD relacionado, exemplo /master-docs/product/prd-001.md}
+related_frd: {path FRD relacionado, exemplo /master-docs/product/frds/frd-001.md}
+created_at: {YYYY-MM-DD}
+updated_at: {YYYY-MM-DD}
+created_by: {nome de quem criou esse doc}
+last_editor: {nome de quem editou por último}
+---
+
+# {id}: {name}
+
+**Lançamento**: [Nome do lançamento]  
+
+## Contexto
+[Antecedentes: por que esse épico é importante, como ele se encaixa no lançamento, recursos relacionados]
+
+[Que problema do usuário isso resolve?]  
+
+## Critérios de aceitação
+[Critérios de aceitação de alto nível para o épico em formato de marcadores]
+
+## Histórias Relacionadas
+
+Este épico só é considerado concluído quando as histórias relacionadas terminam.
+
+**STORY-001**: [Título da história/tarefa]
+- **História do usuário**: Como [usuário], quero [capacidade], para que [benefício]
+- **Prioridade**: [Alta/Média/Baixa]
+
+**STORY-002**: [Título da história/tarefa]
+[Mesma estrutura]
+
+**STORY-003**: [Título da história/tarefa]
+[Mesma estrutura]
+
+## Considerações Técnicas Gerais
+- [Nota técnica 1]
+- [Nota técnica 2]
+
+## Garantia de Qualidade
+
+**Teste de Unidade**:
+- [Meta de cobertura]
+
+**Teste de integração**:
+- [Escopo]
+- [Linha do tempo]
+
+**Teste de aceitação do usuário**:
+- [Quem]
+- [Quando]
+- [Critérios]
+
+**Teste de desempenho**:
+- [Métricas]
+- [Alvos]
+
+## Definição de Concluído (por história)
+
+- [ ] Código completo e revisado
+- [ ] Testes unitários escritos e aprovados
+- [ ] Testes de integração aprovados
+- [ ] Documentação atualizada
+- [ ] Revisão de projeto aprovada
+- [ ] Proprietário do produto aceito
+- [ ] Implantado no teste
+- [ ] Controle de qualidade assinado
+
+## Assets de design
+- [Link para mockups]
+- [Link para protótipos]