@brunosps00/dev-workflow 0.0.3 → 0.0.5

package/scaffold/pt-br/commands/{run-task.md → dw-run-task.md}

@@ -4,12 +4,30 @@ Você é um assistente IA responsável por implementar tasks de desenvolvimento
 <critical>Você não deve se apressar para finalizar a tarefa. Sempre verifique os arquivos necessários, verifique os testes, faça um processo de reasoning para garantir tanto a compreensão quanto a execução correta.</critical>
 <critical>A TAREFA NÃO PODE SER CONSIDERADA COMPLETA ENQUANTO TODOS OS TESTES NÃO ESTIVEREM PASSANDO</critical>
 
+## Quando Usar
+- Use para executar uma única task do tasks.md de um PRD com validação Nível 1 integrada
+- NÃO use quando precisar executar TODAS as tasks sequencialmente (use `/dw-run-plan` em vez disso)
+- NÃO use para corrigir um bug report (use `/dw-bugfix` em vez disso)
+
+## Posição no Pipeline
+**Antecessor:** `/dw-create-tasks` | **Sucessor:** `/dw-run-task` (próxima task) ou `/dw-review-implementation`
+
+## Skills Complementares
+
+Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como suporte especializado sem substituir este comando:
+
+| Skill | Gatilho |
+|-------|---------|
+| `vercel-react-best-practices` | Task envolve renderização React, hidratação, data fetching, bundle, cache ou performance |
+| `webapp-testing` | Task tem frontend interativo que necessita validação E2E em navegador real |
+| `agent-browser` | Validação de UI requer sessão persistente, inspeção de navegação operacional ou evidência visual complementar |
+
 ## Localização dos Arquivos
 
-- PRD: `ai/spec/prd-[nome-funcionalidade]/prd.md`
-- Tech Spec: `ai/spec/prd-[nome-funcionalidade]/techspec.md`
-- Tasks: `ai/spec/prd-[nome-funcionalidade]/tasks.md`
-- Rules do Projeto: `ai/rules/`
+- PRD: `.dw/spec/prd-[nome-funcionalidade]/prd.md`
+- Tech Spec: `.dw/spec/prd-[nome-funcionalidade]/techspec.md`
+- Tasks: `.dw/spec/prd-[nome-funcionalidade]/tasks.md`
+- Rules do Projeto: `.dw/rules/`
 
 ## Etapas para Executar
 
@@ -27,8 +45,9 @@ Você é um assistente IA responsável por implementar tasks de desenvolvimento
 Analise considerando:
 - Objetivos principais da tarefa
 - Como a tarefa se encaixa no contexto do projeto
-- Alinhamento com regras e padrões do projeto (`ai/rules/`)
+- Alinhamento com regras e padrões do projeto (`.dw/rules/`)
 - Possíveis soluções ou abordagens
+- Se React/Next.js estiver no escopo, incorporar explicitamente heurísticas relevantes do `vercel-react-best-practices`
 
 ### 3. Resumo da Tarefa
 
@@ -58,7 +77,8 @@ Após fornecer o resumo e abordagem, **comece imediatamente** a implementar a ta
 - **Implementar testes unitários** (obrigatório para backend)
 - Seguir padrões estabelecidos do projeto
 - Garantir que todos os requisitos sejam atendidos
-- **Rodar testes** conforme o comando de teste do projeto
+- **Rodar testes**: use o comando de teste do projeto
+- Se houver frontend interativo, valide também o comportamento real com `webapp-testing` ou `agent-browser` quando isso reduzir o risco de regressão invisível nos testes unitários
 
 **VOCÊ DEVE** iniciar a implementação logo após o processo acima.
 
@@ -82,6 +102,10 @@ Para cada critério de aceitação definido na task:
 - Se algum critério não foi atendido: **CORRIJA antes de prosseguir**
 
 ### Execução de Testes
+```bash
+# Rodar testes do projeto impactado
+pnpm test   # ou npm test
+```
 - [ ] Todos os testes passam (existentes + novos)
 - [ ] Novos testes foram criados para código novo
 - Se algum teste falha: **CORRIJA antes de prosseguir**
