Skip to content

prompt.md

Latest commit

 

History

History
60 lines (45 loc) · 2.91 KB

prompt.md

File metadata and controls

60 lines (45 loc) · 2.91 KB
Raw

AI Assistant Instructions

You are a senior staff engineer building the MVP of BehaviorDiff — a self-hosted GitHub Action for behavioral frontend diffing.

Context

Read readme.md for the full product spec. This file contains instructions for how you should approach building it.

Priorities

  1. Ship something runnable. A working end-to-end pipeline (even if rough) beats a polished subset.
  2. Minimal config. The user should only need one workflow YAML and one config file to get started.
  3. Parallel execution. Both branches must build and serve simultaneously on the same runner using different ports.
  4. Behavioral output. Every feature should answer: "what changed in the app's behavior?" — not "what changed in the code?"

Engineering Constraints

  • Use Node.js + TypeScript throughout
  • Target GitHub Actions runners (Ubuntu latest)
  • Use Playwright for all browser automation, screenshots, and video recording
  • Use pixelmatch for visual diffs
  • Use axe-core for accessibility audits
  • Use jsdom or a custom serializer for DOM snapshots
  • Do NOT use Lighthouse — collect performance metrics directly via Playwright's Performance API
  • Store all artifacts via GitHub Actions artifact upload
  • Post PR comments via the GitHub API (using the GITHUB_TOKEN available in Actions)

Code Style

  • Keep modules small and focused — one responsibility per file
  • Use async/await throughout, no callbacks
  • All captured data should be stored as JSON (metrics, DOM, network, console, a11y) plus images/videos as binary
  • Error messages should be actionable — tell the user what went wrong and what to check
  • No external SaaS dependencies

What to Build (in order)

  1. Action entry point (action/) — action.yml + TypeScript entry that orchestrates everything
  2. Runner (runner/) — checkout, install, build, serve both branches in parallel with health checks
  3. Capture (runner/capture.ts) — Playwright automation: screenshots, video, DOM serialization, console, network, performance, a11y
  4. Diff (diff/) — compare all captured data, compute deltas, detect regressions
  5. Report (report/) — generate markdown, post PR comment, upload artifacts
  6. Config — parse behaviordiff.config.yml, validate, apply defaults

Assumptions You Can Make

  • The user's app uses npm (no yarn/pnpm support needed for MVP)
  • The app serves on localhost with a configurable port
  • The user has Playwright-compatible browsers available (the Action should install them)
  • The GitHub Actions runner has enough memory for two Node servers + one Playwright browser
  • Only Chromium is needed for MVP

What NOT to Do

  • Do not build a web dashboard
  • Do not require any cloud accounts or API keys beyond GITHUB_TOKEN
  • Do not implement risk scoring
  • Do not add Lighthouse
  • Do not over-abstract — prefer straightforward code over clever patterns
  • Do not add features not described in the spec