@brunosps00/dev-workflow 0.0.7 → 0.1.1

package/bin/dev-workflow.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const { run } = require('../lib/init');
+const installDeps = require('../lib/install-deps');
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -19,13 +20,15 @@ const HELP_TEXT = `
   Usage:
     npx dev-workflow init [--force] [--lang=en|pt-br]
     npx dev-workflow update [--lang=en|pt-br]
+    npx dev-workflow install-deps
     npx dev-workflow help
 
   Commands:
-    init      Scaffold .dw/ (commands, templates, references, scripts, skills, rules, MCPs)
-    update    Update managed files (commands, templates, references, scripts, skills, wrappers, MCPs)
-              Preserves: .dw/rules/, .dw/spec/, user data
-    help      Show this help message
+    init           Scaffold .dw/ (commands, templates, references, scripts, skills, rules, MCPs)
+    update         Update managed files (commands, templates, references, scripts, skills, wrappers, MCPs)
+                   Preserves: .dw/rules/, .dw/spec/, user data
+    install-deps   Install system dependencies (Playwright browsers, MCP servers)
+    help           Show this help message
 
   Options:
     --force        Overwrite existing files (init only; update always overwrites managed files)
@@ -37,6 +40,7 @@ const HELP_TEXT = `
     npx dev-workflow init --lang=pt-br     # Portuguese, no prompt
     npx dev-workflow init --force          # Overwrite existing files
     npx dev-workflow update --lang=en      # Update all managed files to latest version
