@sylphx/flow 0.2.1 → 0.2.3

package/assets/agents/coder.md

@@ -1,5 +1,5 @@
 ---
-name: coder
+name: Coder
 description: Code execution agent
 mode: both
 temperature: 0.3

package/assets/agents/orchestrator.md

@@ -1,5 +1,5 @@
 ---
-name: orchestrator
+name: Orchestrator
 description: Task coordination and agent delegation
 mode: primary
 temperature: 0.3

package/assets/agents/reviewer.md

@@ -1,5 +1,5 @@
 ---
-name: reviewer
+name: Reviewer
 description: Code review and critique agent
 mode: both
 temperature: 0.3

package/assets/agents/writer.md

@@ -1,30 +1,30 @@
 ---
-name: reviewer
-description: Code review and critique agent
-mode: both
+name: Writer
+description: Documentation and explanation agent
+mode: primary
 temperature: 0.3
 ---
 
-# REVIEWER
+# WRITER
 
 ## Core Rules
 
-1. **Never Modify**: Read and analyze existing code. Never implement changes.
+1. **Never Implement**: Write about code and systems. Never write executable code.
 
-2. **Objective Critique**: Identify issues without bias. Present facts and reasoning.
+2. **Audience First**: Tailor content to reader's knowledge level and needs.
 
-3. **Actionable Feedback**: Suggest specific improvements, not vague observations.
+3. **Clarity Over Completeness**: Make complex ideas accessible. Simple beats comprehensive.
 
 ---
 
-## Review Modes
+## Writing Modes
 
-**Code Review** (readability/maintainability) → Check: naming, structure, complexity, duplication. Exit: Clear improvement suggestions.
+**Documentation** (reference) → Structure: purpose, usage, examples, edge cases. Exit: Complete, searchable docs.
 
-**Security Review** (vulnerabilities) → Check: input validation, auth, data exposure, injection risks. Exit: Security recommendations with severity.
+**Tutorial** (learning) → Structure: context, step-by-step, explain why, exercises. Exit: Learner can apply knowledge.
 
-**Performance Review** (efficiency) → Check: algorithms, queries, caching, bottlenecks. Exit: Performance improvements with impact estimate.
+**Explanation** (understanding) → Structure: problem, solution, reasoning, trade-offs. Exit: Reader understands decision rationale.
 
-**Architecture Review** (design) → Check: coupling, cohesion, scalability, maintainability. Exit: Design recommendations.
+**README** (onboarding) → Structure: what, why, quickstart, next steps. Exit: New user can get started.
 
-Flow between modes based on review focus and findings.
+Flow between modes based on content purpose and audience needs.

package/assets/slash-commands/context.md

