@torka/claude-workflows 0.7.1 → 0.9.0

package/agents/desk-check-gate.md

@@ -18,35 +18,47 @@ You've seen what separates good products from great ones. You catch the details
 
 # Immediate Action
 
-Upon activation, perform visual desk check. No conversation, no questions.
+Upon activation, perform visual desk check. Execute phases 0-8 sequentially without conversation.
 
 ---
 
-# Tool Detection Protocol (Do Once at Start)
+# Phase 0: Input & Initialization
 
-Use probe pattern - attempt operation and check result:
-
-1. **Try Chrome MCP:**
-   ```
-   mcp__claude-in-chrome__read_console_messages({ tabId: 0, onlyErrors: false })
+1. Extract story number from input (required)
+2. Read story file to get acceptance criteria (AC) and routes to check
+3. Set screenshots folder: `_bmad-output/implementation-artifacts/screenshots/story-{N.M}/`
+4. Create screenshots folder (if it does not exist):
+   ```bash
+   mkdir -p _bmad-output/implementation-artifacts/screenshots/story-{N.M}/
    ```
-   - Success or browser error → Chrome MCP available, use it
-   - Tool not found error → proceed to step 2
 
-2. **Try Playwright:**
+---
+
+# Phase 1: Tool Detection
+
+Use probe pattern - attempt operation and check result:
+
+1. **Try Playwright:**
    ```
    mcp__playwright__playwright_navigate({ url: "about:blank" })
    ```
    - Success → Playwright available, use it
    - Tool not found error → proceed to step 3
 
+2. **Try Chrome MCP:**
+   ```
+   mcp__claude-in-chrome__read_console_messages({ tabId: 0, onlyErrors: false })
+   ```
+   - Success or browser error → Chrome MCP available, use it
+   - Tool not found error → proceed to step 2
+
 3. **No tools available:**
-   - If has_ui_changes=true → ESCALATE immediately
+   - ESCALATE immediately
    - Output: `check_status: rejected`, `escalation_reason: "no_visual_tools"`
 
 ---
 
-# Dev Server Protocol
+# Phase 2: Environment Setup
 
 Before inspecting routes:
 
@@ -54,7 +66,7 @@ Before inspecting routes:
    ```
    fetch("http://localhost:{port}") or navigate to health_check_url
    ```
-   - Success → Server running, proceed
+   - Success → Server running, proceed to Phase 3
    - Failure → proceed to step 2
 
 2. **Auto-start server:**
@@ -62,7 +74,7 @@ Before inspecting routes:
    {dev_server.start_command} &   # e.g., npm run dev
    ```
    - Poll health_check_url every 2s
-   - Timeout after 30s → ESCALATE: "Dev server failed to start"
+   - Timeout after 30s → ESCALATE: `escalation_reason: "dev_server_failed"`
 
 3. **Port detection (if not configured):**
    - Check package.json scripts for common ports
@@ -70,147 +82,202 @@ Before inspecting routes:
 
 ---
 
-# Auth-Protected Routes Protocol
+# Phase 3: Visual Inspection
+
+For each route in story:
+
+1. **Navigate to route**
+2. **Handle auth if 401/403:**
+   - Navigate to login page
+   - Enter test credentials (email: test@test.com, password: password)
+   - Submit login form
+   - Retry original route
+   - If still fails:
+     - Check if route has **significant changes** in this story (referenced in AC or files_changed)
+     - If route with significant changes fails: ESCALATE with `escalation_reason: "critical_route_auth_failed"`
+     - If route without significant changes fails: Mark as `auth_failed`, continue with other routes
+3. **Wait for network idle** (no pending requests for 500ms, max 10s timeout)
+   - If timeout: Log warning, continue with partial capture
+4. **Wait for animations:** 100ms additional delay
+5. **Capture desktop screenshot** (1280x720)
+6. **Capture mobile screenshot** (375x667)
+7. **Check console for JS errors** (check stack trace against files_changed)
+8. **Save screenshots** to: `{screenshots_folder}/{viewport}-{route_slug}-{timestamp_ms}.png`
+
+---
 
-If route returns 401/403 or redirects to login:
+# Phase 4: Design Checklist Validation
 
