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

Install layout (defaults)

Preferred paths (see install-projects-worktrees.md):

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/main/scripts/install.sh | bash
~/.local/share/workflow-server/start.sh -d

Creates the install layout, clones workflows, writes $INSTALL/env, and starts the GHCR image. Verify and MCP client steps: http.md.

stdio (quick)

git clone https://github.com/m2ux/workflow-server.git
cd workflow-server
npm install
git worktree add ./workflows workflows
npm run build
# optional host layout (without Docker):
./scripts/install.sh --install-dir=~/.local/share/workflow-server

Point the IDE MCP config at dist/index.js with --install-dir and --workflow-dir. Full client snippet and verify: stdio.md.

2. Init a target repo

Two steps per product repo: deploy engineering into the repo, then check it out under $HOST_PROJECTS_ROOT.

2a. Deploy engineering

From the root of the target project (not the workflow-server checkout):

curl -fsSL -o deploy.sh \
  https://raw.githubusercontent.com/m2ux/workflow-server/main/scripts/deploy.sh
chmod +x deploy.sh && ./deploy.sh

This sets up engineering storage (layout, branch/submodule, planning structure). Patterns (same-repo orphan, shared engineering monorepo, in-branch): docs/engineering-storage.md. Flags: ./deploy.sh --help.

2b. Checkout the project

# HOST_PROJECTS_ROOT from $INSTALL/env (default: ~/projects/dev)
git clone https://github.com/owner/repo.git "$HOST_PROJECTS_ROOT/<repo>"
mkdir -p "$HOST_PROJECTS_ROOT/<repo>/.worktrees"

Use the repo basename for <repo>. Layout: checkout = $HOST_PROJECTS_ROOT/<repo>, planning under checkout/.engineering/…, feature worktrees under checkout/.worktrees/<slug>/. Full detail: setup.md §2b · install-projects-worktrees.md. Repeat 2a → 2b for each product repo.

3. Setup Cursor workspace

Recommended: deploy examples/cursor-workspace with scripts/deploy-cursor-workspace.sh. That installs the kickoff layout under ~/.local/share/cursor/workspaces/<name>/ with absolute $HOME/… multi-root paths (no HOST_PROJECTS_ROOT required when opening Cursor), required MCP servers (concept-rag, atlassian, gitnexus, workflow-server), always-applied bootstrap rules, AGENTS.md / CLAUDE.md, and a workspace-local Claude Code baseline (scripts/claude/ hooks + generated .claude/settings.json).

# after install.sh (preferred) or from a workflow-server checkout
# ($HOME must be set; needs python3)
~/.local/share/workflow-server/deploy-cursor-workspace.sh workflow-server
# or: ./scripts/deploy-cursor-workspace.sh workflow-server
# refresh MCP, rules, Claude hooks/settings (keeps extra MCP servers): --force
# preview: --dry-run   ·   open Cursor after deploy: --open
# full flags: ./scripts/deploy-cursor-workspace.sh --help
cursor ~/.local/share/cursor/workspaces/workflow-server/workflow-server.code-workspace

REPO_NAME (or --repo=NAME) is required — basename only, not owner/repo. Other flags: --home=$HOME, --projects-root=$HOME/projects/dev, --mcp-url=…, --force, --dry-run, --open. No args prints help. install.sh also installs scripts/claude/ next to the template so deploy works without a full checkout. Full CLI table and Claude baseline detail: examples/cursor-workspace/README.md · setup.md §3 · docs/ide-setup.md.

Do not treat hand-rolled MCP JSON or pasting bootstrap rules as the primary path. Transports: http.md · stdio.md.

The example workspace already loads the discover-first bootstrap rule. Reference text and verify steps live in docs/ide-setup.md.

4. Verify

Transport-specific health checks:

• HTTP — /health, /ready (require sessionKeyWritable: true), container logs (http.md §4).
• stdio — build/paths, MCP spawn without errors (stdio.md §3).

Primary MCP smoke: from the example workspace, ask the agent to start a work-package (or any) workflow. It must call discover first, then start_session with repo: "owner/repo", and return a session_index. list_workflows alone is not enough. If the agent skips discover, the bootstrap rule is not loaded — see docs/ide-setup.md.

5. Run and resume

Drive workflows in natural language — no tool names, no tokens to copy. A work package is the bundled workflow for planning and implementing one unit of work (for example a feature or issue).

Start a workflow by naming the goal:

Start a new work-package workflow for implementing user authentication

Begin a work-package workflow for issue #42

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

Resume the work-package workflow we were working on

Continue the authentication work package from where we left off

Finish or wind one down:

End the current work-package workflow

Update workflows

Same operations as setup.md §4 (Update Workflows). The anchor #day-two is stable for existing links.

$INSTALL/update-workflows.sh   # refresh workflows branch; restart HTTP if running
$INSTALL/stop.sh               # stop HTTP container

Next steps

• Browse the definitions — glossary of terms across the docs and workflow runs.
• Artifact isolation — workspace vs engineering roots and planning folders.
• Engineering storage patterns — orphan, shared monorepo, in-branch.