@exaudeus/workrail 0.1.1 → 0.1.3

package/README.md

@@ -1,270 +1,234 @@
-# WorkRail: A Workflow Orchestration Server for MCP
+# WorkRail: Guided Workflow Orchestration for AI Agents
 
-> **Reliable, test-driven workflow execution for AI coding assistants – powered by Clean Architecture**
+> **Transform chaotic AI interactions into structured, reliable workflows**
 
-[![Build](https://img.shields.io/github/actions/workflow/status/EtienneBBeaulac/mcp/ci.yml?branch=main)]()
-[![Version](https://img.shields.io/badge/version-0.0.1--alpha-orange)]()
 [![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.org)
+[![Version](https://img.shields.io/badge/version-0.1.0-blue)]()
 
 ---
 
-## 🚀 Overview
+## 🤔 The Problem
 
-Large language models are phenomenal at generating code, yet they often hallucinate, lose context, or perform unsafe operations.  
-This server provides **structured, step-by-step workflows** (defined as JSON documents) that guide an AI assistant through safe, repeatable tasks.  
-It follows [Model Context Protocol (MCP)](https://modelcontextprotocol.org) conventions and exposes a **JSON-RPC 2.0** interface on `stdin/stdout`.
+Large Language Models are incredibly powerful but suffer from well-documented limitations:
 
-The codebase now implements the full MVP described in the original specification, refactored with Clean Architecture for long-term maintainability.
+- **Hallucination** - They confidently generate plausible-sounding but incorrect information
+- **Scope Creep** - Given a complex task, they often try to do too much at once, leading to half-baked solutions  
+- **Context Loss** - They struggle to maintain focus across long conversations
+- **Inconsistency** - The same prompt can yield wildly different results based on minor variations
+- **Missing Prerequisites** - They often start implementing before gathering necessary context
 
-### ✨ New in v0.1.0: Loop Support
-WorkRail now supports powerful iteration patterns with four loop types:
-- **while**: Continue while a condition is true
-- **until**: Continue until a condition is met  
-- **for**: Execute a fixed number of times
-- **forEach**: Process items in an array
+Traditional approaches try to solve these through better prompting or more powerful models. WorkRail takes a different approach.
 
-See the [Loop Documentation](docs/features/loops.md) for details.
+## 💡 The Solution
 
----
-
-## 🚀 Quick Start
-
-```bash
-# Install globally
-npm install -g @exaudeus/workrail
-
-# Initialize your personal workflow directory
-workrail init
+WorkRail guides LLMs through **proven software engineering best practices** via structured workflows, making it much more difficult for the LLM to go off track.
 
-# List all available workflows (bundled + your custom ones)
-workrail list
+Instead of hoping an LLM will follow best practices, this system **guides them toward** best practices through structured, machine-readable workflows.
 
-# Check workflow sources and status
-workrail sources
-
-# Validate a workflow file
-workrail validate my-workflow.json
-
-# Start the MCP server
-workrail start
+**Traditional Approach:**
 ```
-
-**Multiple Workflow Sources**: WorkRail automatically loads workflows from:
-- **Bundled workflows** (included with the package)
-- **User workflows** (`~/.workrail/workflows/`)
-- **Project workflows** (`./workflows/`)
-- **Custom directories** (via `WORKFLOW_STORAGE_PATH` environment variable)
-
----
-
-## ✨ Key Features
-
-* **Clean Architecture** – clear separation of **Domain → Application → Infrastructure** layers.
-* **MCP Protocol Support** – Full MCP SDK integration with proper tool definitions and stdio transport.
-* **Workflow Orchestration Tools** – 5 core tools for workflow management:
-  - `workflow_list` - List all available workflows
-  - `workflow_get` - Get detailed workflow information  
-  - `workflow_next` - Get the next step in a workflow
-  - `workflow_validate` - Advanced validation of step outputs with schema, context-aware, and composition rules
-  - `workflow_validate_json` - Direct JSON workflow validation with comprehensive error reporting and actionable suggestions
-* **Loop Support (v0.1.0)** – Four loop types for powerful iteration patterns:
-  - `while` loops - Continue while a condition is true
-  - `until` loops - Continue until a condition is met
-  - `for` loops - Execute a fixed number of times
-  - `forEach` loops - Process items in an array
-* **Dependency Injection** – pluggable components are wired by `src/container.ts` (Inversify-style, no runtime reflection).
-* **Async, Secure Storage** – interchangeable back-ends: in-memory (default for tests) and file-based storage with path-traversal safeguards.
-* **Advanced ValidationEngine** – Three-tier validation system with JSON Schema validation (AJV), Context-Aware Validation (conditional rules), and Logical Composition (and/or/not operators) for comprehensive step output quality assurance.
-* **Typed Error Mapping** – domain errors (`WorkflowNotFoundError`, `ValidationError`, …) automatically translate to proper JSON-RPC codes.
-* **CLI Tools** – 
-  - `validate` - Test workflow files locally with comprehensive error reporting
-  - `migrate` - Automatically migrate workflows from v0.0.1 to v0.1.0
-* **Comprehensive Test Coverage** – 81 tests passing, 7 failing (performance optimizations in progress), 88 total tests covering storage, validation, error mapping, CLI, and server logic.
-
----
-
-## ⚡ Quick Start
-
-### Prerequisites
-* Node 18+
-* `npm install`
-
-### Development mode
-```bash
-npm run dev
+User: "Help me implement this feature"
+AI: [May or may not ask for context, may or may not plan, may or may not test]
 ```
-The MCP server listens for JSON-RPC requests on **stdin/stdout**.
 
-### Production build
-```bash
-npm run build
-node dist/mcp-server.js
+**WorkRail Approach:**
 ```
-
-### Workflow validation (CLI utility)
-```bash
-npx ts-node src/cli.ts validate <workflow-file.json>
+Workflow guides: Context → Clarification → Planning → Implementation → Verification  
+AI: [Cannot skip steps, must follow proven patterns]
 ```
 
-### Docker
-```bash
-docker-compose up
-```
+This creates an enhanced experience where developers are guided through optimal workflows, missing fewer critical steps, while LLMs work within their strengths following proven patterns.
 
 ---
 
-## 🔧 Configuration
+## 🛠️ MCP Tools
 
-### Usage with Claude Desktop
+WorkRail exposes 6 core tools through the Model Context Protocol:
+
+- **`workflow_list`** - Browse available workflows for different task types
+- **`workflow_get`** - Get complete workflow details and requirements  
+- **`workflow_next`** - Get the next step in an active workflow
+- **`workflow_validate`** - Validate step outputs against quality criteria
+- **`workflow_validate_json`** - Validate and lint workflow JSON files
+- **`workflow_get_schema`** - Get the complete workflow JSON schema for workflow creation
+
+---
 
-Add this to your `claude_desktop_config.json`:
+## ⚙️ Installation
 
-#### npx (once published to npm)
+Add WorkRail to your AI agent by configuring the MCP server:
 
+### NPX (Recommended)
+Add to your agent's `config.json`:
 ```json
 {
   "mcpServers": {
     "workrail": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@exaudeus/workrail"
-      ]
+      "args": ["-y", "@exaudeus/workrail"]
     }
   }
 }
 ```
 
-#### Local development
-
+### Docker
+Add to your agent's `config.json`:
 ```json
 {
   "mcpServers": {
     "workrail": {
-      "command": "node",
-      "args": [
-        "/path/to/your/mcp/packages/workrail/dist/mcp-server.js"
-      ]
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "workrail-mcp"]
     }
   }
 }
 ```
 
-### Usage with VS Code
+---
 
-For manual installation, add this to your User Settings (JSON) or `.vscode/mcp.json`:
+## 📋 Available Workflows
 
-#### npx (once published)
+WorkRail comes with battle-tested workflows for common development tasks:
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "workrail": {
-        "command": "npx",
-        "args": [
-          "-y",
-          "@exaudeus/workrail"
-        ]
-      }
-    }
-  }
-}
-```
+### 🔧 **Development Workflows**
+- **`coding-task-workflow`** - Comprehensive coding workflow with analysis, planning, implementation, and review
+- **`coding-task-workflow-with-loops`** - Enhanced version with iterative refinement loops
+- **`systematic-bug-investigation`** - Systematic debugging methodology that prevents jumping to conclusions
+- **`systemic-bug-investigation-with-loops`** - Enhanced debugging with iterative analysis loops
+
+### 🚀 **Project Management**  
+- **`adaptive-ticket-creation`** - Create well-structured tickets with proper requirements
+- **`mr-review-workflow`** - Thorough merge request review process
+
+### 📚 **Content & Documentation**
+- **`document-creation-workflow`** - Structured approach to creating comprehensive documentation
+- **`presentation-creation`** - Build engaging presentations with clear narrative flow
+- **`personal-learning-course-design`** - Design educational content with learning objectives
+- **`personal-learning-materials-creation-branched`** - Create comprehensive learning materials with adaptive complexity
+
+### 🔍 **Discovery & Analysis**
+- **`exploration-workflow`** - Systematic codebase or domain exploration
+- **`workflow-for-workflows`** - Meta-workflow for designing new workflows
+
+---
+
+## 🔄 Loop Support
+
+WorkRail supports powerful iteration patterns for complex tasks:
+
+- **`while`** - Continue while a condition is true
+- **`until`** - Continue until a condition is met  
+- **`for`** - Execute a fixed number of times
+- **`forEach`** - Process items in an array
+
+Perfect for batch operations, retries, polling, and iterative refinement.
+
+---
+
+## 📖 Quick Example
 
-#### Local development
+Here's what a workflow step looks like:
 
 ```json
 {
-  "mcp": {
-    "servers": {
-      "workrail": {
-        "command": "node",
-        "args": [
-          "/path/to/your/mcp/packages/workrail/dist/mcp-server.js"
-        ]
-      }
-    }
+  "id": "analyze-codebase",
+  "name": "Deep Codebase Analysis",
+  "description": "Understand the codebase structure before making changes",
+  "agentRole": "You are a senior engineer performing careful code analysis",
+  "runCondition": {
+    "type": "context",
+    "key": "taskComplexity", 
+    "operator": "in",
+    "values": ["Medium", "Large"]
+  },
+  "validationCriteria": {
+    "outputLength": {"min": 200, "max": 2000},
+    "mustContain": ["file structure", "key components", "dependencies"]
   }
 }
 ```
 
+The agent receives structured guidance on **what to do**, **how to do it**, and **quality standards to meet**.
+
 ---
 
-## 🗂️ Project Structure (post-refactor)
+## 🌟 Why Choose WorkRail?
 
-```
-packages/workrail/
-  ├─ src/
-  │   ├─ domain/               # Pure entities & errors (no dependencies)
-  │   ├─ application/          # Use-cases, services, ValidationEngine (depends on domain)
-  │   ├─ infrastructure/
-  │   │   ├─ rpc/              # JSON-RPC server adapter
-  │   │   └─ storage/          # File, in-memory, caching, schema-validating adapters
-  │   ├─ mcp-server.ts         # MCP server implementation (main entry point)
-  │   ├─ cli.ts                # CLI utility for workflow validation
-  │   ├─ container.ts          # DI registrations
-  │   └─ index.ts              # Library entrypoint (exports container)
-  ├─ tests/                    # Jest test suites (unit & integration)
-  └─ docs/                     # Guides, reference, advanced topics
-```
+### Consistency & Reproducibility  
+One of the biggest challenges with AI-assisted development is inconsistency. The same request can yield wildly different approaches depending on how the prompt is phrased, the LLM's randomness, or the developer's prompting expertise.
 
-### Layered flow
-```
-Client (AI Agent)
-   ▼  MCP Protocol (stdin/stdout)
-MCP Server       ── mcp-server.ts (MCP SDK adapter)
-   ▼  calls
-Application      ── use-cases (pure biz logic)
-   ▼  operates on
-Domain           ── entities & value objects
-```
+WorkRail reduces these variables:
+- **Same Process** - Every developer follows the same workflow
+- **Same Quality** - Helps junior developers produce work closer to senior-level quality  
+- **Same Standards** - Code style and patterns are guided by workflows
+- **Audit Trail** - Every decision is logged and reviewable
 
----
+| Without WorkRail | With WorkRail |
+|------------------|---------------|
+| "Just fix this bug" → agent makes random changes | Systematic investigation → evidence-based diagnosis → targeted fix |
+| "Add a feature" → incomplete implementation | Analysis → planning → implementation → testing → review |
+| Inconsistent quality across tasks | Repeatable, high-quality processes |
+| Outcome depends on prompting skills | Guided best practices regardless of experience |
 
-## 🛠️ Environment Variables
+---
 
-| Env Var | Default | Description |
-|---------|---------|-------------|
-| `WORKFLOW_DIR` | `spec/examples` | Path where workflow JSON files are loaded (file storage) |
-| `CACHE_TTL` | `300000` | Cache TTL in ms for `CachingWorkflowStorage` |
-| `PORT` | _n/a_ | Not used (stdin/stdout transport) |
+## 🚀 Getting Started
 
-Change them before starting the server, e.g. `export WORKFLOW_DIR=/opt/workflows`.
+1. **Install** WorkRail as an MCP server (see installation above)
+2. **Browse workflows** - Use `workflow_list` to see available options
+3. **Start a workflow** - Use `workflow_get` to load a workflow for your task  
+4. **Follow the steps** - Use `workflow_next` to get guided, step-by-step instructions
+5. **Validate progress** - Use `workflow_validate` to ensure quality at each step
 
 ---
 
-## 🧪 Running Tests
+## 🚀 Planned Features
 
-```bash
-npm test
-```
-Current status: 81 tests passing, 7 failing (performance optimizations in progress), 88 total tests.
+WorkRail is actively evolving. Here are key enhancements on the roadmap:
 
----
+### **Workflow State Management**
+- **Save & Resume** - Generate workflow state summaries for resuming complex workflows in new chat sessions
+- **Context Preservation** - Maintain workflow progress across conversation boundaries
+- **Checkpoint System** - Save progress at key milestones for easy recovery
+
+### **Model Switching Guidance**
+Workflows could recommend optimal models for specific steps:
+- **Analysis steps** → Tool-use heavy models (Claude) for codebase exploration
+- **Planning/design** → Smartest available models for strategic thinking  
+- **Implementation** → Cost-effective models once requirements are clear
 
-## 📚 Documentation Status
+*Note: WorkRail provides text recommendations to users, not automatic model switching*
 
-| Component | Status | Updated |
-|-----------|--------|---------|
-| Root README | ✅ Complete | 2024-07-10 |
-| Implementation guides | 🔄 In Progress | 2024-07-10 |
-| Migration guide 1.2 | 🔄 In Progress | 2024-07-10 |
-| Code snippet refresh | 🔄 In Progress | 2024-07-10 |
+### **Enhanced Workflow Management**
+- **Dynamic Workflow Loading** - Add/edit workflows without republishing the server
+- **Workflow Categories** - Organize workflows by domain (debugging, planning, review, etc.)
+- **Reusable Components** - Plugin system for common workflow patterns (codebase analysis, document creation, etc.)
+- **Schema Versioning** - Backwards-compatible workflow schema evolution
+
+### **Advanced Validation & Quality**
+- **Custom Validation Functions** - Domain-specific output validation beyond basic schema checks
+- **Integration Hooks** - Connect with external quality tools and linters
+- **Performance Validation** - Ensure workflow outputs meet performance criteria
+- **Length Validation Optimization** - Faster validation using terminal commands vs. full content rewrite
+
+### **Workflow Discovery & Intelligence**
+- **Smart Workflow Suggestions** - Recommend workflows based on task context
+- **Pattern Recognition** - Identify when existing codebase patterns should inform workflow steps
 
 ---
+*Have ideas for WorkRail? The planned features list helps guide development priorities.*
 
-## 🤝 Contributing
+---
 
-1. **Fork & PR** – small, focused pull requests please.
-2. **Follow the Architecture** – domain logic must remain framework-free; side effects live in infrastructure.
-3. **Add Tests** – no code is accepted without unit tests.
-4. **Run `npm run lint:fix`** before pushing.
+## 📚 Learn More
 
-See `docs/advanced/contributing.md` for full details.
+- **[Complete Overview](workrail-mcp-overview.md)** - Deep dive into architecture, philosophy, and detailed examples
+- **[Loop Documentation](docs/features/loops.md)** - Advanced iteration patterns  
+- **[API Specification](spec/mcp-api-v1.0.md)** - Complete MCP API reference
+- **[Internal Documentation](docs/README.md)** - Development and architecture guides
 
 ---
 
 ## 📄 License
 
-MIT – see [LICENSE](LICENSE).
+MIT License - see [LICENSE](LICENSE)

package/dist/application/services/classification-engine.d.ts

@@ -0,0 +1,33 @@
+import { ContextLayer, ClassificationRules, ClassifiedContext, RawContext } from '../../types/context-types';
+export interface IClassificationEngine {
+    classify(context: RawContext, rules?: ClassificationRules): Promise<ClassifiedContext>;
+    loadRules(config?: Partial<ClassificationRules>): Promise<void>;
+    addOverride(sessionId: string, contextKey: string, layer: ContextLayer): void;
+    removeOverride(sessionId: string, contextKey: string): void;
+    markCritical(sessionId: string, contextKey: string): Promise<void>;
+    getStats(): ClassificationStats;
+}
+export interface ClassificationStats {
+    totalClassifications: number;
+    layerDistribution: Record<ContextLayer, number>;
+    overrideCount: number;
+    averageProcessingTime: number;
+}
+export declare class ClassificationEngine implements IClassificationEngine {
+    private rules;
+    private overrides;
+    private stats;
+    constructor(initialRules?: ClassificationRules);
+    classify(context: RawContext, rules?: ClassificationRules): Promise<ClassifiedContext>;
+    loadRules(config?: Partial<ClassificationRules>): Promise<void>;
+    addOverride(sessionId: string, contextKey: string, layer: ContextLayer): void;
+    removeOverride(sessionId: string, contextKey: string): void;
+    markCritical(sessionId: string, contextKey: string): Promise<void>;
+    getStats(): ClassificationStats;
+    private classifyKeyValue;
+    private applyPatternMatching;
+    private matchesPattern;
+    private applyHeuristics;
+    private updateStats;
+    private getDefaultRules;
+}