GUI Workflow Guardrails (AGENTS.md + SKILL.md kit)

Stop UI/UX drift in agent-assisted GUI development.

GUI Workflow Guardrails is a small, repo-portable kit (templates + skills) that turns “make the UI better” into a repeatable, reviewable process. It’s built for teams using AI coding agents on browser-based GUIs (React/Vue/Svelte/canvas apps), where it’s easy to accidentally:

• add another way to do the same task,
• ship a feature that has no in-product workflow,
• or break established UI style patterns.

This kit helps agents and humans keep the product coherent over time by making workflows and style explicit.

What it does

• Identify repetitive workflows (multiple ways to do the same task)
• Identify missing workflows (feature exists but no in-product path)
• Enforce workflow quality priorities:
  1. intuitive primary path
  2. fewer steps
  3. shorter mouse pointer travel distance
  4. style consistency (match established UI patterns)
• Require user confirmation only when a change is significant (workflow or style contract break)

Why it’s different (distinct advantages)

• Workflow-first artifacts: encourages living workflow inventories, checklists, and SVG mockups (.plans/) instead of scattered prompts and tribal knowledge.
• De-duplication bias: explicitly requires picking a single primary path and removing/merging redundant entrypoints, rather than accumulating UI.
• Missing-workflow detection: treats “feature exists but only editable via config/YAML” as a first-class bug to fix.
• Style contracts with a tie-break rule: preserves established UI patterns by default, but forces an explicit decision when a style break could improve efficiency.
• Progressive disclosure: uses scoped AGENTS.md files so you don’t overload the root context with every rule.
• CI + PR-friendly: includes optional GitHub Action checks and PR “workflow diff” templates so changes stay reviewable.

What’s inside

• skills/workflow-audit/SKILL.md — process skill to audit, name, and de-duplicate workflows
• skills/workflow-style-contract/SKILL.md — process skill to extract + enforce style patterns
• templates/progressive-disclosure/ — starter AGENTS.md hierarchy (root + scoped files)
• templates/plans/ — starter .plans/ workflow artifacts + mockups README
• templates/pr/ — PR templates including a “workflow diff” section
• templates/ci/ — optional GitHub Action to enforce presence of workflow artifacts
• examples/gui-project/ — minimal example layout showing where .plans/ artifacts live

How to use in a GUI repo

1. Copy the template AGENTS.md files into your repo (or adapt them):
   • templates/progressive-disclosure/AGENTS.md → your repo root
   • templates/progressive-disclosure/src/editor/AGENTS.md → your editor subtree
   • templates/progressive-disclosure/src/phaser/AGENTS.md → your canvas/gesture subtree
2. Add the .plans/ templates:
   • copy templates/plans/.plans/ → your repo’s .plans/
3. (Optional) Add PR + CI templates:
   • templates/pr/*
   • templates/ci/*
4. Copy one or both skills into your agent’s skills directory (tool-specific), or keep them repo-local and load on demand.
5. Maintain .plans/editor-workflows-inventory.md and .plans/ux-checklist-workflow-simplification.md as living workflow artifacts.

Quick start (this repo)

Browse:

• skills/ for the skills
• templates/ for drop-in files
• examples/gui-project/ for a reference layout