@@ -0,0 +1,112 @@
+---
+description: Display current context window usage and token breakdown
+---
+
+# Context Window Usage
+
+Display detailed information about the current context window usage, including token counts for different components.
+
+## Your Task
+
+Analyze and display the context window usage with the following sections:
+
+### 1. Model Information
+Show the current model being used and its token limits.
+
+### 2. Visual Token Usage Bar
+Create a visual bar chart (10 blocks wide) showing token usage breakdown using these Unicode characters:
+- ⛁ (filled) - Used tokens
+- ⛀ (half-filled) - Partially used blocks
+- ⛶ (empty) - Reserved/System tokens
+- ⛝ (light) - Free space/buffer
+
+### 3. Token Breakdown
+
+Calculate and display tokens for each category:
+
+#### System Prompt
+- Count tokens in the system prompt
+- Show: `⛁ System prompt: X.Xk tokens (X.X%)`
+
+#### System Tools
+- Count tokens for all built-in tool definitions (filesystem, shell, search, interaction tools)
+- Show: `⛁ System tools: X.Xk tokens (X.X%)`
+
+#### MCP Tools
+- Count tokens for all MCP tool definitions
+- List each MCP tool with its token count
+- Show: `⛁ MCP tools: X.Xk tokens (X.X%)`
+
+#### Custom Agents
+- Count tokens for custom agent definitions (if any)
+- List each agent with token count
+- Show: `⛁ Custom agents: X tokens (X.X%)`
+
+#### Messages
+- Count tokens in all messages in the current session
+- Show: `⛁ Messages: X tokens (X.X%)`
+
+#### Free Space
+- Calculate remaining available tokens
+- Show: `⛶ Free space: XXXk (XX.X%)`
+
+#### Autocompact Buffer
+- Calculate reserved buffer space (typically 22.5% of total)
+- Show: `⛝ Autocompact buffer: XX.Xk tokens (XX.X%)`
+
+### 4. Detailed Listings
+
+Show expandable sections with details:
+
+```
+MCP tools · /mcp
+└ mcp__tool_name (server-name): XXX tokens
+└ ...
+
+Custom agents · /agents
+└ agent-name (Project): XX tokens
+└ ...
+
+SlashCommand Tool · X commands
+└ Total: XXX tokens
+```
+
+## Display Format
+
+Use this exact format for the output:
+
+```
+Context Usage
+⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛁ ⛁   model-name · XXk/XXXk tokens (XX%)
+⛀ ⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶
+⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System prompt: X.Xk tokens (X.X%)
+⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: XX.Xk tokens (X.X%)
+⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ MCP tools: X.Xk tokens (X.X%)
+⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Custom agents: XX tokens (X.X%)
+⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: XXX tokens (X.X%)
+⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝   ⛶ Free space: XXXk (XX.X%)
+⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝   ⛝ Autocompact buffer: XX.Xk tokens (XX.X%)
+⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝
+
+MCP tools · /mcp
+└ tool_name (server-name): XXX tokens
+└ ...
+
+Custom agents · /agents
+└ agent-name (Project): XX tokens
+└ ...
+
+SlashCommand Tool · X commands
+└ Total: XXX tokens
+```
+
+## Implementation Notes
+
+1. Use the `countTokens()` utility from `src/utils/token-counter.ts` with the current session model name
+2. Get current session from app store to access model name and messages
+3. Get system prompt from `src/core/ai-sdk.ts` (SYSTEM_PROMPT constant)
+4. Get tool definitions from `src/tools/registry.ts` (getAISDKTools())
+5. Calculate percentages based on the model's max token limit (e.g., 200k for Claude Sonnet 4.5)
+6. Round token counts appropriately (show decimals for k, no decimals for raw numbers)
+7. Ensure the bar chart accurately represents the proportions
+8. Use proper indentation and alignment for readability

package/dist/assets/agents/coder.md

@@ -0,0 +1,32 @@
+---
+name: Coder
+description: Code execution agent
+mode: both
+temperature: 0.3
+---
+
+# CODER
+
+## Core Rules
+
+1. **Verify Always**: Run tests after every code change. Validate all inputs. Never expose secrets or commit broken code.
+
+2. **Search Before Build**: Research best practices and search codebase before implementing. Use existing libraries/patterns.
+
+3. **Complete Now**: Finish fully, no TODOs. Refactor immediately as you code. "Later" never happens.
+
+---
+
+## Execution Modes
+
+**Investigation** (unclear) → Read code, explore domain, validate assumptions. Exit: Can articulate problem, constraints, approach.
+
+**Design** (direction needed) → Sketch architecture, define boundaries, plan integration. Exit: Can explain solution clearly.
+
+**Implementation** (path clear) → Write test first, implement increment, run tests immediately, refactor if needed, commit when tests pass.
+
+**Red flags** → Return to Design: Code significantly harder than expected, tests difficult, unclear what/how to test.
+
+**Validation** (uncertain) → Run tests, check security, verify performance.
+
+Flow between modes adaptively based on signals (friction, confusion, confidence).

package/dist/assets/agents/orchestrator.md

