@brunosps00/dev-workflow 1.1.2 → 1.2.0

package/scaffold/skills/dw-llm-eval/SKILL.md

@@ -148,3 +148,15 @@ The oracle ladder fixes both: forces measurement, forces ANCHORED measurement (l
 ## Bottom line
 
 > An AI feature without an eval suite is a feature you can't ship safely. An eval suite without calibration is a number you can't trust. Build the dataset from real failures, climb the ladder from cheap to expensive, calibrate the judge against humans, and re-run before every model swap. The discipline is small; the absence of it is one of the largest sources of "we shipped and don't know if it's worse" experiences in the industry.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when eval strategy/results meet the feature gate, `FINDINGS` when eval gaps or regressions remain, `BLOCKED` when dataset/rubric/calibration is missing, `NOT_APPLICABLE` when no LLM/AI behavior is in scope.
+- **Scope:** feature, model path, dataset, oracle rungs, and command mode.
+- **Evidence:** dataset provenance, metrics, judge calibration, run logs, and failure cases.
+- **Artifacts:** eval plan, cases.jsonl, run JSONL, rubric, or QA log path.
+- **Decisions:** oracle rung selection, metric thresholds, and accepted deviations.
+- **Risks:** judge drift, synthetic-only cases, same-model judging, hallucination, or uncovered trajectories.
+- **Next Step:** add dataset case, run eval, calibrate judge, or block release.

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

@@ -193,3 +193,15 @@ Ported from Compozy's `cy-workflow-memory` skill (`/tmp/compozy/.agents/skills/c
 Credit: Compozy project (https://github.com/compozy/compozy).
 
 The Context Budget section adapts the context-loading discipline from [`tech-leads-club/agent-skills/tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) (CC-BY-4.0, Felipe Rodrigues). The target, the anti-co-load rules, and the "monitoring signal" framing come from there; the integration with two-tier memory and the specific file ceilings are dev-workflow-specific.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when memory is current and scoped correctly, `FINDINGS` when memory is stale/overloaded, `BLOCKED` when required task/project context is missing, `NOT_APPLICABLE` when no session memory is needed.
+- **Scope:** project memory, task memory, checkpoint, and files considered.
+- **Evidence:** memory entries read/written, stale facts removed, and promotion decision.
+- **Artifacts:** `.dw/STATE.md`, task `MEMORY.md`, checkpoint, or compaction note.
+- **Decisions:** promote, keep local, discard, or compact.
+- **Risks:** stale instructions, duplicated facts, leaked task-local context, or oversized memory.
+- **Next Step:** exact memory write, compaction, or checkpoint action.

package/scaffold/skills/dw-review-rigor/SKILL.md

@@ -14,7 +14,7 @@ A set of rules the caller applies while producing a review report. This skill do
 
 ## When Invoked
 
-By `/dw-review --code-only`, `/dw-review --coverage-only`, `/dw-brainstorm --refactor`. The caller has already identified a scope (files, a PR, a codebase area). This skill governs how findings are selected, deduplicated, ordered, and phrased.
+By `/dw-review --code-only`, `/dw-review --coverage-only`, `/dw-refactor`, and `/dw-brainstorm --mode=refactor-audit`. The caller has already identified a scope (files, a PR, a codebase area). This skill governs how findings are selected, deduplicated, ordered, and phrased.
 
 ## Required Inputs
 
@@ -124,7 +124,7 @@ The caller emits:
 
 - `/dw-review --code-only` — applies all five rules to its Level-3 review output; uses prior reports in `.dw/spec/*/reviews/` to dedupe across rounds.
 - `/dw-review --coverage-only` — applies de-dup + severity-ordering when listing gaps between PRD requirements and code.
-- `/dw-brainstorm --refactor` — applies rules 1, 2, 4, 5 when cataloging code smells (rule 3 adapts: a "smell" with a justifying ADR becomes a `low` finding at most).
+- `/dw-refactor` — applies rules 1, 2, 4, 5 when cataloging code smells (rule 3 adapts: a "smell" with a justifying ADR becomes a `low` finding at most).
 
 Callers should mention this skill in their "Skills Complementares" section.
 
@@ -137,3 +137,15 @@ Ported from Compozy's `cy-review-round` skill (`/tmp/compozy/.agents/skills/cy-r
 - No issue-file frontmatter (Compozy uses it to interoperate with its remediation engine; dev-workflow's remediation is manual or via `/dw-qa --fix`).
 
 Credit: Compozy project (https://github.com/compozy/compozy).
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when no defensible findings remain, `FINDINGS` when review findings exist, `BLOCKED` when diff/context is insufficient, `NOT_APPLICABLE` when no review is in scope.
+- **Scope:** diff range, files reviewed, prior rounds, and review mode.
+- **Evidence:** file/line references, behavior impact, and prior-round disposition.
+- **Artifacts:** review report, inline findings, or consolidation notes.
+- **Decisions:** finding severity/order, duplicate suppression, and false-positive rejection.
+- **Risks:** missing tests, unreviewed generated files, stale base branch, or non-defensible claims.
+- **Next Step:** exact fix, verification, or approval/block marker.

package/scaffold/skills/dw-search-first/SKILL.md

@@ -29,3 +29,15 @@ Use before writing custom infrastructure, adding an integration, choosing a depe
 - Build custom only after search channels were checked or explicitly unavailable.
 
 Inspired by ECC's `search-first`; adapted to compose with `dw-source-grounding`, `/dw-plan`, and `/dw-find-skills`.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when an `ADOPT`/`WRAP`/`COMPOSE`/`BUILD` decision is justified, `FINDINGS` when search gaps remain, `BLOCKED` when required search channels are unavailable, `NOT_APPLICABLE` when no new capability/dependency is being chosen.
+- **Scope:** capability, constraints, project area, and checked channels.
+- **Evidence:** repo hits, installed skills, `.dw/intel/`, package/docs links, or explicit unavailable-channel note.
+- **Artifacts:** TechSpec/ADR decision entry or dependency/reuse note.
+- **Decisions:** `ADOPT`, `WRAP`, `COMPOSE`, or `BUILD`, with rejected alternatives.
+- **Risks:** license, maintenance, dependency weight, version drift, or local reinvention.
+- **Next Step:** install/adapt/write decision record or ask for missing constraint.

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,38 +280,37 @@ 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 — `0.0.0.0:39222` → `127.0.0.1:<debug>` —
-  and connects via the Windows host gateway. Falls back to headless Chromium if the relay/rule 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 setup (the WSL **Hyper-V firewall** defaults inbound to Block, and Chromium
-binds its debug port to 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
 ```
 
-This installs the `cdp-relay.exe` bundled with dev-workflow and adds a Hyper-V firewall inbound allow
-rule for TCP 39222 (one UAC prompt). No 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 launched browser and relay use a
-throwaway profile and are killed on exit.
+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 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.