bobmatnyc/claude-mpm/mpm-workflow

MPM Workflow Configuration

Overview

The MPM workflow system supports customizable workflow configurations with a priority-based override system. This allows projects to customize the standard 5-phase workflow while maintaining sensible defaults.

Priority System

Workflow files are loaded with the following priority (highest to lowest):

1. Project-level: .claude-mpm/WORKFLOW.md - Project-specific customizations
2. User-level: ~/.claude-mpm/WORKFLOW.md - User preferences across all projects
3. System default: Built-in framework WORKFLOW.md

Actions

These are skill-driven actions, not claude-mpm workflow CLI subcommands -- there is no such CLI surface. When this skill is invoked (e.g. via /mpm-workflow status), Claude itself reads, writes, or validates the WORKFLOW.md files directly, following the priority order above (project -> user -> system default).

status

When invoked with status, Claude reports the current workflow configuration and its source. Example of what Claude reports back:

Workflow Configuration Status:
  Source: project (.claude-mpm/WORKFLOW.md)
  Phases: 5
  Verification Gates: Enabled
  Custom Overrides: Phase 2 (Code Analysis) skipped

init

When invoked with init, Claude creates a local workflow configuration file:

• /mpm-workflow init -- Claude creates .claude-mpm/WORKFLOW.md with defaults
• /mpm-workflow init --minimal -- Claude creates it with a minimal template

reset

When invoked with reset, Claude removes the local override so the system default takes effect:

• /mpm-workflow reset -- Claude removes the local override, falling back to the system default

validate

When invoked with validate, Claude checks the current workflow configuration for completeness and reports findings. Example of what Claude reports back:

Validating workflow configuration...
  [OK] Phase definitions complete
  [OK] Verification gates defined
  [OK] Agent routing valid
  [WARN] Custom phase 6 defined - ensure agent exists

Workflow File Structure

Required Sections

# PM Workflow Configuration
 
## Mandatory Phase Sequence
 
### Phase 1: Research (ALWAYS FIRST)
**Agent**: Research
**Output**: Requirements, constraints, success criteria
**Template**: ...
 
### Phase 2: Code Analysis Review
**Agent**: Code Analysis
**Output**: APPROVED/NEEDS_IMPROVEMENT/BLOCKED
**Decision**: ...
 
### Phase 3: Implementation
**Agent**: Selected via delegation matrix
**Requirements**: Complete code, error handling, tests
 
### Phase 4: QA (MANDATORY)
**Agent**: qa/api-qa/web-qa
**Requirements**: Real-world testing with evidence
 
### Phase 5: Documentation
**Agent**: Documentation
**When**: Code changes made
 
## Verification Gates
 
| Phase | Verification Required | Evidence Format |
|-------|----------------------|-----------------|
| ... | ... | ... |
 
## Override Commands
 
-"Skip workflow" - bypass sequence
-"Go directly to [phase]" - jump to phase

Customization Examples

Skip Code Analysis for Trusted Projects

### Phase 2: Code Analysis Review
**Agent**: Code Analysis
**Status**: OPTIONAL
**Skip When**: Small fixes, documentation only

Add Custom Phase

### Phase 6: Security Scan (Custom)
**Agent**: Security
**When**: Changes to auth, API, or data handling
**Output**: Security report

Modify Verification Requirements

## Verification Gates
 
| Phase | Verification Required | Evidence Format |
|-------|----------------------|-----------------|
| Implementation | Tests pass + Coverage > 80% | pytest output with coverage |

Integration with Instruction Builder

The workflow loader automatically injects workflow configuration into PM instructions:

1. Checks for project-level WORKFLOW.md
2. Falls back to user-level if not found
3. Uses system default as last resort
4. Injects into workflow_instructions content field

Best Practices

1. Start with defaults: Only override what you need
2. Document changes: Add comments explaining why phases were modified
3. Test workflows: Use /mpm-workflow validate after changes
4. Version control: Commit .claude-mpm/WORKFLOW.md with your project
5. Team alignment: Ensure team agrees on workflow customizations

Troubleshooting

Workflow not loading

1. Check file exists: ls -la .claude-mpm/WORKFLOW.md
2. Validate syntax: /mpm-workflow validate
3. Check priority: /mpm-workflow status

Phases not executing

1. Verify phase is defined in workflow
2. Check agent exists for custom phases
3. Review verification gate requirements

Reset to defaults

Invoke this skill with /mpm-workflow reset and Claude will remove the local override directly.