@brunosps00/dev-workflow 1.1.3 → 1.2.0

package/scaffold/pt-br/commands/dw-skill-health.md

@@ -10,8 +10,10 @@ Voce e o auditor de saude de skills e agentes do dev-workflow.
 1. Leia `scaffold/skill-registry.json` ao auditar o repo dev-workflow, ou `.dw/skill-registry.json` + `.agents/skills/` em projetos consumidores.
 2. Agrupe skills por `kind`: `protocol`, `domain-pack`, `recipe-pack`, `asset-pack`.
 3. Valide que toda skill tem trigger, output esperado, owner, load policy e limite de contexto.
-4. Aponte nomes duplicados, `SKILL.md` ausente, frontmatter ausente, `SKILL.md` grande demais, e references/assets lidos sem trigger especifico.
-5. Recomende manter, compactar entrypoint, mesclar, reclassificar, ou remover da visibilidade core.
+4. Valide que todo `SKILL.md` bundled tem contrato `## Structured Return` com `Status`, `Scope`, `Evidence`, `Artifacts`, `Decisions`, `Risks` e `Next Step`.
+5. Confirme que o vocabulario de `Status` esta explicito: `PASS`, `FINDINGS`, `BLOCKED`, `NOT_APPLICABLE`.
+6. Aponte nomes duplicados, `SKILL.md` ausente, frontmatter ausente, `SKILL.md` grande demais, metadata de output esperado desatualizada, e references/assets lidos sem trigger especifico.
+7. Recomende manter, compactar entrypoint, mesclar, reclassificar, adicionar retorno estruturado, ou remover da visibilidade core.
 
 ## Taxonomia
 
@@ -23,7 +25,13 @@ Voce e o auditor de saude de skills e agentes do dev-workflow.
 `SKILL.md` deve ser um roteador/protocolo curto. Regras longas, exemplos, paletas, receitas, services e assets ficam em references/assets/rules/recipes e sao carregados sob demanda.
 
 ## Saida
-Retorne um relatorio conciso. Nao delete arquivos.
+Retorne um relatorio conciso com uma secao de retorno estruturado. Nao delete arquivos.
+
+Inclua:
+- Status geral: `PASS`, `FINDINGS` ou `BLOCKED`.
+- Issues de registry/schema.
+- Cobertura de retorno estruturado, incluindo qualquer skill sem contrato ou vocabulario de status.
+- Top 3 fixes.
 
 Marcador final: `## SKILL-HEALTH COMPLETE`
 </system_instructions>

package/scaffold/pt-br/references/refactoring-catalog.md

@@ -1,6 +1,6 @@
 # Catálogo de Refatoração — Exemplos Antes/Depois
 
-Referência para `/dw-brainstorm --refactor`. Baseado no catálogo de Fowler.
+Referência para `/dw-refactor` e `/dw-brainstorm --mode=refactor-audit`. Baseado no catálogo de Fowler.
 
 ## 1. Função Longa → Extract Function
 

package/scaffold/pt-br/templates/constitution-template.md

@@ -71,7 +71,7 @@ mode: defaults | custom
 **P-008 — Queries N+1 são flagueadas em code review** (severity: info)
 **Regra:** Loops ou operações em lista que disparam chamadas DB/HTTP por item devem batchar (ex: `IN (...)`, `findMany`, DataLoader) ou ser explicitamente justificadas.
 **Why:** Padrões N+1 escalam linearmente com tamanho dos dados e silenciosamente degradam até que a carga de produção revele.
-**Enforcement:** `dw-code-review` e `dw-refactoring-analysis` detectam padrões await-em-loop contra módulos de repository / API client.
+**Enforcement:** `/dw-review` e `/dw-refactor` detectam padrões await-em-loop contra módulos de repository / API client.
 
 ---
 

package/scaffold/scripts/functional-doc/run-playwright-flow.mjs

@@ -6,10 +6,9 @@
 // which is the only mechanism that works over connectOverCDP (recordVideo does not).
 // Driving directly also removes the dependency on the project's playwright.config.*.
 //
