@sylphx/flow 0.2.1 → 0.2.3

package/dist/assets/knowledge/guides/system-prompt.md

@@ -0,0 +1,344 @@
+---
+name: System Prompt Writing Guide
+description: MEP (Minimal Effective Prompt) framework for writing high-signal, efficient prompts
+---
+
+# Minimal Effective Prompt (MEP) Framework
+
+> **Core Philosophy**: Find the smallest set of high-signal tokens that maximize desired outcomes.
+
+## Core Principles
+
+### The Three Golden Rules
+
+**1. Trust LLM Intelligence**
+Modern LLMs (GPT-4, Claude Sonnet 4+):
+- Strong contextual reasoning and inference
+- Pattern generalization from 1-2 examples
+- Trained on common frameworks, standards, best practices
+- Understand semantic compression
+
+**2. Eliminate Redundancy**
+Each concept appears **exactly once**.
+- Stated in A → Don't repeat in B
+- Implied by X → Don't state explicitly
+- Common sense → Don't state at all
+
+**3. Achieve Goldilocks Zone**
+Balance:
+- Too rigid: Hardcoded if-else, excessive checklists, brittle rules
+- Too vague: "Be helpful", high-level platitudes, no concrete guidance
+- **Goldilocks**: Specific guidance + flexible heuristics
+
+---
+
+## The MEP Framework
+
+### The Three Questions (For Every Token)
+
+**1. Is this UNIQUE?**
+- Can it be inferred from other parts?
+- Is it in LLM's training data?
+- Is it just a rewording?
+
+**2. Is this ACTIONABLE?**
+- Does it enable concrete behavior?
+- Can LLM act on this?
+- Is it specific enough?
+
+**3. Is this HIGH-SIGNAL?**
+- Does it directly impact outcome?
+- Is it critical to success?
+- Would removing it degrade performance?
+
+**Decision Matrix:**
+```
+All 3 YES → KEEP (essential)
+Any 1 NO  → REMOVE or MERGE
+All 3 NO  → DELETE immediately
+```
+
+### Signal Density Target
+
+- **Good**: 60-70% high-signal
+- **Great**: 70-80% high-signal
+- **Exceptional**: 80-90% high-signal
+
+Calculate: (High-signal tokens / Total tokens) × 100%
+
+---
+
+## Writing Process
+
+### Phase 1: Brain Dump
+Capture all requirements, rules, guidance. Don't filter. Focus on completeness.
+
+### Phase 2: Structure
+Organize into logical sections:
+1. Core Rules/Principles (always true)
+2. Identity/Role (who is LLM)
+3. Foundational Concepts (philosophy)
+4. Operational Guidance (how to work)
+5. Tools & Resources (available)
+6. Decision Support (when unclear)
+7. Standards (quality, security)
+8. Anti-Patterns (what to avoid)
+9. Output Format (what to deliver)
+
+### Phase 3: Identify Redundancy
+
+**Type A - Exact Repetition**: Same concept, same wording → Keep 1st, delete all others
+
+**Type B - Semantic Repetition**: Same concept, different wording → Keep clearest
+
+**Type C - Implied Repetition**: B is logical consequence of A → Keep only A
+
+**Type D - Section Redundancy**: Entire section restates another → Delete entire section
+
+### Phase 4: Apply The Three Questions
+
+For each section, validate against uniqueness, actionability, high-signal.
+
+**Remove common sense:**
+❌ "Never commit broken code", "Use descriptive names", "Test your code"
+
+**Keep specific guidance:**
+✅ "Run tests after EVERY change", "Refactor on 3rd duplication", "Extract when >20 lines"
+
+### Phase 5: Optimize Expression
+
+**Compact Syntax:**
+```
+❌ "First do A, then B, then C" → ✅ "A → B → C"
+❌ "Choose from: A, B, or C" → ✅ "Choose: A / B / C"
+❌ "If X then Y" → ✅ "X? → Y"
+❌ "Never X, never Y, never Z" → ✅ "Never: X / Y / Z"
+```
+
+**List Consolidation:**
+- **Bullets**: Complex items needing explanation
+- **Commas**: Simple, parallel items
+
+**Remove Filler:**
+```
+❌ "You should always make sure to test" → ✅ "Always test"
+❌ "It is important that you document" → ✅ "Document"
+❌ "Try to choose the simplest" → ✅ "Choose simplest"
+```
+
+**Merge Related Sections:**
+When sections are conceptually related, <50 tokens each, total merged <150 tokens.
+
+### Phase 6: Format & Polish
+
+**Headers**: Use hierarchy (`#` > `##` > `###`), avoid excessive nesting
+
+**Emphasis**: Bold for key terms (first mention only), emoji sparingly (section markers only)
+
+**Code Blocks**: For templates, examples, specific formats only
+
+**Tables**: For comparisons and decision matrices
+
+---
+
+## Judgment Criteria
+
+### What to KEEP
+
+**Unique Information:**
+- Custom conventions (document format, commit format, priority hierarchy)
+- Novel frameworks (execution modes, decision frameworks)
+- Specific guidance ("Refactor on 3rd duplication", "Extract when >20 lines")
+
+**Actionable Directives:**
+- Specific actions ("Run tests after every change", "Validate inputs at boundaries")
+- Clear workflows ("Analyze → Check → Assume → Implement")
+- Decision rules ("Ambiguous? → existing > conventions > standards")
+
+**High-Signal Examples:**
+1-2 representative examples per concept (LLM generalizes)
+
+### What to REMOVE
+
+**Redundant Content:**
+- Exact repetition (same concept, same wording)
+- Semantic repetition (same concept, different wording)
+- Implied content (B follows from A)
+- Redundant sections (duplicates another section)
+
+**Low-Signal Content:**
+- Common sense ("Write clean code", "Comment your code")
+- Vague directives ("Be thoughtful", "Think carefully", "Consider context")
+- Over-emphasis ("🔴 CRITICAL: MUST VERIFY" → "Verify")
+
+**Verbose Expression:**
+- Filler words ("You should always...", "It is important that...")
+- Redundant explanations (LLM infers implications)
+
+---
+
+## Common Pitfalls
+
+**Over-Specification**: 50+ conditional rules → Principles + heuristics instead
+
+**Repetition for Emphasis**: Stating "Never block" 4 times → State once, trust LLM
+
+**Excessive Examples**: 5+ examples of same pattern → 2 examples sufficient
+
+**Common Sense Inclusion**: Universal programming knowledge → Omit
+
+**Vague Directives**: "Be thoughtful" → Specific, actionable
+
+**Format Overload**: Too many emoji/bold/emphasis → Minimal, purposeful
+
+**Section Bloat**: 20+ tiny sections → Merge related (8-15 sections ideal)
+
+---
+
+## Quality Checklist
+
+### Before Optimization
+- [ ] Brain dump complete
+- [ ] Organized into sections
+- [ ] All examples included
+- [ ] All rules documented
+
+### During Optimization
+- [ ] No concept appears >1 time
+- [ ] Every statement passes 3 questions
+- [ ] Compact syntax used
+- [ ] Related sections merged
+
+### After Optimization
+- [ ] All scenarios handleable
+- [ ] All frameworks fully specified
+- [ ] 40-60% token reduction
+- [ ] 75-85% signal density
+- [ ] 8-15 main sections
+- [ ] 1-2 examples per concept
+- [ ] Goldilocks Zone achieved (specific + flexible)
+- [ ] Clean, scannable formatting
+
+---
+
+## Decision Trees
+
+### "Should I keep this content?"
+```
+Is it unique (not inferable)?
+├─ NO → DELETE
+└─ YES → Is it actionable?
+    ├─ NO → DELETE
+    └─ YES → Is it high-signal?
+        ├─ NO → DELETE
+        └─ YES → KEEP
+```
+
+### "Should I include this example?"
+```
+How many examples already?
+├─ 0 → ADD 1-2 representative
+├─ 1-2 → GOOD, stop
+└─ 3+ → TOO MANY, remove least representative
+```
+
+### "Should I merge these sections?"
+```
+Are they related?
+├─ NO → Keep separate
+└─ YES → Each <50 tokens?
+    ├─ NO → Keep separate
+    └─ YES → Total merged <150?
+        ├─ NO → Keep separate
+        └─ YES → MERGE
+```
+
+---
+
+## Practical Examples
+
+### Example 1: Optimizing Rules
+
+**Before (110 tokens):**
+```markdown
+## Rule 1: Never Block On Uncertainty
+
+**IMPORTANT**: You must never stop working due to missing information...
+
+When you encounter uncertainty:
+1-8. [Long list of steps]
+
+Remember: It is better to complete...
+```
+
+**After (15 tokens, -86%):**
+```markdown
+## Rule 1: Never Block
+
+Make reasonable assumptions, document them, complete task.
+```
+
+### Example 2: Optimizing Decisions
+
+**Before (115 tokens):**
+```markdown
+When you face an ambiguous requirement:
+- You should choose the most reasonable...
+[Multiple verbose bullet points]
+```
+
+**After (30 tokens, -74%):**
+```markdown
+**Ambiguous?** → existing patterns > conventions > standards. Document assumption.
+**Missing info?** → Industry defaults, make configurable.
+**Multiple options?** → Simplest. Note alternatives.
+```
+
+---
+
+## Token Budget Guidelines
+
+**System Prompt Types:**
+
+| Type | Target Tokens | Max Tokens | Focus |
+|------|--------------|------------|-------|
+| Shared Protocol | 150-250 | 300 | Lightweight, universal |
+| Agent-Specific | 800-1200 | 1500 | Comprehensive, specialized |
+| Task-Specific | 300-500 | 700 | Focused, actionable |
+
+---
+
+## Final Validation
+
+**A great prompt should feel like:**
+- ✅ Well-written manual (clear, concise, complete)
+- ✅ Expert colleague conversation (professional, efficient)
+- ✅ Set of principles (guiding, not restricting)
+
+**A great prompt should NOT feel like:**
+- ❌ Legal terms (exhaustive, repetitive, cautious)
+- ❌ IKEA instructions (step-by-step, rigid, brittle)
+- ❌ Drill sergeant (emphasis, repetition, no trust)
+
+**The Ultimate Tests:**
+
+**Can you explain your prompt's purpose in one sentence?**
+- Yes → Focused ✅
+- No → Tries to do too much ❌
+
+**Can you identify high-signal vs noise?**
+- 75%+ essential → Great ✅
+- 50-75% essential → Good, can improve 🟡
+- <50% essential → Too much noise ❌
+
+**Would you want to read your prompt?**
+- Yes → Clean, professional, scannable ✅
+- No → Needs work ❌
+
+---
+
+## Conclusion
+
+Great prompts = **Clarity** (each concept once) + **Trust** (LLM intelligence) + **Economy** (every token earns place) + **Effectiveness** (achieve outcomes)
+
+Shorter. Clearer. More effective. 🎯

