MPM — Spec-driven task queue system for AI coding agents

What MPM Solves

Running multiple Claude Code sessions is chaos. Every time one finishes, it demands attention — while you're mid-thought on something else. Context-switching kills focus.

Batching tasks without specs makes it worse — broken UI/UX, buggy code, contradictory decisions across sessions. You spend more time finding what went wrong than doing actual work.

MPM combines two strategies:

• Spec-driven development — Architecture, design, and verification docs that every task is planned, built, and reviewed against. Claude stays consistent because it has a single source of truth injected at session start.
• Task queue — Claude pops tasks, works, reviews its own output, then moves to the next — automatically. You come back when you're ready.

 You                              Claude
────                              ──────
/mpm-init → define specs    →    create phases, goals, tasks
/mpm-autonext               →    task → review → next → repeat
...do your actual work...        task → review → next → repeat
come back when ready        ←    review queue waiting

Installation

Option A — Global install (recommended):

npm install -g mpm-dashboard
mpm                  # Start dashboard in background (port 5100)
mpm init             # Install MPM into current project

Option B — No install (npx):

npx mpm-dashboard              # Start dashboard
npx mpm-dashboard init         # Install MPM into current project

All CLI commands:

mpm                        # Start dashboard in background (default port 5100)
mpm start --foreground     # Start in foreground (show logs)
mpm stop                   # Stop dashboard
mpm init                   # Install MPM into current project
mpm status                 # Show registered projects and server status
mpm port 3000              # Change dashboard port
mpm disable                # Remove MPM-related files from project
mpm uninstall              # Remove MPM completely

Requirements:

• Node.js 20+
• Claude Code
• Windows: Git for Windows for hook execution

Usage

1. Init

/mpm-init

Runs an office-hour session to define your product, then generates foundation docs (PROJECT.md, ARCHITECTURE.md, DESIGN.md, UIUX.md, VERIFICATION.md) and creates your first phase with goals and tasks.

Takes ~30 min. 10x payoff.

2. Auto-next

/mpm-autonext

Claude pops the next task, does the work, runs /mpm-review, and chains to the next task automatically until the queue is empty.

Use --dangerously-skip-permissions for unattended execution:

claude --dangerously-skip-permissions
# then: /mpm-autonext

3. Human review

Process the review queue from the dashboard or in-session:

/mpm-human-review

Walk through completed tasks — approve, reject, or discard. Rejected tasks are rewritten and pushed back to the queue. The running /mpm-autonext picks them up without restart.

How It Works

Hooks

MPM installs four Claude Code hooks into .claude/settings.json:

| Hook | Script | What it does | |------|--------|--------------| | SessionStart | inject-project-status.sh | Injects all project docs + current task + phase status into context | | SessionStart | hook-notify.sh active | Notifies dashboard: session started | | UserPromptSubmit | hook-notify.sh working | Notifies dashboard: working | | PermissionRequest | hook-notify.sh waiting | Notifies dashboard: waiting for input | | Stop | hook-autonext-stop.sh | If autonext is active and task is done, feeds next task prompt | | Stop | hook-notify.sh waiting | Notifies dashboard: session stopped |

Context injection

Every session start, inject-project-status.sh reads and injects:

1. mpm-workflow.md — how Claude should use MPM
2. Current task (if any)
3. All foundation docs (PROJECT.md, ARCHITECTURE.md, etc.)
4. FEEDBACK_HISTORY.md — past rejection context
5. Phase/goal/task status summary

Claude always has full context without you having to re-explain anything.

Task lifecycle

future.json  →  current/{session}.json  →  review/{id}.json  →  past/{date}.json
   queue            working                  human review           done

| Status | Location | Meaning | |--------|----------|---------| | future | future.json | Queued | | dev | current/{session}.json | Claude working | | agent-review | current/{session}.json | Claude reviewing its own work | | human-review | review/{id}.json | Waiting for your decision | | past | past/{date}.json | Done |

Foundation Documents

Created during /mpm-init, injected into every session automatically.

| Document | Location | Content | |----------|----------|---------| | PROJECT.md | .mpm/docs/ | Problem, target user, constraints, success criteria | | ARCHITECTURE.md | .mpm/docs/ | System design, data flow, tech stack, API, test strategy | | DESIGN.md | .mpm/docs/ | Aesthetic direction, typography, color, spacing, motion | | UIUX.md | .mpm/docs/ | Screens, navigation, interaction states, user journey | | VERIFICATION.md | .mpm/docs/ | Exact commands to verify every feature | | tokens/ | .mpm/docs/tokens/ | Design tokens (CSS/JS/JSON) | | FEEDBACK_HISTORY.md | .mpm/data/ | Auto-logged rejection comments |

Skills

Planning

| Skill | Description | |-------|-------------| | /mpm-init | Full project setup — office-hour → reviews → foundation docs → phases, goals, tasks | | /mpm-office-hour | Product definition through structured questioning (6 forcing questions) | | /mpm-plan-ceo-review | Strategic review — challenges scope, validates premises | | /mpm-plan-eng-review | Engineering review — architecture, data flow, test strategy | | /mpm-task-write | Create well-structured tasks with evidence requirements |

Design

| Skill | Description | |-------|-------------| | /mpm-init-uiux | UI/UX foundation — research, proposes design system, generates preview, writes docs | | /mpm-plan-design-review | Design review — rates dimensions, fixes the plan | | /mpm-ui-ux-pro-max | Design intelligence database — 50+ styles, 161 palettes, 57 font pairings, 99 UX guidelines |

Development

| Skill | Description | |-------|-------------| | /mpm-next | Pop and execute one task | | /mpm-autonext | Auto-process tasks until queue is empty. Supports --top N, --goal <ref>, --phase <ref> |

Review

| Skill | Description | |-------|-------------| | /mpm-review | Review completed work — functional, code quality, UI/UX compliance | | /mpm-review-functional | Does it work? Runs verification commands, tests unhappy paths | | /mpm-review-code | Code quality — architecture compliance, DRY, security, error handling | | /mpm-review-uiux | Design system compliance, visual verification | | /mpm-human-review | Walk through review queue with human — approve, reject, discard |

Utility

| Skill | Description | |-------|-------------| | /mpm-recycle | Rewrite rejected tasks with rejection context and push back to queue | | /mpm-project-progress | Show phase/goal/task progress summary |

Dashboard

mpm       # starts in background
mpm stop  # stops

Opens at http://localhost:5100. Shows all registered projects — phase progress, task status, review queue, and live terminal sessions.

File Structure

.mpm/
├── data/
│   ├── future.json              # Task queue
│   ├── current/                 # One task per active session
│   ├── review/                  # Awaiting human review
│   ├── past/                    # Completed tasks by date
│   ├── phases.json              # Phase/Goal hierarchy
│   └── FEEDBACK_HISTORY.md      # Rejection/needs-input log
├── docs/
│   ├── PROJECT.md
│   ├── ARCHITECTURE.md
│   ├── DESIGN.md
│   ├── UIUX.md
│   ├── VERIFICATION.md
│   └── tokens/
└── scripts/
    ├── task.py                      # Task operations
    ├── phase.py                     # Phase/Goal operations
    ├── inject-project-status.sh     # Context injection (SessionStart)
    ├── hook-autonext-stop.sh        # Auto-next chaining (Stop)
    └── hook-notify.sh               # Dashboard status updates

.claude/
├── skills/
│   ├── mpm-init/
│   ├── mpm-autonext/
│   ├── mpm-next/
│   ├── mpm-review/
│   ├── mpm-human-review/
│   └── ...
└── settings.json                    # Hook definitions (merged, not overwritten)

License

MIT