# Mpm Workflow

> Manage and customize MPM workflow configurations with local overrides

- Skill: `bobmatnyc/mpm-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bobmatnyc/mpm-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bobmatnyc/mpm-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: bobmatnyc (https://skillmd.com/u/bobmatnyc)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/bobmatnyc/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

```markdown
# 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

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

### Add Custom Phase

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

### Modify Verification Requirements

```markdown
## 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.