@programinglive/dev-workflow-mcp-server 1.1.7 → 1.1.16

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,47 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Publish package
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          registry-url: https://registry.npmjs.org
+          scope: "@programinglive"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Verify tag matches package version
+        run: |
+          EXPECTED_TAG="${GITHUB_REF#refs/tags/}"
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          if [ "v${PACKAGE_VERSION}" != "${EXPECTED_TAG}" ]; then
+            echo "Package version ${PACKAGE_VERSION} does not match tag ${EXPECTED_TAG}"
+            exit 1
+          fi
+
+      - name: Publish to npm
+        run: npm publish --provenance

package/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.1.16](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.15...v1.1.16) (2025-10-31)
+
+
+### 🧹 Chores
+
+* align npm provenance metadata ([459572e](https://github.com/programinglive/dev-workflow-mcp-server/commit/459572e07efa340ef87cc679535fb24413d8c997))
+
+### [1.1.15](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.14...v1.1.15) (2025-10-31)
+
+
+### 📝 Documentation
+
+* add npm publish workflow automation ([c923734](https://github.com/programinglive/dev-workflow-mcp-server/commit/c923734ab4399afbcb0166abcd16cd01c3e50c0e))
+
+
+### 👷 Continuous Integration
+
+* **npm:** build + provenance in npm-publish workflow ([5ae04db](https://github.com/programinglive/dev-workflow-mcp-server/commit/5ae04db33e33fe64c33d8eac08db70e98754ea64))
+
+### [1.1.14](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.13...v1.1.14) (2025-10-31)
+
+
+### 🐛 Bug Fixes
+
+* improve workflow state project root resolution ([a575e24](https://github.com/programinglive/dev-workflow-mcp-server/commit/a575e2404d26e550c8e52e4a524a75a3fa64752d))
+
+### [1.1.13](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.12...v1.1.13) (2025-10-30)
+
+### [1.1.12](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.11...v1.1.12) (2025-10-30)
+
+
+### ✨ Features
+
+* **cli:** add 'call' subcommand to invoke MCP tools directly (e.g., node index.js call drop_task) ([c9b8fae](https://github.com/programinglive/dev-workflow-mcp-server/commit/c9b8fae7e24e0915d857135d03fa969b10dcac67))
+* **web:** docs modal, docs API, navbar redesign ([902242b](https://github.com/programinglive/dev-workflow-mcp-server/commit/902242b1318b01f8f62ef7c4c0f6347cb8517617))
+* **web:** embed docs modal and redesign dashboard ([d2cf2fb](https://github.com/programinglive/dev-workflow-mcp-server/commit/d2cf2fb4ae90e61b20c72ed26f25dc0e5119247a))
+
+### [1.1.11](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.10...v1.1.11) (2025-10-30)
+
+
+### 🧹 Chores
+
+* verify run_full_workflow with persisted project summary ([6fdb475](https://github.com/programinglive/dev-workflow-mcp-server/commit/6fdb475f65ee6ef2c061b0b1cf954a282406e2a1))
+
+
+### ✨ Features
+
+* add per-user state, SQLite project summary, and dashboard ([7b57b6e](https://github.com/programinglive/dev-workflow-mcp-server/commit/7b57b6e067ad59f2999a2badcb51b1293192c96b))
+* per-project workflow state with unique per-user IDs; smarter workflow ([b710a52](https://github.com/programinglive/dev-workflow-mcp-server/commit/b710a524997583f58cd6da2567ba9fd14abdd3c9))
+
+### [1.1.10](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.9...v1.1.10) (2025-10-29)
+
+
+### ✨ Features
+
+* add project knowledge library with persisted summary file for future database integration ([b9dc13f](https://github.com/programinglive/dev-workflow-mcp-server/commit/b9dc13f4b25dec756088a55185ccbfdb3988a644))
+
+### [1.1.9](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.8...v1.1.9) (2025-10-29)
+
+
+### 🧹 Chores
+
+* interim commit ([b1aead0](https://github.com/programinglive/dev-workflow-mcp-server/commit/b1aead05920c766a183988fb93d3f0edc3e1eafc))
+
+
+### ✅ Tests
+
+* update README.md, exec.js, package-lock.json +7 more ([894fdf1](https://github.com/programinglive/dev-workflow-mcp-server/commit/894fdf1eace33ddf0081c565028d214e1c7697bf))
+
+
+### ✨ Features
+
+* make run_full_workflow smart and resumable from current phase ([930eb3c](https://github.com/programinglive/dev-workflow-mcp-server/commit/930eb3cb84c241b14f0e194cf490313e1e99a7ce))
+
+### [1.1.8](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.7...v1.1.8) (2025-10-27)
+
+
+### 📝 Documentation
+
+* note DEV_WORKFLOW_STATE_FILE override ([bbeb11b](https://github.com/programinglive/dev-workflow-mcp-server/commit/bbeb11bc7f8be33f7c1a51b336283a3b2a48d3ea))
+
 ### [1.1.7](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.1.6...v1.1.7) (2025-10-26)
 
 

package/README.md

@@ -24,7 +24,7 @@ Each project gets its own isolated workflow state file.
 npm install @programinglive/dev-workflow-mcp-server
 ```
 
-This will automatically create a `.workflow-state.json` file in the **project where you ran `npm install`** (using npm's `INIT_CWD`), keeping workflow history separate per project. If you're installing the package itself (inside `node_modules`), the script skips creation so it never pollutes the shared package directory.
+This will automatically create a `.state/workflow-state.json` file in the **project where you ran `npm install`** (using npm's `INIT_CWD`), keeping workflow history separate per project. If you're installing the package itself (inside `node_modules`), the script skips creation so it never pollutes the shared package directory.
 
 ### Option 2: Install from Source
 
@@ -34,6 +34,31 @@ cd dev-workflow-mcp-server
 npm install
 ```
 
+> **Windows prerequisites:** Installing dependencies from source compiles native modules such as `better-sqlite3`. Make sure Python 3 (added to PATH) and the Visual Studio Build Tools “Desktop development with C++” workload are installed before running `npm install`. Without them, npm will fail with a “need python” or build error.
+
+### Option 3: Install on Plesk Hosting
+
+Plesk supports Node.js applications through its Node.js extension. To deploy the MCP server on a Plesk subscription:
+
+1. **Enable Node.js support** – Ensure the Plesk administrator has installed the Node.js extension and enabled SSH access for your subscription.
+2. **Upload the project** – Either clone the repository or upload an archive into the directory you will run it from (e.g., `httpdocs/dev-workflow-mcp-server`). From SSH you can run:
+   ```bash
+   cd httpdocs
+   git clone https://github.com/programinglive/dev-workflow-mcp-server.git
+   cd dev-workflow-mcp-server
+   ```
+3. **Install dependencies** – In Plesk’s **Node.js** panel use “NPM install” (or run `npm install --production` over SSH). Linux hosts already ship the Python/build toolchain required for `better-sqlite3`; if your plan uses a Windows host, install Python 3 and the Visual Studio Build Tools beforehand or ask your provider to enable them.
+4. **Define environment variables** – In the Node.js panel add any environment variables you need (for example `DEV_WORKFLOW_USER_ID` or `DEV_WORKFLOW_STATE_FILE`). This keeps state files outside the web root if desired.
+5. **Configure the application** – Set **Application startup file** to `index.js` and **Application mode** to `production`. Plesk will run the server with `node index.js`.
+6. **Start/Restart the app** – Click “Restart App” so Plesk launches the MCP server with the new configuration. When you update the code, rerun “NPM install” and restart.
+
+> **Tip:** The MCP server communicates over stdio. If you only need it as a CLI tool, you can also run `npx @programinglive/dev-workflow-mcp-server` directly in an SSH session without keeping it running under the Node.js panel.
+
+#### Two Usage Modes
+
+- **Local (source)**: Point your MCP client to `index.js`. This runs directly from source and requires no build step. Recommended for MCP usage.
+- **Production (built)**: Run `npm run build` once to generate `dist/`. This creates an optimized bundle but isn’t needed for MCP usage.
+
 ### 3. Configure in Windsurf/Claude Desktop
 
 Point your MCP client to the server entry point. Replace `<PROJECT_ROOT>` with the absolute path to this repository on your machine.
@@ -128,27 +153,128 @@ Point your MCP client to the server entry point. Replace `<PROJECT_ROOT>` with t
 
 After adding the configuration, restart the application to load the MCP server.
 
+## 🏗️ Build System
+
+This project includes a Vite-based build system for creating optimized distributions.
+
+### Scripts
+
+- `npm run build` - Bundle the source into `dist/index.mjs` for distribution
+- `npm run dev` - Run in development mode with file watching
+- `npm run local` - Alias for running from source (same as `npm start`)
+- `npm run web` - Launch the lightweight workflow dashboard for browsing task history (see [Web Dashboard docs](./docs/web-dashboard.md))
+
+#### `npm run web`
+
+This command starts the dashboard defined in `web/server.js`, giving you a quick view of workflow history and summary statistics.
+
+```bash
+npm run web
+# 🌐 Dev Workflow Dashboard running at http://localhost:3111
+```
+
+- **Default port:** 3111 (or the next free port if occupied). Override with `DEV_WORKFLOW_WEB_PORT`.
+- **Query parameter:** `?user=<id>` lets you inspect another user’s history (defaults to `default`).
+- **API endpoints:**
+  - `GET /api/summary?user=<id>` → overall stats for the user.
+  - `GET /api/history?user=<id>&page=1&pageSize=20&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD` → paginated task history.
+  - `GET /api/history-summary?user=<id>&frequency=daily|monthly|yearly` → aggregated counts over time.
+
+Open `http://localhost:3111` in a browser to view the dashboard UI (`web/index.html`).
+
+### Build Output
+
+Running `npm run build` generates:
+- `dist/index.mjs` - Optimized ES module bundle
+- Source maps and other build artifacts
+
+The build bundles all source files while externalizing Node.js built-in modules and dependencies, resulting in a single file distribution.
+
+### Usage
+
+For MCP server usage, point your client at `index.js` (source) to avoid stdio transport compatibility issues. The built `dist/index.mjs` is primarily for:
+- npm package distribution
+- Performance optimization
+- Embedding in other projects
+
 ## 📁 Project-Specific Workflow State
 
-When you install this package in a project, a `.workflow-state.json` file is automatically created in your project root. This file:
+When you install this package in a project, a `.state/workflow-state.json` file is automatically created in your project root. This file:
 
 - **Stores workflow history** specific to that project
 - **Tracks task progress** independently per project
 - **Should be gitignored** (already in `.gitignore` by default)
 - **Persists across sessions** so your workflow state is preserved
+- **Stays centralized** even if you run the server from nested build outputs like `dist/`. The MCP server walks back to the project root (looking for `.git` or `package.json`) before reading or writing workflow state, so you never need duplicate copies under build directories.
 
-Each project maintains its own isolated workflow history, so you can work on multiple projects without mixing their histories.
+Each project maintains its own isolated workflow history, so you can work on multiple projects without mixing their histories. Within that `.state` directory, the MCP server automatically creates a unique per-user subdirectory (e.g., `.state/users/user-abc123/`). The generated identifier persists locally so multiple developers sharing the same repository never clobber each other’s workflow files. If you prefer a specific name, set `DEV_WORKFLOW_USER_ID` before launching the server and that value will be used instead of the auto-generated ID.
 
 ### Adding to .gitignore
 
 If you're using this package, add this to your project's `.gitignore`:
 
 ```
-.workflow-state.json
+.state/
 ```
 
 This keeps workflow state local to each developer's machine.
 
+> **Need to override the location?** Set `DEV_WORKFLOW_STATE_FILE=/absolute/path/to/your/project/.state/workflow-state.json` before launching the server (or inside your MCP client config). The server will honor that path, letting you keep the package installed centrally while maintaining per-project workflow history.
+
+## 🛠️ Available Tools
+
+- `start_task` - Begin a new coding task
+- `mark_bug_fixed` - Mark the feature/bug as fixed (requires tests next)
+- `create_tests` - Mark that tests have been created
+- `skip_tests` - Skip tests with justification
+- `run_tests` - Record test results (must pass to proceed)
+- `create_documentation` - Mark documentation as created
+- `check_ready_to_commit` - Verify all steps are complete
+- `commit_and_push` - Commit and push changes
+- `perform_release` - Record release details
+- `complete_task` - Mark task as complete and reset
+- `force_complete_task` - Force completion with reason
+- `drop_task` - Abandon current task
+- `get_workflow_status` - Show current status
+- `view_history` - View completed tasks
+- `continue_workflow` - Get next-step guidance
+- `rerun_workflow` - Reset and restart the current task from the beginning
+- `run_full_workflow` - Execute every workflow step in sequence with a single command (requires supplying the details for each phase)
+
+### `run_full_workflow`
+
+Use this when you already have all the information needed for each workflow phase and want to execute them in one go.
+
+```json
+{
+  "summary": "Add payment webhooks",
+  "testCommand": "npm test",
+  "documentationType": "README",
+  "documentationSummary": "Document webhook configuration",
+  "commitMessage": "feat: add payment webhooks",
+  "releaseCommand": "npm run release:minor",
+  "releaseNotes": "Release webhook support",
+  "branch": "feature/payments",
+  "testsPassed": true,
+  "testDetails": "node --test; 42 tests",
+  "releaseType": "minor",
+  "preset": "minor"
+}
+```
+
+The tool will:
+
+1. `mark_bug_fixed` using `summary`
+2. `create_tests`
+3. `run_tests` with `testsPassed`, `testCommand`, and optional `testDetails`
+4. `create_documentation` with `documentationType` and `documentationSummary`
+5. `check_ready_to_commit`
+6. `commit_and_push` with `commitMessage` and optional `branch`
+7. `perform_release` with `releaseCommand`, plus optional `releaseNotes`, `releaseType`, and `preset`
+8. `complete_task` reusing `commitMessage`
+
+All arguments except the optional flags are required and must be non-empty strings.
+
 ## 🚫 Releasing Without the Workflow Steps
 
 The package ships with a release guard (`release-wrapper.js`) that backs the `npm run release:*` scripts. The guard refuses to run unless:
@@ -162,6 +288,19 @@ If any requirements are missing, the guard exits with guidance to return to the
 1. Use `perform_release {"command":"patch"}` (or `minor`/`major`) via the MCP client.
 2. The guard runs automatically, verifies the workflow state, and records the release before letting you finish with `complete_task`.
 
+### Automated npm Publishing
+
+This repository ships with `.github/workflows/npm-publish.yml`, which publishes the package to npm whenever a git tag matching `v*` is pushed (for example, `v1.1.14`). To enable the workflow:
+
+1. Create an npm automation token with publish rights (`npm token create --read-only false`).
+2. In the repository settings, add a secret named **`NPM_TOKEN`** containing that token.
+3. Ensure your release process pushes tags after running `npm run release:<type>` so the workflow triggers.
+4. Confirm `npm run build` succeeds locally; the workflow runs the build before publishing so broken bundles block the release.
+5. GitHub provenance is enabled via `npm publish --provenance`. Leave GitHub Actions' default OIDC permissions enabled so the job can request an ID token.
+6. Keep the `repository.url` field in `package.json` pointing at this GitHub repo. Provenance validation fails if it does not match the repository that built the package.
+
+The workflow verifies that the tag version matches `package.json` before publishing and fails fast if they diverge.
+
 ## 🛠️ Available Tools
 
 ### Tool Argument Requirements
@@ -372,7 +511,7 @@ You can modify the workflow in `index.js`:
 
 ## 📝 State Management
 
-The server maintains state in `.workflow-state.json`:
+The server maintains state in `.state/workflow-state.json`:
 - Current phase
 - Task description
 - Completion status of each step

package/db/index.js

@@ -0,0 +1,204 @@
+import Database from "better-sqlite3";
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DB_FILENAME = "dev-workflow.db";
+const FREQUENCY_FORMATS = {
+  daily: "%Y-%m-%d",
+  monthly: "%Y-%m",
+  yearly: "%Y",
+};
+
+function getDbPath() {
+  const initCwd = process.env.INIT_CWD || process.cwd();
+  let projectRoot = initCwd;
+  while (projectRoot !== path.dirname(projectRoot)) {
+    if (existsSync(path.join(projectRoot, "package.json"))) break;
+    projectRoot = path.dirname(projectRoot);
+  }
+  return path.join(projectRoot, ".state", DB_FILENAME);
+}
+
+let db;
+export function getDb() {
+  if (!db) {
+    const dbPath = getDbPath();
+    db = new Database(dbPath);
+    db.pragma("journal_mode = WAL");
+    migrate();
+  }
+  return db;
+}
+
+function migrate() {
+  const createHistory = `
+    CREATE TABLE IF NOT EXISTS workflow_history (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      user_id TEXT NOT NULL,
+      task_description TEXT NOT NULL,
+      task_type TEXT NOT NULL,
+      commit_message TEXT,
+      timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
+      forced INTEGER DEFAULT 0,
+      force_reason TEXT,
+      dropped INTEGER DEFAULT 0,
+      drop_reason TEXT,
+      UNIQUE(user_id, timestamp, task_description)
+    )
+  `;
+  const createSummary = `
+    CREATE TABLE IF NOT EXISTS project_summary (
+      user_id TEXT PRIMARY KEY,
+      total_tasks INTEGER DEFAULT 0,
+      task_types TEXT DEFAULT '{}',
+      last_active DATETIME,
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      recent_tasks TEXT DEFAULT '[]'
+    )
+  `;
+  const idxHistory = `CREATE INDEX IF NOT EXISTS idx_workflow_history_user ON workflow_history(user_id)`;
+  const idxSummary = `CREATE INDEX IF NOT EXISTS idx_project_summary_user ON project_summary(user_id)`;
+
+  db.exec(createHistory);
+  db.exec(createSummary);
+  db.exec(idxHistory);
+  db.exec(idxSummary);
+}
+
+export function insertHistoryEntry(userId, entry) {
+  const stmt = getDb().prepare(`
+    INSERT OR REPLACE INTO workflow_history
+    (user_id, task_description, task_type, commit_message, timestamp, forced, force_reason, dropped, drop_reason)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  stmt.run(
+    userId,
+    entry.taskDescription,
+    entry.taskType,
+    entry.commitMessage,
+    entry.timestamp || new Date().toISOString(),
+    entry.forced ? 1 : 0,
+    entry.forceReason || null,
+    entry.dropped ? 1 : 0,
+    entry.dropReason || null
+  );
+  updateSummaryForUser(userId);
+}
+
+export function updateSummaryForUser(userId) {
+  const getHistory = getDb().prepare(`
+    SELECT task_type, timestamp, task_description
+    FROM workflow_history
+    WHERE user_id = ?
+    ORDER BY timestamp DESC
+    LIMIT 20
+  `);
+  const rows = getHistory.all(userId);
+
+  const taskTypes = {};
+  for (const row of rows) {
+    taskTypes[row.task_type] = (taskTypes[row.task_type] || 0) + 1;
+  }
+
+  const recentTasks = rows.slice(0, 5).map(r => ({
+    description: r.task_description,
+    type: r.task_type,
+    timestamp: r.timestamp,
+  }));
+
+  const lastActive = rows[0]?.timestamp || null;
+
+  const upsert = getDb().prepare(`
+    INSERT OR REPLACE INTO project_summary
+    (user_id, total_tasks, task_types, last_active, recent_tasks, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `);
+  upsert.run(
+    userId,
+    rows.length,
+    JSON.stringify(taskTypes),
+    lastActive,
+    JSON.stringify(recentTasks),
+    new Date().toISOString()
+  );
+}
+
+export function getSummaryForUser(userId) {
+  const stmt = getDb().prepare(`
+    SELECT * FROM project_summary WHERE user_id = ?
+  `);
+  const row = stmt.get(userId);
+  if (!row) return null;
+  return {
+    totalTasks: row.total_tasks,
+    taskTypes: JSON.parse(row.task_types),
+    lastActive: row.last_active,
+    recentTasks: JSON.parse(row.recent_tasks),
+    updatedAt: row.updated_at,
+  };
+}
+
+function buildHistoryFilters({ startDate, endDate }) {
+  const clauses = [];
+  const params = [];
+  if (startDate) {
+    clauses.push("DATE(timestamp) >= DATE(?)");
+    params.push(startDate);
+  }
+  if (endDate) {
+    clauses.push("DATE(timestamp) <= DATE(?)");
+    params.push(endDate);
+  }
+  return { clauses, params };
+}
+
+export function getHistoryForUser(userId, options = {}) {
+  const { page = 1, pageSize = 20, startDate, endDate } = options;
+  const sanitizedPage = Math.max(1, Number.isFinite(Number(page)) ? Math.floor(Number(page)) : 1);
+  const sanitizedPageSize = Math.min(100, Math.max(1, Number.isFinite(Number(pageSize)) ? Math.floor(Number(pageSize)) : 20));
+  const offset = (sanitizedPage - 1) * sanitizedPageSize;
+
+  const { clauses, params } = buildHistoryFilters({ startDate, endDate });
+  const where = ["user_id = ?", ...clauses].join(" AND ");
+  const dbInstance = getDb();
+
+  const countStmt = dbInstance.prepare(`SELECT COUNT(*) as total FROM workflow_history WHERE ${where}`);
+  const total = countStmt.get(userId, ...params).total;
+
+  const rowsStmt = dbInstance.prepare(`
+    SELECT *
+    FROM workflow_history
+    WHERE ${where}
+    ORDER BY timestamp DESC
+    LIMIT ?
+    OFFSET ?
+  `);
+  const entries = rowsStmt.all(userId, ...params, sanitizedPageSize, offset);
+
+  return {
+    entries,
+    total,
+    page: sanitizedPage,
+    pageSize: sanitizedPageSize,
+  };
+}
+
+export function getHistorySummary(userId, options = {}) {
+  const { startDate, endDate, frequency = "daily" } = options;
+  const format = FREQUENCY_FORMATS[frequency] || FREQUENCY_FORMATS.daily;
+  const { clauses, params } = buildHistoryFilters({ startDate, endDate });
+  const where = ["user_id = ?", ...clauses].join(" AND ");
+  const stmt = getDb().prepare(`
+    SELECT strftime('${format}', timestamp) AS period, COUNT(*) AS count
+    FROM workflow_history
+    WHERE ${where}
+    GROUP BY period
+    ORDER BY period DESC
+  `);
+  return stmt
+    .all(userId, ...params)
+    .map((row) => ({ period: row.period, count: row.count }));
+}

package/docs/product/PRD.md

@@ -0,0 +1,64 @@
+# Product Requirements Document (PRD)
+
+## 1. Overview
+- **Product**: Development Workflow MCP Server
+- **Prepared by**: Cascade (AI assistant)
+- **Date**: 2025-10-31
+- **Status**: Draft v0.1
+
+## 2. Problem Statement
+Developers need structured guidance to maintain disciplined workflows across projects. Existing tooling lacks enforcement of sequential best practices (testing, documentation, release hygiene) and offers limited visibility into historical task execution.
+
+## 3. Goals & Objectives
+1. Enforce a consistent, auditable development workflow across teams.
+2. Provide actionable guidance for each workflow phase within IDE-integrated environments.
+3. Maintain per-project, per-user workflow state while supporting shared infrastructure (e.g., SQLite summaries, dashboard).
+
+## 4. Non-Goals
+- Replacing full-featured project management tools.
+- Implementing source control hosting or CI/CD pipelines.
+- Providing opinionated task estimation or prioritization features.
+
+## 5. Target Users & Personas
+- **Individual developers** seeking workflow discipline.
+- **Team leads** requiring enforced process compliance.
+- **Tool integrators** embedding MCP capabilities into IDEs or agents.
+
+## 6. User Stories
+1. As a developer, I want to be guided through the workflow steps so I can avoid skipping critical tasks.
+2. As a team lead, I want an auditable history of workflow completion so I can ensure compliance.
+3. As an integrator, I want a simple API (tools/prompts) so I can plug the MCP server into existing agent workflows.
+
+## 7. Functional Requirements
+- Provide MCP tools covering the full workflow lifecycle (start task, fix, test, document, commit, release, complete).
+- Persist workflow state per project and per user, with compatibility handling for legacy locations.
+- Offer aggregated project summaries (JSON artifacts, SQLite sync, optional web dashboard).
+- Guard release commands to ensure prerequisites are satisfied.
+- Support `run_full_workflow` for scripted execution of all steps with validation.
+
+## 8. Technical Considerations
+- Node.js (ESM) codebase leveraging `@modelcontextprotocol/sdk`.
+- File-based state stored under `.state/users/<user>/workflow-state.json` with compatibility symlinks.
+- Optional SQLite integration for history and summary caching.
+- Vite build pipeline for distribution bundle; source usage recommended for MCP.
+- Windows compatibility requirements (Python, Build Tools for native modules).
+
+## 9. Success Metrics
+- ≥90% of workflow operations executed via MCP tools (vs. manual overrides).
+- Reduction in release guard violations to <5% of attempts.
+- Positive qualitative feedback on guidance clarity from pilot teams.
+
+## 10. Milestones
+1. **MVP**: Core workflow tools, state persistence, basic history (complete).
+2. **Enhancements**: Improved project root detection, compatibility mirrors, `run_full_workflow` automation (in progress).
+3. **Future**: Expanded dashboard analytics, customizable workflows, richer integrations.
+
+## 11. Risks & Mitigations
+- **Risk**: Workflow feels overly prescriptive. **Mitigation**: Provide escape hatches (`force_complete_task`, `drop_task`) with audit trails.
+- **Risk**: State corruption due to concurrent access. **Mitigation**: File locking and defensive JSON parsing (existing code handles gracefully, but monitor).
+- **Risk**: Integration friction with IDE clients. **Mitigation**: Maintain detailed README instructions and example configurations.
+
+## 12. Open Questions
+- Should additional workflow phases (e.g., design review) be supported?
+- How should multi-branch workflows be represented in history summaries?
+- What telemetry or analytics are acceptable within privacy constraints?