+    npx dev-workflow install-deps          # Install Playwright browsers and MCP servers
 `;
 
 async function main() {
@@ -47,6 +51,9 @@ async function main() {
     case 'update':
       await run({ force: !!flags.force, lang: flags.lang, mode: 'update' });
       break;
+    case 'install-deps':
+      installDeps.run();
+      break;
     case 'help':
     case '--help':
     case '-h':

package/lib/install-deps.js

@@ -0,0 +1,42 @@
+const { execSync } = require('child_process');
+
+function run() {
+  console.log('\n  dev-workflow install-deps');
+  console.log(`  ${'='.repeat(40)}\n`);
+
+  const deps = [
+    {
+      name: 'Playwright browsers',
+      check: 'npx playwright --version',
+      install: 'npx playwright install --with-deps',
+    },
+    {
+      name: 'Context7 MCP',
+      check: null,
+      install: 'npx -y @upstash/context7-mcp --help',
+    },
+  ];
+
+  let installed = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  for (const dep of deps) {
+    process.stdout.write(`  Installing ${dep.name}...`);
+    try {
+      execSync(dep.install, { stdio: 'pipe', timeout: 300000 });
+      console.log(' \x1b[32m✓\x1b[0m');
+      installed++;
+    } catch (err) {
+      console.log(' \x1b[31m✗\x1b[0m');
+      console.log(`    Error: ${err.message.split('\n')[0]}`);
+      failed++;
+    }
+  }
+
+  console.log(`\n  ${'='.repeat(40)}`);
+  console.log(`  Done! ${installed} installed, ${skipped} skipped, ${failed} failed`);
+  console.log();
+}
+
+module.exports = { run };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "0.0.7",
+  "version": "0.1.1",
   "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-bugfix.md

@@ -16,7 +16,6 @@
     When available in the project at `./.agents/skills/`, use these skills as contextual support without replacing this command:
 
     - `vercel-react-best-practices`: use when the bug affects React/Next.js and there is suspicion of render, hydration, fetching, waterfall, bundle, or re-render issues
-    - `agent-browser`: use when the bug requires reproduction in a real browser, persistent session, request inspection, or visual capture
     - `webapp-testing`: use when the fix requires a reproducible E2E/retest flow in a web app
     - `security-review`: use when the root cause touches auth, authorization, external input, upload, secrets, SQL, XSS, SSRF, or other sensitive surfaces
 
@@ -158,7 +157,7 @@
     - Related error messages
     - Stack traces
     - Recently modified files
-    - If the bug is UI-related or depends on browser flow, supplement collection with `agent-browser` or `webapp-testing`
+    - If the bug is UI-related or depends on browser flow, supplement collection with `webapp-testing`
 
     ### 3. Clarification Questions (MANDATORY - EXACTLY 3)
 
@@ -196,7 +195,7 @@
     - **Probable Cause**: Based on the evidence
     - **Affected Files**: List of files to modify
     - **Impact**: Other components that may be affected
-    - **Skills used**: explicitly record if the analysis used `vercel-react-best-practices`, `agent-browser`, `webapp-testing`, or `security-review`
+    - **Skills used**: explicitly record if the analysis used `vercel-react-best-practices`, `webapp-testing`, or `security-review`
 
     ### 4.1 Scope Checkpoint (MANDATORY)
 

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

@@ -17,7 +17,6 @@ You are an AI assistant specialized in post-QA bug fixing with evidence-driven r
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
 
-- `agent-browser`: support for reproducing bugs with persistent sessions, capturing network data, additional screenshots, and validating fixes browser-first
 - `webapp-testing`: support for structuring retests, captures, and scripts when complementary to Playwright MCP
 - `vercel-react-best-practices`: use only if the fix affects React/Next.js frontend and there is risk of rendering, hydration, fetching, or performance regression
 
@@ -87,7 +86,7 @@ For each fixed bug:
    - `QA/logs/console-retest.log`
    - `QA/logs/network-retest.log`
 7. Record in the QA report which user/profile was used in the retest
-8. If the retest requires persistent auth, request inspection beyond MCP, or more faithful real-browser reproduction, complement with `agent-browser` and record this in the report
+8. If the retest requires persistent auth, request inspection beyond MCP, or more faithful real-browser reproduction, record this in the report
 
 ### 4. Update Artifacts
 

package/scaffold/en/commands/dw-functional-doc.md

@@ -37,6 +37,12 @@ Works best with project analyzed by `/dw-analyze-project`
 <critical>Header and footer of human videos must not compete for useful area with the browser stage. When they exist, they must be outside the browser stage, in a larger composition, preserving the real application viewport intact.</critical>
 <critical>When the goal is a human tour with centered browser, keep the application in a central stage without fixed side columns, preserving header and footer at full width outside the browser area.</critical>
 <critical>Browser visual quality is a mandatory requirement. Do not deliver a human tour with viewport or recording downscaled relative to the final resolution. The runner must align viewport and video capture to the final resolution or record an explicit blocker.</critical>
+<critical>Hardcoded subtitles over the product screen are not an acceptable standard when the environment supports a dedicated shell. The preferred and mandatory standard is: `header` at the top with the tour title, `stage` centered for the intact browser, and `footer` at the bottom exclusively for the narrative caption.</critical>
+<critical>Even when the human video is assembled from screenshots rather than recorded navigation, the final composition must maintain the same shell layout: header and footer outside the application area. Do not deliver a fullscreen slideshow with subtitles burned directly over the product content.</critical>
+<critical>In the main human video artifact, the caption must be visible inside the shell's `footer`. A sidecar `.srt` file and an embedded subtitle track may exist as support, but they do not replace the obligation for the main narrative to already appear correctly positioned in the footer of the final composition.</critical>
+<critical>It is invalid to deliver as the main version an MP4 whose caption depends on the player for positioning (`mov_text`, `tx3g`, or similar subtitle track) when this causes the text to appear outside the shell's footer. If there is an auxiliary embedded track, visually validate that the main version remains correct even without the player rendering subtitles.</critical>
+<critical>When the request involves human video with captions, always generate two video artifacts: a `clean` version without captions rendered in the frame, for use with player + sidecar `.srt`; and a `captioned` version with the narrative already burned correctly in the shell's `footer`.</critical>
+<critical>If a previous flow in the workspace already has a better-resolved human recording shell, reuse that visual and structural pattern before improvising a new composition. This reuse is preferable to a simplified solution with captions embedded over the viewport.</critical>
 
 ### Video Pacing Requirements
 <critical>Before and after main actions, insert intentional pauses. As an operational rule: maintain 2 to 3 seconds of permanence on relevant loaded states and at least 1.5 seconds after the visible outcome of each main action before proceeding.</critical>
@@ -49,7 +55,6 @@ Works best with project analyzed by `/dw-analyze-project`
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command as source of truth:
 
-- `agent-browser`: support for real navigation, request inspection, screenshots, persistent auth, and browser-first reproduction
 - `webapp-testing`: support for structuring E2E flows, local retests, and evidence collection
 - `remotion-best-practices`: mandatory support when there is a final human video, captions, composition, transitions, FFmpeg, or Remotion
 - `humanizer`: mandatory support for reviewing and naturalizing all captions, `.srt` files, descriptive texts, and any human-facing writing before final delivery
@@ -119,6 +124,9 @@ If there is execution:
 If there is a final human video:
 - save in `evidence/videos/` with a name that clearly differentiates the final tour from the raw capture
 - when `ffmpeg` is available, also save the `mp4` version of the final human tour
+- when captions are involved, save two explicit variants:
+  - a `clean` version without captions drawn in the frame
+  - a `captioned` version with captions drawn in the shell's `footer`
 - record in `manifest.json` which files are `raw` and which are `human_final`
 
 ## Required Flow
@@ -224,6 +232,11 @@ Generate `e2e-runbook.md` in detailed operational style:
   - when there is a title and caption, reserve header and footer outside the browser stage
   - when the composition calls for a centered browser, keep the application in a central stage without fixed side columns and without sacrificing full-width header and footer
   - avoid any artificial reduction of the app viewport to fit overlays
+  - avoid burned subtitles directly inside the product viewport when there is a possibility of using an external shell
+  - burn the main narrative in the shell's `footer` of the final video; use sidecar `.srt` and embedded track only as complementary artifacts
+  - for each final tour with captions, produce:
+    - `clean`: no captions in the frame, with separate `.srt` for the player to decide
+    - `captioned`: captions already positioned in the shell's `footer`
   - align video capture to final resolution to avoid sharpness loss in the browser
   - keep each relevant state on screen long enough for visual reading, especially lists, dialogs, badges, validations, messages, and final results
   - keep captions on screen long enough for comfortable reading, without switching text before the corresponding step is visually understood
@@ -246,6 +259,28 @@ When producing or reviewing the final tour, apply these rules as baseline:
 - when comparing before and after states, clearly show both moments
 - if the recording is too fast for human reading, consider the execution inadequate even if technically correct
 - if `ffmpeg` is installed, consider incomplete any delivery that leaves only `webm` or another raw format without generating `mp4`
+- consider inadequate any video that uses only overlaid captions on the browser when the project supports a shell with dedicated header/footer
+- consider inadequate any video whose main caption depends on the player's renderer and therefore appears outside the shell's intended `footer`
+- consider incomplete any delivery that provides only one of the variants (`clean` or `captioned`) when the flow requires video with captions
+
+## Mandatory Visual Shell Standard
+
+When there is a final human video, adopt as minimum visual standard:
+
+- `header` fixed outside the browser with the module or flow name
+- `main` centering a single browser `stage`
+- `footer` fixed outside the browser, reserved for narrative caption or short context
+- `stage` with its own border, radius, and shadow, without cropping the application viewport
+- `stage` width and height explicitly defined and proportional to the final resolution
+
+Baseline recommended for `1920x1080` when no better standard exists in the flow itself:
+
+- `header`: ~`64px`
+- `footer`: ~`112px`
+- `stage`: ~`1600x900`
+
+If a previous flow in the workspace already has a working shell script (e.g., `record-human-tour.cjs`), reuse it as reference. If choosing a different layout, justify explicitly in `manifest.json`.
+
 - Update `manifest.json` with final status, artifacts, and blockers, distinguishing:
   - MCP evidence
   - raw execution capture

package/scaffold/en/commands/dw-review-implementation.md

@@ -7,7 +7,7 @@ You are a specialized implementation reviewer that compares documented requireme
 - Do NOT use when requirements have not been finalized yet
 
 ## Pipeline Position
-**Predecessor:** `/dw-run-plan` (auto) or `/dw-run-task` (manual) | **Successor:** `/dw-code-review`
+**Predecessor:** `/dw-run-plan` (auto) or `/dw-run-task` (manual) | **Successor:** `/dw-code-review` (auto-fixes gaps before completing)
 
 Called by: `/dw-run-plan` at end of all tasks
 
@@ -175,35 +175,82 @@ Check if the implementation follows project patterns:
 2. [secondary action]
 ```
 