-// Browser selection is delegated to ../lib/resolve-browser.mjs (WSL-resilient): a Windows
-// browser over CDP when reachable, otherwise the full headless Chromium (desktop-faithful,
-// no WSLg). The flow module is plain .mjs exporting `async function flow({ page, context,
-// expect, baseURL, step, shot })`.
+// Browser selection is delegated to ../lib/resolve-browser.mjs (WSL-resilient): Playwright
+// Chromium is primary, with a configured Windows/CDP target only as fallback. The flow module
+// is plain .mjs exporting `async function flow({ page, context, expect, baseURL, step, shot })`.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -79,22 +78,51 @@ async function importPlaywright() {
   }
 }
 
-async function openBrowser(chromium, descriptor) {
+async function openBrowser(chromium, descriptor, log) {
   if (descriptor.mode === "cdp") {
-    const browser = await chromium.connectOverCDP(descriptor.endpoint);
-    return { browser, cleanup: descriptor.cleanup ?? (async () => {}) };
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(descriptor.endpoint);
+    } catch (error) {
+      await (descriptor.cleanup ?? (async () => {}))();
+      throw error;
+    }
+    return { browser, descriptor, cleanup: descriptor.cleanup ?? (async () => {}) };
+  }
+  try {
+    const browser = await chromium.launch(descriptor.launchOptions);
+    return {
+      browser,
+      descriptor,
+      cleanup: async () => {
+        try {
+          await browser.close();
+        } catch {
+          // ignore
+        }
+      },
+    };
+  } catch (primaryError) {
+    if (typeof descriptor.openFallback !== "function") {
+      throw primaryError;
+    }
+    log(`browser launch failed (${primaryError.message}); trying CDP fallback from ${descriptor.fallback?.source ?? "config"}.`);
+    let fallbackDescriptor;
+    try {
+      fallbackDescriptor = await descriptor.openFallback();
+    } catch (fallbackError) {
+      throw new Error(`Playwright Chromium launch failed: ${primaryError.message}; CDP fallback failed: ${fallbackError.message}`);
+    }
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(fallbackDescriptor.endpoint);
+    } catch (error) {
+      await (fallbackDescriptor.cleanup ?? (async () => {}))();
+      throw new Error(`Playwright Chromium launch failed: ${primaryError.message}; CDP fallback failed: ${error.message}`);
+    }
+    log(`browser fallback: mode=${fallbackDescriptor.mode} source=${fallbackDescriptor.source}`);
+    return { browser, descriptor: fallbackDescriptor, cleanup: fallbackDescriptor.cleanup ?? (async () => {}) };
   }
