Specs & Workflow

A spec is Monday Morning’s primary unit of work. It’s a folder inside .mm/specs/ that contains everything needed to plan, implement, and verify a coherent piece of work. Specs move through a lifecycle, and the system tracks progress automatically as you go.

The spec lifecycle

Every spec follows the same sequence:

Stage	What happens	Command
Plan	You describe what you want to build. Monday Morning scaffolds a spec folder with spec.md (including an empty ## Tasks section) and supporting files.	/mm:spec
Implement	You (or an agent) work through the tasks in spec.md’s ## Tasks section, checking them off as they’re done.	/mm:spec-start
Verify	A reflection-based verification pass checks the implementation against the spec’s requirements and records a verdict.	/mm:verify-spec

You don’t have to use all three commands every time, but verification matters more than it used to: a spec only reaches done status through a passing /mm:verify-spec verdict or an explicit human override. All tasks checked off with no passing verdict reads as in review, not done.

The spec folder

Each spec lives in .mm/specs/ under a date-prefixed folder name:

.mm/specs/2026-05-03-auth-flow/
├── spec.md              # The specification, including the ## Tasks section
├── requirements.md      # Optional — detailed requirements and constraints
├── tasks.md             # Optional — task breakdown notes
├── prior-work.md        # Auto-generated matches to similar completed specs
├── visuals/             # Screenshots and reference images
├── verification/        # /mm:verify-spec output (summary.json)
└── checkpoints/         # Session checkpoints

The folder name must follow the YYYY-MM-DD-slug pattern. Monday Morning uses this convention to sort, filter, and display specs in the desktop app.

Legacy specs created before tasks moved into spec.md track their tasks in a separate implementation.md. Tools fall back to it automatically — leave it in place for those specs, but never create it for a new one.

spec.md

This is the specification itself — the “what” and “why”, plus the task list that drives progress tracking. A typical spec.md:

---
status: planning
depends_on:
  - 2026-05-01-auth-schema
source: 'Roadmap Q2 item: account security'
---

# Specification: Auth Flow

## Goal
Add email/password authentication so users can log in and persist settings.

## Requirements
- R1: Sign-up with email verification
- R2: Login with rate limiting

## Out of Scope
- OAuth providers (planned for a future spec)

## Tasks

#### Completed
- [x] T1: Set up auth database schema (R1)

#### In Progress
- [ ] T2: Build login endpoint (R2)

#### Blocked

#### Backlog
- [ ] T3: Add rate limiting (R2)

Format rules that matter:

• Inside ## Tasks, sub-section headers use #### (four hashes): #### Completed, #### In Progress, #### Blocked, #### Backlog. Three hashes will not be recognized.
• Tasks use checkbox syntax: - [x] for done, - [ ] for pending.
• Each requirement carries a stable id (R1, R2, …), and tasks cite the id(s) they satisfy as a trailing (R1) or (R1, R3). /mm:verify-spec keys its scorecard to these ids and checks that every requirement is covered by a task. Ids are stable once assigned — never renumber; append the next free one.
• Prefer mm_create with entity: "task" over hand-editing — it batches a whole task list into the ## Tasks section in one write. Completing a task goes through mm_complete, which handles the file edit and progress rollup.

Specs also carry an append-only ## Recorded block — lines an agent writes during a session via the mm_record tool, with mandatory provenance. It’s the durable record of what an agent learned or decided while working the spec.

Dependencies and wave sequencing

Build order is a spec-level concern. Each spec’s depends_on frontmatter lists the spec slugs that must finish first — it’s the single source of truth for ordering.

Run /mm:order-specs (or the mm_order_specs MCP tool) to compute the order: it topologically sorts incomplete specs into numbered waves (wave 1 = no unmet prerequisites) and writes a project-wide .mm/specs/order.json:

{
  "phases": [
    {
      "phase": 1,
      "label": "Foundation",
      "parallel": true,
      "specs": [{ "spec": "2026-05-01-auth-schema", "reason": "No prerequisites" }]
    }
  ],
  "unordered": []
}

• parallel: true — the specs in that wave have no dependencies on each other and can be dispatched concurrently (derived from shared primary files).
• Between waves the relationship is sequential: a spec is blocked until every spec it depends on is done.

Features do not drive ordering. wave and wave_label fields on feature.json are optional display labels only.

What you see in the desktop app

Three stage occupants surface specs on the Floor:

Roadmap board — a list, not a kanban. Nothing is dragged. Phase bands group rows, and every row carries a dispatch verb — Run, View, Shape, or Delete — so the board’s job is to turn a plan into agents, not to be a status wall.

Entity detail — the read view for a spec: the spec body, task list, recorded lines, prior-work matches, and the verification verdict, with a dispatch action in the header. See Roster & Stage.

Artifact browser — one filterable index over every artifact in .mm/ (specs included), grouped by project. Opening a row lands on the entity detail view with the list as a left column.

The Roadmap door in the doors bar shows an “open · total” count for the project, and each row offers “Put an agent on it.”

Linking specs to features

Specs can optionally be grouped under a feature for at-a-glance progress. A feature is a JSON file at .mm/features/{slug}/feature.json that references one or more specs:

{
  "id": "auth",
  "name": "Authentication",
  "linked_specs": [
    "../specs/2026-05-03-auth-flow",
    "../specs/2026-05-10-oauth-providers"
  ]
}

Progress rolls up automatically — when all specs under a feature are complete, the feature is marked complete.

linked_specs is the single canonical record of which specs belong together. Before shaping new work, an agent can read the project’s feature.json files to judge whether related or overlapping work already exists — no other store exists for spec likeness, so what’s there is curated, human-confirmed grouping signal.

Done semantics

A spec is done if and only if its status: frontmatter is done, and that status is reachable only two ways:

1. A passing /mm:verify-spec verdict (verified or verified-with-caveats — caveats count), or
2. An explicit human override — the “Mark done anyway” confirm step in the desktop app.

Checking off every task without a passing verdict reads as in-review everywhere. This keeps “done” meaning verified done, not probably done.

Common commands

Command	What it does
/mm:spec	Scaffold a new spec interactively
/mm:spec-start	Begin implementation of an existing spec
/mm:verify-spec	Run reflection-based verification and record the verdict
/mm:order-specs	Compute the project-wide build order (waves) from spec dependencies
/mm:retrieve-prior-work	Regenerate prior-work matches for a spec

Related

• The .mm/ Data Model — full reference for the .mm/ directory structure
• Your First Workflow — end-to-end walkthrough of the spec lifecycle
• Spec Retrieval (Prior Work) — how completed specs inform future work