Workflow Philosophy
Understanding the methodology behind Workflow MCP
Workflow Philosophy
Workflow MCP is built on a simple premise: AI-assisted development is more effective with structure.
The Problem
When working with AI assistants on complex tasks, several challenges emerge:
- Context loss - Important decisions are forgotten across conversations
- Scope creep - Tasks expand without clear boundaries
- Inconsistency - Different approaches in different sessions
- Lack of traceability - No record of what was tried and why
The Solution: Structured Workflows
Workflow MCP introduces a methodology that addresses these challenges:
1. Defined Phases
Each workflow command represents a distinct phase with its own purpose:
| Phase | Purpose | Artifacts |
|---|---|---|
| Research | Gather information, explore options | Findings, requirements |
| Plan | Design implementation approach | Decisions, task breakdown |
| Implement | Write code, execute plan | Task completions, issues |
| Review | Verify against requirements | Gaps, recommendations |
| Debug | Diagnose and fix problems | Faults, investigations, fixes |
2. Structured Logging
Every significant event is logged with:
- Entry-ID: Unique identifier for cross-referencing
- Timestamp: When it occurred
- Type: Category of entry (finding, decision, task, etc.)
- Context: Relevant details and evidence
3. Handoff Continuity
When transitioning between phases, a handoff message summarizes:
- What was accomplished
- Key findings or decisions
- Recommended next steps
- Any blockers or open issues
Run /clear before starting a new phase to prevent context pollution, then read the handoff for clean context.
Dynamic Problem Solving (DPS)
Not all tasks need the same level of rigidity. DPS levels let you control flexibility:
| Level | Name | Behavior |
|---|---|---|
| 0 | Off | Stop on any deviation, pure role adherence |
| 1 | Minimal | Ask clarifying questions, minor adjustments |
| 2 | Light | Can make small fixes within scope |
| 3 | Moderate | Can propose alternatives when issues arise |
| 4 | Significant | Can redesign components if needed |
| 5 | Full | Maximum flexibility, exploratory mode |
Default DPS by Command
- Research: 4 (exploratory by nature)
- Plan: 1 (should follow research closely)
- Implement: 1 (should follow plan strictly)
- Review: 3 (can propose fixes for gaps)
- Debug: 4 (root cause analysis needs flexibility)
- Archive: 0 (mechanical process)
Best Practices
Start with Research
Even for "obvious" tasks, a quick research phase:
- Identifies constraints you might miss
- Documents decisions for future reference
- Creates a foundation for the plan
Keep Sessions Focused
One topic per session. If scope expands:
- Log a finding noting the expansion
- Consider splitting into multiple topics
- Complete current scope before expanding
Log Everything Significant
If Claude makes a decision, it should be logged. Future-you will thank present-you.
Use Evidence References
When logging findings, include file:line references:
mcp__workflow__log_entry({
tag: "finding",
fields: {
title: "Auth middleware location",
content: "JWT verification happens here",
evidence: "src/middleware/auth.ts:42-58"
}
})Review Before Implementing
The review phase catches gaps between research/plan and implementation. Don't skip it for non-trivial changes.