@exaudeus/workrail 0.8.5 → 0.9.0

package/README.md

@@ -1,496 +1,250 @@
 <div align="center">
-  <img src="./assets/logo.svg" alt="WorkRail Logo" width="200" />
-  <h1>WorkRail: Guided Workflow Orchestration for AI Agents</h1>
-  <p><strong>Transform chaotic AI interactions into structured, reliable workflows</strong></p>
-  
-  [![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.org)
-  [![npm version](https://img.shields.io/npm/v/@exaudeus/workrail.svg)](https://www.npmjs.com/package/@exaudeus/workrail)
-  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-</div>
-
----
+  <img src="./assets/logo.svg" alt="WorkRail Logo" width="180" />
+  <h1>WorkRail</h1>
+  <p>Step-by-step workflow enforcement for AI agents</p>
 
-## 📑 Table of Contents
-
-- [The Problem](#-the-problem)
-- [The Solution](#-the-solution)
-- [MCP Tools](#️-mcp-tools)
-- [Installation](#️-installation)
-- [External Workflows](#-external-workflows-load-from-git-repositories)
-- [Local Workflows](#-using-local-workflows)
-- [Available Workflows](#-available-workflows)
-- [Loop Support](#-loop-support)
-- [Quick Example](#-quick-example)
-- [Why Choose WorkRail](#-why-choose-workrail)
-- [Environment Variables](#-environment-variables-reference)
-  - [Workflow Sources](#workflow-sources)
-  - [External Git Repositories](#external-git-repositories)
-  - [Cache & Performance](#cache--performance)
-  - [Debugging & Logging](#debugging--logging)
-- [Getting Started](#-getting-started)
-- [Planned Features](#-planned-features)
-- [Learn More](#-learn-more)
+[![npm version](https://img.shields.io/npm/v/@exaudeus/workrail.svg)](https://www.npmjs.com/package/@exaudeus/workrail)
+[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+</div>
 
 ---
 
-## 🤔 The Problem
-
-Large Language Models are incredibly powerful but suffer from well-documented limitations:
-
-- **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
-
-Traditional approaches try to solve these through better prompting or more powerful models. WorkRail takes a different approach.
+## The Problem
 
-## 💡 The Solution
+AI agents are eager to help. Too eager.
 
-WorkRail guides LLMs through **proven software engineering best practices** via structured workflows, making it much more difficult for the LLM to go off track.
+Ask one to fix a bug and it starts editing code immediately - before understanding the system, before
+considering alternatives, before verifying assumptions. It's not stupid; it's a predictive model
+doing what predictive models do: fill in gaps and race to an answer.
 
-Instead of hoping an LLM will follow best practices, this system **guides them toward** best practices through structured, machine-readable workflows.
+You can add system prompts: "plan before coding," "gather context first." But as conversations grow,
+those instructions fade into the background. The agent reverts to its default: assume, predict, jump
+to conclusions.
 
-**Traditional Approach:**
-```
-User: "Help me implement this feature"
-AI: [May or may not ask for context, may or may not plan, may or may not test]
-```
-
-**WorkRail Approach:**
-```
-Workflow guides: Context → Clarification → Planning → Implementation → Verification  
-AI: [Cannot skip steps, must follow proven patterns]
-```
-
-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.
+**The result: inconsistent quality that depends on how much you babysit the agent.**
 
 ---
 
-## 🛠️ MCP Tools
-
-WorkRail exposes 6 core tools through the Model Context Protocol:
+## How WorkRail Works
 
-- **`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
+WorkRail replaces the human effort of guiding an agent step-by-step.
 
----
+Instead of one system prompt that fades over time, WorkRail drip-feeds instructions through
+the [Model Context Protocol](https://modelcontextprotocol.org). The agent calls `workflow_next`,
+gets ONE step, completes it, calls again. Future steps stay hidden until previous ones are done.
 
-## ⚙️ Installation
+**The agent can't skip to implementation because it doesn't know those steps exist yet.**
 
-Add WorkRail to your AI agent by configuring the MCP server:
+### The Mechanism
 
-### NPX (Recommended)
-Add to your agent's `config.json`:
-```json
-{
-  "mcpServers": {
-    "workrail": {
-      "command": "npx",
-      "args": ["-y", "@exaudeus/workrail"]
-    }
-  }
-}
 ```
-
-### Docker
-Add to your agent's `config.json`:
-```json
-{
-  "mcpServers": {
-    "workrail": {
-      "command": "docker",
-      "args": ["run", "--rm", "-i", "workrail-mcp"]
-    }
-  }
-}
+You                      Agent                     WorkRail
+ │                         │                          │
+ │  "Fix the auth bug"     │                          │
+ │────────────────────────>│                          │
+ │                         │                          │
+ │                         │  workflow_next()         │
+ │                         │─────────────────────────>│
+ │                         │                          │
+ │                         │   Step 1: Understand     │
+ │                         │      the problem         │
+ │                         │<─────────────────────────│
+ │                         │                          │
+ │   "What error do you    │                          │
+ │    see exactly?"        │                          │
+ │<────────────────────────│                          │
+ │                         │                          │
+ │         ...             │  workflow_next()         │
+ │                         │─────────────────────────>│
+ │                         │                          │
+ │                         │   Step 2: Plan your      │
+ │                         │      investigation       │
+ │                         │<─────────────────────────│
 ```
 
----
-
-## 🌐 External Workflows: Load from Git Repositories
-
-**NEW in v0.6+**: Load workflows from GitHub, GitLab, Bitbucket, or any Git repository!
+### Without WorkRail
 
-Perfect for:
-- **Team sharing** - Company-wide workflow repositories
-- **Community workflows** - Shared across organizations
-- **Version control** - Track workflow changes in Git
-- **Multi-source** - Combine workflows from multiple repos
-
-### Quick Start
-
-Add to your agent config:
-
-```json
-{
-  "mcpServers": {
-    "workrail": {
-      "command": "npx",
-      "args": ["-y", "@exaudeus/workrail"],
-      "env": {
-        "WORKFLOW_GIT_REPOS": "https://github.com/your-org/workflows.git",
-        "GITHUB_TOKEN": "your-github-token"
-      }
-    }
-  }
-}
 ```
+You:   "There's a bug in the auth flow"
 
-### Multiple Repositories
-
-Load workflows from multiple sources (later repos override earlier ones):
-
-```json
-"env": {
-  "WORKFLOW_GIT_REPOS": "https://github.com/company/workflows.git,https://gitlab.com/team/workflows.git",
-  "GITHUB_TOKEN": "ghp_xxx",
-  "GITLAB_TOKEN": "glpat_xxx"
-}
+Agent: "I see the issue! In auth.js line 42, there's a null check that 
+        should handle this. Let me fix it..."
+        
+        *edits code based on a 30-second skim*
+        *breaks something else*
 ```
 
-### Authentication Options
+### With WorkRail
 
-**Service-Specific Tokens** (Recommended):
-```bash
-GITHUB_TOKEN=ghp_xxxx           # For github.com
-GITLAB_TOKEN=glpat_xxxx          # For gitlab.com
-BITBUCKET_TOKEN=xxx              # For bitbucket.org
 ```
+You:   "There's a bug in the auth flow"
 
-**Self-Hosted Git** (hostname-based):
-```bash
-GIT_COMPANY_COM_TOKEN=xxx        # For git.company.com
-GIT_INTERNAL_GITLAB_IO_TOKEN=xxx # For internal.gitlab.io
+Agent: "I'll use the bug-investigation workflow."
+        → workflow_next()
+       
+       Step 1: Investigation Setup
+       "Before I investigate, I need to understand the problem.
+        What exactly happens when it fails? Can you share the error?"
+       
+       [Documents bug, reproduction steps, environment]
+        → workflow_next()
+       
+       Step 2: Plan Investigation
+       "I'll trace execution from login through the auth middleware.
+        Key areas: token validation, session lookup, error handling."
+       
+       [Creates investigation plan before touching code]
+        → workflow_next()
+       
+       Step 3: Form Hypotheses
+       "Based on my analysis, three possible causes:
+        H1: Clock skew in token validation (7/10)
+        H2: Race condition in session lookup (6/10)
+        H3: Null check masking the real error (4/10)"
+       
+       [Tests hypotheses systematically, gathers evidence, proves root cause]
 ```
 
-**SSH Keys** (no token needed):
-```bash
-WORKFLOW_GIT_REPOS="git@github.com:company/workflows.git"
-# Uses your ~/.ssh/ keys automatically
-```
+Same agent. Same model. But it prepared properly because it had no choice.
 
-**Generic Fallback**:
-```bash
-GIT_TOKEN=xxx                    # Used if no specific token found
-WORKFLOW_GIT_AUTH_TOKEN=xxx      # Alternative generic token
-```
+### Why Steps Are Structured This Way
 
-### Repository Structure
+Each step follows a pattern that prevents common AI failure modes:
 
-Your Git repository should have a `/workflows` directory:
+- **Prep**: Understand before acting - read the code, clarify requirements, confirm approach
+- **Implement**: One focused change - not five things at once
+- **Verify**: Validate before continuing - catch errors before they compound
 
-```
-your-repo/
-├── workflows/
-│   ├── custom-workflow.json
-│   ├── team-process.json
-│   └── company-standard.json
-└── README.md (optional)
-```
+This isn't arbitrary structure. It's how experienced developers actually work.
 
-### Features
+### Why This Beats System Prompts
 
-- ✅ **Auto-sync** - Workflows update automatically (configurable interval)
-- ✅ **Caching** - Works offline after initial clone
-- ✅ **Security** - Path traversal prevention, file size limits, command injection protection
-- ✅ **Priority system** - Later repos override earlier ones
-- ✅ **Branch support** - Specify branch in repo config
+| System Prompt | WorkRail |
+|---------------|----------|
+| "Plan first" fades as context grows | Each step is fresh and immediate |
+| Agent decides what to follow | Agent can't skip - next step is hidden |
+| One-size-fits-all instructions | Workflows adapt to task complexity |
+| Inconsistent results | Repeatable, consistent quality |
 
 ---
 
-## 💾 Using Local Workflows
-
-WorkRail will auto-discover workflows even when added to your agent via JSON config. It searches, in priority order:
+## Quick Start
 
-- User: `~/.workrail/workflows` (recommended)
-- Project: `./workflows` relative to the MCP process `cwd`
-- Custom: directories listed in `WORKFLOW_STORAGE_PATH` (colon-separated on macOS/Linux)
-
-Example agent config passing env and `cwd` so your local workflows are picked up:
+Add to your MCP client config (Claude Code, Cursor, Firebender, Antigravity, etc.):
 
 ```json
 {
   "mcpServers": {
     "workrail": {
       "command": "npx",
-      "args": ["-y", "@exaudeus/workrail"],
-      "env": {
-        "WORKFLOW_STORAGE_PATH": "/absolute/path/my-workflows:/absolute/path/shared-workflows"
-      },
-      "cwd": "/absolute/path/my-project"
+      "args": ["-y", "@exaudeus/workrail"]
     }
   }
 }
 ```
 
-WorkRail searches for workflows in this priority order:
-
-1. **Bundled** - Built-in workflows (always available)
-2. **User** - `~/.workrail/workflows` (recommended for personal workflows)
-3. **Custom** - Directories in `WORKFLOW_STORAGE_PATH` (team/shared workflows)
-4. **Git Repositories** - External repos via `WORKFLOW_GIT_REPOS` ([see above](#-external-workflows-load-from-git-repositories))
-5. **Project** - `./workflows` relative to process `cwd` (project-specific)
-
-Later sources override earlier ones when workflow IDs conflict.
-
-### Quick Tips
-
-```bash
-# Initialize your user directory
-workrail init
-
-# Validate a workflow file
-workrail validate /path/to/workflow.json
+Then prompt your agent:
 
-# List all discovered workflows
-workrail list
+> "Use the bug-investigation workflow to debug this auth issue"
 
-# Get workflow JSON schema
-workrail schema
-```
-
-See `docs/workflow-management.md` for more details.
+The agent will find the workflow, start at step 1, and proceed systematically.
 
 ---
 
-## 📋 Available Workflows
-
-WorkRail comes with battle-tested workflows for common development tasks:
-
-### 🔧 **Development Workflows**
-- **`coding-task-workflow-with-loops`** - Enhanced coding workflow with iterative refinement loops, analysis, planning, implementation, and review *(Recommended)*
-- **`systematic-bug-investigation-with-loops`** - Enhanced debugging with iterative analysis loops and systematic methodology *(Recommended)*
-
-#### Deprecated Workflows
-- ~~**`coding-task-workflow`** - [DEPRECATED] Use `coding-task-workflow-with-loops` instead~~
-- ~~**`systematic-bug-investigation`** - [DEPRECATED] Use `systematic-bug-investigation-with-loops` instead~~
-
-### 🚀 **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
+## CI & Releases
 
-### 🔍 **Discovery & Analysis**
-- **`exploration-workflow`** - Systematic codebase or domain exploration
-- **`workflow-for-workflows`** - Meta-workflow for designing new workflows
+- **Lockfile is enforced**: `package-lock.json` is canonical and CI will fail if `npm ci` would modify it. Commit lockfile changes intentionally.
+- **Release authority**: releases are produced by **semantic-release** in GitHub Actions (don’t bump versions/tags locally).
+- **Preview a release (dry-run)**:
+  - **Locally**: `npx semantic-release --dry-run --no-ci`
+  - **In Actions**: run the **Release (dry-run)** workflow (`.github/workflows/release-dry-run.yml`).
 
 ---
 
-## 🔄 Loop Support
+## Included Workflows
 
-WorkRail supports powerful iteration patterns for complex tasks:
+20+ workflows included for development, debugging, review, documentation, and more:
 
-- **`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
+| Workflow | When to Use |
+|----------|-------------|
+| `coding-task-workflow-with-loops` | Feature development with analysis, planning, and review |
+| `bug-investigation` | Systematic debugging with hypothesis testing |
+| `mr-review-workflow` | Code review with architecture and security checks |
+| `exploration-workflow` | Understanding an unfamiliar codebase |
+| `document-creation-workflow` | Technical documentation with structure |
 
-Perfect for batch operations, retries, polling, and iterative refinement.
+Workflows adapt to complexity - simple tasks get fast-tracked, complex tasks get full rigor.
 
-### 🚀 v0.2.0: Optimized Loop Execution
-
-- **60-80% smaller context** after first iteration
-- **Progressive disclosure** pattern for loop information
-- **Native function DSL** to reduce duplication
-- **Automatic empty loop detection** and skipping
-
-See [Loop Optimization Guide](docs/features/loop-optimization.md) for details.
+[See all workflows →](docs/workflows.md)
 
 ---
 
-## 📖 Quick Example
-
-Here's what a workflow step looks like:
-
-```json
-{
-  "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**.
+## The Philosophy
 
----
+### Guardrails Enable Excellence
 
-## 🌟 Why Choose WorkRail?
+WorkRail doesn't lobotomize your AI. The agent still reasons, explores, and creates - but within a
+structure that ensures it actually prepares, plans, and verifies. Guardrails prevent shortcuts, not
+creativity.
 
-### 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.
+### Expert Knowledge, Codified
 
-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
+Workflows aren't just task checklists. They embed hard-won expertise: "verify understanding before
+implementing," "form multiple hypotheses before concluding," "test assumptions with evidence." This
+is how senior engineers think - now encoded into every workflow.
 
-| 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 |
+### Replacing the Human Guide
 
----
-
-## 🚀 Getting Started
+A skilled developer doesn't let AI run unsupervised on complex tasks. They guide it: "Wait, did you
+check X?" "What about edge case Y?" "Show me your reasoning."
 
-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
+WorkRail does this automatically. The workflow asks the questions a senior dev would ask, at the
+moments they'd ask them.
 
 ---
 
-## 🌟 Environment Variables Reference
+## Create Your Own
 
-Customize WorkRail's behavior with these environment variables:
+Drop a JSON file in `~/.workrail/workflows/`:
 
-### Workflow Sources
-```bash
-WORKFLOW_INCLUDE_BUNDLED=true   # Include built-in workflows (default: true)
-WORKFLOW_INCLUDE_USER=true      # Include ~/.workrail/workflows (default: true)
-WORKFLOW_INCLUDE_PROJECT=true   # Include ./workflows from cwd (default: true)
-WORKFLOW_STORAGE_PATH=/path1:/path2  # Additional directories (colon-separated)
-```
-
-### External Git Repositories
-```bash
-# Single or multiple repos (comma-separated)
-WORKFLOW_GIT_REPOS=https://github.com/org/repo.git
-WORKFLOW_GIT_REPOS=repo1.git,repo2.git,repo3.git
-
-# Authentication
-GITHUB_TOKEN=ghp_xxx            # GitHub
-GITLAB_TOKEN=glpat_xxx          # GitLab  
-BITBUCKET_TOKEN=xxx             # Bitbucket
-GIT_HOSTNAME_TOKEN=xxx          # Self-hosted (replace dots with underscores)
-GIT_TOKEN=xxx                   # Generic fallback
-```
-
-### Cache & Performance
-```bash
-WORKRAIL_CACHE_DIR=/path/to/cache  # Cache location (default: ~/.workrail/cache)
-CACHE_TTL=300000                    # Cache TTL in ms (default: 5 minutes)
-```
-
-### Debugging & Logging
-```bash
-# Log levels: DEBUG, INFO, WARN, ERROR, SILENT (default: SILENT)
-WORKRAIL_LOG_LEVEL=INFO
-
-# Log format: 'human' (default) or 'json'
-WORKRAIL_LOG_FORMAT=json
-```
-
-**Log Levels:**
-- `DEBUG` - Verbose logging (cloning, pulling, file operations)
-- `INFO` - Key operations (initialization, workflows loaded)
-- `WARN` - Warnings (branch fallbacks, pull failures)
-- `ERROR` - Errors only
-- `SILENT` - No logging (default in production)
-
-**Example MCP Configuration with Logging:**
 ```json
 {
-  "mcpServers": {
-    "workrail": {
-      "command": "npx",
-      "args": ["-y", "@exaudeus/workrail@beta"],
-      "env": {
-        "WORKRAIL_LOG_LEVEL": "INFO",
-        "WORKFLOW_GIT_REPOS": "https://github.com/org/workflows.git"
-      }
+  "id": "my-review-checklist",
+  "name": "Team Code Review",
+  "version": "1.0.0",
+  "description": "Our standard review process",
+  "steps": [
+    {
+      "id": "check-tests",
+      "title": "Verify Test Coverage",
+      "prompt": "Check that new code has tests. List untested paths.",
+      "agentRole": "You are a reviewer focused on test coverage."
+    },
+    {
+      "id": "check-security",
+      "title": "Security Review",
+      "prompt": "Look for: injection risks, auth issues, data exposure.",
+      "agentRole": "You are a security-focused reviewer."
     }
-  }
+  ]
 }
 ```
 
-Logs are written to **stderr** (stdout is reserved for MCP protocol), so they appear in your MCP client's logs (e.g., Firebender, Claude Desktop).
-
-### Priority Order
+WorkRail discovers it automatically. This is a minimal example - workflows also
+support [conditions, loops, validation criteria](docs/authoring.md), and more.
 
-Workflows are loaded with this priority (later sources override earlier):
-1. Bundled (built-in workflows)
-2. Plugins (npm packages)
-3. User directory (`~/.workrail/workflows`)
-4. Custom paths (`WORKFLOW_STORAGE_PATH`)
-5. Git repositories (`WORKFLOW_GIT_REPOS`)
-6. Project directory (`./workflows`)
+[Writing workflows →](docs/authoring.md) · [Load from Git →](docs/configuration.md#git-repositories)
 
 ---
 
-## 🚀 Planned Features
+## Documentation
 
-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
-
-*Note: WorkRail provides text recommendations to users, not automatic model switching*
-
-### **Enhanced Workflow Management**
-- ✅ ~~**Dynamic Workflow Loading**~~ - **IMPLEMENTED in v0.6+** (Git repositories)
-- **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
-- **Workflow Templates** - Create workflows from templates via CLI
-
-### **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
+- [All Workflows](docs/workflows.md) – Full list with detailed descriptions
+- [Writing Workflows](docs/authoring.md) – Custom workflow creation guide
+- [Configuration](docs/configuration.md) – Git repos, environment variables, local paths
+- [Advanced Features](docs/advanced.md) – Loops, conditionals, validation
 
 ---
-*Have ideas for WorkRail? The planned features list helps guide development priorities.*
-
----
-
-## 📚 Learn More
-
-- **[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 License - see [LICENSE](LICENSE)
+[GitHub](https://github.com/EtienneBBeaulac/workrail) · MIT License