arn-spark-visual-readiness

Arness Visual Readiness

Validate and activate deferred visual testing layers after project milestones. When arn-spark-visual-strategy sets up a multi-layer testing strategy, Layer 1 (typically browser-based capture) is validated and activated immediately. Additional layers (e.g., native window capture) are marked as deferred because the project may not yet have the build pipeline, platform access, or tooling required to validate them. This skill is the checkpoint that evaluates whether deferred layers are now ready, validates them with a spike, and promotes them to active.

This is a conversational skill that runs in normal conversation (NOT plan mode). It uses the arn-spark-visual-test-engineer agent for layer validation spikes.

The primary artifacts are:

• Updated CLAUDE.md -- deferred layers promoted to active with validation evidence
• Updated strategy document -- validation results appended per layer
• Readiness report -- layer status table with evidence and recommendations

The core problem this solves: deferred visual testing layers sit dormant after arn-spark-visual-strategy because nothing re-evaluates whether the project has reached the point where those layers can be activated. This skill closes that gap by checking activation criteria, running validation spikes, and promoting layers that pass.

Prerequisites

Read the project's CLAUDE.md for a ## Arness section. If no ## Arness section exists or Arness Spark fields are missing, inform the user: "Arness Spark is not configured for this project yet. Run /arn-brainstorming to get started — it will set everything up automatically." Do not proceed without it.

Extract:

• Plans directory
• Vision directory (default: .arness/vision)
• Spikes directory (default: .arness/spikes) -- for validation spike workspaces
• Git / Platform

Check for ### Visual Testing subsection:

1. If found: parse all fields (see Step 1 for details)
2. If NOT found: "No visual testing configuration found in CLAUDE.md. Run /arn-spark-visual-strategy first to set up your visual testing strategy." Exit.

Workflow

Step 1: Load Visual Testing Config

Read CLAUDE.md ### Visual Testing section.

Parse top-level fields as Layer 1 config (always active):

• Strategy doc: path to the visual strategy document
• Baseline directory: path to baseline images
• Capture script: path to the capture script
• Compare script: path to the comparison script
• Layers: comma-separated list of layer names
• Diff threshold: pixel difference tolerance percentage
• Integration: manual / npm-script / ci / arness-pipeline

Scan for #### Layer N: subsections. For each subsection, extract per-layer fields:

• Status: active / deferred
• Capture script: path to the layer's capture script
• Compare script: path to the layer's comparison script
• Baseline directory: path to the layer's baselines
• Diff threshold: layer-specific threshold (or inherit top-level)
• Requires dev server: yes / no
• Activation criteria: free-text description of what must be true to activate
• Environment: target platform/OS for this layer
• Spike result: previous spike outcome (Validated / Partially validated / Failed / Deferred)

Build a layer list with all extracted data. Layer 1 is always the top-level config (implicit, always active). Additional layers come from #### Layer N: subsections.

If no ### Visual Testing found: suggest /arn-spark-visual-strategy and exit.

If no deferred layers: "All visual testing layers are active. No deferred layers to promote." Present a summary table of active layers and suggest /arn-code-review-implementation for a full multi-layer quality check. Exit.

Step 2: Validate Active Layers

For each active layer, verify the existing pipeline still works:

1. Run the layer's capture script against the development build (or prototype if dev build unavailable)
2. Run the layer's compare script against the baselines
3. Check baseline counts against the screen manifest (if baseline-manifest.json exists)
4. Report newly capturable screens that lack baselines (screens added since last baseline update)

Present results per active layer:

"Layer [N] ([Name]) -- Active:

• Capture: [PASS / FAIL] -- [N] screens captured
• Compare: [PASS / FAIL] -- [N] screens compared, [M] within threshold
• Baselines: [N] baselines / [M] screens in manifest ([coverage]%)
• New screens without baselines: [list or 'none']"

If an active layer's pipeline fails: report it as a WARNING but continue. Do not block deferred layer evaluation because an active layer has a transient issue.

Step 3: Check Activation Criteria

Read the readiness checklist:

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-visual-readiness/references/readiness-checklist.md

For each deferred layer:

1. Read the layer's Activation criteria: field from CLAUDE.md
2. Match the criteria text against the common patterns in the readiness checklist (Build Success, Platform Access, Tool Availability, CI Configuration)
3. Execute the concrete checks for each matching pattern:
4. Run commands to verify tool availability (which [tool], [tool] --version)
5. Check for build artifacts at expected paths
6. Test file transfer mechanisms for cross-environment layers
7. Verify CI workflow configuration if relevant
8. Collect evidence for each check
9. Journey upgrade check — If the layer has Interaction: static or no Interaction: field:
10. Run the UIA Availability readiness pattern (Pattern 6 from readiness-checklist.md)
11. Run the Journey Runner readiness pattern (Pattern 7 from readiness-checklist.md) — skip if no runner exists yet
12. On macOS: run the Accessibility Permissions pattern (Pattern 8 from readiness-checklist.md)
13. If UIA Availability passes (automation framework available, accessibility tree inspectable):

Inform the user: "This Layer 2 is currently configured for static screenshot capture. The platform's UI automation framework is available, which means journey-based interaction testing is possible. Journey mode walks through the app like a user — clicking buttons, filling forms, navigating screens — and captures screenshots at each step."

Ask (using AskUserQuestion):

"Would you like to upgrade to journey interaction mode?"

Options:

1. Yes — Upgrade to journey-based interaction testing
2. No — Keep static screenshot capture

• Record the user's choice. If yes, mark the layer for journey upgrade in Step 5.
• If UIA Availability fails, do not suggest the upgrade — static mode remains appropriate.

Present status per layer:

"Layer [N] ([Name]): Criteria '[activation criteria text]'

• [Check 1]: [PASS / FAIL] -- [evidence]
• [Check 2]: [PASS / FAIL] -- [evidence]
• Overall: [MET / NOT MET]"

If ambiguous (e.g., a tool is installed but version is uncertain, or platform access is partial): ask the user for explicit confirmation rather than assuming.

Step 4: Validate Deferred Layers

For each deferred layer whose activation criteria are met:

IMPORTANT: Run validation spikes sequentially, one at a time. Do NOT launch multiple arn-spark-visual-test-engineer agents in parallel or in the background. The agent needs Bash and Write tool access, which requires user permission approval. Parallel or background agents cannot surface permission prompts to the user, causing all tool calls to be denied.

For each qualifying layer:

1. Read the spike checklist:

> Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-visual-strategy/references/spike-checklist.md

1. Determine the spike workspace: [spikes-dir]/visual-readiness-spike-layer-[N]/

1. Invoke the arn-spark-visual-test-engineer agent via the Task tool (foreground, not background), passing the model from .arness/agent-models/spark.md as the model parameter (see `plugins/arn