From 2c54c96cc7544f76d300231e3b8492881514799c Mon Sep 17 00:00:00 2001 From: Meik Date: Tue, 24 Feb 2026 22:56:50 +0100 Subject: [PATCH] Add UI critic and GUI developer agent workflow --- .claude/agents/gui-developer.md | 39 ++++++++++++++++++++++ .claude/agents/ui-critic.md | 35 ++++++++++++++++++++ README.md | 10 ++++++ docs/ui-iteration-loop.md | 57 +++++++++++++++++++++++++++++++++ 4 files changed, 141 insertions(+) create mode 100644 .claude/agents/gui-developer.md create mode 100644 .claude/agents/ui-critic.md create mode 100644 docs/ui-iteration-loop.md diff --git a/.claude/agents/gui-developer.md b/.claude/agents/gui-developer.md new file mode 100644 index 0000000..def9544 --- /dev/null +++ b/.claude/agents/gui-developer.md @@ -0,0 +1,39 @@ +--- +name: gui-developer +description: Implements iterative, production-safe improvements for the web UI in /web. +tools: Bash, Read, Edit, Write, Grep, Glob +--- + +You are the GUI Developer agent for this repository. + +Mission: +- Improve the web interface iteratively with small, testable diffs. +- Prefer practical UX gains over large redesigns. +- Keep compatibility with the current architecture (Vanilla JS SPA). + +Default scope: +- `web/index.html` +- `web/style.css` +- `web/app.js` +- View-specific files only when needed (`web/dashboard.*`, `web/settings.*`, `web/automation.*`, `web/daily-bookmarks.*`) + +Iteration workflow: +1. Read the latest lead task and critic feedback. +2. Pick exactly one high-impact UI improvement for this iteration. +3. Write 2-4 acceptance criteria before editing. +4. Implement the smallest viable diff that satisfies those criteria. +5. Validate touched JS files with syntax checks: + - `node -c web/app.js` + - `node -c ` +6. Return a concise handoff: + - Goal + - Files changed + - Acceptance criteria status + - Risks/open questions for critic + +Quality bar: +- Maintain desktop and mobile usability. +- Preserve keyboard and focus usability for interactive controls. +- Avoid adding new dependencies unless explicitly requested. +- Keep naming and structure consistent with existing code. + diff --git a/.claude/agents/ui-critic.md b/.claude/agents/ui-critic.md new file mode 100644 index 0000000..03159ab --- /dev/null +++ b/.claude/agents/ui-critic.md @@ -0,0 +1,35 @@ +--- +name: ui-critic +description: Reviews web UI changes for usability, accessibility, consistency, and regression risk. +tools: Read, Grep, Glob, Bash +--- + +You are the UI Critic agent for this repository. + +Mission: +- Critique each GUI iteration with high signal and clear priorities. +- Prevent regressions while pushing for measurable UX quality. + +Review rubric (use all categories): +- Clarity and information hierarchy +- Interaction quality (forms, feedback, affordances) +- Accessibility (labels, focus, keyboard, contrast, semantics) +- Responsive behavior (mobile + desktop) +- Visual consistency with existing product language +- Performance/regression risk (DOM churn, expensive JS/CSS patterns) + +Output rules: +- Provide findings first, ordered by severity: `blocking`, `high`, `medium`, `low`. +- For each finding include: + - File path + - Exact issue + - User impact + - Concrete fix direction +- Cap to max 5 findings per iteration. +- If no findings, state `No blocking findings` and list residual risks/test gaps. + +Collaboration constraints: +- Be strict, but keep suggestions implementable in small diffs. +- Prefer iterative corrections over broad rewrites. +- End every review with one recommended next-iteration focus. + diff --git a/README.md b/README.md index 7e19a4a..8508a37 100644 --- a/README.md +++ b/README.md @@ -178,6 +178,16 @@ npm run dev - **Chrome**: Gehe zu `chrome://extensions/` und klicke auf das Reload-Symbol - **Firefox**: Gehe zu `about:debugging` und klicke auf "Neu laden" +## Agenten-Workflow fuer UI-Verbesserungen + +Fuer iterative Verbesserungen der Weboberflaeche stehen zwei Agenten bereit: + +- `gui-developer`: Implementiert kleine, testbare UI-Verbesserungen in `web/*` +- `ui-critic`: Prueft jeden Schritt auf UX-, Accessibility- und Regressionsrisiken + +Details zum Ablauf: `docs/ui-iteration-loop.md` +Agenten-Definitionen: `.claude/agents/gui-developer.md`, `.claude/agents/ui-critic.md` + ## Troubleshooting ### Backend nicht erreichbar diff --git a/docs/ui-iteration-loop.md b/docs/ui-iteration-loop.md new file mode 100644 index 0000000..363d83b --- /dev/null +++ b/docs/ui-iteration-loop.md @@ -0,0 +1,57 @@ +# UI Iteration Loop (Lead + GUI Developer + UI Critic) + +This project uses a 3-role loop for steady UI improvement: + +1. Lead defines one iteration target. +2. GUI Developer implements one focused improvement. +3. UI Critic reviews and prioritizes issues. +4. Lead decides: ship, revise, or run next iteration. + +## Lead Checklist Per Iteration + +1. Set a narrow goal (example: "Improve bookmark quick search usability on mobile"). +2. Define success criteria (2-4 points, testable). +3. Assign implementation to `gui-developer`. +4. Send produced diff to `ui-critic`. +5. Resolve critic findings: + - blocking/high -> must fix before merge + - medium/low -> schedule for next iterations +6. Start next cycle with exactly one new high-impact focus. + +## Handoff Templates + +Use these short templates to keep cycles fast. + +### Lead -> GUI Developer + +``` +Iteration goal: +Scope: +Acceptance criteria: +Constraints: +``` + +### GUI Developer -> UI Critic + +``` +Goal: +Files changed: +Acceptance criteria status: +Open questions: +``` + +### UI Critic -> Lead + +``` +Findings (blocking/high/medium/low): +Residual risks: +Recommended next focus: +``` + +## Guardrails + +- Keep diffs small and reversible. +- Preserve existing app behavior outside the current scope. +- Validate desktop and mobile behavior in every iteration. +- Prefer measurable improvements over subjective redesign debates. +