@brunosps00/dev-workflow 0.4.2 → 0.4.4

package/lib/constants.js

@@ -1,7 +1,7 @@
 const COMMANDS = {
   en: [
     { name: 'dw-analyze-project', description: 'Analyze repository stack, patterns, and conventions to generate project rules' },
-    { name: 'dw-autopilot', description: 'Full pipeline orchestrator: from a wish to a PR with minimal intervention (research, PRD, tasks, execution, QA, review, commit)' },
+    { name: 'dw-autopilot', description: 'Full pipeline orchestrator from a wish to a PR with minimal intervention (research, PRD, tasks, execution, QA, review, commit)' },
     { name: 'dw-brainstorm', description: 'Explore ideas and directions before starting implementation' },
     { name: 'dw-bugfix', description: 'Analyze and fix bugs with automatic triage (bug vs feature vs scope)' },
     { name: 'dw-code-review', description: 'Formal code review (Level 3) with persisted report' },
@@ -26,7 +26,7 @@ const COMMANDS = {
   ],
   'pt-br': [
     { name: 'dw-analyze-project', description: 'Analisa stack, patterns e convencoes do repositorio para gerar regras do projeto' },
-    { name: 'dw-autopilot', description: 'Orquestrador completo: de um desejo ate o PR com minima intervencao (pesquisa, PRD, tasks, execucao, QA, review, commit)' },
+    { name: 'dw-autopilot', description: 'Orquestrador completo de um desejo ate o PR com minima intervencao (pesquisa, PRD, tasks, execucao, QA, review, commit)' },
     { name: 'dw-brainstorm', description: 'Explorar ideias e direcoes antes de comecar a implementacao' },
     { name: 'dw-bugfix', description: 'Analisar e corrigir bugs com triagem automatica (bug vs feature vs escopo)' },
     { name: 'dw-code-review', description: 'Code review formal (Nivel 3) com relatorio persistido' },
@@ -56,7 +56,7 @@ const PLATFORMS = {
     dir: '.claude/skills',
     wrapperTemplate: (name, description) => `---
 name: ${name}
-description: ${description}
+description: "${description.replace(/"/g, '\\"')}"
 ---
 
 Read and follow ALL instructions in \`.dw/commands/${name}.md\`.
@@ -66,7 +66,7 @@ Read and follow ALL instructions in \`.dw/commands/${name}.md\`.
     dir: '.agents/skills',
     wrapperTemplate: (name, description) => `---
 name: ${name}
-description: ${description}
+description: "${description.replace(/"/g, '\\"')}"
 ---
 <system_instructions>
 Source of truth: \`.dw/commands/${name}.md\`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

package/scaffold/en/commands/dw-autopilot.md

@@ -53,6 +53,7 @@ If this command is invoked to resume an interrupted autopilot (via `/dw-resume`)
 Evaluate whether the topic requires deep research:
 - **YES** (run `/dw-deep-research`): new technology for the project, unknown domain, external API integrations, critical architectural decisions
 - **NO** (skip to step 3): simple feature in an already mapped domain, refactoring existing code, basic CRUD
+  - If skipping, DOCUMENT the reason in the progress block. E.g.: "Research skipped — domain already mapped in .dw/rules/[file].md". The user must see the justification.
 
 If executed, use `standard` mode by default. Incorporate findings into subsequent steps.
 
@@ -60,8 +61,8 @@ If executed, use `standard` mode by default. Incorporate findings into subsequen
 
 Run `/dw-brainstorm` with accumulated context (intel + research).
 - Generate 3 directions
-- Automatically converge on the most pragmatic option for the project context
-- Do NOT wait for user approval (brainstorm is automatic in autopilot)
+- Present the 3 directions to the user with your recommendation highlighted and justified
+- Wait for user confirmation on which direction to follow before proceeding
 
 ### Step 4: PRD (Interactive — 7+ Questions)
 
@@ -72,6 +73,7 @@ Run `/dw-create-prd` using brainstorm findings.
 - Ask at least 7 questions about: problem, target users, critical features, scope, constraints, design, integration
 - In each question, present a recommendation grounded in brainstorm and deep-research findings (if executed). E.g.: "Based on the research, I recommend X because [evidence]. Do you agree or prefer a different direction?"
 - Wait for user responses to each question
+- This step is BLOCKING — the command STOPS until a response is received from the user for EACH question. If the user does not respond, do NOT proceed. Do NOT assume answers based on context.
 - Only after receiving all responses, write the complete PRD in `.dw/spec/prd-[name]/prd.md`
 
 ### === GATE 1: PRD Approval ===
@@ -92,6 +94,7 @@ Run `/dw-create-techspec` from the approved PRD.
 - Ask at least 7 questions about: preferred architecture, existing vs new libs, testing strategy, integration with existing systems, infrastructure constraints, performance, security
 - In each question, present a technical recommendation grounded in brainstorm, deep-research, and approved PRD findings. E.g.: "Research indicated lib X has better performance for this case [source]. Want to use X or have another preference?"
 - Wait for user responses to each question
+- This step is BLOCKING — the command STOPS until a response is received from the user for EACH question. If the user does not respond, do NOT proceed. Do NOT assume answers based on context.
 - Only after receiving all responses, generate in `.dw/spec/prd-[name]/techspec.md`
 
 ### Step 6: Tasks
@@ -114,7 +117,7 @@ Present to the user:
 Evaluate whether tasks involve frontend:
 - **YES** (run `/dw-redesign-ui`): if there are tasks with visual components AND the `ui-ux-pro-max` skill is available
   - Generate the design contract in `.dw/spec/prd-[name]/design-contract.md`
-  - Do NOT wait for approval (contract is automatic in autopilot, based on PRD requirements)
+  - Present a summary of the design contract to the user (palette, typography, mobile/desktop layout) as a visual checkpoint before proceeding
 - **NO** (skip to step 8): purely backend/infra tasks
 
 ### Step 8: Execution
@@ -150,7 +153,7 @@ Run `/dw-run-qa` with Playwright MCP.
 
 If QA found bugs:
 - Run `/dw-fix-qa` to fix and retest
-- Loop until stable
+- Loop until stable (maximum 5 cycles). After 5 cycles, STOP and ask the user how to proceed.
 
 ### Step 12: Implementation Review (Post-QA)
 
@@ -219,6 +222,8 @@ Save the file `.dw/spec/prd-[name]/autopilot-state.json` with the following form
 - If the session drops, `/dw-resume` will read this file and continue from the correct step
 - When the pipeline finishes (after commit or PR), remove the file or mark `"status": "completed"`
 
+<critical>After EACH completed step, display the updated progress block to the user. This is MANDATORY — the user MUST see what was done and what comes next. If a step was skipped, the reason MUST appear in the progress block.</critical>
+
 ## Progress Format
 
 During execution, report progress in this format:

package/scaffold/en/commands/dw-redesign-ui.md

@@ -4,6 +4,7 @@ You are a frontend redesign specialist for the current workspace. This command e
 <critical>Do NOT redesign without first auditing the current implementation. Always read the code and capture the visual state before proposing changes.</critical>
 <critical>ALWAYS propose design directions and wait for user approval before implementing any changes.</critical>
 <critical>Preserve existing functionality. Redesign is visual/UX, not behavioral. If the change alters behavior, redirect to `/dw-create-prd`.</critical>
+<critical>MOBILE FIRST is MANDATORY. Every design proposal MUST include both mobile AND desktop versions. Implementation MUST start with mobile and then adapt for desktop. Do NOT present only the desktop layout — if the proposal does not show how it looks on mobile, it is incomplete.</critical>
 
 ## When to Use
 - Use for rebuild/modernization of existing pages or components
@@ -57,10 +58,10 @@ Use diagnostic tools based on the project's framework:
 1. Identify the target: page, component, or route to be redesigned.
 2. **AUDIT**: read the current implementation, identify the CSS stack (Tailwind, CSS Modules, styled-components, etc.), capture screenshot if `webapp-testing` is available, run react-doctor if React project.
 3. Ask 3 to 5 questions about redesign goals: style direction, brand constraints, inspirations, target audience, priority devices.
-4. **PROPOSE**: present 2 to 3 design directions using `ui-ux-pro-max` — each with color palette, typography pairing, layout style, and rationale.
+4. **PROPOSE**: present 2 to 3 design directions using `ui-ux-pro-max` — each with color palette, typography pairing, layout style, and rationale. For EACH direction, explicitly describe the mobile layout (<=768px) and desktop layout (>=1024px), including how elements reorganize, stack, or hide between breakpoints.
 5. Wait for explicit user approval before implementing.
-6. **IMPLEMENT**: apply the chosen design respecting the existing stack. Use `vercel-react-best-practices` for React/Next.js. Maintain the project's CSS methodology.
-7. **VALIDATE**: capture after-state, compare before/after, verify accessibility (WCAG 2.2 via `ui-ux-pro-max`), run react-doctor `--diff` if React.
+6. **IMPLEMENT**: apply the chosen design with a mobile-first approach — implement the mobile layout first, then add media queries/breakpoints for tablet and desktop. Respect the existing stack. Use `vercel-react-best-practices` for React/Next.js. Maintain the project's CSS methodology.
+7. **VALIDATE**: capture after-state in BOTH resolutions (mobile and desktop), compare before/after, verify accessibility (WCAG 2.2 via `ui-ux-pro-max`), run react-doctor `--diff` if React. If `webapp-testing` is available, capture screenshots at 375px viewport (mobile) and 1440px viewport (desktop).
 8. **PERSIST CONTRACT**: if the user approved a direction, generate `design-contract.md` in the PRD directory (`.dw/spec/prd-[name]/design-contract.md`) with: approved direction, color palette, typography pairing, layout rules, accessibility rules, and component rules. This contract will be read by `dw-run-task` and `dw-run-plan` to ensure visual consistency.
 
 ## GSD Integration
@@ -107,7 +108,8 @@ If GSD is NOT installed:
 - Prefer incremental changes that can be reviewed visually
 - When in doubt about style direction, ask — don't assume
 - If the page has no tests, flag regression risk before changing
-- Mobile responsiveness is mandatory unless explicitly scoped out by the user
+- Mobile-first is the default — implement mobile first, adapt for desktop after
+- Validate at least 2 breakpoints: mobile (375px) and desktop (1440px)
 - In Angular projects, respect Angular component patterns (style encapsulation, ViewEncapsulation)
 
 ## Useful Outputs

package/scaffold/en/commands/dw-run-qa.md

@@ -222,7 +222,20 @@ Use `browser_snapshot` to verify labels and semantic structure.
 - Capture screenshots of main screens with `browser_take_screenshot` and save to `{{PRD_PATH}}/QA/screenshots/`
 - Check layouts in different states (empty, with data, error, loading)
 - Document visual inconsistencies found
-- Check responsiveness if applicable (different viewports)
+
+### 6.1. Mobile Validation (Required)
+
+<critical>ALL visual checks MUST include tests at mobile viewport (375px) IN ADDITION to desktop (1440px). QA approval REQUIRES that BOTH resolutions are functional and visually acceptable. If the mobile layout is broken, unusable, or visually degraded, QA CANNOT be approved.</critical>
+
+- Capture screenshots at 375px viewport (mobile) for EACH tested screen
+- Capture screenshots at 1440px viewport (desktop) for comparison
+- Verify: elements do not overlap, text is readable, buttons are tappable (min 44x44px), no horizontal scroll, forms are usable
+- Save screenshots with suffix: `[screen]-mobile.png` and `[screen]-desktop.png`
+
+If mobile FAILS visual validation:
+- Document issues in `{{PRD_PATH}}/QA/bugs.md` with severity **High** and tag `[MOBILE]`
+- In the final report, recommend `/dw-redesign-ui` as the next step to fix the mobile layout with a mobile-first approach
+- QA CANNOT be approved with broken mobile
 
 ### 7. Bug Documentation (If issues found)
 

package/scaffold/pt-br/commands/dw-autopilot.md

@@ -53,6 +53,7 @@ Se este comando for invocado para retomar um autopilot interrompido (via `/dw-re
 Avalie se o topico necessita de pesquisa profunda:
 - **SIM** (execute `/dw-deep-research`): tecnologia nova para o projeto, dominio desconhecido, integracoes com APIs externas, decisoes arquiteturais criticas
 - **NAO** (pule para etapa 3): feature simples no dominio ja mapeado, refatoracao de algo existente, CRUD basico
+  - Se pular, DOCUMENTE o motivo no bloco de progresso. Ex: "Pesquisa pulada — dominio ja mapeado em .dw/rules/[arquivo].md". O usuario deve ver a justificativa.
 
 Se executar, use modo `standard` por padrao. Incorpore os findings nas etapas seguintes.
 
@@ -60,8 +61,8 @@ Se executar, use modo `standard` por padrao. Incorpore os findings nas etapas se
 
 Execute `/dw-brainstorm` com o contexto acumulado (intel + pesquisa).
 - Gere 3 direcoes
-- Convirja automaticamente na opcao mais pragmatica para o contexto do projeto
-- NAO aguarde aprovacao do usuario (brainstorm e automatico no autopilot)
+- Apresente as 3 direcoes ao usuario com sua recomendacao destacada e justificativa
+- Aguarde confirmacao do usuario sobre qual direcao seguir antes de prosseguir
 
 ### Etapa 4: PRD (Interativo — 7+ Perguntas)
 
@@ -72,6 +73,7 @@ Execute `/dw-create-prd` usando os findings do brainstorm.
 - Faca pelo menos 7 perguntas ao usuario sobre: problema, usuarios-alvo, funcionalidades criticas, escopo, restricoes, design, integracao
 - Em cada pergunta, apresente uma recomendacao embasada nos findings do brainstorm e do deep-research (se executado). Ex: "Com base na pesquisa, recomendo X porque [evidencia]. Concorda ou prefere outra direcao?"
 - Aguarde as respostas do usuario para cada pergunta
+- Este passo e BLOQUEANTE — o comando PARA ate receber resposta do usuario para CADA pergunta. Se o usuario nao responder, NAO prossiga. NAO assuma respostas com base no contexto.
 - So apos receber todas as respostas, redija o PRD completo em `.dw/spec/prd-[nome]/prd.md`
 
 ### ═══ GATE 1: Aprovacao do PRD ═══
@@ -92,6 +94,7 @@ Execute `/dw-create-techspec` a partir do PRD aprovado.
 - Faca pelo menos 7 perguntas ao usuario sobre: arquitetura preferida, libs existentes vs novas, estrategia de testes, integracao com sistemas existentes, restricoes de infraestrutura, performance, seguranca
 - Em cada pergunta, apresente uma recomendacao tecnica embasada nos findings do brainstorm, deep-research e PRD aprovado. Ex: "A pesquisa indicou que a lib X tem melhor performance para este caso [fonte]. Quer usar X ou tem outra preferencia?"
 - Aguarde as respostas do usuario para cada pergunta
+- Este passo e BLOQUEANTE — o comando PARA ate receber resposta do usuario para CADA pergunta. Se o usuario nao responder, NAO prossiga. NAO assuma respostas com base no contexto.
 - So apos receber todas as respostas, gere em `.dw/spec/prd-[nome]/techspec.md`
 
 ### Etapa 6: Tasks
@@ -114,7 +117,7 @@ Apresente ao usuario:
 Avalie se as tasks envolvem frontend:
 - **SIM** (execute `/dw-redesign-ui`): se houver tasks com componentes visuais E a skill `ui-ux-pro-max` estiver disponivel
   - Gere o design contract em `.dw/spec/prd-[nome]/design-contract.md`
-  - NAO aguarde aprovacao (o contract e automatico no autopilot, baseado nos requisitos do PRD)
+  - Apresente um resumo do design contract ao usuario (paleta, tipografia, layout mobile/desktop) como checkpoint visual antes de prosseguir
 - **NAO** (pule para etapa 8): tasks puramente backend/infra
 
 ### Etapa 8: Execucao
@@ -150,7 +153,7 @@ Execute `/dw-run-qa` com Playwright MCP.
 
 Se o QA encontrou bugs:
 - Execute `/dw-fix-qa` para corrigir e retestar
-- Loop ate estabilizar
+- Loop ate estabilizar (maximo 5 ciclos). Apos 5 ciclos, PARE e pergunte ao usuario como deseja prosseguir.
 
 ### Etapa 12: Review de Implementacao (Pos-QA)
 
@@ -219,6 +222,8 @@ Salve o arquivo `.dw/spec/prd-[nome]/autopilot-state.json` com o seguinte format
 - Se a sessao cair, o `/dw-resume` lera este arquivo e continuara da etapa correta
 - Ao finalizar o pipeline (apos commit ou PR), remova o arquivo ou marque `"status": "completed"`
 
+<critical>Apos CADA etapa completada, exiba o bloco de progresso atualizado ao usuario. Isso e OBRIGATORIO — o usuario DEVE ver o que foi feito e o que vem a seguir. Se uma etapa foi pulada, o motivo DEVE aparecer no bloco de progresso.</critical>
+
 ## Formato de Progresso
 
 Durante a execucao, reporte progresso no formato:

package/scaffold/pt-br/commands/dw-redesign-ui.md

@@ -4,6 +4,7 @@ Você é um especialista em redesign de frontend para o workspace atual. Este co
 <critical>NÃO redesenhe sem antes auditar a implementação atual. Sempre leia o código e capture o estado visual antes de propor mudanças.</critical>
 <critical>SEMPRE proponha direções de design e espere aprovação do usuário antes de implementar qualquer mudança.</critical>
 <critical>Preserve a funcionalidade existente. Redesign é visual/UX, não comportamental. Se a mudança alterar comportamento, redirecione para `/dw-create-prd`.</critical>
+<critical>MOBILE FIRST é OBRIGATÓRIO. Toda proposta de design DEVE incluir versão mobile E desktop. A implementação DEVE começar pelo mobile e depois adaptar para desktop. NÃO apresente apenas o layout desktop — se a proposta não mostrar como fica no mobile, está incompleta.</critical>
 
 ## Quando Usar
 - Use para rebuild/modernização visual de páginas ou componentes existentes
@@ -57,10 +58,10 @@ Utilize ferramentas de diagnóstico conforme o framework do projeto:
 1. Identifique o alvo: página, componente ou rota que será redesenhada.
 2. **AUDITAR**: leia a implementação atual, identifique stack CSS (Tailwind, CSS Modules, styled-components, etc.), capture screenshot se `webapp-testing` disponível, rode react-doctor se projeto React.
 3. Faça 3 a 5 perguntas sobre objetivos do redesign: direção de estilo, constraints de marca, inspirações, público-alvo, dispositivos prioritários.
-4. **PROPOR**: apresente 2 a 3 direções de design usando `ui-ux-pro-max` — cada uma com paleta de cores, par tipográfico, estilo de layout e racional.
+4. **PROPOR**: apresente 2 a 3 direções de design usando `ui-ux-pro-max` — cada uma com paleta de cores, par tipográfico, estilo de layout e racional. Para CADA direção, descreva explicitamente o layout mobile (<=768px) e o layout desktop (>=1024px), incluindo como os elementos se reorganizam, empilham ou escondem entre breakpoints.
 5. Espere aprovação explícita do usuário antes de implementar.
-6. **IMPLEMENTAR**: aplique o design escolhido respeitando a stack existente. Use `vercel-react-best-practices` para React/Next.js. Mantenha a metodologia CSS do projeto.
-7. **VALIDAR**: capture estado depois, compare antes/depois, verifique acessibilidade (WCAG 2.2 via `ui-ux-pro-max`), rode react-doctor `--diff` se React.
+6. **IMPLEMENTAR**: aplique o design escolhido com abordagem mobile-first — implemente primeiro o layout mobile e depois adicione media queries/breakpoints para tablet e desktop. Respeite a stack existente. Use `vercel-react-best-practices` para React/Next.js. Mantenha a metodologia CSS do projeto.
+7. **VALIDAR**: capture estado depois em AMBAS as resoluções (mobile e desktop), compare antes/depois, verifique acessibilidade (WCAG 2.2 via `ui-ux-pro-max`), rode react-doctor `--diff` se React. Se `webapp-testing` disponível, capture screenshots em viewport 375px (mobile) e 1440px (desktop).
 8. **PERSISTIR CONTRATO**: se o usuário aprovou uma direção, gere `design-contract.md` no diretório do PRD (`.dw/spec/prd-[nome]/design-contract.md`) com: direção aprovada, paleta de cores, par tipográfico, regras de layout, regras de acessibilidade e regras de componentes. Este contrato será lido por `dw-run-task` e `dw-run-plan` para garantir consistência visual.
 
 ## Integração GSD
@@ -107,7 +108,8 @@ Se o GSD NÃO estiver instalado:
 - Prefira mudanças incrementais que possam ser revisadas visualmente
 - Quando em dúvida sobre direção de estilo, pergunte — não assuma
 - Se a página não tem testes, sinalize risco de regressão antes de alterar
-- Responsividade mobile é mandatória salvo escopo explícito do usuário
+- Mobile-first é o padrão — implemente mobile primeiro, adapte para desktop depois
+- Valide em pelo menos 2 breakpoints: mobile (375px) e desktop (1440px)
 - Em projetos Angular, respeite os padrões de componentes do Angular (encapsulação de estilos, ViewEncapsulation)
 
 ## Saídas Úteis

package/scaffold/pt-br/commands/dw-run-qa.md

@@ -222,7 +222,20 @@ Use `browser_snapshot` para verificar labels e estrutura semântica.
 - Capturar screenshots das telas principais com `browser_take_screenshot` e salvar em `{{PRD_PATH}}/QA/screenshots/`
 - Verificar layouts em diferentes estados (vazio, com dados, erro, loading)
 - Documentar inconsistências visuais encontradas
-- Verificar responsividade se aplicável (diferentes viewports)
+
+### 6.1. Validação Mobile (Obrigatório)
+
+<critical>TODA verificação visual DEVE incluir testes em viewport mobile (375px) ALÉM do desktop (1440px). A aprovação do QA REQUER que AMBAS as resoluções estejam funcionais e visualmente aceitáveis. Se o layout mobile estiver quebrado, inutilizável ou visualmente degradado, o QA NÃO pode ser aprovado.</critical>
+
+- Capture screenshots em viewport 375px (mobile) para CADA tela testada
+- Capture screenshots em viewport 1440px (desktop) para comparação
+- Verifique: elementos não se sobrepõem, texto é legível, botões são clicáveis (min 44x44px), scroll horizontal não existe, formulários são usáveis
+- Salve screenshots com sufixo: `[tela]-mobile.png` e `[tela]-desktop.png`
+
+Se o mobile FALHAR na validação visual:
+- Documente os problemas em `{{PRD_PATH}}/QA/bugs.md` com severidade **Alta** e tag `[MOBILE]`
+- No relatório final, recomende `/dw-redesign-ui` como próximo passo para corrigir o layout mobile com abordagem mobile-first
+- O QA NÃO pode ser aprovado com mobile quebrado
 
 ### 7. Documentação de Bugs (Se encontrar problemas)