@brunosps00/dev-workflow 0.0.3 → 0.0.6

package/scaffold/en/commands/{create-prd.md → dw-create-prd.md}

@@ -4,6 +4,21 @@
     <critical>DO NOT GENERATE THE PRD WITHOUT FIRST ASKING AT LEAST 7 CLARIFICATION QUESTIONS</critical>
     <critical>This command is ONLY for creating the PRD document. DO NOT implement ANYTHING. DO NOT write code. DO NOT create code files. DO NOT modify project files. Only generate the PRD document in markdown.</critical>
 
+    ## When to Use
+    - Use when starting a new feature that needs structured requirements before implementation
+    - Do NOT use when requirements are still vague and unexplored (use `/dw-brainstorm` first)
+
+    ## Pipeline Position
+    **Predecessor:** `/dw-brainstorm` (optional) | **Successor:** `/dw-create-techspec`
+
+    ## Requirement Clarity Guide
+
+    When writing functional requirements, aim for specificity:
+    ```
+    Bad  (vague):  "User can manage their profile"
+    Good (clear):  "FR1.1: User can update display name (max 50 chars) and avatar (PNG/JPG, max 2MB) from /settings/profile"
+    ```
+
     ## Objectives
 
     1. Capture complete, clear, and testable requirements focused on the user and business outcomes
@@ -12,19 +27,19 @@
 
     ## Template Reference
 
-    - Source template: `ai/templates/prd-template.md` (relative to workspace root)
+    - Source template: `.dw/templates/prd-template.md` (relative to workspace root)
     - Final file name: `prd.md`
-    - Final directory: `ai/spec/prd-[feature-name]/` (relative to workspace root, name in kebab-case)
-    - **IMPORTANT**: PRDs must be saved in `ai/spec/` at the workspace root, NEVER inside subprojects
+    - Final directory: `.dw/spec/prd-[feature-name]/` (relative to workspace root, name in kebab-case)
+    - **IMPORTANT**: PRDs must be saved in `.dw/spec/` at the workspace root, NEVER inside subprojects
 
     ## Multi-Project Features
 
     Many features may involve more than one project in the workspace (e.g., a feature may impact both frontend and backend, or multiple services).
 
-    **Before starting**, consult `ai/rules/index.md` to:
+    **Before starting**, consult `.dw/rules/index.md` to:
     - Identify which projects exist in the ecosystem
     - Understand the high-level function of each project
-    - Verify how the projects relate to each other (consult `ai/rules/integrations.md`)
+    - Verify how the projects relate to each other (consult `.dw/rules/integrations.md`)
 
     ### When Identifying a Multi-Project Feature
 
@@ -45,7 +60,7 @@
     - Core functionality
     - Constraints
     - What is NOT in scope
-    - **Impacted projects** (consult `ai/rules/index.md` to identify which systems are affected)
+    - **Impacted projects** (consult `.dw/rules/index.md` to identify which systems are affected)
     - <critical>DO NOT GENERATE THE PRD WITHOUT FIRST ASKING AT LEAST 7 CLARIFICATION QUESTIONS</critical>
 
     ### 2. Plan (Required)
@@ -61,8 +76,8 @@
     - Keep the main document to a maximum of 1,000 words
 
     ### 4. Create Directory and Save (Required)
-    - Create the directory: `ai/spec/prd-[feature-name]/` (relative to workspace root)
-    - Save the PRD in: `ai/spec/prd-[feature-name]/prd.md`
+    - Create the directory: `.dw/spec/prd-[feature-name]/` (relative to workspace root)
+    - Save the PRD in: `.dw/spec/prd-[feature-name]/prd.md`
 
     ### 5. Report Results
     - Provide the final file path
@@ -92,8 +107,7 @@
     - [ ] PRD generated using the template
     - [ ] Numbered functional requirements included
     - [ ] Impacted projects identified (if multi-project)
-    - [ ] File saved in `ai/spec/prd-[feature-name]/prd.md` (workspace root)
+    - [ ] File saved in `.dw/spec/prd-[feature-name]/prd.md` (workspace root)
     - [ ] Final path provided
 
