devvgwardo/blueprint-skill/blueprint-skill

Blueprint

A blueprint is two things that ship together:

1. The harness (in the repo, tools/blueprint/): scripts that drive the real thing and write raw

evidence (screenshots, recordings, exported files, JSON reports of pass/fail checks and measurements) to a gitignored blueprint-out/.

1. The report (docs/blueprint/<project>-blueprint.html + docs/blueprint/media/), viewable locally

and optionally published at a stable URL when the user requests publishing and a publisher is available. Every number, image and claim in it comes from the latest harness run. Nothing is estimated or copied from memory.

The point is trust: someone reading the page can see what the project does, how it's built, what was tested and what failed, what got fixed, and what to do next. The repo can regenerate all of it.

If the user has earlier blueprints (other repos with docs/blueprint/), read one before writing a new page and match its depth. The two flavours below describe what each kind contains.

Agent compatibility and prerequisites

This skill works in Claude Code and Hermes Agent. Hermes loads it with skill_view("blueprint"); use terminal for harness commands, read_file / search_files for repo evidence, and vision_analyze for screenshot review when available. Other agents use their equivalent tools. Resolve scripts/, templates/, and references/ relative to this skill's installed directory. Never assume Claude-only tools, a publisher, or another skill exists.

• Browser harness: the repo's Playwright dependency, Chrome, and an isolated app/test profile.
• Media helpers: Python + Pillow; ffmpeg for video helpers.
• Visual review: read references/visual-improvement-loop.md.

scripts/visual_evidence.py turns a capture report's PNGs into contact sheets, inspection crops, sampled animation GIFs, and matched before/after comparisons. scripts/visual_blueprint.py runs capture→gallery→opt-in review→finding history in one command. Manual review stays pending and exits 2; it never silently becomes a visual pass.

• Native desktop windows (optional): any screenshot driver that can target an exact

(pid, window_id), such as cua-driver. Run it on the host machine, not inside a VM/container.

Do not clear a user's localStorage, pair accounts, send messages, upload screenshots, publish, or take over their mouse/keyboard as part of a capture-only request. Use explicit, non-sensitive fixtures. Model-based screenshot review sends pixels to that model's provider; review only approved, non-sensitive images. Report unavailable capabilities as blocked, not passed.

Visual improvement loop (required for anything with a UI or visual output)

A source audit, green tests, preflight JSON, or "screenshots saved" is not a completed visual Blueprint. Take images, open their pixels, use what they show, then re-capture.

1. Capture before changing the product. Run the existing capture harness or build one. Capture

meaningful states, errors/empty states, real-use sizes, themes, and context. For motion, sample its beginning, anticipation, peak, handoff, end, and settle, not just one attractive frame.

1. Validate and index images. Save fresh PNGs plus stable image IDs, source/fixture type,

dimensions, input state, sample time, seed, and hashes. Decode images, reject empty/tampered evidence, and measure subject-specific checks. Missing screenshots are a failed capture, not a reason to ship a report without them. Start an isolated lab when one is available.

1. Actually look. Open every contact sheet and inspect the raw crop for anything suspicious.

Use your own image reading, vision_analyze, or a bounded image-only model review (agy). Track which sheets/image IDs were reviewed; file metadata or model prose without image access never counts as visual review.

1. Write actionable findings. Each finding needs an image ID/time and hash, visible issue,

impact, concrete proposed fix, and a re-capture/test that would verify it. Rank the top few. Distinguish subjective taste from measured bugs and label uncertain observations as candidates.

1. Improve when authorized. Choose one evidence-backed issue, make a scoped product change,

run its tests, re-capture with identical inputs, and show BEFORE / AFTER / DIFF. A nonzero pixel diff means "changed", not "better". Read the images again before accepting the fix.

1. Close the loop. Record resolved/persistent/new findings and links to the actual image

evidence. A text-only pass, partial review, or unverified after-state stays incomplete.

When the request is only to improve this skill, implement and validate the capture/review workflow and report its findings; do not silently redesign the user's product. If capture genuinely cannot run, report exactly what was tried and blocked. Never replace real images with generated artwork.

Pick the mode

Always check first whether a blueprint exists: inspect tools/blueprint/, docs/blueprint/, and their README for a saved URL. If Artifact tools are available, also list titles containing "Blueprint". If one exists, you're in feature-pass or refresh mode. A repo can have separate mobile, desktop, or subsystem reports; update the report owning this feature, not a duplicate.

Pick the flavour (or mix them)

• Product (anything with a UI or an output: web apps, editors, games, generators). Evidence comes

from driving the real app with Playwright in real Chrome: UI states, a render/output matrix, exports checked by an independent tool (ffprobe, file parsers), perf, edge cases, phone width, a recorded walkthrough.

• Platform audit (services, monorepos, infra). Evidence comes from the repo and its history: LOC by

area (excluding generated code), routes, tests, git growth, hot paths traced to file:line, security sweeps, flags. The core is a findings ledger: id, severity, effort, evidence anchor, concrete fix. Re-verify the highest-severity claims by hand before publishing.

Repo layout (create it if missing)

tools/blueprint/
  README.md          # what each script does + how to run (template: templates/tools-README.md)
  sweep.mjs          # UI states, output matrix, perf, edge cases   (template: templates/sweep.mjs)
  <feature>.mjs      # one script per feature pass                   (template: templates/feature.mjs)
  exports.mjs        # real outputs through the real UI, verified by an external tool
  mobile.mjs, walk.mjs (optional: phone layout, walkthrough recording)
  # Native desktop evidence may use Python + cua-driver instead of a browser script.
blueprint-out/       # GITIGNORED raw evidence: ui/ render/ mp4/ data/ walk/
docs/blueprint/
  <project>-blueprint.html   # the report source (template: templates/blueprint.html)
  media/                     # curated, compressed evidence the page references (jpg, 540-wide mp4)

Add blueprint-out to .gitignore. The app needs a small test hook so scripts can read state and set up fixtures without clicking through everything, e.g. window.__app = { store, getEngine, makeFixture }. Say in a comment that it's for automation.

Harness rules (these come from bugs we actually hit)