From 96e9b4bf2f7527c55d2abb247940727096cd9e39 Mon Sep 17 00:00:00 2001 From: Darren Neimke Date: Tue, 20 Oct 2026 21:12:49 +1030 Subject: [PATCH 1/9] Update cursor rule with autonomous spec generation from raw feedback --- .cursor/rules/async-ux-pipeline.mdc | 51 +++++++++++++++++++++++ .cursor/skills/async-ux-pipeline/SKILL.md | 34 ++++++++------- 2 files changed, 70 insertions(+), 15 deletions(-) create mode 100644 .cursor/rules/async-ux-pipeline.mdc diff --git a/.cursor/rules/async-ux-pipeline.mdc b/.cursor/rules/async-ux-pipeline.mdc new file mode 100644 index 0000000..dbba98b --- /dev/null +++ b/.cursor/rules/async-ux-pipeline.mdc @@ -0,0 +1,51 @@ +--- +description: Async UX-to-Code Pipeline. Evaluates raw feedback, generates deterministic specs test-first, and automates visual proof. +globs: src/**/*,tests/**/*,scripts/**/* +alwaysApply: true +--- + +# Async UX-to-Code Pipeline + +Eliminate **"glue toil"** and enable **"Asynchronous Dispatch"**: the user spots friction on mobile or desktop, sends a 2-second screenshot or brief note, and walks away. The agent implements the smallest valid change, runs deterministic tests, captures automated Playwright visual snapshots, and opens a pull request ready for a 5-second review. + +## Repository Binding + +Read `AGENTS.md` (personas, journeys, push-back rules, 4-step blueprint) and `docs/design-language.md` (`.cursor/rules/design-language.mdc`) before changing markup, CSS, or JavaScript. + +### Stage 1: Autonomous Spec Generation from Raw Feedback +When the user provides raw, subjective, or high-level feedback (e.g. "Users can't find menu options" or "This screen feels crowded"): + +1. **Investigate Current State**: + - Inspect the relevant UI components, route tables, or layout styles in the repo before forming a plan. +2. **Diagnose the Root Friction**: + - Identify why the current implementation causes that symptom (e.g. deep nesting, ambiguous labels, lack of visual hierarchy). + - Evaluate against the target persona and push-back rules in `AGENTS.md` (e.g. eyes-on-pitch, config-over-code). +3. **Auto-Generate the 5-Part Spec**: + - Explicitly formulate and print the 5-part contract in your thinking trace: + • **Goal**: 1-sentence concrete UX fix. + • **Decisions**: Specific design pattern chosen (e.g. Command palette, flattened top-bar, contextual floating action). + • **Invariants**: Business rules, existing routes, or timers that must not break. + • **Specific Next Step**: The exact component test to write first. + • **Traps to Avoid**: Edge cases to steer clear of. +4. **Self-Direct Execution**: + - Proceed immediately to Stage 2, using your own generated spec as the deterministic boundary. + +### Stage 2: Design Language (Tokens Over Debate) +Follow `docs/design-language.md`: +- CSS tokens and semantic classes in `src/styles.css` (e.g. `btn-blue`, `team-color-*`, `--touch-min`). +- Tailwind utilities for layout and spacing only. +- $\ge 44\text{px}$ touch targets for all live-capture elements. +- Never invent new ad-hoc color classes or styling abstractions. + +### Stage 3: Test-First Discipline (Prevent Code Drift) +For behaviour (click handlers, state management, storage, DOM output): +1. Add or update a Jest test under `tests/` that mirrors the component in `src/`. +2. Run `npm test` and verify the test fails for the current behavior. +3. Implement the smallest change to make the test pass. +4. Run `npm test` to confirm all suites pass. + +### Stage 4: Automated Visual Proof (`npm run test:visual`) +Do not ask the user to open the app, refresh, or click through states. Use direct seeded URLs and run `npm run test:visual`. + +### Stage 5: Pull Request & Zero-Toil Review +Every change ships through a pull request on `feature/`. Never commit or push to `main`. diff --git a/.cursor/skills/async-ux-pipeline/SKILL.md b/.cursor/skills/async-ux-pipeline/SKILL.md index e55d75b..72aea81 100644 --- a/.cursor/skills/async-ux-pipeline/SKILL.md +++ b/.cursor/skills/async-ux-pipeline/SKILL.md @@ -15,20 +15,24 @@ Eliminate **"glue toil"** and enable **"Asynchronous Dispatch"**: the user spots Read `AGENTS.md` (personas, journeys, push-back rules, 4-step blueprint) and `docs/design-language.md` (`.cursor/rules/design-language.mdc`) before changing markup, CSS, or JavaScript. -## Stage 1: Product Triage & Spec (`a → b → c`) - -Before writing code, evaluate the request against `AGENTS.md`: - -1. **Persona & Journey (`a`)**: Identify the target persona (*Dedicated Analyst*, *Bench Coach*, *Drafted Helper*, or *Head Coach*) and journey. -2. **Audit & Push-Back Check (`b → c`)**: Inspect current code against the persona's quality bar and the **Push-Back Rules** in `AGENTS.md`: - - Does it add taps, dialogs, or shifting buttons during live capture? - - Can it be solved purely with a board JSON configuration (use `board-config-generator` instead)? - - Does it help an expert persona while overloading a casual coder or halftime coach? - - **If a rule is violated**: Stop and push back with the concrete tradeoff and a better alternative. -3. **Three-line spec (`c`)**: When the change is sound, state: - - **Problem**: which persona/journey is blocked or high-effort, and why. - - **Target state**: what the screen/code does after the change. - - **Verification**: the automated test and automated visual check that prove it. +## Stage 1: Autonomous Spec Generation from Raw Feedback + +When the user provides raw, subjective, or high-level feedback (e.g. "Users can't find menu options" or "This screen feels crowded"): + +1. **Investigate Current State**: + - Inspect the relevant UI components, route tables, or layout styles in the repo before forming a plan. +2. **Diagnose the Root Friction**: + - Identify why the current implementation causes that symptom (e.g. deep nesting, ambiguous labels, lack of visual hierarchy). + - Evaluate against the target persona and push-back rules in `AGENTS.md` (e.g. eyes-on-pitch, config-over-code). +3. **Auto-Generate the 5-Part Spec**: + - Explicitly formulate and print the 5-part contract in your thinking trace: + • **Goal**: 1-sentence concrete UX fix. + • **Decisions**: Specific design pattern chosen (e.g. Command palette, flattened top-bar, contextual floating action). + • **Invariants**: Business rules, existing routes, or timers that must not break. + • **Specific Next Step**: The exact component test to write first. + • **Traps to Avoid**: Edge cases to steer clear of. +4. **Self-Direct Execution**: + - Proceed immediately to Stage 2, using your own generated spec as the deterministic boundary. ## Stage 2: Design Language (Tokens Over Debate) @@ -65,7 +69,7 @@ Run the automated visual snapshot tool: ```bash npm run test:visual ``` -This boots a headless Chromium instance via Playwright, renders the views across **mobile (390x844)** and **desktop (1280x800)**, and outputs PNG artifacts to `.visual-proof/`. +This boots a headless Chromium instance via Playwright, renders the views across **mobile (390x844)** and **desktop (1280x800)**, and outputs PNG artifacts to `.visual-proof/` and `./diff.png`. ## Stage 5: Pull Request & Zero-Toil Review From 41a0342bcab43e363f7b4c9af41dd2bfb4157ab6 Mon Sep 17 00:00:00 2001 From: Darren Neimke Date: Tue, 20 Oct 2026 21:14:09 +1030 Subject: [PATCH 2/9] Adopt full Async UX-to-Code Pipeline cursor rule specification --- .cursor/rules/async-ux-pipeline.mdc | 89 +++++++++++++++-------------- 1 file changed, 46 insertions(+), 43 deletions(-) diff --git a/.cursor/rules/async-ux-pipeline.mdc b/.cursor/rules/async-ux-pipeline.mdc index dbba98b..e13b6aa 100644 --- a/.cursor/rules/async-ux-pipeline.mdc +++ b/.cursor/rules/async-ux-pipeline.mdc @@ -1,51 +1,54 @@ --- -description: Async UX-to-Code Pipeline. Evaluates raw feedback, generates deterministic specs test-first, and automates visual proof. -globs: src/**/*,tests/**/*,scripts/**/* -alwaysApply: true +description: Async UX-to-Code Pipeline for Coaches Dashboard and simple-coding. Use when reporting UI/UX friction, implementing component changes, or dispatching asynchronous coding tasks without manual browser hovering. +globs: src/**/*, components/**/*, app/**/*, pages/**/*, scripts/**/* --- -# Async UX-to-Code Pipeline +# Cursor Rule: Async UX-to-Code Pipeline -Eliminate **"glue toil"** and enable **"Asynchronous Dispatch"**: the user spots friction on mobile or desktop, sends a 2-second screenshot or brief note, and walks away. The agent implements the smallest valid change, runs deterministic tests, captures automated Playwright visual snapshots, and opens a pull request ready for a 5-second review. +## 1. Operating Mindset: Asynchronous Execution +You are operating as an autonomous software engineer in an **asynchronous dispatch pipeline**. The human founder dispatches a task and closes their laptop to reclaim daylight. -## Repository Binding +Your mandate is to take a raw friction report (screenshot, voice note, or bullet points), translate it into a formal specification, implement it test-first, and produce an **automated visual proof artifact** so the founder never has to manually refresh Chrome, log in, or click through test states. -Read `AGENTS.md` (personas, journeys, push-back rules, 4-step blueprint) and `docs/design-language.md` (`.cursor/rules/design-language.mdc`) before changing markup, CSS, or JavaScript. +## 2. The 4-Stage Execution Pipeline ### Stage 1: Autonomous Spec Generation from Raw Feedback -When the user provides raw, subjective, or high-level feedback (e.g. "Users can't find menu options" or "This screen feels crowded"): - -1. **Investigate Current State**: - - Inspect the relevant UI components, route tables, or layout styles in the repo before forming a plan. -2. **Diagnose the Root Friction**: - - Identify why the current implementation causes that symptom (e.g. deep nesting, ambiguous labels, lack of visual hierarchy). - - Evaluate against the target persona and push-back rules in `AGENTS.md` (e.g. eyes-on-pitch, config-over-code). -3. **Auto-Generate the 5-Part Spec**: - - Explicitly formulate and print the 5-part contract in your thinking trace: - • **Goal**: 1-sentence concrete UX fix. - • **Decisions**: Specific design pattern chosen (e.g. Command palette, flattened top-bar, contextual floating action). - • **Invariants**: Business rules, existing routes, or timers that must not break. - • **Specific Next Step**: The exact component test to write first. - • **Traps to Avoid**: Edge cases to steer clear of. -4. **Self-Direct Execution**: - - Proceed immediately to Stage 2, using your own generated spec as the deterministic boundary. - -### Stage 2: Design Language (Tokens Over Debate) -Follow `docs/design-language.md`: -- CSS tokens and semantic classes in `src/styles.css` (e.g. `btn-blue`, `team-color-*`, `--touch-min`). -- Tailwind utilities for layout and spacing only. -- $\ge 44\text{px}$ touch targets for all live-capture elements. -- Never invent new ad-hoc color classes or styling abstractions. - -### Stage 3: Test-First Discipline (Prevent Code Drift) -For behaviour (click handlers, state management, storage, DOM output): -1. Add or update a Jest test under `tests/` that mirrors the component in `src/`. -2. Run `npm test` and verify the test fails for the current behavior. -3. Implement the smallest change to make the test pass. -4. Run `npm test` to confirm all suites pass. - -### Stage 4: Automated Visual Proof (`npm run test:visual`) -Do not ask the user to open the app, refresh, or click through states. Use direct seeded URLs and run `npm run test:visual`. - -### Stage 5: Pull Request & Zero-Toil Review -Every change ships through a pull request on `feature/`. Never commit or push to `main`. +When the user provides raw, subjective, or high-level feedback (e.g. "Users can't find menu options" or "This screen feels crowded") or a 5-part brief: +1. **Investigate Current State**: Inspect the relevant UI components, route tables, or layout files in the repo before forming a plan. +2. **Diagnose the Root Friction**: Identify why the current implementation causes that symptom (e.g. deep menu nesting, ambiguous labels, lack of visual hierarchy). +3. **Auto-Generate the 5-Part Spec**: Explicitly formulate and output the 5-part contract in your thinking trace: + - **Goal**: 1-sentence concrete outcome. + - **Decisions**: Specific UI pattern chosen (e.g. Command palette, flattened top-bar, contextual floating action). + - **Invariants**: Business rules, existing routes, or timers that must not break. + - **Specific Next Step**: The exact component test to write first. + - **Traps to Avoid**: Edge cases to steer clear of. +4. **Self-Direct Execution**: Proceed immediately to Stage 2, using your own generated spec as the deterministic boundary. + +### Stage 2: Design Token & UI Primitive Enforcement +Do not invent arbitrary styles or nested CSS abstractions. +* **Component Primitives**: Always reuse existing UI components and primitives (``, ``, ``, ``). +* **Tailwind Consistency**: Use project token scales for spacing (`p-2`, `p-4`, `gap-3`), typography (`text-xs`, `text-sm`, `font-semibold`), and elevation (`bg-slate-900`, `border-slate-800`). +* **Ergonomics**: Maintain high contrast for sunlight readability and ensure touch targets $\ge$ 48px. + +### Stage 3: Test-First Agent Handoff (The Deterministic Gate) +Before touching production component code: +1. **Write or Update a Component Test**: Create a Vitest/Jest test asserting the desired behavior (use `vi.useFakeTimers()` or Jest fake timers for clocks/timers). +2. **Verify Failure**: Run the test to ensure it fails on the current implementation. +3. **Implement Minimum Code**: Write the cleanest solution to make the test pass. Do not touch unreachable code or add speculative features. + +### Stage 4: Automated Visual Verification (No Manual Chrome Clicking) +Never ask the user to "open localhost:3000 and click through to verify." +1. **Support Seeded Mock Routes**: Ensure dev preview routes support query-state seeding (e.g., `/dev/preview?state=double-up-selections` or `?mock=pc-counter`). +2. **Generate a Playwright / Puppeteer Screenshot**: Execute an automated script to load the dev URL, wait for network idle, take a focused snapshot of the modified component or screen, and save it to `./diff.png`. +3. **Output the Visual Proof**: State clearly in your final response: + - Test suite status (all green). + - File path to the generated `./diff.png` screenshot for instant 5-second human inspection. + +## 3. Completion Checklist (Self-Gate Before Replying) +Before concluding your task, verify: +* [ ] No regression on existing unit or integration tests (`npm test`). +* [ ] Invariants preserved (timer integrity, event schemas, double-up tags). +* [ ] Zero arbitrary inline styles or unvetted CSS classes. +* [ ] Seeded mock test state loads cleanly without auth blockers. +* [ ] Visual diff artifact generated and saved to disk. +* [ ] Summary provided in under 10 lines of concise markdown. From 3f49d36c475b1e46317eb6e2d6c8a89585bbfb7c Mon Sep 17 00:00:00 2001 From: Darren Neimke Date: Wed, 21 Oct 2026 18:32:51 +1030 Subject: [PATCH 3/9] feat(boards): protect default coding forms and add starter presets --- src/components/config.js | 30 +++++++++++- src/index.html | 37 +++++++++++++- src/main.js | 86 ++++++++++++++++++++++++++++++++- tests/components/config.test.js | 60 +++++++++++++++++++++-- 4 files changed, 206 insertions(+), 7 deletions(-) diff --git a/src/components/config.js b/src/components/config.js index 55f78b0..451e4a5 100644 --- a/src/components/config.js +++ b/src/components/config.js @@ -82,12 +82,37 @@ const HOCKEY_ONE_ZONED_CONFIG = { ] }; +const SIMPLE_STARTER_CONFIG = { + rowDefs: [ + { gridCols: "grid-cols-2", buttons: ["START", "END"].map(code => ({ event: code, text: code, color: "btn-gray", ...clipTiming(code) })) }, + { team: 1, grids: [{ gridCols: "grid-cols-3", buttons: slotButtons(["A25E", "CE", "SHOT", "PC", "GOAL", "CARD"]) }] }, + { team: 2, grids: [{ gridCols: "grid-cols-3", buttons: slotButtons(["A25E", "CE", "SHOT", "PC", "GOAL", "CARD"]) }] } + ] +}; + const DEFAULT_CONFIG = HOCKEY_ONE_ZONED_CONFIG; const BUILT_IN_NAMED_CONFIGS = { - 'hockey-one-zoned': HOCKEY_ONE_ZONED_CONFIG + 'hockey-one-zoned': HOCKEY_ONE_ZONED_CONFIG, + 'simple-starter': SIMPLE_STARTER_CONFIG }; +export function isBuiltInConfig(name) { + const trimmed = String(name ?? '').trim(); + return Boolean(trimmed && BUILT_IN_NAMED_CONFIGS[trimmed]); +} + +export function resetNamedConfigToDefault(name) { + const trimmed = String(name ?? '').trim(); + if (!isBuiltInConfig(trimmed)) { + throw new Error(`"${trimmed}" is not a built-in configuration.`); + } + const configs = readNamedConfigs(); + configs[trimmed] = cloneConfig(BUILT_IN_NAMED_CONFIGS[trimmed]); + writeNamedConfigs(configs); + return cloneConfig(BUILT_IN_NAMED_CONFIGS[trimmed]); +} + // Names that used to be seeded. An unchanged copy is removed; a saved edit under that name is kept. export const RETIRED_BUILT_IN_CONFIGS = { default: LEGACY_DEFAULT_CONFIG, @@ -269,6 +294,9 @@ export function saveNamedConfig(name, config) { if (!trimmedName) { throw new Error('Configuration name is required.'); } + if (isBuiltInConfig(trimmedName)) { + throw new Error(`Cannot overwrite built-in configuration "${trimmedName}". Use "Save as" to save under a new name.`); + } validateConfig(config); const configs = readNamedConfigs(); diff --git a/src/index.html b/src/index.html index 093d239..a5b88fb 100644 --- a/src/index.html +++ b/src/index.html @@ -80,6 +80,7 @@
+ Customize
- +
+ + +
+ +
+
+
+ + + +
+
+ + + +
+
+
+
`, ``). -* **Tailwind Consistency**: Use project token scales for spacing (`p-2`, `p-4`, `gap-3`), typography (`text-xs`, `text-sm`, `font-semibold`), and elevation (`bg-slate-900`, `border-slate-800`). -* **Ergonomics**: Maintain high contrast for sunlight readability and ensure touch targets $\ge$ 48px. - -### Stage 3: Test-First Agent Handoff (The Deterministic Gate) -Before touching production component code: -1. **Write or Update a Component Test**: Create a Vitest/Jest test asserting the desired behavior (use `vi.useFakeTimers()` or Jest fake timers for clocks/timers). -2. **Verify Failure**: Run the test to ensure it fails on the current implementation. -3. **Implement Minimum Code**: Write the cleanest solution to make the test pass. Do not touch unreachable code or add speculative features. - -### Stage 4: Automated Visual Verification (No Manual Chrome Clicking) -Never ask the user to "open localhost:3000 and click through to verify." -1. **Support Seeded Mock Routes**: Ensure dev preview routes support query-state seeding (e.g., `/dev/preview?state=double-up-selections` or `?mock=pc-counter`). -2. **Generate a Playwright / Puppeteer Screenshot**: Execute an automated script to load the dev URL, wait for network idle, take a focused snapshot of the modified component or screen, and save it to `./diff.png`. -3. **Output the Visual Proof**: State clearly in your final response: - - Test suite status (all green). - - File path to the generated `./diff.png` screenshot for instant 5-second human inspection. - -## 3. Completion Checklist (Self-Gate Before Replying) -Before concluding your task, verify: -* [ ] No regression on existing unit or integration tests (`npm test`). -* [ ] Invariants preserved (timer integrity, event schemas, double-up tags). -* [ ] Zero arbitrary inline styles or unvetted CSS classes. -* [ ] Seeded mock test state loads cleanly without auth blockers. -* [ ] Visual diff artifact generated and saved to disk. -* [ ] Summary provided in under 10 lines of concise markdown. +# Autonomous 4-Stage UX & Verification Pipeline + +Never optimize merely for "making the static screen pass tests." Optimize for the target persona completing their actual job from Tap 1 to completion without human QA intervention. + +## Stage 1: Autonomous Spec & 3-Tap Journey Trace +When given raw user friction, image comments, or a 5-part brief, do not write production code until you have: +1. **Investigated Current State**: Inspect the relevant UI components, routes, and state helpers first. +2. **Traced the Full User Journey (`Tap 1 → Tap 2 → Tap 3`)**: Never design only the entry state. Explicitly map: + - **Tap 1 (Entry Trigger)**: What the user clicks/taps to start (e.g., *Duplicate to edit*). + - **Tap 2 (Active Manipulation)**: How the user performs the core edit/action (e.g., *Tap button on visual board → edit in modal*). Ensure the persona never hits a technical dead-end (such as raw JSON or developer instructions) on Tap 2. + - **Tap 3 (Persisted Outcome)**: How the change saves and reflects immediately in the UI. +3. **Output the 5-Part Contract**: State the **Goal**, **Decisions & 3-Tap Journey**, **Invariants**, **Specific Next Step**, and **Traps to Avoid** before touching code. +4. **Resolve Forks or Execute**: If `Tap 2` has a genuine product fork (e.g., single-item vs. mirrored behaviour), ask 1–2 concise questions alongside the 5-Part Contract. Otherwise, proceed straight through Stages 2–4 autonomously. + +## Stage 2: Design Tokens, Ergonomics & Copy Hygiene +1. **Primary Actions Above the Fold**: Primary workflow CTAs must be immediately accessible without scrolling past dense boards or long lists on a `390px` mobile viewport. +2. **Verified Styling**: Only use CSS classes/tokens that exist in the stylesheet. Never leave raw unstyled text or duplicate status messages (e.g., a badge and a banner repeating the same sentence). +3. **Zero Implementation Leakage**: Never expose developer jargon (`localStorage`, `JSON`, `factory default`, `schema`, `state`) in user-facing copy. Speak strictly in the user's domain language. + +## Stage 3: Test-First State Verification +1. Write or update deterministic unit/state tests (e.g., `*.test.js` with fake timers where applicable) covering the full state transition before or alongside UI changes. +2. All unit tests must pass with exit code `0` before running visual verification. + +## Stage 4: Multi-State Visual Proof & Mandatory Vision Self-Audit +Never ask the user to manually click through localhost in a browser, and never treat `npm run test:visual` exit code `0` as the finish line. +1. **Snapshot Interactive States, Not Just Landing URLs**: When a feature involves a multi-step flow (e.g., duplicating, opening an edit modal, saving), update the visual snapshot script to drive through and capture each active state in `.visual-proof/` (e.g., `step-1-readonly.png`, `step-2-duplicated.png`, `step-3-edit-modal.png`). +2. **Mandatory Multimodal Self-Audit (`read_file`)**: After running `npm run test:visual`, you **MUST** inspect every generated `.visual-proof/*.png` using `read_file` / vision tools before replying to the user. +3. **Self-Reject & Fix Before Handoff**: If your visual inspection reveals any of the following, fix the code and re-run `npm run test:visual` before yielding your turn: + - Primary actions buried below the fold on `390px` mobile. + - Unstyled classes, broken layouts, or overlapping elements. + - Redundant chrome (badges and banners repeating the same message). + - Developer/implementation jargon in user-facing labels or helper text. +4. **Concise Handoff**: Present your `<10-line` summary only after all unit tests and your visual self-audit pass. diff --git a/.cursor/skills/async-ux-pipeline/SKILL.md b/.cursor/skills/async-ux-pipeline/SKILL.md index 72aea81..07e04e9 100644 --- a/.cursor/skills/async-ux-pipeline/SKILL.md +++ b/.cursor/skills/async-ux-pipeline/SKILL.md @@ -1,58 +1,46 @@ --- name: async-ux-pipeline description: >- - Eliminates glue toil via asynchronous dispatch. Evaluates user feedback - against AGENTS.md personas and push-back rules, implements changes test-first, - proves the result with automated Playwright visual snapshots (no manual clicking), - and ships a pull request. + Enforces the autonomous UX & test-first development pipeline. Evaluates user feedback + against AGENTS.md personas and push-back rules, traces Tap 1 -> Tap 2 -> Tap 3, + implements changes test-first, proves multi-state flows with automated Playwright + visual snapshots and mandatory vision self-audit, and ships a pull request. --- -# Async UX-to-Code Pipeline +# Autonomous UX & Verification Pipeline -Eliminate **"glue toil"** and enable **"Asynchronous Dispatch"**: the user spots friction on mobile or desktop, sends a 2-second screenshot or brief note, and walks away. The agent implements the smallest valid change, runs deterministic tests, captures automated Playwright visual snapshots, and opens a pull request ready for a 5-second review. +Never optimize merely for "making the static screen pass tests." Optimize for the target persona completing their actual job from Tap 1 to completion without human QA intervention. ## Repository Binding -Read `AGENTS.md` (personas, journeys, push-back rules, 4-step blueprint) and `docs/design-language.md` (`.cursor/rules/design-language.mdc`) before changing markup, CSS, or JavaScript. +Read `AGENTS.md` (personas, journeys, push-back rules, execution protocol) and `docs/design-language.md` (`.cursor/rules/design-language.mdc`) before changing markup, CSS, or JavaScript. -## Stage 1: Autonomous Spec Generation from Raw Feedback +## Stage 1: Autonomous Spec & 3-Tap Journey Trace -When the user provides raw, subjective, or high-level feedback (e.g. "Users can't find menu options" or "This screen feels crowded"): +When given raw user friction, image comments, or a 5-part brief, do not write production code until you have: +1. **Investigated Current State**: Inspect the relevant UI components, routes, and state helpers first. +2. **Traced the Full User Journey (`Tap 1 → Tap 2 → Tap 3`)**: Never design only the entry state. Explicitly map: + - **Tap 1 (Entry Trigger)**: What the user clicks/taps to start (e.g., *Duplicate to edit*). + - **Tap 2 (Active Manipulation)**: How the user performs the core edit/action (e.g., *Tap button on visual board → edit in modal*). Ensure the persona never hits a technical dead-end (such as raw JSON or developer instructions) on Tap 2. + - **Tap 3 (Persisted Outcome)**: How the change saves and reflects immediately in the UI. +3. **Output the 5-Part Contract**: State the **Goal**, **Decisions & 3-Tap Journey**, **Invariants**, **Specific Next Step**, and **Traps to Avoid** before touching code. +4. **Resolve Forks or Execute**: If `Tap 2` has a genuine product fork (e.g., single-item vs. mirrored behaviour), ask 1–2 concise questions alongside the 5-Part Contract. Otherwise, proceed straight through Stages 2–5 autonomously. -1. **Investigate Current State**: - - Inspect the relevant UI components, route tables, or layout styles in the repo before forming a plan. -2. **Diagnose the Root Friction**: - - Identify why the current implementation causes that symptom (e.g. deep nesting, ambiguous labels, lack of visual hierarchy). - - Evaluate against the target persona and push-back rules in `AGENTS.md` (e.g. eyes-on-pitch, config-over-code). -3. **Auto-Generate the 5-Part Spec**: - - Explicitly formulate and print the 5-part contract in your thinking trace: - • **Goal**: 1-sentence concrete UX fix. - • **Decisions**: Specific design pattern chosen (e.g. Command palette, flattened top-bar, contextual floating action). - • **Invariants**: Business rules, existing routes, or timers that must not break. - • **Specific Next Step**: The exact component test to write first. - • **Traps to Avoid**: Edge cases to steer clear of. -4. **Self-Direct Execution**: - - Proceed immediately to Stage 2, using your own generated spec as the deterministic boundary. - -## Stage 2: Design Language (Tokens Over Debate) +## Stage 2: Design Tokens, Ergonomics & Copy Hygiene Follow `docs/design-language.md`: -- CSS tokens and semantic classes in `src/styles.css` (e.g. `btn-blue`, `team-color-*`, `--touch-min`). -- Tailwind utilities for layout and spacing only. -- $\ge 44\text{px}$ touch targets for all live-capture elements. -- Never invent new ad-hoc color classes or styling abstractions. +1. **Primary Actions Above the Fold**: Primary workflow CTAs must be immediately accessible without scrolling past dense boards or long lists on a `390px` mobile viewport. Touch targets $\ge 44\text{px}$ (`--touch-min`). +2. **Verified Styling**: Only use CSS classes/tokens that exist in `src/styles.css` (e.g. `btn-blue`, `team-color-*`, `--touch-min`) and Tailwind for layout/spacing only. Never leave raw unstyled text or duplicate status messages (e.g., a badge and a banner repeating the same sentence). +3. **Zero Implementation Leakage**: Never expose developer jargon (`localStorage`, `JSON`, `factory default`, `schema`, `state`) in user-facing copy. Speak strictly in the user's domain language. -## Stage 3: Test-First Discipline (Prevent Code Drift) +## Stage 3: Test-First State Verification -For behaviour (click handlers, state management, storage, DOM output): -1. Add or update a Jest test under `tests/` that mirrors the component in `src/`. -2. Run `npm test` and verify the test fails for the current behavior. -3. Implement the smallest change to make the test pass. -4. Run `npm test` to confirm all suites pass. +1. Write or update deterministic unit/state tests in `tests/` (with fake timers where applicable) covering the full state transition before or alongside UI changes. +2. Run `npm test` — all unit tests must pass with exit code `0` before running visual verification. -## Stage 4: Automated Visual Proof (`npm run test:visual`) +## Stage 4: Multi-State Visual Proof & Mandatory Vision Self-Audit -Do not ask the user to open the app, refresh, or click through states. +Never ask the user to manually click through localhost in a browser, and never treat `npm run test:visual` exit code `0` as the finish line. Use **Direct Seeded URLs** to load state instantly without modal clicks or setup: @@ -63,32 +51,20 @@ Use **Direct Seeded URLs** to load state instantly without modal clicks or setup | **Saved Games** | `index.html#saved-games?mock=sample` | Saved games list pre-populated with sample game | | **Saved Game Log** | `index.html#log/sample-game` | Read-only match timeline & statistics | | **Match Review** | `timeline-video.html?game=sample-game` | Synchronized timeline, video UI, and favorites | -| **Configure** | `index.html#configure` | Board JSON configuration editor | +| **Configure** | `index.html#configure` | Visual button board customizer & templates | -Run the automated visual snapshot tool: -```bash -npm run test:visual -``` -This boots a headless Chromium instance via Playwright, renders the views across **mobile (390x844)** and **desktop (1280x800)**, and outputs PNG artifacts to `.visual-proof/` and `./diff.png`. +1. **Snapshot Interactive States, Not Just Landing URLs**: Run `npm run test:visual`. When a feature involves a multi-step flow (e.g., duplicating, opening an edit modal, saving), drive through and capture each active state in `.visual-proof/` (e.g., `step-1-readonly.png`, `step-2-duplicated.png`, `step-3-edit-modal.png`). +2. **Mandatory Multimodal Self-Audit (`read_file`)**: After running `npm run test:visual`, you **MUST** inspect every generated `.visual-proof/*.png` using `read_file` / vision tools before replying to the user. +3. **Self-Reject & Fix Before Handoff**: If your visual inspection reveals any of the following, fix the code and re-run `npm run test:visual` before yielding your turn: + - Primary actions buried below the fold on `390px` mobile. + - Unstyled classes, broken layouts, or overlapping elements. + - Redundant chrome (badges and banners repeating the same message). + - Developer/implementation jargon in user-facing labels or helper text. +4. **Concise Handoff**: Present your `<10-line` summary only after all unit tests and your visual self-audit pass. ## Stage 5: Pull Request & Zero-Toil Review Every change ships through a pull request. Never commit or push to `main`. - -1. Start from an up-to-date `main` and create `feature/`. +1. Branch from `main` using `feature/`. 2. Commit with a concise message describing the user benefit. -3. Push the branch and open a PR against `main` using `gh pr create`. -4. In the PR body, include: - - **Persona & Journey** affected. - - **What Changed**. - - **Behaviour Preserved**. - - **Verification**: `npm test` count and visual snapshots generated by `npm run test:visual`. -5. The user reviews the PR and visual snapshots in 5 seconds and merges. - -## Done When - -- [ ] Behaviour changes have a passing Jest test (`npm test`). -- [ ] `AGENTS.md` persona quality bars and design-language tokens hold. -- [ ] Automated visual proof succeeded via `npm run test:visual`. -- [ ] A pull request is open against `main` on a `feature/` branch. -- [ ] The reply summarizes what changed, the test count, visual snapshot status, and PR link. +3. Push the branch and open a PR against `main` using `gh pr create` (Persona & Journey, What Changed, Behaviour Preserved, Verification). diff --git a/AGENTS.md b/AGENTS.md index 14cfa5e..84d9138 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,7 +66,7 @@ When the user provides feedback, a pain point, or a feature idea: | **3. Saved Games** | `index.html#saved-games` | `index.html#saved-games?mock=sample` | Seeds sample game into storage so cards and export/review actions are live. | | **4. Saved Game Log** | `index.html#log/` | `index.html#log/sample-game` | Read-only match log for `sample-game` (auto-seeded if missing). | | **5. Match Review** | `timeline-video.html?game=` | `timeline-video.html?game=sample-game` | Loads timeline with 8 tactical events, favorites, and video player UI. | -| **6. Configuration** | `index.html#configure` | `index.html#configure` | Power-user JSON editor for button board schemas. | +| **6. Configuration** | `index.html#configure` | `index.html#configure` | Visual button board customizer with protected templates and optional JSON view. | --- @@ -79,3 +79,13 @@ When the user provides feedback, a pain point, or a feature idea: - Never rename board colour classes (`btn-blue`, `btn-red`, `btn-green`, `btn-yellow`, `btn-orange`, `btn-gray`) or `team-color-*`. - Never break `localStorage` keys (`fieldHockeyGames_v1`, `fieldHockeyConfig_v1`, `fieldHockeyNamedConfigs_v1`, `fieldHockeyCaptureDraft_v1`) or Sportscode XML `` / `` structure. - Follow `docs/design-language.md` and `.cursor/rules/design-language.mdc` for all UI changes (tokens in `src/styles.css`, Tailwind for layout/spacing only). + +--- + +## Execution Protocol (Non-Negotiable) + +1. **Trace `Tap 1 → Tap 2 → Tap 3` First**: Never implement an entry button without implementing the complete interactive flow behind it. The target user must never hit a technical dead-end or raw JSON fallback mid-journey. +2. **Zero Developer Jargon in UI**: User copy must never mention `localStorage`, `JSON`, `factory default`, or internal state mechanics. +3. **Test-First State Logic**: Pure state helpers and storage contracts must be verified via unit tests (`npm test`) before UI handoff. +4. **Multi-State Visual Proof**: `npm run test:visual` must capture every interactive state of a new flow in `.visual-proof/*.png` (desktop + `390px` mobile)—never just the static initial route. +5. **Mandatory Vision Self-Audit**: Passing `npm run test:visual` with exit code `0` is NOT completion. You must open and inspect every generated `.visual-proof/*.png` with `read_file` before replying. If primary actions are buried below the mobile fold, classes are unstyled, banners duplicate badges, or developer jargon is visible, fix it yourself before handing the turn back.