Workflow Server

Getting started

Install the server, prepare a target repo, adopt the example Cursor workspace, and run workflows in natural language. Canonical operator guide: setup.md. Transport details: http.md · stdio.md.

1. Choose a transport

PathWhenGuide
Docker / HTTP GHCR image; no server source checkout http.md
stdio Local checkout; IDE spawns node dist/index.js stdio.md

Install layout (defaults)

Preferred paths (see the workspace README):

PathDefaultPurpose
Install dir~/.local/share/workflow-serverHelper scripts, env, state/, default corpus checkout
Projects root$HOST_PROJECTS_ROOT (default ~/projects/dev)Product checkouts by basename
Checkout$HOST_PROJECTS_ROOT/<repo>/Source / repo_root
Planning$HOST_PROJECTS_ROOT/<repo>/.engineering/…Planning / sessions
Feature worktrees$HOST_PROJECTS_ROOT/<repo>/.worktrees/<slug>/Per-work-package trees
Corpus$INSTALL/workflowsDefault --workflow-dir; products under corpus/

Install (host), deploy (into the product repo), and checkout under $HOST_PROJECTS_ROOT/<repo> are different operations — see setup.md.

Docker / HTTP (quick)

curl -fsSL https://raw.githubusercontent.com/m2ux/workflow-server/docker/scripts/install.sh | bash
~/.local/share/workflow-server/start.sh -d

Creates the install layout, places a corpus at $INSTALL/workflows (or --workflows-dir), writes $INSTALL/env, and starts the GHCR image. --corpus-branch and --repo-url select which tree to clone; those values are what start.sh refreshes. Verify and MCP client steps: http.md.

stdio (quick)

git clone https://github.com/m2ux/workflow-server.git
cd workflow-server
npm ci
# corpus at --workflow-dir (default .worktrees/workflows)
git worktree add .worktrees/workflows workflows
npm run build

The server reads any corpus at --workflow-dir (default .worktrees/workflows of the primary checkout). Product definitions live under corpus/ of that tree. Point the IDE MCP config at dist/index.js with --workspace=PATH (one checkout, or a projects root holding several) or --repo=owner/repo; --install-dir alone is not a binding, and the process exits. Full client snippet and verify: stdio.md.

2. Initialise the workspace

Follow the setup instructions in the workspace README: it checks out the template workspace, forks it, deploys the engineering branch, and adds each project component the agents work on.

3. Setup Cursor workspace

The kickoff workspace lives on the workspace branch. The workspace README covers its rules, including the bootstrap rule, and the workspace roots. Transports: http.md · stdio.md.

The discover-first bootstrap rule is part of that IDE setup.

4. Verify

Transport-specific health checks:

Primary MCP smoke: from the example workspace, ask the agent to start any workflow. It must call discover first, then start_session with working_directory set to the absolute path of the checkout under work (the server derives owner/repo from its origin), and return a session_index. list_workflows alone is not enough. If the agent skips discover, the bootstrap rule is not loaded — see the workspace README.

5. Run and resume

Drive workflows in natural language — no tool names, no tokens to copy. The examples name an invented feature-delivery workflow; name one your corpus offers.

Start a workflow by naming the goal:

Start a new feature-delivery workflow for implementing user authentication
Begin a feature-delivery workflow for issue #42

Resume one — sessions live on disk, so this works across restarts and even across chat conversations:

Resume the feature-delivery workflow we were working on
Continue the authentication work from where we left off

Finish or wind one down:

End the current feature-delivery workflow

Next steps