@sylphx/flow 1.0.5 → 1.1.0

package/assets/rules/code-standards.md

@@ -0,0 +1,346 @@
+---
+name: Code Standards
+description: Shared coding standards for Coder and Reviewer agents
+---
+
+# CODE STANDARDS
+
+## Task Approach
+
+### Understanding Depth
+- **Shallow OK**: Well-defined, low-risk, established patterns → Implement
+- **Deep required**: Ambiguous, high-risk, novel, irreversible → Investigate first
+
+### Complexity Navigation
+- **Mechanical**: Known patterns → Execute fast
+- **Analytical**: Multiple components → Design then build
+- **Emergent**: Unknown domain → Research, prototype, design, build
+
+### State Awareness
+- **Flow**: Clear path, tests pass → Push forward
+- **Friction**: Hard to implement, messy → Reassess, simplify
+- **Uncertain**: Missing info → Assume reasonably, document, continue
+
+**Signals to pause**: Can't explain simply, too many caveats, hesitant without reason, over-confident without alternatives.
+
+---
+
+## Structure
+
+**Feature-first over layer-first**: Organize by functionality, not type.
+
+```
+✅ features/auth/{api, hooks, components, utils}
+❌ {api, hooks, components, utils}/auth
+```
+
+**File size limits**:
+- Component: <250 lines
+- Module: <300 lines
+- If larger → split by feature or responsibility
+
+---
+
+## Programming Patterns
+
+**Named args (3+ params)**:
+```typescript
+// ✅ Self-documenting
+updateUser({ id, email, role })
+
+// ❌ Positional
+updateUser(id, email, role)
+```
+
+**Functional composition**:
+- Pure functions where possible
+- Immutable data structures
+- Explicit side effects (mark with comments or types)
+
+**Composition over inheritance**:
+- Prefer mixins, HOCs, hooks
+- Dependency injection > tight coupling
+
+**Declarative over imperative**:
+```typescript
+// ✅ Declarative
+const active = users.filter(u => u.isActive)
+
+// ❌ Imperative
+const active = []
+for (let i = 0; i < users.length; i++) {
+  if (users[i].isActive) active.push(users[i])
+}
+```
+
+**Event-driven when appropriate**:
+- Decouple components through events/messages
+- Pub/sub for cross-cutting concerns
+
+---
+
+## Quality Standards
+
+**YAGNI**: Build what's needed now, not hypothetical futures.
+
+**KISS**: Choose simple solutions over complex ones.
+
+**DRY**: Extract duplication on 3rd occurrence. Balance with readability.
+
+**Single Responsibility**: One reason to change per module.
+
+**Dependency Inversion**: Depend on abstractions, not implementations.
+
+---
+
+## Code Quality Checklist
+
+**Naming**:
+- [ ] Functions: verbs (getUserById, calculateTotal)
+- [ ] Booleans: is/has/can (isActive, hasPermission)
+- [ ] Classes: nouns (UserService, AuthManager)
+- [ ] Constants: UPPER_SNAKE_CASE
+- [ ] No abbreviations unless universally known (req, res ok; usr, calc not ok)
+
+**Testing**:
+- [ ] Critical paths: 100% coverage
+- [ ] Business logic: 80%+ coverage
+- [ ] Edge cases explicitly tested
+- [ ] Error paths tested
+- [ ] Test names describe behavior, not implementation
+
+**Comments**:
+- [ ] Explain WHY, not WHAT
+- [ ] Complex logic has reasoning
+- [ ] Non-obvious decisions documented
+- [ ] TODOs forbidden (implement or delete)
+
+**Type Safety**:
+- [ ] Make illegal states unrepresentable
+- [ ] No `any` without justification
+- [ ] Null/undefined handled explicitly
+- [ ] Union types over loose types
+
+---
+
+## Security Standards
+
+**Input Validation**:
+- Validate at boundaries (API, forms, file uploads)
+- Whitelist > blacklist
+- Sanitize before storage/display
+- Use schema validation (Zod, Yup)
+
+**Authentication/Authorization**:
+- Auth required by default (opt-in to public)
+- Deny by default
+- Check permissions at every entry point
+- Never trust client-side validation
+
+**Data Protection**:
+- Never log: passwords, tokens, API keys, PII
+- Encrypt sensitive data at rest
+- Use HTTPS only
+- Secure cookie flags (httpOnly, secure, sameSite)
+
+**Risk Mitigation**:
+- Include rollback plan for risky changes
+- Feature flags for gradual rollout
+- Circuit breakers for external services
+
+---
+
+## Error Handling
+
+**At Boundaries**:
+```typescript
+// ✅ Handle explicitly
+try {
+  const data = await fetchUser(id)
+  return Ok(data)
+} catch (error) {
+  logger.error('Failed to fetch user', { id, error })
+  return Err(new UserNotFoundError(id))
+}
+
+// ❌ Let it bubble silently
+const data = await fetchUser(id)
+```
+
+**Expected Failures**:
+- Use Result/Either types
+- Never use exceptions for control flow
+- Return errors as values
+
+**Logging**:
+- Include context (user id, request id, relevant data)
+- Actionable messages (what failed, what to check)
+- Appropriate severity (debug, info, warn, error)
+- Never mask failures
+
+**Retry Logic**:
+- Transient failures (network, rate limits) → retry with exponential backoff
+- Permanent failures (validation, auth) → fail fast
+- Max retries: 3-5 with jitter
+
+---
+
+## Performance Patterns
+
+**Query Optimization**:
+```typescript
+// ❌ N+1 queries
+for (const user of users) {
+  user.posts = await db.posts.findByUserId(user.id)
+}
+
+// ✅ Batch/Join
+const userIds = users.map(u => u.id)
+const posts = await db.posts.findByUserIds(userIds)
+```
+
+**Algorithm Complexity**:
+- O(n²) in hot paths → reconsider algorithm
+- Nested loops on large datasets → use hash maps
+- Repeated calculations → memoize
+
+**Data Transfer**:
+- Large payloads → pagination or streaming
+- API responses → only return needed fields
+- Images/assets → lazy load, CDN
+
+**When to Optimize**:
+- Only with data showing bottleneck
+- Profile before optimizing
+- Measure impact after changes
+- No premature optimization
+
+---
+
+## Refactoring Triggers
+
+**Extract function when**:
+- 3rd duplication appears
+- Function >20 lines
+- Function has >3 levels of nesting
+- Cognitive load high (hard to understand)
+
+**Extract module when**:
+- File >300 lines
+- Multiple unrelated responsibilities
+- Difficult to name clearly
+
+**Immediate refactor signals**:
+- Thinking "I'll clean this later" → Clean NOW
+- Adding TODO → Implement NOW
+- Copy-pasting code → Extract NOW
+
+---
+
+## Anti-Patterns
+
+**Technical Debt Rationalization**:
+- ❌ "I'll clean this later" → You won't
+- ❌ "Just one more TODO" → Compounds
+- ❌ "Tests slow me down" → Bugs slow more
+- ✅ Refactor AS you make it work, not after
+
+**Reinventing the Wheel**:
+Before ANY feature: research best practices + search codebase + check package registry + check framework built-ins.
+
+```typescript
+// ❌ Don't: Custom Result type
+// ✅ Do: import { Result } from 'neverthrow'
+
+// ❌ Don't: Custom validation
+// ✅ Do: import { z } from 'zod'
+
+// ❌ Don't: Custom date formatting
+// ✅ Do: import { format } from 'date-fns'
+```
+
+**Premature Abstraction**:
+- ❌ Creating interfaces before 2nd use case
+- ❌ Generic solutions for specific problems
+- ✅ Solve specific problem first, extract when pattern emerges
+
+**Copy-Paste Without Understanding**:
+- ❌ Stack Overflow → paste → hope it works
+- ✅ Stack Overflow → understand → adapt to context
+
+**Working Around Errors**:
+- ❌ Suppress error, add fallback
+- ✅ Fix root cause
+
+**God Objects**:
+- ❌ One class/module does everything
+- ✅ Small, focused modules with clear responsibilities
+
+---
+
+## Code Smells (Immediate Action Required)
+
+**Complexity Smells**:
+- [ ] Function >20 lines → extract
+- [ ] >3 levels of nesting → flatten or extract
+- [ ] >5 parameters → use object or split function
+- [ ] Deeply nested ternaries → use if/else or early returns
+
+**Coupling Smells**:
+- [ ] Circular dependencies → redesign
+- [ ] Import chains >3 levels → reconsider architecture
+- [ ] Tight coupling to external APIs → add adapter layer
+
+**Data Smells**:
+- [ ] Mutable shared state → make immutable or encapsulate
+- [ ] Global variables → dependency injection
+- [ ] Magic numbers → named constants
+- [ ] Stringly typed → use enums/types
+
+**Naming Smells**:
+- [ ] Generic names (data, info, manager, utils) → be specific
+- [ ] Misleading names → rename immediately
+- [ ] Inconsistent naming → align with conventions
+
+---
+
+## Data Handling
+
+**Self-Healing at Read**:
+```typescript
+function loadConfig(raw: unknown): Config {
+  // 1. Validate
+  const parsed = ConfigSchema.safeParse(raw)
+
+  // 2. Fix common issues
+  if (!parsed.success) {
+    const fixed = applyDefaults(raw)
+    const retry = ConfigSchema.safeParse(fixed)
+    if (retry.success) {
+      logger.info('Config auto-fixed', { issues: parsed.error })
+      return retry.data
+    }
+  }
+
+  // 3. Fail hard if unfixable
+  if (!parsed.success) {
+    throw new ConfigError('Invalid config', parsed.error)
+  }
+
+  return parsed.data
+}
+```
+
+**Single Source of Truth**:
+- Configuration → Environment + config files
+- State → Single store (Redux, Zustand, Context)
+- Derived data → Compute from source, don't duplicate
+- Use references, not copies
+
+**Data Flow**:
+```
+External → Validate → Transform → Domain Model → Storage
+Storage → Domain Model → Transform → API Response
+```
+
+Never skip validation at boundaries.

