@programinglive/dev-workflow-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,237 @@
+# Development Workflow MCP Server
+
+An MCP (Model Context Protocol) server that helps enforce development discipline and workflow best practices. This server acts as your coding conscience, reminding you to follow proper development workflows.
+
+## 🎯 Purpose
+
+This MCP server guides you through a disciplined development workflow:
+
+1. **Start Conscious** - Be clear about what you're coding
+2. **Fix/Implement** - Write your code
+3. **Create Tests** - Always test your changes
+4. **Run Tests** - Tests must pass (GREEN)
+5. **Document** - Update documentation
+6. **Commit & Push** - Only when all steps are complete
+
+## 🚀 Installation
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Configure in Windsurf/Claude Desktop
+
+Add to your MCP settings file:
+
+**For Windsurf** (`~/Library/Application Support/Windsurf/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "dev-workflow": {
+      "command": "node",
+      "args": ["/Users/mahardhika/code/project/mine/app/CascadeProjects/windsurf-project/index.js"]
+    }
+  }
+}
+```
+
+**For Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "dev-workflow": {
+      "command": "node",
+      "args": ["/Users/mahardhika/code/project/mine/app/CascadeProjects/windsurf-project/index.js"]
+    }
+  }
+}
+```
+
+### 3. Restart Windsurf/Claude Desktop
+
+After adding the configuration, restart the application to load the MCP server.
+
+## 🛠️ Available Tools
+
+### `start_task`
+Start a new coding task. This is your first step - be conscious about what you're coding.
+
+**Parameters:**
+- `description` (string, required): Clear description of what you're going to code
+- `type` (enum, required): Type of task - "feature", "bugfix", "refactor", or "other"
+
+**Example:**
+```
+Use the start_task tool with:
+- description: "Add user authentication to the login page"
+- type: "feature"
+```
+
+### `mark_bug_fixed`
+Mark that the bug/feature is fixed. **Reminder: Now you MUST create tests!**
+
+**Parameters:**
+- `summary` (string, required): Brief summary of what was fixed/implemented
+
+### `run_tests`
+Record test results. **NEVER commit if tests fail!** Only proceed if all tests are green.
+
+**Parameters:**
+- `passed` (boolean, required): Did all tests pass?
+- `testCommand` (string, required): The test command that was run
+- `details` (string, optional): Test results details
+
+**Example:**
+```
+Use run_tests with:
+- passed: true
+- testCommand: "npm test"
+- details: "All 15 tests passed"
+```
+
+### `create_documentation`
+Mark that documentation has been created/updated. This is required before committing.
+
+**Parameters:**
+- `documentationType` (enum, required): "README", "inline-comments", "API-docs", "changelog", or "other"
+- `summary` (string, required): What was documented
+
+### `check_ready_to_commit`
+Check if all workflow steps are completed and you're ready to commit & push.
+
+### `complete_task`
+Mark the task as complete after successful commit & push. Resets workflow for next task.
+
+**Parameters:**
+- `commitMessage` (string, required): The commit message used
+
+### `get_workflow_status`
+Get current workflow status and what needs to be done next.
+
+### `view_history`
+View workflow history of completed tasks.
+
+**Parameters:**
+- `limit` (number, optional): Number of recent tasks to show (default: 10)
+
+## 📋 Available Prompts
+
+### `workflow_reminder`
+Get a complete reminder of the development workflow discipline.
+
+### `pre_commit_checklist`
+Get a pre-commit checklist to ensure nothing is missed before committing.
+
+## 🔄 Typical Workflow
+
+Here's how you'd use this MCP server in a typical coding session:
+
+1. **Start your task:**
+   ```
+   Ask Cascade to use start_task:
+   "Start a new task: implementing user profile page, type: feature"
+   ```
+
+2. **Code your feature/fix**
+   - Write your code as usual
+
+3. **Mark as fixed:**
+   ```
+   "Mark the feature as fixed: User profile page with avatar and bio completed"
+   ```
+
+4. **Create tests:**
+   - Write your tests
+   - The server will remind you this is mandatory!
+
+5. **Run tests:**
+   ```
+   "Record test results: passed=true, command='npm test'"
+   ```
+   - If tests fail, the server will **block** you from proceeding!
+
+6. **Document:**
+   ```
+   "Create documentation: type=README, summary='Added user profile section to docs'"
+   ```
+
+7. **Check readiness:**
+   ```
+   "Check if I'm ready to commit"
+   ```
+
+8. **Commit & Push:**
+   ```bash
+   git add .
+   git commit -m "feat: add user profile page with tests and docs"
+   git push
+   ```
+
+9. **Complete:**
+   ```
+   "Complete the task with commit message: 'feat: add user profile page'"
+   ```
+
+## 🎯 Key Features
+
+- **Enforces discipline**: Won't let you skip steps
+- **Test-driven**: Blocks commits if tests fail
+- **Documentation reminder**: Ensures you document your work
+- **State tracking**: Remembers where you are in the workflow
+- **History**: Keeps track of completed tasks
+- **Prompts**: Quick reminders of best practices
+
+## 🚫 What This Server Prevents
+
+- ❌ Committing without tests
+- ❌ Committing with failing tests
+- ❌ Committing without documentation
+- ❌ Losing track of what you're working on
+- ❌ Skipping important workflow steps
+
+## 💡 Tips
+
+1. **Always start with `start_task`** - This sets your intention
+2. **Never skip tests** - The server will remind you!
+3. **Use `get_workflow_status`** - Check where you are anytime
+4. **Review history** - Learn from your past tasks
+5. **Follow the prompts** - They contain best practices
+
+## 🔧 Customization
+
+You can modify the workflow in `index.js`:
+- Add more workflow phases
+- Customize reminders
+- Add integration with your test runner
+- Add custom validation rules
+
+## 📝 State Management
+
+The server maintains state in `.workflow-state.json`:
+- Current phase
+- Task description
+- Completion status of each step
+- History of completed tasks
+
+This file is automatically created and managed by the server.
+
+## 🤝 Integration with Your Rules
+
+This MCP server aligns with your existing development rules:
+- ✅ Enforces test-first discipline
+- ✅ Prevents commits with failing tests
+- ✅ Reminds about documentation
+- ✅ Tracks workflow state
+- ✅ Maintains history
+
+## 📄 License
+
+MIT
+
+## 🙏 Contributing
+
+Feel free to customize this server to match your specific workflow needs!

package/index.js

@@ -0,0 +1,588 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Workflow state management
+export class WorkflowState {
+  constructor(stateFilePath = path.join(__dirname, ".workflow-state.json")) {
+    this.stateFile = stateFilePath;
+    this.state = {
+      currentPhase: "idle",
+      taskDescription: "",
+      bugFixed: false,
+      testsPassed: false,
+      documentationCreated: false,
+      readyToCommit: false,
+      history: [],
+    };
+  }
+
+  async load() {
+    try {
+      const data = await fs.readFile(this.stateFile, "utf-8");
+      this.state = JSON.parse(data);
+    } catch (error) {
+      // File doesn't exist yet, use default state
+    }
+  }
+
+  async save() {
+    await fs.writeFile(this.stateFile, JSON.stringify(this.state, null, 2));
+  }
+
+  reset() {
+    this.state = {
+      currentPhase: "idle",
+      taskDescription: "",
+      bugFixed: false,
+      testsPassed: false,
+      documentationCreated: false,
+      readyToCommit: false,
+      history: this.state.history,
+    };
+  }
+
+  addToHistory(entry) {
+    this.state.history.push({
+      ...entry,
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+
+export const workflowState = new WorkflowState();
+await workflowState.load();
+
+// Create MCP server
+export const server = new Server(
+  {
+    name: "@programinglive/dev-workflow-mcp-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+      prompts: {},
+    },
+  }
+);
+
+// Define tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "start_task",
+        description:
+          "Start a new coding task. This is the first step - be conscious about what you're coding.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            description: {
+              type: "string",
+              description: "Clear description of what you're going to code",
+            },
+            type: {
+              type: "string",
+              enum: ["feature", "bugfix", "refactor", "other"],
+              description: "Type of task",
+            },
+          },
+          required: ["description", "type"],
+        },
+      },
+      {
+        name: "mark_bug_fixed",
+        description:
+          "Mark that the bug/feature is fixed. Reminder: Now you MUST create tests!",
+        inputSchema: {
+          type: "object",
+          properties: {
+            summary: {
+              type: "string",
+              description: "Brief summary of what was fixed/implemented",
+            },
+          },
+          required: ["summary"],
+        },
+      },
+      {
+        name: "run_tests",
+        description:
+          "Record test results. NEVER commit if tests fail! Only proceed if all tests are green.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            passed: {
+              type: "boolean",
+              description: "Did all tests pass?",
+            },
+            testCommand: {
+              type: "string",
+              description: "The test command that was run",
+            },
+            details: {
+              type: "string",
+              description: "Test results details",
+            },
+          },
+          required: ["passed", "testCommand"],
+        },
+      },
+      {
+        name: "create_documentation",
+        description:
+          "Mark that documentation has been created/updated. This is required before committing.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            documentationType: {
+              type: "string",
+              enum: ["README", "inline-comments", "API-docs", "changelog", "other"],
+              description: "Type of documentation created",
+            },
+            summary: {
+              type: "string",
+              description: "What was documented",
+            },
+          },
+          required: ["documentationType", "summary"],
+        },
+      },
+      {
+        name: "check_ready_to_commit",
+        description:
+          "Check if all workflow steps are completed and you're ready to commit & push.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "complete_task",
+        description:
+          "Mark the task as complete after successful commit & push. Resets workflow for next task.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            commitMessage: {
+              type: "string",
+              description: "The commit message used",
+            },
+          },
+          required: ["commitMessage"],
+        },
+      },
+      {
+        name: "get_workflow_status",
+        description: "Get current workflow status and what needs to be done next.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "view_history",
+        description: "View workflow history of completed tasks.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            limit: {
+              type: "number",
+              description: "Number of recent tasks to show (default: 10)",
+            },
+          },
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case "start_task": {
+      workflowState.reset();
+      workflowState.state.currentPhase = "coding";
+      workflowState.state.taskDescription = args.description;
+      workflowState.state.taskType = args.type;
+      await workflowState.save();
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `✅ 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. ⏳ Commit & push\n\nReminder: Focus on writing clean, maintainable code!`,
+          },
+        ],
+      };
+    }
+
+    case "mark_bug_fixed": {
+      if (workflowState.state.currentPhase === "idle") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "⚠️ Please start a task first using 'start_task'!",
+            },
+          ],
+        };
+      }
+
+      workflowState.state.bugFixed = true;
+      workflowState.state.currentPhase = "testing";
+      workflowState.state.fixSummary = args.summary;
+      await workflowState.save();
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `✅ 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. ⏳ Commit & push\n\n🚫 DO NOT SKIP TESTING!`,
+          },
+        ],
+      };
+    }
+
+    case "run_tests": {
+      if (!workflowState.state.bugFixed) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "⚠️ Please mark your feature/bug as fixed first using 'mark_bug_fixed'!",
+            },
+          ],
+        };
+      }
+
+      workflowState.state.testsPassed = args.passed;
+      workflowState.state.testCommand = args.testCommand;
+      workflowState.state.testDetails = args.details || "";
+
+      if (!args.passed) {
+        workflowState.state.currentPhase = "testing";
+        await workflowState.save();
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `❌ TESTS FAILED!\n\n🚫 STOP! DO NOT COMMIT OR PUSH!\n\nYou must:\n1. Fix the failing tests\n2. Run tests again until they pass\n\nTest command: ${args.testCommand}\n\nNever skip or ignore failing tests!`,
+            },
+          ],
+        };
+      }
+
+      workflowState.state.currentPhase = "documentation";
+      await workflowState.save();
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `✅ All tests passed! 🎉\n\nTest command: ${args.testCommand}\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ✓ Create tests\n3. ✓ Run tests (GREEN!)\n4. ⏳ Create/update documentation\n5. ⏳ Commit & push\n\nReminder: Document what you did before committing!`,
+          },
+        ],
+      };
+    }
+
+    case "create_documentation": {
+      if (!workflowState.state.testsPassed) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "⚠️ Please ensure tests are passing first! Run 'run_tests' with passed=true.",
+            },
+          ],
+        };
+      }
+
+      workflowState.state.documentationCreated = true;
+      workflowState.state.documentationType = args.documentationType;
+      workflowState.state.documentationSummary = args.summary;
+      workflowState.state.currentPhase = "ready";
+      workflowState.state.readyToCommit = true;
+      await workflowState.save();
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `✅ Documentation created!\n\nType: ${args.documentationType}\nSummary: ${args.summary}\n\n🎉 You're ready to commit!\n\nNext Steps:\n1. ✓ Fix/implement feature\n2. ✓ Create tests\n3. ✓ Run tests (GREEN!)\n4. ✓ Create documentation\n5. ⏳ Run 'check_ready_to_commit' to verify\n6. ⏳ Commit & push\n7. ⏳ Mark as complete with 'complete_task'\n\nRemember: git add . && git commit && git push`,
+          },
+        ],
+      };
+    }
+
+    case "check_ready_to_commit": {
+      const status = workflowState.state;
+      const checks = [
+        { name: "Task started", done: status.currentPhase !== "idle" },
+        { name: "Feature/bug fixed", done: status.bugFixed },
+        { name: "Tests created and passed", done: status.testsPassed },
+        { name: "Documentation created", done: status.documentationCreated },
+      ];
+
+      const allDone = checks.every((c) => c.done);
+      const checkList = checks
+        .map((c) => `${c.done ? "✅" : "❌"} ${c.name}`)
+        .join("\n");
+
+      if (allDone) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `🎉 ALL CHECKS PASSED! You're ready to commit!\n\n${checkList}\n\n✅ You can now:\n1. git add .\n2. git commit -m "your message"\n3. git push\n4. Run 'complete_task' to finish\n\nTask: ${status.taskDescription}`,
+            },
+          ],
+        };
+      } else {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `⚠️ NOT READY TO COMMIT!\n\n${checkList}\n\nPlease complete all steps before committing.`,
+            },
+          ],
+        };
+      }
+    }
+
+    case "complete_task": {
+      if (!workflowState.state.readyToCommit) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "⚠️ Not ready to complete! Run 'check_ready_to_commit' first.",
+            },
+          ],
+        };
+      }
+
+      workflowState.addToHistory({
+        taskDescription: workflowState.state.taskDescription,
+        taskType: workflowState.state.taskType,
+        fixSummary: workflowState.state.fixSummary,
+        testCommand: workflowState.state.testCommand,
+        documentationType: workflowState.state.documentationType,
+        commitMessage: args.commitMessage,
+      });
+
+      const completedTask = workflowState.state.taskDescription;
+      workflowState.reset();
+      workflowState.state.currentPhase = "idle";
+      await workflowState.save();
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `🎉 Task completed successfully!\n\nCompleted: ${completedTask}\nCommit: ${args.commitMessage}\n\n✅ Workflow reset. Ready for next task!\n\nUse 'start_task' when you begin your next coding session.`,
+          },
+        ],
+      };
+    }
+
+    case "get_workflow_status": {
+      const status = workflowState.state;
+
+      if (status.currentPhase === "idle") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "📋 No active task.\n\nUse 'start_task' to begin a new coding session.",
+            },
+          ],
+        };
+      }
+
+      const phaseMessages = {
+        coding: "🔨 Currently coding",
+        testing: "🧪 Ready for testing",
+        documentation: "📝 Ready for documentation",
+        ready: "✅ Ready to commit",
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `📋 Current Workflow Status\n\nTask: ${status.taskDescription}\nPhase: ${phaseMessages[status.currentPhase]}\n\nProgress:\n${status.bugFixed ? "✅" : "⏳"} Feature/bug fixed\n${status.testsPassed ? "✅" : "⏳"} Tests passed\n${status.documentationCreated ? "✅" : "⏳"} Documentation created\n${status.readyToCommit ? "✅" : "⏳"} Ready to commit\n\nNext: ${getNextStep(status)}`,
+          },
+        ],
+      };
+    }
+
+    case "view_history": {
+      const limit = args.limit || 10;
+      const history = workflowState.state.history.slice(-limit).reverse();
+
+      if (history.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "📜 No workflow history yet.",
+            },
+          ],
+        };
+      }
+
+      const historyText = history
+        .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 {
+        content: [
+          {
+            type: "text",
+            text: `📜 Workflow History (last ${history.length} tasks)\n\n${historyText}`,
+          },
+        ],
+      };
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+// Helper function
+export function getNextStep(status) {
+  if (!status.bugFixed) return "Mark feature/bug as fixed";
+  if (!status.testsPassed) return "Create and run tests";
+  if (!status.documentationCreated) return "Create documentation";
+  if (!status.readyToCommit) return "Check if ready to commit";
+  return "Commit and push!";
+}
+
+// Define prompts
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return {
+    prompts: [
+      {
+        name: "workflow_reminder",
+        description: "Get a reminder of the complete development workflow",
+      },
+      {
+        name: "pre_commit_checklist",
+        description: "Pre-commit checklist to ensure nothing is missed",
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name } = request.params;
+
+  if (name === "workflow_reminder") {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Development Workflow Discipline:
+
+1. 🎯 START CONSCIOUS
+   - Use 'start_task' to declare what you're coding
+   - Be clear about your intention
+
+2. 🔨 CODE WITH PURPOSE
+   - Implement your feature or fix
+   - Follow best practices
+
+3. 🧪 ALWAYS CREATE TESTS
+   - After fixing/implementing, create tests
+   - Use 'mark_bug_fixed' when done
+
+4. ✅ TESTS MUST PASS
+   - Run your tests with 'run_tests'
+   - If tests fail: FIX THEM, never skip!
+   - Only proceed when all tests are GREEN
+
+5. 📝 DOCUMENT YOUR WORK
+   - Update README, comments, or docs
+   - Use 'create_documentation' when done
+
+6. 🚀 COMMIT & PUSH
+   - Use 'check_ready_to_commit' to verify
+   - git add . && git commit && git push
+   - Use 'complete_task' to finish
+
+Remember: No shortcuts! Each step is important for code quality.`,
+          },
+        },
+      ],
+    };
+  }
+
+  if (name === "pre_commit_checklist") {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Pre-Commit Checklist:
+
+Before you commit and push, verify:
+
+□ Feature/bug is fully implemented
+□ Tests are created for the changes
+□ All tests pass (GREEN) - run 'run_tests'
+□ Documentation is updated
+□ Code is clean (no console.logs, unused imports)
+□ No TypeScript 'any' types
+□ Followed project coding standards
+
+Use 'check_ready_to_commit' to verify workflow completion.
+
+🚫 NEVER commit if tests are failing!
+✅ Only commit when everything is green!`,
+          },
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown prompt: ${name}`);
+});
+
+// Start server
+export async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Dev Workflow MCP Server running on stdio");
+}
+
+if (process.argv[1] === __filename) {
+  main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@programinglive/dev-workflow-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server to enforce development workflow discipline",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "dev-workflow-mcp": "./index.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check index.js",
+    "start": "node index.js",
+    "dev": "node --watch index.js"
+  },
+  "keywords": [
+    "mcp",
+    "workflow",
+    "development",
+    "discipline"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tests/workflowState.test.js

@@ -0,0 +1,87 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { WorkflowState, getNextStep } from "../index.js";
+
+async function withWorkflowState(callback) {
+  const tempDir = await mkdtemp(path.join(tmpdir(), "workflow-state-"));
+  const stateFile = path.join(tempDir, "state.json");
+  const state = new WorkflowState(stateFile);
+  await state.load();
+
+  try {
+    await callback(state);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+test("WorkflowState persists data across save/load", async () => {
+  await withWorkflowState(async (state) => {
+    state.state.currentPhase = "testing";
+    state.state.taskDescription = "Test persistence";
+    state.state.bugFixed = true;
+    await state.save();
+
+    const reloaded = new WorkflowState(state.stateFile);
+    await reloaded.load();
+
+    assert.equal(reloaded.state.currentPhase, "testing");
+    assert.equal(reloaded.state.taskDescription, "Test persistence");
+    assert.equal(reloaded.state.bugFixed, true);
+  });
+});
+
+test("WorkflowState reset keeps history but clears progress", async () => {
+  await withWorkflowState(async (state) => {
+    state.state.currentPhase = "ready";
+    state.state.testsPassed = true;
+    state.state.documentationCreated = true;
+    state.addToHistory({ taskDescription: "Sample task" });
+
+    state.reset();
+
+    assert.equal(state.state.currentPhase, "idle");
+    assert.equal(state.state.testsPassed, false);
+    assert.equal(state.state.documentationCreated, false);
+    assert.equal(state.state.history.length, 1);
+    assert.equal(state.state.history[0].taskDescription, "Sample task");
+  });
+});
+
+test("getNextStep guides workflow progression", () => {
+  const baseState = {
+    bugFixed: false,
+    testsPassed: false,
+    documentationCreated: false,
+    readyToCommit: false,
+  };
+
+  assert.equal(
+    getNextStep(baseState),
+    "Mark feature/bug as fixed"
+  );
+
+  const afterFix = { ...baseState, bugFixed: true };
+  assert.equal(
+    getNextStep(afterFix),
+    "Create and run tests"
+  );
+
+  const afterTests = { ...afterFix, testsPassed: true };
+  assert.equal(
+    getNextStep(afterTests),
+    "Create documentation"
+  );
+
+  const afterDocs = { ...afterTests, documentationCreated: true };
+  assert.equal(
+    getNextStep(afterDocs),
+    "Check if ready to commit"
+  );
+
+  const ready = { ...afterDocs, readyToCommit: true };
+  assert.equal(getNextStep(ready), "Commit and push!");
+});