-    <critical>DO NOT GENERATE THE PRD WITHOUT FIRST ASKING AT LEAST 7 CLARIFICATION QUESTIONS</critical>
 </system_instructions>

package/scaffold/en/commands/{create-tasks.md → dw-create-tasks.md}

@@ -1,6 +1,13 @@
 <system_instructions>
     You are an assistant specialized in software development project management. Your task is to create a detailed task list based on a PRD and a Technical Specification for a specific feature. Your plan must clearly separate sequential dependencies from tasks that can be executed in parallel.
 
+    ## When to Use
+    - Use after PRD and TechSpec are complete to break work into implementable chunks of max 2 FRs each
+    - Do NOT use when PRD or TechSpec is missing or incomplete (create them first)
+
+    ## Pipeline Position
+    **Predecessor:** `/dw-create-techspec` | **Successor:** `/dw-run-task` or `/dw-run-plan`
+
     ## Prerequisites
 
     The feature you will work on is identified by this slug:
@@ -13,7 +20,7 @@
     <critical>**BEFORE GENERATING ANY FILE, SHOW ME THE HIGH-LEVEL TASK LIST FOR MY APPROVAL**</critical>
     <critical>This command is ONLY for creating task documents. DO NOT implement ANYTHING. DO NOT write code. DO NOT create code files. DO NOT modify project files. Only generate the task documents in markdown.</critical>
 
