Workflow Philosophy

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:

1. Context loss - Important decisions are forgotten across conversations
2. Scope creep - Tasks expand without clear boundaries
3. Inconsistency - Different approaches in different sessions
4. 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

Tip

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:

1. Log a finding noting the expansion
2. Consider splitting into multiple topics
3. 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.