Workflow Best Practices

# Workflow Compliance Enforcer MCP [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io) > **Enforce client-mandated development workflows with audit trails, state persistence, and compliance reporting.** A Model Context Protocol (MCP) server designed for enterprise, government, and regulated industries where development workflows are **non-negotiable** and **compliance is critical**. ## Why This Exists In enterprise consulting and government contracts, clients often mandate strict development workflows: - ✅ Tests **must** pass before commit - ✅ Code **must** be deployed before issue close - ✅ Production **must** be verified - ✅ Audit trail **must** exist for compliance **This MCP server enforces those workflows** and provides proof of compliance. ## Features ### 🔒 Compliance-First - **State Persistence** - Workflow survives Claude Code restarts - **Audit Trails** - Automatic compliance reports with timestamps - **Pre-flight Checks** - Validates required scripts before starting - **Time Tracking** - Duration tracking for all steps ### 🎯 Workflow Management - **Visual Progress** - Real-time workflow visualization - **Multiple Templates** - Different workflows for different tasks - **Resume Capability** - Pick up where you left off after crashes - **Better Errors** - Actionable suggestions for common issues ### ⚙️ Configurable - **Per-Project Config** - Different workflows for different projects - **Deployment Methods** - Git-push, script-based, or manual - **Verification Strategies** - Smoke test, script, manual, or none - **Strict/Lenient Modes** - Enforce or warn ## Quick Start ### Installation 1. **Clone and build:** ```bash git clone https://github.com/scarter4work/workflow-compliance-enforcer.git cd workflow-compliance-enforcer npm install npm run build ``` 2. **Add to Claude Code MCP config** (`~/.claude/mcp.json`): ```json { "mcpServers": { "workflow-enforcer": { "command": "node", "args": ["/path/to/workflow-compliance-enforcer/build/index.js"] } } } ``` 3. **Restart Claude Code** ### Configuration Create `.workflow-enforcer.json` in your project root: ```json { "mode": "strict", "template": "full-deployment", "test_command": "npm test", "deploy_method": "git-push", "production_verification": "script", "production_test_command": "npm run test:prod" } ``` ## Usage ### Basic Workflow ```javascript // 1. Start work on an issue workflow_start_issue({ issue_number: 42 }) // 2. Write your code, then run tests workflow_run_tests() // 3. Commit (only works after tests pass) workflow_commit({ message: "fix: resolve authentication bug" }) // 4. Deploy to production workflow_deploy() // 5. Verify production workflow_verify_prod() // 6. Close issue and generate audit report workflow_close_issue() ``` ### Resume After Crash ```javascript // If Claude Code crashes mid-workflow workflow_start_issue({ issue_number: 42, resume: true }) // Picks up exactly where you left off! ``` ### Check Progress ```javascript workflow_status({ detailed: true }) ``` **Output:** ``` 📊 Workflow Status: State: TESTS_PASSED Active Issue: #42 - Fix authentication bug Commit: None 📋 Workflow Progress (full-deployment): ✅ 1. Start Issue (workflow_start_issue) ✅ 2. Run Tests (workflow_run_tests) ⏳ 3. Commit Changes (workflow_commit) ← YOU ARE HERE ⬜ 4. Deploy to Production (workflow_deploy) ⬜ 5. Verify Production (workflow_verify_prod) ⬜ 6. Close Issue (workflow_close_issue) Available actions: - workflow_commit ``` ## Workflow Templates ### Full Deployment (default) For production features requiring full release cycle: 1. Start Issue → 2. Run Tests → 3. Commit → 4. Deploy → 5. Verify → 6. Close ### Tests Only For internal changes that don't need deployment: 1. Start Issue → 2. Run Tests → 3. Commit → 4. Close ### Docs Only For documentation changes: 1. Start Issue → 2. Commit → 3. Close ## Audit Reports Every completed workflow generates an audit report: ``` 📊 Workflow Completion Report - Issue #42 ====================================================================== Issue: Fix authentication bug Started: 2025-11-16T12:00:00.000Z Completed: 2025-11-16T12:45:30.000Z Duration: 0h 45m 30s Steps Completed: ✅ Start Issue - 2025-11-16T12:00:00.000Z ✅ Run Tests - 2025-11-16T12:15:00.000Z (12450ms) ✅ Commit Changes - 2025-11-16T12:20:00.000Z ✅ Deploy to Production - 2025-11-16T12:35:00.000Z (145000ms) ✅ Verify Production - 2025-11-16T12:43:00.000Z (8200ms) ✅ Close Issue - 2025-11-16T12:45:30.000Z Commits: - a1b2c3d: fix: resolve authentication bug Attestation: All required workflow steps completed successfully. Signed: workflow-enforcer v2.0.0 ``` Saved to `.workflow/reports/issue-42-report.md` for compliance purposes. ## Configuration Options | Option | Values | Description | |--------|--------|-------------| | `mode` | `strict`, `lenient` | Strict = enforced; Lenient = warnings | | `template` | `full-deployment`, `tests-only`, `docs-only` | Workflow to use | | `test_command` | string | Test command (default: `npm test`) | | `deploy_method` | `git-push`, `script`, `manual` | How to deploy | | `production_verification` | `smoke-test`, `script`, `manual`, `none` | How to verify | See [WORKFLOW_ENFORCER_V2.md](./WORKFLOW_ENFORCER_V2.md) for complete documentation. ## Use Cases ### Enterprise Client ```json { "mode": "strict", "template": "full-deployment", "deploy_method": "manual", "production_verification": "manual" } ``` Manual gates for deployment and verification with full audit trail. ### CI/CD Automation ```json { "mode": "strict", "template": "full-deployment", "deploy_method": "git-push", "production_verification": "smoke-test", "production_url": "https://api.example.com/health" } ``` Automated deployment with quick smoke test verification. ### Internal Development ```json { "mode": "lenient", "template": "tests-only" } ``` Skip deployment for internal changes, but still enforce tests. ## Available Tools - `workflow_start_issue` - Begin work with pre-flight checks - `workflow_run_tests` - Run test suite with duration tracking - `workflow_commit` - Commit code (only after tests pass) - `workflow_deploy` - Deploy to production - `workflow_verify_prod` - Verify production deployment - `workflow_close_issue` - Close issue and generate audit report - `workflow_status` - Check current workflow state - `workflow_config` - View/update configuration ## Requirements - Node.js 18+ - GitHub CLI (`gh`) for issue management - Claude Code with MCP support ## Comparison: v1.0 vs v2.0 | Feature | v1.0 | v2.0 | |---------|------|------| | State Persistence | ❌ | ✅ | | Pre-flight Checks | ❌ | ✅ | | Workflow Visualization | ❌ | ✅ | | Audit Reports | ❌ | ✅ | | Configuration | ❌ Hardcoded | ✅ Per-project | | Templates | ❌ One size fits all | ✅ 3 templates | | Error Messages | ⚠️ Generic | ✅ Actionable | | Time Tracking | ❌ | ✅ | | Resume Capability | ❌ | ✅ | ## Contributing Contributions welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Submit a pull request For major changes, please open an issue first. ## License MIT License - see [LICENSE](LICENSE) file for details. ## Support - **Issues:** [GitHub Issues](https://github.com/scarter4work/workflow-compliance-enforcer/issues) - **Documentation:** [Full Docs](./WORKFLOW_ENFORCER_V2.md) - **MCP Docs:** [Model Context Protocol](https://modelcontextprotocol.io) ## Acknowledgments Built with [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic. --- **Built for compliance. Designed for real-world client workflows.**