@sylphx/flow 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @sylphx/flow
 
+## 3.3.0 (2026-01-26)
+
+### ✨ Features
+
+- add /catchup command and architecture principles ([f5d6cd9](https://github.com/SylphxAI/flow/commit/f5d6cd9475aba40094f5c434fb962b7451632f1d))
+
+### 🐛 Bug Fixes
+
+- **builder:** simplify CLAUDE.md memory instructions ([fedd464](https://github.com/SylphxAI/flow/commit/fedd46482dc01ef5988d5552b9f7a7c8675c6240))
+
+## 3.2.0 (2026-01-26)
+
+### ✨ Features
+
+- add /audit, /growth commands and builder memory ([a94cefc](https://github.com/SylphxAI/flow/commit/a94cefc918868e151800b13e13f6c37a9b48aaba))
+- add /product slash command for design review ([019cf6d](https://github.com/SylphxAI/flow/commit/019cf6d507fec9aaa517425c93f5b5a048921fad))
+
+### 💅 Styles
+
+- format package.json ([02414d2](https://github.com/SylphxAI/flow/commit/02414d2291374d82188cd3d274e73e76a65be930))
+
 ## 3.1.0 (2026-01-26)
 
 ### ✨ Features

package/assets/agents/builder.md

@@ -45,6 +45,9 @@ AI SDK v6+
 **Auth & Services:**
 Better Auth, Resend (email)
 
+**i18n:**
+Next-intl — language files MUST be split by feature/page, never one large file
+
 **Tooling:**
 Biome (lint/format), Bunup (build), Bun test
 
@@ -83,6 +86,14 @@ Vercel CLI, Neon CLI, GitHub CLI
 
 **Todos.** Track what needs to be done next. This is your memory of what to do.
 
+**CLAUDE.md** — Your persistent memory file. Write to it when you discover:
+- Project-specific commands (build, test, deploy, lint)
+- Environment setup (env vars, prerequisites, dependencies)
+- Architecture decisions and their reasoning
+- Common patterns and conventions used in this codebase
+- Gotchas, workarounds, or non-obvious behaviors
+- Frequently referenced paths, configs, or resources
+
 **Recovery:**
 - Lost context? → Check `git log` for history
 - Forgot next steps? → Check todos
@@ -106,11 +117,18 @@ Vercel CLI, Neon CLI, GitHub CLI
 
 * No workarounds, no hacks — all implementations must meet state-of-the-art industrial standards
 * Single Source of Truth — one authoritative source for every state, behavior, and decision
-* Safety and strong typing — use tRPC for end-to-end type safety across all server communication
-* Observability: comprehensive logging, metrics, and tracing
-* Recoverability: systems must be swiftly restorable without data loss
+* Type safety — end-to-end type safety across all boundaries (tRPC, Zod, strict TypeScript)
+* Observability — logging, metrics, tracing; platform code must be observable by design
+* Recoverability — systems must be swiftly restorable without data loss
 * If automation exists for a task, manual execution is prohibited
 
+## Architecture Principles
+
+* **Pure functions** — no side effects, deterministic output; isolate impure code at boundaries
+* **Decoupling** — minimize dependencies between modules, use interfaces and dependency injection
+* **Modularisation** — single responsibility, clear boundaries, independent deployability
+* **Reusable composition** — build primitives that compose; prefer composition over inheritance
+
 ## Codebase
 
 * Zero tolerance: no TODOs, no dead code, no unused code

package/assets/slash-commands/audit.md

@@ -0,0 +1,145 @@
+---
+name: audit
+description: Find all problems in the project - design, code, UX - and open issues
+---
+
+# Audit: Comprehensive Problem Discovery
+
+Scan the entire project for issues. Find problems, don't fix them. Open GitHub issues for everything found.
+
+**Rule: DO NOT fix anything. Only discover and document.**
+
+## Scan Areas
+
+### 1. Code Quality
+- Dead code, unused imports, unused variables
+- TODOs, FIXMEs, HACKs left in code
+- `any` types, missing type safety
+- 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
+
+### 2. Architecture
+- Circular dependencies
+- God objects/files doing too much
+- Tight coupling between modules
+- Missing abstractions
+- Leaky abstractions
+- Single points of failure
+- Missing SSOT (multiple sources of truth)
+- Inconsistent patterns across codebase
+
+### 3. UI/UX Issues
+- Confusing user flows
+- Missing loading states
+- Missing error states
+- Missing empty states
+- Inconsistent spacing/typography
+- Non-responsive layouts
+- Accessibility violations (contrast, keyboard nav)
+- Missing feedback on user actions
+- Unclear CTAs or labels
+- Information overload
+
+### 4. Product Design
+- Unclear value proposition
+- Friction in core user journey
+- Missing onboarding guidance
+- Features that don't serve business goals
+- Confusing navigation structure
+- Missing progressive disclosure
+- Power user needs unmet
+- Beginner barriers too high
+
+### 5. Performance
+- Slow page loads
+- Unnecessary re-renders
+- Large bundle sizes
+- Missing lazy loading
+- N+1 queries
+- Missing caching opportunities
+- Unoptimized images/assets
+
+### 6. Security
+- Exposed secrets or credentials
+- Missing input validation
+- XSS vulnerabilities
+- CSRF vulnerabilities
+- Insecure dependencies
+- Missing rate limiting
+- Overly permissive CORS
+
+### 7. Developer Experience
+- Missing or outdated documentation
+- Unclear setup instructions
+- Flaky or missing tests
+- Slow CI/CD pipeline
+- Missing type definitions
+- Confusing folder structure
+
+## Process
+
+1. **Scan** each area systematically
+2. **Document** every issue found with:
+   - Clear description of the problem
+   - Location (file, line, or area)
+   - Impact (High/Medium/Low)
+   - Category label
+3. **DO NOT** attempt any fixes
+4. **Open GitHub issues** for each problem found
+
+## Issue Format
+
+```bash
+gh issue create --title "[Category] Brief description" --body "$(cat <<'EOF'
+## Problem
+What is wrong and where.
+
+## Impact
+Why this matters. What could go wrong.
+
+## Evidence
+Code snippets, screenshots, or specific locations.
+
+## Suggested Category
+- [ ] Bug
+- [ ] Tech Debt
+- [ ] UX Issue
+- [ ] Performance
+- [ ] Security
+- [ ] Documentation
+EOF
+)" --label "audit"
+```
+
+## Output
+
+After scanning, report:
+
+### Summary
+| Category | Issues Found | High | Medium | Low |
+|----------|--------------|------|--------|-----|
+| Code     | ...          | ...  | ...    | ... |
+| UI/UX    | ...          | ...  | ...    | ... |
+| ...      | ...          | ...  | ...    | ... |
+
+### Issues Created
+- #123 [Code] Description...
+- #124 [UX] Description...
+- ...
+
+### Critical Issues (need immediate attention)
+- ...
+
+## Mindset
+
+* Be thorough, not selective
+* No issue is too small to document
+* Assume nothing is perfect
+* Fresh eyes find more problems
+* The goal is awareness, not judgment
+* Better to over-report than miss something

package/assets/slash-commands/catchup.md

@@ -0,0 +1,119 @@
+---
+name: catchup
+description: Deep dive into project history, direction, and implementation details
+---
+
+# Catchup: Understand the Project Deeply
+
+Get up to speed with the entire project — history, direction, and details.
+
+## Phase 1: Git History Analysis
+
+### Recent Commits
+```bash
+git log --oneline -50
+git log --oneline --since="1 week ago"
+git log --oneline --since="1 month ago" --until="1 week ago"
+```
+
+### Commit Patterns
+- What areas are being actively worked on?
+- What types of changes dominate? (feat, fix, refactor, docs)
+- Who are the contributors and what do they focus on?
+- Are there any recurring issues being fixed?
+
+### Recent Activity by Area
+```bash
+git log --oneline --all -- "src/components/*" | head -20
+git log --oneline --all -- "src/api/*" | head -20
+git log --oneline --all -- "src/lib/*" | head -20
+```
+
+## Phase 2: Development Direction
+
+### Read Project Documentation
+1. **PRODUCT.md** — Vision, goals, target users, success metrics
+2. **ARCHITECTURE.md** — Tech decisions, patterns, system design
+3. **CLAUDE.md** — Project-specific knowledge, commands, gotchas
+4. **README.md** — Setup, usage, contribution guidelines
+5. **CHANGELOG.md** — Release history, breaking changes
+
+### Identify Current Focus
+- What features are in progress?
+- What's the roadmap or next milestones?
+- Are there open issues or PRs that indicate direction?
+
+```bash
+gh issue list --state open --limit 20
+gh pr list --state open --limit 10
+```
+
+### Branch Analysis
+```bash
+git branch -a
+git log main..HEAD --oneline  # if on feature branch
+```
+
+## Phase 3: Deep Implementation Research
+
+### Codebase Structure
+```bash
+tree -L 2 -d src/  # or relevant directories
+```
+
+### Key Files to Understand
+- Entry points (main, index, app)
+- Configuration files (config, env, settings)
+- Core business logic
+- Database schema and migrations
+- API routes and handlers
+- Shared utilities and helpers
+
+### Dependency Analysis
+- What are the major dependencies?
+- Are there any custom abstractions worth understanding?
+- What patterns are consistently used?
+
+### Test Coverage
+- Where are tests located?
+- What's tested, what's not?
+- What do test failures tell us about the system?
+
+## Output
+
+### Executive Summary
+```
+Project: [name]
+Stage: [MVP / Growth / Mature]
+Focus: [current development focus]
+Health: [assessment based on commits, issues, code quality]
+```
+
+### Recent Activity (Last 2 Weeks)
+| Date | Area | Changes | Impact |
+|------|------|---------|--------|
+| ...  | ...  | ...     | H/M/L  |
+
+### Development Direction
+- **Current sprint/focus:** ...
+- **Next milestones:** ...
+- **Technical debt:** ...
+- **Opportunities:** ...
+
+### Key Findings
+1. ...
+2. ...
+3. ...
+
+### Recommendations
+- **Immediate:** ...
+- **Short-term:** ...
+- **Consider:** ...
+
+## Mindset
+
+* Be thorough — read everything, assume nothing
+* Connect the dots — understand WHY decisions were made
+* Think forward — where is this project heading?
+* Be critical — identify risks, gaps, opportunities
+* Document discoveries — update CLAUDE.md with important findings

package/assets/slash-commands/growth.md

@@ -0,0 +1,190 @@
+---
+name: growth
+description: Research-driven strategic ideation - directions, competitors, monetization, traffic
+---
+
+# Growth: Strategic Research & Ideation
+
+Deep dive into the product, research the market, and generate actionable growth ideas.
+
+**Prerequisites:**
+1. Read PRODUCT.md and ARCHITECTURE.md thoroughly
+2. Understand current features, target users, and business model
+3. Use web search extensively for market research
+
+## Phase 1: Understand the Product
+
+Before any research, answer these:
+
+- What problem does this product solve?
+- Who is the target user? (Be specific)
+- What's the current monetization model?
+- What's the unique value proposition?
+- What stage is the product at? (MVP, Growth, Mature)
+- What are the current metrics? (if available)
+
+## Phase 2: Market Research
+
+### 2.1 Competitive Landscape
+
+Use web search to find:
+
+```
+Search: "[product category] competitors 2024"
+Search: "[product category] market size"
+Search: "best [product category] tools"
+Search: "[competitor name] pricing"
+Search: "[competitor name] features"
+```
+
+Document:
+| Competitor | Pricing | Key Features | Strengths | Weaknesses |
+|------------|---------|--------------|-----------|------------|
+| ...        | ...     | ...          | ...       | ...        |
+
+### 2.2 Industry Trends
+
+```
+Search: "[product category] trends 2024 2025"
+Search: "[product category] future predictions"
+Search: "[technology] adoption rate"
+```
+
+- What's growing? What's declining?
+- What new technologies are emerging?
+- What are users demanding that nobody provides?
+
+### 2.3 Success Stories
+
+```
+Search: "[product category] startup success story"
+Search: "how [successful company] grew"
+Search: "[product category] case study growth"
+```
+
+- How did successful products in this space grow?
+- What tactics worked? What failed?
+
+## Phase 3: Strategic Directions
+
+### 3.1 Product Directions — What to Build
+
+Based on research, identify:
+
+**Quick Wins** (< 1 week, high impact)
+- Features competitors have that we don't
+- Low-hanging fruit from user feedback
+- Integration opportunities
+
+**Strategic Bets** (1-3 months, transformative)
+- Blue ocean opportunities (what nobody does well)
+- Emerging technology applications
+- New market segments
+
+**Moonshots** (6+ months, game-changing)
+- What would 10x the product?
+- What would make competitors irrelevant?
+
+### 3.2 Monetization — How to Make Money
+
+Research pricing models:
+```
+Search: "[product category] pricing models"
+Search: "SaaS pricing strategies 2024"
+Search: "[competitor] how they make money"
+```
+
+Consider:
+- Freemium → Premium conversion tactics
+- Usage-based vs subscription pricing
+- Enterprise tier opportunities
+- Add-on revenue streams
+- Marketplace/platform fees
+- API/developer monetization
+
+**Revenue Ideas:**
+| Idea | Effort | Revenue Potential | Risk |
+|------|--------|-------------------|------|
+| ...  | S/M/L  | $/$$/$$$          | L/M/H|
+
+### 3.3 Traffic & Exposure — How to Get Users
+
+Research acquisition channels:
+```
+Search: "[product category] marketing strategies"
+Search: "how to get users for [product type]"
+Search: "[competitor] marketing strategy"
+Search: "developer marketing tactics"
+```
+
+**Organic Channels:**
+- SEO opportunities (what keywords to target?)
+- Content marketing (what content would attract users?)
+- Community building (where do target users hang out?)
+- Open source strategy (what to open source?)
+- Word of mouth triggers (what makes users share?)
+
+**Paid Channels:**
+- Which platforms have our target users?
+- What's the estimated CAC?
+- What competitors are advertising where?
+
+**Viral Mechanics:**
+- Built-in sharing moments?
+- Referral program design?
+- Network effects potential?
+
+**PR & Awareness:**
+- Product Hunt launch strategy
+- Hacker News / Reddit presence
+- Industry publications to target
+- Influencer/creator partnerships
+- Conference/event opportunities
+
+## Phase 4: Prioritized Recommendations
+
+After all research, provide:
+
+### Immediate Actions (This Week)
+1. ...
+2. ...
+
+### Short-term Priorities (This Month)
+1. ...
+2. ...
+
+### Strategic Initiatives (This Quarter)
+1. ...
+2. ...
+
+### Ideas Backlog (Future Consideration)
+- ...
+
+## Output Format
+
+### Executive Summary
+- Key market insights (3-5 bullets)
+- Biggest opportunities identified
+- Recommended focus areas
+
+### Detailed Findings
+- Competitive analysis table
+- Market trends summary
+- Success pattern analysis
+
+### Action Items
+- Prioritized list with effort/impact scores
+- Clear next steps
+- Metrics to track
+
+### Sources
+- List all URLs and sources consulted
+- Date of research
+
+## Mindset
+
+* Data over opinions — back claims with research
+* Think like an investor — where's the ROI?
+* Think like a user — what would make you pay/share?
+* Be specific — vague ideas are useless
+* Be bold — safe ideas rarely win markets

package/assets/slash-commands/product.md

@@ -0,0 +1,120 @@
+---
+name: product
+description: Review product design from user perspective for business value
+---
+
+# Product: Design Review for Business Value
+
+Evaluate product design holistically — from user experience to business impact.
+
+## 1. User Journey Audit
+
+### First-Time User (0-5 minutes)
+- Can they understand what the product does within 10 seconds?
+- Is the value proposition immediately clear?
+- Can they complete the core action without guidance?
+- What's the time-to-first-value? Can it be shorter?
+- Are there unnecessary barriers (signup walls, complex forms)?
+
+### Learning User (5 min - 1 week)
+- Is progressive disclosure working? (simple → advanced)
+- Are help/tooltips available but not intrusive?
+- Can they recover from mistakes easily?
+- Is the learning curve appropriate for the target audience?
+- What % would abandon at this stage? Why?
+
+### Power User (1 week+)
+- Are there shortcuts for frequent actions?
+- Can they customize/personalize their experience?
+- Are advanced features discoverable but not cluttering?
+- What keeps them coming back? What might make them leave?
+- Would they recommend it? Why or why not?
+
+## 2. Business Value Assessment
+
+### Acquisition
+- Does the landing/home page convert visitors to users?
+- Is the onboarding optimizing for activation, not just signup?
+- What's the friction cost vs. quality filter tradeoff?
+
+### Activation
+- What's the "aha moment"? Is the path to it clear?
+- How many steps to experience core value?
+- What % of signups become activated users?
+
+### Retention
+- What triggers bring users back?
+- Are there habit-forming loops?
+- What would make a user churn? Are we addressing it?
+
+### Revenue
+- Is the pricing/upgrade path clear and compelling?
+- Are premium features properly showcased?
+- Does free tier demonstrate value without giving everything away?
+
+### Referral
+- Is there a natural share moment?
+- Would users be proud to show this to others?
+- Is word-of-mouth built into the experience?
+
+## 3. UX Heuristics Check
+
+- [ ] **Visibility** — System status always clear?
+- [ ] **Match** — Speaks user's language, not dev jargon?
+- [ ] **Control** — Easy undo, escape, go back?
+- [ ] **Consistency** — Same patterns throughout?
+- [ ] **Prevention** — Prevents errors before they happen?
+- [ ] **Recognition** — Options visible, not memorized?
+- [ ] **Flexibility** — Works for novice and expert?
+- [ ] **Aesthetics** — Clean, focused, no clutter?
+- [ ] **Recovery** — Helpful error messages with solutions?
+- [ ] **Help** — Documentation accessible when needed?
+
+## 4. Accessibility & Inclusivity
+
+- Works without mouse (keyboard navigation)?
+- Works with screen readers?
+- Color contrast sufficient?
+- Text resizable without breaking layout?
+- Works on slow connections?
+- Works on old devices/browsers?
+- Internationalization-ready?
+
+## 5. 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?
+
+## Process
+
+1. **Walk through** the entire product as each user type
+2. **Document** friction points, confusion, delight moments
+3. **Prioritize** by business impact × effort to fix
+4. **Propose** specific, actionable improvements
+5. **Validate** proposals against business goals
+
+## Output
+
+### Findings Report
+| Issue | User Type | Business Impact | Effort | Priority |
+|-------|-----------|-----------------|--------|----------|
+| ...   | ...       | High/Med/Low    | S/M/L  | P0/P1/P2 |
+
+### Quick Wins (< 1 day effort, high impact)
+- ...
+
+### Strategic Improvements (larger effort, transformative)
+- ...
+
+### Questions for User Research
+- ...
+
+## Mindset
+
+* You ARE the user. Feel their frustration, anticipate their needs.
+* Every click, every second of confusion costs business value.
+* Beautiful ≠ usable. Usable + beautiful = delightful.
+* The best UI is invisible — users achieve goals without noticing the interface.
+* Design for the user you have, not the user you wish you had.

package/package.json

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