package/dist/assets/knowledge/guides/tech-stack.md

@@ -0,0 +1,92 @@
+---
+name: Tech Stack (Recommended)
+description: Opinionated stack (Next.js, PandaCSS, GraphQL, Pothos, Drizzle) - optimized for LLM accuracy
+---
+
+# Technical Stack
+
+Scalable, secure SaaS stack. Type safety, performance, serverless. Validate with E2E (Playwright), monitor with Sentry.
+
+## Domain-Driven Architecture
+
+Feature-based layout: `src/features/<domain>/` (frontend), `src/graphql/<domain>/` (backend). Colocate related code. Cross-domain via explicit exports.
+
+**Frontend domains**: `src/features/<domain>/` → `components/`, `hooks/`, `store/`, `services/`, `utils/`, `types.ts`
+**Backend domains**: `src/graphql/<domain>/` → `types/`, `queries.ts`, `mutations.ts`, `subscriptions.ts`, `loaders.ts` (DataLoader for N+1)
+**Shared infra**: `src/lib/` (clients), `src/app/` (routes, providers)
+
+## Frontend Stack
+
+**Framework**: Next.js App Router (routing, SSR/SSG, Turbopack). `src/app/(app)/dashboard/page.tsx`
+
+**UI**: React + Radix UI primitives (a11y). Prefer Radix for structural/interactive, custom only when Radix lacks. `src/features/<domain>/components/`
+
+**State**: Zustand (global sessions). Avoid Redux. `src/features/<domain>/store/`
+
+**Styling**: PandaCSS (type-safe atomic CSS-in-JS, zero-runtime, <10KB)
+- **Tokens/Themes**: `panda.config.ts` semantics (`colors.primary.500`), `_dark`/CSS vars
+- **Atomic**: Inline JSX (`bg-primary-500 p-4`), `css({ color: 'red' })` merges
+- **Recipes**: `cva` (Button variants), `sva` slots (Card), `jsx: ['Button']` track
+- **Merging**: `cx(recipe(), css({ bg: 'red' }))` overrides
+- **Optimize**: `staticCss: { recipes: '*' }`, purge globs, `panda analyze`, Next.js plugins
+
+**Hooks**: react-use (localStorage, useMeasure, useDebounce, sensors), urql (GraphQL cache, SSR, subscriptions, offline, batching)
+
+**Auth**: Better Auth (passkey-first, 2FA), reCAPTCHA (bot mitigation)
+
+## Backend Stack
+
+GraphQL-first, serverless. `src/graphql/<domain>/`
+
+**Schema/Server**: Pothos (code-first), Yoga. `gql.tada` for all GraphQL docs (never raw templates), `graphql-scalars` for custom scalars
+- Modular `queryField`, typed client hooks via `gql.tada`, colocate operations with components/pages, DataLoader in `loaders.ts` (batch, cache, prevent N+1)
+
+**Auth**: Better Auth (JWT/Redis denylist), rotate tokens
+
+**Request Context**: AsyncLocalStorage with `headers()`/`cookies()` → tiny accessors (`getAuthSession()`, `getLocale()`) instead of passing context objects
+
+**ORM**: Drizzle (queries/migrations). **Never** raw SQL except unavoidable complex cases (use parameterized placeholders). Query builder methods (`eq`, `and`, `or`). Schemas/queries per domain: `src/domains/<domain>/data/`
+- `db.select().from(users).where(eq(users.id, userId))`
+
+**Security**: @simplewebauthn/server, Redis limits
+
+## Data Layer
+
+**DB**: PostgreSQL (Neon/pgBouncer), RLS. Scale: Partition (logs/date)
+
+**Cache/RT**: Upstash Redis (cache/pubsub/streams). TTL (24h), event streams
+
+## Payments
+
+**Billing**: Stripe (Checkout/Portal/Invoices/webhooks idempotent). Wallet credit on session complete, 3x retry
+
+## DevOps
+
+**Local**: Docker Compose (stack), bun, Biome (linting/formatting), Lefthook (Git hooks)
+- **Biome Ignore**: Tests (`__tests__/**`, `*.test.*`), generated (`*.generated.*`, `dist/**`), project-specific (`styled-system`, `*.gql.tada.ts`, `drizzle`, `.next`)
+- **Biome Config**: Recommended + custom flow, ignoreUnknown false
+- **Lefthook**: Pre-commit (Biome, type-check), pre-push (tests). `bun add -D lefthook`, `lefthook install`
+- **Entry**: `bun install && migrate && dev`, Lefthook auto-runs, `biome check .` in CI
+
+**Deploy**: Serverless (Vercel), GraphQL BFF. CI: Actions, 99.9% SLO alerts
+
+## Framework Rules
+
+### GraphQL Standards
+- **IDs**: Use `ID` scalar (not `String`). Base64 for keys.
+- **Enums/Unions**: Enums for fixed (Role), unions for polymorphic (Result = Post | User). Limit depth 3-5.
+
+### GraphQL Document Placement
+Colocate operations in domain services (`src/features/<domain>/services/`), `src/graphql/<domain>/`
+- **Routes/pages**: Import from domain services for tree-shaking
+- **Components**: Queries/mutations in domain services, export typed helpers
+- **Stores**: GraphQL docs in domain services
+- **Fragments**: `src/features/<domain>/services/fragments/` with barrel exports
+- **Tests**: Colocate under `src/features/<domain>/`
+- **Typed modules**: `.gql.ts` stay domain-local, enriched by `graphql-env.d.ts`
+
+### Pothos Best Practices
+- **ID Handling**: `exposeId: false` by default (security), `exposeId: true` only when needed
+- **Subscription Ordering**: `subscribe` before `resolve` for TS inference
+- **Extensions**: `extendType` for modularity, integrate gql.tada for E2E types
+- **Errors**: Custom scalars (graphql-scalars), try-catch with GraphQLError

