@brunosps00/dev-workflow 1.1.3 → 1.2.0

package/scaffold/skills/dw-silent-failure/SKILL.md

@@ -31,3 +31,15 @@ Only flag a finding when you can name:
 - the minimal fix.
 
 Inspired by ECC's `silent-failure-hunter`; adapted as both a skill and a dispatchable `dw-silent-failure-hunter` agent.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when no concrete silent-failure risk is found, `FINDINGS` when at least one named risk exists, `BLOCKED` when failure paths cannot be inspected, `NOT_APPLICABLE` when no fallible control flow is in scope.
+- **Scope:** files/functions, failure paths, async boundaries, and IO surfaces inspected.
+- **Evidence:** exact location, trigger, hidden bad outcome, and current handling behavior.
+- **Artifacts:** review finding, bugfix task, regression guard, or log/trace path.
+- **Decisions:** why the issue is concrete enough to flag or why it is an explicit pass.
+- **Risks:** swallowed errors, false success, lost stack/context, untracked async work, or unsafe fallback.
+- **Next Step:** minimal fix or verification proving the pass.

package/scaffold/skills/dw-simplification/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dw-simplification
-description: Use when simplifying code. Chesterton's Fence (WHY first), behavior-preserving refactor, complexity metrics, deep-modules analysis. Triggers from /dw-review and /dw-brainstorm refactor-audit.
+description: Use when simplifying code. Chesterton's Fence (WHY first), behavior-preserving refactor, complexity metrics, deep-modules analysis. Triggers from /dw-review, /dw-refactor, and /dw-brainstorm refactor-audit.
 allowed-tools:
   - Read
   - Edit
@@ -18,7 +18,7 @@ Behavioral discipline for simplifying code without breaking it. The trap of refa
 Read this skill when:
 
 - `/dw-review --code-only` flagged a complexity issue (deep nesting, long function, duplication).
-- `/dw-brainstorm` dispatched its **refactor-audit** mode and proposed a simplification target.
+- `/dw-refactor` or `/dw-brainstorm` dispatched **refactor-audit** and proposed a simplification target.
 - The user explicitly asks to "clean this up" / "simplify X".
 - During `/dw-run` if the implementation accidentally produced complex code that wants pre-commit cleanup.
 
@@ -117,9 +117,9 @@ For changes that altered cyclomatic complexity, optionally run a complexity anal
 
 In the formal Level 3 review (post-Level 2 chain from `dw-review-implementation`), code-review flags complexity issues using the patterns above. Each flagged issue references this skill: "consider simplifying via guard clauses; apply Chesterton's Fence — verify why the nested check exists before flattening."
 
-## How `/dw-brainstorm` refactor-audit mode uses this
+## How `/dw-refactor` / refactor-audit uses this
 
-The refactor-audit mode dispatched by `/dw-brainstorm` catalogs code smells (Fowler vocabulary) AND runs the deep-modules analysis (`references/deep-modules.md`) against the target area. For each smell or shallow-module flag, the proposed refactor cites:
+`/dw-refactor` and the refactor-audit mode dispatched by `/dw-brainstorm` catalog code smells (Fowler vocabulary) AND run the deep-modules analysis (`references/deep-modules.md`) against the target area. For each smell or shallow-module flag, the proposed refactor cites:
 
 1. Which simplification rule applies (early return / extract method / lookup table / etc.).
 2. Whether Chesterton's Fence concerns block the refactor (existing tests inadequate? no recent commits explaining the structure? → flag as YELLOW, don't act).
