jarvis-ai-framework 1.0.0

package/workflows/product/prod.spec.issue.md

@@ -0,0 +1,145 @@
+---
+name: prod.spec.issue
+description: Criar um especificação de issues como Histórias de Usuário, Tarefas técnicas e bugs, seguindo as melhores práticas de gestão de produto e projeto.
+auto_execution_mode: 3
+env_file: "@/ENV.md"
+recommended_model: gpt-4o
+model_tier: medium
+model_justification: Criação de issues é estruturada e segue templates, requer boa compreensão mas não raciocínio extremamente complexo
+---
+
+# Fluxo de Criação de Issues
+
+Antes de iniciar, revise o arquivo de regras invioláveis em `$PROD_RULES/**/*.*`.
+
+Este fluxo orienta você na criação de issues (histórias de usuários, tarefas, bugs etc) bem definidas usando o template `$PROD_TEMPLATES/prod-issue-template.md`. Cada issue deve ser uma unidade de trabalho autocontida que pode ser completada dentro de uma única sprint.
+
+Uma issue é a menor unidade de trabalho que pode ser feita. Ela deve entregar valor sozinha. Ela precisa ser o menor tamanho possível para entregar rápido e com qualidade, mas não pode ser tão pequena que não entrega valor percebido para o usuário ou para o produto.
+
+Um grupo de histórias de um mesmo assunto podem formar um épico.
+
+## Quando Usar
+- Ao decompor épicos em histórias de usuário implementáveis
+- Criar tarefas técnicas
+- Criar requisitos não funcionais
+- Documentar e rastrear bugs
+- Quando você precisa capturar trabalho que não requer documentação completa de PRD
+- Para qualquer item de trabalho que precisa ser rastreado em uma sprint ou que necessita ser feita no projeto
+- Para criar ou modificar novas funcionalidades, jornadas, ações de usuário e outras modificações dentro do projeto
+
+## Pré-requisitos
+- Entendimento claro do trabalho a ser feito. Leia a PRD, épicos, histórias criadas anteriormente para entender o contexto a ser feito.
+- Entenda também últimos commits do projeto e outras alterações que possam ter sido feitas em sessões anteriores
+- Se não houver uma PRD ou épico relacionado, sugira para o usuário a criação do épico ou da PRD, mas é totalmente opcional
+- Referências de design (para histórias de usuário)
+- Quaisquer restrições técnicas ou requisitos relevantes
+
+## Resultado Final
+- Siga a estrutura exata do template `$PROD_TEMPLATES/prod-issue-template.md`
+- Convenção de nomenclatura: `{issue_type}-{id}-{issue_name}.md` (ex: story-123-fluxo-lembrar-senha.md)
+- O idioma do arquivo deve corresponder ao idioma de interação do usuário
+- Se o usuário não tiver um título claro, crie um título baseado no conteúdo do arquivo e no contexto do épico
+- Uma História ou Task pode ou não ter subtasks. Sugira as subtasks que são as menores partes da issue para guiar o PM ou o Dev na criação dessas histórias ou tasks.
+- Se o usuário pedir para salver no Jira, procure no arquivo ENV.md se há o link do board e projeto Jira e salve o projeto no board correto. 
+  - Se você não encontrar as informações do board ou projeto correto do Jira, não faça nada, pergunte para o usuário quais são as informações corretas necessárias para você executar essa tarefa.
+
+## Estrutura da Issue
+
+### 1. Título e Metadados
+- **Título**: Título claro e orientado à ação (ex: "Implementar Formulário de Login do Usuário")
+- **PRD Relacionada**: Link para a PRD pai, se aplicável
+- **Épico Relacionado**: Link para o épico pai, se aplicável
+- **Tipo**: História/Tarefa/Bug
+- **Prioridade**: Alta/Média/Baixa
+
+### 2. Contexto
+
+Deve descrever o contexto do problema ou funcionalidade a ser implementada:
+- Informações de contexto
+- Valor de negócio
+- Como se encaixa no panorama maior
+- Qualquer pesquisa de usuário ou dados relevantes
+
+Para resumir a ação final que deve ser feita, use o formato abaixo:
+```
+**Como** [papel do usuário]  
+**Eu quero** [objetivo]  
+**Para que** [benefício/valor]
+```
+
+#### Assets de Design
+- Links para mockups/wireframes
+- Referências do design system
+- Links de protótipos
+
+Se usuário não tiver fornecido os links ou os assets de design, questione se podemos avançar sem eles. Se ele aprover, continue. Se ele entregar os assets, liste-os no template. Se ele enviar imagens, utilize-as como referência, entendendo os principais pontos e fluxos descritos no design.
+
+### 3. Critérios de Aceitação
+- Siga o formato do template
+- Agrupe critérios relacionados sob subtítulos claros
+- Inclua todos os cenários possíveis e casos extremos
+- Seja específico sobre elementos de UI e comportamento
+- Inclua estados de erro e validações
+
+Exemplo:
+```
+#### Fluxo de Autenticação
+- Quando o usuário clicar no botão "Login" na página inicial, o sistema exibe modal de login
+- Quando o usuário inserir formato de email inválido, o sistema exibe mensagem de erro abaixo do campo
+- Quando a autenticação falhar, o sistema mostra mensagem de erro específica
+- Após login bem-sucedido, o sistema redireciona para o dashboard do usuário
+```
+
+### 4. Requisitos Técnicos
+Nesse bloco, você deve ser explicito sobre como serão organizados os requisitos técnicos e defuncionamento. Utilize FRD para descrever os requisitos técnicos.
+- Orientações de implementação (sugestões, não requisitos)
+- Considerações de performance
+- Requisitos de segurança
+- Requisitos de dados
+- Dependências
+
+### 5. Casos Extremos e Tratamento de Erros
+- Liste potenciais casos extremos
+- Defina como o sistema deve lidar com cada caso
+- Inclua mensagens de erro amigáveis ao usuário
+
+### 6. Fora do Escopo
+- Declare claramente o que não está incluído
+- Referencie melhorias futuras se necessário
+
+## Melhores Práticas
+
+### Para Histórias de Usuário
+- Foque nas necessidades do usuário, não na implementação
+- Deixe as histórias descritivas para que agentes de IA possam construir as features corretas
+- Torne-as independentes e negociáveis. As histórias devem entregar valor para o usuário ou para o produto en suas entregas.
+- Elas devem ser o menor tamanho possível para entregar rápido e com qualidade, mas não pode ser tão pequena que não entrega valor percebido para o usuário ou para o produto.
+- Garanta que sejam valiosas para os usuários
+
+### Para Tarefas
+- Seja específico sobre o que precisa ser feito
+- Inclua critérios de sucesso
+- Anote quaisquer dependências
+- Estime o esforço se possível
+- Torne-as independentes e negociáveis
+- Elas devem ser o menor tamanho possível para entregar rápido e com qualidade, mas não pode ser tão pequena que não entrega valor percebido para o usuário ou para o produto.
+
+### Para Bugs
+- Inclua passos para reproduzir
+- Peça para o usuário se ele tem evidências como vídeos ou imagens para adicionar na história. Se ele enviar, coloque o link no arquivo final, e salve os arquivos em `<project-path>/docs/master-docs/assets/`
+- Documente comportamento esperado vs. real
+- Pergunte detalhes do ambiente, erros no console, mensagens de erro do próprio produto
+- Solicite informações de identificação do cliente, o fluxo que ele seguiu para reproduzir o erro, e quaisquer outros detalhes que possam ajudar a reproduzir o erro
+
+## Armadilhas Comuns
+- Critérios de aceitação vagos ou incompletos
+- Casos extremos faltando
+- Descrições excessivamente técnicas
+- Falta de critérios claros de sucesso
+- Não vincular ao trabalho relacionado
+
+## Pontos de Integração
+- **PRDs**: Devemos atualizar a PRD com as modificações feitas nas FRDs, sem abordar o micro, mas alterações de alto nível.
+- **FRDs**: Devemos atualizar a FRD com as modificações feitas nas issues, sem abordar o micro, mas alterações de alto nível.
+- **Épicos**: Issues como Histórias ou Tasks devem se encaixar no escopo do épico
+- **Código**: Devem referenciar ID da issue nos commits