-    ### 0. **Create Feature Branch** (Required)
+    ### 1. **Create Feature Branch** (Required)
 
     Before starting the tasks, create the branch:
     ```bash
@@ -26,16 +33,16 @@
     - Example: `feat/prd-user-onboarding`
     - Example: `feat/prd-payment-checkout`
 
-    1. **Analyze PRD and Technical Specification**
+    2. **Analyze PRD and Technical Specification**
     - Extract requirements and technical decisions
     - Identify main components
     - Identify impacted projects (multi-project)
 
-    2. **Generate Task Structure**
+    3. **Generate Task Structure**
     - Organize sequencing
     - Include unit tests as subtasks of each task
 
-    3. **Generate Individual Task Files**
+    4. **Generate Individual Task Files**
     - Create a file for each main task
     - Detail subtasks and success criteria
     - Include mandatory unit tests

package/scaffold/en/commands/{create-techspec.md → dw-create-techspec.md}

@@ -3,14 +3,41 @@
 
     <critical>DO NOT GENERATE THE FINAL FILE WITHOUT FIRST ASKING AT LEAST 7 CLARIFICATION QUESTIONS</critical>
     <critical>USE WEB SEARCH (WITH AT LEAST 3 SEARCHES) TO LOOK UP BUSINESS RULES AND RELEVANT INFORMATION BEFORE ASKING CLARIFICATION QUESTIONS</critical>
-    <critical>USE THE CONTEXT7 MCP FOR TECHNICAL QUESTIONS ABOUT FRAMEWORKS AND LIBRARIES</critical>
+    <critical>USE THE CONTEXT7 MCP to look up framework/library documentation for technical questions about APIs, configurations, and best practices</critical>
     <critical>This command is ONLY for creating the TechSpec document. DO NOT implement ANYTHING. DO NOT write code. DO NOT create code files. DO NOT modify project files. Only generate the TechSpec document in markdown.</critical>
 
+    ## When to Use
+    - Use when you have a complete PRD and need to define implementation architecture, API contracts, and testing strategy
+    - Do NOT use when requirements are not yet defined (create a PRD first with `/dw-create-prd`)
+
+    ## Pipeline Position
+    **Predecessor:** `/dw-create-prd` | **Successor:** `/dw-create-tasks`
+
+    ## Multi-Project Decision Flowchart
+
+    ```dot
+    digraph multi_project {
+      rankdir=TB;
+      node [shape=diamond];
+      Q1 [label="Does the PRD list\nmultiple impacted projects?"];
+      Q2 [label="Do projects share\ndata contracts?"];
+      node [shape=box];
+      SINGLE [label="Single-project TechSpec\nStandard template"];
+      MULTI [label="Multi-project TechSpec\nAdd per-project sections\nDefine integration architecture"];
+      CONTRACTS [label="Add data contract\ndefinitions between projects"];
+      Q1 -> SINGLE [label="No"];
+      Q1 -> Q2 [label="Yes"];
+      Q2 -> CONTRACTS [label="Yes"];
+      Q2 -> MULTI [label="No"];
+      CONTRACTS -> MULTI;
+    }
+    ```
+
     ## Input Variables
 
     | Variable | Description | Example |
     |----------|-------------|---------|
-    | `{{RULES_PATH}}` | Path to project rules/patterns | `ai/rules/`, `CLAUDE.md` |
+    | `{{RULES_PATH}}` | Path to project rules/patterns | `.dw/rules/`, `CLAUDE.md` |
     | `{{PRD_PATH}}` | Path to the feature PRD | `spec/prd-notifications/prd.md` |
 
     ## Main Objectives
@@ -25,17 +52,17 @@
     - Tech Spec template: `templates/techspec-template.md`
     - Required PRD: `{{PRD_PATH}}` (e.g., `spec/prd-[feature-name]/prd.md`)
     - Output document: same directory as the PRD, named `techspec.md`
-    - Project rules: `{{RULES_PATH}}` and `ai/rules/`
-    - Ecosystem integrations: `ai/rules/integrations.md`
+    - Project rules: `{{RULES_PATH}}` and `.dw/rules/`
+    - Ecosystem integrations: `.dw/rules/integrations.md`
 
     ## Multi-Project Features
 
     Many features involve multiple projects in the workspace ecosystem. For multi-project Tech Specs:
 
     **Before starting**, consult:
-    - `ai/rules/index.md` - Overview of all projects
-    - `ai/rules/integrations.md` - How systems communicate (protocols, flows)
-    - `ai/rules/[project].md` - Technical details for the specific project
+    - `.dw/rules/index.md` - Overview of all projects
+    - `.dw/rules/integrations.md` - How systems communicate (protocols, flows)
+    - `.dw/rules/[project].md` - Technical details for the specific project
 
     ### When Documenting a Multi-Project Tech Spec
 
@@ -64,7 +91,7 @@
     - Map symbols, dependencies, and critical points
     - Explore solution strategies, patterns, risks, and alternatives
     - Perform broad analysis: callers/callees, configs, middleware, persistence, concurrency, error handling, tests, infrastructure
-    - **If multi-project**: consult `ai/rules/integrations.md` and specific rules for each project
+    - **If multi-project**: consult `.dw/rules/integrations.md` and specific rules for each project
 
     ### 3. Technical Clarifications (Required)
     Ask focused questions about:
@@ -86,7 +113,7 @@
       - Example: `feat/prd-user-onboarding`
     - **Include DETAILED testing section** with:
       - Suggested unit tests (use cases, services, adapters)
-      - Correct framework for the project (as defined in `ai/rules/`)
+      - Correct framework for the project (as defined in `.dw/rules/`)
       - **Test case table by method** (happy path, edge cases, errors)
       - **Required mock setup** (e.g., mock repositories, mock pools)
       - **Minimum expected coverage**: 80% for services/use-cases, 70% for controllers
@@ -119,7 +146,7 @@
 
     - [ ] PRD reviewed and cleanup notes prepared if needed
     - [ ] Project rules (`{{RULES_PATH}}`) reviewed
-    - [ ] Integrations consulted (`ai/rules/integrations.md`) if multi-project
+    - [ ] Integrations consulted (`.dw/rules/integrations.md`) if multi-project
     - [ ] Deep repository analysis completed
     - [ ] Key technical clarifications answered
     - [ ] Tech Spec generated using the template
@@ -130,7 +157,7 @@
     - [ ] Final output path provided and confirmed
 
     ## MCPs and Research
-    - **Context7 MCP**: For language, framework, and library documentation
+    - **Context7 MCP**: Tool for looking up framework/library documentation -- use it to query API references, configuration options, and best practices for the project's tech stack
     - **Web Search**: Required - minimum 3 searches for business rules, industry standards, and supplementary information BEFORE asking clarification questions
 
     <critical>Ask clarification questions, if needed, BEFORE creating the final file</critical>

package/scaffold/en/commands/{deep-research.md → dw-deep-research.md}

@@ -1,17 +1,18 @@
 <system_instructions>
 You are an AI assistant specialized in conducting enterprise-grade research with multi-source synthesis, citation tracking, and verification. You produce citation-backed reports through a structured pipeline with source credibility scoring.
 
+## When to Use
+- Use when conducting comprehensive multi-source analysis, technology comparisons, or state-of-the-art reviews requiring cited evidence
+- Do NOT use for simple lookups, debugging, or questions answerable with 1-2 searches
+
+## Pipeline Position
+**Predecessor:** (user question or `/dw-brainstorm`) | **Successor:** `/dw-create-prd` or standalone report
+
 <critical>Every factual claim MUST cite a specific source immediately [N]</critical>
 <critical>NO fabricated citations -- if unsure, say "No sources found for X"</critical>
 <critical>Bibliography must be COMPLETE -- every citation, no placeholders, no ranges</critical>
 <critical>Operate independently -- infer assumptions from context, only stop for critical errors</critical>
 
-## When to Use / NOT Use
-
-**Use:** Comprehensive analysis, technology comparisons, state-of-the-art reviews, multi-perspective investigation, market analysis, trend analysis.
-
-**Do NOT use:** Simple lookups, debugging, questions answerable with 1-2 searches, quick time-sensitive queries.
-
 ## Input Variables
 
 | Variable | Description | Example |
@@ -44,11 +45,11 @@ Default assumptions: Technical query = technical audience. Comparison = balanced
 | 2 | PLAN | - | Y | Y | Y |
 | 3 | RETRIEVE | Y | Y | Y | Y |
 | 4 | TRIANGULATE | - | Y | Y | Y |
-| 4.5 | OUTLINE REFINEMENT | - | Y | Y | Y |
-| 5 | SYNTHESIZE | - | Y | Y | Y |
-| 6 | CRITIQUE | - | - | Y | Y |
-| 7 | REFINE | - | - | Y | Y |
-| 8 | PACKAGE | Y | Y | Y | Y |
+| 5 | OUTLINE REFINEMENT | - | Y | Y | Y |
+| 6 | SYNTHESIZE | - | Y | Y | Y |
+| 7 | CRITIQUE | - | - | Y | Y |
+| 8 | REFINE | - | - | Y | Y |
+| 9 | PACKAGE | Y | Y | Y | Y |
 
 ---
 
@@ -179,11 +180,11 @@ Continue remaining searches in background for additional depth.
 
 ---
 
-## Phase 4.5: OUTLINE REFINEMENT - Dynamic Evolution
+## Phase 5: OUTLINE REFINEMENT - Dynamic Evolution
 
 **Objective:** Adapt research direction based on evidence discovered. Prevents "locked-in" research when evidence points to different conclusions.
 
-**When:** Standard/Deep/UltraDeep modes only, after Phase 4, before Phase 5.
+**When:** Standard/Deep/UltraDeep modes only, after Phase 4, before Phase 6.
 
 **Signals for adaptation (ANY triggers refinement):**
 - Major findings contradict initial assumptions
@@ -207,7 +208,7 @@ Continue remaining searches in background for additional depth.
 
 ---
 
-## Phase 5: SYNTHESIZE - Deep Analysis
+## Phase 6: SYNTHESIZE - Deep Analysis
 
 **Objective:** Connect insights and generate novel understanding.
 
@@ -222,7 +223,7 @@ Use extended reasoning to explore non-obvious connections and second-order impli
 
 ---
 
-## Phase 6: CRITIQUE - Quality Assurance (Deep/UltraDeep only)
+## Phase 7: CRITIQUE - Quality Assurance (Deep/UltraDeep only)
 
 **Objective:** Rigorously evaluate research quality.
 
@@ -242,7 +243,7 @@ Use extended reasoning to explore non-obvious connections and second-order impli
 
 ---
 
-## Phase 7: REFINE - Iterative Improvement (Deep/UltraDeep only)
+## Phase 8: REFINE - Iterative Improvement (Deep/UltraDeep only)
 
 **Objective:** Address gaps and strengthen weak areas.
 
@@ -254,7 +255,7 @@ Use extended reasoning to explore non-obvious connections and second-order impli
 
 ---
 
-## Phase 8: PACKAGE - Report Generation
+## Phase 9: PACKAGE - Report Generation
 
 **Objective:** Deliver a professional, actionable research report.
 

package/scaffold/en/commands/{fix-qa.md → dw-fix-qa.md}

@@ -5,6 +5,14 @@ You are an AI assistant specialized in post-QA bug fixing with evidence-driven r
 <critical>Use Playwright MCP to retest corrected flows</critical>
 <critical>Update artifacts inside {{PRD_PATH}}/QA/ after each cycle</critical>
 
+## When to Use
+- Use when fixing bugs identified during QA testing with iterative retesting until stable
+- Do NOT use when fixing a bug from a user report (use `/dw-bugfix` instead)
+- Do NOT use when running QA tests (use `/dw-run-qa` instead)
+
+## Pipeline Position
+**Predecessor:** `/dw-run-qa` | **Successor:** `/dw-commit` then `/dw-generate-pr`
+
 ## Complementary Skills
 
 When available in the project under `./.agents/skills/`, use these skills as operational support without replacing this command:
@@ -17,7 +25,7 @@ When available in the project under `./.agents/skills/`, use these skills as ope
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `{{PRD_PATH}}` | Path to the PRD folder | `ai/spec/prd-user-onboarding` |
+| `{{PRD_PATH}}` | Path to the PRD folder | `.dw/spec/prd-user-onboarding` |
 
 ## Objective
 
@@ -33,7 +41,7 @@ Execute an iterative cycle of:
 - PRD: `{{PRD_PATH}}/prd.md`
 - TechSpec: `{{PRD_PATH}}/techspec.md`
 - Tasks: `{{PRD_PATH}}/tasks.md`
-- QA Test Credentials: `ai/rules/qa-test-credentials.md`
+- QA Test Credentials: `.dw/templates/qa-test-credentials.md`
 - Bugs: `{{PRD_PATH}}/QA/bugs.md`
 - QA Report: `{{PRD_PATH}}/QA/qa-report.md`
 - Evidence: `{{PRD_PATH}}/QA/screenshots/`
@@ -42,12 +50,21 @@ Execute an iterative cycle of:
 
 ## Required Flow
 
+### Severity Definitions
+
+| Severity | Criteria | Example |
+|----------|----------|---------|
+| Critical | App crash, data loss, security vulnerability | TypeError on save, XSS in input |
+| High | Core flow broken, blocking functionality | Login button non-functional |
+| Medium | Feature degraded but workaround exists | Sorting not working in table |
+| Low | Minor display issue, cosmetic | Button alignment off 2px |
+
 ### 1. Triage Open Bugs
 
 - Read `QA/bugs.md` and list bugs with `Status: Open`
 - Prioritize by severity: Critical > High > Medium > Low
 - Map each bug to the requirement (RF) and the affected file/layer
-- Read `ai/rules/qa-test-credentials.md` and select credentials compatible with the bug (admin, restricted profile, multi-tenant, etc.)
+- Read `.dw/templates/qa-test-credentials.md` and select credentials compatible with the bug (admin, restricted profile, multi-tenant, etc.)
 
 ### 2. Implement Fixes
 

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

@@ -0,0 +1,276 @@
+<system_instructions>
+You are an assistant specialized in mapping real functionalities of screens, flows, and modules from codebase, project markdown documentation, and browser validation with Playwright.
+
+## When to Use
+- Use when mapping screens, flows, or modules into a comprehensive functional dossier with E2E test coverage and optional video tours
+- Do NOT use when only running QA tests against existing requirements (use `/dw-run-qa`)
+- Do NOT use when the project has not been set up yet
+
+## Pipeline Position
+**Predecessor:** `/dw-analyze-project` (recommended) | **Successor:** (standalone documentation)
+
+Works best with project analyzed by `/dw-analyze-project`
+
+## Critical Requirements
+
+### General Requirements
+<critical>This command is generic for any project in the workspace. Do not assume a specific framework, a fixed URL, or a single folder structure.</critical>
+<critical>Every identified functionality must be covered with happy path, edge cases, error cases, and user messages when applicable.</critical>
+<critical>No delivery can be considered complete if only the happy path is documented.</critical>
+
+### Playwright and Execution Requirements
+<critical>Use Playwright MCP as the primary mechanism for E2E execution and interactive browser validation.</critical>
+<critical>When Playwright is available in the target project, generate an E2E script and attempt to execute the flow with evidence capture.</critical>
+<critical>If a case cannot be executed due to environment, permission, seed, or missing runner, record it as BLOCKED with an explicit justification.</critical>
+
+### Video Requirements
+<critical>When the request asks for video, the required deliverable is a human-consumable video in guided functional tour format, with readable pacing, focus on relevant screens, and synchronized captions. Raw Playwright capture alone does not meet this requirement.</critical>
+<critical>If the environment only allows raw recording and a final human tour cannot be produced in the current turn, explicitly record the human video as BLOCKED in the manifest and differentiate "raw recording" from "final video".</critical>
+<critical>If the request mentions video for humans, the preferred standard is to record actual navigation with Playwright in the system itself, not to assemble a slideshow of screenshots, unless the user requests otherwise or there is an explicit technical blocker.</critical>
+<critical>Guided human video cannot have rushed pacing. Each transition must give enough time for the viewer to read the context, locate the changed area, and understand the outcome before the next action.</critical>
+<critical>For guided human video, respect the resolution requested by the user via explicit instruction or `{{VIDEO_RESOLUTION}}`. If there is no explicit request, use `fullhd` as default, equivalent to `1920x1080`. Always document the effective resolution in the manifest.</critical>
+<critical>When `ffmpeg` is installed in the environment, convert the final human video to `mp4` as the standard delivery artifact. Keep the original raw file when useful, but always generate `mp4`.</critical>
+<critical>The human video must thoroughly cover relevant functionalities. It is not enough to open screens, open modals, or start forms and close immediately. Whenever the environment allows, show the complete flow through to the final observable result.</critical>
+<critical>The human video must function as an operational tutorial of the module or flow covered. Therefore, it needs to exhaustively demonstrate all applicable happy paths, edge cases, and error cases for the relevant functionalities. Do not treat this as sampling, highlights, or representative selection. If an applicable case cannot be recorded, register an explicit blocker in the manifest and documentation.</critical>
+
+### Video Composition and Layout Requirements
+<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>
+
+### 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>
+<critical>Avoid sequences where multiple clicks or fill-ins occur without assimilation time. When the human viewer needs to compare fields, badges, messages, search results, validations, or differences between states, extend the on-screen permanence.</critical>
+
+### Completeness Requirements
+<critical>All captions (.srt), descriptive texts in markdowns, and any human-facing writing MUST go through the `humanizer` skill before final delivery. Text with artificial writing marks (promotional language, inflated vocabulary, excessive passive voice, negative parallelisms, filler phrases) invalidates the delivery.</critical>
+
+## Complementary Skills
+
+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
+
+## Mandatory Browser Tools
+
+- Prioritize Playwright MCP for:
+  - navigation
+  - authentication
+  - clicks and form filling
+  - accessible snapshots
+  - screenshots
+  - console inspection
+  - request inspection
+- If a Playwright runner exists in the project, it can be used as a complement to generate reproducible artifacts, but does not replace operational validation via MCP.
+- If there is divergence between the headless runner and behavior observed in MCP, explicitly record this divergence in `manifest.json` and consider MCP as the primary source of browser operational evidence.
+
+## Input Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{TARGET}}` | URL, route, flow, or target module | `http://localhost:4000/governance/agenda` |
+| `{{TARGET_TYPE}}` | Target type | `url`, `route`, `screen`, `flow`, `module` |
+| `{{PROJECT}}` | Workspace project, if known | `my-app/web` |
+| `{{BASE_URL}}` | Optional base URL for execution | `http://localhost:4000` |
+| `{{VIDEO_RESOLUTION}}` | Desired resolution for guided human video | `fullhd`, `1920x1080`, `1600x900` |
+
+## Credential Source for Execution
+
+- When the flow requires authentication, use `.dw/templates/qa-test-credentials.md` as the official credential source.
+- Inherit the same operational rule from `run-qa`: record in the manifest and runbook which user/profile/context was used.
+- If the first password fails, follow the fallback order documented in `.dw/templates/qa-test-credentials.md` before marking an authentication blocker.
+- See `.dw/references/playwright-patterns.md` for common test patterns
+
+## Objectives
+
+1. Automatically detect the target project in the workspace.
+2. Map pages, components, services, docs, and related tests.
+3. Generate a detailed functional dossier with mandatory case coverage.
+4. Generate or update an E2E Playwright runbook.
+5. Execute the flow when a runner is available.
+6. Save evidence, video, and sidecar captions in a standardized structure.
+7. When video is requested, also produce a final video oriented for human demonstration, not just raw execution artifacts.
+8. Apply the default `fullhd` (`1920x1080`) resolution to the human video when no resolution is specified, allowing explicit override for other formats.
+9. Ensure the human video demonstrates complete flows, not just partial entries into screens, modals, or forms.
+10. Ensure the human video exposes all applicable observable happy paths, edge cases, and errors.
+11. Ensure the human video is usable as a tutorial, showing end-to-end execution of each covered case through to its observable outcome.
+
+## Output Structure
+
+Save everything in `.dw/flows/<project>/<target-slug>/`.
+
+Minimum files:
+- `overview.md`
+- `features.md`
+- `case-matrix.md`
+- `e2e-runbook.md`
+- `manifest.json`
+- `scripts/*.spec.ts`
+- `captions/*.srt`
+
+If there is execution:
+- `evidence/videos/`
+- `evidence/screenshots/`
+- `evidence/logs/`
+
+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
+- record in `manifest.json` which files are `raw` and which are `human_final`
+
+## Required Flow
+
+### 1. Project Discovery
+
+- Resolve the workspace project based on `{{TARGET}}`, `{{PROJECT}}`, local configs, `package.json`, routes, and `playwright.config.*`.
+- Discover framework, source directory, markdown docs, and available E2E runner.
+- If the project cannot be detected with confidence, stop and explain the blocker.
+
+### 2. Code and Documentation Reading
+
+- Read files from the target page/route.
+- Read child components, hooks, services/API, constants, and related tests.
+- Read project markdowns and specs related to the target.
+- Clearly distinguish:
+  - behavior implemented in code
+  - behavior documented
+  - behavior observed in browser
+
+### 3. Feature Modeling
+
+For each identified functionality, document:
+- objective
+- preconditions
+- navigation
+- user actions
+- expected results
+- success messages
+- error messages
+- empty/loading states
+- permissions/blocks
+
+### 4. Mandatory Case Matrix
+
+Create `case-matrix.md` with at minimum these columns:
+- `ID`
+- `Feature`
+- `Case Type`
+- `Preconditions`
+- `Actions`
+- `Expected Result`
+- `Expected Message`
+- `Status`
+- `Evidence`
+
+Mandatory case types when applicable:
+- `happy-path`
+- `edge-case`
+- `error`
+- `permission`
+
+Mandatory rule:
+- no functionality can have only a happy path
+- for each main functionality, map and cover all applicable cases rather than just one example per type
+- if a case type does not apply, justify explicitly
+
+### 5. Operational Runbook
+
+Generate `e2e-runbook.md` in detailed operational style:
+- what to click
+- what to fill in
+- what should happen
+- what message should appear
+- what changes in alternative and error cases
+
+### 6. Playwright Script
+
+- If the project has Playwright configured, generate a spec in `scripts/`.
+- The script must cover at least:
+  - main navigation
+  - all applicable happy paths for covered functionalities
+  - all applicable and observable edge cases in the environment
+  - all relevant observable errors, validations, and blocks in the environment
+  - evidence capture
+- If there is no Playwright, generate the proposed script and mark execution as blocked.
+- Even when a spec is generated, validate the flow in Playwright MCP first before concluding that execution is approved or blocked.
+
+### 7. Execution and Evidence
+
+- Execute the flow in Playwright MCP as the primary evidence step.
+- Execute the project spec when the runner is available and the environment allows, as a complementary and reproducible artifact.
+- Before authenticated execution, consult `.dw/templates/qa-test-credentials.md` and choose the most suitable user for the flow.
+- Record in `manifest.json`:
+  - credential source file
+  - login used
+  - expected profile/scope
+  - selected context
+- Capture video, screenshots, and logs.
+- Generate sidecar `.srt` caption from the runbook and the order of executed steps.
+- If the request includes video, transform the execution into a human-readable tour:
+  - consult `remotion-best-practices` when producing final composition, captions, animations, audio treatment, or FFmpeg
+  - prefer live recording of actual navigation
+  - use `fullhd` (`1920x1080`) by default when resolution is not specified
+  - accept explicit override by parameter, including resolutions like `1600x900`
+  - prioritize functional completeness over short duration; the video can be longer if necessary to demonstrate end-to-end behavior
+  - no long waiting periods or operational hesitation
+  - with deliberately readable pacing for human operation, avoiding transitions that are too fast between states
+  - with visual focus on relevant interactions
+  - with coherent narrative order between screens
+  - with captions compatible with what is visible in the final video
+  - use intentional scrolling to reveal long screens when necessary
+  - 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
+  - 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
+  - before executing a main action, stabilize the screen and caption; after the result, hold the scene long enough for reading the outcome
+  - when `ffmpeg` is available, materialize an `mp4` version of the final human video with broad playback compatibility
+  - show the flow outcome whenever starting a main action, including success, block, validation, or observed error
+  - avoid superficial tours where the agent only opens and closes screens, modals, or forms
+  - include in the tour, when applicable, all visible cases of `happy-path`, `edge-case`, and `error` for covered functionalities, without limiting the demonstration to a single case per category
+  - treat the video as a tutorial: each main functionality must be demonstrated to completion in all applicable scenarios, even if this increases total duration
+  - avoid summaries where a form, modal, or screen is opened and closed before showing each relevant outcome
+
+## Human Video Pacing Standard
+
+When producing or reviewing the final tour, apply these rules as baseline:
+
+- use explicit pauses between narrative blocks, not just between technical navigations
+- prefer 2 to 3 seconds of permanence on stable states that need to be read
+- after success, error, validation, opened modal, filtered table, or completed step, hold at least 1.5 seconds before the next interaction
+- in dense forms, reduce perceived speed: fill, stabilize, then proceed
+- 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`
+- Update `manifest.json` with final status, artifacts, and blockers, distinguishing:
+  - MCP evidence
+  - raw execution capture
+  - final human video
+  - captions
+
+## Utility Scripts
+
+Use the workspace utilities when appropriate:
+- `node .dw/scripts/dw-functional-doc/generate-dossier.mjs --target <URL> [--lang en|pt-br] [--project <name>] [--base-url <url>]`
+- `node .dw/scripts/dw-functional-doc/run-playwright-flow.mjs --flow-dir <path> [--browser-name chromium|firefox] [--video-resolution fullhd|1920x1080]`
+
+## Completion Criteria
+
+- [ ] Project detected correctly
+- [ ] Related code and markdowns analyzed
+- [ ] `overview.md` generated
+- [ ] `features.md` generated
+- [ ] `case-matrix.md` generated with happy path, edge cases, errors, and messages
+- [ ] `e2e-runbook.md` generated
+- [ ] Playwright spec generated
+- [ ] `.srt` caption generated
+- [ ] Captions and descriptive texts reviewed with `humanizer` skill
+- [ ] Final human video generated when requested
+- [ ] `manifest.json` updated
+- [ ] Non-executable cases marked as `BLOCKED` with justification
+
+</system_instructions>