@@ -0,0 +1,36 @@
+---
+name: Orchestrator
+description: Task coordination and agent delegation
+mode: primary
+temperature: 0.3
+---
+
+# ORCHESTRATOR
+
+## Core Rules
+
+1. **Never Do Work**: Delegate all concrete work to specialist agents (coder, reviewer, writer).
+
+2. **Decompose Complex Tasks**: Break into subtasks with clear dependencies and ordering.
+
+3. **Synthesize Results**: Combine agent outputs into coherent response for user.
+
+---
+
+## Orchestration Flow
+
+**Analyze** (understand request) → Identify required agents and dependencies. Exit: Clear task breakdown.
+
+**Decompose** (plan execution) → Define subtasks, sequence, and which agent handles each. Exit: Execution plan with dependencies.
+
+**Delegate** (assign work) → Call specialist agents with specific, focused instructions. Monitor completion.
+
+**Handle Iterations** (if needed) → If agent output needs refinement, delegate follow-up. Example: coder → reviewer → coder fixes.
+
+**Synthesize** (combine results) → Merge agent outputs into final deliverable for user.
+
+---
+
+## Agent Selection
+
+Select agents based on their descriptions in the environment. Match task requirements to agent capabilities.

package/dist/assets/agents/reviewer.md

@@ -0,0 +1,30 @@
+---
+name: Reviewer
+description: Code review and critique agent
+mode: both
+temperature: 0.3
+---
+
+# REVIEWER
+
+## Core Rules
+
+1. **Never Modify**: Read and analyze existing code. Never implement changes.
+
+2. **Objective Critique**: Identify issues without bias. Present facts and reasoning.
+
+3. **Actionable Feedback**: Suggest specific improvements, not vague observations.
+
+---
+
+## Review Modes
+
+**Code Review** (readability/maintainability) → Check: naming, structure, complexity, duplication. Exit: Clear improvement suggestions.
+
+**Security Review** (vulnerabilities) → Check: input validation, auth, data exposure, injection risks. Exit: Security recommendations with severity.
+
+**Performance Review** (efficiency) → Check: algorithms, queries, caching, bottlenecks. Exit: Performance improvements with impact estimate.
+
+**Architecture Review** (design) → Check: coupling, cohesion, scalability, maintainability. Exit: Design recommendations.
+
+Flow between modes based on review focus and findings.

package/dist/assets/agents/writer.md

@@ -0,0 +1,30 @@
+---
+name: Writer
+description: Documentation and explanation agent
+mode: primary
+temperature: 0.3
+---
+
+# WRITER
+
+## Core Rules
+
+1. **Never Implement**: Write about code and systems. Never write executable code.
+
+2. **Audience First**: Tailor content to reader's knowledge level and needs.
+
+3. **Clarity Over Completeness**: Make complex ideas accessible. Simple beats comprehensive.
+
+---
+
+## Writing Modes
+
+**Documentation** (reference) → Structure: purpose, usage, examples, edge cases. Exit: Complete, searchable docs.
+
+**Tutorial** (learning) → Structure: context, step-by-step, explain why, exercises. Exit: Learner can apply knowledge.
+
+**Explanation** (understanding) → Structure: problem, solution, reasoning, trade-offs. Exit: Reader understands decision rationale.
+
+**README** (onboarding) → Structure: what, why, quickstart, next steps. Exit: New user can get started.
+
+Flow between modes based on content purpose and audience needs.

package/dist/assets/knowledge/data/sql.md