package/workflows/product/prod.spec.md

@@ -0,0 +1,60 @@
+---
+name: prod.spec
+description: Guia o usuário para construir especificações macro ou micro de produto, como PRDs, histórias, tarefas, RFDs e outros.
+auto_execution_mode: 3
+env_file: "@/ENV.md"
+recommended_model: claude-sonnet-4-20250514
+model_tier: medium
+model_justification: Especificações de produto requerem compreensão de requisitos e estruturação de documentos
+---
+
+# Iniciar uma especificação
+
+Estas instruções ajudam a orientar o usuário que deseja começar a construir uma especificação. Esta especificação pode variar desde um PRD, história de usuário até tarefas. Devemos orientá-lo nessa construção de forma que a especificação, seja ela macro ou micro seja criada de acordo com as instruções e padrões do projeto.
+
+## Quando usar
+- Esse comando serve para unificar a criação de todos os tipos de especificações do projeto.
+- Ao iniciar uma nova especificação de projeto ou modificar um PRD existente
+- Quando não souber qual tipo de especificação criar
+- Quando precisar criar novas ou editar FRDs
+- Quando precisar criar novos ou editar épicos, issues, tasks, stories e bugs
+- Quando precisar de orientação sobre o tipo de documentação a ser gerada
+
+## Instruções
+
+- **Sessões de produto**: rascunhos WIP em `$SESSIONS_DIR/prod/{TASK_MANAGER_KEY}/`. A spec canônica fica em `$PROD_DOCS` (não substituir).
+- **Regras do projeto**: Sempre revise os arquivos de regras invioláveis em `$PROD_RULES/**/*.*`.
+- **Projeto existente ou novo**: entenda se o projeto é novo ou se já é um projeto em andamento, que tenha uma base de código já construída.
+  - Procure no diretório por documentações já existentes, como PRDs, FRDs, ARDs, issues, etc. Procure na pasta toda, mas comece procurando em `$PROD_DOCS`.
+  - Verifique se já há código disponível no projeto, analisando também se existe um respositório git disponível. Se existir, analise os últimos 5 pushs feitos para entender as mudanças recentes.
+  - Se for um projeto existente, mas sem documentação:
+    - Confirme com o usuário que esse é um projeto existente, mas que você não encontrou documentação, e sugira iniciar a criação de uma PRD inicial para o projeto. Se usuário quiser criar PRD, siga as instruções em `$PROD_FLOWS/prod.spec.prd.md`
+  - Se for um projeto existente, e já tem documentação, mas está espalhada ou não na estrutura como esperada por esse framework:
+    - Confirme com o usuário que você encontrou documentação existente, mas que ela não está na estrutura esperada por esse framework.
+    - Então, sugira ao usuário que organize a documentação existente em uma estrutura adequada para esse framework. E que que você pode fazer isso para ele seguindo o modelo e estrutura desse framework.
+  - Se for um novo projeto:
+    - Avance para iniciar a PRD do projeto com as instruções em `$PROD_FLOWS/prod.spec.prd.md`
+  - Se for um projeto existente, que já tem uma estrutura `$PROD_DOCS`:
+    - Pergunte para o usuário qual documentação ele deseja criar:
+      - PRD
+      - FRD
+      - ARD
+      - Issue (story, task ou bug)
+- **Uso adequado dos comandos e instruções**: 
+  - Para PRD use as instruções em `$PROD_FLOWS/prod.spec.prd.md`
+  - Para FRD use as instruções em `$PROD_FLOWS/prod.spec.frd.md`
+  - Para ARD use as instruções em `$PROD_FLOWS/prod.spec.ard.md`
+  - Para Issue use as instruções em `$PROD_FLOWS/prod.spec.issue.md`
+  - Para clarificar e revisar qualquer tipo de especificação, use as instruções em `$PROD_FLOWS/prod.spec.clarify.md`
+  - Para quebrar uma especificação grande em fatias (versões / épicos / histórias), use `$PROD_FLOWS/prod.spec.breakdown.md`
+  - Para criar épicos, use as instruções em `$PROD_FLOWS/prod.spec.epic.md`
+- **Idioma**: Mantenha o mesmo idioma da interação com o usuário, sendo que o idioma padrão é português brasileiro
+- **Faça suposições informadas**: Use o contexto, padrões de mercado e padrões comuns para preencher os gaps que a documentação ou a falta de informação não estiver cobrindo
+- **Não seja verboso**: Evite fazer muitas perguntas para o usuário ao criar ou atualizar uma especificação. Seja direto e objetivo. Se perguntar, faça perguntas estratégicas e suficientes para que o usuário dê informações relevantes para a criação ou modificação com eficácia.
+- **Perguntas para direcionar o usuário**: Use perguntas estratégicas para entender o escopo, objetivo e contexto da especificação que o usuário deseja criar ou modificar:
+- Se o usuário fornecer informações junto com a resposta da questão, utilize-as para enriquecer o seu contexto.
+- Sempre faça perguntas em mensagens distintas, para não complicar o fluxo de conversa. 
+- Só faça as perguntas necessárias para entender o contexto e o escopo do produto. 
+- Evite fazer perguntas redundantes ou que não agreguem valor à especificação. 
+- Se o usuário não responder uma pergunta, não repita a mesma pergunta novamente, mas continue com o fluxo com as informações disponíveis. 
+- Se o usuário responder com uma resposta que não se encaixa nas opções, pergunte novamente de forma clara e objetiva, mas guarde a informação que ele forneceu.

