@sylphx/flow 3.6.0 → 3.7.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @sylphx/flow
 
+## 3.7.0 (2026-01-28)
+
+### ✨ Features
+
+- sweep modern UI patterns across all commands ([80f4264](https://github.com/SylphxAI/flow/commit/80f4264e1cf6450d83a09507551740b12be54820))
+- **excellence:** add accessibility and mobile dimensions ([e288eab](https://github.com/SylphxAI/flow/commit/e288eabd53fe9f0eb923f41c9ef1dad8a343724c))
+- add /polish command for modern UI excellence ([040ea22](https://github.com/SylphxAI/flow/commit/040ea2280a7c4a7532caa8ed0b33829f3ec79633))
+
+## 3.6.1 (2026-01-28)
+
+### ♻️ Refactoring
+
+- comprehensive review of all commands and builder ([73b103a](https://github.com/SylphxAI/flow/commit/73b103a4d6901079408d9e4e0237cad4e4087f14))
+
 ## 3.6.0 (2026-01-28)
 
 ### ✨ Features

package/assets/agents/builder.md

@@ -144,6 +144,17 @@ Vercel CLI, Neon CLI, GitHub CLI
 * Semantic HTML — use correct elements (nav, main, article, section, aside, header, footer)
 * Data presentation must use Data Tables
 * Large datasets require cursor-based pagination, virtualization, and infinite scrolling
+* Modern interactions — inline editing, drag & drop, undo everywhere, keyboard shortcuts
+* Feedback — skeleton loading, optimistic UI, smooth transitions
+* Accessibility — keyboard navigation, screen reader support, WCAG contrast
+
+## Public-Facing & Exposure
+
+* SEO — proper title tags, meta descriptions, structured data, sitemap
+* Social sharing — OG tags, Twitter cards for all public pages
+* README — clear value prop, quick start, badges, screenshots
+* Landing page — value prop above the fold, clear CTA, social proof
+* Documentation — complete, searchable, up-to-date
 
 ## Delivery
 

package/assets/slash-commands/audit.md

@@ -12,16 +12,16 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 ## Scan Areas
 
 ### 1. Code Quality
-- Dead code, unused imports, unused variables
+- Dead code, unused imports, unreachable code
 - TODOs, FIXMEs, HACKs left in code
-- `any` types, missing type safety
+- Weak typing (`any`, missing types, unsafe casts)
 - Hardcoded values that should be config
-- Console.logs, debug code in production
-- Copy-paste duplication
-- Functions > 50 lines, files > 300 lines
-- Missing error handling
-- Inconsistent naming conventions
-- Outdated dependencies with known issues
+- Debug artifacts in production (console.logs, commented code)
+- Copy-paste duplication (DRY violations)
+- Overly complex functions/files (hard to understand at a glance)
+- Missing or inconsistent error handling
+- Naming that doesn't convey intent
+- Outdated or vulnerable dependencies
 
 ### 2. Business Logic Correctness
 
@@ -50,17 +50,28 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 
 ### 4. UI/UX Issues
 - Confusing user flows
-- Missing loading states
-- Missing error states
-- Missing empty states
+- Missing loading states (use skeleton, not spinner)
+- Missing error states (with recovery actions)
+- Missing empty states (with guidance)
 - Inconsistent spacing/typography
 - Non-responsive layouts
-- Accessibility violations (contrast, keyboard nav)
+- Accessibility violations (contrast, keyboard nav, screen reader)
 - Missing feedback on user actions
 - Unclear CTAs or labels
 - Information overload
 
-### 5. Product Design
+### 5. Modern UI Patterns (Lack of)
+- No inline editing (everything requires modal/page)
+- No drag & drop where it makes sense
+- No undo capability (destructive actions are permanent)
+- No auto-save (users must remember to save)
+- No keyboard shortcuts for power users
+- No command palette (⌘K) for quick navigation
+- Outdated inputs (dropdowns instead of combobox with search)
+- No optimistic UI (waiting for server on every action)
+- Jarring transitions (no smooth state changes)
+
+### 6. Product Design
 - Unclear value proposition
 - Friction in core user journey
 - Missing onboarding guidance
@@ -70,7 +81,7 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Power user needs unmet
 - Beginner barriers too high
 
-### 6. Performance
+### 7. Performance
 - Slow page loads
 - Unnecessary re-renders
 - Large bundle sizes
@@ -79,7 +90,7 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Missing caching opportunities
 - Unoptimized images/assets
 
-### 7. Security
+### 8. Security
 - Exposed secrets or credentials
 - Missing input validation
 - XSS vulnerabilities
@@ -88,7 +99,7 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Missing rate limiting
 - Overly permissive CORS
 
-### 8. Developer Experience
+### 9. Developer Experience
 - Missing or outdated documentation
 - Unclear setup instructions
 - Flaky or missing tests
@@ -96,6 +107,15 @@ Scan the entire project for issues. Find problems, don't fix them. Open GitHub i
 - Missing type definitions
 - Confusing folder structure
 
+### 10. Public-Facing & Exposure
+- **SEO**: Missing/poor title tags, meta descriptions, structured data
+- **Social Sharing**: Missing OG tags, Twitter cards, poor share previews
+- **Landing/Home**: Unclear value prop above the fold, weak CTAs
+- **README**: Missing badges, unclear quick start, no screenshots
+- **Docs**: Incomplete, outdated, hard to navigate
+- **Analytics**: Missing tracking, no conversion funnels
+- **Branding**: Inconsistent voice, visuals, messaging
+
 ## Process
 
 1. **Scan** each area systematically

package/assets/slash-commands/catchup.md

@@ -48,6 +48,13 @@ gh issue list --state open --limit 20
 gh pr list --state open --limit 10
 ```
 
+### Business & Marketing Strategy
+- What's the monetization model? Is it working?
+- Who are the competitors? How does this differentiate?
+- What's the go-to-market strategy?
+- How are users being acquired? (SEO, social, paid, referral)
+- What public-facing assets exist? (landing page, blog, socials)
+
 ### Branch Analysis
 ```bash
 git branch -a

package/assets/slash-commands/challenge.md

@@ -11,8 +11,8 @@ Stop. Step back. Challenge everything you just did.
 
 ### 1. State of the Art?
 - Would industry experts approve this implementation?
-- Does it follow current best practices (2024+)?
-- Is this how top engineers at FAANG would solve it?
+- Does it follow current best practices?
+- Is this how top engineers would solve it?
 - Are you using modern APIs, patterns, and approaches?
 
 ### 2. Correct Approach or Workaround?
@@ -21,21 +21,30 @@ Stop. Step back. Challenge everything you just did.
 - Would you be embarrassed if a senior engineer reviewed this?
 - Is there technical debt being created?
 
-### 3. Clean & Complete?
-- Zero dead code?
-- Zero unused imports?
-- Zero TODOs left behind?
-- Zero console.logs or debug code?
+### 3. Business Logic Sound?
+- Does this make sense from a business perspective?
+- Are edge cases handled correctly for real-world scenarios?
+- Would domain experts find issues with this logic?
+- Does it handle regional/locale differences correctly?
+
+### 4. Clean & Complete?
+- Zero dead code, unused imports, TODOs?
 - All edge cases handled?
-- Error handling complete?
+- Error handling complete and user-friendly?
+- No debug artifacts left behind?
 
-### 4. Human Experience?
+### 5. Human Experience?
 - Is the UX intuitive? Would a user understand without explanation?
 - Are error messages helpful and actionable?
 - Is the UI responsive and accessible?
 - Does it feel polished, not janky?
 
-### 5. Better Way?
+### 6. Impact Beyond Code?
+- Does this affect public-facing content (SEO, OG tags, docs)?
+- Should README or documentation be updated?
+- Are there marketing/exposure implications?
+
+### 7. Better Way?
 - What would you do differently with unlimited time?
 - Is there a simpler solution you overlooked?
 - Could this be more elegant?

package/assets/slash-commands/e2e-audit.md

@@ -46,6 +46,12 @@ mcp__playwright__browser_snapshot - Get current page state
 - [ ] Boundary values (min/max)
 - [ ] Invalid inputs
 
+**Public-Facing Pages:**
+- [ ] Landing/home page — value prop clear? CTA works?
+- [ ] Pricing page — accurate? Links work?
+- [ ] Docs/help — accessible? Search works?
+- [ ] Social sharing — OG previews correct? Links work?
+
 ### 3. Test Business Logic
 
 **Region/Locale Consistency:**
@@ -88,6 +94,16 @@ mcp__playwright__browser_take_screenshot  # Capture evidence
 - Responsive issues
 - Inconsistent styling
 
+### Modern UI Patterns (Test for)
+- Can you edit inline or must open modal/page?
+- Can you drag & drop to reorder?
+- Is there undo after destructive actions?
+- Does it auto-save or require manual save?
+- Do keyboard shortcuts work (⌘K, ⌘S, etc.)?
+- Are loading states smooth (skeleton) or jarring (spinner)?
+- Are transitions animated or instant jumps?
+- Do inputs have search/autocomplete where useful?
+
 ## Browser Tools Reference
 
 ```

package/assets/slash-commands/excellence.md

@@ -44,17 +44,32 @@ Based on this specific project's nature, determine what "excellence" means here.
 - Would users choose this over competitors?
 - Is it intuitive, fast, polished?
 - Are edge cases handled gracefully?
+- Does it feel **modern**? (inline editing, drag & drop, ⌘K, undo everywhere)
+- Or does it feel **dated**? (modal forms, no shortcuts, destructive actions)
+
+### Accessibility & Inclusivity
+- Can everyone use this? Keyboard users? Screen reader users?
+- Does it meet WCAG standards (contrast, focus, labels)?
+- Does it respect user preferences (reduced motion, dark mode)?
+- Is it an afterthought or designed-in from the start?
+
+### Mobile & Responsive
+- Does it work beautifully on all screen sizes?
+- Are touch interactions first-class, not degraded?
+- Is mobile a real use case or an afterthought?
 
 ### Performance
 - Is it best-in-class or just acceptable?
 - Are there obvious bottlenecks?
 - Would performance engineers approve?
 
-### Public-Facing (Docs, README, Marketing)
-- Is the messaging compelling?
-- Would it attract users/contributors?
-- Is documentation clear and complete?
-- Does it convey professionalism and quality?
+### Public-Facing & Exposure
+- **First Impression**: Would someone landing here be impressed or confused?
+- **SEO/Discoverability**: Can people find this? Are meta tags, titles, descriptions optimized?
+- **Social Sharing**: Do OG tags, Twitter cards make people want to click?
+- **README/Docs**: World-class or bare minimum? Would it make someone star/fork?
+- **Landing Page**: Does it convert? Is the value prop crystal clear?
+- **Branding**: Consistent, professional, memorable?
 
 ## Process
 

package/assets/slash-commands/polish.md

@@ -0,0 +1,167 @@
+---
+name: polish
+description: Elevate UI from functional to delightful - modern patterns and interactions
+---
+
+# Polish: Elevate UI to Modern Excellence
+
+Transform functional UI into delightful, state-of-the-art interfaces. This is not about fixing bugs — it's about raising the bar from "it works" to "it's a joy to use".
+
+## Philosophy
+
+> **"Reduce user thinking, increase system intelligence."**
+
+Modern UI is:
+- **Direct** — interact with the thing itself, not a separate control
+- **Responsive** — immediate feedback, never leave users wondering
+- **Forgiving** — undo everywhere, mistakes are recoverable
+- **Smart** — anticipate needs, reduce manual input
+- **Fluid** — smooth transitions, not jarring jumps
+
+## Upgrade Dimensions
+
+### 1. Direct Manipulation
+
+**Before → After:**
+- Upload button → Click avatar/image to change
+- Edit button → Click text to edit inline
+- Reorder with arrows → Drag & drop
+- Separate settings page → Contextual controls where needed
+
+**Principle:** Users should manipulate the object itself, not a proxy control.
+
+### 2. Rich Feedback
+
+**Before → After:**
+- Spinner → Skeleton/shimmer loading
+- Submit and wait → Optimistic update (instant, sync in background)
+- Alert box → Toast notification (non-blocking)
+- Page reload → Smooth transition/animation
+- Binary states → Progress indicators with context
+
+**Principle:** Every action should have immediate, visible response.
+
+### 3. Modern Input Patterns
+
+**Before → After:**
+- Text field for tags → Chip/tag input with autocomplete
+- Dropdown select → Combobox with search and create
+- File upload button → Drag & drop zone + paste support
+- Date text input → Visual picker + natural language ("next monday")
+- Manual everything → Smart defaults + auto-complete
+
+**Principle:** Inputs should be as intelligent as possible.
+
+### 4. Information Architecture
+
+**Before → After:**
+- All fields visible → Progressive disclosure (show when needed)
+- Fixed layout → Adaptive layout based on content/task
+- Pagination → Infinite scroll with virtualization
+- Menu diving → Command palette (⌘K) for quick access
+- Nested menus → Flat structure + contextual actions
+
+**Principle:** Show the right information at the right time.
+
+### 5. Trust & Control
+
+**Before → After:**
+- "Are you sure?" dialogs → Undo everywhere (Gmail style)
+- Save button → Auto-save with visible status
+- Silent operations → Visible system status (syncing, saved, offline)
+- Error = dead end → Recovery suggestions + retry options
+- Single version → Version history + restore
+
+**Principle:** Users should feel safe to explore and experiment.
+
+### 6. Visual Polish
+
+**Before → After:**
+- Flat/harsh shadows → Subtle depth (light shadows, blur)
+- Color as decoration → Color as information (status, priority)
+- Uniform text → Clear typography hierarchy
+- Cramped layout → Consistent spacing system (breathing room)
+- Static states → Purposeful motion (guide attention, show relationships)
+
+**Principle:** Visual design should reduce cognitive load, not add to it.
+
+### 7. Power User Enablement
+
+**Before → After:**
+- Mouse only → Keyboard shortcuts for common actions
+- One item at a time → Bulk selection and actions
+- Fixed views → Customizable columns/layouts
+- No way out → Export/import data
+- Hidden features → Discoverable via command palette
+
+**Principle:** Reward expertise without punishing beginners.
+
+### 8. Mobile & Touch
+
+**Before → After:**
+- Desktop-only design → Responsive from the start
+- Click targets → Touch-friendly tap targets (44px+)
+- Hover states only → Touch gestures (swipe, long-press)
+- Desktop modals → Bottom sheets on mobile
+- Mouse precision → Finger-friendly spacing
+
+**Principle:** Touch is not a degraded experience — it's a different one.
+
+## Process
+
+### 1. Audit Current State
+Walk through the UI as a user:
+- Where do I have to click too many times?
+- Where am I waiting without feedback?
+- Where do I feel friction or annoyance?
+- What feels dated compared to best-in-class apps?
+
+### 2. Prioritize by Impact
+Focus on:
+- High-frequency interactions (used daily)
+- Pain points (users complain or work around)
+- First impressions (onboarding, landing)
+
+### 3. Apply Modern Patterns
+For each area:
+- Identify the current pattern
+- Choose the modern equivalent
+- Implement with smooth transitions
+- Ensure accessibility is maintained
+
+### 4. Verify Quality
+- Interactions feel snappy (< 100ms feedback)
+- Animations are smooth (60fps)
+- Works with keyboard navigation
+- Responsive across screen sizes
+- Accessible (screen readers, contrast)
+
+## Reference: Best-in-Class Examples
+
+| Pattern | See How It's Done |
+|---------|-------------------|
+| Command Palette | Linear, Raycast, VS Code (⌘K) |
+| Inline Editing | Notion, Airtable |
+| Drag & Drop | Trello, Figma |
+| Optimistic UI | Twitter/X likes, Gmail send |
+| Skeleton Loading | Facebook, LinkedIn |
+| Tag Input | GitHub labels, Notion tags |
+| Auto-save | Google Docs, Figma |
+
+## Accessibility is Non-Negotiable
+
+Modern ≠ Inaccessible. Every polish must maintain:
+- **Keyboard navigation** — all interactions work without mouse
+- **Screen reader support** — proper ARIA labels, announcements
+- **Reduced motion** — respect `prefers-reduced-motion`
+- **Color contrast** — WCAG AA minimum (4.5:1 text, 3:1 UI)
+- **Focus indicators** — visible, clear focus states
+
+## Remember
+
+* **Polish is not decoration** — it's reducing friction
+* **Motion with purpose** — guide attention, show relationships
+* **Accessibility first** — modern doesn't mean inaccessible
+* **Performance is UX** — slow animations are worse than none
+* **Consistency compounds** — one pattern, used everywhere
+* **Steal from the best** — Linear, Figma, Notion set the bar

package/assets/slash-commands/product.md

@@ -70,7 +70,16 @@ Evaluate product design holistically — from user experience to business impact
 - [ ] **Recovery** — Helpful error messages with solutions?
 - [ ] **Help** — Documentation accessible when needed?
 
-## 4. Accessibility & Inclusivity
+## 4. Modern Interaction Patterns
+
+- **Direct manipulation**: Can users interact with content directly (inline edit, drag to reorder)?
+- **Instant feedback**: Optimistic UI, skeleton loading, smooth transitions?
+- **Power user support**: Keyboard shortcuts, command palette (⌘K)?
+- **Trust**: Undo everywhere, auto-save, visible sync status?
+- **Smart inputs**: Search in dropdowns, autocomplete, paste to upload?
+- Does it feel like a 2025 app or a 2015 form?
+
+## 5. Accessibility & Inclusivity
 
 - Works without mouse (keyboard navigation)?
 - Works with screen readers?
@@ -80,13 +89,21 @@ Evaluate product design holistically — from user experience to business impact
 - Works on old devices/browsers?
 - Internationalization-ready?
 
-## 5. Competitive Edge
+## 6. Competitive Edge
 
 - What do competitors do better? Can we match or exceed?
 - What do we do uniquely well? Is it emphasized?
 - What's missing in the market that we could own?
 - If a user tried competitor after us, would they come back? Why?
 
+## 7. Public-Facing & Exposure
+
+- **Landing Page**: Does it convert? Value prop clear in 5 seconds?
+- **SEO**: Are we discoverable? Right keywords targeted?
+- **Social Sharing**: Do shared links look compelling? OG tags set?
+- **README**: Would a developer star this? Quick start clear?
+- **Docs**: Can users self-serve? Search works?
+
 ## Process
 
 1. **Walk through** the entire product as each user type

package/assets/slash-commands/refactor.md

@@ -5,56 +5,57 @@ description: Deep refactoring - modularity, deduplication, cleanup
 
 # Refactor: Deep Codebase Improvement
 
-Systematically refactor the codebase for maximum quality.
+Systematically refactor the codebase toward excellence. The goal is not just clean code, but code that is a joy to work with — maintainable, understandable, and extensible.
+
+## Why Refactor?
+
+> "Any fool can write code that a computer can understand. Good programmers write code that humans can understand." — Martin Fowler
+
+Refactoring is about:
+- **Future velocity** — clean code is faster to change
+- **Bug prevention** — simple code has fewer hiding places for bugs
+- **Onboarding** — new contributors can understand and contribute faster
+- **Pride** — code you'd be proud to show anyone
 
 ## Targets
 
-1. **Dead code** — remove all unused code, imports, variables, functions
-2. **Duplication** — extract shared logic, eliminate copy-paste
-3. **TODOs** — resolve or remove every TODO comment
-4. **Modularity** — split large files, extract reusable modules
-5. **Naming** — rename unclear variables, functions, files
-6. **Types** — strengthen typing, remove `any`, add missing types
-7. **Structure** — reorganize files into logical folders
-8. **Dependencies** — remove unused deps, update outdated ones
+1. **Dead code** — if it's not used, it's noise
+2. **Duplication** — DRY violations are bug factories
+3. **Complexity** — if it's hard to understand, it's wrong
+4. **Naming** — code should read like well-written prose
+5. **Types** — weak types are hidden bugs waiting to happen
+6. **Structure** — logical organization reduces cognitive load
+7. **Dependencies** — unused deps are attack surface and bloat
 
 ## Process
 
-### Phase 1: Scan
-
-1. Find dead code: unused exports, unreachable code
-2. Find duplication: similar code blocks, copy-paste patterns
-3. Find TODOs: `grep -r "TODO" --include="*.ts" --include="*.tsx"`
-4. Find large files: files > 300 lines
-5. Find weak types: `any`, missing return types
+### Phase 1: Understand
+- What is the code trying to do?
+- Why was it written this way?
+- What are the dependencies and side effects?
 
 ### Phase 2: Refactor
-
-For each issue found:
-1. Plan the refactor
-2. Make the change
-3. Run tests to verify no regression
+For each improvement:
+1. Understand the context first
+2. Make one logical change
+3. Verify behavior unchanged (tests, manual check)
 4. Commit atomically: `refactor: description`
-5. Push immediately
 
 ### Phase 3: Verify
+- Tests pass
+- Types check
+- Linter happy
+- Build succeeds
+- Behavior unchanged
 
-1. Run full test suite
-2. Run type check
-3. Run linter
-4. Verify build succeeds
-
-## Rules
+## Principles
 
-* One logical change per commit
-* Tests must pass after each refactor
-* No behavior changes — refactor only
-* If behavior change needed, separate commit
+* **Understand before changing** — never refactor blindly
+* **One change at a time** — atomic commits, easy to revert
+* **Behavior unchanged** — refactor ≠ rewrite
+* **Tests are your safety net** — if no tests, add them first
+* **When in doubt, simplify** — less code is usually better
 
 ## Exit Condition
 
-* Zero TODOs
-* Zero dead code
-* Zero duplication
-* All tests pass
-* All types strict
+The codebase should feel **clean, consistent, and comprehensible**.

package/assets/slash-commands/sweep.md

@@ -51,20 +51,13 @@ For each similar case found:
 
 ## Examples
 
-### Bug Fix Sweep
+### Code Pattern Sweep
 ```
 Fixed: Null check missing in UserProfile
 Sweep: Find all components accessing user data without null checks
 Result: Fixed 12 similar issues across 8 files
 ```
 
-### Pattern Improvement Sweep
-```
-Improved: Converted callback to async/await in fetchData
-Sweep: Find all callback-style async code
-Result: Modernized 23 functions to async/await
-```
-
 ### Type Safety Sweep
 ```
 Fixed: Added proper TypeScript types to API response
@@ -72,18 +65,32 @@ Sweep: Find all `any` types in API layer
 Result: Added proper types to 15 API functions
 ```
 
-### Component Pattern Sweep
+### Business Logic Sweep
+```
+Fixed: HK user was seeing CN tax options
+Sweep: Find all region-dependent logic, verify correctness
+Result: Fixed 5 similar locale issues across settings, billing, reports
+```
+
+### UX Pattern Sweep
+```
+Improved: Added loading state to save button
+Sweep: Find all async actions without loading feedback
+Result: Added loading states to 8 similar interactions
+```
+
+### Error Handling Sweep
 ```
 Created: Reusable ErrorBoundary with retry
-Sweep: Find all try-catch error handling in components
-Result: Replaced 8 ad-hoc error handlers with ErrorBoundary
+Sweep: Find all ad-hoc error handling in components
+Result: Standardized error handling across 12 components
 ```
 
-### Performance Optimization Sweep
+### Public-Facing Sweep
 ```
-Optimized: Added useMemo to expensive calculation
-Sweep: Find all expensive calculations in render
-Result: Memoized 6 similar calculations
+Fixed: Missing OG tags on product page
+Sweep: Find all public pages missing proper meta tags
+Result: Added OG/Twitter cards to 6 pages
 ```
 
 ## Output
@@ -111,6 +118,7 @@ Cases Fixed: [count]
 
 * **One fix = comprehensive sweep** — never leave similar issues behind
 * **Think in patterns** — what class of problem did you just solve?
-* **Be thorough** — check everywhere, including tests and docs
-* **Maintain consistency** — all similar code should look similar
+* **Sweep all dimensions** — code, business logic, UX, public-facing
+* **Be thorough** — check everywhere: code, tests, docs, marketing pages
+* **Maintain consistency** — similar things should look and work similarly
 * **This is how you reach State of the Art** — excellence everywhere, not just in spots

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/flow",
-	"version": "3.6.0",
+	"version": "3.7.0",
 	"description": "One CLI to rule them all. Unified orchestration layer for AI coding assistants. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {