MartinoPolo Project Workflow Guide
This document provides background knowledge about spec-driven development workflow. It is automatically loaded when discussing project specifications, checklists, or implementation planning.
Workflow Overview
┌──────────────────────────────────────────────────────────────┐
│ Project Lifecycle │
└──────────────────────────────────────────────────────────────┘
Idea ──► Spec ──► Plan ──► Implement ──► Test ──► Ship
│ │ │
▼ ▼ ▼
SPEC.md ROADMAP.md Commits
phases/
File Responsibilities
| File | Purpose | When Updated |
|---|---|---|
| SPEC.md | Requirements source of truth (checkbox list) | Initial creation, scope changes |
| ROADMAP.md | Phase overview, dependencies, tracking, decisions, blockers | Phase completion, decisions |
| phases/NN-name/ | Phase folder with CHECKLIST.md (specs + tasks + state) | During phase execution |
Best Practices
Writing Good Specifications
- Write each requirement as a checkbox item (
- [ ]/- [x]) - Use precise, testable language with no ambiguity
- Preserve constraints and edge cases inline
- Prefer zero information loss over brevity
Breaking Down Tasks
- Each task should be completable in one sitting
- Tasks should have clear completion criteria
- Group related tasks together
- Order tasks by dependency
Phase Design
- Each phase should produce working software
- Minimize dependencies between phases
- Foundation phase always comes first
- Polish/testing phase always comes last
Requirements vs Implementation
- Requirements skills (
/mpx-add-requirements,/mpx-report-issue-or-bug,/mpx-parse-spec) are documentation-only - They update
.mpx/files — never source code, configs, or tests mpx-spec-analyzeris the dedicated parser that converts SPEC into ROADMAP + phase checklists- Implementation happens only via
/mp-execute mpx
Session Handoff
- Run
/mp-handoffat end of each session to create ephemeral HANDOFF.md - HANDOFF.md only exists if
/mp-handoffwas run — it is optional, not always present - Note any decisions made and why
- Document blockers clearly
- Leave "next step" note for continuity
- HANDOFF.md is consumed and deleted by
/mp-executeat next session start
Troubleshooting
"I'm lost in my project"
- Run
/mpx-show-project-statusto see current state - Read ROADMAP.md for overall progress and decisions
- Check last commits with
git log --oneline -10
"The plan doesn't match reality"
- Update SPEC.md with actual requirements
- Run
/mpx-parse-specto regenerate checklists - Review and adjust as needed
"Context is getting degraded"
- Use
/mp-execute mpxfor complex work - This spawns fresh agent with clean context
- CHECKLIST.md maintains continuity (HANDOFF.md adds optional session context if
/mp-handoffwas run)
"I need to change scope"
- Run
/mpx-add-requirements "..."to update SPEC safely - It automatically re-parses via analyzer
- Completed work is preserved in git
"I want to control what gets executed"
/mp-execute mpx phase 3— target specific phase/mp-execute mpx task— force single task/mp-execute mpx all— force entire remaining phase
"I need to add new requirements"
- Run
/mpx-add-requirements "description" - Clarifies ambiguous input before writing
- Updates SPEC.md and re-parses via analyzer into roadmap/checklists
"I found a bug to track"
- Run
/mpx-report-issue-or-bug "description of the bug" - Finds related phase, adds Fix + Verify task pair
- Creates bugfix phase if no matching phase exists
Quick Reference
/mpx-setup - Unified setup (auto-detects: init, convert, restructure)
/mpx-init-repo - Git initialization only
/mpx-parse-spec - Re-parse edited SPEC via analyzer
/mp-execute mpx - Execute tasks (auto-selects phase and scope)
/mpx-show-project-status - Show progress and next steps
/mpx-add-requirements - Primary requirements entry (create/update + parse)
/mpx-report-issue-or-bug - Track bugs/issues in phase system