---

The Problem

AI agents are eager to help. Too eager.

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.

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.

The result: inconsistent quality that depends on how much you babysit the agent.

---

How WorkRail Works

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. The agent calls start_workflow, gets the first step, completes it, calls continue_workflow. Future steps stay hidden until previous ones are done.

The agent can't skip to implementation because it doesn't know those steps exist yet.

The Mechanism

You                      Agent                     WorkRail
 │                         │                          │
 │  "Fix the auth bug"     │                          │
 │────────────────────────>│                          │
 │                         │                          │
 │                         │  start_workflow()        │
 │                         │─────────────────────────>│
 │                         │                          │
 │                         │   Step 1: Understand     │
 │                         │      the problem         │
 │                         │<─────────────────────────│
 │                         │                          │
 │   "What error do you    │                          │
 │    see exactly?"        │                          │
 │<────────────────────────│                          │
 │                         │                          │
 │         ...             │  continue_workflow()     │
 │                         │─────────────────────────>│
 │                         │                          │
 │                         │   Step 2: Plan your      │
 │                         │      investigation       │
 │                         │<─────────────────────────│

Without WorkRail

You:   "There's a bug in the auth flow"

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*

With WorkRail

You:   "There's a bug in the auth flow"

Agent: "I'll use the bug-investigation workflow."
        → start_workflow()
       
       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]
        → continue_workflow()
       
       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]
        → continue_workflow()
       
       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]

Same agent. Same model. But it prepared properly because it had no choice.

Why Steps Are Structured This Way

Each step follows a pattern that prevents common AI failure modes:

• 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

This isn't arbitrary structure. It's how experienced developers actually work.

Why This Beats System Prompts

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

---

Quick Start

Add to your MCP client config (Claude Code, Cursor, Firebender, Antigravity, etc.):

{
  "mcpServers": {
    "workrail": {
      "command": "npx",
      "args": ["-y", "@exaudeus/workrail"]
    }
  }
}

Then prompt your agent:

"Use the bug-investigation workflow to debug this auth issue"

The agent will find the workflow, start at step 1, and proceed systematically.

Troubleshooting: "Permission denied" on startup

Versions before 3.19.0 were published without the execute bit set on the binary. If you see Permission denied when WorkRail starts, reinstall or fix it in place:

# Option A: reinstall (recommended)
npm install -g @exaudeus/workrail

# Option B: fix in place without reinstalling
chmod +x $(npm root -g)/@exaudeus/workrail/dist/mcp-server.js

---

CI & Releases

• 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).
• Major releases are approval-gated: breaking changes become minor by default and only become major when WORKRAIL_ALLOW_MAJOR_RELEASE=true.
• Release type comes from the commit on main: for squash merges, the PR title / squash commit title controls whether the release is patch, minor, major, or untagged. See docs/reference/releases.md.
• Preview a release (dry-run):
  • Locally: npx semantic-release --dry-run --no-ci
  • Locally (major allowed): WORKRAIL_ALLOW_MAJOR_RELEASE=true npx semantic-release --dry-run --no-ci
• In Actions: run the Release (dry-run) workflow (.github/workflows/release-dry-run.yml).
• Full release policy: see docs/reference/releases.md

---

Included Workflows

30+ workflows included for development, debugging, review, documentation, and more:

Workflow	When to Use
coding-task-workflow-agentic	Feature development with notes-first durability and audit loops
bug-investigation-agentic	Systematic debugging with evidence-based analysis
mr-review-workflow-agentic	Code review with parallel reviewer families
wr.discovery	Upstream exploration, framing, and design synthesis
document-creation-workflow	Technical documentation with structure

Workflows adapt to complexity - simple tasks get fast-tracked, complex tasks get full rigor.

See all workflows →

---

The Philosophy

Guardrails Enable Excellence

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.

Expert Knowledge, Codified

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.

Replacing the Human Guide

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."

WorkRail does this automatically. The workflow asks the questions a senior dev would ask, at the moments they'd ask them.

---

Create Your Own

Drop a JSON file in ~/.workrail/workflows/:

{
  "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."
    }
  ]
}

WorkRail discovers it automatically. This is a minimal example - workflows also support conditions, loops, validation criteria, and more.

Writing workflows → · Load from Git →

---

Documentation

• All Workflows – Full list with detailed descriptions
• Writing Workflows – Custom workflow creation guide
• Workflow Authoring Principles (v2) – Cross-workflow design rules and authoring principles
• Configuration – Git repos, environment variables, local paths
• Advanced Features – Loops, conditionals, validation
• Integrations
  • Claude Code Setup – Complete guide for Desktop & CLI
  • Firebender Setup – Firebender integration

---

GitHub · MIT License