@exaudeus/workrail 3.28.0 → 3.30.0

package/docs/implementation/README.md

@@ -0,0 +1,21 @@
+# Implementation Guides
+
+Use this directory for **live implementation guides**.
+
+Good fits:
+
+- testing guidance
+- security/performance/deployment guides
+- workflow development guides
+- practical how-to material for contributors
+
+Do **not** use this directory for:
+
+- roadmap history
+- superseded phase plans
+- product prioritization
+- durable architecture/design that should live in `docs/design/`
+
+## Notes
+
+- New planning or status docs should usually go to `docs/roadmap/`, `docs/tickets/`, or `docs/plans/` instead.

package/docs/integrations/claude-code.md

@@ -0,0 +1,300 @@
+# Claude Code Integration Guide
+
+This guide covers setting up WorkRail with Claude Code (both Desktop and CLI).
+
+## Quick Start
+
+### Claude Desktop App
+
+1. Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent location on your OS
+2. Add WorkRail to the `mcpServers` section:
+
+```json
+{
+  "mcpServers": {
+    "workrail": {
+      "command": "npx",
+      "args": ["-y", "@exaudeus/workrail"]
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop
+4. Verify by asking: "List available workflows"
+
+### Claude Code CLI
+
+#### Method 1: Using `claude mcp add` (Recommended)
+
+```bash
+# Navigate to your project
+cd /path/to/your/project
+
+# Add WorkRail MCP server
+claude mcp add workrail npx -y @exaudeus/workrail
+```
+
+This creates/updates `.claude.json` in your project root.
+
+#### Method 2: Manual Configuration
+
+Edit or create `.claude.json` in your project root:
+
+```json
+{
+  "projects": {
+    "/absolute/path/to/your/project": {
+      "mcpServers": {
+        "workrail": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "@exaudeus/workrail"],
+          "env": {}
+        }
+      }
+    }
+  }
+}
+```
+
+**Important:** The path must be absolute and match your actual project directory.
+
+---
+
+## Custom Workflow Configuration
+
+To use custom workflows, add environment variables:
+
+```json
+{
+  "projects": {
+    "/path/to/your/project": {
+      "mcpServers": {
+        "workrail": {
+          "type": "stdio",
+          "command": "npx",
+          "args": ["-y", "@exaudeus/workrail"],
+          "env": {
+            "WORKFLOW_STORAGE_PATH": "/path/to/custom/workflows",
+            "WORKFLOW_GIT_REPOS": "https://github.com/your-org/workflows.git",
+            "GITHUB_TOKEN": "ghp_your_token_here"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## workrail-executor Agent
+
+The `workrail-executor` agent enables delegating workflow execution to subagents, allowing parallel context gathering and multi-agent workflows.
+
+### Setup
+
+Create `~/.claude/agents/workrail-executor.md`:
+
+```markdown
+---
+name: workrail-executor
+description: Executes WorkRail workflows step by step using the WorkRail MCP tools. Use when the user wants to run a workflow, follow a structured process, or resume a previous workflow session. Handles start, continue, and checkpoint operations, interpreting each step's instructions faithfully and advancing only when the step is complete.
+tools: Bash, Read, Write, Edit, mcp__workrail__list_workflows, mcp__workrail__inspect_workflow, mcp__workrail__start_workflow, mcp__workrail__continue_workflow, mcp__workrail__checkpoint_workflow, mcp__workrail__resume_session, mcp__workrail__create_session, mcp__workrail__update_session, mcp__workrail__read_session, mcp__workrail__open_dashboard
+---
+
+You are the WorkRail executor. Your job is to faithfully follow WorkRail workflow steps one at a time.
+
+## Core responsibilities
+
+- Use `mcp__workrail__start_workflow` to begin a workflow by name or ID.
+- Use `mcp__workrail__continue_workflow` with a `continueToken` to advance after completing a step.
+- Use `mcp__workrail__checkpoint_workflow` to save progress and return a resume token when asked or when ending a session.
+- Use `mcp__workrail__list_workflows` to show available workflows.
+- Use `mcp__workrail__inspect_workflow` to preview a workflow's steps before starting.
+
+## Execution rules
+
+1. **Read each step carefully.** The step prompt is your instruction. Execute it fully before advancing.
+2. **Do not skip steps.** Every step must be completed in order.
+3. **Provide required notes.** Steps that require notes must receive substantive notes before you call `continue_workflow`. Pass them via the `output.notesMarkdown` parameter.
+4. **Advance only when done.** Call `continue_workflow` only after the step's work is complete.
+5. **Checkpoint on request.** If the user asks to pause or save progress, call `mcp__workrail__checkpoint_workflow` and share the resume token.
+6. **Report clearly.** After each step, briefly summarize what was done before moving on.
+
+## Token handling
+
+- `continueToken` (`ct_` prefix) — use with `continue_workflow` to advance.
+- `checkpointToken` / `resumeToken` (`cp_` or `st_` prefix) — use with `checkpoint_workflow` or `continue_workflow` to save/rehydrate.
+- Never mix token types.
+
+## Workflow complete
+
+When the workflow returns `isComplete: true`, summarize all work done across the workflow and confirm completion to the user.
+```
+
+### Usage
+
+Once configured, spawn workrail-executor agents in workflows:
+
+```python
+# In Python (or equivalent in your language)
+agent = Agent(
+    subagent_type="workrail-executor",
+    description="Execute context gathering",
+    prompt="""
+    Start the routine-context-gathering workflow.
+
+    Workspace: /path/to/project
+    Focus: COMPLETENESS
+    Context: ...
+    """
+)
+```
+
+Or from the main agent in Claude Code:
+
+```
+Please use the workrail-executor agent to run the bug-investigation-agentic workflow
+```
+
+---
+
+## Troubleshooting
+
+### WorkRail tools not available
+
+**Symptoms:** Claude doesn't recognize workflow commands or says workrail tools aren't available.
+
+**Solutions:**
+
+1. **Desktop App:** Restart Claude Desktop completely (Quit, not just close window)
+2. **CLI:** Exit and start a new session - MCP servers load at startup, not mid-session
+3. **Verify config:**
+   ```bash
+   # For CLI
+   cat .claude.json | jq '.projects[].mcpServers.workrail'
+
+   # For Desktop
+   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq '.mcpServers.workrail'
+   ```
+
+### Agent can't access workrail tools
+
+**Symptoms:** workrail-executor agent reports "I don't have access to WorkRail workflow tools"
+
+**Common causes:**
+
+1. **Wrong tool names in agent config** - Tool names must match exactly:
+   - Correct: `mcp__workrail__start_workflow`
+   - Wrong: `mcp_workrail_start_workflow` (missing double underscores)
+   - Wrong: `mcp__workrail__mcp_workrail_start_workflow` (doubled prefix)
+
+2. **Agent config not reloaded** - After editing `~/.claude/agents/workrail-executor.md`, start a fresh session
+
+3. **MCP server not running** - Ensure workrail MCP is configured and loaded (see "WorkRail tools not available" above)
+
+### Workflows not found
+
+```bash
+# Check what WorkRail sees
+npx @exaudeus/workrail list
+
+# Verify custom paths
+ls -la ~/.workrail/workflows/
+
+# Check environment variables
+echo $WORKFLOW_STORAGE_PATH
+```
+
+### Git repository authentication fails
+
+```bash
+# Test GitHub token
+curl -H "Authorization: token $GITHUB_TOKEN" \
+  https://api.github.com/user
+
+# Test repo access
+git ls-remote https://github.com/your-org/workflows.git
+```
+
+---
+
+## Advanced Configuration
+
+### Per-Project Workflows
+
+Use project-local workflows that override bundled ones:
+
+```bash
+cd /path/to/your/project
+mkdir -p workflows
+# Add your .json workflow files
+```
+
+WorkRail auto-discovers `./workflows/` in the current directory.
+
+### Multiple Git Repositories
+
+```json
+{
+  "env": {
+    "WORKFLOW_GIT_REPOS": "https://github.com/team-a/workflows.git,https://github.com/team-b/workflows.git"
+  }
+}
+```
+
+Later repositories override earlier ones with the same workflow ID.
+
+### Disable Bundled Workflows
+
+```json
+{
+  "env": {
+    "WORKFLOW_INCLUDE_BUNDLED": "false"
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Version control your agent configs** - Check `~/.claude/agents/` into a dotfiles repo
+2. **Use project-specific `.claude.json`** - Different projects can have different workflow configs
+3. **Enable session tools for debugging** - Set `WORKRAIL_ENABLE_SESSION_TOOLS=true` to use dashboard and session inspection
+4. **Create team-specific workflows** - Host in a shared Git repo and reference via `WORKFLOW_GIT_REPOS`
+
+---
+
+## Examples
+
+### Running a workflow directly
+
+```
+> Use the bug-investigation-agentic workflow to investigate the cache expiration issue
+```
+
+### Delegating to workrail-executor
+
+```
+> Spawn two workrail-executor agents in parallel:
+> 1. One running routine-context-gathering with focus=COMPLETENESS
+> 2. One running routine-context-gathering with focus=DEPTH
+```
+
+### Resuming a checkpointed workflow
+
+```
+> Resume the workflow session using token: st_abc123...
+```
+
+---
+
+## See Also
+
+- [Configuration Reference](../configuration.md)
+- [Writing Workflows](../authoring.md)
+- [All Available Workflows](../workflows.md)
+- [Firebender Integration](./firebender.md)

package/docs/integrations/firebender.md

@@ -0,0 +1,315 @@
+# Firebender Integration Guide
+
+## Overview
+Firebender is an Agentic IDE that supports multiple subagents. WorkRail works with Firebender in two modes: **Delegation** (Gold) and **Proxy** (Silver).
+
+## Configuration Rules
+
+Firebender has a specific behavior regarding Tool Access that you must understand to enable **Delegation Mode**.
+
+### The "Inheritance" Rule (Recommended)
+If you define a subagent **without** a `tools` configuration block, it inherits **ALL** tools from the main agent, including WorkRail.
+
+** Recommended Config (Tier 3 Enabled):**
+```json
+{
+  "subagents": {
+    "researcher": {
+      "systemPrompt": "You are a Researcher...",
+      // No "tools" block -> Inherits everything!
+    }
+  }
+}
+```
+
+### The "Whitelist" Pitfall
+If you define a `tools` block (even if empty), the subagent loses access to everything except what is listed.
+
+** Broken Config (Tier 2 Only):**
+```json
+{
+  "subagents": {
+    "researcher": {
+      "systemPrompt": "...",
+      "tools": ["read_file", "grep"] // Missing WorkRail tools!
+    }
+  }
+}
+```
+
+** Fixed Whitelist Config:**
+If you MUST whitelist tools, you must explicitly add the WorkRail suite:
+```json
+{
+  "subagents": {
+    "researcher": {
+      "systemPrompt": "...",
+      "tools": [
+        "read_file", 
+        "grep",
+        "list_workflows",
+        "start_workflow",
+        "continue_workflow",
+        "checkpoint_workflow"
+      ]
+    }
+  }
+}
+```
+
+## Step-by-Step Setup
+
+### 1. Install WorkRail Subagent Config
+
+Copy the universal WorkRail executor to your Firebender agents directory:
+
+```bash
+# Copy the universal executor
+cp assets/agent-configs/firebender/workrail-executor.md ~/.firebender/agents/
+
+# Legacy: Individual subagent configs (deprecated in favor of universal executor)
+# cp assets/agent-configs/firebender/*.md ~/.firebender/agents/
+```
+
+### 2. Register Subagent in Firebender
+
+Edit your `~/.firebender/firebender.json` (or project-specific `firebender.json`):
+
+```json
+{
+  "subagents": [
+    "~/.firebender/agents/workrail-executor.md"
+  ]
+}
+```
+
+**Important:** The subagent config uses **tool inheritance** (no `tools` field), so it will automatically have access to all tools including WorkRail.
+
+### 3. Agentic Workflows Are Enabled by Default
+
+`.agentic.json` workflow variants and routines now ship enabled by default in WorkRail.
+
+If you need to disable them temporarily, set:
+
+```bash
+export WORKRAIL_ENABLE_AGENTIC_ROUTINES=false
+```
+
+### 4. Verify Your Setup
+
+Run the diagnostic workflow to test your configuration:
+
+```bash
+# In Firebender, ask the main agent:
+"Run the workflow-diagnose-environment workflow"
+```
+
+This will:
+- Check if the WorkRail executor is available
+- Probe if the executor has WorkRail tool access
+- Report your tier (Solo, Proxy, or Delegate)
+
+### 5. Test with a Simple Delegation
+
+Try delegating a simple task to verify everything works:
+
+```
+"Delegate to the WorkRail Executor:
+
+Execute the 'Context Gathering Routine' workflow at depth=1.
+
+Work Package:
+MISSION: Map the structure of the src/auth directory
+TARGET: src/auth/
+CONTEXT: I need to understand how authentication works
+DELIVERABLE: context-map.md"
+```
+
+If the WorkRail Executor can execute the routine and return a structured deliverable, you're in **Tier 3 (Delegation Mode)** 
+
+---
+
+## Usage Patterns
+
+### **Pattern 1: Explicit Delegation**
+
+Use the `task` tool to explicitly delegate to the WorkRail executor:
+
+```
+task(subagent_type="workrail-executor", prompt="
+  Execute the 'Context Gathering Routine' workflow at depth=2.
+  
+  Work Package:
+  MISSION: Understand how user authentication works in this codebase
+  TARGET: src/auth/
+  CONTEXT: 
+    - Bug: Valid tokens rejected in production
+    - Previous Finding: AuthService identified as likely location
+  DELIVERABLE: context-map.md with component structure and execution flow
+")
+```
+
+The WorkRail Executor will:
+1. Load the `Context Gathering Routine` workflow
+2. Execute it autonomously at depth=2
+3. Return `context-map.md` with findings
+
+### **Pattern 2: Main Agent Instruction**
+
+You can also instruct the main agent to delegate for you:
+
+```
+"Please delegate context gathering to the WorkRail Executor.
+
+Execute the 'Context Gathering Routine' at depth=2 (Explore level).
+
+Mission: Understand the authentication system
+Target: src/auth/
+Context: Investigating token validation bug
+Deliverable: context-map.md"
+```
+
+The main agent will format the delegation and call the WorkRail Executor.
+
+### **Pattern 3: Workflow-Driven Delegation**
+
+Agentic workflows (`.agentic.json`) include delegation instructions in their prompts:
+
+```
+"Start the bug-investigation workflow"
+```
+
+The workflow will guide the main agent through strategic delegation points, with prompts like:
+
+```
+"Execute the 'Context Gathering Routine' workflow at depth=2.
+
+Work Package:
+MISSION: [extracted from context]
+TARGET: [identified files/areas]
+..."
+```
+
+The main agent reads these instructions and delegates to the WorkRail Executor accordingly.
+
+### **Pattern 4: Parallel Delegation**
+
+For THOROUGH mode workflows, delegate to multiple executors simultaneously:
+
+```
+# Spawn 3 WorkRail Executors in parallel:
+
+Executor 1: Execute 'Ideation Routine' with perspective=logic-errors
+Executor 2: Execute 'Ideation Routine' with perspective=data-state
+Executor 3: Execute 'Ideation Routine' with perspective=integration
+
+# Then synthesize all deliverables
+```
+
+Each executor works independently, exploring different solution spaces.
+
+---
+
+## Troubleshooting
+
+### **"WorkRail Executor can't find workflow_list"**
+
+**Cause:** Subagent has a `tools` whitelist that excludes WorkRail tools.
+
+**Fix:** Either:
+- Remove the `tools` field entirely from the YAML frontmatter (use inheritance)
+- Or add WorkRail tools to the whitelist: `list_workflows`, `start_workflow`, `continue_workflow`, `checkpoint_workflow`
+
+The provided `workrail-executor.md` uses inheritance (no `tools` field), so this shouldn't happen unless you modified it.
+
+### **"WorkRail Executor returns incomplete results"**
+
+**Cause:** Insufficient context in delegation prompt.
+
+**Fix:** Provide a complete work package:
+- **Workflow**: Which routine to execute (by name)
+- **Parameters**: Workflow-specific params (depth, rigor, perspective, etc.)
+- **Mission**: What to accomplish
+- **Target**: What to analyze (files, directories, code areas)
+- **Context**: Background, constraints, prior work
+- **Deliverable**: What artifact to create and what format
+
+### **"How do I know which workflow to use?"**
+
+**Guide:**
+- **Context Gathering Routine**: "I need to understand how X works"
+- **Hypothesis Challenge Routine**: "Challenge my assumptions about Y"
+- **Plan Analysis Routine**: "Review this implementation plan"
+- **Execution Simulation Routine**: "Trace what happens when I call X with Y"
+- **Ideation Routine**: "Generate multiple approaches to solve X"
+- **Feature Implementation Routine**: "Implement this feature according to the plan"
+
+The WorkRail Executor can execute any of these - the workflow defines its behavior.
+
+### **"Can I use auto-invocation instead of explicit delegation?"**
+
+**Answer:** Yes, Firebender can auto-invoke subagents based on task matching (using the `description` field in the YAML frontmatter). However, **explicit delegation is recommended** for predictability and control, especially for workflows with parameters (depth, rigor, etc.).
+
+---
+
+## Advanced Configuration
+
+### **Per-Project Subagents**
+
+You can have project-specific subagent configs:
+
+```bash
+# Create project-specific agents directory
+mkdir .firebender/agents/
+
+# Copy and customize subagents
+cp ~/.firebender/agents/context-researcher.md .firebender/agents/
+
+# Register in project firebender.json
+{
+  "subagents": [
+    ".firebender/agents/context-researcher.md"
+  ]
+}
+```
+
+### **Custom Subagents**
+
+To create a custom subagent:
+
+1. Copy an existing subagent as a template
+2. Modify the YAML frontmatter:
+   ```yaml
+   ---
+   name: my-custom-agent
+   description: "My custom agent description"
+   tools:  # Optional, omit to inherit all tools
+     - read_file
+     - grep_search
+   model: claude-sonnet-4
+   ---
+   ```
+3. Update the system prompt to define the cognitive function
+4. Register in `firebender.json`
+
+### **Model Selection**
+
+Choose models based on task complexity:
+
+```yaml
+---
+name: context-researcher
+model: claude-haiku-4  # Fast, cheap (for depth 0-1)
+# OR
+model: claude-sonnet-4  # Powerful (for depth 2+)
+---
+```
+
+---
+
+## Verifying Your Setup
+
+Run the Diagnostic Workflow to test your configuration:
+1. Start a chat with the Main Agent.
+2. Ask: "Run the environment diagnostic workflow."
+3. Follow the steps to probe your subagent's capabilities.