-  const browser = await chromium.launch(descriptor.launchOptions);
-  return {
-    browser,
-    cleanup: async () => {
-      try {
-        await browser.close();
-      } catch {
-        // ignore
-      }
-    },
-  };
 }
 
 async function openContext(browser, descriptor, { resolution, baseURL }) {
@@ -168,15 +196,18 @@ async function main() {
   };
 
   const descriptor = await resolveBrowser({ projectRoot, headless: true });
-  log(`browser: mode=${descriptor.mode} source=${descriptor.source}`);
+  log(
+    `browser: mode=${descriptor.mode} source=${descriptor.source}` +
+      (descriptor.fallback ? ` fallback=${descriptor.fallback.source}` : ""),
+  );
   if (args.browserName && args.browserName !== "chromium") {
     log(`note: --browser-name=${args.browserName} ignored; screencast/CDP require Chromium.`);
   }
 
-  const { browser, cleanup: cleanupBrowser } = await openBrowser(chromium, descriptor);
-  const { context, owns: ownsContext } = await openContext(browser, descriptor, { resolution, baseURL });
+  const { browser, descriptor: activeDescriptor, cleanup: cleanupBrowser } = await openBrowser(chromium, descriptor, log);
+  const { context, owns: ownsContext } = await openContext(browser, activeDescriptor, { resolution, baseURL });
   const page = await context.newPage();
-  if (descriptor.mode === "cdp") {
+  if (activeDescriptor.mode === "cdp") {
     try {
       await page.setViewportSize({ width: resolution.width, height: resolution.height });
     } catch {
@@ -263,8 +294,8 @@ async function main() {
 
   updateManifest(manifestPath, {
     status,
-    browserMode: descriptor.mode,
-    browserSource: descriptor.source,
+    browserMode: activeDescriptor.mode,
+    browserSource: activeDescriptor.source,
     recording,
     videoResolution: resolution.label,
     video: videoExists ? videoPath : null,

package/scaffold/scripts/lib/capture-screenshots.mjs

@@ -62,6 +62,55 @@ function slugify(value) {
   );
 }
 
+async function openBrowser(chromium, descriptor) {
+  if (descriptor.mode === "cdp") {
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(descriptor.endpoint);
+    } catch (error) {
+      await (descriptor.cleanup ?? (async () => {}))();
+      throw error;
+    }
+    return { browser, descriptor, cleanup: descriptor.cleanup ?? (async () => {}) };
+  }
+  try {
+    const browser = await chromium.launch(descriptor.launchOptions);
+    return {
+      browser,
+      descriptor,
+      cleanup: async () => {
+        try {
+          await browser.close();
+        } catch {
+          // ignore
+        }
+      },
+    };
+  } catch (primaryError) {
+    if (typeof descriptor.openFallback !== "function") {
+      throw primaryError;
+    }
+    process.stderr.write(
+      `browser launch failed (${primaryError.message}); trying CDP fallback from ${descriptor.fallback?.source ?? "config"}.\n`,
+    );
+    let fallbackDescriptor;
+    try {
+      fallbackDescriptor = await descriptor.openFallback();
+    } catch (fallbackError) {
+      throw new Error(`Playwright Chromium launch failed: ${primaryError.message}; CDP fallback failed: ${fallbackError.message}`);
+    }
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(fallbackDescriptor.endpoint);
+    } catch (error) {
+      await (fallbackDescriptor.cleanup ?? (async () => {}))();
+      throw new Error(`Playwright Chromium launch failed: ${primaryError.message}; CDP fallback failed: ${error.message}`);
+    }
+    process.stderr.write(`browser fallback: mode=${fallbackDescriptor.mode} source=${fallbackDescriptor.source}\n`);
+    return { browser, descriptor: fallbackDescriptor, cleanup: fallbackDescriptor.cleanup ?? (async () => {}) };
+  }
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (!args.url) {
@@ -85,27 +134,17 @@ async function main() {
 
   fs.mkdirSync(outDir, { recursive: true });
   const descriptor = await resolveBrowser({ projectRoot: process.cwd(), headless: true });
-  process.stderr.write(`browser: mode=${descriptor.mode} source=${descriptor.source}\n`);
+  process.stderr.write(
+    `browser: mode=${descriptor.mode} source=${descriptor.source}` +
+      (descriptor.fallback ? ` fallback=${descriptor.fallback.source}` : "") +
+      "\n",
+  );
 
-  let browser;
-  let cleanup = async () => {};
-  if (descriptor.mode === "cdp") {
-    browser = await chromium.connectOverCDP(descriptor.endpoint);
-    cleanup = descriptor.cleanup ?? (async () => {});
-  } else {
-    browser = await chromium.launch(descriptor.launchOptions);
-    cleanup = async () => {
-      try {
-        await browser.close();
-      } catch {
-        // ignore
-      }
-    };
-  }
+  const { browser, descriptor: activeDescriptor, cleanup } = await openBrowser(chromium, descriptor);
 
   const shots = [];
   try {
-    const existing = descriptor.mode === "cdp" ? browser.contexts()[0] : null;
+    const existing = activeDescriptor.mode === "cdp" ? browser.contexts()[0] : null;
     const context = existing ?? (await browser.newContext());
     const ownsContext = !existing;
     const page = await context.newPage();

package/scaffold/scripts/lib/resolve-browser.mjs

@@ -3,19 +3,17 @@
 // Resolves which browser to drive for dev-workflow's browser-automation flows
 // (dw-qa, dw-functional-doc, dw-redesign-ui), with WSL resilience.
 //
-// Resolution order: env BROWSER_TEST -> .dw/config.json (browserTest) -> auto-detect.
-// On WSL with no explicit config, auto-detects a Windows browser (Edge first, then
-// Chrome) and launches it in remote-debugging mode so flows connect over CDP instead
-// of opening WSLg / losing layout fidelity in the bundled Linux Chromium.
+// Resolution order: Playwright Chromium primary -> optional CDP fallback from env
+// BROWSER_TEST or .dw/config.json (browserTest).
 //
 // Returns one of:
-//   { mode: "cdp",    endpoint, source, cleanup }   // connect over CDP (browser ready)
-//   { mode: "launch", launchOptions, source }        // let Playwright launch the browser
+//   { mode: "launch", launchOptions, source, fallback?, openFallback? } // let Playwright launch first
+//   { mode: "cdp",    endpoint, source, cleanup }                       // resolved fallback descriptor
 //
-// DEFAULT (no BROWSER_TEST): the full Playwright Chromium in headless via
-// channel:"chromium", which uses the new headless mode (desktop-faithful rendering,
-// not the lighter headless-shell) and never opens WSLg. This is the robust default on
-// WSL. Set BROWSER_TEST to opt into a Windows browser.
+// DEFAULT: full Playwright Chromium in headless via channel:"chromium", which uses the
+// new headless mode (desktop-faithful rendering, not the lighter headless-shell) and
+// never opens WSLg. BROWSER_TEST can provide a CDP/Windows-browser fallback when the
+// primary Playwright launch fails.
 //
 // NOTE on WSL networking: the Chromium debug port binds Windows loopback only. In mirrored
 // networking mode WSL shares that loopback, so 127.0.0.1 connects directly. In NAT mode the
@@ -548,21 +546,45 @@ async function launchWindowsBrowser(exePath, { headless, projectRoot }) {
 
 const noopCleanup = async () => {};
 
-function bundledDescriptor(headless, source = "bundled") {
+function bundledDescriptor(headless, source = "playwright-default") {
   return { mode: "launch", launchOptions: { ...BUNDLED_LAUNCH, headless }, source };
 }
 
-// When an explicit BROWSER_TEST cannot be honored, degrade to the headless default
-// (resilient) unless allowFallback is false (then throw, e.g. for diagnostics).
-function degradeOrThrow(message, { headless, allowFallback }) {
-  if (allowFallback) {
-    process.stderr.write(`resolve-browser: ${message} Falling back to headless Chromium.\n`);
-    return bundledDescriptor(headless, "fallback");
+function cdpFallbackInfo({ kind, source, value }) {
+  return { mode: "cdp", kind, source, value };
+}
+
+async function resolveCdpFallback({ kind, value, source, projectRoot, headless }) {
+  if (kind === "cdp") {
+    const url = new URL(value.replace(/^cdp:\/\//i, "http://"));
+    const port = Number(url.port) || 9222;
+    const found = await findReachableCdp(port, [url.hostname]);
+    if (!found) {
+      throw new Error(`CDP fallback '${value}' is not reachable (start the browser with --remote-debugging-port=${port}).`);
+    }
+    return { mode: "cdp", endpoint: found.base, source: `fallback:${source}`, cleanup: noopCleanup };
   }
-  throw new Error(message);
+
+  if (kind === "exe") {
+    if (!fs.existsSync(value)) {
+      throw new Error(`CDP fallback points to '${value}', but that file does not exist.`);
+    }
+    const descriptor = await launchWindowsBrowser(value, { headless, projectRoot });
+    return { ...descriptor, source: `fallback:${descriptor.source}` };
+  }
+
+  throw new Error(`Unsupported CDP fallback kind '${kind}'.`);
 }
 
-export async function resolveBrowser({ projectRoot, headless = true, allowFallback = true } = {}) {
+function withCdpFallback(primary, fallbackArgs) {
+  return {
+    ...primary,
+    fallback: cdpFallbackInfo(fallbackArgs),
+    openFallback: () => resolveCdpFallback(fallbackArgs),
+  };
+}
+
+export async function resolveBrowser({ projectRoot, headless = true } = {}) {
   const { value, source } = readConfigValue(projectRoot);
 
   if (!value) {
@@ -572,30 +594,11 @@ export async function resolveBrowser({ projectRoot, headless = true, allowFallba
   const kind = classifyValue(value);
 
   if (kind === "cdp") {
-    const url = new URL(value.replace(/^cdp:\/\//i, "http://"));
-    const port = Number(url.port) || 9222;
-    const found = await findReachableCdp(port, [url.hostname]);
-    if (!found) {
-      return degradeOrThrow(
-        `BROWSER_TEST endpoint '${value}' is not reachable (start the browser with --remote-debugging-port=${port}).`,
-        { headless, allowFallback },
-      );
-    }
-    return { mode: "cdp", endpoint: found.base, source, cleanup: noopCleanup };
+    return withCdpFallback(bundledDescriptor(headless), { kind, value, source, projectRoot, headless });
   }
 
   if (kind === "exe") {
-    if (!fs.existsSync(value)) {
-      return degradeOrThrow(`BROWSER_TEST points to '${value}', but that file does not exist.`, {
-        headless,
-        allowFallback,
-      });
-    }
-    try {
-      return await launchWindowsBrowser(value, { headless, projectRoot });
-    } catch (error) {
-      return degradeOrThrow(error.message, { headless, allowFallback });
-    }
+    return withCdpFallback(bundledDescriptor(headless), { kind, value, source, projectRoot, headless });
   }
 
   // channel: chrome | msedge | chromium

package/scaffold/skill-registry.json

@@ -240,7 +240,7 @@
       "trigger": "Security review, sensitive code, OWASP checks, auth/payment/input surfaces",
       "expected_output": "High-confidence security findings or explicit pass.",
       "load_policy": "lazy-references",
-      "context_limit": 12000,
+      "context_limit": 14000,
       "bundled": true
     },
     {

package/scaffold/skills/api-testing-recipes/SKILL.md

@@ -102,3 +102,15 @@ Per-recipe details in `references/auth-patterns.md`.
 ## Inspired by
 
 Hand-curated by dev-workflow. `.http` syntax follows the JetBrains HTTP Client / VSCode REST Client conventions. Per-stack recipes adapt patterns from each ecosystem's official testing docs (FastAPI testing tutorial, NestJS testing recipes, Microsoft.AspNetCore.Mvc.Testing docs, Axum testing examples).
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when a recipe and evidence path are selected, `FINDINGS` when API test gaps remain, `BLOCKED` when the stack or auth flow is unknown, `NOT_APPLICABLE` when no HTTP/API surface is in scope.
+- **Scope:** API surface, requirement/RF, auth mode, and selected recipe.
+- **Evidence:** route/schema/source files read and request/response logs or planned log path.
+- **Artifacts:** `.http` file, test file, matrix, or log path to create/update.
+- **Decisions:** why this recipe fits the stack and why alternatives were rejected.
+- **Risks:** credentials, environment dependencies, flaky external calls, or uncovered negative cases.
+- **Next Step:** exact command or file edit needed to execute the recipe.

package/scaffold/skills/docker-compose-recipes/SKILL.md

@@ -82,3 +82,15 @@ Each row points to `services/<name>.yml`.
 ## Inspired by
 
 Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `redis`, `mailhog/mailhog`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when service recipes and compose guidance are selected, `FINDINGS` when compose gaps remain, `BLOCKED` when required ports/secrets/envs are unknown, `NOT_APPLICABLE` when no local infrastructure service is in scope.
+- **Scope:** services, project mode (`dev`/`prod`), ports, volumes, and env files touched.
+- **Evidence:** existing compose files, service references, healthcheck needs, and conflicting ports.
+- **Artifacts:** compose snippets/files, `.env` keys, healthchecks, and follow-up reference files.
+- **Decisions:** selected service recipe, image tag policy, and any prod/dev transform.
+- **Risks:** secret leakage, readiness ambiguity, data persistence, mail routing, or destructive defaults.
+- **Next Step:** exact compose edit and validation command.

package/scaffold/skills/dw-codebase-intel/SKILL.md

@@ -11,7 +11,7 @@ allowed-tools:
 
 # dw-codebase-intel
 
-Bundled skill that gives dev-workflow native **codebase intelligence** — a queryable knowledge base of the project's stack, file graph, API surface, dependencies, and architecture. Other commands (`/dw-plan prd`, `/dw-plan techspec`, `/dw-review --code-only`, `/dw-brainstorm --refactor`, `/dw-brainstorm`, etc.) read from this index instead of re-exploring the codebase on every invocation.
+Bundled skill that gives dev-workflow native **codebase intelligence** — a queryable knowledge base of the project's stack, file graph, API surface, dependencies, and architecture. Other commands (`/dw-plan prd`, `/dw-plan techspec`, `/dw-review --code-only`, `/dw-opportunities`, `/dw-refactor`, `/dw-brainstorm`, etc.) read from this index instead of re-exploring the codebase on every invocation.
 
 ## Why a skill (not inline)
 
@@ -111,3 +111,15 @@ If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded
 Adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`gsd-intel-updater`) by gsd-build (MIT license). Core schemas (`files.json`, `apis.json`, `deps.json`, `stack.json`, `arch.md`) and incremental update protocol preserved. Path conventions changed from `.planning/intel/` to `.dw/intel/`. CLI tooling (`gsd-sdk query intel.*`) replaced by agent-driven inline operations (no separate runtime). The companion `gsd-codebase-mapper` agent (human-readable analysis docs) was NOT ported — its scope overlaps with the existing `/dw-analyze-project` command which writes to `.dw/rules/`.
 
 The `bugfixes.json` index and the `bugfix-history` / `risk-area` query shapes (see `references/query-patterns.md`) were added in v1.0.2 to enable cross-skill awareness of `.dw/bugfixes/` — adapted from the operational-memory pattern in [`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 original skill maintains a single `STATE.md`; dev-workflow splits this into project-level `.dw/STATE.md` (session continuity) and a queryable `bugfixes.json` (historical fixes), which compose with the existing per-PRD `MEMORY.md`.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when indexes are updated or the query answer is cited, `FINDINGS` when intel is stale/incomplete, `BLOCKED` when required project files cannot be read, `NOT_APPLICABLE` when the task does not need codebase intel.
+- **Scope:** index files, query type, module, and paths inspected.
+- **Evidence:** cited `.dw/intel/*` entries, source files, timestamps, or stale-index indicators.
+- **Artifacts:** updated index files, query answer, codemap, or bugfix index path.
+- **Decisions:** whether to rebuild, incrementally update, or answer from existing intel.
+- **Risks:** stale docs, missing generated files, broad reads, or uncited conclusions.
+- **Next Step:** exact index update, query refinement, or source read required.

package/scaffold/skills/dw-context-budget/SKILL.md

@@ -43,3 +43,15 @@ Return:
 5. What must remain loaded because commands depend on it.
 
 Inspired by ECC's `context-budget` and `strategic-compact` patterns; adapted for dev-workflow's `.dw/` scaffold and cross-platform wrappers.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when the budget is acceptable, `FINDINGS` when concrete savings exist, `BLOCKED` when files cannot be measured, `NOT_APPLICABLE` when context budget is not relevant.
+- **Scope:** commands, skills, agents, MCPs, and instruction files measured.
+- **Evidence:** largest files, duplicate content, loaded references, and approximate byte/token cost.
+- **Artifacts:** report path or inline budget table.
+- **Decisions:** what stays loaded, what moves behind lazy references, and what can merge/remove.
+- **Risks:** losing trigger clarity, hiding required instructions, or creating stale references.
+- **Next Step:** top compaction action with expected savings.

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

@@ -180,3 +180,15 @@ Adaptations for dev-workflow:
 - Integration points map to dev-workflow commands (`dw-brainstorm`, `dw-create-techspec`) instead of Compozy's idea-factory pipeline
 
 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 advisor positions and a recommendation are complete, `FINDINGS` when unresolved tensions remain, `BLOCKED` when inputs or constraints are missing, `NOT_APPLICABLE` when no high-impact tradeoff exists.
+- **Scope:** decision, constraints, advisors consulted, and artifact path.
+- **Evidence:** each advisor's cited position and the facts they used.
+- **Artifacts:** council report, debate notes, or decision summary path.
+- **Decisions:** recommended path, rejected alternatives, and what would change the call.
+- **Risks:** unresolved disagreement, missing stakeholder data, or unvalidated assumptions.
+- **Next Step:** concrete follow-up: accept, run experiment, gather data, or escalate.

package/scaffold/skills/dw-debug-protocol/SKILL.md

@@ -106,3 +106,15 @@ After 60 minutes stuck at step 2 (localize) or step 4 (root cause), surface the
 - Don't silently spin. Fresh eyes find what stuck eyes miss.
 
 This is not failure — it's protocol. Stuck > 1 hour is a signal, not a flaw.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when the bug is reproduced, root-caused, guarded, and verified, `FINDINGS` when a confirmed defect remains, `BLOCKED` when reproduction/localization is impossible, `NOT_APPLICABLE` when the task is not bug-shaped.
+- **Scope:** symptom, affected surface, environment, and triage step reached.
+- **Evidence:** reproduction command, failing output, localized files, and root-cause proof.
+- **Artifacts:** bugfix task/report, regression test, logs, or verification output.
+- **Decisions:** chosen fix path and rejected hypotheses.
+- **Risks:** non-reproducibility, partial guard coverage, rollback gaps, or hidden adjacent defects.
+- **Next Step:** next triage step or verification command.

package/scaffold/skills/dw-execute-phase/SKILL.md

@@ -131,3 +131,15 @@ If the executor exhausts its context budget mid-phase OR the user signals stop:
 ## Inspired by
 
 Adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) (`gsd-executor`, `gsd-plan-checker`) by gsd-build (MIT license). Core protocols (goal-backward verification, atomic commits, deviation handling, checkpoint resume) preserved. Path conventions changed from `.planning/<phase>/` to `.dw/spec/prd-<slug>/`. SDK CLI calls (`gsd-sdk query init.execute-phase`) replaced by inline operations. The companion `gsd-debugger` agent (1452 lines) was NOT ported — its scope overlaps with the existing `/dw-bugfix` and `/dw-qa --fix` commands.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when plan-check and execution wave complete, `FINDINGS` when deviations or failed tasks remain, `BLOCKED` when plan-check returns `REVISE`/`BLOCK`, `NOT_APPLICABLE` when no task execution is in scope.
+- **Scope:** PRD/spec slug, wave, tasks, dependencies, and agent roles.
+- **Evidence:** plan-check verdict, task files read, command outputs, and deviation notes.
+- **Artifacts:** changed files, task memory, checkpoint, deviations report, or commits.
+- **Decisions:** wave ordering, task split, and accepted deviations.
+- **Risks:** dependency drift, uncommitted work, skipped verification, or partial checkpoint.
+- **Next Step:** next task, commit, checkpoint, or revision needed.

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

@@ -121,3 +121,15 @@ Real-world software can't always be perfect:
 - [ ] No `--no-verify`
 - [ ] No amend of pushed commit
 - [ ] Branch name follows convention
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when the commit/PR plan is atomic and verified, `FINDINGS` when git hygiene gaps remain, `BLOCKED` when repository state is ambiguous, `NOT_APPLICABLE` when no git action is in scope.
+- **Scope:** branch, staged/unstaged files, intended commit/PR, and remote state.
+- **Evidence:** `git status`, diff summary, verification commands, and branch checks.
+- **Artifacts:** commit plan, commit hash, PR body, or branch hygiene report.
+- **Decisions:** commit split, message type/scope, and files intentionally excluded.
+- **Risks:** unrelated dirty files, skipped checks, pushed-history rewrite, or mixed intent.
+- **Next Step:** exact stage/commit/push/PR command or cleanup action.

package/scaffold/skills/dw-incident-response/SKILL.md

@@ -166,3 +166,15 @@ Files are committed to the repo alongside code — incidents are part of the pro
 ## Why this skill exists
 
 dev-workflow's existing surface is "build feature → ship." Nothing covered "production broke, what now?" Teams improvised postmortems, action items got lost, and the same bug recurred. This skill closes that loop: structured response in the moment, blameless reflection after, and cross-incident learning that feeds back into the project's constitution.
+
+## Structured Return
+
+When invoked directly or by a harness, return or merge this block:
+
+- **Status:** `PASS` when incident triage, resolution, comms, and follow-up are complete, `FINDINGS` when incident work remains, `BLOCKED` when severity/ownership/evidence is missing, `NOT_APPLICABLE` when no incident workflow is in scope.
+- **Scope:** incident id, severity, service, timeline window, and owner.
+- **Evidence:** symptoms, customer impact, logs/metrics, mitigation, and verification.
+- **Artifacts:** incident files, communication draft, action items, or postmortem path.
+- **Decisions:** severity, mitigation path, rollback/fix choice, and communication cadence.
+- **Risks:** recurring cause, incomplete customer notice, weak action items, or missing monitoring.
+- **Next Step:** next incident phase or postmortem/action-item owner.

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.