package/workflows/product/prod.spec.prd.md

@@ -0,0 +1,100 @@
+---
+name: prod.spec.prd
+description: Alterar ou criar um especificação de produto PRD - Product Requirement Document seguindo o template especificado, regras invioláveis, possibilitando a utilização por agentes de IA e humanos.
+auto_execution_mode: 3
+env_file: "@/ENV.md"
+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
+
+Este comando tem como objetivo criar, atualizar ou editar uma PRD seguindo o template especificado e as instruções.
+
+Antes de iniciar, revise o arquivo de regras invioláveis em `$PROD_RULES/**/*`. Se você não estiver familiarizado com essa variável, leia as regras diretamente na pasta `.$IDE/rules/product/**/*.*`.
+
+Utilize o `$ARGUMENTS` que o usuário passar como ponto de partida e para entender o contexto do que foi pedido.
+<requirement>
+#$ARGUMENTS
+</requirement>
+
+## Skills que devem ser usadas
+
+Utilize a Skill tool para executar as skills necessárias:
+
+- **Para gerar ou modificar especificações de produto** use a Skill tool para executar a skill `prod-specs` para gerar o output final de acordo com os padrões estabelecidos;
+
+## Busca no Central Docs (condicional)
+
+Se `CENTRAL_DOCS_REPO` definido no ENV.md:
+
+1. **Para iteração de PRD existente:**
+   - Executar busca automática no central-docs:
+     ```bash
+     jarvis docs sync --silent
+     ```
+   - Buscar PRD relacionado usando:
+     - Nome/contexto do PRD fornecido pelo usuário
+     - Jira ID (se disponível)
+     - Tags semânticas
+   - Se PRD encontrado no central-docs:
+     - Carregar automaticamente como base para iteração
+     - Informar ao usuário: "✅ PRD encontrado no central-docs: [nome]"
+     - Usar como contexto para a skill `prod-specs`
+   - Se não encontrado:
+     - Perguntar ao usuário se tem PRD localmente
+     - Continuar com fluxo normal
+
+2. **Para PRD novo:**
+   - Pular busca no central-docs
+   - Continuar com criação normal
+
+## Instruções
+
+- Se o usuário forneceu ou está atuando em um projeto existente, priorize obter informações sobre o projeto a partir de:
+  - **Central-docs** (se configurado) - busca automática de PRDs existentes
+  - Documentação existente (README, docs/, PRDs, FRDs, ARDs, etc.)
+  - Commits recentes para entender o que está sendo desenvolvido
+  - Arquivos de AI como CLAUDE.md e AGENTS.md para obter informações estruturadas sobre o contexto do projeto/produto.
+- Para fazer perguntas para o usuário, tente usar o tool `AskUserQuestion` se ele estiver disponível no seu ambiente
+- Use a Skill tool para executar a skill `prod-specs` para gerar o output final de acordo com os padrões estabelecidos, enviando as informações que encontrou como contexto
+- Quando receber output disponibilizado pela skill, mostre para o usuário o resultado final para a aprovação e validação.
+- Quando confirmado e validado pelo usuário:
+  - Se o usuário estiver modificando ou atualizando uma spec existente, salve o arquivo modificado
+  - Se for uma spec nova:
+    - Salve na pasta `$PROD_DOCS` seguindo todos os padrões de nomenclatura e estrutura de pastas já estabelecidos em `$PROD_RULES/**/*`
+
+## Publicação no Central Docs (condicional)
+
+Após salvar o PRD localmente e obter aprovação do usuário:
+
+1. Se `CENTRAL_DOCS_REPO` definido no ENV.md:
+   - Perguntar ao usuário:
+     ```
+     Deseja publicar este PRD no repositório central de documentação?
+     - ( ) Sim, publicar agora
+     - ( ) Não, vou publicar depois manualmente
+     ```
+
+2. Se **Sim**:
+   - Extrair o slug do nome do arquivo (ex: `prd-wallet.md` → `wallet`)
+   - Executar:
+     ```bash
+     jarvis docs publish \
+       --file {caminho_do_prd} \
+       --tipo prd \
+       --feature {slug}
+     ```
+
+3. Informar resultado:
+   - ✅ Sucesso: "PRD publicado no central-docs. MR criado: [URL]"
+   - ❌ Erro: Exibir mensagem de erro e orientar troubleshooting
+
+4. Se **Não**:
+   - Informar: "Para publicar depois, execute: `jarvis docs publish --file {caminho} --tipo prd --feature {slug}`"
+
+5. Se `CENTRAL_DOCS_REPO` não estiver definido:
+   - Informar: "Para habilitar publicação automática, configure `CENTRAL_DOCS_REPO` no ENV.md"
+
+> **Nota**: A publicação cria um Merge Request no GitLab. O PRD só será visível no central-docs após aprovação e merge do MR.
+