-### 8. Post-Report Decision (Required)
+### 8. Gap Resolution Loop (Required)
 
-After generating the final report, evaluate the result:
+<critical>Review does NOT end at the first report. If gaps are found, enter an automatic fix-review loop until 100% compliance or explicit BLOCK.</critical>
+
+After generating the report, evaluate:
 
-**If there are NO gaps (0 pending, 0 partial, 100% implemented):**
-- Present the report to the user
-- **DO NOT enter planning mode (EnterPlanMode)**
-- **DO NOT dispatch execution agents (Task)**
-- **DO NOT create tasks (TaskCreate)**
-- **DO NOT propose implementing anything**
-- Simply conclude with: "Implementation 100% compliant. No action needed."
-- END the review immediately
-
-**If there ARE gaps (pending > 0 OR partial > 0):**
-- Present the report with gaps and recommendations
-- List actions needed to resolve each gap
-- Wait for user instructions on how to proceed
-- **DO NOT enter planning mode automatically**
-- **DO NOT execute fixes without explicit user instruction**
-
-**Compliance Check Decision Flow:**
 ```dot
-digraph compliance {
-  "Analysis Complete" -> "0 gaps AND 0 partial?";
-  "0 gaps AND 0 partial?" -> "Report + EXIT" [label="yes"];
-  "0 gaps AND 0 partial?" -> "Report + List Actions\nWAIT for user" [label="no"];
+digraph review_loop {
+  rankdir=TB;
+  "Generate Review Report" -> "Gaps found?";
+  "Gaps found?" -> "100% Compliant\nExit" [label="no"];
+  "Gaps found?" -> "Fix gaps\n(implement missing code)" [label="yes"];
+  "Fix gaps\n(implement missing code)" -> "Re-review\nimplementation";
+  "Re-review\nimplementation" -> "Still gaps?";
+  "Still gaps?" -> "100% Compliant\nExit" [label="no"];
+  "Still gaps?" -> "Max cycles\nreached?" [label="yes"];
+  "Max cycles\nreached?" -> "Fix gaps\n(implement missing code)" [label="no"];
+  "Max cycles\nreached?" -> "BLOCKED\nReport residual gaps" [label="yes (3 cycles)"];
 }
 ```
 