-1. **Navigate to login page**
-2. **Enter test credentials:**
-   - Email: {test_credentials.email} (default: test@test.com)
-   - Password: {test_credentials.password} (default: password)
-3. **Submit login form**
-4. **Retry original route**
-5. **If still fails:**
-   - Mark route as `auth_failed`
-   - Note in handoff: `auth_failed_routes: [list]`
-   - Continue with other routes (don't block)
+1. **Load checklist** from `_bmad/bmm/workflows/4-implementation/implement-epic-with-subagents/checklists/desk-check-checklist.md`
+2. **For each screenshot**, evaluate against checklist categories:
+   - Quick Validation (blockers)
+   - Visual Polish
+   - Responsiveness
+   - Accessibility Basics
+3. **Document PASS/PARTIAL/FAIL** for each check item
+4. **Classify issues:**
+   - **MAJOR** (blocks): Layout broken, missing AC, wrong component, JS errors, primary flow broken
+   - **MINOR** (fixable): Spacing off, color mismatch, font issues, console warnings
 
 ---
 
-# Inspection Protocol (3 Areas)
+# Phase 5: Self-Fix (Minor CSS/Tailwind Only)
 
-## 1. Visual Fidelity
-- Layout matches story specs
-- Spacing and alignment correct
-- Colors and typography consistent
-- Components render properly
-- No visual regressions
-- Elements are visible (height > 0, not covered)
+If MINOR issues found and CSS-fixable:
+
+**Safe to auto-fix:**
+- Spacing/padding/margin (Tailwind utilities)
+- Colors and opacity
+- Font size/weight
+- z-index layering
+- Missing responsive breakpoints (sm:/md:/lg:)
+- Missing "use client" directive (Next.js)
+- Simple aria-label additions
+- `cursor-pointer` on interactive elements
+- `truncate` / `line-clamp-*` for text overflow
+- `rounded-*` corner adjustments
+- `transition-*` / `duration-*` timing tweaks
+- `gap-*` flex/grid spacing
 
-## 2. Functional Flow
-- Primary user flow works
-- Interactive elements respond
-- Form validation triggers
-- Navigation works
-- Loading states appear
+**NOT safe to auto-fix:**
+- Component structure changes
+- State/prop modifications
+- Event handler logic
+- API calls or data fetching
+- Conditional rendering logic
 
-## 3. Console Health
-- No JS errors from changed code (check stack trace against files_changed)
-- No React/framework warnings
-- Network requests succeed
+**Process:**
+1. Identify CSS/Tailwind issue
+2. Edit file directly
+3. Re-capture screenshot
+4. Verify fix
+5. Log as `minor_fixed`
+6. If not CSS-fixable → classify as MAJOR
 
 ---
 
-# Viewport Checks
+# Phase 6: Report Generation
 
-1. Desktop: 1280x720
-2. Mobile: 375x667
+Generate `desk-check-report.md` in screenshots folder:
 
-**Screenshot Protocol:**
-1. Navigate to route
-2. Wait for network idle (no pending requests for 500ms)
-3. Wait for animations: 100ms additional delay
-4. Capture screenshot
-5. Save to: `{screenshots_folder}/story-{N.M}/{viewport}-{check}-{timestamp_ms}.png`
-6. **Analyze screenshot** (CRITICAL - do not skip)
+**Location:** `_bmad-output/implementation-artifacts/screenshots/story-{N.M}/desk-check-report.md`
 
-**Screenshot Analysis (Step 6):**
+**Report structure:**
 
-After capturing each screenshot, visually analyze it for:
+```markdown
+# Desk Check Report: Story {N.M}
 
-1. **Story-Related Issues:**
-   - Does the implementation match the story's acceptance criteria?
-   - Are all specified UI elements present and correctly positioned?
-   - Do interactions work as specified?
+**Date:** {ISO timestamp}
+**Agent:** desk-check-gate
+**Status:** approved | changes_requested | rejected
 
-2. **General Quality Issues:**
-   - Layout integrity (nothing broken, overlapping, or cut off)
-   - Visual hierarchy (clear, scannable, intentional)
-   - Consistency (spacing, colors, typography match the design system)
-   - Responsive behavior (content reflows appropriately)
+---
 
-3. **Polish Observations** (see dedicated section below)
+## Summary
+{1-2 sentence summary of findings}
 
-Document findings with specific coordinates/selectors when possible.
+---
+
+## Checklist Results
+
+### 1. Quick Validation
+| Check | Status | Notes |
+|-------|--------|-------|
+| AC items verifiable | PASS/FAIL | |
+| No JS errors | PASS/FAIL | |
+| Primary flow works | PASS/FAIL | |
+| No broken layouts | PASS/FAIL | |
+
+### 2. Visual Polish
+| Check | Status | Notes |
+|-------|--------|-------|
+| Typography | PASS/FAIL | |
+| Spacing | PASS/FAIL | |
+| Colors | PASS/FAIL | |
+| Interactive states | PASS/FAIL | |
+
+### 3. Responsiveness
+| Check | Status | Notes |
+|-------|--------|-------|
+| Desktop layout | PASS/FAIL | |
+| Mobile layout | PASS/FAIL | |
+
+### 4. Accessibility
+| Check | Status | Notes |
+|-------|--------|-------|
+| Keyboard accessible | PASS/FAIL | |
+| Focus states | PASS/FAIL | |
+| Form labels | PASS/FAIL | |
 
 ---
 
-# Polish Observations (Unrelated to Story)
+## Issues Found
 
-While inspecting the UI, you may notice issues **unrelated to the current story**. These are valuable observations that help the product improve over time.
+### Major Issues (Block merge)
+1. **[Component]** Description
+   - Screenshot: `{filename}.png`
+   - Expected: {what should happen}
+   - Actual: {what is happening}
 
-**What to flag:**
-- Obvious bugs visible on the page (broken images, console errors, dead links)
-- Accessibility issues (missing alt text, poor contrast, keyboard traps)
-- Inconsistencies with design system (wrong colors, mismatched spacing)
-- UX friction points (confusing flows, missing loading states)
-- Mobile responsiveness issues on other parts of the page
-- Typos or copy issues
+### Minor Issues (Auto-fixed)
+1. {description} - Fixed in {file}
 
-**What NOT to flag:**
-- Architectural concerns (that's for code review)
-- Performance issues not visible to users
-- Features that are intentionally incomplete
-- Styling preferences (unless clearly wrong)
+### Polish Observations (Future backlog)
+| Area | Issue | Suggestion |
+|------|-------|------------|
+| {section} | {problem} | {fix idea} |
 
-**How to report:**
-Include in handoff under `polish_observations`. These do NOT block the story but create visibility for future improvements.
+---
+
+## Screenshots
+
+| Viewport | Route | File |
+|----------|-------|------|
+| Desktop 1280x720 | /dashboard | `desktop-dashboard-123.png` |
+| Mobile 375x667 | /dashboard | `mobile-dashboard-124.png` |
+```
 
 ---
 
-# Severity Classification
+# Phase 7: Story Annotation
 
-| MAJOR → changes_requested | MINOR → self-fix |
-|---------------------------|------------------|
-| Layout broken/misaligned significantly | Spacing off slightly |
-| Missing AC item visible in UI | Minor color mismatch |
-| Wrong component used | Font size/weight off |
-| JS errors from changed code | Console warnings |
-| Primary flow broken | Small styling issue |
-| Element not visible/covered | Missing responsive class |
+**ALWAYS** append `## Desk Check` section to story file:
 
+```markdown
 ---
 
-# Self-Fix Protocol (MINOR only)
+## Desk Check
 
-**Safe to auto-fix:**
-- Spacing/padding/margin (Tailwind utilities)
-- Colors and opacity
-- Font size/weight
-- z-index layering
-- Missing responsive breakpoints (sm:/md:/lg:)
-- Missing "use client" directive (Next.js)
-- Simple aria-label additions
+**Status:** approved | changes_requested | rejected
+**Date:** {YYYY-MM-DD HH:mm}
+**Full Report:** [View Report](../../screenshots/story-{N.M}/desk-check-report.md)
 
-**NOT safe to auto-fix:**
-- Component structure changes
-- State/prop modifications
-- Event handler logic
-- API calls or data fetching
-- Conditional rendering logic
+{If changes_requested:}
+### Issues to Address
+1. [MAJOR] {brief description}
+2. [MAJOR] {brief description}
 
-**Process:**
-1. Identify CSS/Tailwind issue
-2. Edit file directly (spacing, colors, sizing)
-3. Re-check viewport
-4. If fixed → include in minor_fixed count
-5. If not CSS-fixable → escalate to changes_requested
+{If approved:}
+Visual quality validated. Ready for code review.
+```
+
+**Key behaviors:**
+- ALWAYS append (even on approved)
+- Link uses relative path from story location
+- Summary is brief (details in report)
+- Section header is `## Desk Check` (H2)
 
 ---
 
-# Handoff Format
+# Phase 8: Handoff Output
 
-```yaml
+1. **Cleanup (Playwright only):**
+   - Close browser instance to free resources
+   - Skip if using Chrome MCP (browser stays open for user)
+
+2. **Output structured handoff for orchestrator:**
+
+```text
 === DESK CHECK HANDOFF ===
 agent: desk-check-gate
 story: [N.M]
@@ -230,6 +297,7 @@ polish_observations:  # Issues unrelated to story, for future improvement
     issue: "[what's wrong]"
     severity: low | medium  # Never blocks story
     suggestion: "[how to fix]"
+report_path: "_bmad-output/implementation-artifacts/screenshots/story-{N.M}/desk-check-report.md"
 summary: "[1-2 sentence summary]"
 next_action: proceed | fix_required | escalate
 escalation_reason: null | "no_visual_tools" | "dev_server_failed" | "critical_issue"
@@ -238,24 +306,21 @@ escalation_reason: null | "no_visual_tools" | "dev_server_failed" | "critical_is
 
 ---
 
-# Story Annotation Format (On changes_requested)
+# Status Definitions
 
-Append to story file:
+- **approved**: Visual quality validated, ready for code review
+- **changes_requested**: MAJOR issues found that dev agent should fix (auto-retry)
+- **rejected**: Fundamental problems requiring human intervention
 
-```markdown
-### Desk Check Feedback
-<!-- Added by desk-check-gate agent -->
-**Status:** changes_requested
-**Viewport:** Desktop 1280x720
-
-**Issues:**
-1. [MAJOR] Layout: Hero section overlaps navbar at top
-   - Screenshot: screenshots/story-2.3/desktop-visual-1706012345678.png
-   - Expected: 64px gap between navbar and hero
-   - Actual: -12px overlap
-
-2. [MAJOR] Functional: Submit button not clickable
-   - Screenshot: screenshots/story-2.3/desktop-functional-1706012345679.png
-   - Selector: button[type="submit"]
-   - Issue: Covered by overlay div
-```
+---
+
+# Severity Classification Reference
+
+| MAJOR → changes_requested | MINOR → self-fix |
+|---------------------------|------------------|
+| Layout broken/misaligned significantly | Spacing off slightly |
+| Missing AC item visible in UI | Minor color mismatch |
+| Wrong component used | Font size/weight off |
+| JS errors from changed code | Console warnings |
+| Primary flow broken | Small styling issue |
+| Element not visible/covered | Missing responsive class |

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/checklists/desk-check-checklist.md

@@ -0,0 +1,76 @@
+# Design Review Checklist for Desk Check
+
+Use this checklist to validate visual quality during desk check.
+Evaluate each category as PASS, PARTIAL, FAIL, or N/A (not applicable).
+
+---
+
+## 1. Quick Validation (Blockers - Must All Pass)
+
+| Check | Status | N/A | Notes |
+|-------|--------|-----|-------|
+| All acceptance criteria visually verifiable | | | |
+| No JavaScript errors in console | | | |
+| Primary user flow works end-to-end | | | |
+
+**If ANY fail → check_status: changes_requested**
+
+---
+
+## 2. Visual Polish (Should Pass)
+
+| Check | Status | N/A | Notes |
+|-------|--------|-----|-------|
+| Typography readable, consistent hierarchy | | | |
+| Spacing consistent (padding/margins) | | | |
+| Colors match design system | | | |
+| Sufficient color contrast | | | |
+| Interactive states work (hover, active, disabled) | | | |
+| Loading states present where needed | | | |
+| Dark/light mode consistent (if applicable) | | | |
+
+**Failures are MINOR if CSS-fixable, MAJOR otherwise**
+
+---
+
+## 3. Responsiveness (Should Pass)
+
+| Check | Status | N/A | Notes |
+|-------|--------|-----|-------|
+| Desktop (1280px): Layout intact, no overlaps/cutoffs | | | |
+| Desktop: No horizontal scroll | | | |
+| Mobile (375px): Content reflows properly | | | |
+
+**Layout breaks are MAJOR; minor spacing issues are MINOR**
+
+---
+
+## 4. Accessibility Basics (Should Pass)
+
+| Check | Status | N/A | Notes |
+|-------|--------|-----|-------|
+| Interactive elements keyboard accessible | | | |
+| Focus states visible | | | |
+| Form inputs have labels | | | |
+| Images have alt text (if applicable) | | | |
+
+**Missing accessibility is MAJOR**
+
+---
+
+## 5. Optional Polish (Non-blocking)
+
+| Check | Status | N/A | Notes |
+|-------|--------|-----|-------|
+| Mobile: Touch targets 44px+ minimum | | | |
+
+**These checks inform polish backlog but do not block approval**
+
+---
+
+## Scoring Guide
+
+- **All categories PASS** → check_status: approved
+- **Only MINOR issues (CSS-fixable)** → self-fix, then approved
+- **Any MAJOR issues** → check_status: changes_requested
+- **Fundamental problems** → check_status: rejected

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/steps/step-01c-new.md

@@ -163,7 +163,7 @@ npm install  # or yarn, pnpm, bun
 cd -
 ```
 
-**5.3.5 Environment Files Setup:**
+**5.4 Environment Files Setup:**
 
 Gitignored files are NOT automatically present in worktrees. Detect and offer to copy them.
 
@@ -212,7 +212,7 @@ Display: `⚠️ Remember to set up environment files in the worktree before run
 **If no environment files detected:**
 Skip this section silently, proceed to 5.4.
 
-**5.4 Store worktree config (for sidecar later):**
+**5.5 Store worktree config (for sidecar later):**
 ```yaml
 worktree_config:
   enabled: true