@programinglive/dev-workflow-mcp-server 1.7.16 → 1.7.17

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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.7.17](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.16...v1.7.17) (2025-12-26)
+
+
+### 📝 Documentation
+
+* update release notes for v1.7.16 ([0afd96b](https://github.com/programinglive/dev-workflow-mcp-server/commit/0afd96b754717953eb162f65426129457fc8626e))
+
+
+### ✨ Features
+
+* allow skipping release step ([004e4fa](https://github.com/programinglive/dev-workflow-mcp-server/commit/004e4fae071e064b2c2efb9d69ecd97e794d3cb8))
+
+
+### 🧹 Chores
+
+* add @programinglive/commiter setup ([1d2a19d](https://github.com/programinglive/dev-workflow-mcp-server/commit/1d2a19d0453b50c6f0db35b15924b51a27c4891a))
+
 ### [1.7.16](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.15...v1.7.16) (2025-12-24)
 
 

package/README.md

@@ -512,7 +512,7 @@ This keeps workflow state local to each developer's machine.
 - `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
+- `perform_release` - Record release details (or use `skip_release` when the project has no release automation)
 - `complete_task` - Mark task as complete and reset
 - `force_complete_task` - Force completion with reason
 - `drop_task` - Abandon current task
@@ -553,6 +553,7 @@ The tool will:
 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`
+   - Alternatively call `skip_release` with a justification when the repository has no Node-based release step (e.g., Python-only or docs-only tasks)
 8. `complete_task` reusing `commitMessage`
 
 All arguments except the optional flags are required and must be non-empty strings.
@@ -571,7 +572,7 @@ The package ships with a release guard (`release-wrapper.js`) that backs the `np
 
 If any requirements are missing, the guard exits with guidance to return to the MCP tools. This prevents accidentally bumping versions or tagging releases outside the managed workflow. To release correctly:
 
-1. Use `perform_release {"command":"patch"}` (or `minor`/`major`) via the MCP client.
+1. Use `perform_release {"command":"patch"}` (or `minor`/`major`) via the MCP client, or `skip_release {"reason":"<explanation>"}` if no release applies.
 2. The guard runs automatically, verifies the workflow state, and records the release before letting you finish with `complete_task`.
 
 ### Automated npm Publishing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.7.16",
+  "version": "1.7.17",
   "description": "MCP server to enforce development workflow discipline",
   "homepage": "https://devworkflow.programinglive.com/",
   "mcpName": "io.github.programinglive/dev-workflow-mcp-server",
@@ -62,11 +62,13 @@
   "devDependencies": {
     "@commitlint/cli": "^20.2.0",
     "@commitlint/config-conventional": "^20.2.0",
-    "@programinglive/commiter": "^1.2.16",
+    "@programinglive/commiter": "^1.2.17",
     "autoprefixer": "^10.4.22",
+    "cross-env": "^10.1.0",
     "husky": "^9.1.7",
     "postcss": "^8.5.6",
     "standard-version": "^9.5.0",
+    "supertest": "^7.1.4",
     "tailwindcss": "^3.4.18"
   },
   "standard-version": {

package/scripts/release.cjs

@@ -11,6 +11,9 @@ const FS_FOK_PRELOAD_FLAG = buildPreloadFlag(fsFokPreloadPath);
 
 require('./preload/fs-f-ok.cjs');
 
+const DEFAULT_PRD_RELATIVE_PATH = path.join('docs', 'PRD.md');
+const DEFAULT_PRD_DISPLAY_PATH = 'docs/PRD.md';
+
 const VALID_RELEASE_TYPES = new Set([
   'major',
   'minor',
@@ -161,6 +164,8 @@ function runRelease({
     throw new Error('Working tree has uncommitted changes. Commit or stash before running release.');
   }
 
+  ensurePrdPresence({ cwd, dependencies });
+
   const testResult = runProjectTests({ spawn, env });
   if (testResult && typeof testResult.status === 'number' && testResult.status !== 0) {
     return testResult;
@@ -219,9 +224,31 @@ module.exports = {
   detectPackageManager,
   runProjectTests,
   runRelease,
-  isWorkingTreeClean
+  isWorkingTreeClean,
+  ensurePrdPresence
 };
 
+function ensurePrdPresence({ cwd = process.cwd(), dependencies = {} } = {}) {
+  const {
+    fsExistsSync = fs.existsSync,
+    logger = console,
+    prdRelativePath = DEFAULT_PRD_RELATIVE_PATH,
+    prdDisplayPath = DEFAULT_PRD_DISPLAY_PATH
+  } = dependencies;
+
+  const resolvedPath = path.isAbsolute(prdRelativePath)
+    ? prdRelativePath
+    : path.join(cwd, prdRelativePath);
+
+  if (fsExistsSync(resolvedPath)) {
+    return true;
+  }
+
+  const warn = typeof logger?.warn === 'function' ? logger.warn.bind(logger) : console.warn.bind(console);
+  warn(`⚠️  Product Requirements Document missing (${prdDisplayPath}). Add ${DEFAULT_PRD_DISPLAY_PATH} so teams understand release expectations.`);
+  return false;
+}
+
 function buildPreloadFlag(filePath) {
   const resolved = path.resolve(filePath);
   const escaped = resolved.includes(' ')

package/tests/build.test.js

@@ -8,7 +8,7 @@ import path from 'path';
 const exec = promisify(execCallback);
 
 test('build generates dist/index.mjs file', async () => {
-  const { stderr } = await exec('NODE_ENV=development npm run build:server');
+  const { stderr } = await exec('npx cross-env NODE_ENV=development npm run build:server');
   // Allow the known vite warning about node:process
   const knownWarning = '[plugin vite:resolve] Module "node:process" has been externalized for browser compatibility';
   const tailwindOutput = '≈ tailwindcss';

package/tests/handlers.test.js

@@ -970,6 +970,45 @@ test("perform_release accepts shorthand patch command", async () => {
   });
 });
 
+test("skip_release records justification and advances to completion phase", async () => {
+  await withWorkflowState(async (workflowState) => {
+    workflowState.state.currentPhase = "release";
+    workflowState.state.commitAndPushCompleted = true;
+    workflowState.state.readyCheckCompleted = true;
+    workflowState.state.lastCommitMessage = "chore: docs";
+    workflowState.state.releaseSkipped = false;
+    workflowState.state.released = false;
+    workflowState.state.releaseCommand = "";
+    await workflowState.save();
+
+    const response = await handleToolCall({
+      request: createRequest("skip_release", { reason: "Python project – no npm release" }),
+      normalizeRequestArgs,
+      workflowState,
+      exec: async () => ({ stdout: "" }),
+      git: {
+        hasWorkingChanges: async () => false,
+        hasStagedChanges: async () => false,
+        hasTestChanges: async () => true,
+        getStagedChanges: async () => [],
+        getCurrentBranch: async () => "main",
+        getPrimaryBranch: async () => "main",
+        getLastCommitMessage: async () => "chore: docs",
+        workingTreeSummary: () => ({ hasChanges: false, lines: [] }),
+      },
+      utils,
+    });
+
+    const text = response.content[0].text;
+    assert.ok(text.includes("Release step skipped"), "response should mention release was skipped");
+    assert.equal(workflowState.state.releaseSkipped, true);
+    assert.equal(workflowState.state.releaseSkippedReason, "Python project – no npm release");
+    assert.equal(workflowState.state.releaseCommand, "(skipped)");
+    assert.equal(workflowState.state.currentPhase, "ready_to_complete");
+    assert.equal(workflowState.state.released, false);
+  });
+});
+
 test("perform_release respects explicit releaseType option", async () => {
   await withWorkflowState(async (workflowState) => {
     workflowState.state.currentPhase = "release";

package/tools/definitions.js

@@ -148,6 +148,21 @@ export function getToolList() {
         required: ["command"],
       },
     },
+    {
+      name: "skip_release",
+      description:
+        "Record that the release step was intentionally skipped (e.g., non-Node projects or documentation-only work). Requires a justification.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          reason: {
+            type: "string",
+            description: "Why the release step is being skipped",
+          },
+        },
+        required: ["reason"],
+      },
+    },
     {
       name: "complete_task",
       description:

package/tools/handler-modules/shared.js

@@ -0,0 +1,187 @@
+import fs from "fs/promises";
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+export const PROJECT_SUMMARY_FILENAME = "project-summary.json";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const textResponse = (text) => ({
+  content: [
+    {
+      type: "text",
+      text,
+    },
+  ],
+});
+
+export function isReleaseSatisfied(state) {
+  return Boolean(state?.released || state?.releaseSkipped);
+}
+
+export async function resetToCommitIfWorkingChanges(workflowState, git) {
+  if (!workflowState.state.commitAndPushCompleted) {
+    return false;
+  }
+
+  const hasWorkingChanges = await git.hasWorkingChanges();
+  const hasStagedChanges = await git.hasStagedChanges();
+
+  if (!hasWorkingChanges && !hasStagedChanges) {
+    return false;
+  }
+
+  workflowState.state.commitAndPushCompleted = false;
+  workflowState.state.released = false;
+  workflowState.state.releaseSkipped = false;
+  workflowState.state.releaseSkippedReason = "";
+  workflowState.state.currentPhase = "commit";
+  workflowState.state.releaseCommand = "";
+  workflowState.state.releaseNotes = "";
+  await workflowState.save();
+  return true;
+}
+
+export function formatChecklist(checks) {
+  return checks.map((c) => `${c.done ? "✅" : "❌"} ${c.name}`).join("\n");
+}
+
+export function summarizeHistory(history, limit) {
+  const recent = history.slice(-limit).reverse();
+  if (recent.length === 0) {
+    return null;
+  }
+
+  const historyText = recent
+    .map(
+      (entry, index) =>
+        `${index + 1}. [${new Date(entry.timestamp).toLocaleString()}]\n   Task: ${entry.taskDescription}\n   Type: ${entry.taskType}\n   Commit: ${entry.commitMessage}\n`
+    )
+    .join("\n");
+
+  return `📜 Workflow History (last ${recent.length} tasks)\n\n${historyText}`;
+}
+
+export function generateProjectSummary(history) {
+  if (!history || history.length === 0) {
+    return "No workflow history available.";
+  }
+
+  const taskTypes = {};
+  const recentTasks = history.slice(-20);
+
+  for (const entry of recentTasks) {
+    const type = entry.taskType || "other";
+    taskTypes[type] = (taskTypes[type] || 0) + 1;
+  }
+
+  const typeSummary = Object.entries(taskTypes)
+    .map(([type, count]) => `${type}: ${count}`)
+    .join(", ");
+
+  const totalTasks = history.length;
+  const lastTask = history[history.length - 1];
+  const lastActive = lastTask ? new Date(lastTask.timestamp).toLocaleDateString() : "Never";
+
+  return `🧠 Project Knowledge Summary\n\n📊 Stats\n- Total tasks completed: ${totalTasks}\n- Recent task mix: ${typeSummary}\n- Last active: ${lastActive}\n\n📝 Recent tasks (last 5)\n${history.slice(-5).reverse().map((e, i) => `${i + 1}. ${e.taskDescription} (${e.taskType})`).join("\n")}`;
+}
+
+export function getContinueGuidance(status) {
+  switch (status.currentPhase) {
+    case "coding": {
+      const task = status.taskDescription ? ` "${status.taskDescription}"` : "";
+      return `Finish implementing${task} and then run 'mark_bug_fixed' with a brief summary of the change.`;
+    }
+    case "testing":
+      if (!status.testsCreated) {
+        return "Create automated coverage now using 'create_tests' before recording any results.";
+      }
+
+      if (status.testsPassed) {
+        return "With tests green, move on to 'create_documentation' and capture what changed.";
+      }
+
+      if (status.testsSkipped) {
+        return "Document why tests were skipped using 'create_documentation' so the workflow can proceed.";
+      }
+
+      return status.testCommand
+        ? `Fix any failing tests and re-run '${status.testCommand}'. Once they pass, record the results with 'run_tests'.`
+        : "Run your automated tests and record the outcome with 'run_tests'. Fix any failures before moving forward.";
+    case "documentation":
+      return status.testsSkipped
+        ? `Document the change (including manual QA for skipped tests) with 'create_documentation'. Reason recorded: ${status.testsSkippedReason || "(none provided)"}.`
+        : "Capture your updates with 'create_documentation' (provide the documentation type and a short summary).";
+    case "ready":
+      return "Run 'check_ready_to_commit' to verify all prerequisite steps before committing.";
+    case "commit":
+      return "All checks passed—run 'commit_and_push' with your commit message (and optional branch).";
+    case "release":
+      return "Commit recorded. Execute 'perform_release' with the release command you ran to publish changes, or call 'skip_release' with a justification if no release is required.";
+    case "ready_to_complete":
+      return "Release recorded. Finish up by calling 'complete_task' with the commit message you used.";
+    default:
+      return "Review your workflow progress and complete the next required step.";
+  }
+}
+
+export async function handleReadyCheck(workflowState) {
+  const status = workflowState.state;
+  const testsCreatedDone = status.testsSkipped || status.testsCreated;
+  const testsPassedDone = status.testsSkipped || status.testsPassed;
+  const checks = [
+    { name: "Task started", done: status.currentPhase !== "idle" },
+    { name: "Feature/bug fixed", done: status.bugFixed },
+    {
+      name: status.testsSkipped ? "Tests skipped (manual QA documented)" : "Tests created",
+      done: testsCreatedDone,
+    },
+    {
+      name: status.testsSkipped ? "Tests skipped acknowledged" : "Tests passed",
+      done: testsPassedDone,
+    },
+    { name: "Documentation created", done: status.documentationCreated },
+  ];
+
+  const allDone = checks.every((c) => c.done);
+  const checkList = formatChecklist(checks);
+
+  workflowState.state.readyCheckCompleted = allDone;
+  if (allDone) {
+    if (workflowState.state.commitAndPushCompleted) {
+      workflowState.state.currentPhase = isReleaseSatisfied(workflowState.state) ? "ready_to_complete" : "release";
+    } else {
+      workflowState.state.currentPhase = "commit";
+    }
+  }
+  await workflowState.save();
+
+  if (allDone) {
+    return textResponse(
+      `🎉 ALL CHECKS PASSED!\n\n${checkList}\n\n✅ Next actions:\n1. Run 'commit_and_push' (commits and pushes your changes)\n2. Run 'perform_release' (handles versioning, tags, and final push)\n3. Finish with 'complete_task'\n\nTip: Provide the optional 'branch' argument to 'commit_and_push' to push to a non-default branch.\n\nTask: ${status.taskDescription}`
+    );
+  }
+
+  return textResponse(`⚠️ NOT READY TO COMMIT!\n\n${checkList}\n\nPlease complete all steps before committing.`);
+}
+
+export async function loadProjectSummary(workflowState) {
+  const summaryPath = path.join(path.dirname(workflowState.stateFile), PROJECT_SUMMARY_FILENAME);
+  try {
+    const data = await fs.readFile(summaryPath, "utf-8");
+    return JSON.parse(data);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export const prdPath = path.join(__dirname, "..", "docs", "product", "PRD.md");
+
+export function ensurePrdExists() {
+  return existsSync(prdPath);
+}

package/tools/handlers.js

@@ -16,6 +16,10 @@ const textResponse = (text) => ({
   ],
 });
 
+function isReleaseSatisfied(state) {
+  return Boolean(state?.released || state?.releaseSkipped);
+}
+
 async function resetToCommitIfWorkingChanges(workflowState, git) {
   if (!workflowState.state.commitAndPushCompleted) {
     return false;
@@ -30,6 +34,8 @@ async function resetToCommitIfWorkingChanges(workflowState, git) {
 
   workflowState.state.commitAndPushCompleted = false;
   workflowState.state.released = false;
+  workflowState.state.releaseSkipped = false;
+  workflowState.state.releaseSkippedReason = "";
   workflowState.state.currentPhase = "commit";
   workflowState.state.releaseCommand = "";
   workflowState.state.releaseNotes = "";
@@ -113,7 +119,7 @@ function getContinueGuidance(status) {
     case "commit":
       return "All checks passed—run 'commit_and_push' with your commit message (and optional branch).";
     case "release":
-      return "Commit recorded. Execute 'perform_release' with the release command you ran to publish changes.";
+      return "Commit recorded. Execute 'perform_release' with the release command you ran to publish changes, or call 'skip_release' with a justification if no release is required.";
     case "ready_to_complete":
       return "Release recorded. Finish up by calling 'complete_task' with the commit message you used.";
     default:
@@ -185,7 +191,7 @@ async function handleStartTask(args, workflowState) {
   await workflowState.save();
 
   return textResponse(
-    `✅ Task Started: ${args.description}\n\n🎯 Be conscious about what you're coding!\n\nWorkflow Steps:\n1. ✓ Start task (current)\n2. ⏳ Fix/implement the feature\n3. ⏳ Create tests\n4. ⏳ Run tests (must pass!)\n5. ⏳ Create documentation\n6. ⏳ Run 'check_ready_to_commit'\n7. ⏳ Run 'commit_and_push' (commits and pushes)\n8. ⏳ Run 'perform_release' (handles versioning and tags)\n9. ⏳ Complete task\n\nReminder: Focus on writing clean, maintainable code!`
+    `✅ Task Started: ${args.description}\n\n🎯 Be conscious about what you're coding!\n\nWorkflow Steps:\n1. ✓ Start task (current)\n2. ⏳ Fix/implement the feature\n3. ⏳ Create tests\n4. ⏳ Run tests (must pass!)\n5. ⏳ Create documentation\n6. ⏳ Run 'check_ready_to_commit'\n7. ⏳ Run 'commit_and_push' (commits and pushes)\n8. ⏳ Run 'perform_release' (handles versioning and tags) or 'skip_release' (when no release is needed)\n9. ⏳ Complete task\n\nReminder: Focus on writing clean, maintainable code!`
   );
 }
 
@@ -225,6 +231,8 @@ async function handleMarkBugFixed(args, workflowState) {
   workflowState.state.fixSummary = args.summary;
   workflowState.state.readyCheckCompleted = false;
   workflowState.state.released = false;
+  workflowState.state.releaseSkipped = false;
+  workflowState.state.releaseSkippedReason = "";
   workflowState.state.releaseCommand = "";
   workflowState.state.releaseNotes = "";
   workflowState.state.commitAndPushCompleted = false;
@@ -233,7 +241,7 @@ async function handleMarkBugFixed(args, workflowState) {
   await workflowState.save();
 
   return textResponse(
-    `✅ Feature/Bug marked as fixed!\n\n⚠️ CRITICAL REMINDER: You MUST create tests now!\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ⏳ Create tests for: ${args.summary}\n3. ⏳ Run tests (must be green!)\n4. ⏳ Create documentation\n5. ⏳ Run 'check_ready_to_commit'\n6. ⏳ Run 'commit_and_push'\n7. ⏳ Run 'perform_release'\n8. ⏳ Complete task\n\n🚫 DO NOT SKIP TESTING!`
+    `✅ Feature/Bug marked as fixed!\n\n⚠️ CRITICAL REMINDER: You MUST create tests now!\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ⏳ Create tests for: ${args.summary}\n3. ⏳ Run tests (must be green!)\n4. ⏳ Create documentation\n5. ⏳ Run 'check_ready_to_commit'\n6. ⏳ Run 'commit_and_push'\n7. ⏳ Run 'perform_release' (or 'skip_release' if no release applies)\n8. ⏳ Complete task\n\n🚫 DO NOT SKIP TESTING!`
   );
 }
 
@@ -247,13 +255,15 @@ async function handleCreateTests(workflowState) {
   workflowState.state.testsSkippedReason = "";
   workflowState.state.readyCheckCompleted = false;
   workflowState.state.released = false;
+  workflowState.state.releaseSkipped = false;
+  workflowState.state.releaseSkippedReason = "";
   workflowState.state.commitAndPushCompleted = false;
   workflowState.state.lastCommitMessage = "";
   workflowState.state.lastPushBranch = "";
   await workflowState.save();
 
   return textResponse(
-    "✅ Tests recorded!\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ✓ Create tests\n3. ⏳ Run tests (must be green!)\n4. ⏳ Create documentation\n5. ⏳ Run 'check_ready_to_commit'\n6. ⏳ Run 'commit_and_push'\n7. ⏳ Run 'perform_release'\n8. ⏳ Complete task\n\n🧪 Run your test command and record the results using 'run_tests'."
+    "✅ Tests recorded!\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ✓ Create tests\n3. ⏳ Run tests (must be green!)\n4. ⏳ Create documentation\n5. ⏳ Run 'check_ready_to_commit'\n6. ⏳ Run 'commit_and_push'\n7. ⏳ Run 'perform_release' (or 'skip_release' if appropriate)\n8. ⏳ Complete task\n\n🧪 Run your test command and record the results using 'run_tests'."
   );
 }
 
@@ -280,6 +290,8 @@ async function handleSkipTests(args, workflowState) {
   workflowState.state.readyToCommit = false;
   workflowState.state.readyCheckCompleted = false;
   workflowState.state.released = false;
+  workflowState.state.releaseSkipped = false;
+  workflowState.state.releaseSkippedReason = "";
   workflowState.state.commitAndPushCompleted = false;
   workflowState.state.lastCommitMessage = "";
   workflowState.state.lastPushBranch = "";
@@ -297,7 +309,7 @@ Next Steps:
 3. ⏳ Create/update documentation
 4. ⏳ Run 'check_ready_to_commit'
 5. ⏳ Run 'commit_and_push'
-6. ⏳ Run 'perform_release'
+6. ⏳ Run 'perform_release' or 'skip_release'
 7. ⏳ Complete task`
   );
 }
@@ -328,6 +340,8 @@ async function handleRunTests(args, workflowState) {
   workflowState.state.testsSkippedReason = "";
   workflowState.state.readyCheckCompleted = false;
   workflowState.state.released = false;
+  workflowState.state.releaseSkipped = false;
+  workflowState.state.releaseSkippedReason = "";
   workflowState.state.commitAndPushCompleted = false;
   workflowState.state.lastCommitMessage = "";
   workflowState.state.lastPushBranch = "";
@@ -345,7 +359,7 @@ async function handleRunTests(args, workflowState) {
   await workflowState.save();
 
   return textResponse(
-    `✅ All tests passed! 🎉\n\nTest command: ${args.testCommand}\n\n📝 Now create or update documentation using 'create_documentation' with:\n- documentationType: "PRD", "README", "RELEASE_NOTES", "inline-comments", "API-docs", "changelog", or "other"\n- summary: Brief description of what was documented\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ✓ Create tests\n3. ✓ Run tests (GREEN!)\n4. ⏳ Create/update documentation\n5. ⏳ Run 'check_ready_to_commit'\n6. ⏳ Run 'commit_and_push'\n7. ⏳ Run 'perform_release'\n8. ⏳ Complete task`
+    `✅ All tests passed! 🎉\n\nTest command: ${args.testCommand}\n\n📝 Now create or update documentation using 'create_documentation' with:\n- documentationType: "PRD", "README", "RELEASE_NOTES", "inline-comments", "API-docs", "changelog", or "other"\n- summary: Brief description of what was documented\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ✓ Create tests\n3. ✓ Run tests (GREEN!)\n4. ⏳ Create/update documentation\n5. ⏳ Run 'check_ready_to_commit'\n6. ⏳ Run 'commit_and_push'\n7. ⏳ Run 'perform_release' (or use 'skip_release' if no release is needed)\n8. ⏳ Complete task`
   );
 }
 
@@ -371,13 +385,58 @@ async function handleCreateDocumentation(args, workflowState) {
   workflowState.state.readyToCommit = true;
   workflowState.state.readyCheckCompleted = false;
   workflowState.state.released = false;
+  workflowState.state.releaseSkipped = false;
+  workflowState.state.releaseSkippedReason = "";
   workflowState.state.commitAndPushCompleted = false;
   workflowState.state.lastCommitMessage = "";
   workflowState.state.lastPushBranch = "";
   await workflowState.save();
 
   return textResponse(
-    `✅ Documentation created/updated!\n\nType: ${args.documentationType}\nSummary: ${args.summary}\n✅ PRD verified: docs/product/PRD.md exists\n\n🎉 You're ready to verify your work!\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ✓ Create tests\n3. ✓ Run tests (GREEN!)\n4. ✓ Create/update documentation\n5. ⏳ Run 'check_ready_to_commit' to verify\n6. ⏳ Run 'commit_and_push'\n7. ⏳ Run 'perform_release'\n8. ⏳ Mark as complete with 'complete_task'`
+    `✅ Documentation created/updated!\n\nType: ${args.documentationType}\nSummary: ${args.summary}\n✅ PRD verified: docs/product/PRD.md exists\n\n🎉 You're ready to verify your work!\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ✓ Create tests\n3. ✓ Run tests (GREEN!)\n4. ✓ Create/update documentation\n5. ⏳ Run 'check_ready_to_commit' to verify\n6. ⏳ Run 'commit_and_push'\n7. ⏳ Run 'perform_release' (or 'skip_release' when applicable)\n8. ⏳ Mark as complete with 'complete_task'`
+  );
+}
+
+async function handleSkipRelease(args, workflowState) {
+  if (workflowState.state.currentPhase === "idle") {
+    return textResponse("⚠️ Please start a task first using 'start_task' before skipping release.");
+  }
+
+  const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+  if (!reason) {
+    return textResponse("⚠️ Provide a non-empty 'reason' explaining why the release step is being skipped.");
+  }
+
+  if (workflowState.state.releaseSkipped) {
+    workflowState.state.releaseSkippedReason = reason;
+    await workflowState.save();
+    return textResponse(
+      `ℹ️ Release step was already skipped for this task.\nUpdated reason: ${reason}\n\nNext: run 'complete_task' to wrap up.`
+    );
+  }
+
+  if (workflowState.state.released) {
+    return textResponse("⚠️ A release command has already been recorded. Continue with 'complete_task'.");
+  }
+
+  if (!workflowState.state.readyCheckCompleted) {
+    return textResponse("⚠️ Please run 'check_ready_to_commit' and ensure all prerequisites pass before skipping release.");
+  }
+
+  if (!workflowState.state.commitAndPushCompleted) {
+    return textResponse("⚠️ Please complete 'commit_and_push' before skipping release.");
+  }
+
+  workflowState.state.releaseSkipped = true;
+  workflowState.state.releaseSkippedReason = reason;
+  workflowState.state.released = false;
+  workflowState.state.releaseCommand = "(skipped)";
+  workflowState.state.releaseNotes = "";
+  workflowState.state.currentPhase = "ready_to_complete";
+  await workflowState.save();
+
+  return textResponse(
+    `⚠️ Release step skipped.\nReason: ${reason}\n\n✅ Next: run 'complete_task' with your final commit message to close out the workflow.`
   );
 }
 
@@ -404,11 +463,11 @@ async function handleReadyCheck(workflowState) {
 
   workflowState.state.readyCheckCompleted = allDone;
   if (allDone) {
-    workflowState.state.currentPhase = workflowState.state.commitAndPushCompleted
-      ? workflowState.state.released
-        ? "ready_to_complete"
-        : "release"
-      : "commit";
+    if (workflowState.state.commitAndPushCompleted) {
+      workflowState.state.currentPhase = isReleaseSatisfied(workflowState.state) ? "ready_to_complete" : "release";
+    } else {
+      workflowState.state.currentPhase = "commit";
+    }
   }
   await workflowState.save();
 
@@ -448,7 +507,7 @@ async function handleCommitAndPush(args, context) {
     workflowState.state.commitAndPushCompleted = true;
     workflowState.state.lastCommitMessage = effectiveCommitMessage || "";
     workflowState.state.lastPushBranch = branchForPush;
-    workflowState.state.currentPhase = workflowState.state.released ? "ready_to_complete" : "release";
+    workflowState.state.currentPhase = isReleaseSatisfied(workflowState.state) ? "ready_to_complete" : "release";
     await workflowState.save();
 
     return textResponse(
@@ -457,10 +516,10 @@ async function handleCommitAndPush(args, context) {
     );
   }
 
-  if (!(await git.hasTestChanges()) && !workflowState.state.testsSkipped) {
-    return textResponse(
-      "⚠️ Please include test updates in your changes before running 'commit_and_push'. Ensure at least one test file is modified."
-    );
+  const statusOutput = await git.getStatusOutput();
+
+  if (!workflowState.state.testsSkipped && !git.containsTestFilesInStatus(statusOutput)) {
+    return textResponse("⚠️ Please include test updates in your changes before running 'commit_and_push'. Ensure at least one test file is modified.");
   }
 
   try {
@@ -514,7 +573,7 @@ async function handleCommitAndPush(args, context) {
   workflowState.state.commitAndPushCompleted = true;
   workflowState.state.lastCommitMessage = generatedSummary;
   workflowState.state.lastPushBranch = branchForPush;
-  workflowState.state.currentPhase = workflowState.state.released ? "ready_to_complete" : "release";
+  workflowState.state.currentPhase = isReleaseSatisfied(workflowState.state) ? "ready_to_complete" : "release";
   await workflowState.save();
 
   return textResponse(
@@ -936,7 +995,7 @@ async function handleRunFullWorkflow(args, { workflowState, exec, git, utils })
       continue;
     }
 
-    if (!state.released) {
+    if (!isReleaseSatisfied(state)) {
       const resp = await executeStep("perform_release", handlePerformRelease, [
         releaseArgs,
         { workflowState, exec, git, utils },
@@ -996,6 +1055,8 @@ export async function handleToolCall({
         return handleCommitAndPush(args, { workflowState, exec, git, utils });
       case "perform_release":
         return handlePerformRelease(args, { workflowState, exec, git, utils });
+      case "skip_release":
+        return handleSkipRelease(args, workflowState);
       case "complete_task":
         return handleCompleteTask(args, workflowState);
       case "force_complete_task":

package/workflow-state.js

@@ -440,6 +440,8 @@ export class WorkflowState {
       readyToCommit: false,
       readyCheckCompleted: false,
       released: false,
+      releaseSkipped: false,
+      releaseSkippedReason: "",
       releaseCommand: "",
       releaseNotes: "",
       commitAndPushCompleted: false,
@@ -477,6 +479,12 @@ export class WorkflowState {
       if (typeof this.state.released !== "boolean") {
         this.state.released = false;
       }
+      if (typeof this.state.releaseSkipped !== "boolean") {
+        this.state.releaseSkipped = false;
+      }
+      if (typeof this.state.releaseSkippedReason !== "string") {
+        this.state.releaseSkippedReason = "";
+      }
       if (typeof this.state.commitAndPushCompleted !== "boolean") {
         this.state.commitAndPushCompleted = false;
       }
@@ -622,6 +630,8 @@ export class WorkflowState {
       readyToCommit: false,
       readyCheckCompleted: false,
       released: false,
+      releaseSkipped: false,
+      releaseSkippedReason: "",
       releaseCommand: "",
       releaseNotes: "",
       commitAndPushCompleted: false,