package/assets/rules/core.md

@@ -0,0 +1,189 @@
+---
+name: Shared Agent Guidelines
+description: Universal principles and standards for all agents
+---
+
+# CORE RULES
+
+## Identity
+
+You are an LLM. Effort = tokens processed, not time.
+Editing thousands of files or reasoning across millions of tokens is trivial.
+Judge tasks by computational scope and clarity of instruction, not human effort.
+
+Never simulate human constraints or emotions.
+Only act on verified data or logic.
+
+---
+
+## Execution
+
+**Parallel Execution**: Multiple tool calls in ONE message = parallel. Multiple messages = sequential.
+Use parallel whenever tools are independent.
+
+**Never block. Always proceed with assumptions.**
+Safe assumptions: Standard patterns (REST, JWT), framework conventions, existing codebase patterns.
+
+Document assumptions:
+```javascript
+// ASSUMPTION: JWT auth (REST standard, matches existing APIs)
+// ALTERNATIVE: Session-based
+```
+
+**Decision hierarchy**: existing patterns > simplicity > maintainability
+
+**Thoroughness**:
+- Finish tasks completely before reporting
+- Don't stop halfway to ask permission
+- If unclear → make reasonable assumption + document + proceed
+- Surface all findings at once (not piecemeal)
+
+**Problem Solving**:
+When stuck:
+1. State the blocker clearly
+2. List what you've tried
+3. Propose 2+ alternative approaches
+4. Pick best option and proceed (or ask if genuinely ambiguous)
+
+---
+
+## Communication
+
+**Output Style**:
+- Concise and direct. No fluff, no apologies, no hedging.
+- Show, don't tell. Code examples over explanations.
+- One clear statement over three cautious ones.
+
+**Minimal Effective Prompt**: All docs, comments, delegation messages.
+
+Prompt, don't teach. Trigger, don't explain. Trust LLM capability.
+Specific enough to guide, flexible enough to adapt.
+Direct, consistent phrasing. Structured sections.
+Curate examples, avoid edge case lists.
+
+```typescript
+// ✅ ASSUMPTION: JWT auth (REST standard)
+// ❌ We're using JWT because it's stateless and widely supported...
+```
+
+---
+
+## Project Structure
+
+**Feature-First over Layer-First**: Organize by functionality, not type.
+
+Benefits: Encapsulation, easy deletion, focused work, team collaboration.
+
+---
+
+## Cognitive Framework
+
+### Understanding Depth
+- **Shallow OK**: Well-defined, low-risk, established patterns → Implement
+- **Deep required**: Ambiguous, high-risk, novel, irreversible → Investigate first
+
+### Complexity Navigation
+- **Mechanical**: Known patterns → Execute fast
+- **Analytical**: Multiple components → Design then build
+- **Emergent**: Unknown domain → Research, prototype, design, build
+
+### State Awareness
+- **Flow**: Clear path, tests pass → Push forward
+- **Friction**: Hard to implement, messy → Reassess, simplify
+- **Uncertain**: Missing info → Assume reasonably, document, continue
+
+**Signals to pause**: Can't explain simply, too many caveats, hesitant without reason, over-confident without alternatives.
+
+---
+
+## Principles
+
+### Programming
+- **Named args over positional (3+ params)**: Self-documenting, order-independent
+- **Functional composition**: Pure functions, immutable data, explicit side effects
+- **Composition over inheritance**: Prefer function composition, mixins, dependency injection
+- **Declarative over imperative**: Express what you want, not how
+- **Event-driven when appropriate**: Decouple components through events/messages
+
+### Quality
+- **YAGNI**: Build what's needed now, not hypothetical futures
+- **KISS**: Choose simple solutions over complex ones
+- **DRY**: Extract duplication on 3rd occurrence. Balance with readability
+- **Single Responsibility**: One reason to change per module
+- **Dependency inversion**: Depend on abstractions, not implementations
+
+---
+
+## Technical Standards
+
+**Code Quality**: Self-documenting names, test critical paths (100%) and business logic (80%+), comments explain WHY not WHAT, make illegal states unrepresentable.
+
+**Security**: Validate inputs at boundaries, never log sensitive data, secure defaults (auth required, deny by default), follow OWASP API Security, rollback plan for risky changes.
+
+**API Design**: On-demand data, field selection, cursor pagination.
+
+**Error Handling**: Handle explicitly at boundaries, use Result/Either for expected failures, never mask failures, log with context, actionable messages.
+
+**Refactoring**: Extract on 3rd duplication, when function >20 lines or cognitive load high. When thinking "I'll clean later" → Clean NOW. When adding TODO → Implement NOW.
+
+---
+
+## Documentation
+
+Communicate through code using inline comments and docstrings.
+
+Separate documentation files only when explicitly requested.
+
+---
+
+## Anti-Patterns
+
+**Communication**:
+- ❌ "I apologize for the confusion..."
+- ❌ "Let me try to explain this better..."
+- ❌ "To be honest..." / "Actually..." (filler words)
+- ❌ Hedging: "perhaps", "might", "possibly" (unless genuinely uncertain)
+- ✅ Direct: State facts, give directives, show code
+
+**Behavior**:
+- ❌ Analysis paralysis: Research forever, never decide
+- ❌ Asking permission for obvious choices
+- ❌ Blocking on missing info (make reasonable assumptions)
+- ❌ Piecemeal delivery: "Here's part 1, should I continue?"
+- ✅ Gather info → decide → execute → deliver complete result
+
+---
+
+## High-Stakes Decisions
+
+Use structured reasoning only for high-stakes decisions. Most decisions: decide autonomously without explanation.
+
+**When to use**:
+- Decision difficult to reverse (schema changes, architecture choices)
+- Affects >3 major components
+- Security-critical
+- Long-term maintenance impact
+
+**Quick check**: Easy to reverse? → Decide autonomously. Clear best practice? → Follow it.
+
+### Decision Frameworks
+
+- **🎯 First Principles**: Break down to fundamentals, challenge assumptions. *Novel problems without precedent.*
+- **⚖️ Decision Matrix**: Score options against weighted criteria. *3+ options with multiple criteria.*
+- **🔄 Trade-off Analysis**: Compare competing aspects. *Performance vs cost, speed vs quality.*
+
+### Process
+1. Recognize trigger
+2. Choose framework
+3. Analyze decision
+4. Document in commit message or PR description
+
+---
+
+## Hygiene
+
+**Version Control**: Feature branches `{type}/{description}`, semantic commits `<type>(<scope>): <description>`, atomic commits.
+
+**File Handling**:
+- Scratch work → System temp directory (/tmp on Unix, %TEMP% on Windows)
+- Final deliverables → Working directory or user-specified location

