Specs & Workflow

A spec is Monday Morning’s unit of work. It’s a folder inside .mm/specs/ that contains everything needed to plan, implement, and verify a feature or change. 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, requirements.md, and implementation.md.	/mm:spec
Implement	You (or an AI agent) work through the tasks in implementation.md, checking them off as they’re done.	/mm:spec-start
Verify	The system confirms all tasks are complete and the spec meets its requirements.	/mm:verify-spec

You don’t have to use all three commands every time. If you already know exactly what to build, you can scaffold the folder manually and jump straight to implementation.

The spec folder

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

.mm/specs/2025-12-03-auth-flow/
├── spec.md              # What you're building and why
├── requirements.md      # Detailed requirements and constraints
├── implementation.md    # Task list with checkboxes (this drives progress)
├── tasks.md             # Mirror of implementation.md (kept in sync)
└── prior-work.md        # Auto-generated matches to similar completed specs

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.

spec.md

This is the specification itself — the “what” and “why.” A typical spec.md includes:

# Specification: Auth Flow

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

## Requirements
- Sign-up with email verification
- Login with rate limiting
- Session tokens stored in HTTP-only cookies

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

The spec-writer agent reads this file to understand intent. Keep it focused — one spec should cover one coherent unit of work.

implementation.md

This file drives the progress tracking you see in the desktop app. It uses a specific format:

# Auth Flow - Implementation

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

## In Progress
- [ ] T2: Build login endpoint

## Backlog
- [ ] T3: Add rate limiting
- [ ] T4: Write integration tests

Format rules that matter:

• Section headers must use ## (two hashes) — ## Completed, ## In Progress, ## Backlog
• Tasks must use checkbox syntax: - [x] for done, - [ ] for pending
• Task IDs like T1:, T2: are conventional but not required

When you check off a task (or call mm_complete_task), Monday Morning updates implementation.md and recalculates progress for the spec and any linked feature.

What you see in the desktop app

The desktop app gives you two views of your specs:

Kanban board — All specs across your project, grouped by status (Backlog, In Progress, Complete). Each card shows the spec title, task count, and progress bar. Cards with prior-work matches display an “N prior work” badge.

Spec detail view — Click a spec card to see the full spec body, task list, and prior work panel. You can start implementation directly from this view, which opens a Claude Code session pre-loaded with the spec context.

Linking specs to features

Specs can be grouped under a feature for higher-level tracking. 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/2025-12-03-auth-flow",
    "../specs/2025-12-10-oauth-providers"
  ]
}

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

Wave sequencing

Once you have more than a handful of features, the order they get built in matters. Monday Morning models build order as waves — numbered groups of features, where every feature in a wave depends only on features in earlier waves.

Wave assignment lives on the feature itself:

{
  "id": "distribution",
  "name": "Distribution",
  "wave": 8,
  "wave_label": "Phase 2 — Distribution",
  "depends_on": ["packaging", "mvp-release"],
  "linked_specs": [...]
}

• wave (number) — the build sequence position. Lower numbers come first.
• wave_label (string) — a human label for the wave, shown in the kanban header. The header renders as Wave {wave} — {wave_label}.
• depends_on — IDs of features this one needs in place before it can start. Used to compute the wave number; circular or forward-pointing references will surface as ordering errors.

Features without a wave value fall into an Unsequenced bucket at the bottom of the backlog.

Parallel vs. sequential

Within a single wave, features have no dependencies on each other by construction, so they can be implemented concurrently. The kanban renders a Parallel badge on the wave header whenever a wave contains more than one feature — that’s the visual cue that you can safely use the column’s “Run in parallel” action to spawn worktree-isolated Claude sessions for each feature at once. Waves with a single feature get no badge (there’s nothing to parallelize).

Between waves the relationship is sequential: wave N+1 features should not start until wave N is complete, because they depend on something in it.

Where waves appear

Wave headers only appear in the backlog (Spec’d) column and only when the column is in manual sort mode. Switching to any other sort (by date, by priority, etc.) flattens the wave grouping because the sort breaks the dependency-aware ordering. The other columns (Building, In Review, Done) don’t show wave headers — once a feature is in flight, its wave is no longer a planning concern.

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	Verify a spec’s completion status
/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