@@ -90,7 +114,8 @@ Para cada critério de aceitação definido na task:
 - [ ] Tipos explícitos (sem `any`)
 - [ ] Código compila sem erros
 - [ ] Lint passa
-- [ ] Padrões do projeto seguidos (`ai/rules/`)
+- [ ] Multi-tenancy respeitado (se aplicável)
+- [ ] Padrões do projeto seguidos (`.dw/rules/`)
 
 ### Verificação de UI Funcional (para tasks com frontend)
 <critical>Páginas placeholder/stub NÃO são entrega aceitável para RFs de interação do usuário.</critical>

package/scaffold/pt-br/references/playwright-patterns.md

@@ -0,0 +1,133 @@
+# Padrões de Teste Playwright
+
+Referência para `/dw-run-qa` e `/dw-functional-doc`. Padrões E2E comuns.
+
+## 1. Navegação Autenticada
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+test("navegar rota autenticada", async ({ page }) => {
+  // Login
+  await page.goto("/login");
+  await page.getByLabel("Email").fill("user@test.com");
+  await page.getByLabel("Senha").fill("password123");
+  await page.getByRole("button", { name: "Entrar" }).click();
+  
+  // Aguardar redirect
+  await page.waitForURL("/dashboard");
+  await expect(page.getByRole("heading", { name: /dashboard/i })).toBeVisible();
+});
+```
+
+## 2. Submissão de Formulário com Validação
+
+```typescript
+test("submeter formulário com erros de validação", async ({ page }) => {
+  await page.goto("/users/new");
+
+  // Submeter vazio → erros de validação
+  await page.getByRole("button", { name: "Salvar" }).click();
+  await expect(page.getByText("Nome é obrigatório")).toBeVisible();
+  await expect(page.getByText("Email é obrigatório")).toBeVisible();
+
+  // Preencher e submeter → sucesso
+  await page.getByLabel("Nome").fill("Maria Silva");
+  await page.getByLabel("Email").fill("maria@example.com");
+  await page.getByRole("button", { name: "Salvar" }).click();
+  
+  await expect(page.getByText("Usuário criado com sucesso")).toBeVisible();
+});
+```
+
+## 3. Tabela com Filtro e Paginação
+
+```typescript
+test("filtrar e paginar tabela", async ({ page }) => {
+  await page.goto("/users");
+
+  // Verificar carregamento inicial
+  const rows = page.locator("table tbody tr");
+  await expect(rows).toHaveCount(10);
+
+  // Filtrar
+  await page.getByPlaceholder("Buscar...").fill("admin");
+  await expect(rows).toHaveCount(2);
+
+  // Limpar e paginar
+  await page.getByPlaceholder("Buscar...").clear();
+  await page.getByRole("button", { name: "Próxima" }).click();
+  await expect(page.getByText("Página 2")).toBeVisible();
+});
+```
+
+## 4. Interação com Modal / Dialog
+
+```typescript
+test("abrir modal, preencher e confirmar", async ({ page }) => {
+  await page.goto("/projects");
+
+  // Abrir modal
+  await page.getByRole("button", { name: "Novo Projeto" }).click();
+  const dialog = page.getByRole("dialog");
+  await expect(dialog).toBeVisible();
+
+  // Preencher formulário do modal
+  await dialog.getByLabel("Nome do Projeto").fill("Meu Projeto");
+  await dialog.getByRole("button", { name: "Criar" }).click();
+
+  // Modal fecha, item aparece na lista
+  await expect(dialog).not.toBeVisible();
+  await expect(page.getByText("Meu Projeto")).toBeVisible();
+});
+```
+
+## 5. Permissão / Acesso Negado
+
+```typescript
+test("usuário restrito vê acesso negado", async ({ page }) => {
+  // Login como usuário restrito
+  await page.goto("/login");
+  await page.getByLabel("Email").fill("restricted@test.com");
+  await page.getByLabel("Senha").fill("password123");
+  await page.getByRole("button", { name: "Entrar" }).click();
+
+  // Tentar acessar rota admin
+  await page.goto("/admin/settings");
+  
+  // Verificar acesso negado
+  await expect(page.getByText(/acesso negado|proibido|não autorizado/i)).toBeVisible();
+});
+```
+
+## 6. Tratamento de Erro de API
+
+```typescript
+test("trata erro de API graciosamente", async ({ page }) => {
+  // Interceptar API para simular erro
+  await page.route("**/api/users", (route) =>
+    route.fulfill({ status: 500, body: "Internal Server Error" })
+  );
+
+  await page.goto("/users");
+
+  // Verificar estado de erro
+  await expect(page.getByText(/erro|algo deu errado/i)).toBeVisible();
+  
+  // Verificar que botão de retry funciona
+  await page.unroute("**/api/users");
+  await page.getByRole("button", { name: /tentar novamente/i }).click();
+  await expect(page.locator("table tbody tr")).toHaveCount(10);
+});
+```
+
+## Padrão de Captura de Evidência
+
+```typescript
+await test.step("Capturar evidência", async () => {
+  await page.screenshot({ 
+    path: `evidence/screenshots/${testInfo.title}-${Date.now()}.png`, 
+    fullPage: true 
+  });
+});
+```

package/scaffold/pt-br/references/refactoring-catalog.md

@@ -0,0 +1,166 @@
+# Catálogo de Refatoração — Exemplos Antes/Depois
+
+Referência para `/dw-refactoring-analysis`. Baseado no catálogo de Fowler.
+
+## 1. Função Longa → Extract Function
+
+**Smell:** Função com >15 linhas de lógica, múltiplas responsabilidades.
+
+```typescript
+// ❌ ANTES: 30+ linhas fazendo validação, transformação e persistência
+async function processOrder(order: Order) {
+  if (!order.items.length) throw new Error("Empty order");
+  if (order.total < 0) throw new Error("Invalid total");
+  if (!order.customer) throw new Error("No customer");
+  
+  const discount = order.customer.isPremium 
+    ? order.total * 0.1 
+    : order.total > 100 ? order.total * 0.05 : 0;
+  const tax = (order.total - discount) * 0.15;
+  const finalTotal = order.total - discount + tax;
+  
+  order.discount = discount;
+  order.tax = tax;
+  order.total = finalTotal;
+  order.status = "processed";
+  
+  await db.orders.update(order.id, order);
+  await emailService.send(order.customer.email, "Order processed", { order });
+}
+
+// ✅ DEPOIS: Cada função com uma responsabilidade
+async function processOrder(order: Order) {
+  validateOrder(order);
+  const pricing = calculatePricing(order);
+  const processed = applyPricing(order, pricing);
+  await persistOrder(processed);
+  await notifyCustomer(processed);
+}
+```
+
+## 2. Feature Envy → Move Method
+
+**Smell:** Função acessa dados de outro objeto mais que os próprios.
+
+```typescript
+// ❌ ANTES: calculateShipping conhece demais sobre Address
+function calculateShipping(order: Order) {
+  const addr = order.address;
+  if (addr.country === "BR" && addr.state === "SP") return 5.99;
+  if (addr.country === "BR") return 9.99;
+  return 19.99 + (addr.isRemote ? 10 : 0);
+}
+
+// ✅ DEPOIS: Address é dono da lógica de frete
+class Address {
+  getShippingCost(): number {
+    if (this.country === "BR" && this.state === "SP") return 5.99;
+    if (this.country === "BR") return 9.99;
+    return 19.99 + (this.isRemote ? 10 : 0);
+  }
+}
+```
+
+## 3. Obsessão por Primitivos → Value Object
+
+**Smell:** Usar strings/números crus para conceitos do domínio (emails, dinheiro, datas).
+
+```typescript
+// ❌ ANTES: email é apenas uma string em todo lugar
+function sendEmail(to: string, subject: string) {
+  if (!to.includes("@")) throw new Error("Invalid email");
+}
+
+// ✅ DEPOIS: Email é um value object com validação embutida
+class Email {
+  constructor(private readonly value: string) {
+    if (!value.includes("@")) throw new Error("Invalid email");
+  }
+  toString() { return this.value; }
+}
+
+function sendEmail(to: Email, subject: string) { /* ... */ }
+```
+
+## 4. Lógica Duplicada → Extrair Utilitário Compartilhado
+
+**Smell:** Mesmas 3+ linhas de lógica aparecem em múltiplos locais.
+
+```typescript
+// ❌ ANTES: formatação de data repetida em 4 componentes
+const formatted = `${date.getFullYear()}-${String(date.getMonth()+1).padStart(2,"0")}-${String(date.getDate()).padStart(2,"0")}`;
+
+// ✅ DEPOIS: utilitário único
+function formatDate(date: Date): string {
+  return date.toISOString().split("T")[0];
+}
+```
+
+## 5. God Component → Dividir por Responsabilidade
+
+**Smell:** Componente React com 200+ linhas, múltiplos useEffects, responsabilidades misturadas.
+
+```tsx
+// ❌ ANTES: UserDashboard faz fetch, filtragem, renderização e modais
+function UserDashboard() {
+  // 50 linhas de state + effects
+  // 30 linhas de handlers
+  // 120 linhas de JSX com condições inline
+}
+
+// ✅ DEPOIS: container + presentation + hook
+function useUserDashboard() { /* data fetching + state */ }
+function UserFilters({ filters, onChange }) { /* UI de filtros */ }
+function UserTable({ users, onSelect }) { /* UI de tabela */ }
+function UserDashboard() {
+  const { users, filters, setFilters } = useUserDashboard();
+  return (
+    <>
+      <UserFilters filters={filters} onChange={setFilters} />
+      <UserTable users={users} />
+    </>
+  );
+}
+```
+
+## 6. Condicional Complexa → Strategy Pattern / Early Return
+
+**Smell:** Cadeia de if/else aninhados com 4+ branches.
+
+```typescript
+// ❌ ANTES: condicionais aninhadas
+function getPrice(user: User, product: Product) {
+  if (user.type === "premium") {
+    if (product.category === "electronics") {
+      return product.price * 0.8;
+    } else {
+      return product.price * 0.9;
+    }
+  } else if (user.type === "wholesale") {
+    return product.price * 0.7;
+  } else {
+    return product.price;
+  }
+}
+
+// ✅ DEPOIS: mapa de estratégias + early return
+const DISCOUNT_STRATEGIES: Record<string, (p: Product) => number> = {
+  premium: (p) => p.category === "electronics" ? 0.8 : 0.9,
+  wholesale: () => 0.7,
+  standard: () => 1.0,
+};
+
+function getPrice(user: User, product: Product) {
+  const discount = DISCOUNT_STRATEGIES[user.type] ?? DISCOUNT_STRATEGIES.standard;
+  return product.price * discount(product);
+}
+```
+
+## Guia de Priorização
+
+| Severidade | Critério | Ação |
+|------------|----------|------|
+| **P0 - Crítico** | Risco de segurança, corrupção de dados, contrato de API quebrado | Corrigir imediatamente |
+| **P1 - Alto** | >3 duplicações, god objects, código não-testável | Corrigir no sprint atual |
+| **P2 - Médio** | Funções longas, obsessão por primitivos, feature envy | Agendar para refatoração |
+| **P3 - Baixo** | Problemas menores de naming, pequenas duplicações, estilo | Corrigir oportunisticamente |

package/scaffold/pt-br/templates/brainstorm-matrix.md

@@ -0,0 +1,44 @@
+# Brainstorm: {{TOPIC}}
+
+## Contexto
+
+{{CONTEXT_DESCRIPTION}}
+
+## Matriz de Opções
+
+| Critério | Opção A: {{NAME_A}} | Opção B: {{NAME_B}} | Opção C: {{NAME_C}} |
+|----------|---------------------|---------------------|---------------------|
+| **Abordagem** | | | |
+| **Esforço** | Baixo / Médio / Alto | Baixo / Médio / Alto | Baixo / Médio / Alto |
+| **Risco** | Baixo / Médio / Alto | Baixo / Médio / Alto | Baixo / Médio / Alto |
+| **Escalabilidade** | | | |
+| **Manutenibilidade** | | | |
+| **Dependências** | | | |
+
+## Trade-offs
+
+### Opção A: {{NAME_A}}
+- **Prós:** 
+- **Contras:** 
+- **Melhor quando:** 
+
+### Opção B: {{NAME_B}}
+- **Prós:** 
+- **Contras:** 
+- **Melhor quando:** 
+
+### Opção C: {{NAME_C}}
+- **Prós:** 
+- **Contras:** 
+- **Melhor quando:** 
+
+## Recomendação
+
+**Recomendada:** Opção {{X}}
+
+**Justificativa:** {{WHY}}
+
+## Próximos Passos
+
+- [ ] Validar com stakeholders
+- [ ] Criar PRD: `/dw-create-prd`

package/scaffold/pt-br/templates/functional-doc/case-matrix.md

@@ -0,0 +1,5 @@
+# Matriz de Casos
+
+| ID | Funcionalidade | Tipo de caso | Pré-condições | Ações | Resultado esperado | Mensagem esperada | Status | Evidência |
+|----|----------------|--------------|---------------|-------|--------------------|-------------------|--------|-----------|
+{{rows}}

package/scaffold/pt-br/templates/functional-doc/e2e-runbook.md

@@ -0,0 +1,3 @@
+# Roteiro E2E
+
+{{steps}}

package/scaffold/pt-br/templates/functional-doc/features.md

@@ -0,0 +1,3 @@
+# Funcionalidades
+
+{{features}}

package/scaffold/pt-br/templates/functional-doc/overview.md

@@ -0,0 +1,21 @@
+# Dossiê Funcional
+
+- **Projeto:** {{projectName}}
+- **Target:** {{target}}
+- **Tipo:** {{targetType}}
+- **Framework detectado:** {{framework}}
+- **Base URL:** {{baseUrl}}
+- **Runner E2E:** {{playwrightStatus}}
+- **Gerado em:** {{generatedAt}}
+
+## Resumo
+
+{{summary}}
+
+## Fontes analisadas
+
+{{sources}}
+
+## Bloqueios
+
+{{blockers}}

package/scaffold/pt-br/templates/functional-doc/playwright.spec.ts.tpl

@@ -0,0 +1,19 @@
+import { test, expect } from "@playwright/test";
+
+const BASE_URL = process.env.BASE_URL ?? "{{baseUrl}}";
+
+test("{{testTitle}}", async ({ page }) => {
+  const evidence = [] as string[];
+
+  await test.step("Abrir rota alvo", async () => {
+    await page.goto(`${BASE_URL}{{routePath}}`);
+    await expect(page).toHaveURL(new RegExp("{{routeRegex}}"));
+    evidence.push("navigation");
+  });
+
+{{testSteps}}
+
+  await test.step("Registrar contexto final", async () => {
+    expect(evidence.length).toBeGreaterThan(0);
+  });
+});

package/scaffold/pt-br/templates/pr-bugfix-template.md

@@ -0,0 +1,28 @@
+## Resumo
+
+- **Bug:** {{ORIGINAL_PROBLEM}}
+- **Causa raiz:** {{WHY_IT_HAPPENED}}
+- **Solução:** {{WHAT_WAS_FIXED}}
+
+## Mudanças
+
+{{CHANGES_LIST}}
+
+## Evidências de Teste
+
+- **Antes do fix:** {{SCREENSHOT_OR_ERROR_BEFORE}}
+- **Depois do fix:** {{SCREENSHOT_OR_RETEST_PASS}}
+- **Testes unitários relacionados:** {{TEST_LIST}}
+
+## Plano de Teste
+
+- [ ] Testes unitários passando
+- [ ] Build com sucesso
+- [ ] Lint passando
+- [ ] Fix testado manualmente
+- [ ] Verificado que não há regressão em features relacionadas
+
+## Relacionados
+
+- Issue: {{ISSUE_LINK}}
+- Análise do bugfix: `.dw/spec/bugfix-{{NAME}}/prd.md` (se aplicável)

package/scaffold/pt-br/templates/qa-test-credentials.md

@@ -0,0 +1,37 @@
+# Credenciais de Teste QA
+
+## Perfis de Credenciais
+
+| Perfil | Login | Senha | Role | Escopo | Usar Quando |
+|--------|-------|-------|------|--------|-------------|
+| **Admin** | admin@test.com | {{PASSWORD}} | Administrador | Acesso total | Testar fluxos admin, gestão de usuários, configurações |
+| **Usuário Padrão** | user@test.com | {{PASSWORD}} | Usuário | Acesso padrão | Testar happy paths, fluxos principais |
+| **Restrito** | restricted@test.com | {{PASSWORD}} | Visualizador | Somente leitura | Testar bloqueios de permissão, acesso negado |
+| **Multi-tenant A** | tenant-a@test.com | {{PASSWORD}} | Usuário | Tenant A | Testar isolamento de tenant, segregação de dados |
+| **Multi-tenant B** | tenant-b@test.com | {{PASSWORD}} | Usuário | Tenant B | Testar bloqueio de acesso cross-tenant |
+
+## Ordem de Fallback de Senha
+
+Se a senha primária falhar, tente nesta ordem:
+1. `{{PRIMARY_PASSWORD}}`
+2. `{{FALLBACK_1}}`
+3. `{{FALLBACK_2}}`
+
+Se todas falharem, marcar autenticação como **BLOQUEADA** no manifesto.
+
+## Método de Login
+
+- **URL:** {{LOGIN_URL}}
+- **Provedor de autenticação:** {{AUTH_PROVIDER}} (ex: Keycloak, Auth0, NextAuth)
+- **Campo de login:** Email / Usuário / CPF (escolher baseado no provedor)
+- **Observações:** {{NOTES}}
+
+## Guia de Seleção
+
+| Tipo de Bug / Fluxo | Perfil Recomendado | Motivo |
+|---------------------|-------------------|--------|
+| Teste de happy path | Usuário Padrão | Representa uso típico |
+| Teste de permissão negada | Restrito | Valida controle de acesso |
+| Funcionalidades admin | Admin | Acesso total necessário |
+| Isolamento multi-tenant | Tenant A + Tenant B | Testa fronteiras de dados |
+| Fluxo de auth/login | Todos os perfis | Testa cada nível de acesso |

package/scaffold/pt-br/templates/techspec-template.md

@@ -116,7 +116,7 @@ type NomeServico interface {
 
 ### Conformidade com Padrões
 
-[Pesquise as rules em `ai/rules/` que se encaixam nesta techspec e liste-as abaixo:]
+[Pesquise as rules em `.dw/rules/` que se encaixam nesta techspec e liste-as abaixo:]
 
 ### Arquivos Relevantes
 

package/scaffold/rules-readme.md

@@ -4,7 +4,7 @@ This directory contains auto-generated project rules created by the `analyze-pro
 
 ## How to populate
 
-Run the `/analyze-project` command inside your AI assistant to scan your codebase and generate:
+Run the `/dw-analyze-project` command inside your AI assistant to scan your codebase and generate:
 
 - `index.md` — Project overview, stack summary, quick reference
 - `{module}.md` — Per-module detailed rules with patterns and conventions
@@ -12,7 +12,7 @@ Run the `/analyze-project` command inside your AI assistant to scan your codebas
 ## Structure
 
 ```
-ai/rules/
+.dw/rules/
 ├── README.md          # This file
 ├── index.md           # Project overview (auto-generated)
 └── {module}.md        # Per-module rules (auto-generated)
@@ -22,4 +22,4 @@ ai/rules/
 
 These rules are automatically read by workflow commands (`create-prd`, `create-techspec`, `run-task`, etc.) to ensure generated artifacts follow your project's conventions.
 
-Re-run `/analyze-project` whenever your stack or conventions change significantly.
+Re-run `/dw-analyze-project` whenever your stack or conventions change significantly.