diff --git a/agents/gsd-ui-auditor.md b/agents/gsd-ui-auditor.md
index 9ad27bbf9..c066d1ac7 100644
--- a/agents/gsd-ui-auditor.md
+++ b/agents/gsd-ui-auditor.md
@@ -86,6 +86,46 @@ This gate runs unconditionally on every audit. The .gitignore ensures screenshot
+
+
+## Automated Screenshot Capture via Playwright-MCP (preferred when available)
+
+Before attempting the CLI screenshot approach, check whether `mcp__playwright__*`
+tools are available in this session. If they are, use them instead of the CLI approach:
+
+```
+# Preferred: Playwright-MCP automated verification
+# 1. Navigate to the component URL
+mcp__playwright__navigate(url="http://localhost:3000")
+
+# 2. Take desktop screenshot
+mcp__playwright__screenshot(name="desktop", width=1440, height=900)
+
+# 3. Take mobile screenshot
+mcp__playwright__screenshot(name="mobile", width=375, height=812)
+
+# 4. For specific components listed in UI-SPEC.md, navigate to each
+# component route and capture targeted screenshots for comparison
+# against the spec's stated dimensions, colors, and layout.
+
+# 5. Compare screenshots against UI-SPEC.md requirements:
+# - Dimensions: Is component X width 70vw as specified?
+# - Color: Is the accent color applied only on declared elements?
+# - Layout: Are spacing values within the declared spacing scale?
+# Report any visual discrepancies as automated findings.
+```
+
+**When Playwright-MCP is available:**
+- Use it for all screenshot capture (skip the CLI approach below)
+- Each UI checkpoint from UI-SPEC.md can be verified automatically
+- Discrepancies are reported as pillar findings with screenshot evidence
+- Items requiring subjective judgment are flagged as `needs_human_review: true`
+
+**When Playwright-MCP is NOT available:** fall back to the CLI screenshot approach
+below. Behavior is unchanged from the standard code-only audit path.
+
+
+
## Screenshot Capture (CLI only — no MCP, no persistent browser)
diff --git a/get-shit-done/workflows/ui-review.md b/get-shit-done/workflows/ui-review.md
index 2d23f166f..0f3a8e55f 100644
--- a/get-shit-done/workflows/ui-review.md
+++ b/get-shit-done/workflows/ui-review.md
@@ -146,6 +146,26 @@ Full review: {path to UI-REVIEW.md}
───────────────────────────────────────────────────────────────
```
+## Automated UI Verification (when Playwright-MCP is available)
+
+If `mcp__playwright__*` tools are accessible in this session:
+
+1. Navigate to each UI component described in the phase's UI-SPEC.md using
+ `mcp__playwright__navigate` (or equivalent Playwright-MCP tool).
+2. Take a screenshot of each component using `mcp__playwright__screenshot`.
+3. Compare against the spec's visual requirements — dimensions, color palette,
+ layout, spacing scale, and typography.
+4. Report any dimension, color, or layout discrepancies automatically as
+ additional findings within the relevant pillar section of UI-REVIEW.md.
+5. Flag items that require human judgment (brand feel, content tone) as
+ `needs_human_review: true` in the findings — these are surfaced to the user
+ separately after the automated pass completes.
+
+If Playwright-MCP is not available in this session, this section is skipped
+entirely. The audit falls back to the standard code-only review described above.
+No configuration change is required — the availability of `mcp__playwright__*`
+tools is detected at runtime.
+
## 5. Commit (if configured)
```bash
diff --git a/get-shit-done/workflows/verify-work.md b/get-shit-done/workflows/verify-work.md
index 57e23dc86..6ce61fc2d 100644
--- a/get-shit-done/workflows/verify-work.md
+++ b/get-shit-done/workflows/verify-work.md
@@ -86,6 +86,42 @@ Provide a phase number to start testing (e.g., /gsd:verify-work 4)
Continue to `create_uat_file`.
+
+**Automated UI Verification (when Playwright-MCP is available)**
+
+Before running manual UAT, check whether this phase has a UI component and whether
+`mcp__playwright__*` or `mcp__puppeteer__*` tools are available in the current session.
+
+```
+UI_PHASE_FLAG=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get workflow.ui_phase --raw 2>/dev/null || echo "true")
+UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
+```
+
+**If Playwright-MCP tools are available in this session (`mcp__playwright__*` tools
+respond to tool calls) AND (`UI_PHASE_FLAG` is `true` OR `UI_SPEC_FILE` is non-empty):**
+
+For each UI checkpoint listed in the phase's UI-SPEC.md (or inferred from SUMMARY.md):
+
+1. Use `mcp__playwright__navigate` (or equivalent) to open the component's URL.
+2. Use `mcp__playwright__screenshot` to capture a screenshot.
+3. Compare the screenshot visually against the spec's stated requirements
+ (dimensions, color, layout, spacing).
+4. Automatically mark checkpoints as **passed** or **needs review** based on the
+ visual comparison — no manual question required for items that clearly match.
+5. Flag items that require human judgment (subjective aesthetics, content accuracy)
+ and present only those as manual UAT questions.
+
+If automated verification is not available, fall back to the standard manual
+checkpoint questions defined in this workflow unchanged. This step is entirely
+conditional: if Playwright-MCP is not configured, behavior is unchanged from today.
+
+**Display summary line before proceeding:**
+```
+UI checkpoints: {N} auto-verified, {M} queued for manual review
+```
+
+
+
**Find what to test:**
diff --git a/tests/playwright-ui-verify.test.cjs b/tests/playwright-ui-verify.test.cjs
new file mode 100644
index 000000000..34392f3b2
--- /dev/null
+++ b/tests/playwright-ui-verify.test.cjs
@@ -0,0 +1,49 @@
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+
+describe('Playwright-MCP UI verification integration', () => {
+ test('verify-work.md mentions automated UI verification', () => {
+ const content = fs.readFileSync(
+ path.join(__dirname, '..', 'get-shit-done', 'workflows', 'verify-work.md'), 'utf-8'
+ );
+ assert.ok(
+ content.toLowerCase().includes('playwright') || content.includes('automated') && content.includes('UI'),
+ 'verify-work.md should mention automated UI verification option'
+ );
+ });
+
+ test('ui-review.md mentions Playwright-MCP when available', () => {
+ const content = fs.readFileSync(
+ path.join(__dirname, '..', 'get-shit-done', 'workflows', 'ui-review.md'), 'utf-8'
+ );
+ assert.ok(
+ content.toLowerCase().includes('playwright') || content.includes('mcp__playwright'),
+ 'ui-review.md should reference Playwright-MCP'
+ );
+ });
+
+ test('gsd-ui-auditor.md includes automated screenshot guidance', () => {
+ const content = fs.readFileSync(
+ path.join(__dirname, '..', 'agents', 'gsd-ui-auditor.md'), 'utf-8'
+ );
+ assert.ok(
+ content.toLowerCase().includes('playwright') || content.includes('screenshot') || content.includes('automated'),
+ 'gsd-ui-auditor.md should mention automated screenshot verification'
+ );
+ });
+
+ test('automated verification is optional/conditional (falls back to manual)', () => {
+ const verifyContent = fs.readFileSync(
+ path.join(__dirname, '..', 'get-shit-done', 'workflows', 'verify-work.md'), 'utf-8'
+ );
+ // Must include a fallback / "if available" conditional
+ const hasConditional =
+ verifyContent.includes('if available') ||
+ verifyContent.includes('when available') ||
+ verifyContent.includes('if Playwright') ||
+ verifyContent.includes('fall back');
+ assert.ok(hasConditional, 'Playwright integration must be conditional with manual fallback');
+ });
+});