package/workflows/taxonomy.md

@@ -0,0 +1,92 @@
+---
+description: Gerencia o arquivo taxonomy.md de forma segura (CRUD de opções organizacionais)
+---
+
+# taxonomy
+
+Gerencia o arquivo `taxonomy.md` que define as opções válidas para SQUAD, HUB, POSITION e AREA.
+
+## Uso
+
+Este command invoca o skill `taxonomy-manager` para operações CRUD seguras:
+
+### Listar opções
+
+```bash
+/taxonomy list SQUADS
+/taxonomy list HUBS
+/taxonomy list POSITIONS
+/taxonomy list AREAS
+```
+
+### Adicionar nova opção
+
+```bash
+/taxonomy add SQUADS MOBILE "Time focado em desenvolvimento mobile nativo"
+/taxonomy add HUBS DEVOPS "DevOps e infraestrutura"
+/taxonomy add POSITIONS PRINCIPAL "Principal Engineer"
+```
+
+### Atualizar descrição
+
+```bash
+/taxonomy update SQUADS CORE "Nova descrição do time"
+```
+
+### Remover opção
+
+```bash
+/taxonomy remove SQUADS MOBILE
+```
+
+### Validar estrutura
+
+```bash
+/taxonomy validate
+```
+
+## Sintaxe
+
+```
+Skill("taxonomy-manager", "$ARGUMENTS")
+```
+
+Onde `$ARGUMENTS` é um dos formatos:
+- `list <CATEGORIA>`
+- `add <CATEGORIA> <NOME> <DESCRIÇÃO>`
+- `update <CATEGORIA> <NOME> <NOVA_DESCRIÇÃO>`
+- `remove <CATEGORIA> <NOME>`
+- `validate`
+
+## Exemplos
+
+### Adicionar novo squad
+```
+/taxonomy add SQUADS DATA "Time de Data Science e Analytics"
+```
+
+### Listar todas as positions
+```
+/taxonomy list POSITIONS
+```
+
+### Remover hub obsoleto
+```
+/taxonomy remove HUBS LEGACY
+```
+
+## Segurança
+
+✅ Backup automático antes de modificações
+✅ Validação de formato (MAIÚSCULAS, sem espaços)
+✅ Confirmação para ações destrutivas
+✅ Preservação da estrutura markdown
+
+## Após Modificações
+
+Depois de adicionar/remover opções:
+1. Execute `/init-jarvis` - as novas opções aparecem automaticamente
+2. Não é necessário reiniciar o Claude ou a IDE
+3. Projetos existentes continuam funcionando
+
+> **Documentação completa**: Ver `.claude/skills/taxonomy-manager/SKILL.md`