+**Loop rules:**
+1. After the initial report, if there are gaps (❌ not implemented or ⚠️ partial), enter the loop automatically
+2. For each cycle:
+   a. Fix all identified gaps: implement missing code, complete partial implementations
+   b. Follow project patterns from `.dw/rules/` during fixes
+   c. Run tests after fixes (`pnpm test` or equivalent)
+   d. Re-read the changed files and re-compare against PRD requirements
+   e. Update the review report with cycle results
+   f. If 100% compliance → exit loop, present final report
+   g. If gaps remain → continue next cycle
+3. **Maximum 3 fix-review cycles.** After 3 cycles, mark review as **BLOCKED** with residual gaps documented
+4. Each cycle must append a section to the report showing what was fixed and the new compliance status
+5. Commit fixes after each cycle: `fix(review): implement [requirement] from PRD`
+
+**What to fix automatically:**
+- ❌ Requirements not implemented → implement them
+- ⚠️ Requirements partially implemented → complete them
+- 📝 Tasks marked complete but actually incomplete → finish them
+
+**What NOT to fix (stop and ask user):**
+- Requirements that contradict each other in the PRD
+- Requirements that need architectural decisions not covered in TechSpec
+- Requirements that depend on external services not available
+- If a fix would take more than the scope of a single task
+
+**Cycle report format (append to review report):**
+```markdown
+## Fix Cycle [N] — [YYYY-MM-DD]
+
+### Gaps Resolved
+| RF | Description | Action Taken | Status |
+|----|-------------|-------------|--------|
+| RF-XX | [requirement] | [what was implemented] | ✅ |
+
+### Tests
+- `pnpm test`: PASS/FAIL
+- Files changed: [list]
+
+### Remaining Gaps
+- [list or "None"]
+
+### Cycle Result: CONTINUE / COMPLIANT / BLOCKED
+```
+
+**If 100% compliant after any cycle:**
+- Present the final report
+- **DO NOT enter planning mode (EnterPlanMode)**
+- **DO NOT create tasks (TaskCreate)**
+- Conclude with: "Implementation 100% compliant after [N] fix cycles. No further action needed."
+
+**If BLOCKED after 3 cycles:**
+- Present the report with residual gaps
+- List what could not be resolved and why
+- Wait for user instructions
+
 ## Status Levels
 
 | Icon | Meaning |
@@ -255,4 +302,5 @@ git diff <commit> -- path/to/file
 <critical>DO NOT APPROVE requirements without concrete evidence in the code</critical>
 <critical>ANALYZE the actual code, do not trust only the checkboxes in tasks.md</critical>
 <critical>If 100% of requirements were implemented and there are NO gaps: DO NOT enter plan mode, DO NOT create tasks, DO NOT dispatch agents. Just present the report and END.</critical>