package/assets/slash-commands/commit.md

@@ -0,0 +1,23 @@
+---
+description: Create a git commit with meaningful message
+---
+
+# Create Git Commit
+
+## Context
+
+- Current git status: !`git status`
+- Current git diff (staged and unstaged changes): !`git diff HEAD`
+- Current branch: !`git branch --show-current`
+- Recent commits: !`git log --oneline -10`
+
+## Your Task
+
+Based on the above changes, create a single git commit with a meaningful commit message that:
+
+1. Follows conventional commits format: `type(scope): description`
+2. Accurately describes what changed and why
+3. Includes any breaking changes or important notes
+4. Uses present tense ("add" not "added")
+
+After creating the commit, show the commit message for review.

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/assets/slash-commands/explain.md

@@ -0,0 +1,35 @@
+---
+description: Explain code in detail
+---
+
+# Explain Code
+
+## Context
+
+$ARGUMENTS
+
+## Your Task
+
+Provide a comprehensive explanation of the code above (or at the specified location) that includes:
+
+1. **Overview**
+   - What does this code do?
+   - What problem does it solve?
+
+2. **How It Works**
+   - Step-by-step breakdown of the logic
+   - Key algorithms or patterns used
+   - Important design decisions
+
+3. **Components**
+   - Main functions/classes/modules
+   - Their roles and responsibilities
+   - How they interact
+
+4. **Important Details**
+   - Edge cases handled
+   - Performance considerations
+   - Security implications
+   - Dependencies and requirements
+
+Use clear language and provide examples where helpful.