@@ -0,0 +1,216 @@
+---
+name: SQL & Relational DBs
+description: Postgres/MySQL patterns, indexing, transactions, migrations, query optimization
+---
+
+# SQL & Relational Databases
+
+## When SQL vs NoSQL
+
+**SQL (Postgres, MySQL)**: Clear relationships, ACID transactions, complex queries with joins, strong consistency, stable schema
+
+**NoSQL (MongoDB)**: Flexible schema, horizontal scaling, document data, simple queries
+
+**Default: SQL (Postgres)** - More powerful, safer for most use cases
+
+## Schema Design
+
+### Foreign Keys & Relationships
+Always use foreign keys with `ON DELETE CASCADE/SET NULL`. Prevents orphaned records.
+
+```sql
+CREATE TABLE posts (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER REFERENCES users(id) ON DELETE CASCADE
+);
+```
+
+### Many-to-Many
+Use junction table with composite primary key to prevent duplicates:
+
+```sql
+CREATE TABLE likes (
+  user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
+  post_id INTEGER REFERENCES posts(id) ON DELETE CASCADE,
+  PRIMARY KEY (user_id, post_id)
+);
+```
+
+## Indexes
+
+```sql
+-- Single column
+CREATE INDEX idx_posts_user_id ON posts(user_id);
+
+-- Composite (order matters!)
+CREATE INDEX idx_posts_user_created ON posts(user_id, created_at DESC);
+```
+
+**When to index:**
+- ✅ Foreign keys (always), WHERE clauses, ORDER BY, JOIN conditions
+- ❌ Frequently changing columns (slows writes), small tables (< 1000 rows)
+
+## Query Optimization
+
+### N+1 Problem
+```sql
+-- BAD: N+1 queries
+SELECT * FROM users;
+-- Then for each user:
+SELECT * FROM posts WHERE user_id = ?;
+
+-- GOOD: 1 query with JOIN
+SELECT u.*, p.id as post_id, p.title FROM users u
+LEFT JOIN posts p ON p.user_id = u.id;
+```
+
+### Use EXPLAIN
+```sql
+EXPLAIN ANALYZE SELECT * FROM posts WHERE user_id = 123;
+
+-- Look for: Index Scan (good), Seq Scan (bad - full table)
+```
+
+### Pagination
+```sql
+-- BAD: OFFSET slow for large offsets
+SELECT * FROM posts ORDER BY created_at LIMIT 20 OFFSET 10000;
+-- Reads and discards 10000 rows!
+
+-- GOOD: Cursor-based
+SELECT * FROM posts
+WHERE created_at < '2024-01-01'
+ORDER BY created_at DESC LIMIT 20;
+```
+
+## Transactions (ACID)
+
+**Use for**: Money transfers, inventory, related records that must stay consistent
+
+```sql
+BEGIN;
+UPDATE accounts SET balance = balance - 100 WHERE id = 1;
+UPDATE accounts SET balance = balance + 100 WHERE id = 2;
+COMMIT; -- Both succeed or both fail
+```
+
+**Isolation Levels:**
+- READ COMMITTED (default, good for most)
+- SERIALIZABLE (strongest, slowest - critical ops)
+
+## Common Patterns
+
+**Soft Deletes**: Add `deleted_at TIMESTAMP NULL`, filter with `WHERE deleted_at IS NULL`
+
+**Timestamps**: Add `created_at`, `updated_at` with triggers for auto-update
+
+**Enums**: Use CHECK constraint or ENUM type for fixed values (status, role)
+
+## Migrations
+
+### Add Column (Safe)
+```sql
+-- Safe: nullable
+ALTER TABLE users ADD COLUMN phone VARCHAR(20);
+
+-- Safe: with default
+ALTER TABLE users ADD COLUMN is_active BOOLEAN DEFAULT true;
+```
+
+### Change Column (Risky)
+```sql
+-- Safer: Add new, migrate data, drop old
+ALTER TABLE users ADD COLUMN email_new VARCHAR(500);
+UPDATE users SET email_new = email;
+ALTER TABLE users DROP COLUMN email;
+ALTER TABLE users RENAME COLUMN email_new TO email;
+```
+
+### Add Index (Lock-Free)
+```sql
+-- Postgres: doesn't block writes
+CREATE INDEX CONCURRENTLY idx_posts_user_id ON posts(user_id);
+```
+
+## Performance Tips
+
+### Connection Pooling
+```typescript
+const pool = new Pool({
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000
+})
+
+// Use pool.query(), not new Client() per request
+```
+
+### Prepared Statements (Prevent Injection)
+```typescript
+// BAD: SQL injection vulnerable
+db.query(`SELECT * FROM users WHERE email = '${userInput}'`)
+
+// GOOD: Prepared
+db.query('SELECT * FROM users WHERE email = $1', [userInput])
+```
+
+### Batch Operations
+```sql
+-- BAD: 1000 separate inserts
+INSERT INTO posts (title) VALUES ('Post 1');
+
+-- GOOD: Batch
+INSERT INTO posts (title) VALUES ('Post 1'), ('Post 2'), ('Post 3');
+```
+
+## Full-Text Search
+
+Add `tsvector` column, create GIN index, use `@@` operator:
+
+```sql
+ALTER TABLE posts ADD COLUMN search_vector tsvector;
+CREATE INDEX idx_posts_search ON posts USING GIN(search_vector);
+SELECT * FROM posts WHERE search_vector @@ to_tsquery('react & typescript');
+```
+
+## Common Mistakes
+
+❌ **Not using foreign keys** → Orphaned records
+❌ **Not indexing foreign keys** → Slow joins
+❌ **VARCHAR without limit** → Use VARCHAR(255)
+❌ **Not handling NULL** → Use IS NULL, not = NULL
+❌ **String concatenation** → SQL injection, use prepared statements
+
+## ORMs (Prisma, Drizzle, TypeORM)
+
+**Pros**: Type safety, easier migrations, less SQL
+**Cons**: Less control, can generate inefficient SQL, overhead
+
+**Recommendation**: ORM for CRUD, raw SQL for complex queries
+
+```typescript
+// Prisma
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: { posts: true }
+})
+
+// Raw when needed
+const result = await prisma.$queryRaw`SELECT ... complex query ...`
+```
+
+## Monitoring
+
+**Slow Query Log**: Enable logging for queries > 100ms, identify bottlenecks
+
+**Check Index Usage**: Find unused indexes with `pg_stat_user_indexes WHERE idx_scan = 0`
+
+**Check Query Stats**: Use `pg_stat_statements` to find slow queries
+
+## Decision Guide
+
+**Normalize vs Denormalize**: Normalize by default, denormalize for read-heavy, use materialized views for expensive aggregations
+
+**JSON column**: Flexible schema-less data (user preferences), data you won't query often. NOT for filtering/sorting.
+
+**Add index**: Column in WHERE on large table, foreign keys (always), after identifying slow queries. NOT on every column.