+<critical>If gaps are found, enter the fix-review loop automatically. Do NOT wait for user instructions to fix gaps. Maximum 3 cycles before marking as BLOCKED.</critical>
 </system_instructions>

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

@@ -7,7 +7,7 @@ You are an AI assistant specialized in Quality Assurance. Your task is to valida
 - Do NOT use when requirements have not been defined yet (create PRD first)
 
 ## Pipeline Position
-**Predecessor:** `/dw-run-plan` or `/dw-run-task` | **Successor:** `/dw-fix-qa` (if bugs) or `/dw-code-review`
+**Predecessor:** `/dw-run-plan` or `/dw-run-task` | **Successor:** `/dw-code-review` (auto-fixes bugs internally before completing)
 
 <critical>Use the Playwright MCP to execute all E2E tests</critical>
 <critical>Verify ALL requirements from the PRD and TechSpec before approving</critical>
@@ -20,7 +20,6 @@ You are an AI assistant specialized in Quality Assurance. Your task is to valida
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
 
-- `agent-browser`: support for operational navigation, persistent auth, additional screenshots, request inspection, and session debugging
 - `webapp-testing`: support for structuring test flows, retests, screenshots, and logs when complementary to Playwright MCP
 - `vercel-react-best-practices`: use only if the frontend under test is React/Next.js and there is indication of regression related to rendering, fetching, hydration, or perceived performance
 
@@ -96,7 +95,7 @@ Refer to `.dw/rules/` for project-specific URLs and frameworks.
 - Verify the application is running on localhost
 - Use `browser_navigate` from Playwright MCP to access the application
 - Confirm the page loaded correctly with `browser_snapshot`
-- If persistent session, auth import, network inspection beyond MCP, or browser-first reproduction is needed, complement with `agent-browser`
+- If persistent session, auth import, or network inspection beyond MCP is needed, complement with `webapp-testing`
 
 ### 3. Menu Page Verification (Required -- Execute BEFORE RF tests)
 
@@ -163,7 +162,7 @@ For each functional requirement from the PRD:
 8. Mark as PASSED or FAILED
 9. Save the Playwright flow script in `{{PRD_PATH}}/QA/scripts/` with standardized name: `RF-XX-[slug].spec.ts` (or `.js`)
 10. Record in the report which credentials (user/profile) were used in each permission-sensitive flow
-11. When the MCP flow becomes unstable or insufficient for operational evidence, complement with `agent-browser` or `webapp-testing`, recording this explicitly in the report
+11. When the MCP flow becomes unstable or insufficient for operational evidence, complement with `webapp-testing`, recording this explicitly in the report
 
 <critical>It is not enough to validate only the happy path. Each requirement must be exercised against its boundary states and most likely regressions</critical>
 <critical>If a requirement cannot be fully validated via E2E, QA must be marked as REJECTED or BLOCKED, never APPROVED</critical>
