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

code

┌──────────────────────────────────────────────────────────────┐
│                     Project Lifecycle                        │
└──────────────────────────────────────────────────────────────┘

  Idea ──► Spec ──► Plan ──► Implement ──► Test ──► Ship
           │         │           │
           ▼         ▼           ▼
        SPEC.md  ROADMAP.md   Commits
                 STATE.md
                 phases/

File Responsibilities

File	Purpose	When Updated
SPEC.md	Requirements, tech stack, scope	Initial creation, scope changes
ROADMAP.md	Phase overview, dependencies, high-level tracking	Phase completion
STATE.md	Global state, session handoff, decisions, blockers	Each session
phases/NN-name/	Phase folder with SPEC.md, CHECKLIST.md, STATE.md	During phase execution

Best Practices

Writing Good Specifications

•Be specific about features, not implementation
•Include success criteria
•Define what's OUT of scope
•List assumptions explicitly

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

Session Handoff

•Update STATE.md at end of each session
•Note any decisions made and why
•Document blockers clearly
•Leave "next step" note for continuity

Troubleshooting

"I'm lost in my project"

•Run /mpx-show-project-status to see current state
•Read STATE.md for recent context
•Check last commits with git log --oneline -10

"The plan doesn't match reality"

•Update SPEC.md with actual requirements
•Run /mpx-parse-spec to regenerate checklists
•Review and adjust as needed

"Context is getting degraded"

•Use /mpx-execute-task for complex work
•This spawns fresh agent with clean context
•STATE.md maintains continuity

"I need to change scope"

•Update SPEC.md with new requirements
•Regenerate with /mpx-parse-spec
•Completed work is preserved in git

"I need to add new requirements"

•Run /mpx-add-requirements "description"
•Reviews current state and detects conflicts
•Updates SPEC.md and generates new tasks

Integration with Git

Commit Strategy

•Commit after each logical unit of work
•Use descriptive commit messages
•For phases: phase-N: description
•For tasks: [section] description

Branch Strategy (optional)

•Main branch for stable code
•Feature branches for risky changes
•Merge when phase completes

Quick Reference

code

/mpx-init-project       - Full setup (spec + git + checklist)
/mpx-create-spec        - Interactive spec creation
/mpx-init-repo          - Git initialization only
/mpx-parse-spec         - Generate checklists from spec
/mpx-execute-task            - Execute next task (simple or complex)
/mpx-show-project-status     - Show progress and next steps
/mpx-add-requirements   - Add new requirements to existing project