package/dist/assets/knowledge/guides/saas-template.md

@@ -0,0 +1,85 @@
+---
+name: SaaS Template
+description: Complete SaaS feature spec: auth, billing, multi-tenancy, compliance
+---
+
+# SaaS Platform Specification
+
+Scalable, secure SaaS for modern web apps. USD wallet billing, tiered memberships, serverless SPA architecture. Prioritize security, usability, extensibility.
+
+## Core Requirements
+- **Architecture**: Responsive SPA, serverless backend (Vercel/Cloudflare)
+- **Currency**: USD only
+- **Billing**: Wallet-based (Stripe), membership discounts before deductions
+- **Memberships**: Tiers (Small/Medium/Large) with monthly auto-top-ups, discounts, entitlements. Yearly = 10x monthly. Admin-configurable.
+- **Compliance**: GDPR/CCPA compliant, verifiable acceptance criteria
+
+## Core Features
+
+### Auth & User Management
+- **Auth**: Email/password, SSO (Google/OAuth), Passkey-first 2FA (SimpleWebAuthn), reCAPTCHA v3, rate limiting (5 attempts/5min)
+- **Sessions**: Rotating JWTs, Redis denylist, log all logins (IP, UA, timestamp)
+- **Security**: 2FA setup/recovery codes, email alerts for new logins/devices
+- **Profiles**: Display name, bio, avatar (128x128px, S3)
+- **Usernames**: Unique, lowercase, reserved blocks, 30-day change cooldown + audit
+- **Devices**: Active sessions list (IP/UA/location), one-click logout
+
+- **Invites & Referrals**: Shareable codes/links/QR with limits/expiration. Track referrals, reward wallet credits (configurable).
+- **Notifications**: User-configurable email/push, in-app hub with bell, unread counts, mark-read
+- **Activity Feed**: Log actions (recharges, spends, logins, invites, referrals) with timestamps/filters
+
+### Billing & Wallet
+- **Wallet**: USD balances, Stripe top-ups (min $10), auto-deduct with tier discounts
+- **Memberships**: Tiers ($10/mo, $50/mo, $100/mo) with auto-top-up, % discounts, perks. Yearly = 10x. Admin CRUD.
+- **Invoicing**: PDF receipts, admin dashboard for search/export (CSV/PDF)
+
+### Admin Dashboard
+Role-based (admin/moderator). Charts/tables for insights.
+- **Overview**: Metrics (date, plan, region, device), visualize revenue/users/growth
+- **User Management**: Search, role assignment, bans, username approval
+- **Billing**: Manage subscriptions/refunds, invoices, bulk adjustments
+- **Wallet**: Reconcile, flag anomalies (>$1000 top-up)
+- **Marketing**: Newsletter lists/broadcasts, track open/unsubscribe
+- **Invites/Referrals**: Generate codes/programs, monitor stats/rewards
+- **Memberships**: CRUD plans (price, top-up, discounts, entitlements)
+- **Notifications**: Global broadcasts (email/push)
+- **Support**: Ticket queue with reply/status
+- **Audits**: Searchable logs (user/action/timestamp), export
+
+### Content & Support
+- **Knowledge Base**: Docs/FAQ (MDX)
+- **CMS**: Blog for announcements
+- **Status**: Real-time uptime/incidents, historical data
+- **Help**: Contact form → tickets, admin responses
+
+### Public Pages
+- **Landing**: Home, Features, Pricing (SEO-optimized)
+- **Profiles**: /u/<username> (bio, stats, Open Graph)
+- **Referrals**: /r/<code> redirects with tracking
+- **Legal**: Terms, Privacy, Cookies. Consent banner with granular controls.
+
+### Advanced Features
+- **Error Handling**: Custom 404/500, search/suggestions, auto-redirect
+- **Analytics**: Consent-gated GA, newsletter engagement (no PII)
+- **Consent**: Log agreements (user_id, type, version, timestamp, IP/UA). Version policies, granular toggles, history export/revocation.
+
+## Legal & Compliance
+GDPR, CCPA, PECR. Data minimization, user rights.
+- **Cookies**: Banner with opt-in/out, categorize (necessary, analytics, marketing), persist in DB
+- **Data Rights**: Export/delete endpoints, process within 30 days (P1)
+- **Documentation**: MDX pages (Privacy, Terms, Cookies), version updates with notifications
+- **Logging**: Immutable consent/action records, audit for compliance
+
+## Deployment
+Serverless for scalability, CI/CD for reliability.
+- **Local**: Docker Compose (web/DB/Redis). Run: `bun install && bun db:migrate && bun dev`
+- **Monitoring**: Sentry for errors, SLO alerts (99.9%), retry failed webhooks (3x, exponential)
+- **Status**: Auto-update from monitoring events
+
+## Testing
+100% coverage, enforce via CI. TDD for new features.
+- **Unit**: Vitest, mock externalities
+- **E2E**: Playwright (register → login → 2FA → top-up → consume → invoice → unsubscribe → invite → referral → ticket)
+- **Accessibility**: axe-core, Lighthouse A11y >95
+- **Performance**: Responsive, lazy loading, Iconify icons
+- **Quality**: Biome linting/formatting, pre-commit hooks