Your First Workflow

This guide walks the core Monday Morning loop end to end: shape a spec, break it into tasks, put an agent on it, complete the work, and track an issue along the way. The spec is the primary unit of work — everything else hangs off it.

Every entity here is a plain file you could write by hand, but the normal path is the /mm:* commands and the universal MCP verbs, which own the file mechanics so nothing drifts.

The Loop

Create a spec (define the work)
Add tasks (break it down)
Dispatch an agent (do the work)
Complete tasks (record progress)
Track issues (as they surface)
Verify (a spec is done when verification says so)

1. Create a Spec

In a Claude Code session, run /mm:spec and describe the work — the command shapes requirements and writes the spec folder. Or ask your agent directly (“create a spec for the welcome wizard”) and it calls the universal verb:

mm_create {
  "entity": "spec",
  "project_path": "/path/to/your/project",
  "name": "Welcome Wizard",
  "description": "3-step welcome wizard that runs on first launch"
}

That creates .mm/specs/2026-08-08-welcome-wizard/ with a spec.md containing the goal, a ## Requirements section with stable IDs (R1, R2, …), and an empty ## Tasks section:

---
status: planning
---

# Specification: Welcome Wizard

## Goal
Build a 3-step welcome wizard that runs on first launch.

## Requirements
- R1: Collect user name and role
- R2: Choose notification preferences

## Out of Scope
- Team onboarding (separate spec)

## Tasks

#### Completed

#### In Progress

#### Blocked

#### Backlog

2. Add Tasks

Tasks live in spec.md’s ## Tasks section — there is no separate task file for a spec. Batch them in one call:

mm_create {
  "entity": "task",
  "project_path": "/path/to/your/project",
  "spec_path": "2026-08-08-welcome-wizard",
  "titles": [
    "T1: Wizard layout and navigation component (R1)",
    "T2: Name and role form (R1)",
    "T3: Notification preferences step (R2)"
  ]
}

The tasks land under #### Backlog:

## Tasks

#### Completed

#### In Progress

#### Blocked

#### Backlog

- [ ] T1: Wizard layout and navigation component (R1)
- [ ] T2: Name and role form (R1)
- [ ] T3: Notification preferences step (R2)

The trailing (R1) ties each task to the requirement it satisfies — verification later checks that every requirement is covered.

3. Dispatch an Agent

In the desktop app, the spec now appears behind the Roadmap door, and its row carries a dispatch verb — Put an agent on it. Or state the ask yourself in the command bar and press DISPATCH:

Implement the welcome wizard spec — start with T1.

The agent appears as a card on the roster; select it to put the session on the stage and watch the work. From a terminal instead, /mm:spec-start begins implementing a spec in the current Claude Code session.

4. Complete Tasks

When a task is done, the agent (or you) marks it complete:

mm_complete {
  "entity": "task",
  "project_path": "/path/to/your/project",
  "spec_path": "2026-08-08-welcome-wizard",
  "task_title": "T1: Wizard layout and navigation component (R1)"
}

This checks the box, moves the task to #### Completed, and rolls progress up — task → spec → feature (if the spec is linked to one). Progress counts top-level tasks only; with T1 done, this spec reads 1 of 3 (33%).

5. Track an Issue

Hit a bug that isn’t this spec’s job to fix? Log it without breaking stride:

mm_create {
  "entity": "issue",
  "project_path": "/path/to/your/project",
  "title": "Wizard flashes unstyled content on first paint",
  "description": "On a cold start the wizard renders unstyled for ~200ms before tokens load.",
  "severity": "medium"
}

The issue gets its own file in .mm/issues/ and a row on the issues dashboard. Close it later with /mm:issue-close when it’s fixed.

6. See It in the App

Everything you just made is visible on the Floor:

Roadmap door — the door face shows open · total specs; open the drawer and the welcome-wizard row is there with its dispatch verbs (Run · View · Shape · Delete).
Entity detail — opening the spec puts a read view on the stage: requirements, tasks, prior work, and the verification verdict once one exists. Its one action is a header dispatch.
Artifact browser — one filterable index over every artifact (specs, issues, notes, docs) across your projects.

7. Verify and Done

All tasks checked does not make a spec done — it reads as in-review. Run /mm:verify-spec to check the implementation against the requirements; a passing verdict (or an explicit human override in the app) is what moves status: to done. Honest doneness is the point: the roadmap only calls something finished when verification agreed.

The Universal Verbs

Everything above used the same small set of verbs with an entity discriminator:

Verb	Used with	What it does
`mm_create`	`spec`, `task`, `issue`, `note`, `idea`, `doc`, …	Create any entity
`mm_list`	`spec`, `issue`, `note`, …	List entities of a kind
`mm_get`	`spec`, `status`, `blockers`, …	Read one entity or project status
`mm_update`	`task`, …	Change status or fields
`mm_complete`	`task`, `quick`	Complete with rollup
`mm_record`	—	Append a provenance-carrying line to a spec’s `## Recorded` block
`mm_search`	—	Hybrid search across everything in `.mm/`

Summary

Define — a spec states the goal and requirements, with stable R IDs.
Break down — tasks live in spec.md’s ## Tasks, each citing the requirement it serves.
Dispatch — put an agent on it from the roadmap or the command bar.
Complete — mm_complete rolls progress up; issues get logged, not lost.
Verify — /mm:verify-spec gates done, so the roadmap never lies.

All of it is plain files in your repo. Next session, any agent reads .mm/ and knows exactly where things stand.

Next Steps

MCP Tools Reference — every verb, the core catalog, and the opt-in groups.
The Floor — the desktop app that dispatches, watches, and records this loop.