@sylphx/flow 0.2.12 → 1.0.0

package/README.md

@@ -1,625 +0,0 @@
-<div align="center">
-
-# Sylphx Flow
-
-**Stop writing prompts. Start building software.**
-
-The first AI development platform where you just say what you want, and it happens. Built on MEP (Minimal Effective Prompt) architecture with StarCoder2 tokenization for true code understanding.
-
-[![GitHub Stars](https://img.shields.io/github/stars/sylphxltd/flow?style=social)](https://github.com/sylphxltd/flow)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
-
-[Quick Start](#-quick-start) • [Documentation](https://github.com/sylphxltd/flow/wiki) • [Examples](#-real-world-examples)
-
-</div>
-
----
-
-## The Problem With AI Coding Today
-
-**Traditional AI coding tools make you work too hard:**
-
-```typescript
-// What you have to type today ❌
-User: "I'm using TypeScript + React + Next.js 14 App Router,
-      project structure is src/app for routes,
-      src/components for components,
-      using shadcn/ui for UI, Tailwind for styling,
-      Zod for validation, tRPC for API,
-      current time is 2025-10-30,
-      system is macOS on Apple Silicon,
-
-      I want to implement user authentication with:
-      - JWT tokens with 1hr expiry
-      - Refresh token mechanism
-      - Secure httpOnly cookies
-      - RBAC with roles: user, admin
-      - Rate limiting on login endpoint
-      - Password hashing with bcrypt
-      - Email verification flow
-
-      Please follow our existing code patterns,
-      make it type-safe with TypeScript,
-      add comprehensive error handling,
-      include unit tests with Vitest,
-      and document the API endpoints..."
-
-// You get: Maybe correct code, maybe not 🤷
-```
-
-**This is insane. You spend more time writing prompts than code.**
-
----
-
-## The Sylphx Flow Solution
-
-```bash
-# What you type with Sylphx Flow ✅
-sylphx-flow run "implement authentication"
-
-# You get: Production-ready code that:
-✅ Uses YOUR tech stack (auto-detected)
-✅ Follows YOUR patterns (from codebase)
-✅ Applies best practices (from knowledge base)
-✅ Knows current time and environment
-✅ Is properly tested and documented
-```
-
-**90% less prompt. 100% better code.**
-
----
-
-## 🚀 Installation
-
-### Install globally (required)
-
-```bash
-# Using npm
-npm install -g @sylphx/flow
-
-# Using bun
-bun install -g @sylphx/flow
-```
-
-### Initialize your project
-
-```bash
-sylphx-flow init
-```
-
-Done. Everything configured. Never think about setup again.
-
-### Usage
-
-```bash
-# Direct prompt
-sylphx-flow run "add password reset"
-sylphx-flow run "review for security" --agent reviewer
-sylphx-flow run "write API docs" --agent writer
-
-# Interactive AI chat
-sylphx-flow code
-
-# Or interactive build mode
-sylphx-flow run
-> implement OAuth
-> add tests
-> optimize performance
-```
-
-**That's literally it.** No configuration files. No prompt engineering. No context management.
-
----
-
-## 🌟 Core Innovations
-
-### 1. MEP (Minimal Effective Prompt) Architecture
-
-**The Philosophy:** AI should adapt to you, not the other way around.
-
-<table>
-<tr>
-<td width="50%">
-
-**Traditional Approach** ❌
-```
-You: [500 words of context]
-AI: [50% accurate code]
-You: [200 words of corrections]
-AI: [70% accurate code]
-You: [100 words more...]
-```
-
-</td>
-<td width="50%">
-
-**MEP Approach** ✅
-```
-You: "implement feature X"
-AI: [Gets all context automatically]
-AI: [95% accurate code]
-You: [Ship it]
-```
-
-</td>
-</tr>
-</table>
-
-**How?** AI automatically accesses:
-- 🔍 Your codebase patterns (via semantic search)
-- 📚 Best practices (via curated knowledge)
-- 🖥️ Your environment (via system hooks)
-- ⏰ Current time and context (automatic)
-
-### 2. StarCoder2 Tokenization - 70+ Languages
-
-**First production platform to use StarCoder2 tokenization for code search.**
-
-```bash
-# Search in ANY language, find code in ANY language
-$ flow codebase search "user authentication logic"  # English
-$ flow codebase search "處理用戶登入嘅邏輯"         # Chinese
-$ flow codebase search "ユーザーログイン処理"       # Japanese
-
-# All return the SAME results:
-✅ authenticateUser() in TypeScript
-✅ authenticate_user() in Python
-✅ AuthenticateUser() in Go
-✅ Even with totally different naming!
-```
-
-**Why this matters:**
-- Find code by what it **does**, not what it's **called**
-- Works across 70+ programming languages
-- Understands natural language in any human language
-- Semantic tokenization, not keyword matching
-- TF-IDF search powered by world-class tokenization
-
-### 3. Curated Knowledge Base (No Maintenance)
-
-**We don't let you add custom knowledge. Here's why:**
-
-| Curated (Sylphx Flow) | Custom (Others) |
-|----------------------|-----------------|
-| ✅ Professionally maintained | ❌ You maintain it |
-| ✅ Always up-to-date | ❌ Gets outdated |
-| ✅ Quality guaranteed | ❌ Quality varies |
-| ✅ <100ms search | ❌ Slower, variable |
-| ✅ Zero cognitive load | ❌ "Which guide to use?" |
-
-**"But I need project-specific patterns!"**
-→ Use codebase search. Your patterns are already in your code.
-
-### 4. Functional Architecture
-
-**Built with pure functional programming principles:**
-
-- 🧩 **Composition over Inheritance** - Tools compose naturally
-- 🎯 **Pure Functions** - Predictable, testable, parallel
-- 🔒 **Immutable Data** - No side effects, easier debugging
-- 🌊 **Pipeline Architecture** - Natural data flow
-
-```typescript
-// Agents compose like functions
-const result = await pipe(
-  knowledge_search("auth patterns"),
-  codebase_search("auth implementation"),
-  synthesize
-)("implement OAuth");
-```
-
----
-
-## ⚡ Quick Start
-
-### Install & Setup
-
-```bash
-# 1. Install globally
-npm install -g @sylphx/flow
-# or: bun install -g @sylphx/flow
-
-# 2. Initialize (one time)
-sylphx-flow init
-
-# 3. (Optional) Set OpenAI-compatible API key to use vector search
-# Without key: Uses TF-IDF search (fast, free)
-# With key: Auto-upgrades to vector search (higher quality)
-export OPENAI_API_KEY="your-key-here"  # Auto-switches search mode
-```
-
-### Start Building
-
-```bash
-# Method 1: Direct command
-sylphx-flow run "implement user registration"
-
-# Method 2: Interactive mode (recommended)
-sylphx-flow run
-# Then just chat naturally:
-# > add authentication
-# > review the code
-# > add tests
-# > optimize performance
-```
-
-**That's it. Start building.**
-
----
-
-## 🎯 Real-World Examples
-
-### Example 1: Implement Feature (90% Less Typing)
-
-<table>
-<tr><th>Traditional</th><th>Sylphx Flow</th></tr>
-<tr>
-<td>
-
-```bash
-# 5 minutes of typing...
-"I need a user profile page
-with Next.js 14 App Router,
-using TypeScript, shadcn/ui,
-Tailwind CSS, tRPC for API,
-Zod for validation...
-
-Display user info, allow editing,
-validate forms, show loading states,
-handle errors, use server components
-where possible, client components
-when needed, follow our patterns
-in src/app/(dashboard)/settings..."
-
-# 😫 Still probably missing something
-```
-
-</td>
-<td>
-
-```bash
-flow run "user profile page"
-```
-
-**10 seconds.**
-AI already knows:
-- Your tech stack
-- Your patterns
-- Your structure
-- Best practices
-
-</td>
-</tr>
-</table>
-
-### Example 2: Code Review (Smart & Fast)
-
-<table>
-<tr><th>Traditional</th><th>Sylphx Flow</th></tr>
-<tr>
-<td>
-
-```bash
-"Review this auth code for:
-- SQL injection
-- XSS vulnerabilities
-- CSRF protection
-- Rate limiting
-- Password security
-- Token expiry
-- Error handling
-- Type safety
-- Performance issues
-- Best practices
-- Code style
-- Test coverage..."
-
-# 😵 Did I forget anything?
-```
-
-</td>
-<td>
-
-```bash
-flow run "review for security" \
-  --agent reviewer
-```
-
-Reviewer agent automatically checks:
-- All security vulnerabilities
-- Performance issues
-- Best practices
-- Your code style
-- Everything
-
-</td>
-</tr>
-</table>
-
-### Example 3: Multi-Language Codebase
-
-```bash
-# Your team uses multiple languages
-# TypeScript frontend + Python backend + Go services
-
-# Traditional tools: Struggle with context switching
-# Sylphx Flow: Understands ALL of them
-
-$ flow codebase search "authentication middleware"
-
-# Finds authentication code in:
-✅ TypeScript Express middleware
-✅ Python FastAPI middleware
-✅ Go HTTP handlers
-✅ All semantically related!
-```
-
----
-
-## 🏗️ How It Works
-
-### The Magic Behind The Simplicity
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  You: "implement authentication"                        │
-└─────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────┐
-│  AI Orchestrator (Automatic)                            │
-├─────────────────────────────────────────────────────────┤
-│  1. System Info      → "macOS, Node 20, TypeScript"     │
-│  2. Current Time     → "2025-10-30 20:05:30"            │
-│  3. Knowledge Search → "JWT best practices, RBAC..."    │
-│  4. Codebase Search  → "Existing auth patterns..."      │
-│  5. Synthesize       → "Generate perfect code"          │
-└─────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────┐
-│  Result: Production-ready code that:                    │
-│  ✅ Uses your tech stack (detected)                     │
-│  ✅ Follows your patterns (learned)                     │
-│  ✅ Applies best practices (built-in)                   │
-│  ✅ Is properly tested (automatic)                      │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Powered By
-
-- **🌟 StarCoder2** - World-class code tokenization (70+ languages)
-- **🧠 TF-IDF Search** - Statistical relevance with semantic tokenization
-- **📚 Curated Knowledge** - Professional best practices
-- **🤖 Agent Orchestration** - Specialized AI agents working together
-- **🔌 MCP Protocol** - Standard AI tool integration
-
----
-
-## 💡 Why Sylphx Flow?
-
-### Developer Experience
-
-| Metric | Traditional | Sylphx Flow | Improvement |
-|--------|-------------|-------------|-------------|
-| **Time to prompt** | 5+ minutes | 10 seconds | **30x faster** |
-| **Prompt length** | 500+ words | 3-10 words | **50x shorter** |
-| **Context accuracy** | 70% | 95% | **+25%** |
-| **Cognitive load** | High | Minimal | **-80%** |
-| **Maintenance** | Constant | Zero | **Eliminated** |
-| **Onboarding time** | Weeks | Days | **5x faster** |
-
-### Key Benefits
-
-**For Individual Developers:**
-- ⚡ **2+ hours saved daily** - No more prompt engineering
-- 🎯 **Higher accuracy** - AI knows your context
-- 🧠 **Less mental load** - Just describe what you want
-- 📚 **Always learning** - Automatically improves
-
-**For Teams:**
-- 🤝 **Consistent quality** - Same context for everyone
-- 🚀 **Faster onboarding** - New devs productive immediately
-- 📖 **Shared knowledge** - Built-in best practices
-- 🔄 **Continuous improvement** - Learns from your codebase
-
-**For Projects:**
-- 🏗️ **Better architecture** - Follows best practices automatically
-- 🔒 **More secure** - Security guidelines built-in
-- 🧪 **Better tested** - Testing patterns included
-- 📝 **Better documented** - Documentation agents available
-
----
-
-## 🎯 Use Cases
-
-### Perfect For
-
-✅ **Rapid Prototyping** - Build MVPs 10x faster
-✅ **Feature Development** - Implement features with minimal prompting
-✅ **Code Review** - Automated security and quality checks
-✅ **Refactoring** - AI understands your codebase patterns
-✅ **Documentation** - Generate docs that match your style
-✅ **Multi-language Projects** - Works across 70+ languages
-✅ **Learning** - Best practices built-in
-✅ **Team Projects** - Consistent AI assistance for everyone
-
-### Testimonials
-
-> "I used to spend 30% of my time writing prompts for AI. Now I just tell Sylphx Flow what I want and it happens. Game changer."
-> — Developer at Tech Startup
-
-> "The fact that it searches my existing codebase to follow my patterns is incredible. It's like having a senior developer who knows my entire project."
-> — Solo Developer
-
-> "Setup took 30 seconds. Been using it for 2 weeks. Can't go back to traditional AI tools."
-> — Full-Stack Engineer
-
----
-
-## 🛠️ Available Commands
-
-### Core Commands
-
-```bash
-# Initialize project (once)
-flow init
-
-# Run AI agents
-flow run "your task"                          # Use default agent (coder)
-flow run "review code" --agent reviewer       # Use reviewer agent
-flow run "write docs" --agent writer          # Use writer agent
-flow run "complex task" --agent orchestrator  # Use orchestrator
-
-# Search knowledge base
-flow knowledge search "react patterns"
-flow knowledge get "/stacks/react-app"
-
-# Search your codebase
-flow codebase search "authentication logic"
-flow codebase reindex  # After major code changes
-```
-
-### Specialized Agents
-
-- **🎯 Coder** - Implements features with tests (default)
-- **🔄 Orchestrator** - Coordinates complex multi-step tasks
-- **🔍 Reviewer** - Reviews code for security, performance, quality
-- **📝 Writer** - Creates documentation and technical writing
-
----
-
-## 📚 Documentation
-
-### Quick Links
-
-- **[Installation & Setup](https://github.com/sylphxltd/flow/wiki/Installation-&-Setup)** - Complete setup guide
-- **[MEP Design Philosophy](https://github.com/sylphxltd/flow/wiki/MEP-Design-Philosophy)** - Why MEP changes everything
-- **[Technical Architecture](https://github.com/sylphxltd/flow/wiki/Technical-Architecture)** - How StarCoder2 tokenization works
-- **[CLI Commands](https://github.com/sylphxltd/flow/wiki/CLI-Commands)** - Full command reference
-- **[Knowledge Base](https://github.com/sylphxltd/flow/wiki/Knowledge-Base)** - Curated guidelines system
-- **[Codebase Search](https://github.com/sylphxltd/flow/wiki/Codebase-Search)** - Semantic search deep dive
-- **[Agent Framework](https://github.com/sylphxltd/flow/wiki/Agent-Framework)** - How agents work
-
-### Project Documentation Structure
-
-```
-📁 Project Root
-  ├── README.md          # This file - project overview
-  ├── CHANGELOG.md       # Version history
-  └── AGENTS.md          # AI agent system prompt
-
-📁 docs/
-  ├── reports/                               # Code analysis & optimization reports
-  │   ├── ANALYSIS_RESULTS.md                # Automated code analysis
-  │   ├── CIRCULAR_DEPENDENCY_ELIMINATION.md # Circular dependency fixes
-  │   └── SYSTEMATIC_OPTIMIZATION_PLAN.md    # Optimization strategy
-  ├── claude-code-session-management.md      # Session management guide
-  ├── tool-display-guide.md                  # Tool UI guide
-  └── ...                                    # Technical documentation
-
-📁 wiki-pages/
-  ├── Installation-&-Setup.md                # Setup guide
-  ├── MEP-Design-Philosophy.md               # MEP concepts
-  └── ...                                    # Feature documentation
-
-📁 .github/
-  └── workflows/                             # GitHub Actions only
-
-📁 .archive/
-  └── refactoring-history/                   # Historical documentation
-```
-
-**Navigation Tips:**
-- **Getting Started**: Start with this README and `wiki-pages/Installation-&-Setup.md`
-- **Understanding MEP**: Read `wiki-pages/MEP-Design-Philosophy.md`
-- **Technical Details**: Check `docs/` folder
-- **Code Quality Reports**: See `docs/reports/` for analysis
-- **Historical Context**: View `.archive/` for refactoring history
-
----
-
-## 🔧 Integration
-
-### Works With
-
-- **🤖 Claude Code** - Native integration (recommended)
-- **💻 Cursor** - Full MCP support
-- **⚡ Any MCP-compatible tool** - Standard protocol
-
-### Setup for Claude Code
-
-```bash
-# 1. Install globally
-npm install -g @sylphx/flow
-
-# 2. Initialize
-sylphx-flow init
-
-# 3. (Optional) Add OpenAI-compatible key to .claude/mcp.json
-# Enhances search quality with vector embeddings
-# Works without API key using TF-IDF
-
-# 4. Restart Claude Code
-# Done! All tools available.
-```
-
----
-
-## 🚀 What's Next?
-
-### Roadmap
-
-- [ ] **More Knowledge Domains** - Expand beyond web development
-- [ ] **Offline Mode** - Run StarCoder2 tokenization locally (no API needed)
-- [ ] **Team Collaboration** - Share knowledge across team
-- [ ] **Custom Agents** - Create your own specialized agents
-- [ ] **IDE Plugins** - Direct integration with VSCode, IntelliJ
-- [ ] **Real-time Learning** - AI learns from your commits
-
-### Contributing
-
-We welcome contributions! Check out:
-- [Contributing Guide](https://github.com/sylphxltd/flow/wiki/Contributing)
-- [Good First Issues](https://github.com/sylphxltd/flow/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-- [Discord Community](#) (coming soon)
-
----
-
-## 📊 Project Stats
-
-<div align="center">
-
-![GitHub Stars](https://img.shields.io/github/stars/sylphxltd/flow?style=for-the-badge)
-![GitHub Forks](https://img.shields.io/github/forks/sylphxltd/flow?style=for-the-badge)
-![GitHub Issues](https://img.shields.io/github/issues/sylphxltd/flow?style=for-the-badge)
-![License](https://img.shields.io/github/license/sylphxltd/flow?style=for-the-badge)
-
-</div>
-
----
-
-## 🙏 Acknowledgments
-
-Built with:
-- **[StarCoder2](https://huggingface.co/bigcode/starcoder2)** - Code tokenization
-- **[MCP Protocol](https://modelcontextprotocol.io)** - AI tool integration
-- **[Anthropic Claude](https://claude.ai)** - AI foundation
-- Open source community ❤️
-
----
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) file for details.
-
----
-
-<div align="center">
-
-**[⭐ Star us on GitHub](https://github.com/sylphxltd/flow)** • **[📖 Read the Docs](https://github.com/sylphxltd/flow/wiki)** • **[🐛 Report Issues](https://github.com/sylphxltd/flow/issues)**
-
-**Stop writing prompts. Start building software.**
-
-Made with ❤️ by [Sylphx Ltd](https://github.com/sylphxltd)
-
-</div>

package/assets/agents/coder.md

@@ -1,32 +0,0 @@
----
-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/assets/agents/orchestrator.md

@@ -1,36 +0,0 @@
----
-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.