Skip to content

docs(site): add .engineering deploy step to Getting started #222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
m2ux merged 1 commit into from
Jul 12, 2026
Merged

docs(site): add .engineering deploy step to Getting started #222

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions site/guide/getting-started.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Getting started — Workflow Server</title>
<meta name="description" content="Install the workflow-server, connect an MCP client, add the bootstrap rule, and run your first workflow.">
<meta name="description" content="Install the workflow-server, deploy .engineering to your project, connect an MCP client, add the bootstrap rule, and run your first workflow.">
<link rel="stylesheet" href="../style.css">
</head>
<body>
Expand Down Expand Up @@ -67,7 +67,7 @@

<main id="main">
<h1>Getting started</h1>
<p class="lede prose">Install the server, connect your MCP client, add the bootstrap rule, and run workflows in natural language. You need <strong>Node.js 18+</strong> and an MCP client (Cursor, Claude Desktop, Claude Code, or similar). For how the client, server, and workspace fit together, see <a href="../index.html#pieces">The pieces</a> on the home page.</p>
<p class="lede prose">Install the server, set up <code>.engineering</code> in your project, connect your MCP client, add the bootstrap rule, and run workflows in natural language. You need <strong>Node.js 18+</strong> and an MCP client (Cursor, Claude Desktop, Claude Code, or similar). For how the client, server, and workspace fit together, see <a href="../index.html#pieces">The pieces</a> on the home page.</p>

<h2 id="install">1. Install and build</h2>
<pre><code># Clone and install
Expand All @@ -91,7 +91,14 @@ <h2 id="install">1. Install and build</h2>
</ul>
</aside>

<h2 id="configure">2. Configure your MCP client</h2>
<h2 id="deploy">2. Deploy <code>.engineering</code> to your project</h2>
<p class="prose">Session state lives under your project’s <code>.engineering/artifacts/planning/</code> tree. From the <strong>root of the project</strong> you will use as your workspace — not the workflow-server clone — run:</p>
<pre><code>curl -O https://raw.githubusercontent.com/m2ux/workflow-server/main/scripts/deploy.sh
chmod +x deploy.sh
./deploy.sh</code></pre>
<p class="prose">The script creates <code>.engineering/</code> with the artifact directories and workflow submodules the server expects. Commit the submodule entry when it finishes. For deploy modes, options, and updating submodules, see <a href="https://github.com/m2ux/workflow-server/blob/main/SETUP.md#deploying-to-projects">SETUP.md (source)</a>.</p>

<h2 id="configure">3. Configure your MCP client</h2>
<p>Register the server in your client's MCP configuration. For Cursor this is <code>~/.cursor/mcp.json</code>; for Claude Desktop it is <code>claude_desktop_config.json</code> (macOS: <code>~/Library/Application Support/Claude/</code>, Windows: <code>%APPDATA%\Claude\</code>).</p>
<pre><code>{
"mcpServers": {
Expand All @@ -105,7 +112,7 @@ <h2 id="configure">2. Configure your MCP client</h2>
}
}
}</code></pre>
<p><code>WORKFLOW_WORKSPACE</code> points at the project the server manages sessions for — the repository whose <code>.engineering/artifacts/planning/</code> folder holds session state. It is required: the server refuses to start without a workspace (you can pass <code>--workspace=PATH</code> as a command-line argument instead). Restart your MCP client after editing the configuration.</p>
<p>Set <code>WORKFLOW_WORKSPACE</code> to the project root from <a href="#deploy">step 2</a>. It points at the repository whose <code>.engineering/artifacts/planning/</code> folder holds session state. It is required: the server refuses to start without a workspace (you can pass <code>--workspace=PATH</code> as a command-line argument instead). Restart your MCP client after editing the configuration.</p>

<div class="table-wrap">
<table>
Expand All @@ -120,20 +127,20 @@ <h2 id="configure">2. Configure your MCP client</h2>
</table>
</div>

<h2 id="bootstrap-rule">3. Add the bootstrap rule</h2>
<h2 id="bootstrap-rule">4. Add the bootstrap rule</h2>
<p>Add this to your IDE's always-applied rule set (a Cursor rule, a Claude Code project rule, or the equivalent in your client):</p>
<pre><code>For any start workflow, create work package, or resume work package request, call the `discover` tool on the workflow-server MCP server to learn the bootstrap procedure. Complete the procedure before any other action.

If the user provides a `session_token`, pass it to subsequent workflow-server calls per their instructions.</code></pre>
<p class="prose">Restart your MCP client after adding the rule.</p>

<h2 id="verify">4. Verify</h2>
<h2 id="verify">5. Verify</h2>
<p>Ask your agent:</p>
<pre><code>Use the workflow server to list available workflows</code></pre>
<p>The agent should call <a href="../api/tools.html#list_workflows"><code>list_workflows</code></a> and return the workflow inventory.</p>
<p>Then ask it to <em>start a work-package workflow</em>. It should call <code>discover</code> first, then proceed through <code>list_workflows</code>, <code>start_session</code>, and <code>get_workflow</code>. If it skips <code>discover</code>, the rule is not applied — recheck your IDE rule configuration.</p>

<h2 id="run">5. Run and resume</h2>
<h2 id="run">6. Run and resume</h2>
<p class="prose">Drive workflows in natural language — no tool names, no tokens to copy. A <strong>work package</strong> is the bundled workflow for planning and implementing one unit of work (for example a feature or issue).</p>
<p><strong>Start</strong> a workflow by naming the goal:</p>
<pre><code>Start a new work-package workflow for implementing user authentication</code></pre>
Expand All @@ -147,7 +154,6 @@ <h2 id="run">5. Run and resume</h2>
<h2 id="next">Next steps</h2>
<ul class="prose">
<li><a href="./definitions.html">Browse the definitions</a> — a glossary of terms you will encounter across the docs and in workflow runs.</li>
<li>Deploying the <code>.engineering/</code> pattern into your own project is covered in <a href="https://github.com/m2ux/workflow-server/blob/main/SETUP.md">SETUP.md (source)</a>.</li>
</ul>
</main>

Expand Down
3 changes: 2 additions & 1 deletion site/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,8 @@ <h2 id="docs-map-h">Where to start</h2>
<tbody>
<tr><td>I am new — where do I begin?</td><td><a href="guide/getting-started.html">Getting started</a> → <a href="guide/definitions.html">Definitions</a></td></tr>
<tr><td>What is this project?</td><td><a href="#pieces">The pieces</a> on this page or <a href="https://github.com/m2ux/workflow-server/blob/main/README.md">README (source)</a></td></tr>
<tr><td>How do I install and connect the server?</td><td><a href="guide/getting-started.html">Getting started</a> and <a href="https://github.com/m2ux/workflow-server/blob/main/SETUP.md">SETUP (source)</a></td></tr>
<tr><td>How do I install and connect the server?</td><td><a href="guide/getting-started.html">Getting started</a></td></tr>
<tr><td>How do I deploy <code>.engineering</code> to my project?</td><td><a href="guide/getting-started.html#deploy">Getting started</a> — step 2</td></tr>
<tr><td>How do I wire the IDE bootstrap rule?</td><td><a href="guide/getting-started.html#bootstrap-rule">Getting started</a></td></tr>
<tr><td>How do I run or resume a workflow?</td><td><a href="guide/getting-started.html#run">Getting started</a> — example phrases</td></tr>
<tr><td>What are workflows, sessions, and checkpoints?</td><td><a href="guide/definitions.html">Definitions</a> · <a href="specs/checkpoints.html">Checkpoints</a></td></tr>
Expand Down
Loading