@@ -272,6 +271,62 @@ Generate report in `{{PRD_PATH}}/QA/qa-report.md`:
 [Final QA assessment]
 ```
 
+### 9. QA Fix-Retest Loop (Automatic)
+
+<critical>QA does NOT end at the first report. If bugs are found, enter an automatic fix-retest loop until QA is APPROVED or explicitly BLOCKED.</critical>
+
+After generating the initial QA report:
+
+```dot
+digraph qa_loop {
+  rankdir=TB;
+  "Generate QA Report" -> "Bugs found?";
+  "Bugs found?" -> "QA APPROVED\nExit" [label="no"];
+  "Bugs found?" -> "Fix bugs\n(follow dw-fix-qa rules)" [label="yes"];
+  "Fix bugs\n(follow dw-fix-qa rules)" -> "Retest ALL\nfixed bugs";
+  "Retest ALL\nfixed bugs" -> "New/reopened\nbugs?";
+  "New/reopened\nbugs?" -> "QA APPROVED\nExit" [label="no"];
+  "New/reopened\nbugs?" -> "Max cycles\nreached?" [label="yes"];
+  "Max cycles\nreached?" -> "Fix bugs\n(follow dw-fix-qa rules)" [label="no"];
+  "Max cycles\nreached?" -> "QA BLOCKED\nReport residual bugs" [label="yes (5 cycles)"];
+}
+```
+
+**Loop rules:**
+1. After the initial report, if `QA/bugs.md` has bugs with `Status: Open`, enter the loop automatically
+2. For each cycle:
+   a. Fix all open bugs surgically (same rules as `/dw-fix-qa`: no scope creep, minimal impact)
+   b. Retest ALL fixed bugs via Playwright MCP with evidence capture
+   c. Check for regressions introduced by the fixes
+   d. Update `QA/bugs.md` and `QA/qa-report.md` with the cycle results
+   e. If all critical/high bugs are closed → **QA APPROVED**, exit loop
+   f. If new bugs appeared or fixes failed → continue next cycle
+3. **Maximum 5 fix-retest cycles.** After 5 cycles, mark QA as **BLOCKED** with residual bugs documented
+4. Each cycle must update the QA report with a "Cycle N" section showing what was fixed, retested, and the result
+5. Commit fixes after each successful cycle: `fix(qa): resolve BUG-NN [description]`
+
+**Cycle report format (append to qa-report.md):**
+```markdown
+## Fix-Retest Cycle [N] — [YYYY-MM-DD]
+
+### Bugs Fixed
+| Bug | Fix Description | Retest | Evidence |
+|-----|----------------|--------|----------|
+| BUG-01 | [what was changed] | PASS/FAIL | `QA/screenshots/BUG-01-cycle-N.png` |
+
+### Regressions Checked
+- [list of related flows retested]
+
+### Cycle Result
+- **Bugs remaining:** [count]
+- **Status:** CONTINUE / APPROVED / BLOCKED
+```
+
+**Red flags — STOP the loop:**
+- Fix requires a new feature (not a bug) → stop, recommend `/dw-create-prd`
+- Fix requires major refactoring → stop, recommend `/dw-refactoring-analysis`
+- Same bug keeps reappearing after 2+ fix attempts → mark as BLOCKED with root cause analysis
+
 ## Quality Checklist
 
 - [ ] PRD analyzed and requirements extracted

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

@@ -20,7 +20,6 @@ When available in the project at `./.agents/skills/`, use these skills as specia
 |-------|---------|
 | `vercel-react-best-practices` | Task touches React rendering, hydration, data fetching, bundle, cache, or performance |
 | `webapp-testing` | Task has interactive frontend needing E2E validation in a real browser |
-| `agent-browser` | UI validation requires persistent session, operational navigation inspection, or complementary visual evidence |
 
 ## File Locations
 
@@ -78,7 +77,7 @@ After providing the summary and approach, **begin implementation immediately**:
 - Follow established project patterns
 - Ensure all requirements are met
 - **Run tests**: use the project's test command
-- If there is interactive frontend, also validate real behavior with `webapp-testing` or `agent-browser` when doing so reduces the risk of invisible regression in unit tests
+- If there is interactive frontend, also validate real behavior with `webapp-testing` when doing so reduces the risk of invisible regression in unit tests
 
 **YOU MUST** start the implementation right after the process above.
 

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

@@ -16,7 +16,6 @@
     Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como suporte contextual sem substituir este comando:
 
     - `vercel-react-best-practices`: use quando o bug afeta React/Next.js e há suspeita de problemas de render, hidratação, fetching, waterfall, bundle ou re-render
-    - `agent-browser`: use quando o bug requer reprodução em navegador real, sessão persistente, inspeção de requests ou captura visual
     - `webapp-testing`: use quando a correção requer fluxo E2E/reteste reproduzível em uma web app
     - `security-review`: use quando a causa raiz toca auth, autorização, input externo, upload, secrets, SQL, XSS, SSRF ou outras superfícies sensíveis
 
@@ -152,7 +151,7 @@
     - Mensagens de erro relacionadas
     - Stack traces
     - Arquivos modificados recentemente
-    - Se o bug for relacionado a UI ou depender de fluxo no navegador, complemente a coleta com `agent-browser` ou `webapp-testing`
+    - Se o bug for relacionado a UI ou depender de fluxo no navegador, complemente a coleta com `webapp-testing`
 
     ### 3. Perguntas de Clarificação (OBRIGATÓRIO - EXATAMENTE 3)
 
@@ -179,7 +178,7 @@
     - **Causa Provável**: Baseado nas evidências
     - **Arquivos Afetados**: Lista de arquivos a modificar
     - **Impacto**: Outros componentes que podem ser afetados
-    - **Skills utilizadas**: registre explicitamente se a análise usou `vercel-react-best-practices`, `agent-browser`, `webapp-testing` ou `security-review`
+    - **Skills utilizadas**: registre explicitamente se a análise usou `vercel-react-best-practices`, `webapp-testing` ou `security-review`
 
     ### 4.1 Checkpoint de Escopo (OBRIGATÓRIO)
 

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

@@ -17,7 +17,6 @@ Você é um assistente IA especializado em correção de bugs pós-QA com retest
 
 Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como suporte operacional sem substituir este comando:
 
-- `agent-browser`: suporte para reproduzir bugs com sessões persistentes, capturar dados de rede, screenshots adicionais e validar correções browser-first
 - `webapp-testing`: suporte para estruturar retestes, capturas e scripts quando complementar ao Playwright MCP
 - `vercel-react-best-practices`: use apenas se a correção afetar frontend React/Next.js e houver risco de regressão de renderização, hidratação, fetching ou performance
 
@@ -87,7 +86,7 @@ Para cada bug corrigido:
    - `QA/logs/console-retest.log`
    - `QA/logs/network-retest.log`
 7. Registrar no relatório de QA qual usuário/perfil foi usado no reteste
-8. Se o reteste exigir auth persistente, inspeção além do MCP, ou reprodução mais fiel em navegador real, complementar com `agent-browser` e registrar no relatório
+8. Se o reteste exigir auth persistente, inspeção além do MCP, ou reprodução mais fiel em navegador real, registrar no relatório
 
 ### 4. Atualização de Artefatos
 

package/scaffold/pt-br/commands/dw-functional-doc.md

@@ -37,6 +37,12 @@ Funciona melhor com projeto analisado por `/dw-analyze-project`
 <critical>Header e footer de vídeos humanos não podem disputar área útil com a tela do browser. Quando eles existirem, devem ficar fora do stage do browser, em uma composição maior, preservando intacta a viewport real da aplicação.</critical>
 <critical>Quando o objetivo for um tour humano com browser centralizado, mantenha a aplicação em um palco central sem colunas laterais fixas, preservando header e footer em largura total fora da área do browser.</critical>
 <critical>Qualidade visual do browser é requisito obrigatório. Não entregue tour humano com viewport ou gravação reescalada para baixo em relação à resolução final. O runner deve alinhar viewport e captura de vídeo à resolução final ou registrar bloqueio explícito.</critical>
+<critical>Legenda hardcoded sobre a tela do produto não é padrão aceitável quando o ambiente permitir shell dedicada. O padrão preferencial e obrigatório é: `header` superior com título do tour, `stage` centralizado para o browser intacto e `footer` inferior exclusivo para a legenda narrativa.</critical>
+<critical>Mesmo quando o vídeo humano for montado a partir de screenshots e não de navegação gravada, a composição final deve manter o mesmo layout de shell: cabeçalho e rodapé fora da área útil da aplicação. Não entregar slideshow fullscreen com subtitles queimadas diretamente sobre o conteúdo do produto.</critical>
+<critical>No artefato principal de vídeo humano, a legenda precisa estar visível dentro do `footer` da shell. Arquivo `.srt` sidecar e faixa de subtitle embutida podem existir como apoio, mas não substituem a obrigação de a narrativa principal já aparecer posicionada corretamente no rodapé da composição final.</critical>
+<critical>É inválido entregar como versão principal um MP4 cuja legenda dependa do player para posicionamento (`mov_text`, `tx3g`, subtitle track similar) quando isso fizer o texto sair do footer da shell. Se houver faixa embutida auxiliar, validar visualmente que a versão principal continua correta mesmo sem o player renderizar subtitles.</critical>
+<critical>Quando o pedido envolver vídeo humano com legenda, gerar sempre dois artefatos de vídeo: um `clean` sem legenda renderizada no quadro, para uso com player + `.srt` sidecar; e um `captioned` com a narrativa já queimada corretamente no `footer` da shell.</critical>
+<critical>Se já existir no workspace um flow anterior com shell de gravação humana melhor resolvida, reutilize esse padrão visual e estrutural antes de improvisar nova composição. Esse reaproveitamento é preferível a uma solução simplificada com legendas embutidas sobre a viewport.</critical>
 
 ### Requisitos de Cadência do Vídeo
 <critical>Antes e depois de ações principais, inserir pausas intencionais. Como regra operacional: manter de 2 a 3 segundos de permanência em estados relevantes já carregados e pelo menos 1,5 segundo após o desfecho visível de cada ação principal antes de seguir.</critical>
@@ -49,7 +55,6 @@ Funciona melhor com projeto analisado por `/dw-analyze-project`
 
 Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como apoio operacional, sem substituir este comando como fonte de verdade:
 
-- `agent-browser`: apoio para navegação real, inspeção de requests, screenshots, auth persistente e reprodução browser-first
 - `webapp-testing`: apoio para estruturar fluxos E2E, retestes locais e coleta de evidências
 - `remotion-best-practices`: apoio obrigatório quando houver vídeo humano final, legendas, composição, transições, FFmpeg ou Remotion
 - `humanizer`: apoio obrigatório para revisar e naturalizar todas as legendas, captions `.srt`, textos descritivos e qualquer redação voltada a leitura humana antes da entrega final
@@ -119,6 +124,9 @@ Se houver execução:
 Se houver vídeo humano final:
 - salvar em `evidence/videos/` com nome que diferencie claramente o tour final da captura bruta
 - quando `ffmpeg` estiver disponível, salvar também a versão `mp4` do tour humano final
+- quando houver legendas, salvar também duas variantes explícitas:
+  - uma versão `clean` sem legenda desenhada no frame
+  - uma versão `captioned` com legenda desenhada no `footer` da shell
 - registrar no `manifest.json` quais arquivos são `raw` e quais são `human_final`
 
 ## Fluxo obrigatório
@@ -224,6 +232,11 @@ Gerar `e2e-runbook.md` no estilo operacional detalhado:
   - quando houver título e legenda, reservar cabeçalho e rodapé próprios fora do stage do browser
   - quando a composição pedir browser centralizado, manter a aplicação em um palco central sem colunas laterais fixas e sem sacrificar a largura total do cabeçalho e do rodapé
   - evitar qualquer redução artificial da viewport do app para encaixar overlays
+  - evitar subtitles queimadas diretamente dentro da viewport do produto quando houver possibilidade de usar shell externa
+  - queimar a narrativa principal no `footer` da shell do vídeo final; usar `.srt` sidecar e faixa embutida apenas como artefatos complementares
+  - para cada tour final com legenda, produzir:
+    - `clean`: sem legenda no frame, com `.srt` separado para o player decidir
+    - `captioned`: legenda já posicionada no `footer` da shell
   - alinhar a captura de vídeo à resolução final para evitar perda de nitidez no browser
   - manter em tela cada estado relevante por tempo suficiente para leitura visual, em especial listas, diálogos, badges, validações, mensagens e resultados finais
   - manter as legendas tempo suficiente para leitura confortável, sem trocar texto antes de a etapa correspondente ser compreendida visualmente
@@ -246,6 +259,28 @@ Quando produzir ou revisar o tour final, aplicar estas regras como baseline:
 - quando houver comparação entre estado anterior e posterior, mostrar claramente os dois momentos
 - se a gravação ficar rápida demais para leitura humana, considerar a execução inadequada mesmo que tecnicamente correta
 - se `ffmpeg` estiver instalado, considerar incompleta a entrega que deixar apenas `webm` ou outro bruto sem gerar `mp4`
+- considerar inadequado o vídeo que use apenas captions sobrepostas ao browser quando o projeto permitir shell com header/footer dedicados
+- considerar inadequado o vídeo cuja legenda principal dependa do renderer do player e por isso apareça fora do `footer` previsto na shell
+- considerar incompleta a entrega que disponibilize só uma das variantes (`clean` ou `captioned`) quando o fluxo exigir vídeo com legenda
+
+## Padrão visual obrigatório da shell
+
+Quando houver vídeo humano final, adotar como padrão visual mínimo:
+
+- `header` fixo fora do browser com o nome do módulo ou fluxo
+- `main` centralizando um `stage` único do browser
+- `footer` fixo fora do browser, reservado para legenda narrativa ou contexto curto
+- `stage` com borda, raio e sombra próprios, sem cortar a viewport da aplicação
+- largura e altura do `stage` definidas explicitamente e proporcionais à resolução final
+
+Baseline recomendada para `1920x1080` quando não houver padrão melhor no próprio flow:
+
+- `header`: ~`64px`
+- `footer`: ~`112px`
+- `stage`: ~`1600x900`
+
+Se já existir no workspace um script de shell funcional (ex: `record-human-tour.cjs`), reutilize-o como referência. Se optar por outro layout, justifique explicitamente no `manifest.json`.
+
 - Atualizar `manifest.json` com status final, artefatos e bloqueios, distinguindo:
   - evidências MCP
   - captura bruta de execução