@@ -138,10 +138,22 @@ The refactor-audit mode dispatched by `/dw-brainstorm` catalogs code smells (Fow
 - `references/chestertons-fence.md` — the protocol in detail; case studies of "obvious-but-wrong" removals.
 - `references/complexity-metrics.md` — when each metric (cyclomatic, cognitive, depth, fanout) actually matters; how to measure cheaply.
 - `references/behavior-preserving.md` — characterization tests, refactor with test gate, rollback patterns, codemod tooling per language.
-- `references/deep-modules.md` — high-leverage modules behind small interfaces; deletion test, locality, leverage, seam, adapter diagnostic; anti-patterns (shallow wrapper, god-module). Invoked by `/dw-brainstorm` refactor-audit mode.
+- `references/deep-modules.md` — high-leverage modules behind small interfaces; deletion test, locality, leverage, seam, adapter diagnostic; anti-patterns (shallow wrapper, god-module). Invoked by `/dw-refactor` and `/dw-brainstorm` refactor-audit mode.
 
 ## Inspired by
 
-Adapted from [`addyosmani/agent-skills/code-simplification`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT license). Core principles (Chesterton's Fence, behavior preservation, scope discipline, Rule of 500) preserved. dev-workflow integration: invoked by `dw-code-review` and `/dw-brainstorm` refactor-audit mode via Complementary Skills.
+Adapted from [`addyosmani/agent-skills/code-simplification`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT license). Core principles (Chesterton's Fence, behavior preservation, scope discipline, Rule of 500) preserved. dev-workflow integration: invoked by `/dw-review`, `/dw-refactor`, and `/dw-brainstorm` refactor-audit mode via Complementary Skills.
 
 The deep-modules reference is adapted from [`mattpocock/skills/improve-codebase-architecture`](https://github.com/mattpocock/skills/tree/main/improve-codebase-architecture) by Matt Pocock (MIT license). Core framing (deep modules = high leverage at small interface, deletion test, shallow-wrapper anti-pattern) preserved; paths and integration points rebased on dev-workflow conventions.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when simplification is safe and justified, `FINDINGS` when concrete refactor opportunities exist, `BLOCKED` when behavior or ownership is unclear, `NOT_APPLICABLE` when no simplification/refactor scope exists.
+- **Scope:** module, smell, complexity signal, and behavior boundary.
+- **Evidence:** code paths read, metrics, duplication, tests, and Chesterton's Fence rationale.
+- **Artifacts:** refactor recommendation, characterization test plan, codemod plan, or task list.
+- **Decisions:** simplify now, defer, split, preserve, or reject.
+- **Risks:** behavior drift, shallow wrapper churn, missing tests, or broad blast radius.
+- **Next Step:** smallest behavior-preserving refactor or prerequisite guard.

package/scaffold/skills/dw-simplification/references/deep-modules.md

@@ -2,7 +2,7 @@
 
 A **deep module** absorbs complexity behind a narrow public surface. Its callers see a small, stable API and get a lot of work done per call. A **shallow module** is the opposite — small interface AND small implementation, so it adds an indirection without absorbing any complexity. Or worse: a god-module, deep implementation BUT huge interface, where the surface itself is the complexity.
 
-The refactor-audit mode of `/dw-brainstorm` checks every candidate module against this framing alongside the Fowler smell taxonomy. A "code smell" can mislead if the construct is actually a deep wrapper doing its job correctly.
+`/dw-refactor` and the refactor-audit mode of `/dw-brainstorm` check every candidate module against this framing alongside the Fowler smell taxonomy. A "code smell" can mislead if the construct is actually a deep wrapper doing its job correctly.
 
 ## The premise
 

package/scaffold/skills/dw-source-grounding/SKILL.md

@@ -126,3 +126,15 @@ Already does multi-source research; gains the citation discipline. Each finding
 ## Inspired by
 
 Adapted from [`addyosmani/agent-skills/source-driven-development`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT license). Core protocol (Detect → Fetch → Implement → Cite) and source authority hierarchy preserved. dev-workflow integration: invoked by `dw-create-techspec`, `dw-deps-audit`, `dw-deep-research` via Complementary Skills, and citation format aligned with our existing report frontmatter conventions (`type: ...`, `schema_version: ...`).
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when the decision is source-grounded and cited, `FINDINGS` when citations are stale/weak, `BLOCKED` when required sources cannot be fetched, `NOT_APPLICABLE` when no external/source-sensitive decision exists.
+- **Scope:** decision, library/API/version, and source priority tier.
+- **Evidence:** URL, version, retrieval date, source tier, and quoted/paraphrased facts.
+- **Artifacts:** citation block, TechSpec/ADR entry, dependency note, or research report.
+- **Decisions:** accepted source, rejected source, and freshness judgment.
+- **Risks:** stale docs, unofficial authority, version mismatch, or uncited assumptions.
+- **Next Step:** fetch stronger source, cite, defer, or mark unverified.

package/scaffold/skills/dw-testing-discipline/SKILL.md

@@ -171,3 +171,15 @@ Any of these in a PR is enough to REJECT a verdict:
 ## Bottom line
 
 > A test that cannot fail is decorative. A test that fails for the wrong reason is misleading. Build tests that fail for exactly one reason — the reason the invariant was violated — and trust them when they do. Mocks isolate. Real systems validate. Coverage shines a light. Mutation score grades the suite. Agents will reach for the mock and the snapshot; the guardrails make them put both down. Tests reveal bugs, not just pass.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when tests target real behavior at the right layer, `FINDINGS` when test design gaps or anti-patterns remain, `BLOCKED` when the invariant or owning layer is unclear, `NOT_APPLICABLE` when no test work is in scope.
+- **Scope:** invariant, owning layer, suite/file, and workflow (`author`, `review`, `debug`, `flaky`).
+- **Evidence:** production behavior read, existing suite, execution output, anti-patterns, and guardrails checked.
+- **Artifacts:** test file, matrix, flaky quarantine note, mutation/coverage result, or QA log.
+- **Decisions:** placement, mock/real-system boundary, snapshot classification, and negative companion.
+- **Risks:** false confidence, flakiness, mock drift, implementation-detail coupling, or weak assertions.
+- **Next Step:** exact test edit, verification command, or clarification needed.

package/scaffold/skills/dw-testing-discipline/references/playwright-recipes.md

@@ -280,21 +280,20 @@ to pick a browser deterministically. Both `.dw/scripts/functional-doc/run-playwr
 (video, via `page.screencast`) and `.dw/scripts/lib/capture-screenshots.mjs` (responsive shots)
 use it, so the same rules apply everywhere.
 
-Resolution order: `BROWSER_TEST` env → `.dw/config.json` (`browserTest`) → default.
+Resolution order: Playwright Chromium default first → optional CDP fallback from `BROWSER_TEST` env
+or `.dw/config.json` (`browserTest`) only if the primary launch fails.
 
-- **Default (no config):** full Chromium in new-headless mode (`channel: "chromium"`) — desktop-faithful
+- **Default / primary:** full Chromium in new-headless mode (`channel: "chromium"`) — desktop-faithful
   rendering, never opens WSLg. This is the recommended default on WSL.
-- **`BROWSER_TEST` = CDP URL** (e.g. `http://localhost:9222`): connects with `chromium.connectOverCDP`.
-  Tries `127.0.0.1` first, then the Windows host (default-route gateway) for NAT.
-- **`BROWSER_TEST` = Windows exe** (e.g. `/mnt/c/.../msedge.exe`): launches it with a temp profile in
-  remote-debugging mode (`--remote-allow-origins=*`) and connects over CDP. **Works in both WSL2 modes:**
-  in mirrored networking it connects to `127.0.0.1` directly; in NAT mode it starts the bundled
-  **`cdp-relay.exe`** (a tiny prebuilt Windows x64 binary, no runtime) on Windows in reverse mode.
-  The relay opens outbound connections to a WSL broker, which exposes a local CDP proxy. Falls back
-  to headless Chromium if the relay is absent.
+- **`BROWSER_TEST` = CDP URL** (e.g. `http://localhost:9222`): fallback target using
+  `chromium.connectOverCDP` if the primary Chromium launch fails.
+- **`BROWSER_TEST` = Windows exe** (e.g. `/mnt/c/.../msedge.exe`): fallback target. The runner launches it
+  with a temp profile in remote-debugging mode (`--remote-allow-origins=*`) and connects over CDP. In NAT
+  mode it starts the bundled **`cdp-relay.exe`** on Windows in reverse mode; the relay opens outbound
+  connections to a WSL broker, which exposes a local CDP proxy.
 - **`BROWSER_TEST` = channel** (`chrome` | `msedge` | `chromium`): launches that channel locally.
 
-NAT mode needs a one-time user-level setup because Chromium binds its debug port to Windows loopback only:
+NAT mode needs this one-time user-level setup only if you want the Windows-browser CDP fallback:
 
 ```bash
 npx @brunosps00/dev-workflow setup-wsl-browser
@@ -302,16 +301,16 @@ npx @brunosps00/dev-workflow setup-wsl-browser
 
 This installs the `cdp-relay.exe` bundled with dev-workflow into `%LOCALAPPDATA%\dev-workflow`.
 No admin prompt, firewall rule, or Rust toolchain is required on the Windows target. After that,
-the *real* Windows browser is driven from WSL — including `page.screencast` video — under NAT.
+the *real* Windows browser is available as a fallback from WSL — including `page.screencast` video — under NAT.
 The launched browser and relay use a throwaway profile and are killed on exit.
 
 Two env vars, two jobs — keep them distinct:
 - `BROWSER` — opens URLs for a human (used by `/dw-generate-pr`).
-- `BROWSER_TEST` — the automation target for QA / functional-doc / redesign capture.
+- `BROWSER_TEST` — optional CDP fallback target for QA / functional-doc / redesign capture.
 
-To drive the real Windows browser, set `BROWSER_TEST` to its exe path (NAT works as long as `node` is on
-the Windows PATH; mirrored works too). To force the faithful local-headless path instead, leave
-`BROWSER_TEST` unset or set it to `chromium`.
+To make the real Windows browser available as fallback, set `BROWSER_TEST` to its exe path (NAT works
+as long as `node` is on the Windows PATH; mirrored works too). Leave `BROWSER_TEST` unset for the plain
+Playwright-default path.
 
 ```bash
 # Probe what would be used (cleans up any launched browser):

package/scaffold/skills/dw-ui-discipline/SKILL.md

@@ -155,3 +155,15 @@ In all bend cases, document the bend in the PR (one line). "I skipped the state
 The shorter route — "agent loads a 161-palette catalog and picks one" — produces dashboards that look like every other dashboard because the agent has no constraint that pulls it away from training-data centers of mass.
 
 The grounding pulls the design toward the specific surface, the specific user, the specific moment. Even with the same palette catalog, a "3am on-call dark room troubleshooting" design lands different choices than a "morning manager approving expenses" design. That difference is where surface quality lives.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when grounding, state coverage, accessibility, and visual review pass, `FINDINGS` when UI risks remain, `BLOCKED` when design authority or surface job is unclear, `NOT_APPLICABLE` when no UI surface is in scope.
+- **Scope:** screen/component, design authority, user job, state matrix, and device/context.
+- **Evidence:** design source read, four grounding answers, states checked, screenshots, and accessibility checks.
+- **Artifacts:** UI proposal, design notes, state matrix, screenshot path, or QA finding.
+- **Decisions:** palette/type/component choices, state handling, and accepted deviations.
+- **Risks:** training-data defaults, missing states, contrast/focus failures, unreadable hierarchy, or mobile overflow.
+- **Next Step:** exact design/code/QA action or missing input to gather.

package/scaffold/skills/dw-verify/SKILL.md

@@ -161,3 +161,13 @@ Verification failure is information, not a dead end. Protocol:
 Discover the project gate before claiming success. Prefer documented gates in `.dw/rules/`, then package scripts such as `verify`, `check`, `ci`, or `test`, then Makefile/just/pyproject equivalents. If no verification command exists, state that explicitly in the Verification Report and avoid completion language.
 
 Load `references/verification-discovery-and-attribution.md` when you need the full discovery checklist, command integration table, or attribution notes.
+
+## Structured Return
+
+- **Status:** `PASS` fresh gates prove the claim, `FINDINGS` fail/incomplete, `BLOCKED` no valid gate, `NOT_APPLICABLE` no claim.
+- **Scope:** claim, files, gates, environment.
+- **Evidence:** commands, exit codes, output, timestamps.
+- **Artifacts:** report, logs, screenshots, CI link.
+- **Decisions:** selected gate and skipped-gate reason.
+- **Risks:** stale output, partial runs, unverified generated files.
+- **Next Step:** rerun, fix, add gate, or name blocker.

package/scaffold/skills/humanizer/SKILL.md

@@ -75,3 +75,15 @@ Provide:
 2. Brief audit of what still sounds AI-generated
 3. Final rewrite
 4. Short change summary when useful
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when the final rewrite preserves meaning and voice, `FINDINGS` when prose issues remain, `BLOCKED` when audience/voice/source constraints are missing, `NOT_APPLICABLE` when no prose rewrite is in scope.
+- **Scope:** document, audience, intended voice, and sections edited.
+- **Evidence:** AI-writing tells found, source meaning preserved, and style constraints applied.
+- **Artifacts:** draft rewrite, audit, final rewrite, and change summary.
+- **Decisions:** tone choices, cuts, preserved terminology, and unresolved wording tradeoffs.
+- **Risks:** meaning drift, over-polishing, unsupported claims, or voice mismatch.
+- **Next Step:** accept final rewrite, provide missing voice sample, or revise named section.

package/scaffold/skills/remotion-best-practices/SKILL.md

@@ -61,3 +61,15 @@ Read individual rule files for detailed explanations and code examples:
 - [rules/parameters.md](rules/parameters.md) - Make a video parametrizable by adding a Zod schema
 - [rules/maps.md](rules/maps.md) - Add a map using Mapbox and animate it
 - [rules/voiceover.md](rules/voiceover.md) - Adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when relevant Remotion rules are selected and actionable, `FINDINGS` when implementation gaps remain, `BLOCKED` when composition/media requirements are missing, `NOT_APPLICABLE` when no Remotion/video work is in scope.
+- **Scope:** composition, media type, render target, and selected rules.
+- **Evidence:** project files, rule references, asset constraints, and render/test output when available.
+- **Artifacts:** implementation guidance, component/file path, render command, or asset list.
+- **Decisions:** selected rule set, animation/media approach, and rejected alternatives.
+- **Risks:** timing drift, asset decode failure, text overflow, render cost, or accessibility/caption gaps.
+- **Next Step:** exact rule file to read, code edit, or render validation command.

package/scaffold/skills/security-review/SKILL.md

@@ -329,3 +329,15 @@ If no vulnerabilities found, state: "No high-confidence vulnerabilities identifi
 - `terraform.md` - IaC security
 - `ci-cd.md` - Pipeline security
 - `cloud.md` - AWS/GCP/Azure security
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when no high-confidence security findings remain, `FINDINGS` when exploitable issues exist, `BLOCKED` when threat context or sensitive paths cannot be inspected, `NOT_APPLICABLE` when no security-relevant surface is in scope.
+- **Scope:** assets, trust boundaries, languages/frameworks, data classes, and threat model slice.
+- **Evidence:** file/line references, exploit path, affected data/actor, and reference category.
+- **Artifacts:** security findings, verification notes, remediation plan, or audit report.
+- **Decisions:** severity, confidence, exploitability, and false-positive rejection.
+- **Risks:** authz bypass, injection, secret exposure, SSRF, supply chain, logging, or misconfiguration.
+- **Next Step:** minimal remediation, verification, or explicit accepted risk owner.

package/scaffold/skills/vercel-react-best-practices/SKILL.md

@@ -150,3 +150,15 @@ For the complete guide with all rules expanded: `AGENTS.md`
 ## References
 
 - `references/perf-discipline.md` — workflow discipline (measure → identify → fix → verify → guard) that wraps the per-rule recipes above. Use when tackling performance work; cite the metric and tool before applying any rule. Adapted from [`addyosmani/agent-skills/performance-optimization`](https://github.com/addyosmani/agent-skills/tree/main/performance-optimization) (MIT).
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when selected rules are evidence-backed and verified, `FINDINGS` when React/Next.js performance issues remain, `BLOCKED` when baseline metrics or app context are missing, `NOT_APPLICABLE` when no React/Next.js performance surface is in scope.
+- **Scope:** route/component, framework mode, metric, and selected rule category.
+- **Evidence:** baseline measurement, trace/profile/build output, rule references, and affected code paths.
+- **Artifacts:** recommendation, code path, perf log, bundle report, or guard test.
+- **Decisions:** rule selected, metric target, and rejected optimizations.
+- **Risks:** premature optimization, hydration mismatch, cache staleness, bundle bloat, or rerender regressions.
+- **Next Step:** measure, apply rule, verify, or add regression guard.

package/scaffold/skills/vercel-react-best-practices/references/perf-discipline.md

@@ -119,4 +119,4 @@ Optimize in this order; don't jump to (5) before (1).
 
 ## Integration with dev-workflow
 
-Use with `dw-refactoring-analysis` when flagging perf-related smells: cite the metric, the measurement tool, and the suggested rule from the `rules/` directory. Without those three, a perf "smell" is a guess.
+Use with `/dw-refactor` when flagging perf-related smells: cite the metric, the measurement tool, and the suggested rule from the `rules/` directory. Without those three, a perf "smell" is a guess.