package/dist/assets/knowledge/guides/ui-ux.md

@@ -0,0 +1,44 @@
+---
+name: UI/UX Guidelines
+description: Modern SPA design patterns, PandaCSS, Radix UI, conversational interfaces
+---
+
+# Modern SPA UI/UX
+
+Apply when designing/updating single-page application interfaces. Keep concise, modular, consistent with conversational products (chat-first SaaS).
+
+## Core Principles
+- Minimalist functionalism: Remove clutter, highlight primary content/controls
+- Balanced readability: Letter-spacing 1.2–1.5, line-height ≥1.5, clear hierarchy
+- Global consistency: Reuse tokens for spacing, color, typography, radii
+- Perceived fluidity: Transitions <200ms, never block input
+
+## Visual System
+- **Color**: Dark backgrounds (#111–#1A1A), optional light mode. One accent for CTAs. WCAG AA contrast ≥4.5:1
+- **Shapes**: 8–12px border radius. Cards with subtle shadows (0 1px 3px rgba(0,0,0,0.1))
+- **Typography**: Sans-serif (Inter, SF Pro). Bold headings, progressively larger. Body 14–16px, 1.5 line-height
+
+## Micro-Interactions
+- Duration: 200–400ms ease-in-out
+- Hover: 1.03× scale or deeper shadow
+- Active: 0.95–0.98× for tactile feedback
+- Page transitions: Fade/slide, prefetch routes (<100ms latency)
+
+## Interaction Patterns
+- **Conversational**: Messages top-to-bottom, timestamp/metadata aligned (chat UIs)
+- **Input**: Pin primary composer at viewport bottom, minimal controls
+- **Feedback**: Visual response on every submit/load/state change (spinners, progress, confirmations)
+- **Expandable**: Collapse long sections, keep critical details visible
+
+## UX Guidelines
+- Persistent nav (top/sidebar), limit to 5–7 items
+- Eliminate distractions: No autoplay, reduce focal points
+- Natural scrolling, lazy loading for long lists/media
+- Reusable primitives (buttons, cards, inputs) with consistent props
+- Mobile-first: Validate 320px, 768px, 1024px breakpoints, identical functionality
+
+## Validation
+- Contrast/readability in dark/light (axe-core, Lighthouse ≥90)
+- Hover/tap feedback within 50ms
+- Responsive layouts on phone/tablet/desktop, adjust spacing/typography for overflow
+- Document UI decisions (tokens, components) for reuse

package/dist/assets/knowledge/stacks/nextjs-app.md

@@ -0,0 +1,165 @@
+---
+name: Next.js Application
+description: Next.js App Router, Server Components, data fetching, routing, deployment
+---
+
+# Next.js Development
+
+## When Next.js vs React SPA
+
+**Next.js**: SEO matters, fast initial load, full-stack in one codebase
+**React SPA**: Dashboard/admin, behind auth, separate backend exists
+
+## App Router vs Pages Router
+
+**App Router (app/)** - Recommended:
+- Server Components by default (less JS)
+- Built-in layouts, loading, error states
+- Better data fetching patterns
+
+**Pages Router (pages/)**: Legacy maintenance only
+
+## Server vs Client Components
+
+### Decision Tree
+```
+Needs interactivity? (onClick, useState, hooks)
+├─ YES → 'use client'
+└─ NO → Server Component (default)
+```
+
+**Server Components (default):**
+- Render on server, direct DB access, zero client JS
+- Can't use hooks/handlers
+
+**Client Components ('use client'):**
+- Hooks, handlers, interactivity, ships JS to browser
+
+### Composition Pattern
+Server components wrap client components. Fetch data in server, pass as props to client.
+
+## Data Fetching
+
+### Cache Options
+```typescript
+// Cached forever (default)
+await fetch('https://api.example.com/data')
+
+// Cache with revalidation
+await fetch('...', { next: { revalidate: 3600 } })
+
+// Never cache
+await fetch('...', { cache: 'no-store' })
+```
+
+### Parallel Fetching
+```typescript
+// BAD - Sequential
+const posts = await getPosts()
+const users = await getUsers()
+
+// GOOD - Parallel
+const [posts, users] = await Promise.all([getPosts(), getUsers()])
+```
+
+## Caching & Revalidation
+
+**Time-based (ISR):**
+```typescript
+export const revalidate = 3600 // Every hour
+```
+
+**On-demand:**
+```typescript
+import { revalidatePath, revalidateTag } from 'next/cache'
+revalidatePath('/posts')
+revalidateTag('posts')
+```
+
+**Dynamic (no cache):**
+```typescript
+export const dynamic = 'force-dynamic'
+```
+
+## Routing
+
+### File Structure
+```
+app/page.tsx              → /
+app/about/page.tsx        → /about
+app/blog/[slug]/page.tsx  → /blog/:slug
+app/(marketing)/features/page.tsx → /features (route group)
+```
+
+### Special Files
+- `layout.tsx`: Shared UI for segment + children
+- `loading.tsx`: Loading UI (Suspense boundary)
+- `error.tsx`: Error UI (must be 'use client')
+
+## Authentication
+
+### Middleware (Route Protection)
+```typescript
+// middleware.ts
+export function middleware(request: Request) {
+  const token = request.cookies.get('token')
+  if (!token) return NextResponse.redirect(new URL('/login', request.url))
+}
+
+export const config = { matcher: '/dashboard/:path*' }
+```
+
+### Server Actions (Form Handling)
+```typescript
+// app/actions.ts
+'use server'
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title')
+  if (!title) return { error: 'Missing title' }
+
+  const post = await db.posts.create({ data: { title } })
+  revalidatePath('/posts')
+  return { success: true, post }
+}
+
+// In component
+<form action={createPost}>
+  <input name="title" />
+  <button type="submit">Create</button>
+</form>
+```
+
+## Performance
+
+**Image**: Use `<Image>` with `priority` for above-fold, `placeholder="blur"` for UX
+**Font**: `next/font/google` for automatic optimization
+**Code Splitting**: `dynamic(() => import('./Heavy'), { ssr: false })` for client-only heavy components
+
+## Common Pitfalls
+
+❌ **'use client' everywhere** → Only for interactivity
+❌ **Over-fetching** → Fetch once in layout/page, pass as props
+❌ **Not streaming** → Use Suspense boundaries
+❌ **Forgetting revalidation** → Always revalidate after mutations
+
+## Environment Variables
+
+```bash
+DATABASE_URL="..." # Server only
+NEXT_PUBLIC_API_URL="..." # Exposed to browser (must start with NEXT_PUBLIC_)
+```
+
+## Decision Guide
+
+**Server Component:**
+- Fetching data, backend access, large dependencies, non-interactive
+
+**Client Component:**
+- Interactive (clicks, state, hooks), browser APIs, event handlers
+
+**API Route:**
+- Hide API keys, webhooks, complex server logic, third-party integrations
+
+**Server Action:**
+- Form submissions, mutations (CRUD), simple server ops